home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rexxuuxx.zip / UUXXCODE.INF (.txt) < prev    next >
OS/2 Help File  |  1997-05-13  |  13KB  |  369 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Copyrights and Notices ΓòÉΓòÉΓòÉ
  3.  
  4. The following copyright information applies to the various components of this 
  5. software. 
  6.  
  7.  
  8. ΓòÉΓòÉΓòÉ 1.1. The PL/I Run-Time Library ΓòÉΓòÉΓòÉ
  9.  
  10.  
  11. IBM Supplied Software 
  12.  
  13. I am contractually obliged by IBM to include the following, since you need a 
  14. copy of the PL/I run-time library in order to run this code. 
  15.  
  16. CONTAINS 
  17. IBM PL/I for OS/2 Professional Edition Version 1.2 
  18. Runtime Modules 
  19. (c) Copyright IBM Corporation 1994, 1996 
  20. All rights reserved 
  21.  
  22.  
  23. ΓòÉΓòÉΓòÉ 1.2. The OS/2 Commands and REXX Extension DLL ΓòÉΓòÉΓòÉ
  24.  
  25.  
  26. COPYRIGHT AND LICENSING INFORMATION 
  27.  
  28. This suite of programs and subroutines is freeware, distributed as is, without 
  29. any warranty of its usefulness for any purpose. You may use it freely. You may 
  30. also redistribute it, provided no charge is levied beyond the price of its 
  31. distribution medium. 
  32.  
  33. However, the author retains all intellectual property rights. 
  34. Copyright (C) David W. Noon, 1995, 1997 
  35.  
  36. OBTAINING TECHNICAL SUPPORT 
  37.  
  38. You can obtain technical support via Internet e-mail, Compuserve or FidoNet 
  39. Netmail. My addresses are as follows. 
  40.  
  41.  Internet:      david_noon@donor2.demon.co.uk 
  42.                 dwnoon@ibm.net 
  43.                 dnoon@acm.org 
  44.  Compuserve:    72172,431 
  45.  FidoNet:       David Noon 2:440/4 
  46.  
  47.  The FidoNet mailbox and the first listed Internet mailbox, which are the same 
  48.  place, I check almost every day. The others are checked less frequently, such 
  49.  as every third day or so. 
  50.  
  51.  Turn-around time on problems might not be spectacular, especially if I have 
  52.  other issues to handle. This is freeware and you should expect no more than 
  53.  you pay for. 
  54.  
  55.  
  56. ΓòÉΓòÉΓòÉ 2. The Encoding and Decoding Specifications ΓòÉΓòÉΓòÉ
  57.  
  58. The following are "table napkin specs." for the various encoding schemes 
  59. supported by this software. 
  60.  
  61.  
  62. ΓòÉΓòÉΓòÉ 2.1. The UU and XX Encoding and Decoding Specifications ΓòÉΓòÉΓòÉ
  63.  
  64. Condensed from a doc file for a UUENCODE/DECODE program by: 
  65.                     Richard Marks 
  66.                     931 Sulgrave Lane 
  67.                     Bryn Mawr, PA 19010 
  68.  
  69.  UU-encoding is a way to code a file which may contain any characters into a 
  70.  standard character set that can be reliably sent over diverse networks. 
  71.  
  72.  THE CHARACTER ENCODING: 
  73.  
  74.  The basic scheme is to break groups of 3 eight bit characters (24 bits) into 4 
  75.  six bit characters and then add 32 (a space) to each six bit character which 
  76.  maps it into the readily transmittable character. Another way of phrasing this 
  77.  is to say that the encoded 6 bit characters are mapped into the set: 
  78.      `!"#$%&'()*+,-./012356789:;<=>?@ABC...XYZ[\]^_ 
  79.  for transmission over communications lines. 
  80.  
  81.  As some transmission mechanisms compress or remove spaces, spaces are changed 
  82.  into back-quote characters (a 96). (A better scheme might be to use a bias of 
  83.  33 so the space is not created, but this is not done.) 
  84.  
  85.  Another newer less popular encoding method, called XX-encoding uses the set: 
  86.      +-01...89ABC...XYZabc...xyz 
  87.  
  88.  In my opinion, XX-encoding is superior to UU-encoding because it uses more 
  89.  "normal" characters that are less likely to get corrupted. In fact several of 
  90.  the special characters in the UU set do not get thru an EBCDIC to ASCII 
  91.  translation correctly. Conversely, an advantage of the UU set is that it does 
  92.  not use lower case characters. Now-a-days both upper and lower case are sent 
  93.  with no problems; maybe in the communications dark ages, there was a problem 
  94.  with lower case. 
  95.  
  96.  COMPOSING A LINE OF ENCODED CHARACTERS: 
  97.  
  98.  A small number of eight bit characters are encoded into a single line and a 
  99.  count is put at the start of the line. (Most lines in an encoded file have 45 
  100.  encoded characters. When you look at a UU-encoded file note that most lines 
  101.  start with the letter "M".  "M" is decimal 77 which, minus the 32 bias, is 
  102.  45.) 
  103.  
  104.  This encode program puts a check character at the end of each line. The check 
  105.  is the sum of all the encoded characters, before adding the mapping, modulo 
  106.  64. 
  107.  
  108.  Note:  Horton 9/1/87 UUENCODE has a bug in the line check algorithm; it uses 
  109.  the sum of the original, not the encoded characters. 
  110.  
  111.  PACKAGING THE LINES INTO FILES: 
  112.  
  113.  The lines of encoded data can be preceded by comments and by network 
  114.  addressing information.  The encoded data is directly preceded by a line 
  115.  containing: begin <file-mode> <file-name> 
  116.  
  117.  The final end of encoded data is an encoded line with zero encoded characters 
  118.  (a back-quote), followed by a line containing "end". 
  119.  
  120.  SPLITING UP LONG FILES: 
  121.  
  122.  Long files are broken into several sections before transmission. This is done 
  123.  because very large files are cumbersome to handle and because some networks 
  124.  require files to be less than 64K bytes. 
  125.  
  126.  TABLE LINES: 
  127.  
  128.  Some encoded files put the mapping used at the front of the encoded file, just 
  129.  in front of the "begin" line. The format for this is: 
  130.  
  131.   table
  132.   first 32 characters
  133.   second 32 characters
  134.  
  135.  All this starts in column 1. 
  136.  
  137.  
  138. ΓòÉΓòÉΓòÉ 2.2. The Base64 Encoding and Decoding Specifications ΓòÉΓòÉΓòÉ
  139.  
  140. Darned if I know where I put these, but they're real simple. Read the code. 
  141.  
  142.  
  143. ΓòÉΓòÉΓòÉ 3. The Commands ΓòÉΓòÉΓòÉ
  144.  
  145. The command syntax descriptions follow. 
  146.  
  147.  
  148. ΓòÉΓòÉΓòÉ 3.1. The UUENCODE Command ΓòÉΓòÉΓòÉ
  149.  
  150.  
  151. Syntax 
  152.  
  153. The command is issued from an OS/2 command prompt as follows: 
  154.  
  155.           UUENCODE <Output file> <Input file> [<Input file> ...] 
  156.  
  157.  The output file name is mandatory, as is at least one input file name. The 
  158.  input file(s) will be read as a binary byte stream. The output file will 
  159.  contain all the specified input files, each with its own 'begin' record so 
  160.  that they will be separated when decoded. 
  161.  
  162.  
  163. ΓòÉΓòÉΓòÉ 3.2. The UUDECODE Command ΓòÉΓòÉΓòÉ
  164.  
  165.  
  166. Syntax 
  167.  
  168. The command is issued from an OS/2 command prompt as follows: 
  169.  
  170.           UUDECODE [HORTON] <Input file> [+<Input file> ...] 
  171.  
  172.  At 1 least input file name is mandatory. Additional input files can be 
  173.  concatenated with a plus sign (+) with no embedded spaces. All encoded files 
  174.  in the input concatenation will be decoded. The purpose of this is to allow 
  175.  for the download of multiple messages for a large file and have the decoder 
  176.  join them back together again. 
  177.  
  178.  The HORTON flag indicates that the decoder should allow for Horton's erroneous 
  179.  checksum algorithm. This option must be first and is case sensitive. If you 
  180.  get a lot of checksum warnings decoding a file (like on every line) this 
  181.  option might cure the problem. 
  182.  
  183.  
  184. ΓòÉΓòÉΓòÉ 3.3. The XXENCODE Command ΓòÉΓòÉΓòÉ
  185.  
  186.  
  187. Syntax 
  188.  
  189. The command is issued from an OS/2 command prompt as follows: 
  190.  
  191.           XXENCODE <Output file> <Input file> [<Input file> ...] 
  192.  
  193.  The output file name is mandatory, as is at least one input file name. The 
  194.  input file(s) will be read as a binary byte stream. The output file will 
  195.  contain all the specified input files, each with its own 'begin' record so 
  196.  that they will be separated when decoded. 
  197.  
  198.  
  199. ΓòÉΓòÉΓòÉ 3.4. The XXDECODE Command ΓòÉΓòÉΓòÉ
  200.  
  201.  
  202. Syntax 
  203.  
  204. The command is issued from an OS/2 command prompt as follows: 
  205.  
  206.           XXDECODE [HORTON] <Input file> [+<Input file> ...] 
  207.  
  208.  At 1 least input file name is mandatory. Additional input files can be 
  209.  concatenated with a plus sign (+) with no embedded spaces. All encoded files 
  210.  in the input concatenation will be decoded. The purpose of this is to allow 
  211.  for the download of multiple messages for a large file and have the decoder 
  212.  join them back together again. 
  213.  
  214.  The HORTON flag indicates that the decoder should allow for Horton's erroneous 
  215.  checksum algorithm. This option must be first and is case sensitive. If you 
  216.  get a lot of checksum warnings decoding a file (like on every line) this 
  217.  option might cure the problem. However, this bug is more likely to manifest 
  218.  itself in a UU-encoded file than an XX-encoded file. 
  219.  
  220.  
  221. ΓòÉΓòÉΓòÉ 4. The REXX Functions ΓòÉΓòÉΓòÉ
  222.  
  223. The REXX extension functions are all in a library called REXXUUXX.DLL. 
  224.  
  225. Note:  REXXUUXX is meant to rhyme with "Gadzooks", not "Shucks". 
  226.  
  227. Each function must be loaded as needed by the RxFuncAdd() built-in function of 
  228. REXX. For example: 
  229.  
  230. CALL RxFuncAdd 'UUDecodeFiles','REXXUUXX','UUDecodeFiles'
  231.  
  232. The DLL has been linked as case insensitive, so the third parameter can be any 
  233. mixture of lower case and capital letters. 
  234.  
  235.  
  236. ΓòÉΓòÉΓòÉ 4.1. UUEncodeFiles ΓòÉΓòÉΓòÉ
  237.  
  238.  
  239. DESCRIPTION 
  240.  
  241. The UUEncodeFiles subroutine takes a list of input files and creates an output 
  242. file that is the UU-encoded form of those files. You must specify the name of 
  243. the output file, and it must be the first parameter supplied. Each input file 
  244. has its own 'begin' statement so that the individual files will be separated 
  245. again when decoded. 
  246.  
  247. Syntax 
  248.  
  249. The calling sytax is as follows: 
  250.  
  251.                CALL UUEncodeFiles 'OUTFILE.UUE','INFILE1.DAT'[,'INFILE2.DAT'] 
  252.                ... 
  253.  
  254.  
  255. ΓòÉΓòÉΓòÉ 4.2. UUDecodeFiles ΓòÉΓòÉΓòÉ
  256.  
  257.  
  258. DESCRIPTION 
  259.  
  260. The UUDecodeFiles subroutine takes a list of input files and creates an output 
  261. file that is the UU-decoded form of those files. The output file(s) are 
  262. determined by the 'begin' record that are encountered in the encoded input. 
  263.  
  264. Syntax 
  265.  
  266. The calling sytax is as follows: 
  267.  
  268.                CALL UUDecodeFiles 'INFILE1.UUE'[,'INFILE2.UUE'] ... 
  269.  
  270.  The multiple input files facility is very useful if you have downloaded a file 
  271.  that spans multiple messages. They are simply concatenated back together by 
  272.  the subroutine, but you do need to code them in the correct order. 
  273.  
  274.  If you find that an encoded file does not decode properly, it is possible it 
  275.  was encoded using the invalid checksum algorithm, attributable to Horton. To 
  276.  overcome this, the first parameter can be the string 'HORTON', in all capital 
  277.  letters. On seeing this, the decoder routine will use Horton's checksum 
  278.  algorithm instead. Use sparingly. 
  279.  
  280.                CALL UUDecodeFiles 'HORTON','INFILE1.UUE'[,'INFILE2.UUE'] ... 
  281.  
  282.  
  283. ΓòÉΓòÉΓòÉ 4.3. XXEncodeFiles ΓòÉΓòÉΓòÉ
  284.  
  285.  
  286. DESCRIPTION 
  287.  
  288. The XXEncodeFiles subroutine takes a list of input files and creates an output 
  289. file that is the XX-encoded form of those files. You must specify the name of 
  290. the output file, and it must be the first parameter supplied. Each input file 
  291. has its own 'begin' statement so that the individual files will be separated 
  292. again when decoded. 
  293.  
  294. Syntax 
  295.  
  296. The calling sytax is as follows: 
  297.  
  298.                CALL XXEncodeFiles 'OUTFILE.XXE','INFILE1.DAT'[,'INFILE2.DAT'] 
  299.                ... 
  300.  
  301.  
  302. ΓòÉΓòÉΓòÉ 4.4. XXDecodeFiles ΓòÉΓòÉΓòÉ
  303.  
  304.  
  305. DESCRIPTION 
  306.  
  307. The XXDecodeFiles subroutine takes a list of input files and creates an output 
  308. file that is the XX-decoded form of those files. The output file(s) are 
  309. determined by the 'begin' record that are encountered in the encoded input. 
  310.  
  311. Syntax 
  312.  
  313. The calling sytax is as follows: 
  314.  
  315.                CALL XXDecodeFiles 'INFILE1.XXE'[,'INFILE2.XXE'] ... 
  316.  
  317.  The multiple input files facility is very useful if you have downloaded a file 
  318.  that spans multiple messages. They are simply concatenated back together by 
  319.  the subroutine, but you do need to code them in the correct order. 
  320.  
  321.  If you find that an encoded file does not decode properly, it is possible it 
  322.  was encoded using the invalid checksum algorithm, attributable to Horton. To 
  323.  overcome this, the first parameter can be the string 'HORTON', in all capital 
  324.  letters. On seeing this, the decoder routine will use Horton's checksum 
  325.  algorithm instead. Use sparingly. 
  326.  
  327.                CALL XXDecodeFiles 'HORTON','INFILE1.XXE'[,'INFILE2.XXE'] ... 
  328.  
  329.  This problem is very rare in XX-encoded files. It is more typical of 
  330.  UU-encoded files. 
  331.  
  332.  
  333. ΓòÉΓòÉΓòÉ 4.5. Base64EncodeFiles ΓòÉΓòÉΓòÉ
  334.  
  335.  
  336. DESCRIPTION 
  337.  
  338. The Base64EncodeFiles subroutine takes an input file and creates an output file 
  339. that is the Base64-encoded form of those files. You must specify the name of 
  340. the output file, and it must be the first parameter supplied. There only only 2 
  341. parameters for this subroutine. 
  342.  
  343. Syntax 
  344.  
  345. The calling sytax is as follows: 
  346.  
  347.                CALL Base64EncodeFiles 'OUTFILE.B64','INFILE.DAT' 
  348.  
  349.  
  350. ΓòÉΓòÉΓòÉ 4.6. Base64DecodeFiles ΓòÉΓòÉΓòÉ
  351.  
  352.  
  353. DESCRIPTION 
  354.  
  355. The Base64DecodeFiles subroutine takes a list of input files and creates an 
  356. output file that is the Base64-decoded form of those files. You must specify 
  357. the name of the output file, since the Base64 encoding does not include the 
  358. filename, and it must be the first parameter supplied. 
  359.  
  360. Syntax 
  361.  
  362. The calling sytax is as follows: 
  363.  
  364.                CALL Base64DecodeFiles 
  365.                'OUTFILE.DAT','INFILE1.B64'[,'INFILE2.B64'] ... 
  366.  
  367.  The multiple input files facility is very useful if you have downloaded a file 
  368.  that spans multiple messages. They are simply concatenated back together by 
  369.  the subroutine, but you do need to code them in the correct order.