(implemented in VERSION 7) System Functions
CMP( ) Compress Data
   
Format CMP(string[,ERR=stmtref])
 
Where:
string Original data to be compressed.
stmtref Program line number or label to which to transfer control.
   
Returns Compressed data string.
   
Description The CMP( ) function uses standard ZLIB compression libraries to compress a data string. To expand (uncompress) the data, use the UCP( ) Function. TCB(195) will return 1 if ZLIB support is available.

The data returned from the CMP( ) function includes a single header byte (value between $01$ and $FF$) to facilitate ZLIB uncompression routines. This represents a multiplier value that can be used against the length of the compressed data to estimate uncompressed data size (basically, original size/compressed size rounded up and capped at 255). When expanding the compressed data using the UCP( ) function, the length of the compressed data will be multiplied by this header byte to determine an estimated uncompressed buffer size.

*Note* Since the CMP( ) and UCP( ) compression routines are not supported on all platforms, systems using these functions or this algorithm may not be fully portable.
  Typically, the compressed data will be smaller than the original data; however, in rare instances or when dealing with short strings, the compressed data might be longer. Also be aware that data returned from the compression logic may contain any potential character; therefore, if writing to a data file, do not use field delimiters since they may occur within the compressed data.

Interfacing with Other ZLIB-compliant Utilities

The header byte should be removed from the compressed data if it is to be used outside of ProvideX.

   
Example

0100 ! ^100 - CMP and UCP functions
0110 Original$=dim(512,"String to compress ")
0120 Compressed$=cmp(Original$)
0130 print "Length of Original: ",'BR',str(len(Original$)),'ER'
0140 print "Original String: ",'BR',Original$,'ER'
0150 print "Length of Compressed:",'BR',str(len(Compressed$)),'ER'
0160 print "Compressed String:",'BR',cvs(Compressed$,16:"~"),'ER'
0170 print
0180 !
0200 ! ^100 - Due to Zlib overhead, not all strings yield smaller strings
0210 for StrLen=16 to 64 step 8
0220 Original$=dim(StrLen,"This is a short string")
0230 Compressed$=cmp(Original$)
0240 o=len(Original$),c=len(Compressed$)
0250 print "Orig:",o," CMP:",c," ",tbl(o>c,'red'+"Not Shorter"+'RM',"")
0260 next

   
See Also UCP( ) UnCompress Data