BinaryDecode

Decodesbinary data and places it into the specified variables.Syntax:

```
binaryDecode(<formatsList>, <data>, <variablesList>)

```

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)

```

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

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

```

Parameters:

* formatsList: The formatsList consists of one or more dataTypes, each followedoptionally by an amount. A dataType is one of the following singleletters: x: skip next amount bytes of data
* data (string): A string of encoded binary data.
* variablesList: A comma-separated list of local or global variable names. The number ofvariable names must be the same as the number of dataTypes specified inthe formatsList, and the variables must already exist.
* amount: a: convert next amount bytes of data to charactersA: convert next amountbytes of data (skipping spaces) to charactersb: convert next amount bitsof data to 1s and 0sB: convert next amount bits of data to 1s and 0s,starting at the high end of each byteh: convert next amount bytes ofdata to hexadecimal digitsH: convert next amount bytes of data tohexadecimal digits, starting at the high end of each bytec: convert nextamount bytes of data to signed 1-byte integersC: convert next amountbytes of data to unsigned 1-byte integerss: convert next amount 2-bytechunks of data to signed integers in host byte orderS: convert nextamount 2-byte chunks of data to unsigned integers in host byte orderi:convert next amount 4-byte chunks of data to signed integers in hostbyte orderI: convert next amount 4-byte chunks of data to unsignedintegers in host byte ordern: convert next amount 2-byte chunks of datato signed integers in network byte orderN: convert next amount 4-bytechunks of data to signed integers in network byte orderm: convert nextamount 2-byte chunks of data to unsigned integers in network byteorderM: convert next amount 4-byte chunks of data to unsigned integersin network byte orderf: convert next amount 4-byte chunks of data to asingle-precision floatd: convert next amount 8-byte chunks of data to adouble-precision floatThe amount corresponding to each dataType is aninteger or the \* character. If no amount is specified, the dataType isused for a single byte of data. The \* character causes the rest of thedata to be converted according to the formatType, so it should appearonly as the last character in the formatsList.]]\*Important:\* If youspecify an amount with a string dataType (a or A), the binaryDecodefunction places amount bytes in the next variable of the variablesList.If you specify an amount with a numeric dataType, the function placesamount chunks of data in the next amount variables of the variablesList.For example, the dataType "a3" requires only one variable, which willhold a 3-characterstring, but the dataType "h3" requires threevariables, each of which will hold a single hex digit.
* Returns: The **binaryDecode** function returns the number of dataTypesthat were successfully converted and placed in variables (notcounting data skipped by the x dataType). The actual data is placed inthe variables, rather than returned by the function.

See also: numToChar (function),format (function),value (function),