texttobinary( function

texttobinary(

TEXT

ENCODING

)

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

Parameters

This function has two parameters:

text – text to convert to binary data.

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. If the encoding value is preceded by the word lossy (for example "lossy MacOSRoman") then lossy conversion is allowed (see below for more information about lossy conversion).

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 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 ordinary text into binary data. This function is normally only used when you want to export text from Panorama to some other program or computer. (Note: To simply convert a single character to its equivalent numeric value, use the asc( function.)

radixstr("hex",texttobinary("abc™")) ☞ 616263E284A2

As this example shows, one character in the input text may convert to two or more bytes in the output text. In this case, the trademark symbol actually converts to three bytes:

a ☞ 61
b ☞ 62
c ☞ 63
™ ☞ E284A2

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

radixstr("hex",texttobinary("abc™","MacOS Roman")) ☞ 616263AA

With this encoding, the trademark symbol converts to a single byte:

a ☞ 61
b ☞ 62
c ☞ 63
™ ☞ AA

Most encodings can only handle a small subset of all available characters. For example the ASCII encoding (1) can handle only the basic 96 characters (7 bit) included in the original ASCII standard, no accented or special characters. If your text includes characters that are not available in the output encoding, the result will be an empty binary value. In this example because there is one unsupported character (trademark), the entire output is blank.

radixstr("hex",texttobinary("abc™","ASCII")) ☞

If you specify lossy encoding then the output will include all characters that can be converted, leaving out any that are not available in the specified encoding. To specify lossy mode, put the word lossy in front of the encoding name.

radixstr("hex",texttobinary("abc™","lossy ascii")) ☞ 616263

In this example the trademark symbol is skipped (hence lossy encoding) but abc is included in the output data.

a ☞ 61
b ☞ 62
c ☞ 63
™ ☞ AA

If you are specifying the encoding numerically, make the encoding value negative for lossy encoding. Since the value for ASCII encoding is 1, use -1 for lossy ASCII encoding.

radixstr("hex",texttobinary("abc™",-1)) ☞ 616263

How do you know what encoding to use? It depends on what you plan to do with the binary data. 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. (You can use either the name or the value.)

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

texttobinary( function encoding parameter is an invalid encoding type. – See above for a list of legal values for the encoding parameter.

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

See Also

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.
binarytotext( -- converts binary data into text, optionally using a specified encoding.
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
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).
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.