UCM

Uncompress Data

This string function returns the uncompressed version of another string, which was compressed, into the format specified in the DCM function.

Syntax

UCM ( string-expression [,ERR=line-ref|,ERC=error-code])

string-expression

is any string of compressed data following the format used by the DCM function as described below.

line-ref

is the program line number or label to branch to if an error is produced by this function.

error-code

is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

This function is generally available starting with release level 8.1.

The string-expression is evaluated, left to right, for character packets, which specify groups of like and unlike characters. This function then expands those packets of like characters into their full length, removes all control bytes for both like and unlike character packets, and builds a single string.

If an illegal compression format is detected, an ERR=20 results.

If string-expression results in a string whose length exceeds available memory for this task, an ERR=33 results.

The format expected in string-expression is:

1 - 2

The first two bytes contain the length, in binary, of the packet immediately following.

3 - n

If the left-most bit is set (the sign bit) then the packet contains unlike characters and the value of the first two bytes (minus the sign bit) is the length of that packet.

If the sign bit of these two bytes is zero, then the two bytes represent the length of a multiple-occurrence character. This character is found in the next byte after the two-byte length. The string returned by this function contains that character, for the number of bytes specified in the two-byte length, at this point in the string.

The first packet is followed by subsequent packets for the length of string-expression.

The simplest way to create the properly formatted string-expression is through the use of the DCM function.

Examples

LET EXPANDED_STRING$ = UCM ( $00 04 41 80 05 42 43 44 45 46 00 05 47$ )

processes the hexadecimal string shown as follows:

$00 04$ indicates a packet of like characters ($00$ has a zero sign bit) that is 4 bytes long. The following $41$ is the character “A”. So, “AAAA” is specified as $00 04 41$.

$80 05$ indicates a packet of unlike characters (sign bit set) that is 5 bytes long; the following 5 bytes, $42 43 44 45 46$, represent the string “BCDEF”.

$00 05$ defines a like-character packet of 5 bytes whose character value is $47$, a “G”.

The total resultant string returned in this example is 14 bytes long and contains the value “AAAABCDEFGGGGG”.

See also

DCM function

From the Thoroughbred Basic Language Reference, Volume III: R–Z, version 8.9.1. Open this page in the PDF