home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1993 #2 / Image.iso / clipper / cacode.zip / CAENCODE.TXT < prev    next >
Text File  |  1993-07-14  |  13KB  |  308 lines
  1. *************************************************************************
  2.  
  3.                               IMPORTANT NOTE:
  4.  
  5. If you do not have the MS C compiler, version 5.0 or higher, then *DO NOT* 
  6. delete the .OBJ files:
  7.  
  8.      INT2B.OBJ
  9.      B2INT.OBJ
  10.      BYTESOUT.OBJ.  
  11.  
  12. They are needed for linking and you will be unable to recreate them without 
  13. the MS C compiler.
  14.  
  15. *************************************************************************
  16.  
  17. CA-ENCODE and CA-DECODE HISTORY
  18.  
  19. CAEncode() and CADecode() are Clipper counterparts for the Unix utilities: 
  20. uuencode and uudecode.  The CA in the place of UU means, naturally, 
  21. Computer Associates (our new and adopted parents).  
  22.  
  23. They differ slightly in convention and application.  The most notable 
  24. difference is that they are written in Clipper and can be directly 
  25. incorporated in any Clipper application.  
  26.  
  27. Version 1 of these utilities was written in 100% Clipper, which was my 
  28. original goal in doing them.  The programs' functionality and performance 
  29. were not the main concern.  I simply wanted 100% Clipper code that I could 
  30. use in any Clipper application.  I simply wanted to do it and say it was 
  31. "pure Clipper!"  well, been there, done that!
  32.  
  33. I actually had more response that I had anticipated, and a number of people 
  34. from all over North America and Europe have asked me about them, and for 
  35. permission to use them (something I apparently forgot to mention in the 
  36. original documentation.)
  37.  
  38. Since there was more than academic interest in Version 1, several people 
  39. commented on the speed, or rather lack of it.  This is something that I did 
  40. not neglect to mention in the original documentation.  I was aware that on 
  41. a 486-33, it took Version 1.0 almost one full minute to encode a 30K binary 
  42. file, and almost three minutes to decode it.  But the stated purpose of 
  43. that early version was strictly an exercise in "doing it all in Clipper."
  44.  
  45. So, with a stated interest in actually using the programs, and with the 
  46. adoption of the programs as the "official" encoder of the FidoNet CLIPPER 
  47. echo, I thought it might be worthwhile to divorce myself from the "100% 
  48. Clipper" ideology, and rewrite the time intensive portions in "C" (which is 
  49. still, after all, linkable to Clipper and therefore of use embedded in 
  50. Clipper applications.)
  51.  
  52.  
  53.  
  54. The gains were fairly decent, and short of rewriting it completely in "C",
  55. I have finagled a fair amount of performance out of them.  The encoder and 
  56. decoder both take between 10 and 15 seconds to encode/decode what used to 
  57. take about 1-3 minutes.  It is still largely a Clipper effort, and so it is 
  58. still not going to be as fast as a "100% C" program.  The largest gains 
  59. came from rewriting in "C" those routines that performed character to 
  60. binary and binary to character translations.
  61.  
  62. A later version may incorporate even greater performance benefits by 
  63. working on more than three bytes at a time.  Let's just wait and see how 
  64. this version goes, first.
  65.  
  66. The real benefit of CAENCODE and CADECODE is that they are completely free, 
  67. come with complete Clipper and "C" source and are user modifiable with no 
  68. restrictions on modifications or use.  Basically, do with them what you 
  69. will (except redistribute them with your name on them).  For use in 
  70. commercial or corporate applications, feel free to remove my name and 
  71. whatnot from the screen output sections.
  72.  
  73.  
  74.  
  75. PURPOSE & USAGE
  76.  
  77. CAENCODE Syntax: CAENCODE <inputfilename.ext> <outputfilename.ext>
  78.  
  79. CADECODE Syntax: CADECODE <inputfilename.ext>
  80.  
  81.      where <inputfilename.ext> is the CAENCODE <outputfilename.ext>
  82.  
  83. Some e-mail networks do not support the full ASCII character set and so 
  84. cannot be used to transmit any file containing these characters across 
  85. those networks.  And almost ALL mail systems cannot handle high-order or 
  86. low-order ASCII characters (usually referred to collectively as the non-
  87. printable character set).  Any attempt to do so will invariably end up in 
  88. mayhem.
  89.  
  90. These programs together allow you to take any DOS file, whether EXE, COM, 
  91. LIB, OBJ, TXT, WRI, DLL, whatever, and encode them into a file that 
  92. contains only the transmittable/printable characters in the ASCII ranges of 
  93. 48-111 (or, "0" - "o").
  94.  
  95. This resulting file can be readily transferred across almost any network / 
  96. mail system as a typical message.
  97.  
  98.  
  99.  
  100. Example:
  101.  
  102.         MYLIB.LIB   23,456  09-12-91  03:40a
  103.  
  104. This file cannot be transmitted as a message in a mail echo.  The high / 
  105. low order ASCII characters in it will completely throw any mailer / reader 
  106. that comes across it.  But you can encode it so that all the characters are 
  107. sure to be transmittable:
  108.  
  109.     CAENCODE MYLIB.LIB MYLIB.CAE
  110.  
  111. Here is what the output file MYLIB.CAE might look like:
  112.  
  113. +++CAFile: mylib.lib
  114. +++CABegin+++
  115. P0X024=1ADi3CdA5?9Kd0008@d55CT=?A4D4@dm4A@E9E4m2D`A3CdA5149DCdT4@dm4
  116. A@QCE45DBD=C90A3CdA51d=OAEA5F5@7ADi4@dm4A@UODeU=DeA1DU@8DeU=DeA1DU@7
  117. DeU=@Tm<D`MCFDe2CdaC1emCFDe5CT@6DeU=ADi414iEC4`7@TE7A45D@@EOA45D@@A4
  118. @EA11UmCFDe@@PA4@EA11EmCFDe@14A1E446Ge=ICE1514A1E446Gd=?CU=D1D=?CU=D
  119. 15m=DdL3CE=71em2ADM2De<6@TE7@U=C15m2De<3@U=C1em5CTA2De<6ADi4@U=C1TA7
  120. DTmED7bH1`10W@D20`5iV0L0@8l010D1R9P7042500H70HjH1`10:0082@7WV0L0B000
  121. 06DK4@0Z_@0C100g0@0k0P1LZbL102[003T205\`0P0Z`P0i0P1l7`d0:\@0>@40;`80
  122. LC0102[703L207TN001PRi`50<@1E094W0D0b0AD1cRL1@3425@7>9`50<`>EPdRX8T0
  123. 0`00^1H0^`00Dk\005<>D9X00000Pl@8bbX002P10b[>07`_0`1l;`@0:]00=`40[G9Z
  124. ;`807P\0HcL203KoogD_0P0g0P1lJB0a02[B03L406L_100Ze00g0@0g101b_P41<@1N
  125. 0000000000000000BEA?@U<000000000000004I9C4D00000000000000016Ce15CP00
  126. 000000000000AT=BAD5DA@000000000004IGDTUDA@00000000000016DTE1A0000000
  127. 00000000@E=3@Dh0000000000000049DCdT00000000000000011C5A4000000000000
  128. 0000AT=<Ce=500000000000005=D@EA9@e<T00000P00003=W0L0c1a@0@0099`50<`\
  129. EP8?W0D0c3aF0ojL1`3<C502003cW0D0c5aF1=fL1@3<K5H5c9`50<alEPJkW0D0c8aF
  130. 1jZL1@3<W5H8VI`50<b\EPV8W0L0c;a@0`00PY`50<c<EPYWW0D0c=aF2eJL1`3<k504
  131. 001AX0`0300000000?00001HW0D0c01D1cR@3`000@Q3@DE>@dm4A@0002J@30000PE9
  132. E4m2D`000=b@2`000`A2E4m90000<8X2001d
  133. +++CAEnd+++
  134.  
  135.  
  136. The token +++CAFile: informs the decoder of the file name of the original 
  137. file.  CADECODE will be recreate it with it's original name without you 
  138. having to know it.
  139.  
  140. The token +++CABegin+++ informs the decoder that the encoded data begins on 
  141. the very next line. 
  142.  
  143. The token +++CAEnd+++ informs the decoder that it has processed the last 
  144. line of encoded text.
  145.  
  146.  
  147.  
  148. You can annotate your encoded file by including text (for humans) in 
  149. between the +++CAFile and +++CABegin+++ tokens.  Anything in this area is 
  150. ignored by the CADECODE decoder.  Simply create the encoded file as shown 
  151. above, then use an ASCII text editor to insert lines of text in between the 
  152. +++CAFile: token and the +++CABegin+++ token. Example:
  153.  
  154. +++CAFile: mylib.lib
  155.  
  156. ********************************************************************
  157.  
  158.     John,
  159.  
  160.     Try this library out and let me know if it works for you!
  161.     I hope this fixes the problem.  If it does not, call me at
  162.     (918) 481-5715
  163.  
  164.                                              Dave
  165. ********************************************************************
  166.  
  167. +++CABegin+++
  168. P0X024=1ADi3CdA5?9Kd0008@d55CT=?A4D4@dm4A@E9E4m2D`A3CdA5149DCdT4@dm4
  169. A@QCE45DBD=C90A3CdA51d=OAEA5F5@7ADi4@dm4A@UODeU=DeA1DU@8DeU=DeA1DU@7
  170. DeU=@Tm<D`MCFDe2CdaC1emCFDe5CT@6DeU=ADi414iEC4`7@TE7A45D@@EOA45D@@A4
  171. @EA11UmCFDe@@PA4@EA11EmCFDe@14A1E446Ge=ICE1514A1E446Gd=?CU=D1D=?CU=D
  172. 15m=DdL3CE=71em2ADM2De<6@TE7@U=C15m2De<3@U=C1em5CTA2De<6ADi4@U=C1TA7
  173. DTmED7bH1`10W@D20`5iV0L0@8l010D1R9P7042500H70HjH1`10:0082@7WV0L0B000
  174. 06DK4@0Z_@0C100g0@0k0P1LZbL102[003T205\`0P0Z`P0i0P1l7`d0:\@0>@40;`80
  175. LC0102[703L207TN001PRi`50<@1E094W0D0b0AD1cRL1@3425@7>9`50<`>EPdRX8T0
  176. 0`00^1H0^`00Dk\005<>D9X00000Pl@8bbX002P10b[>07`_0`1l;`@0:]00=`40[G9Z
  177. ;`807P\0HcL203KoogD_0P0g0P1lJB0a02[B03L406L_100Ze00g0@0g101b_P41<@1N
  178. 0000000000000000BEA?@U<000000000000004I9C4D00000000000000016Ce15CP00
  179. 000000000000AT=BAD5DA@000000000004IGDTUDA@00000000000016DTE1A0000000
  180. 00000000@E=3@Dh0000000000000049DCdT00000000000000011C5A4000000000000
  181. 0000AT=<Ce=500000000000005=D@EA9@e<T00000P00003=W0L0c1a@0@0099`50<`\
  182. EP8?W0D0c3aF0ojL1`3<C502003cW0D0c5aF1=fL1@3<K5H5c9`50<alEPJkW0D0c8aF
  183. 1jZL1@3<W5H8VI`50<b\EPV8W0L0c;a@0`00PY`50<c<EPYWW0D0c=aF2eJL1`3<k504
  184. 001AX0`0300000000?00001HW0D0c01D1cR@3`000@Q3@DE>@dm4A@0002J@30000PE9
  185. E4m2D`000=b@2`000`A2E4m90000<8X2001d
  186. +++CAEnd+++
  187.  
  188.  
  189. To send an .OBJ or .COM file to another user in another part of the world, 
  190. simply encode the file, send the encoded file as an e-mail.  He may then 
  191. download your text message, cut it out with a word processor of his choice, 
  192. and decode it.  Naturally, both sides must have the same encoder/decoder 
  193. set (CAEncode/CADecode).
  194.  
  195. To decode the file:
  196.  
  197.     CADECODE mylib.cax
  198.  
  199.  
  200. MYLIB.CAX will be decoded into MYLIB.LIB *OVERWRITING* any MYLIB.LIB that 
  201. happens to be in the current directory.  BE CAREFUL.
  202.  
  203.  
  204.  
  205. DEVIATIONS
  206.  
  207. I forget what all of them are.  I disposed of individual line checksums.  
  208. Most mail handlers and e-mail networks are reliable enough today that lost 
  209. data is rare.  Besides, most off-line readers and other mail tossers work 
  210. with entire message bases that are ZIPPED, so any damage to the file is not 
  211. going to be recoverable even with a checksum.  The result is a few 
  212. percentage points of smaller encoded file.
  213.  
  214. Also, the tags/tokens are obviously different (+++CABegin+++ is plainly 
  215. specific to CA-Clipper).
  216.  
  217. Additionally, the ability to embed unrelated text in the encoded file is a 
  218. big plus (in my opinion) since I can then document, in plain text (as much 
  219. of it as I need), the encoded file.  After all, several pages of "garbage" 
  220. isn't very descriptive.  The text area between +++CAFile: and +++CABegin+++ 
  221. are very useful for notes and descriptive messages to the recipient of the 
  222. file and can contain, for instance, a description and even decoding 
  223. instructions!  It is all ignored by the decoder.
  224.  
  225.  
  226. COMPILING
  227.  
  228. The batch file COMPILE.BAT contains all the necessary compile and link 
  229. scripts that you will need to compile and link with either Blinker or 
  230. RTLink.
  231.  
  232. IMPROVEMENTS
  233.  
  234. There are some planned.  If you have improvements and would like them 
  235. incorporated, send them my way (with a description - I am not a mind 
  236. reader), and I will incorporate them (if it is as good as you say it is) 
  237. and give you full credit in the source code and documentation.  I have 
  238. established a list of distribution points both in North America and Europe 
  239. and these people are expecting updates to come from me directly.
  240.  
  241. DISTRIBUTION
  242.  
  243. Please distribute this product all over the world.  Try to do so in an 
  244. unmodified manner.  Keeping track of multiple "different copies" can be a 
  245. nightmare.  Something I'd like to avoid.  LONG LIVE CLIPPER!  Death to the 
  246. Bourgeois Imperialistic MicroSoft software dictatorship!
  247.  
  248.  
  249.  
  250. NOTICE
  251. -------------------------------------------------------------------------
  252.  
  253. Please make sure that the echo, network, or other e-mail system that you 
  254. participate in allows the use of such products as this.  Many sysops will 
  255. become quite irate (myself included) if an echo turns into nothing but a 
  256. file transfer channel.  Echoes are meant to carry meaningful discussions 
  257. and conversations; not meaningless CAEncode codes.
  258.  
  259. The CLIPPER echo DOES allow the use of this product within reasonable 
  260. limits.  The Moderator is j_mag guthrie, or sometimes just j_mag.  Ask if 
  261. you are in doubt.
  262.  
  263. Comments are welcome, as are suggestions for improvements/features. The 
  264. source code is included for those of you who want to "roll-your-own."
  265.  
  266. ***********************************************************************
  267.  
  268. These programs may be distributed/used freely with no charge and with no 
  269. royalty.  It may be modified and used in any manner you see fit.
  270.  
  271. The only restriction is that you may not modify and then redistribute
  272. the product.  This is FreeWare.  Thank me in whatever way you see fit 
  273. (money is not necessarily the answer... - I have other products for that)
  274.  
  275. ***********************************************************************
  276.  
  277. Oh, By the way!
  278.  
  279. One interesting application of it that I have seen is program storage on 
  280. paper!  Really.  I'm not kidding.  A friend here in Tulsa actually scanned 
  281. a print of an encoded file into a document imaging system, then used OCR 
  282. software to recreate it, then ran CADECODE against it and got his original 
  283. program back.  Other programs are simply stored as plain disk documents in 
  284. the weirdest program archive I have ever seen.
  285.  
  286. There are various ways to reach me.  Any FidoNet node that carries either 
  287. the Clipper or Mensa echoes can be used to get e-mail to me I use the name 
  288. KIRBY WALLACE - I wonder why?
  289.  
  290. Kirby L. Wallace
  291.  
  292. CIS: 70262,524
  293.  
  294. I frequent these addresses:
  295.  
  296. FidoNet 1:170/110
  297. OS2Net  1:202/201
  298. ibmNet  40:4372/0
  299.  
  300. AT&T Net: (918) 835-7109 (Data - well, sometimes)
  301.  
  302. And, least likely of all, since I move often:
  303.  
  304. US SnailNet : 120 N. Sandusky Ave.
  305.               Tulsa, OK.  74115
  306.               USA
  307.  
  308.