** z:\hst\slc\330\lnx\readme.txt *** L=010 --- 2017/10/25 15:19:46 (L05) -- ** SELCOPY for i386 Linux ** -- (RedHat, SuSE, etc. GNU/Linux 2.4 and above) * Contents * ** 1.0 Overview 2.0 SELCOPY for i386 Linux Install 2.1 Important - Apply SELCOPY Licence Key Information 2.2 SELCOPY directory contents 3.0 Running SELCOPY - Control Statement Input 3.1 Terminal input - prompted by SELCOPY 3.2 Parameters on the SELCOPY command 3.3 Control Statement input file 3.4 Control statement input file with user supplied arguments 4.0 IBM Mainframe SELCOPY compatibility 5.0 SELCOPY Samples 6.0 Contact CBL 7.0 Copyright Notice 8.0 README Change History 1.0 Overview *** In essence, SELCOPY for OS/400, Windows and the various flavours of UNIX systems, is the same program, written in C++ to emulate the IBM mainframe version of SELCOPY, simply recompiled on each platform. All documentation for SELCOPY applies equally to all platforms unless stated otherwise. SELCOPY is a batch utility that performs data manipulation as directed by user supplied SELCOPY input control statements. SELCOPY control statement syntax is documented in the accompanying SELCOPY User Manual. Like most standard Linux commands and programs, SELCOPY may be invoked from a user written program (e.g. C/C++) or batch command procedure (script.) Alternatively, it may be invoked directly from a terminal command prompt. Details of SELCOPY syntax and its use is documented in detail in SELCOPY_C++_3.40_Language_Reference.pdf, available via the CBL web pages or FTP server. Samples of SELCOPY invocation are detailed below in "3.0 Running SELCOPY - Control Statement Input". Although recorded on an IBM mainframe z/OS platform, new users should view the "SELCOPY/batch Recorded Demonstrations" found at the following web location: http://www.cbl.com/selcdem.html These provide good first step tutorials for developing SELCOPY tasks on any of the supported platforms, including Linux systems. 2.0 SELCOPY for i386 Linux Install *** 1. FTP the SELCOPY for i386 Linux gzipped tape archive (.tgz) install bundle to /tmp directory. 2. For convenience, set an environment variable for the SELCOPY install directory. # setenv s /opt/selcopy/s330_001 3. Create the install directory and make it the working directory. # mkdir -m 777 $s # cd $s 4. Decompress the tar/gzipped archive to the current working directory. # tar -xvzf /tmp/selcopy_i386_Linux_330_001.tgz 5. Create the local SELCOPY configuration file, "selcopy.nam", a release independent configuration file for SELCOPY at your installation. # cp -p selcnam.nmx selcopy.nam Edit and update "selcopy.nam" with the SELCOPY licence key provided by CBL. See "2.1 Important - Apply SELCOPY Licence Key Information" below. 6. Create 3 symbolic links in a directory mentioned in the path environment variable for SELCOPY users, e.g. /usr/bin Note: You will need root user authority to do this. # cd /usr/bin # ln -sf $s/s330_001 selcopy # ln -sf $s/selcopy.nam selcopy.nam # ln -sf $s/selcopy.msg selcopy.msg ######################################################################## 2.1 Important - Apply SELCOPY Licence Key Information *** ######################################################################## For successful execution of SELCOPY, a file of fileid "selcopy.nam" must exist in the same directory as the SELCOPY executable. On execution of SELCOPY, the selcopy.nam file is interrogated to establish licence key information. If the SELCOPY.nam file does not exist or licence key information is invalid, then SELCOPY will terminate with "ERROR 003 - SELCOPY.NAM FILE NOT FOUND" or "ERROR 124 - CHECK EXPIRY DATE". If selcopy.nam does not already exist in the SELCOPY directory, then please perform the following post installation steps. 1. Rename the skeleton file selcnam.nmx, found in the SELCOPY Installation directory, to selcopy.nam. 2. Use your preferred editor (e.g. Vi) to open selcopy.nam and to change the following options statement operands to specify the unique Licence Key information as supplied to you by CBL: opt site='Your Installation Name - Location' opt range='1990/01/01-2001/06/11' opt pass=x'0123,4567,89ab,cdef' Where: site - The licensed company name and location. range - The SELCOPY product operational date range. pass - The SELCOPY product licence key. (Hex string) Note that the licence key corresponds to an operational date range. Please contact CBL to request SELCOPY Licence Key information. Prior to the display of date range expiry warning messages, which occur on execution of SELCOPY for 4 weeks before the end of the operational data range, CBL will supply customers with updated pass/range details to replace existing values in selcopy.nam. 3. Save selcopy.nam and execute SELCOPY to test accurate application of the licence keys information. e.g. From a command shell, execute "selcopy -v". e.g. # selcopy -v If licence ley information has been successfully applied, SELCOPY will successfully display version information. e.g. SELCOPY/LNX 3.30 at Your Installation Name - Location 2015/04/22 16:18 Build Level=001 2015/02/19 14:40 (Latest change). -------- Your install is now finished -------- and you are ready to run. Thank you. 2.2 SELCOPY directory contents *** readme.txt (This file.) Information on install and execution of SELCOPY for i386 Linux. snnn_bbb The SELCOPY main executable. e.g. s330_001 Where nnn indicates the release number. e.g. 330 for Rel 3.30 and bbb indicates the build level. e.g. 008 selcopy.nmx Original skeleton for "selcopy.nam" file. Copy this to create the selcopy.nam file which you then tailor for your installation. selcopy.msg Text file of SELCOPY Error messages used at run time. It is release independent. samples/... Directory containing sample SELCOPY contol statement input files. Users, new and experienced, should view these samples to adopt good methods and techniques used in coding SELCOPY syntax. 3.0 Running SELCOPY - Control Statement Input *** Control statements may be supplied to SELCOPY via any of the following methods: 1. As input from a terminal. 2. As parameters to the SELCOPY executable. 3. A control statement input file. These methods are discussed below. 3.1 Terminal input - prompted by SELCOPY *** (SELCOPY/LNX Test Drive 1) Supply all control statements at the console when SELCOPY prompts for them. Just invoke SELCOPY with no arguments and no input redirection. % selcopy The SELCOPY program will respond with the following: SELCOPY/LNX n.nn at Your Installation Name - Locn yyyy/mm/dd hh:mm Enter Selcopy Ctl Cards... (Use /* to end.) You should then enter your SELCOPY control cards at the keyboard, using the enter key to terminate each line. Multiple SELCOPY statements may be entered using SELCOPY's default separator char, "!". Special chars such as "!", "$", "*", "'", """ and all the rest of the meta chars (including "\" the escape char) will not be interpreted by the shell because the data is read directly by SELCOPY. To read this file, "readme.txt", from the current dir, and display on the terminal all the commands used for this install, and at the same time write them to the file "z.z", your response lines would be: read readme.txt * You have to key this in and hit enter. if p 1 = # * and this. t log s=22 * and this. (Log each rec (stopaft=22) to screen.) t wr z.z * and this. (Write all recs to the file "z.z".) end * The "end" statement to terminate input. * Could use /* or ^D to do the same thing as "end". To read the executable binary file, "/usr/bin/ls", and display the 1st 5 recs in TYPE=B (both char and hex) on the terminal and 55 recs on SELCOPY's print file, treating the input data as fixed length 64 byte recs, your response lines would be: rd /usr/bin/ls l=64 pr ty=b s=55 * Print output goes to ./SELC.LST by default. log ty=b s=5 ! e * "e" is abbrev for "end". (Same as "/*" in pos 1.) 3.2 Parameters on the SELCOPY command *** (SELCOPY/LNX Test Drive 2) Supply all control statements on the command line when invoking SELCOPY. The first "!" in the arg string tells SELCOPY that control statements follow, where statements are separated by further "!" chars. The following command duplicates the example in 3.1 above, but without the comments: % selcopy ! read readme.txt! if p 1 = #! t log s=22! t wr z.z! end Because SELCOPY's linend is an exclamation mark, care must be taken to ensure that every "!" for SELCOPY is followed by a blank, otherwise it will get interpreted by the /bin/csh shell as a recall of a previous command. When a blank is not possible, the "!" must be preceded by a "\" character (the escape char) to get the shell to treat the "!" as data. A further shell problem is that any quotes intended for SELCOPY need to be enclosed in quotes of the other kind in order to protect SELCOPY's quotes from the shell. Single or double quotes may be used either way round. The inner quotes are then passed intact to SELCOPY by the shell. Similarly, meta chars, such as "*", must also be in quotes or escaped with the "\" escape char. % selcopy ! in ./selcopy.msg! if pos any = "'RECOG'"! t log s=4 \!"/*" To avoid having to remember to enclose "/*" in quotes, it is recommended that "end" be used to terminate the control statements instead. e.g. % selcopy ! in ./selcopy.msg! if pos any = '"RECOG"'! t log s=4! end 3.3 Control Statement input file *** (SELCOPY/LNX Test Drive 3) Supply all control statements from a file. Say we edited a new file, "/tmp/x", to contain the following: * Sample SELCOPY control statements. read ./selcopy.msg lrecl=40 * Fixed Length, 40. (RECFM=F) log type=m stopaft=4 * To check LF or CRLF. if p any = 'RECOG' then p @ = 'recog' * Selective changes. then print ty=m s=7 wr /tmp/selcopy.msg.copy eol=no We can then run SELCOPY, redirecting its control statement input from that file, using one of the following 2 commands: % selcopy -ctl /tmp/x % selcopy < /tmp/x Parameters "-ctl" and "-lst" identify SELCOPY control statement input and list output files respectively, without allocating stdin and stdout. Use of these parameters is preferred (as opposed to the stdin and stdout redirection symbols "<" and ">") as it allows a SELCOPY job to read piped input (read stdin) and write piped output (write stdout) as data. Alternatively, we could set up a script file called "test3", using the shell facility to redirect input from data within the shell, containing: # "test3" - Script file to execute SELCOPY control statements. # Remove the "\" from =\EOF= to get shell substitution # on control statements. # SELCOPY << =\EOF= * Sample SELCOPY control statements. read ./selcopy.msg lrecl=40 * Fixed Length, 40. (RECFM=F) log type=m stopaft=4 * To check LF or CRLF. if p any = 'RECOG' then p @ = 'recog' * Selective changes. then print ty=m s=7 wr /tmp/selcopy.msg.copy eol=no =\EOF= exit $status To run this script, we then simply issue the command "test3". % test3 SELCOPY's listing file will be SELC.LST on the current directory, unless the environment variable SLCLST was set, which takes precedence. Use of the command line option -lst=fileid would however take precedence over both SLCLST and SELC.LST defaults. The output file will of course be on the /tmp/selcopy.msg.copy file. No end-of-line characters have been written at the end of each 40-byte input record, but the output file will still be readable because the 40-byte records written would still have the EOL chars that were read off the input file as data. % more ./SELC.LST % more /tmp/selcopy.msg.copy 3.4 Control statement input file with user supplied arguments *** (SELCOPY/LNX Test Drive 4) Supply all control statements from an existing file, but also pass some arguments. Consider an existing file, "localEOL", which is an ascii text file on the "ctl" directory of your current directory, consisting of the following 3 lines only: * This is a comment line in the SELCOPY ctl statement file, "localEOL". read %1 * Read the 1st file, arg 1 off the command line. write %2 * Write the 2nd file, arg 2. Suppose you have a file, "dos.data" which is an ascii file, but has CRLF as linend, instead of LF, and you wish to create a copy in local UNIX format, then either of the following 2 commands will fix it: % selcopy -ctl=ctl/localEOL "'%HOME%/dos.data'" "'%HOME%/unix.format.data'" SELCOPY will equate %1 to '%HOME%/dos.data' and %2 to '%HOME%/unix.format.data' and then obey the control statements in localEOL which reads %1 and writes %2, defaulting to the EOL string for the local system. (LF for UNIX.) File names processed by SELCOPY for i386 Linux are treated as mixed case and kept intact. However, if a filename is passed as an EQU string, then it is not known at that time as an fname and consequently, if not in quotes, is uppercased. To overcome this, we must put each fname in quotes for SELCOPY. But the 1st set of quotes are stripped off by the shell, so the extra set of quotes are used to protect SELCOPY's quotes from the shell. The string %HOME% will be translated by SELCOPY to the value of the environment variable, HOME. We can't use $home or $HOME because the shell will not interpret it due to the use of single quotes. Alternatively, the escape char (\) could be used to protect the quotes from the shell, giving also the advantage of having the shell interpret the $home variable. % selcopy -ctl=ctl/localEOL \'%HOME%/dos.data\' \'$home/unix.format.data\' Any text input file read by SELCOPY, by default, may have any combination of the following linend delimiters: LF, CRLF, or CR, (for Unix, DOS or OS2), but text output files, by default, are written according to the preferred convention of the host operating system, which for UNIX systems is simply LF. The EOL parameter may, however, be used to override this. e.g. read %1 !write %2 eol=crlf or even: read %1 !write %2 eol=x'0d0a' or any other hex combination you choose (of any length). 4.0 IBM Mainframe SELCOPY compatibility *** Supply all control statements as used for the SELCOPY program written in the IBM Mainframe Assembler language. For users who are migrating data from an IBM mainframe platform to a Linux platform, simply select a mainframe SELCOPY job which processes files that have been copied to your Linux server, adjust input/output fileids as appropriate and use it as input to SELCOPY for i386 Linux. Processing should work as on the mainframe platform, including correct handling of Packed Decimal, Zoned, Floating Point and big endian Binary fields. (Arithmetic and data type conversion.) Please see the SELCOPY User Manual section "AS/400 , UNIX and PC Processing" for information on subtle differences that may be encountered. e.g. Searching for a blank as X'40' instead of X'20'. (It is better to search for ' '.) 5.0 SELCOPY Samples ** Sample SELCOPY control statement input files may be found in the "Samples" directory in the SELCOPY installation folder. It is recommended that new users use these jobs as a good basis for learning and writing new SELCOPY jobs. 6.0 Contact CBL ** Compute (Bridgend) Ltd 8 Merthyr Mawr Road Tel: +44 (1656) 652222 Bridgend Fax: +44 (1656) 652227 UK CF31 3NH Eml: support@cbl.com Web: http://www.cbl.com 7.0 Copyright Notice ** Copyright in the whole and every part of this document and of the SELCOPY system and programs is owned by Compute (Bridgend) Ltd, whose registered office is located at 8 Merthyr Mawr Road, Bridgend, Wales, UK, CF31 3NH, and who reserve the right to alter at their convenience the whole or any part of this document, or the SELCOPY system and programs. No reproduction of the whole or any part of the SELCOPY system and programs, or of this document, is to be made without prior written authority from Compute (Bridgend) Ltd. 8.0 README Change History *** L=010 2017/10/25 -nbj- Release 3.40 Build 001. L=009 2015/04/22 -nbj- Release 3.30 Build 001. L=008 2013/10/22 -nbj- Release 3.20 Build 001. L=007 2013/06/21 -nbj- Release 3.10 Build 008 and remove .pdf documentation. L=006 2013/05/10 -nbj- Release 3.10 Build 007. L=005 2012/12/18 -nbj- Release 3.10 Build 005. L=004 2011/06/23 -nbj- Revamp - especially install procedure which now uses tar. L=003 2007/08/15 -djh- Adjust spacing. L=002 2007/08/13 -djh- Remove slccall.so and mention libselc.so for CALL stmt. L=001 2003/11/11 -djh- Started. --- End ---