Binary functions

Overview

The Binary functions BinaryToHex and HexToBinary are used to convert binary data between its normal binary representation and a printable form consisting of hexadecimal characters. In a hexadecimal representation, two digits from the set (0-9, A-F) are used to represent each byte. Hexadecimal representation is useful for storing binary data in ASCII files. Many databases use hexadecimal representation when displaying binary data from SQL query tools. These functions help you process binary information that was obtained in hexadecimal form.

The "+" operator works for binary values, allowing you to concatenate binary values. Thus

BinaryToHex(HexToBinary("AABB") + HexToBinary("CCDD"))produces "AABBCCDD"

BinaryToHex

Accepts a binary argument and converts it to sequence of hexadecimal digits.

Syntax

BinaryToHex( binary )

Remarks

Each byte is converted to a pair of hexadecimal digits. The first digit in the pair is the high-order four bits of the byte, and the second digit of the pair is the low-order four bits of the byte. This results in a text string that is twice as long as the binary value. This representation is compatible with the binary data formats of many databases, and is useful for moving binary data around in a generic format.

Examples

DecodeBase64

Produces a binary output in which the input text string is decoded from a single base64-encoded line of text without line breaks.

Syntax

DecodeBase64( text )

Remarks

Base64 encoding schemes are commonly used to encode binary data that must be stored and transferred over media designed to deal with textual data, ensuring that the data remains intact without modification during transport. Base64 is commonly used in a number of applications including email via MIME, and storing complex data in XML.

EncodeBase64

Produces a text output in which the input binary value is represented as a single base64-encoded line of text without line breaks.

Syntax

EncodeBase64( binary )

Remarks

Base64 encoding schemes are commonly used to encode binary data that must be stored and transferred over media designed to deal with textual data, ensuring that the data remains intact without modification during transport. Base64 is commonly used in a number of applications including email via MIME, and storing complex data in XML.

DecodeTextBytes

Converts a binary or spatial value to Unicode and returns a text value.

Syntax

DecodeTextBytes( binary, code_page )

Remarks

DecodeTextBytes accepts a binary or spatial value that is presumed to contain text formatted in the specified code_page, which may be obtained from file-writing tools configured as "output to field."  See Code pages for a complete list of code pages.

EncodeTextBytes

Converts a TextVar or Unicode value to binary.

Syntax

EncodeTextBytes( text, code_page )

Remarks

EncodeTextBytes accepts a text value (either TextVar or Unicode) and returns a binary value containing the text represented in the code_page. See Code pages for a complete list of code pages.

GetByte

Extracts a byte from text at position. If there aren't enough bytes, an error value is returned.

Syntax

GetByte(text, position )

Remarks

The argument position is one-based. The return value is an integer between 0 and 255.

Example

GetByte(HexToBinary("AABBCCDD"), 2) returns 204.

HexToBinary

Accepts a text value consisting of a sequence of pairs of hexadecimal digits, and converts it to a binary value.

Syntax

HexToBinary( text )

Remarks

The parameter text must contain an even number of digits. The resulting binary value will be half the size of text.

Examples

SubBinary

Extracts length bytes from binary starting at position. If there aren't enough bytes, a smaller value is extracted; it is not an error.

Syntax

SubBinary( binary, position, length )

Remarks

The argument position is one-based. The return value is binary.

Example

BinaryToHex(SubBinary(HexToBinary("AABBCCDD"), 2, 2)) returns "BBCC".