binarytotext( function

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 to 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

Note: The binarytotext( function is for binary values, not numeric values. If you want to convert a numeric value to a single character of text, use the chr( function.

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

asc( -- converts the first character of a text string into a number from 0 to 65535 based on Unicode encoding.
bigendianbinaryvalue( -- converts big endian binary data (a byte, word, or longword) into an unsigned number (see Binary Data).
Binary Data -- Panorama allows a formula or procedure to work with raw binary data.
binarydatabuild( -- builds a binary value by scanning a database and assembling individual binary values for every record (including unselected records) in the database.
binaryvalue( -- converts binary data (a byte, word, longword, or longlongword) into a number (see Binary Data).
byte( -- converts a number into a single byte of binary data (see Binary Data).
bytearray( -- extracts a value from an array of bytes (see [Binary Data]).
bytepattern( -- converts a byte count to text: 543 Bytes, 543 Kb, 123 Mb, 3.2 Gb
chr( -- converts a number into a single character of text, based on Unicode encoding.
chunkarray( -- extracts a binary "chunk" from binary data (see Binary Data).
Data Arrays -- A numbered collection of data values.
Data Dictionaries -- Overview of Panorama's key/value data dictionaries.
hex( -- converts a text item containing a hexadecimal number into a standard number (decimal).
hexbyte( -- converts a limited range of decimal numbers to a two-digit hexadecimal number expressed as a text string.
hexlong( -- converts a decimal number to an eight-digit hexadecimal number expressed as a text string
hexstr( -- converts a number to text formatted as a hexadecimal number.
hextobinary( -- converts a sequence of hexadecimal digits into a raw binary data value.
hexword( -- converts a decimal number to a four-digit hexadecimal number expressed as a text string.
littleendianbinaryvalue( -- converts little endian binary data (a byte, word, longword, or longlongword) into an unsigned number (see Binary Data).
longlongword( -- converts a number into a 64 bit longword (8 bytes) of binary data (see Binary Data).
longlongwordarray( -- extracts a value from an array of 64 bit longlongwords (see [Binary Data]).
longword( -- converts a number into a 32 bit longword (4 bytes) of binary data (see Binary Data).
longwordarray( -- extracts a value from an array of 32 bit longwords (see [Binary Data]).
radix( -- converts a text item containing a number in a radix between 2 and 36 into a decimal number.
radixstr( -- converts a number into a text item containing the equivalent number in a radix between 2 and 36.
signedbinaryvalue( -- converts binary data (a byte, word, longword, or longlongword) into a signed number (see Binary Data).
texttobinary( -- converts text into binary data, optionally using a specified encoding.
word( -- converts a number into a single word (2 bytes) of binary data (see Binary Data).
wordarray( -- extracts a value from an array of 16 bit words (see Binary Data).

History

Version	Status	Notes
10.0	New	Support for binary data, as well as text encodings, is new in this version.