R_Compress() 
 Compresses a file using the Lempel-Ziv algorithm
------------------------------------------------------------------------------

 Syntax
        nRetCode := R_Compress ( cInFile [, cOutFile[, nCmpFact ] ] )

 Arguments
        cInFile         File specification of the file to be compressed
                        (=input file)
                        Format  : [drive:][\path\]filename[.ext]
                        Example : C:\INVOICE\INVOICE.DBF

        cOutFile        File specification of the compressed file
                        (=output file)
                        Format  : [drive:][\path\]filename[.ext]
                        Example : C:\INVOICE\INVOICE.ZIP

                        If NO output file name is specified the output file
                        will be created on the default drive, in the default
                        directory, with the same name as the input file.
                        THE FIRST CHARACTER OF THE FILE NAME EXTENSION WILL
                        BE REPLACED BY THE '#' CHARACTER.

                        Examples:
                        R_Compress ( 'TEST.DBF', 'TEST.LZC' ) => TEST.LZC
                        R_Compress ( 'TEST.DBF' )             => TEST.#CP

(v2.0)  nCmpFact        Compression factor [1-5]
                        Higher numbers give a higher compression factor.
                        Default value is 5. In most cases this is the best
                        choice. If there are "not-enough-memory" problems
                        take a lower compression factor : this saves memory
                        (but the size of the compressed files will increase
                        a little bit ...).

 Returns
        nRetCode        Numeric return code

                        The values and descriptions of this return code
                        are defined in RCmpLib.CH :

        +-----------------------------------------------------------+
        |Code|Constant            |Description                      |
        |----+--------------------+---------------------------------|
        |  0 |CP_OKAY             |Everything okay                  |
        |  1 |CP_INVALID_PARM     |Invalid parameter(s) passed      |
        |  2 |CP_OPEN_INPUT       |Error OPENING input file         |
        |  3 |CP_NOT_RCMPLIB      |Not compressed by RCmpLib        |
        |  4 |CP_WRONG_VERSION    |Wrong version of RCmpLib         |
        |  5 |CP_CREATE_OUTPUT    |Error CREATING output file       |
        |  6 |CP_READ_INPUT       |Error READING  input  file       |
        |  7 |CP_WRITE_OUTPUT     |Error WRITING  output file       |
        |  8 |CP_CLOSE_INPUT      |Error CLOSING  input  file       |
        |  9 |CP_CLOSE_OUTPUT     |Error CLOSING  output file       |
        | 10 |CP_MEMORY_ERROR     |Not enough memory                |
        | 11 |CP_ALLOCATE_ERROR   |Error allocating buffer          |
        +-----------------------------------------------------------+

 Description
        Compresses the input file using Lempel-Ziv compression.

        +----------------------------------------------------------------+
        |                         -+- CAUTION -+-                        |
        |                                                                |
        |     IN THE UN-REGISTERED  VERSION OF RCMPLIB THE FOLLOWING     |
        |     REGISTRATION MESSAGE WILL BE DISPLAYED AT RANDOM TIMES     |
        |     (WHILE EXECUTING THE R_COMPRESS() FUNCTION) :              |
        |                                                                |
        | UN-Registered version of RCmpLib -+- Please wait for 8 seconds |
        |                                                                |
        |       AFTER A 8 SECONDS DELAY THE PROGRAM WILL CONTINUE.       |
        +----------------------------------------------------------------+

 Example
        *-- Compresses the file INVOICE.DBF => INVOICE.#BF

        *-- Header file of RCmpLib
        #include "RCmpLib.CH"

        LOCAL   nRetCode                        && Return code R_Compress
        LOCAL   aCmpError := CP_ERRMSG          && Array with error msgs

        *-- Save the original file size
        LOCAL   nFSizeIn   := R_FSize ( 'INVOICE.DBF' )
        LOCAL   nFSizeOut                       && Size of output file
        LOCAL   nFactor                         && Compression factor

        [...]

        nRetCode := R_Compress ( 'INVOICE.DBF', 'INVOICE.#BF' )

        IF nRetCode = CP_OKAY

                *-- Compression is okay :
                *--    delete the original file
                FErase ( 'INVOICE.DBF' )

                *-- Determine the size of the compressed file
                nFSizeOut := R_FSize ( 'INVOICE.#BF' )

                *-- Calculate the compression factor
                nFactor   := 100*(nFSizeIn-nFSizeOut)/nFSizeIn

                *-- Show the compression factor
                ALERT ( 'Compression factor : '+Str(nFactor)+' %' )

        ELSE
                *-- Oops, error while compressing ...

                *-- Display the error message
                ALERT ( 'Error R_Compress() : ' + aCmpError [nRetCode] )
        ENDIF

        *-- Continuation of the program
        [...]

        More examples can be found in the demo program RCmpDemo.PRG.