home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxcrc32.zip / RxCRC32.INF (.txt) < prev   
OS/2 Help File  |  1998-01-24  |  13KB  |  355 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. RxCRC32 V1.00
  5. A REXX interface DLL for CRC-32
  6.  
  7. Copyright (C) Mads Orbesen Troest & SIRIUS Cybernetics 
  8.  
  9.  
  10. ΓòÉΓòÉΓòÉ 1.1. Abstract ΓòÉΓòÉΓòÉ
  11.  
  12. Abstract Introduction 
  13.  
  14. So what on earth is this stuff all about?! 
  15.  
  16. RxCRC32 is a small OS/2 Dynamic Link Library (DLL) that interfaces quite fast 
  17. routines for the calculation of CRC-32 checksums with REXX. 
  18.  
  19. CRC-32 is used many places; it is widely considered a de-facto checking method 
  20. of most modern communication systems, and is also frequently used as a unique 
  21. identifier for a given file. 
  22.  
  23. However, it is a rather computionally intensive task to calculate a CRC-32; 
  24. REXX is way too slow for this, unless you are a very, very patient person. 
  25.  
  26. With this easy-to-use and very versatile DLL, you can efficiently calculate 
  27. CRC-32 from your standard REXX programs, without even bothering about the 
  28. implementation of the algorithm. You won't ever need looking for other 
  29. alternatives of getting a CRC-32 of a file or buffer from REXX! 
  30.  
  31.  
  32. ΓòÉΓòÉΓòÉ 1.2. Conditions of Use ΓòÉΓòÉΓòÉ
  33.  
  34. Conditions of Use 
  35.  
  36. This version is to be considered internal SIRIUS Cybernetics software; it must 
  37. not be spread to other parties without the author's explicit accept! 
  38.  
  39. If you are not a member of SIRIUS Cybernetics, you may only use this package if 
  40. you have got the consent of Mads Orbesen Troest. 
  41.  
  42. Click here to see how to contact the author... 
  43.  
  44.  
  45. ΓòÉΓòÉΓòÉ 1.3. Contacting Author ΓòÉΓòÉΓòÉ
  46.  
  47. Contacting Author 
  48.  
  49. If you wish to contact me for any questions, feedback, suggestions or just 
  50. plain talk, you can reach me in the following ways: 
  51.  
  52.      SnailMail 
  53.  
  54.           Mads Orbesen Troest 
  55.           Dyrskuevej 53, 1.MF 
  56.           DK-9200 Aalborg SV 
  57.           Denmark 
  58.  
  59.      Phone 
  60.  
  61.           (+45) 3073 5352 (Voice) 
  62.           (+45) 9818 5383 (Fax/Data) 
  63.  
  64.      InterNet 
  65.  
  66.           motr96@sprog.auc.dk 
  67.           http://www.sprog.auc.dk/~motr96 
  68.           Eek @ #Eek & #OS/2 (IRC Net) 
  69.  
  70.      FTN 
  71.  
  72.           2:238/202@FidoNet 
  73.           81:445/202@OS2Net 
  74.  
  75.  Never you hesitate to write; I always enjoy response to my work! 
  76.  
  77.  
  78. ΓòÉΓòÉΓòÉ 2. Using RxCRC32 ΓòÉΓòÉΓòÉ
  79.  
  80. Using RxCRC32 
  81.  
  82. This section describes how you make RxCRC32 accessible to your own REXX code, 
  83. and how you go about utilising the available functions. 
  84.  
  85.  
  86. ΓòÉΓòÉΓòÉ 2.1. Making RxCRC32 Accessible ΓòÉΓòÉΓòÉ
  87.  
  88. Making RxCRC32 Accessible 
  89.  
  90. The first thing you must do to be able to use RxCRC32 from your own REXX 
  91. programs is to tell the REXX interpreter which external functions to load from 
  92. which DLL. This is achieved through the RxFuncAdd command: 
  93.  
  94.           /* Sample REXX Code for making all functions of RxCRC32 available */
  95.  
  96.           CALL RxFuncAdd "RxCRC32Ver",    "RXCRC32", "RXCRC32VER"
  97.           CALL RxFuncAdd "RxCRC32Init",   "RXCRC32", "RXCRC32INIT"
  98.           CALL RxFuncAdd "RxCRC32Update", "RXCRC32", "RXCRC32UPDATE"
  99.           CALL RxFuncAdd "RxCRC32Done",   "RXCRC32", "RXCRC32DONE"
  100.  
  101.  I know... I might have made it easier for you by providing a 
  102.  "RxCRC32LoadFuncs", but I was too lazy to do that; you'll have to accept this, 
  103.  or bug me to implement it in a newer version, if any such is to come. 
  104.  
  105.  A comment on unloading the DLL (and other REXX DLLs): It is, in fact, very 
  106.  nasty behaviour if you try to manually enforce OS/2 to drop the external 
  107.  functions it has loaded. OS/2 will automatically discard these DLLs when the 
  108.  session from which it was loaded is ended; if you force it to drop the 
  109.  functions before that, all other running programs that may use it will also 
  110.  loose the funcs! Please remember that this is a multi-tasking system! 
  111.  
  112.  After having added the functions with the REXX RxFuncAdd call, you should be 
  113.  able to call them. The next section describes how you use the set of routines 
  114.  to calculate CRC-32 from your own REXX application... 
  115.  
  116.  
  117. ΓòÉΓòÉΓòÉ 2.2. RxCRC32 Usage ΓòÉΓòÉΓòÉ
  118.  
  119. RxCRC32 Usage 
  120.  
  121. To calculate the CRC-32 of something, you need to take the following steps: 
  122.  
  123. First, you must call RxCRC32Init; this call returns an initialised CRC-32 
  124. variable (which consists of an 8-byte, uppercased hexadecimal numeric string). 
  125. You might think of this returned value as a sort of handle from an open 
  126. function (only, this value is not fixed, but continously updated as the CRC 
  127. calculation progresses); you must supply it to both RxCRC32Update and 
  128. RxCRC32Done when calling them. 
  129.  
  130. After having initialised a CRC variable, you keep calling RxCRC32Update until 
  131. you are through your data. The reason RxCRC32 works this way is that it becomes 
  132. very flexible that way. The update-function takes the current CRC variable and 
  133. a buffer-string to process. It returns the new, updated CRC variable that you 
  134. must pass the next time. 
  135.  
  136. When you have processed all your data this way, you must call RxCRC32Done to 
  137. complete the calculation. This call also takes the current CRC variable as 
  138. argument, and returns the final CRC-32 value of the calculation. After having 
  139. called this function, you may no longer call the update- or done-functions, 
  140. until a new CRC-session is initialised with the init-function. 
  141.  
  142. For further details, I suggest you take a look at the examples to see how to 
  143. use RxCRC32 in practice. 
  144.  
  145.  
  146. ΓòÉΓòÉΓòÉ 3. RxCRC32 Function Reference ΓòÉΓòÉΓòÉ
  147.  
  148. RxCRC32 Function Reference 
  149.  
  150. This section provides a reference of the functions that RxCRC32 provide. These 
  151. functions are: 
  152.  
  153.      RxCRC32Ver - Return Version Information 
  154.      RxCRC32Init - Initialise CRC-32 Calculation 
  155.      RxCRC32Update - Update CRC-32 Calculation with Buffer 
  156.      RxCRC32Done - Complete CRC-32 Calculation 
  157.  
  158.  
  159. ΓòÉΓòÉΓòÉ 3.1. RxCRC32Ver - Return Version Information ΓòÉΓòÉΓòÉ
  160.  
  161. RxCRC32Ver 
  162.  
  163.           ΓöÇΓöÇΓöÇRxCRC32Ver()ΓöÇΓöÇΓöÇΓöÇΓöÇ
  164.  
  165.  RxCRC32Ver returns a version and copyright string with the following format: 
  166.  
  167.           ID      VER   - COPYRIGHT NOTICE
  168.           ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  169.           RxCRC32 V1.00 - (C) Mads Orbesen Troest & SIRIUS Cybernetics
  170.  
  171.  Examples 
  172.  
  173.  
  174. ΓòÉΓòÉΓòÉ 3.2. RxCRC32Init - Initialise CRC-32 Calculation ΓòÉΓòÉΓòÉ
  175.  
  176. RxCRC32Init 
  177.  
  178.           ΓöÇΓöÇΓöÇRxCRC32Init()ΓöÇΓöÇΓöÇΓöÇΓöÇ
  179.  
  180.  RxCRC32Init returns an initialised CRC-32 variable (an 8-digit hexadecimal 
  181.  string) for further use during the runnning calculation of the CRC. 
  182.  
  183.  This call must always be made during the initialisation phase of the CRC 
  184.  calculation, before calling RxCRC32Update or RxCRC32Done. 
  185.  
  186.  Examples 
  187.  
  188.  
  189. ΓòÉΓòÉΓòÉ 3.3. RxCRC32Update - Update CRC-32 Calculation with Buffer ΓòÉΓòÉΓòÉ
  190.  
  191. RxCRC32Update 
  192.  
  193.           ΓöÇΓöÇΓöÇRxCRC32Update( CRC, Buffer )ΓöÇΓöÇΓöÇΓöÇΓöÇ
  194.  
  195.  RxCRC32Update returns an updated running (must be initialised through 
  196.  RxCRC32Init) CRC-32 variable (an 8-digit hexadecimal string) for continued use 
  197.  during the calculation of the CRC. 
  198.  
  199.  This function takes the running CRC-32 variable as argument, followed by a 
  200.  string holding the buffer with which to update the running CRC value. 
  201.  
  202.  Examples 
  203.  
  204.  
  205. ΓòÉΓòÉΓòÉ 3.4. RxCRC32Done - Complete CRC-32 Calculation ΓòÉΓòÉΓòÉ
  206.  
  207. RxCRC32Done 
  208.  
  209.           ΓöÇΓöÇΓöÇRxCRC32Done( CRC )ΓöÇΓöÇΓöÇΓöÇΓöÇ
  210.  
  211.  RxCRC32Done completes the running CRC calculation; after calling this function 
  212.  no more calls to RxCRC32Update may be made, until it is reinitialised by 
  213.  RxCRC32Init. 
  214.  
  215.  This function takes the running CRC-32 variable (an 8-digit hexadecimal 
  216.  string) as argument, and returns the final, completed result of the CRC 
  217.  calculation. 
  218.  
  219.  Examples 
  220.  
  221.  
  222. ΓòÉΓòÉΓòÉ 4. Examples of Usage ΓòÉΓòÉΓòÉ
  223.  
  224. Examples of Usage 
  225.  
  226. This section provides a couple of examples on how to use RxCRC32 in practice: 
  227.  
  228.      CRC-32 of Entered String 
  229.      CRC-32 of File 
  230.  
  231.  
  232. ΓòÉΓòÉΓòÉ 4.1. CRC-32 of Entered String ΓòÉΓòÉΓòÉ
  233.  
  234. CRC-32 of Entered String 
  235.  
  236. Here is the REXX source for a small script that reads a line of text from stdin 
  237. (keyboard by default), and calculates its corresponding CRC-32 value: 
  238.  
  239. Source Code: 
  240.  
  241.           /* RxCRC32-Test: Calculate CRC-32 of Entered String *
  242.            *                                                  *
  243.            * (C) Mads Orbesen Troest & SIRIUS Cybernetics     */
  244.  
  245.           /* Load External RxCRC32 Routines: */
  246.  
  247.           CALL RxFuncAdd "RxCRC32Ver",    "RXCRC32", "RXCRC32VER"
  248.           CALL RxFuncAdd "RxCRC32Init",   "RXCRC32", "RXCRC32INIT"
  249.           CALL RxFuncAdd "RxCRC32Done",   "RXCRC32", "RXCRC32DONE"
  250.           CALL RxFuncAdd "RxCRC32Update", "RXCRC32", "RXCRC32UPDATE"
  251.  
  252.           /* Do some initial chitchat: */
  253.  
  254.           SAY ""
  255.           SAY "RxCRC32-Test: Calculate CRC-32 of Entered String, utilising:"
  256.           SAY RxCRC32Ver() /* Report Version Information */
  257.           SAY ""
  258.  
  259.           /* Initialize the variable CRC for running CRC-32 calculation: */
  260.  
  261.           CRC = RxCRC32Init()
  262.  
  263.           /* Get the buffer to calculate: */
  264.  
  265.           SAY "Whack in some line that you want me to calculate the CRC-32 of:"
  266.           PARSE PULL Buffer
  267.  
  268.           /* Calculate CRC-32 of Buffer: */
  269.  
  270.           CRC = RxCRC32Update( CRC, Buffer )
  271.  
  272.           /* Complete Calculation: */
  273.  
  274.           CRC = RxCRC32Done( CRC )
  275.  
  276.           /* Report the result: */
  277.  
  278.           SAY ""
  279.           SAY "Well, then... CRC-32 : "CRC" (HEX) - Thanks for using RxCRC32 :-)"
  280.  
  281.  Screen Dump: 
  282.  
  283.           RxCRC32-Test: Calculate CRC-32 of Entered String, utilising:
  284.           RxCRC32 V1.00 - (C) Mads Orbesen Troest & SIRIUS Cybernetics
  285.  
  286.           Whack in some line that you want me to calculate the CRC-32 of:
  287.           Dear Mads Orbesen Troest; thank you SO much for a neat REXX DLL!!! ;-)
  288.  
  289.           Well, then... CRC-32 : 08511B7C (HEX) - Thanks for using RxCRC32 :-)
  290.  
  291.  
  292. ΓòÉΓòÉΓòÉ 4.2. CRC-32 of File ΓòÉΓòÉΓòÉ
  293.  
  294. CRC-32 of File 
  295.  
  296. Here is the REXX source for a small script that reads a file from disk, and 
  297. calculates its corresponding CRC-32 value: 
  298.  
  299. Source Code: 
  300.  
  301.           /* RxCRC32-Test: Calculate CRC-32 of Stored File *
  302.            *                                               *
  303.            * (C) Mads Orbesen Troest & SIRIUS Cybernetics  */
  304.  
  305.           ARG FileName /* Get FileName on CommandLine */
  306.           IF FileName = "" THEN EXIT /* Exit if no FileName Specified */
  307.  
  308.           /* Define a BufferSize for the blocks read from the File */
  309.           /* Do not set too low as this gives unnecessary calling-overhead! */
  310.           /* Set it after how much memory you are willing to spend on it... :-) */
  311.  
  312.           BufferSize = 4096 /* Can't be that bad a size; could be bigger though .-) */
  313.  
  314.           /* Load External RxCRC32 Routines: */
  315.  
  316.           CALL RxFuncAdd "RxCRC32Ver",    "RXCRC32", "RXCRC32VER"
  317.           CALL RxFuncAdd "RxCRC32Init",   "RXCRC32", "RXCRC32INIT"
  318.           CALL RxFuncAdd "RxCRC32Done",   "RXCRC32", "RXCRC32DONE"
  319.           CALL RxFuncAdd "RxCRC32Update", "RXCRC32", "RXCRC32UPDATE"
  320.  
  321.           /* Do some initial chitchat: */
  322.  
  323.           SAY ""
  324.           SAY "RxCRC32-Test: Calculate CRC-32 of Stored File, utilising:"
  325.           SAY RxCRC32Ver() /* Report Version Information */
  326.           SAY ""
  327.  
  328.           /* Initialize the variable CRC for as in CRC-calculation: */
  329.  
  330.           CRC = RxCRC32Init()
  331.  
  332.           /* Calculate CRC-32 of File: */
  333.  
  334.           DO UNTIL LENGTH( Buffer ) \= BufferSize /* Traverse File */
  335.            Buffer = CHARIN( FileName,, BufferSize ) /* Fill Buffer (there may be a faster way :-) */
  336.            CRC = RxCRC32Update( CRC, Buffer ) /* Update CRC with Buffer */
  337.           END
  338.  
  339.           /* Complete Calculation: */
  340.  
  341.           CRC = RxCRC32Done( CRC )
  342.  
  343.           /* Report the result: */
  344.  
  345.           SAY "Well, then... CRC-32 : "CRC" (HEX) - Thanks for using RxCRC32 :-)"
  346.  
  347.  Screen Dump: 
  348.  
  349.           WarpTek [d:\work\programming\cpp\rxcrc32.dll] FileCRC32.CMD FileCRC32.CMD
  350.  
  351.           RxCRC32-Test: Calculate CRC-32 of Stored File, utilising:
  352.           RxCRC32 V1.00 - (C) Mads Orbesen Troest & SIRIUS Cybernetics
  353.  
  354.           Well, then... CRC-32 : 89BF3738 (HEX) - Thanks for using RxCRC32 :-)
  355.