Documentation for the Base64 Utilities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Contents: ~~~~~~~~~ 1. General information regarding the programs 2. About ENCODE64.EXE + Examples + Forming header string(s) 3. About DECODE64.EXE + Examples / Multi-part decoding help 4. About UNIX2DOS.COM 5. Technical information regarding BASE-64 encoding 6. Disclaimer, Distribution, About the Author, etc. 7. Registration Information 8. Revision Notes The only requirement for any of these programs is DOS for ENCODE64 and DECODE64, and Windows 3.1 or above for SHELL2 (it will also work on Windows '95). For information on SHELL2.EXE, refer to SHELL2.TXT. Find other good programs like this one at my home page: http://www.geocities.com/SiliconValley/Park/3056/ Support Shareware: Register! 1. General: ~~~~~~~~~~~ These DOS programs have built-in error checking to make sure the files are processed correctly. However, if there are unexplained errors while processing, the program will give a "Runtime Error" message. Check in this documentation for information regarding possible errors. Most errors will likely be caused by the DECODE64 program, because of text-processing problems. If all else fails, refer to the section on DECODE64 and see how the program works! If you think a certain problem may be a bug in the program, please e-mail me. My e-mail address is at the bottom of this file. NOTE: DECODE64 will ONLY decode files with a CR/LF at the end of every line, so it will not decode UNIX text files. A (freeware) utility I wrote was included with these programs, called UNIX2DOS. See the section on UNIX2DOS.EXE for information on how to use it. REGARDING E-MAIL: Internet mail programs will almost definitely not recognize encoded files over e-mail when encoded using ENCODE64. This is because information is added to the header and body of sent e-mails when files are included with them. It is impossible to mimic this with these programs. Whoever receives a Base64 encoded file encoded using ENCODE64 may need a utility similar to DECODE64 to be able to decode it. (This is especially true when using multiple-part encoding & decoding.) 2. About ENCODE64.EXE: ~~~~~~~~~~~~~~~~~~~~~~ This program takes any file (binary or otherwise) and converts it into a format transmittable over the Internet. (See technical information below.) The command line for this program is: ENCODE64 [output filename] [/M] [/O] [/P] [/B] [/H
] Items in <> are necessary, in [] are optional. Where is any file. [Output filename] is optional, but if you do give it, ENCODE64 will attempt to use that file name instead of the generic ".64" filename. /B --> Make your own "boundary" string inside of the encoded files. This is more advanced and will probably not need to be used unless you're using ENCODE64.EXE with an e-mail program. /H
--> Lets you form your own header. This is an advanced option; see the end of this section for more information. /O --> When you use this option, the program will AUTOMATICALLY attempt to overwrite any files it needs to, without having a (Y/N) prompt. Use this carefully. /M --> Tell ENCODE64 to do a multiple-file output. A number should immediately follow, telling ENCODE64 how many kilobytes (KB) of data should be put into each file. 1 kilobyte is slightly less than 20 lines of data. The program will tell you if the number of kilobytes you specified is too out of range for the particular file you are encoding. The maximum number of files ENCODE64 will output to is 99 (for filename reasons). Use the Base64 Windows Shell program for easier multi-part encoding. /P --> Turn on a percentage meter which tells how far through ENCODE64 is. For single files, it will show how far it is so far. For multiple files, it will show how far through it is for the particular file it is working on. (The last file it creates may not reach 100%) * Examples: * ~~~~~~~~~~~~~ C:\>ENCODE64 PROGRAM.ZIP After executing this, ENCODE64 will create a file called "PROGRAM.64" in the current directory. If a file with that name was already found, it will say so and will not overwrite it (it must be moved or deleted before ENCODE64 will create the file, just to make sure that no data is lost). C:\>ENCODE64 PROGRAM.ZIP PROG.TXT ENCODE64 will attempt to make a file called PROG.TXT instead of the generic PROGRAM.64. It will ask you if you wish to overwrite it if it already exists. C:\>ENCODE64 PROGRAM.ZIP PROG.TXT /M20 /O /P ENCODE64 will attempt to make multiple files until the end of PROGRAM.ZIP is reached. It will start with PROG01.TXT, put 20 kilobytes of encoded data in it (approx. 400 lines of data), then move on to PROG02.TXT. If it encountered PROG01.TXT already, it will automatically overwrite it because the "/O" option was put on the command line. It will also have a percentage meter which will show how far it is through each one of the files it creates. * Forming your own header strings * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are using ENCODE64 with an e-mail system, you may need to do this to make other programs recognize files encoded using ENCODE64.EXE. Since the command line cannot accept characters (for line breaks), you will need to use the following special characters: % -- Insert filename. ^ -- Insert CR/LF. # -- Insert space. This would be a generic header: -hContent-Disposition:#attachment;#filename="%" ^Content-Transfer-Encoding:#BASE64 ^Content-Type:#application/octet-stream (Note that I split up into three sections what would normally be a single string on the command line.) If this header string were used, the header that appears at the top of encoded files would appear like this: Content-Disposition: attachment; filename="anyfile.zip" Content-Transfer-Encoding: BASE64 Content-Type: application/octet-stream 3. About DECODE64.EXE: ~~~~~~~~~~~~~~~~~~~~~~ This part of the documentation may seem a little complex, but the only really necessary command-line option is the first: the input file which contains the encoded data. Command line for this program is: DECODE64 [output file] [/M] [/O] [/K] [/L] Items in <> are necessary, in [] are optional. Where is any Base64-encoded file. /O --> Tell DECODE64 to automatically erase any files it needs to without prompting you. Be careful when using this switch that you do not overwrite any important files. /K --> Tell DECODE64 to NOT Keep reading through a Base64- encoded file until all files are decoded out of it. If you want it to stop scanning the file after the first file is decoded, or if you know that the encoded file only contains one file to decode, then use this. It will speed up processing because DECODE64 won't need to keep searching. [output filename] --> DECODE64 will use this instead of the filename it finds inside the Base64-encoded file(s). When using the "/M" option, DECODE64 will use the filename it finds in the first Base64-encoded file it scans. /M --> Tell the program to accept input from more than one file. If you use this, you should use a instead of a single . The mask should use generic DOS wildcard characters such as '*' and '?'. Use the "DIR" command to make sure the files are in the correct order before decoding. (See examples below.) /L --> Tell DECODE64 to decode multiple encoded files, one at a time, using a . This (obviously) does not work with "/M". The [output file] option does not work with this. "/K" is automatically activated by the program when this switch is used, meaning that only the first file located in each encoded file will be decoded, and decoding will stop in each file as soon as the first file is finished. (See examples below.) At the top of every multiple-part file created by ENCODE64, it tells what part number the current file is, and how many parts there are totally. This first number can be used to create the correct filename for decoding multiple-part files, if you receive them in different e-mails. (Otherwise there may not be a way to tell which file comes first, second, etc.) Note that DECODE64 is *not* able to read this header automatically, since it does not know which files are made with which encoder. DECODE64 will automatically right- and left-justify all lines of encoded data. * Examples: * ~~~~~~~~~~~~~ C:\>DECODE64 PROGRAM.64 PROG.ZIP Running it with this command line will make DECODE64 attempt to decode PROGRAM.64, and, instead of using the file name it finds in PROGRAM.64, it will use the filename PROG.ZIP to output to. - C:\>DECODE64 PROGRAM.64 PROG.ZIP /O If PROG.ZIP already exists, DECODE64 will erase it without prompting. - C:\>DECODE64 PROG*.64 PROG.ZIP /M /O DECODE64 will use the filename mask "PROG*.64" and use those files to output to PROG.ZIP. DECODE64 will discard whatever filename it finds in the PROG*.64 files, and use the name "PROG.ZIP" instead. If PROG.ZIP already exists, DECODE64 will erase it without prompting. Be careful when using the /M option -- use "DIR" before running DECODE64 to make sure your files are in the correct order. Such as: PROG01.64 PROG02.64 PROG03.64 ... This would be ideal. This is the order that ENCODE64 puts files in. - C:\>DECODE64 *.64 /L This would decode all files with the ".64" extension, one at a time. - The ideal format for the BASE 64 file would be one created by the ENCODE64 program, or in this format: --========================== name="test.zip"
AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJKKKKLLLLMMMMNNNNOOOOPPPP QQ== --========================== Note the blank line between the header and the encoded data, and the "-" character immediately following the encoded data. This will make sure the file is created properly. If there is no blank space between the header and the encoded data, the program will keep reading until it reaches a blank line, causing errors. If the file ends immediately after the encoded data, DECODE64 will give an error message ("Possible unexpected end of file"), but will nevertheless create the file correctly. It is recommended that there be a line starting with a dash (-) immediately following the data. About the "Bad Character" error: This error is caused by a character other than the ones accepted by Base64 being in the encoded data. This error will not halt the program, but the outputted file may have bad data in it. If the end of the encoded data was not properly found, this error could also be caused by DECODE64 attempting to decode regular text which may appear after the encoded file segment. Most other errors may be caused by DECODE64 not being able to properly find the end of the encoded data. For best results, edit the encoded file so it matches the template shown above. 4. About UNIX2DOS.COM: ~~~~~~~~~~~~~~~~~~~~~~ I included this program in the archive so that users who have a UNIX e-mail system can also use the Base64 encoder and decoder. The program will convert any generic UNIX-type text file to the DOS CR/LF standard. The command line is simple: UNIX2DOS Where is the name of any UNIX-type text file. This program will not harm DOS-type text files if they are processed. 5. Technical Information: ~~~~~~~~~~~~~~~~~~~~~~~~~ BASE-64 (MIME encoding) converts regular 8-bit encoded files into a form which can be readily transmittable via Internet e-mail. It is impossible to send any 8-bit file over e-mail without this or a similar process done (such as XX-encoding, UU-encoding, etc). The way it encodes is by taking three (8-bit) bytes from the file, and converting those 24 bits into 4 sets of 6-bit numbers. Since a 6-bit number can never go over 63, it outputs to the BASE-64 file with these characters: Character:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ Value: 0..............................................................63 Since all files will not have sizes evenly divisible by three, padding is added with the "=" character at the end of the BASE64-encoded data. BASE-64 is superior to UU encoding & XX encoding in that it does not use any characters that may *not* be readily transmittable via Internet. Also, for every 45 encoded characters of XX & UU, there is one extra character as a line checksum (seen as the first character of every line). Data transmission has become so reliable that checksums are no longer necessary. For more information on MIME encoding, look up RFC 1521. (This and other files can be downloaded off my homepage. See the URL at the top of this document or by running ENCODE64 or DECODE64.) 6. Disclaimer, Distribution, About the Author, Etc. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DISCLAIMER: I'm not responsible if this messes up your computer in any way. But how could it? :) If you enjoy using this, or use it a lot, please register! Since I have spent WAY too much of my life updating this program and providing support to users, I have "upgraded" this from freeware to shareware. (There are 400+ lines of code in DECODE64 alone!) If there are any persistent problems with either of the programs which you think are bugs, e-mail me. These programs can be distributed freely as long as ALL of the original files are kept in the same archive, not modified in any way, and no other programs can be put into the same archive with these. (See VENDOR.TXT) If these programs are put on a CD-ROM, FTP site, WWW, BBS, etc, I'd appreciate knowing it! Also, none of the programs can be sold. Thanks go to the few people who have written me and convinced me to bring out future versions with revisions and improvements, and to those who have written just to thank me! :) My e-mail address is: frog@star2.opsys.com If that doesn't work: d034923c@dc.seflin.org My homepage (great place!): http://www.geocities.com/SiliconValley/Park/3056/ 7. Registration information ~~~~~~~~~~~~~~~~~~~~~~~~~~~ As you may have noticed, I have not added anything to the program to cripple it, or any "nags". (Except for a small registration notice at the beginning of the program. :) I've also been giving out a lot of technical support to many, many users! So, if you use this program a lot, please e-mail me for registration information. (Especially important for companies!) You can request a registration form by writing to me at the address below. Registration is just $15^ for the three programs (ENCODE64, DECODE64, and the always useful SHELL2). Just $5 each + of course, you get UNIX2DOS for free. My e-mail address is: frog@star2.opsys.com If that doesn't work: d034923c@dc.seflin.org ^ -- A company site license is extra. 8. Revision Updates ~~~~~~~~~~~~~~~~~~~ These notes tell of features, etc, added to the programs after the first release. The programs themselves don't tell their own version number, but if this document was included with your archive, then you have the updated version. Sorry, no fancy version numbers. Can only make filename eight characters! --\ #1|--> Basic version. Didn't even support more than one command line --/ option. :( After a lot of tracking down, I even found a copy of it! --\ #2|--> 1. First update. --/ 2. Support for using the 'name = ' string instead of 'name=""' string. (Used by some encoders.) 3. User can now optionally overwrite files: either the Base64 files created by ENCODE64 or the files created by DECODE64. 4. Support for some encoders, which, instead of having dashes ("-") immediately following encoded data, will terminate with a blank line. If DECODE64 finds a blank line anywhere in encoded data, it will stop processing. --\ #3|--> Basically re-wrote the entire program. --/ 1. User can now enter two filenames on the command line, one specifying the input file, and one the output file. For ENCODE64, you can specify the file name to use instead of the generic ".64" file; with DECODE64, you can specify which file name to use instead of the one found in the header of the file DECODE64 decodes. 2. Fast, Assembler character search routine added to DECODE64. 3. Corrected error of DECODE64: it left one or both files open if an error occurred during processing. 4. /O option added to command line. This will force the programs to automatically attempt to overwrite any files they create, without making a (Y/N) prompt to ask you if you want it overwritten. ***USE CAREFULLY*** (So as to not overwrite important data.) 5. /M option added. For ENCODE64, this will allow the output of more than one Base64 file; for DECODE64, this will allow the input of more than one Base64 file into one larger file. (When using with DECODE64, it requires a filename mask instead of an input filename.) 6. Programs themselves have become more helpful -- I've added better help and error notices. Just run the programs with no command line to see the help. 7. Added more efficient code to both ENCODE64 and DECODE64. Nearly doubled the math speed of ENCODE64. --\ #4|--> 1. Included the file utility UNIX2DOS with the archive. It will --/ convert UNIX text files to DOS format, which is used by ENCODE64 & DECODE64. It will not harm DOS text files if they are accidentally processed. 2. Percentage meter added to ENCODE64, activated by the "/P" command-line parameter. For single-file encoding, it will tell you how far through it is. For multiple file encoding, it will tell how far complete it is on the single file it is working on. (The last file it creates may not reach 100%) 3. ENCODE64 tells how many files it will create before it starts processing. 4. Added code to ENCODE64 for faster string concatenation. Over double the speed of the old routine. 5. ENCODE64 now, instead of using number of lines as the basis for multi-part encoding, will use kilobytes instead. 6. SHELL64 program added to archive; Windows program to make encoding and decoding files easier, especially for multiple files. It is the first version, so there may be some bugs to iron out. 7. "Text/plain" in header of encoded files has been changed to "application/octet-stream" for compatibility with mail programs. --\ #5|--> 1. ENCODE64 has gotten even faster AND smaller. A miracle of --/ modern programming efficiency. :) 2. DECODE64 can now decode more than one file out of a single Base64-encoded file, using the "/K" option. 3. ENCODE64 changed so last boundary marker leaves extra two dashes ("--") for more compatibility with MIME. Also, there is now an empty line between the last line of encoded data and the last boundary marker. 4. Another option added to DECODE64 -- "/L". With this, many files can be decoded at once using a . Useful for batch files and e-mail programs! 5. DECODE64 will now "intelligently" scan for the filename in the header. It will look for anything between two quotes and anything coming after the "=" symbol. (Not just for the two 'name = ' and 'name="' strings.) It is much more compatible with e-mail programs. 6. UNIX2DOS has been re-written entirely in Assembler for more speed. Therefore, it doesn't really have that many options, and is only safe when used properly. On the other hand, it is faster and much smaller! --\ #6|--> 1. UNIX2DOS re-written. VERY fast. --/ 2. Support for new Content-Disposition header. Hopefully this won't mess up any e-mail programs. 3. You can define your own boundary marker now. Good for using ENCODE64 with e-mail systems. 4. 386 Assembler code added for more speed. Still not very fast, but what can you expect from Pascal? 5. Headers can be defined on the command line. 6. Small error using ENCODE64 with Shell64 -- the pause after the program runs would sometimes mess things up a bit. --\ #7|--> 1. Shell64 reincarnated as Shell2. --/ 2. 386 code being taken out of version #6. Wasn't worth not letting the program be run on 286 and slower computers for such a minimal gain in speed. 3. Big bugs in the original Shell64 which are fixed in Shell2. Probably more, but I can't find everything! 4. Updated Shell2's faulty PIF files. 5. Fixed bug with ENCODE64's and DECODE64's (undocumented) "/W" command-line option, which is only used by Shell2. I think it's actually a bug with the TP compiler I use, but I fixed it by adding Assembler code that does nearly the same thing. This bug would cause ENCODE64 and DECODE64, when used with SHELL2, to produce an error by Windows which would alert the user to re-boot the computer. 6. Bug with using DECODE64 with SHELL2 - Shell2 would put the file it decodes into the wrong directory. Fixed! __________________________________________________________________________ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~