Skip to content
Thoroughbred Software InternationalThoroughbred Software InternationalThoroughbred DocumentationDocs

DCM

Data Compress

This string function returns the compressed version of another string based on the compression rules below.

Syntax

Section titled “Syntax”
DCM (string-expression [,ERR=line-ref|,ERC=error-code])
string-expression
is any string.
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

Section titled “Remarks”

String-expression is evaluated, left to right, for multiple occurrences of the same character in groups of 4 or more. The resultant string function returns a single string made up of packets of compressed and uncompressed characters as follows:

  • The first two bytes contain the length, in binary, of the packet immediately following. 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 was 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 first packet is followed by subsequent packets for the length of string-expression.

The result of this string compression algorithm can be uncompressed using the UCM function.

Starting with release level 8.9.0, multiple packets will be generated when the length of the string being compressed exceeds 32,767 characters.

Examples

Section titled “Examples”
LET COMPRESSED_STRING$ = DCM ("AAAABCDEFGGGGG")

results in COMPRESSED_STRING$ containing three packets as follows:

  • $00 04 41$ specifies 4 like characters of $41$, the code for an “A”.
  • $80 05 42 43 44 45 46$ specifies 5 unlike characters (“BCDEF”).
  • $00 05 47$ specifies 5 like characters of $47$ (“G”).

Total returned string length is 13 bytes.

LET STR$ = DIM(40000)+”STRING-DATA”
LET DCM$ = DCM(STR$)

results in DCM$ containing three packets as follows:

  • $7FFF 20$ specifies 32,767 like characters of $20$, the code for a space.
  • $1C41 20$ specifies 7,233 like characters of $20$, the code for a space.
  • $800B 535452494E472D44415441$ specifies 11 unlike characters (“STRING-DATA”).

Total returned string length is 19 bytes.

See also

Section titled “See also”

UCM Function

From the Thoroughbred Basic Language Reference, Volume I: A–E, version 8.9.1. Open this page in the PDF