home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxgzlib.zip / rxgzlib.doc < prev    next >
Text File  |  1999-12-22  |  8KB  |  220 lines
  1. 21 December 1999.
  2.  
  3. rxGZlib ver 1.01 -- GZIP compression procedures for OS/2 REXX
  4.  
  5. These procedures will deflate, and inflate, both strings and files.
  6. Deflate & inflage are used by the popular GZIP compression program; hence
  7. the output of these procedures is readable by GZIP.EXE (and vice versa).
  8.  
  9. In addition, GZIP is often used in as an http content-encoding.
  10. It is hoped that the availability of this library will encourage OS/2 REXX 
  11. programmers to use GZIP compression in their web applications.
  12.  
  13.  
  14. Installation:
  15.    To install rxGZlib, simply copy rxGZlib.dll to your LIBPATH; 
  16.    say, to x:\OS2\DLL, where x: is your boot drive.  You'll also
  17.    need to load the rxGZlib library; see the description of
  18.    rxGZloadfuncs for an example of how to do this.
  19.  
  20.  
  21. Notes:
  22.  
  23.    *  SRC.ZIP contains the source code for rxGZlib.
  24.  
  25.    *  RXGZLIB2.ZIP contains an under-development alternate to the
  26.       rxGZlib procedures. 
  27.    
  28.    *  TSTGZLIB.CMD contains a short example of how to use rxGZlib.
  29.       TST2ZLB.CMD demonstrates that the rxGZlib procedures are interoperable
  30.       with GZIP.EXE.
  31.  
  32.    *  rxGZlib.dll does NOT require EMX (EMX, and ZLIB.LIB, are built into 
  33.       the dll).
  34.  
  35.    *  rxGZlib has been tested under classic rexx.
  36.       It may, or may not, work under other flavors of REXX (such as 
  37.       object rexx).
  38.   
  39.    *  rxGZlib has been tested, but as a new release it may have bugs.
  40.       Please contact us if you run into any problems (see the bottom of 
  41.       this file for contact info).
  42.  
  43.  
  44.               ---------------------------------------------------
  45. I) Description of procedures
  46.  
  47. The following describes the rxGZlib procedures.
  48.  
  49.  
  50. rxGZloadfuncs -- Load the rxGZlib library.
  51.    Use this to load the rxGZlib library. 
  52.  
  53.     Example:
  54.        foo=rxfuncquery('rxGZLoadFuncs')
  55.        if foo=1 then do
  56.           foo2=RxFuncAdd( 'rxGZLoadFuncs', 'rxGZlib', 'rxGZLoadFuncs')
  57.            if foo2=0 then 
  58.               say "Sorry. rxGZlib is not available"
  59.            else
  60.               call rxGZLoadFuncs
  61.        end
  62.  
  63.  
  64. rxGZUnloadFuncs --Unload the rxGZlib library.
  65.    Use this to unload the rxGZlib library. 
  66.  
  67.    Example: 
  68.       call rxGZUnloadFuncs
  69.  
  70.  
  71. rxGZDeflateFile(infile,outfile[,compression_opt])
  72.     "Deflate" infile, and store results to outfile (outfile will
  73.      a compressed file).
  74.  
  75.      compression_Opt is optional, and should take a value between "0" and
  76.      "9", with "0" meaning no compression, and "9" meaning maximal
  77.      compression. Note that the the default compression level is 6.
  78.  
  79.      Returns a status code:
  80.         0 - success
  81.         1 - problem opening/reading from inputfile 
  82.         2 - problem writing to outputfile
  83.         4 - problem finalising outputfile
  84.  
  85.     Example:
  86.         stat=rxGZDeflateFile('c:\samples\myfile.exe','c:\samples\myfile.gz')
  87.         stat=rxGZDeflateFile('c:\samples\myfile.exe','c:\samples\myfile2.gz',"9")
  88.  
  89.  
  90. rxGZInflateFile(infile,outfile)
  91.      Inflate (unDeflate) infile, and store results to outfile. Note that infile
  92.      MUST be a GZIP-formatted "deflated" file (say, as produced by 
  93.      GZIP.EXE, or by rxGZDeflateFile).
  94.  
  95.      Returns a status code:
  96.         0 - success
  97.         1 - problem opening/reading from inputfile 
  98.         2 - problem writing to outputfile
  99.         4 - problem finalising outputfile
  100.  
  101.  
  102.      Note that if infile is NOT a GZIP formatted file, rxGZInflateFile will copy
  103.      infile to outfile.
  104.  
  105.     Example:
  106.         stat=rxGZInflateFile('c:\samples\myfile.gz','e:\foo\barfile.out')
  107.     
  108. rxGZDeflateString(a_string[,compression_Opt])
  109.      Deflate a string, and return the results.
  110.  
  111.      compression_Opt is optional, and should take a value between "0" and
  112.      "9", with "0" meaning no compression, and "9" meaning maximal
  113.      compression. Note that the the default compression level is 6.
  114.  
  115.      rxDeflateString creates a string using the GZIP format.
  116.      Note that this is somewhat different from the "ZLIB" format that
  117.      may be produced by other versions of the ZLIB library.
  118.  
  119.  
  120.      The advantage of the "GZIP" format is that the output can be read
  121.      by GZIP.EXE. For example, 
  122.      If ...
  123.         a) you have a file (say FOO.BAR),
  124.         b) you create FOO.BAR.GZ using rxGZDeflateFile
  125.         c) you read FOO.BAR into a string (VARFOO)
  126.         d) you create VARFOO_gz using rxDeflateString; i.e.;
  127.            VARFOO_GZ=rxdeflatestring(varfoo)
  128.      Then ...
  129.         the contents of FOO.BAR.GZ and VARFOO_gz will be the same. 
  130.  
  131.      Example:
  132.           astring='This is just a short string that we will use'
  133.           deflated_string=rxDeflateString(astring)
  134.  
  135.  
  136. rxGZInflateString(deflated_string)
  137.     Inflate (undeflate) a "GZIP" string, and return the results.
  138.  
  139.     If an error occurs, then an empty string will be returned. 
  140.     This can happen if deflated_string is not a "deflated string".
  141.  
  142.      Example:
  143.           astring='This is just a short string that we will use'
  144.           deflated_string=rxDeflateString(astring)
  145.  
  146.             /* .... a zillion lines of  miscellaneous code */
  147.  
  148.            astring_recover=rxInflateString(deflated_string)
  149.        
  150.  
  151.               ---------------------------------------------------
  152.  
  153. II) Future changes:
  154.  
  155. We may add a more formal method of reporting error codes, string to file 
  156. (and vice versa) procedures, and support for the ZLIB format (which is
  157. slightly more efficient for short strings).
  158.  
  159. If and when this occurs, it will probably appear in the MYGZIP "alternate"
  160. version of rxGZlib.
  161.  
  162.               ---------------------------------------------------
  163.  
  164.  
  165. III) Example:
  166.  
  167.    Although it's not necessarily recommended, the following illustrates
  168.    how one can use rxDeflateString instead of rxDeflateFile.
  169.  
  170.    /* read a file into a string (with no error checking) */
  171.    input_file='c:\samples\foobar.exe'
  172.    sz=stream(input_file,'c','query size')
  173.    astring=charin(input_file,1,sz)
  174.    foo=stream(input_file,'c','close')
  175.    
  176.    deflated_astringz=rxDeflateString(astring,1)
  177.    
  178.    output_file='c:\samples\foobar.exe.gz'
  179.    oo=charout(output_file,deflated_astringz,1)
  180.    foo=stream(output_file,'c','close')
  181.  
  182.               ---------------------------------------------------
  183.  
  184. IV) Disclaimer and terms of use:
  185.  
  186.    The various components of rxGZlib are freeware that are to be used at  
  187.    your own risk -- the authors and any potentially affiliated 
  188.    institutions disclaim all responsibilties for any consequence arising from 
  189.    the use, misuse, or abuse of this software (or pieces of this software).
  190.  
  191.    You may use this (or subsets of this) program as you see fit,    
  192.    including for commercial purposes; so long as  proper attribution
  193.    is made, and so long as such use does not in any way preclude 
  194.    others from making use of this code.
  195.  
  196.    Note that the zlib, and gzip, formats are in the public domain --
  197.    see http://www.gzip.org for the details.
  198.  
  199.               ---------------------------------------------------
  200.  
  201. V) Contact information
  202.  
  203. The principal contact for rxGZlib related matters is:
  204.  
  205.          Daniel Hellerstein (danielh@crosslink.net)
  206.  
  207. who is merely instigating & packaging & distributing the work of:
  208.  
  209.    Christopher McRae,  christopher.mcrae@mq.edu.au
  210.    Timur Kazimirov, timurk@sax.mmbank.ru
  211.  
  212. and with help from
  213.    Michal Necasek, mike@mendelu.cz
  214.  
  215. The most current distribution version of rxGZlib can be found at:
  216.    http://www.srehttp.org/apps/rxgzlib, or 
  217.    http://www.srehttp.org/distrib/rxgzlib.zip
  218.  
  219. .end of documentation
  220.