COMPRESS

Compress a data string

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall COMPRESS(control, dest, source, length)

Arguments

control

The compress control flag. (n)

D_COMP = 1 Compress

D_UNCOMP = 2 Uncompress

DR_COMP = 3 Raw compress

DR_UNCOMP = 4 Raw uncompress

dest

The data area where the resulting data string is stored. (a)

source

The data area containing the data string to compress or uncompress. (a)

length

Returned with the resulting length of the operation or ‑1 on compression failure. (n)

Discussion

D_COMP and DR_COMP compress the data record specified by source for the length of source and store the result in the data record specified by dest. The D_COMP form encodes the length of the uncompressed record and stores it at the beginning of the compressed record as a two‑byte portable integer. The raw form, DR_COMP, does not store the length. The size of dest must be at least three bytes larger than source using D_COMP and at least one byte larger using DR_COMP.

D_UNCOMP and DR_UNCOMP uncompress the compressed data record specified by source, provided the same form was used to compress the data. If the raw form is used, the length of dest is used as the exact length of the uncompressed record.

Dest is not blank‑filled if its length is larger than the resulting data string. The size of dest must be greater than or equal to the size of the uncompressed record on D_UNCOMP and equal to the size of the uncompressed record on DR_UNCOMP.

The returned length is the length of the compressed data record on D_COMP/DR_COMP and the length of the uncompressed data record on D_UNCOMP/DR_UNCOMP.

If the uncompress fails due to invalid compression codes or an invalid dest length in the raw form, the returned length is set to ‑1 and dest is loaded with the incomplete uncompressed record up to the failure.

Examples

The following routines write and read compressed records to a file.

subroutine write_compressed
    a_chn       ,d
    a_rec       ,a
record
    cmprec      ,a MAXRECSZ+3
    clen        ,i2
proc
    xcall compress(D_COMP, cmprec, a_rec, clen)
    puts(a_chn, ^a(clen))               ;See %CNV_IP to make clen portable
    puts(a_chn, cmprec(1:clen))
    xreturn
endsubroutine
subroutine read_compressed
    a_chn       ,d
    a_rec       ,a
    a_len       ,d                      ;Returned record length
record
    cmprec      ,a MAXRECSZ
    clen        ,i2
proc
    gets(a_chn, cmprec(1:clen))
    xcall compress(D_UNCOMP, a_rec, cmprec, a_len)
    if (a_len .eq. -1)
      writes(1, "Compression failure - D_UNCOMP")
    xreturn
endsubroutine