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.

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


History

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