Error getting tags :
error 404Error getting tags :
error 404 binaryDecode | revDocs | RunRev
Welcome Guest (Log in)
Product Edition
Version
binaryDecode
Basics
Expander triangle
Type
Function
Syntax

binaryDecode(formatsList,data,variablesList)

Introduced
1.0
Environment
Desktop, Web and Server
Platform Support
MacOS,Mac OS X,Windows,Linux
Security
None required
Summary
Decodesbinary data and places it into the specified variables.
Examples

binaryDecode("h","M",theHex) - converts M to its hex equivalent
binaryDecode("a*",receivedData,textData) -- converts data to text
binaryDecode("x12Sh16",picHeader,junk,numColors,colorTable)
binaryDecode(myFormat,placeHolder,importantStuff)

Additional Comments
Expander triangle

Use the binaryDecode function to convert binary data into a form that can be manipulated by handlers.

Parameters:

The formatsList consists of one or more dataTypes, each followed optionally by an amount. A dataType is one of the following single letters:

x: skip next amount bytes of data

a: convert next amount bytes of data to characters

A: convert next amount bytes of data (skipping spaces) to characters

b: convert next amount bits of data to 1s and 0s

B: convert next amount bits of data to 1s and 0s, starting at the high end of each byte

h: convert next amount bytes of data to hexadecimal digits

H: convert next amount bytes of data to hexadecimal digits, starting at the high end of each byte

c: convert next amount bytes of data to signed 1-byte integers

C: convert next amount bytes of data to unsigned 1-byte integers

s: convert next amount 2-byte chunks of data to signed integers in host byte order

S: convert next amount 2-byte chunks of data to unsigned integers in host byte order

i: convert next amount 4-byte chunks of data to signed integers in host byte order

I: convert next amount 4-byte chunks of data to unsigned integers in host byte order

n: convert next amount 2-byte chunks of data to signed integers in network byte order

N: convert next amount 4-byte chunks of data to signed integers in network byte order

m: convert next amount 2-byte chunks of data to unsigned integers in network byte order

M: convert next amount 4-byte chunks of data to unsigned integers in network byte order

f: convert next amount 4-byte chunks of data to a single-precision float

d: convert next amount 8-byte chunks of data to a double-precision float

The amount corresponding to each dataType is an integer or the * character. If no amount is specified, the dataType is used for a single byte of data. The * character causes the rest of the data to be converted according to the formatType, so it should appear only as the last character in the formatsList.

Important! If you specify an amount with a stringdataType (a or A), the binaryDecodefunction places amountbytes in the next variable of the variablesList. If you specify an amount with a numericdataType, the function places amount chunks of data in the next amountvariables of the variablesList. For example, the dataType "a3" requires only one variable, which will hold a 3-characterstring, but the dataType "h3" requires three variables, each of which will hold a single hex digit.

The data is a string of encoded binary data.

The variablesList is a comma-separated list of local or global variable names. The number of variable names must be the same as the number of dataTypes specified in the formatsList, and the variables must already exist.

Value:

The binaryDecode function returns the number of dataTypes that were successfully converted and placed in variables (not counting data skipped by the x dataType).

The actual data is placed in the variables, rather than returned by the function.

Comments:

The binary data format used by binaryDecode is similar to the format produced by the "pack" function of the Perl programming language.

You must declare or otherwise create all variables in the variablesList before using them in the binaryDecode function. Unlike the put command, the binaryDecode function does not automatically create local variables when you use them.

Although the x dataType skips the specified number of bytes rather than converting them, you still must provide a variable for instances of x that appear in the formatsList. The binaryDecode function does not change the value of a variable used for the dataType x.

If the formatsList specifies fewer bytes than are in the data, the binaryDecode function ignores the remaining bytes. If the formatsList specifies more bytes than are in the data, the binaryDecode function converts as many of the dataTypes as there is data for. Check the value that the binaryDecode function returns to determine how much data was actually converted. Here is an example:

on convertStuff dataToConvert

global headerData,placeholder,bodyData,footerData

put binaryDecode("i5x2a24xi2",dataToConvert, \

headerData,placeholder,bodyData,placeholder,footerData) \

into convertResult

if convertResult < 3 then return "Error: data was corrupted"

end convertStuff

User Comments
Expander triangle
User thumbnail
benr_mc@cogapp.com
StarStarStarStarStar
Jul 20, 2009
Documentation is in error at least on the following point: h: convert next amount bytes of data to hexadecimal digits H: convert next amount bytes of data to hexadecimal digits, starting at the high end of each byte
Actually, the 'amount' in these two cases is the number of characters output, not the number of bytes of input converted. So if you have 8 bytes of data, you'll need to specify "h16" to get it all output as hex digits.