home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxrsync.zip / rxrsync.doc < prev    next >
Text File  |  1999-11-16  |  12KB  |  303 lines
  1. 15 November 1999.
  2.  
  3.         RxRsync: Rexx procedures to implement the rsync differencing protocol 
  4.  
  5. Absract:
  6.    RxRsync contains several OS/2 classic REXX procedures that implement
  7.    the rsync "differencing" protocol. This document describes their use.
  8.  
  9.                         ---------------------
  10.  
  11. I) Introduction
  12.  
  13. The Rsync protocol is a "client/server" differencing protocol that 
  14. does not require that both parties have the same copy of a prior 
  15. version.  Instead, the client sends a synopsis of a prior 
  16. version, information which the server can use to create a difference 
  17. file (it uses this synopsis in lieu of the actual contents of the 
  18. prior version).
  19.  
  20. Thus, rsync trades off some extra exchange of information (the synopsis
  21. the client sends to the server), in return for removing the 
  22. need for both sides of the transaction having identical copies of 
  23. the prior version. Of course, the efficiency of rsync is a function 
  24. of how close the prior version (on the client side) is to the current
  25. version (on the server side).  Nevertheless, in even the worst case
  26. (comparison of two different random files), the penalty is small; wheras
  27. in the best case (slight changes), 10 to 1 reductions in total (both ways)
  28. message size are not uncommon.
  29.  
  30. The rsync protocol has several steps. Assume a client wants a current
  31. version of a file; and that the client has a prior version of the
  32. file available. Then:
  33.  
  34. 1) A "client" creates a "synopsis" of it's prior version.  
  35. 2) The client requests the "server" for the current version, and
  36.    sends a copy of this synopsis along with this request
  37. 3) The server creates a "difference" file by comparing the synopsis
  38.    to it's copy of the current version.
  39. 4) The server send this difference file back to the client
  40. 5) The client combines the difference file with it's copy of the prior
  41.    version to create an exact duplicate of the new version.
  42.  
  43. Note that the server is NOT expected to have a copy of the prior version!
  44.  
  45. The procedures in RxRsync can be used to implement this chain of events.
  46. About all you need to do is worry about the communication steps (steps
  47. 2 and 4).
  48.  
  49.                         ---------------------
  50.  
  51. II) Installing RxRsync
  52.  
  53. First, unzip RXRSYNC.ZIP to an empty temporary directory.
  54.  
  55.   1) Copy RXRsync.DLL to your LIBPATH (say, copy it to x:\OS2\DLL).
  56.      You will also need a copy of REXXUTIL, but that's part of
  57.      most OS/2 installations.
  58.      
  59.   2) Write a REXX program, and  either:
  60.        a)include a copy of RxRSYNC.REX (say, put it at the end of your 
  61.          rexx program file)
  62.        b) Load RxRSYNC.RXL into "macrospace", and load a few dlls.
  63.        See the notes in section IV below for the details.
  64.  
  65.   3) Within your REXX programs, call the procedures.
  66.  
  67.  
  68. Alternatively, you can use the RXSYNC.CMD program -- it's an "all rexx"
  69. implementation of rsync.  It's very slow, but it should work on
  70. any REXX system.
  71.  
  72.                         ---------------------
  73.  
  74. III) Description of procedures
  75.      
  76. There are three  REXX procedures:
  77.  
  78.      rsync_client: creates a synopsis of an old version.
  79.      rsync_server: uses this synopsis, and the new version, to create
  80.                    an rsync difference file
  81.      rsync_undiff: uses the difference file, and the old version, to
  82.                    build a copy of the new version
  83.  
  84. Rsync_client: create a synopsis of an old version
  85.  
  86.    Syntax:
  87.  
  88.      status=rsync_client(oldver_file,synopsis_file,comment,quiet,blocksize)
  89.  
  90.    where:
  91.        oldver_file: a fully qualified file name (the old version)
  92.        synopsis_file: a fully qualified file name (the synopsis file)
  93.        comment: an optional comment 
  94.        quiet: set to 1 to suppress runtime status messages
  95.               This is an optional parameter (the default is 0).
  96.        blocksize: blocksize to be used when creating synopsis file.
  97.                   Sizes between 500 and 1000 seem to work best.
  98.                   This is an optional parameter (the default is 500)
  99.  
  100.    and
  101.        status: A status message of the form:
  102.                  stat multi-word message
  103.                where
  104.                   stat= OK for success
  105.                         ERROR for failure
  106.  
  107.    Notes:
  108.      * Examples of status returned values:
  109.            ERROR no such old version
  110.            OK 5151 bytes written to  C1FILE.RSY
  111.      *  The synopsis_file will be created in "overwrite mode" (prior
  112.         versions of this file will first be deleted).
  113.      *  The comment can be up to 80 characters long. If not specified,
  114.         a timestamp is used
  115.  
  116. Rsync_server: use a synopsis to create a difference file
  117.    
  118.    Syntax:
  119.  
  120.       status=rsync_server(synopsis_file,newver_file,diff_file,quiet)
  121.  
  122.     where:
  123.         synopsis_file: a synopsis file 
  124.         newver_file: a fully qualified file name (the new version)
  125.         diff_file: a fully qualified file name  (the difference file)
  126.         quiet: set to 1 to suppress runtime status messages
  127.             This is an optional parameter (the default is 0).
  128.      and
  129.         status: A status message
  130.  
  131.    Notes:
  132.       * as with the synopsis_file, the diff_file is created in overwrite mode
  133.       * the status has the same structure as status in rsync_client
  134.  
  135. Rsync_undiff:  create a duplicate of a new file from a difference file
  136.  
  137.    Syntax:
  138.  
  139.          status=rsync_undiff(oldver_file,diff_file,newver_file_dup,quiet)
  140.  
  141.    where:
  142.         oldver_file: a fully qualified file name (the old version)
  143.         diff_file: a fully qualified file name  (the difference file)
  144.         newver_file_dup: a fully qualified file name (the "duplicate" new ver)
  145.         quiet: set to 1 to suppress runtime status messages
  146.             This is an optional parameter (the default is 0).
  147.  
  148.    and
  149.         status: A status message
  150.  
  151.    Notes:
  152.       * as with the synopsis_file, the newver_file_dup is created in 
  153.         overwrite mode
  154.       * the status has the same structure as status in rsync_client
  155.  
  156.                         ---------------------
  157.  
  158. IV) The rxRsync.Dll dynamic link library.
  159.  
  160. Since REXX is very slow at repetitive math, the above rexx procedures 
  161. use several procedures in rxRsync.dll. 
  162.  
  163. RxRsyncLoad: Loads the rxRsync procedures.
  164.  
  165.   For example:
  166.  
  167.   if rxfuncquery('rx_md4')=1  then do
  168.       call RXFuncAdd 'RXRsyncLoad', 'RXRSYNC', 'RxRsyncLoad'
  169.       call RxRsyncLoad
  170.   end
  171.   if rxfuncquery('rx_md4')=1  then do
  172.      return "ERROR could not load  RxRsync.DLL"
  173.   end
  174.  
  175. RxRsyncDrop: unload the rxRsync procedures
  176.    
  177.    For example:
  178.         call RxRsyncDrop
  179.  
  180. RX_RSYNC32: Compute a 32 bit rolling checksum of a string
  181.   
  182.    For example: 
  183.        csum32=rx_rsync32('some kind of string of any length')
  184.        csum32 will be an 8 character hex number
  185.  
  186. RX_MD4: Compute an MD4 hash of a string
  187.    For example: 
  188.        amd4=rx_md4('some kind of string of any length')
  189.        amd4 will be a 32 character hex number
  190.  
  191. RX_RSYNC32_MD4: Compute a 32 bit rolling checksum, and an md4 hash
  192.    For example: 
  193.        csum32_md4=rx_rsync32_md4('some kind of string of any length')
  194.        csum32 will be an 20 characters. The first 4 are the rolling
  195.        checksum, characters 5 to 20 are the MD4. 
  196.        Thus:  csum32=c2x(substr(csum_32_md4),1,4)
  197.               amd4=c2x(substr(csum_32_md4),5,16)
  198.         
  199. RX_RSYNC_SERVER: Compute a "difference", given a "current instance
  200.                  and a "synopsis".
  201.  
  202.     status=rx_rsync_server(newverfile,synopsis,outfile)
  203.     where:
  204.         newverfile: a file containing the "current instance"
  205.         synopsis: the "synopsis" of the "old instance" (as may be
  206.                   produced by rsync_client)
  207.         outfile: a file name, the "difference" file will be written
  208.                  to this file name (in overwrite mode)
  209.         use4: Optional. If set to 1, then only the first 4 characters of
  210.               the md4 checksum are used to verify. This is useful
  211.               when using the http version of rsync (smaller request
  212.               headers, with some small risk of an incorrect "undifferencing",
  213.               which may necessitate a re-request).
  214.      status is a status message. If it begins with OK, then success.
  215.      Otherwise, it will begin with ERROR.
  216.  
  217.                         ---------------------
  218.  
  219. V) Notes and disclaimer
  220.  
  221.   * RSYNCtst.CMD demonstrates the use of these procedures as text inclusions.
  222.  
  223.   * RSyncts2.CMD  demonstrates their use as a macrospace library.
  224.  
  225.   * !!! If you use the "macrospace" version, you MUST be sure to 
  226.     load several dlls, and to load the macrospace library.  
  227.  
  228.     RsyncTs2 contains a simple procedure (LOAD_LIBS) that will do this.
  229.  
  230.   * The Rsync protocol was invented by Andrew Tridgell. For more information,
  231.     see http://samba.org.au/rsync/  
  232.  
  233.   * Users of the SRE-http web server (http://www.srehttp.org) can use
  234.     the sreRsync "pre-reply procedure", and the DoGET.CMD http requester,
  235.     as an http implementation of rsync.
  236.  
  237.   * Structure of a synopsis file
  238.      Comment  -- 80 characters (i.e.; a requested file name)
  239.      1 space
  240.      Blocksize  -- 6 digit integer (i.e; 500)
  241.      1 space
  242.      #Blocks    -- 8 digit character (N)
  243.      1 space
  244.      md4        -- 32 digit md4
  245.      3 spaces
  246.      chksum1||md41||..||chksumN||md4N -- chksum and md4 values 
  247.                                          (machine integer format, 
  248.                                          high order bytes first)
  249.  
  250.   * Structure of a differnce file:
  251.      md4 --     32 hex character  md4 of "new file"
  252.      1 space
  253.      blocksize - several digit blocksize (i.e.; 500)
  254.      crlf       - 0x0d0a  
  255.      Record1   -- a BLOCK or CHARACTER record
  256.      crlf
  257.      ...
  258.      RecordN
  259.      crlf
  260.  
  261.      The record structures are:
  262.         Bn1:n2          n1 and n2 are integers that define a "run" of blocks
  263.                         Example: B10:35  means "use blocks 10 to 35 of
  264.                                  the old version, where blocks are defined
  265.                                  by the blocksize"
  266.        Cnnn:string
  267.                        nnn is  an integer that defines how long the 
  268.                        "string". Note that string can contain any characters
  269.                        (including crlfs),  and can be of any length.
  270.     
  271.  
  272.   * Contens of rxRsync.zip
  273.  
  274.         read.me       -- a small read.me file
  275.         RxRSYNC.RXL   -- REXX "macrospace" version of the three REXX procedures
  276.         rxrsync.rex   -- REXX code version of the three REXX procedures
  277.         rxsync.cmd    -- An all REXX implementation of Rsync (slow)
  278.         rsyncts2.cmd  -- Demo of rsync, using RxRSYNC.DLL
  279.         rsynctst.cmd  -- Demo of rsync, using (local copy of) rxrsync.rex
  280.         rxrsync.doc   -- this documentation file
  281.         RxRsync.dll   -- a Rexx callable dll containing several procedures
  282.         dllsrc.zip    -- Source code (watcom fortran, and rexx) used to create
  283.                          RxRsync.dll and RxRsync.rxl
  284.  
  285.                         ---------------------
  286.  
  287. Disclaimer:
  288.  
  289.    This is freeware that is to be used at your own risk -- the 
  290.    author and any potentially affiliated institutions disclaim all 
  291.    responsibilties for any consequence arising from the use, misuse, or abuse 
  292.    of this software (or pieces of this software).
  293.  
  294.    You may use this (or subsets of this) program as you see fit,    
  295.    including for commercial purposes; so long as  proper attribution
  296.    is made, and so long as such use does not in any way preclude 
  297.    others from making use of this code.
  298.  
  299. Contact:
  300.    Daniel Hellerstein (danielh@crosslink.net or danielh@econ.ag.gov)
  301.    
  302.  
  303.