$ZWPACK and $ZWBPACK (ObjectScript)

Synopsis

$ZWPACK(string)

$ZWBPACK(string)

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.

You can use the IsBigEndian()Opens in a new tab class method to determine which bit ordering is used on your operating system platform: 1=big-endian bit order; 0=little-endian bit order.

  WRITE $SYSTEM.Version.IsBigEndian()

Examples

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

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

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

See Also

• $LENGTH function

• $ZISWIDE function

• $ZWUNPACK and $ZWBUNPACK functions