Caché ObjectScript Reference
$ZWUNPACK and $ZWBUNPACK
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Unpacks a single 16-bit character to two 8-bit characters.
Synopsis
$ZWUNPACK(string)

$ZWBUNPACK(string)
Parameter
string A string consisting of one or more 16-bit characters.
Description
$ZWUNPACK is a function that takes one or more two-byte wide characters and “unpacks” them, returning the corresponding pairs of single-byte characters in little endian order.
$ZWBUNPACK performs the same task, but the two-byte wide characters are unpacked 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 should consist entirely of 16-bit wide characters created using $ZWPACK or $ZWBPACK. The empty string is permitted, and returns the empty string. string should not contain any 16-bit Unicode characters, or any 8-bit characters.
You can use $ZISWIDE on string to check that it contains multibyte characters. However, you must use $ZISWIDE on each character to ensure that the string does not contain a mix of 16-bit and 8-bit characters. $ZISWIDE does not distinguish between Unicode and packed 16-bit characters.
Examples
Note that the following examples require a Unicode installation of Caché.
The following example unpacks a string (“ABCD”) that was packed using $ZWPACK. It unpacks two 16-bit wide characters into four 8-bit characters. Note the little-endian order of the bytes in the wide characters of the packed string: hexadecimal 4241 4443.
   IF $SYSTEM.Version.IsUnicode() {
   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
   }
   ELSE {WRITE "This example requires a Unicode installation of Caché"}
 
The following example performs the same operation as the previous example, but uses big-endian order. Note the big-endian order of the bytes in the wide characters of the packed string: hexadecimal 4142 4344.
   IF $SYSTEM.Version.IsUnicode() {
   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
   }
   ELSE {WRITE "This example requires a Unicode installation of Caché"}
 
The following example shows what happens when you “unpacks” a string of 8-bit characters. Note that the unpacking operation assumes each character to be a 16-bit wide character, and thus supplies the missing eight bits as hexadecimal 00. This use of $ZWUNPACK is not recommended.
   IF $SYSTEM.Version.IsUnicode() {
   SET str=$CHAR(65,66,67)
   WRITE !,$LENGTH(str)," characters: ",str
   SET nstr=$ZWUNPACK(str)
   WRITE !,$LENGTH(nstr)," unpacked characters:"
   ZZDUMP nstr
   }
   ELSE {WRITE "This example requires a Unicode installation of Caché"}
 
The following example shows what happens when you “unpacks” a string of 16-bit Unicode characters; in this case, lowercase Greek letters. This use of $ZWUNPACK is not recommended.
   IF $SYSTEM.Version.IsUnicode() {
   SET str=$CHAR(945,946,947)
   WRITE !,$LENGTH(str)," characters: ",str
   SET nstr=$ZWUNPACK(str)
   WRITE !,$LENGTH(nstr)," unpacked characters: ",nstr
   ZZDUMP nstr
   }
   ELSE {WRITE "This example requires a Unicode installation of Caché"}
 
See Also