Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions page (login required).

$ZWPACK and $ZWBPACK

Packs two 8-bit characters into a single 16-bit character.

Synopsis

$ZWPACK(string)

$ZWBPACK(string)

Parameter

Argument Description
string A string consisting of two or more 8-bit characters. string must be an even number of characters.

Description

The $ZWPACK function packs a string of 8-bit characters as a string of 16-bit wide characters in little-endian order. Two 8-bit characters are packed into a single 16-bit character.

$ZWBPACK performs the same task, but the 8-bit characters are stored in 16-bit wide characters in big-endian order.

Packing a string is a way to halve the character count of the string for storage and string manipulation. Unpacking restores the original 8-bit character string for display. These operations should not be used when Unicode characters are permitted in the data.

The input string has the following requirements:

  • string must consist of an even number of characters. The empty string is permitted, and returns the empty string. Specifying an odd number of characters results in a <FUNCTION> error.

  • string cannot contain any multibyte characters. You can use $ZISWIDE on string to check that it does not contain multibyte characters. If you use $ZWPACK or $ZWBPACK on a string containing multibyte characters, the system generates a <WIDE CHAR> error.

Examples

Note that the following examples require a Unicode installation of Caché.

The following example shows $ZWPACK packing four 8-bit characters into two 16-bit wide characters. Note the little-endian order of the bytes in the wide characters of the packed string: hexadecimal 4241 4443.

   SET str=$CHAR(65,66,67,68)
   WRITE !,$LENGTH(str)," characters: ",str
   WRITE !,"$ZWPACK"
   SET wstr=$ZWPACK(str)
   WRITE !,$LENGTH(wstr)," packed characters: ",wstr
   ZZDUMP wstr
   WRITE !,"$ZWUNPACK"
   SET nstr=$ZWUNPACK(wstr)
   WRITE !,$LENGTH(nstr)," unpacked characters: ",nstr
Copy code to clipboard

The following example shows $ZWBPACK packing four 8-bit characters into two 16-bit wide characters. Note the big-endian order of the bytes in the wide characters of the packed string: hexadecimal 4142 4344.

   SET str=$CHAR(65,66,67,68)
   WRITE !,$LENGTH(str)," characters: ",str
   WRITE !,"$ZWBPACK"
   SET wstr=$ZWBPACK(str)
   WRITE !,$LENGTH(wstr)," packed characters: ",wstr
   ZZDUMP wstr
   WRITE !,"$ZWBUNPACK"
   SET nstr=$ZWBUNPACK(wstr)
   WRITE !,$LENGTH(nstr)," unpacked characters: ",nstr
Copy code to clipboard

The following example validates string before packing it:

   SET str=$CHAR(65,66,67,68)
   IF $ZISWIDE(str) {
      WRITE !,str," contains wide characters"
      QUIT }
   ELSEIF $LENGTH(str) # 2  {
      WRITE !,str," contains an odd number of characters"
      QUIT }
   ELSE {
      WRITE !,str," passes validation" }
   WRITE !,$LENGTH(str)," characters: ",str
   SET wstr=$ZWPACK(str)
   WRITE !,$LENGTH(wstr)," packed characters: ",wstr
   ZZDUMP wstr
Copy code to clipboard

See Also

Feedback