binarytotext(
BINARY
,
ENCODING
)

The binarytotext( function converts binary data into text, optionally using a specified encoding.


Parameters

This function has two parameters:

binary – binary data to convert to text.

encoding – name or numeric value of the encoding scheme used to store the text as binary data. Common encodings include:

ASCII (7 bit)
UTF–8 (Unicode)
MacOSRoman (used by OS 9)

The encoding parameter is optional. If it is omitted, UTF-8 encoding will be used.

Note: Spaces and punctuation in this parameter are ignored, and names may be in either upper or lower case. For example "Mac OS Roman", "MACOSROMAN" and "Macos Roman" will all work for specify Mac OS Roman encoding. You can also specify the encoding numerically, for example 30 for Mac OS Roman. See the table below for a full list of encoding names and numeric values.


Description

This function converts binary data into ordinary text. This function is normally only used when you want to import text into Panorama from some other program or computer.

binarytotext(byte(65)+byte(66)+byte(67)) ☞ ABC
binarytotext(byte(0xE2)+byte(0x84)+byte(0xA2)) ☞     

As this example shows, multiple bytes in the input data may convert to one character in the output text. In this case, the trademark symbol actually converts from three bytes.

There are many different encodings that can be used to store text in binary data. By default, the binarytotext( function encodes text using UTF–8, a variation of unicode. By adding a second parameter to the binarytotext( function you can choose from over a dozen different encoding methods (see full list below). For example, this formula specifies that the binary data is encoded using MacOSRoman, the primary encoding used by OS 9 and by earlier versions of Panorama.

binarytotext(byte(0xAA),"Mac OS Roman") ☞     

With this encoding, the trademark symbol converts from a single byte in the input data.

Not all binary data corresponds to valid text. If the binary data does not contain valid text in the specified encoding the result will be empty text.

binarytotext(byte(65)+byte(66)+byte(67)+byte(0xAA)) ☞ 

Notice that it only takes one invalid byte to cause the entire conversion to fail. In the example above the first three bytes correspond to valid UTF–8 characters, but the final byte does not, so the entire conversion fails. (Unlike the texttobinary( function, there is no lossy option for the binarytotext( function.)

How do you know what encoding to use? It depends on where the binary data came from. Modern OS X and Windows computers use UTF–8, but older software can use a variety of encodings. You may have to do some research and/or trial and error to determine the correct encoding. Here is a list of all of the encodings available:

ASCII = 1
NEXTSTEP = 2
JapaneseEUC = 3
UTF8 = 4
ISOLatin1 = 5
Symbol = 6
NonLossyASCII = 7
ShiftJIS = 8
ISOLatin2 = 9
Unicode = 10
WindowsCP1251 = 11
WindowsCP1252 = 12
WindowsCP1253 = 13
WindowsCP1254 = 14
WindowsCP1250 = 15
ISO2022JP = 21
MacOSRoman = 30
UTF16 = 10
UTF16BigEndian = 2415919360
UTF16LittleEndian = 2483028224
UTF32 = 2348810496
UTF32BigEndian = 2550137088
UTF32LittleEndian = 2617245952
Proprietary = 65536

Error Messages

binarytotext( function binary parameter must be a binary value, not numeric or text. – The first parameter must be a binary data value.

binarytotext( function encoding parameter is an invalid encoding type parameter. – See Panorama Help for a list of legal values for the encoding parameter.


See Also


History

VersionStatusNotes
10.0NewSupport for binary data, as well as text encodings, is new in this version.