XbZ_Compress2()
Previous  Top  Next

XbZ_Compress2() - Compress (Deflate) a string with the variable Compression Level.

Syntax

XbZ_Compress2(@cData,  
             [nCompression],  
             [@nError]) --> cCompressed  

Parameters

<@cData>  
<@cData> contains a string that should be compressed (with the Deflate method). This parameter must be passed by reference, even though it will not be modified.  

<nCompression>  
<nCompression> optionally specifies the Compression Level that is used. If this value is omitted or invalid, it  
will default to XBZ_DEFAULT_COMPRESSION.  
 
Possible options are the following Define Constants from the XbZLib.ch file:  
 
Define
Value
Description
XBZ_DEFAULT_COMPRESSION
-1
Default compression (similar to 6).
XBZ_NO_COMPRESSION
0
No compression, cannot be specified!
XBZ_BEST_SPEED
1
Minimum compression, fastest speed.
XBZ_BEST_COMPRESSION
9
Maximum compression, slowest speed.
 
 
Also possible are all integer values between 1 and 9 (for which no define constants exist), which determine the relation between Speed and Compression Ratio and give a finer granulation than the above listed Define values. But in virtually all cases, the Default Compression is the best compromise between compression ratio and speed. Using higher compression ratios will result in only very slightly smaller files, and using a better speed (lower compression ratio) will give only very small improvements in the speed!  
 
This function is also used for compressing the Data of Zip File Entries by the :AddData() method, using the instance variable :Compression for this value.  

<@nError>  
After XbZ_Compress2() returns, the optional Parameter <@nError> will contain any kind of Compression Error that might be raised by the ZLib compress2() function. This parameter is optional, but must be passed by reference if it should be updated.  
 
Possible values are the following Define Constants from the XbZLib.ch file:  
 
Define
Value
Description
XBZ_OK
0
Adding/Updating of (File) Entry was successful.
XBZ_STREAM_ERROR
-2
(ZLib Error Code) Compression Level invalid.
XBZ_MEM_ERROR
-4
(ZLib Error Code) Not enough Memory.
XBZ_BUF_ERROR
-5
(ZLib Error Code) Output Buffer too small.
 

Returns

This function returns a Deflated (compressed) version of <@cData> or possibly a string that only contains spaces, if an error occurred.  

Description

This is basically an Xbase++ Wrapper Function for the ZLib Function: compress2(). It returns the compressed (deflated) <@cData> as a string, and updates <@nError> with any possible Error Return Code of the ZLib Function. It is virtually identical to the XbZ_Compress() method, but additionally allows the setting of <nCompression>.  

Example

LOCAL nError := XbZ_OK  
LOCAL cFile  := 'XbZLib.chm'  
LOCAL cData  := XbZ_FileRead(cFile, @nError)  
LOCAL cCompr := ''  
if nError == XbZ_OK  
   cCompr := XbZ_Compress2(@cData, XBZ_BEST_SPEED, @nError)  
   if nError # XbZ_OK  
      QOut(cFile + ' could not be compressed!')  
      QOut('Error: ' + alltrim(str(nError)))  
   endif  
else  
   QOut(cFile + ' could not be read!')  
   QOut('Error: ' + alltrim(str(nError)) + ' - ' + ;  
                DosErrorMessage(nError))  
endif