═══ 1. Copyrights and Notices ═══ The following copyright information applies to the various components of this software. ═══ 1.1. The PL/I Run-Time Library ═══ IBM Supplied Software I am contractually obliged by IBM to include the following, since you need a copy of the PL/I run-time library in order to run this code. CONTAINS IBM PL/I for OS/2 Professional Edition Version 1.2 Runtime Modules (c) Copyright IBM Corporation 1994, 1996 All rights reserved ═══ 1.2. The OS/2 Commands and REXX Extension DLL ═══ COPYRIGHT AND LICENSING INFORMATION This suite of programs and subroutines is freeware, distributed as is, without any warranty of its usefulness for any purpose. You may use it freely. You may also redistribute it, provided no charge is levied beyond the price of its distribution medium. However, the author retains all intellectual property rights. Copyright (C) David W. Noon, 1995, 1997 OBTAINING TECHNICAL SUPPORT You can obtain technical support via Internet e-mail, Compuserve or FidoNet Netmail. My addresses are as follows. Internet: david_noon@donor2.demon.co.uk dwnoon@ibm.net dnoon@acm.org Compuserve: 72172,431 FidoNet: David Noon 2:440/4 The FidoNet mailbox and the first listed Internet mailbox, which are the same place, I check almost every day. The others are checked less frequently, such as every third day or so. Turn-around time on problems might not be spectacular, especially if I have other issues to handle. This is freeware and you should expect no more than you pay for. ═══ 2. The Encoding and Decoding Specifications ═══ The following are "table napkin specs." for the various encoding schemes supported by this software. ═══ 2.1. The UU and XX Encoding and Decoding Specifications ═══ Condensed from a doc file for a UUENCODE/DECODE program by: Richard Marks 931 Sulgrave Lane Bryn Mawr, PA 19010 UU-encoding is a way to code a file which may contain any characters into a standard character set that can be reliably sent over diverse networks. THE CHARACTER ENCODING: The basic scheme is to break groups of 3 eight bit characters (24 bits) into 4 six bit characters and then add 32 (a space) to each six bit character which maps it into the readily transmittable character. Another way of phrasing this is to say that the encoded 6 bit characters are mapped into the set: `!"#$%&'()*+,-./012356789:;<=>?@ABC...XYZ[\]^_ for transmission over communications lines. As some transmission mechanisms compress or remove spaces, spaces are changed into back-quote characters (a 96). (A better scheme might be to use a bias of 33 so the space is not created, but this is not done.) Another newer less popular encoding method, called XX-encoding uses the set: +-01...89ABC...XYZabc...xyz In my opinion, XX-encoding is superior to UU-encoding because it uses more "normal" characters that are less likely to get corrupted. In fact several of the special characters in the UU set do not get thru an EBCDIC to ASCII translation correctly. Conversely, an advantage of the UU set is that it does not use lower case characters. Now-a-days both upper and lower case are sent with no problems; maybe in the communications dark ages, there was a problem with lower case. COMPOSING A LINE OF ENCODED CHARACTERS: A small number of eight bit characters are encoded into a single line and a count is put at the start of the line. (Most lines in an encoded file have 45 encoded characters. When you look at a UU-encoded file note that most lines start with the letter "M". "M" is decimal 77 which, minus the 32 bias, is 45.) This encode program puts a check character at the end of each line. The check is the sum of all the encoded characters, before adding the mapping, modulo 64. Note: Horton 9/1/87 UUENCODE has a bug in the line check algorithm; it uses the sum of the original, not the encoded characters. PACKAGING THE LINES INTO FILES: The lines of encoded data can be preceded by comments and by network addressing information. The encoded data is directly preceded by a line containing: begin The final end of encoded data is an encoded line with zero encoded characters (a back-quote), followed by a line containing "end". SPLITING UP LONG FILES: Long files are broken into several sections before transmission. This is done because very large files are cumbersome to handle and because some networks require files to be less than 64K bytes. TABLE LINES: Some encoded files put the mapping used at the front of the encoded file, just in front of the "begin" line. The format for this is: table first 32 characters second 32 characters All this starts in column 1. ═══ 2.2. The Base64 Encoding and Decoding Specifications ═══ Darned if I know where I put these, but they're real simple. Read the code. ═══ 3. The Commands ═══ The command syntax descriptions follow. ═══ 3.1. The UUENCODE Command ═══ Syntax The command is issued from an OS/2 command prompt as follows: UUENCODE [ ...] The output file name is mandatory, as is at least one input file name. The input file(s) will be read as a binary byte stream. The output file will contain all the specified input files, each with its own 'begin' record so that they will be separated when decoded. ═══ 3.2. The UUDECODE Command ═══ Syntax The command is issued from an OS/2 command prompt as follows: UUDECODE [HORTON] [+ ...] At 1 least input file name is mandatory. Additional input files can be concatenated with a plus sign (+) with no embedded spaces. All encoded files in the input concatenation will be decoded. The purpose of this is to allow for the download of multiple messages for a large file and have the decoder join them back together again. The HORTON flag indicates that the decoder should allow for Horton's erroneous checksum algorithm. This option must be first and is case sensitive. If you get a lot of checksum warnings decoding a file (like on every line) this option might cure the problem. ═══ 3.3. The XXENCODE Command ═══ Syntax The command is issued from an OS/2 command prompt as follows: XXENCODE [ ...] The output file name is mandatory, as is at least one input file name. The input file(s) will be read as a binary byte stream. The output file will contain all the specified input files, each with its own 'begin' record so that they will be separated when decoded. ═══ 3.4. The XXDECODE Command ═══ Syntax The command is issued from an OS/2 command prompt as follows: XXDECODE [HORTON] [+ ...] At 1 least input file name is mandatory. Additional input files can be concatenated with a plus sign (+) with no embedded spaces. All encoded files in the input concatenation will be decoded. The purpose of this is to allow for the download of multiple messages for a large file and have the decoder join them back together again. The HORTON flag indicates that the decoder should allow for Horton's erroneous checksum algorithm. This option must be first and is case sensitive. If you get a lot of checksum warnings decoding a file (like on every line) this option might cure the problem. However, this bug is more likely to manifest itself in a UU-encoded file than an XX-encoded file. ═══ 4. The REXX Functions ═══ The REXX extension functions are all in a library called REXXUUXX.DLL. Note: REXXUUXX is meant to rhyme with "Gadzooks", not "Shucks". Each function must be loaded as needed by the RxFuncAdd() built-in function of REXX. For example: CALL RxFuncAdd 'UUDecodeFiles','REXXUUXX','UUDecodeFiles' The DLL has been linked as case insensitive, so the third parameter can be any mixture of lower case and capital letters. ═══ 4.1. UUEncodeFiles ═══ DESCRIPTION The UUEncodeFiles subroutine takes a list of input files and creates an output file that is the UU-encoded form of those files. You must specify the name of the output file, and it must be the first parameter supplied. Each input file has its own 'begin' statement so that the individual files will be separated again when decoded. Syntax The calling sytax is as follows: CALL UUEncodeFiles 'OUTFILE.UUE','INFILE1.DAT'[,'INFILE2.DAT'] ... ═══ 4.2. UUDecodeFiles ═══ DESCRIPTION The UUDecodeFiles subroutine takes a list of input files and creates an output file that is the UU-decoded form of those files. The output file(s) are determined by the 'begin' record that are encountered in the encoded input. Syntax The calling sytax is as follows: CALL UUDecodeFiles 'INFILE1.UUE'[,'INFILE2.UUE'] ... The multiple input files facility is very useful if you have downloaded a file that spans multiple messages. They are simply concatenated back together by the subroutine, but you do need to code them in the correct order. If you find that an encoded file does not decode properly, it is possible it was encoded using the invalid checksum algorithm, attributable to Horton. To overcome this, the first parameter can be the string 'HORTON', in all capital letters. On seeing this, the decoder routine will use Horton's checksum algorithm instead. Use sparingly. CALL UUDecodeFiles 'HORTON','INFILE1.UUE'[,'INFILE2.UUE'] ... ═══ 4.3. XXEncodeFiles ═══ DESCRIPTION The XXEncodeFiles subroutine takes a list of input files and creates an output file that is the XX-encoded form of those files. You must specify the name of the output file, and it must be the first parameter supplied. Each input file has its own 'begin' statement so that the individual files will be separated again when decoded. Syntax The calling sytax is as follows: CALL XXEncodeFiles 'OUTFILE.XXE','INFILE1.DAT'[,'INFILE2.DAT'] ... ═══ 4.4. XXDecodeFiles ═══ DESCRIPTION The XXDecodeFiles subroutine takes a list of input files and creates an output file that is the XX-decoded form of those files. The output file(s) are determined by the 'begin' record that are encountered in the encoded input. Syntax The calling sytax is as follows: CALL XXDecodeFiles 'INFILE1.XXE'[,'INFILE2.XXE'] ... The multiple input files facility is very useful if you have downloaded a file that spans multiple messages. They are simply concatenated back together by the subroutine, but you do need to code them in the correct order. If you find that an encoded file does not decode properly, it is possible it was encoded using the invalid checksum algorithm, attributable to Horton. To overcome this, the first parameter can be the string 'HORTON', in all capital letters. On seeing this, the decoder routine will use Horton's checksum algorithm instead. Use sparingly. CALL XXDecodeFiles 'HORTON','INFILE1.XXE'[,'INFILE2.XXE'] ... This problem is very rare in XX-encoded files. It is more typical of UU-encoded files. ═══ 4.5. Base64EncodeFiles ═══ DESCRIPTION The Base64EncodeFiles subroutine takes an input file and creates an output file that is the Base64-encoded form of those files. You must specify the name of the output file, and it must be the first parameter supplied. There only only 2 parameters for this subroutine. Syntax The calling sytax is as follows: CALL Base64EncodeFiles 'OUTFILE.B64','INFILE.DAT' ═══ 4.6. Base64DecodeFiles ═══ DESCRIPTION The Base64DecodeFiles subroutine takes a list of input files and creates an output file that is the Base64-decoded form of those files. You must specify the name of the output file, since the Base64 encoding does not include the filename, and it must be the first parameter supplied. Syntax The calling sytax is as follows: CALL Base64DecodeFiles 'OUTFILE.DAT','INFILE1.B64'[,'INFILE2.B64'] ... The multiple input files facility is very useful if you have downloaded a file that spans multiple messages. They are simply concatenated back together by the subroutine, but you do need to code them in the correct order.