Sets the data compression type and attribute to be used when creating files with data compression.
Note: To enable data compression, you need to either use the COMPRESS_FILE keyword or programmatically add ctCompressRec in the XCREblk.splval (for ISAM and Low-Level API).
ctSETCOMPRESS( NINT comptype, NINT compvrsn, pTEXT dllname, pTEXT attrstr, VRLEN attrlen )
attrstr - NULL if no fine-tuning parameters are specified, or the following optional parameter format is:
"parm1=value; ... parmn=value;"
zlib specific parameter names are:
sRLE specific parameter names are:
Similar in operation to ctSETENCRYPT(), ctSETCOMPRESS() determines the compression specifics that will be used for all compressed data files created after the call to ctSETCOMPRESS(). To use different compression routines for different files, the application creating the files must call ctSETCOMPRESS() before each of the creates. Calling ctSETCOMPRESS() does not affect the compression used by existing files. When existing files are opened the compression resource is used to specify how the records are compressed. Such an open will fail if the resource contains a DLL name that is not available.
If no call is made to ctSETCOMPRESS(), then default, built-in zlib compression routines are used, as long as no server configuration is specified otherwise.
If no DLL is required, dllname is NULL. If no fine-tuning parameters are specified, then attrstrf is NULL and attrlen is zero. (See User Defined Compression Dynamic Shared Library for additional details.)
Default FairCom DB compression can be specified with the following configuration keywords:
CMPREC_TYPE < "ZLIB" | "USER" | "RLE" >
CMPREC_VERSION <a number >= 1>
CMPREC_DLL <name of DLL>
These keywords should be entered in the configuration file in the order shown, and a DLL name is required for CMPREC_TYPE of USER.
The COMPRESS_FILE keyword can be used to enable compression in files whose names match specified file names (including wildcards).
Run Length Encoding (RLE) compression option is available in V10.3 and later. Configure the RLE compression algorithm in ctsrvr.cfg, similar to using the keywords ZLIB or USER.
In v10.3.0 and later, c-tree on Unix/Linux platforms dynamically loads zlib instead of statically linking with it.
Compressed Files in c-treeDB - In V10 and later, the c-treeDB file create mode, CTCREATE_COMPRESS, enables compressed record support in c-treeDB. When CTCREATE_COMPRESS mode is used, c-treeDB automatically creates the file as variable-length.
Could not allocate a buffer for an augmented variable-length record. (for example, ctCMPREC).
Augmented variable-length records not supported for SUPERFILE host, fixed length files or index files.
Could not decompress the data record. sysiocod set to Z_xyz_ERROR.
Compressed record-length files require ISAM update; not Low-Level update.
Requested operation not supported for augmented records.
Bad augmented record file mode at create. Two conditions return this error:
The FairCom DB data record compression feature supports user definable compression modules. To include a custom compression module, the following information must be made available from within the shared library.
pCMPRECFNC pfnc; input pointer to function pointer/DLL structure defined in ctstrc.h.
ppVOID pattrbuf; on input, a pointer to optional, fine-tuning parameter buffer. *pattrbuf==NULL implies no fine-tuning parameters specified. On output, *pattrbuf points to a parameter buffer. *pattrbuf is not guaranteed to be NULL on output if it is NULL on input, and vice versa.
pVRLEN pattrlen; on input, pointer to length of fine-tuning parameter buffer. If *pattrbuf is NULL on input, *pattrlen must be zero. On output *pattrlen contains the length of the parameter buffer.
pCMPRECRES pres; input pointer to compression resource structure defined in ctstrc.h.
pVOID context; input pointer to optional, compression/decompression support structure. If the compression (CmpActn) and/or decompression (ExpActn) routines do not use a support structure, then context will be NULL or ((pVOID) 1).
pVOID source; input pointer to byte stream to be compressed or decompressed.
VRLEN slen; input length of source buffer.
pVOID destination; output pointer to buffer that will contain the result of compression/decompression.
pVRLEN pdlen; on input, *pdlen is length of destination buffer. On output, *pdlen is the length of the byte stream result from the compression/decompression.
The module ctzlib.c has implementations of these functions for the built-in zlib support.
NINT FncInit(pCMPRECFNC pfnc,pTEXT attrstr,VRLEN attrlen)
This routine performs a one-time setup on each physical open of a file after the DLL has been loaded. attrstr and attrlen are the same as those in ctSETCOMPRESS(). In addition to any DLL specific requirements, FncInit() should verify that the compression type and version (pfnc->comptype and pfnc->compvrsn) are compatible with the DLL, and that the fine-tuning parameters, if any, are valid. If no fine-tuning parameters are passed in, then if the routines require a parameter set, FncInit() should allocate and initialize such a parameter buffer. If it does so, then it should set pfnc->allocbuf to the address of the allocated buffer.
FncInit() returns NO_ERROR or CMPR_ERR (). In the case of CMPR_ERR FncInit() should set the sysiocod (using the routine usys(code)) as listed in cterrc.h for CMPR_ERR. FncInit() does not actually set uerr_cod.
NINT FncExit(pCMPRECFNC pfnc )
FncExit() is called just before a file is closed and its associated DLL is unloaded. In addition to DLL specific requirements, FncExit() should free memory allocated for a parameter buffer. FncExit() can test pfnc->allocbuf to find the allocated buffer address, if any.
FncExit() should return NO_ERROR.
pVOID CmpInit(pCMPRECFNC pfnc)
CmpInit() is called each time a user opens a compressed data file. CmpInit() should allocate a context buffer if the DLL requires one, and initialize the context as needed. The context buffer would typically be used to initialize and maintain the compression state. If no such context buffer is needed, then return ((pVOID) 1).
CmpInit() returns the address of the context buffer, or (pVOID) 1 if no context is used, or NULL on error. In case of error call usys(35) to indicate the CmpInit() failure.
NINT CmpActn(pVOID context, pCMPRECFNC pfnc, pVOID source, VRLEN slen, pVOID destination, pVRLEN pdlen)
CmpActn() performs the actual compression of the source into the destination. *pdlen holds the length of the destination buffer on input, and is set to the length of the compressed output on return. CmpActn should be aware that an input value of ((pVOID) 1) means that no context structure has been provided.
CmpActn() returns CMPREC_OK () on success, CMPREC_BUF () if the destination buffer is too small, or CMPR_ERR for an unexpected error. In case of an unexpected error, usys(1000 + err) should be called to set sysiocod where err is the internal error code used by the compression routines. (See zlib1_CmpActn() for an example.)
NINT CmpExit(pVOID context, pCMPRECFNC pfnc)
CmpExit() is called each time a user closes a compressed data file. CmpExit() should de-initialize a context buffer, if one has been allocated in CmpInit(), and free the associated memory.
CmpExit() typically returns NO_ERROR unless the DLL specific code to de-initialize the context buffer returns an error code in which case return this error code.
The following three functions behave just as their compression counterparts except that they apply to decompression. ExpActn() has the same return values as CmpExp() except that attempting to decompress corrupted data results in a return value of CMPREC_DATA and usys(2000 + err) is called where err is the DLL specific internal code signifying the corruption.
pVOID ExpInit(pCMPRECFNC pfnc)
NINT ExpActn(pVOID context, pCMPRECFNC pfnc, pVOID source, VRLEN slen, pVOID destination, pVRLEN pdlen)
NINT ExpExit(pVOID context, pCMPRECFNC pfnc)