R_CmpFile() 
 Compresses one or more files into a RCmpLib archive
------------------------------------------------------------------------------

 Syntax
        nRetCode := R_CmpFile ( acSkeleton, cRcpFile [, lMove
                        [, nBarLen [, nBarRow [, nBarCol [, cBarChr
                        [, cBarColor [, cPassWord [, lEscape [, bRCmpBlk
                        ] ] ] ] ] ] ] ] ] )

 Arguments
        acSkeleton      Array with file skeletons
                                p.e. { '*.DBF', 'C:\DB\*.NTX' }
                        - or -
                        String with one skeleton
                                p.e. '*.DBF'

                        A skeleton may contain a drive and/or a path and
                        the DOS wildcards * and ?.

        cRcpFile        Name of the archive file to be created
                        Format  : [drive:][\path\]filename[.ext]
                        Example : C:\INVOICE\INVOICE.ZIP
                        Default extension is .RCP

        lMove           .F.     : Don't delete the original files
                        .T.     : Delete original files after compression
                                  (if no errors are detected ...)
                        Default : .F. = no deletion of files

        nBarLen         Length of the progression bar
                        Default : 0 = no progression bar

        nBarRow         Screen row for the progression bar
                        Default : centered on the screen

        nBarCol         Screen column for the progression bar
                        Default : centered on the screen

        cBarChr         Character used for displaying progression bar
                        Default : # = Chr ( 219 )

        cBarColor       Color of the progression bar. This is a Clipper
                        color string.
                        Default : 'GR+/G' = Yellow on Green

        cPassword       Password for encryption of the archive file.
                        The maximum length of the password is 10 characters.
                        Default : no encryption
                        NOTE    : the password is case-sensitive !

        lEscape         .F.     : compression can't be interrupted by
                                  the user
                        .T.     : compression may be interrupted by pressing
                                  the <Esc> key
                        Default : .F. = no interruption

        bRCmpBlk        CodeBlock that is evaluated once for each file, just
                        before it is compressed.
                        The current file name is passed to bRCmpBlk.

 Returns
        nRetCode        Return code

                        Possible return codes :

                        0 = CP_OKAY           No errors detected
                        1 = CP_INVALID_PARM   Invalid parameter passed
                        5 = CP_CREATE_OUTPUT  Error CREATING archive file
                        6 = CP_READ_INPUT     Error READING  input  file
                        7 = CP_WRITE_OUTPUT   Error WRITING  output file
                        8 = CP_NO_FILES_FOUND No files found to compress
                        9 = CP_USER_ABORT     Compression aborted by user

                        See also the item ErrorCodes in this guide.

 Description
        Compresses one or more files into one archive file.

        Features :
        - progression bar display
        - password encryption

        About the PASSWORD :
        - Remember the password .... (it's impossible to decompress the
          the archive without the correct password !)
        - Maximum length is 10 characters
        - The password is case-sensitive

        About the CODEBLOCK bRCmpBlk :
        The codeblock, when used, should return one of the following values :
        0 = CP_ABORT    Compression will be aborted;
                        R_CmpFile() will return 9 (= CP_USER_ABORT)
        1 = CP_CONT     Compression continues
        These constants are pre-defined in RCmpLib.CH.

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

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

        *------------------------------------------------------------------
        * Files to be compressed : *.DBF, *.DBT & *.NTX (current directory)
        * Output : the archive file ARCHIVE.RCP
        * The original files will be deleted ( lMove = .T. )
        * Progression bar will be shown
        *       Length of bar = 20 - Position = 10,10 - Character = '#'
        *       Color  of bar = Bright White on Red
        * Password : TESTPW
        * Non interruptable ( lEscape = .F. )
        * Codeblock to evaluate for each file : { |x| ShowName ( x ) }
        *------------------------------------------------------------------
        nRetCode := R_CmpFile ( ;
                { '*.DBF', '*.DBT', '*.NTX' }, ;
                'ARCHIVE.RCP', .T., ;
                20, 10, 10, '#', 'W+/R', ;
                'TESTPW', .F., { |x| ShowName ( x ) } )

        IF nRetCode != CP_OKAY
                *-- Oops, error while compressing ...

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

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

        QUIT

        *------------------------------------------------------------------
        * Display the name of the file being compressed
        *------------------------------------------------------------------
        FUNCTION ShowName ( cFileName )

        DevPos ( 9, 10 )                && Just above the bar ...
        DevOut ( 'Compressing : ' + PadR ( cFileName, 12 ) )

        RETURN  CP_CONT                 && Continue compression

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

 .