<doc>

<legacy_id>2037</legacy_id>

<name>binaryDecode</name>

<type>function</type>

<syntax>

<example>binaryDecode(<i>formatsList</i>,<i>data</i>,<i>variablesList</i>)</example>

</syntax>

<library></library>

<objects>

</objects>

<synonyms>

</synonyms>

<classification>

</classification>

<references>

<function tag="numToChar">numToChar Function</function>

</references>

<history>

<introduced version="1.0">Added.</introduced>

</history>

<platforms>

<mac/>

<windows/>

<linux/>

<ios/>

<android/>

</platforms>

<classes>

<desktop/>

<server/>

<web/>

<mobile/>

</classes>

<security>

</security>

<summary><glossary tag="decode">Decodesbinary data</glossary> and places it into the specified <glossary tag="variable">variables</glossary>.</summary>

<examples>

<example>binaryDecode("h","M",theHex) - converts M to its hex equivalent</example>

<example>binaryDecode("a*",receivedData,textData) <i>-- converts data to text</i></example>

<example>binaryDecode("x12Sh16",picHeader,junk,numColors,colorTable)</example>

<example>binaryDecode(myFormat,placeHolder,importantStuff)</example>

</examples>

<description>

<p>Use the <b>binaryDecode</b> function to convert <glossary tag="binary data">binary data</glossary> into a form that can be manipulated by <glossary tag="handler">handlers</glossary>.</p><p/><p><b>Parameters:</b></p><p>The <i>formatsList</i> consists of one or more <i>dataTypes</i>, each followed optionally by an <i>amount</i>. A <i>dataType</i> is one of the following single letters:</p><p/><p>x: skip next <i>amount</i> <glossary tag="byte">bytes</glossary> of <i>data</i></p><p>a: convert next <i>amount</i> <glossary tag="byte">bytes</glossary> of <i>data</i> to characters</p><p>A: convert next <i>amount</i> <glossary tag="byte">bytes</glossary> of <i>data</i> (skipping spaces) to characters</p><p>b: convert next <i>amount</i> <glossary tag="bit">bits</glossary> of <i>data</i> to 1s and 0s</p><p>B: convert next <i>amount</i> <glossary tag="bit">bits</glossary> of <i>data</i> to 1s and 0s, starting at the high end of each byte</p><p>h: convert next <i>amount</i> <glossary tag="byte">bytes</glossary> of <i>data</i> to <glossary tag="hexadecimal">hexadecimal</glossary> digits</p><p>H: convert next <i>amount</i> bytes of <i>data</i> to <glossary tag="hexadecimal">hexadecimal</glossary> digits, starting at the high end of each byte</p><p>c: convert next <i>amount</i> bytes of <i>data</i> to signed 1-byte integers</p><p>C: convert next <i>amount</i> bytes of <i>data</i> to unsigned 1-byte integers</p><p>s: convert next <i>amount</i> 2-byte chunks of <i>data</i> to signed <glossary tag="integer">integers</glossary> in host byte order</p><p>S: convert next <i>amount</i> 2-byte chunks of <i>data</i> to unsigned <glossary tag="integer">integers</glossary> in host byte order</p><p>i: convert next <i>amount</i> 4-byte chunks of <i>data</i> to signed <glossary tag="integer">integers</glossary> in host byte order</p><p>I: convert next <i>amount</i> 4-byte chunks of <i>data</i> to unsigned <glossary tag="integer">integers</glossary> in host byte order</p><p>n: convert next <i>amount</i> 2-byte chunks of <i>data</i> to signed <glossary tag="integer">integers</glossary> in network byte order</p><p>N: convert next <i>amount</i> 4-byte chunks of <i>data</i> to signed <glossary tag="integer">integers</glossary> in network byte order</p><p>m: convert next <i>amount</i> 2-byte chunks of data to unsigned integers in network byte order</p><p>M: convert next <i>amount</i> 4-byte chunks of data to unsigned integers in network byte order</p><p>f: convert next <i>amount</i> 4-byte chunks of <i>data</i> to a single-precision float</p><p>d: convert next <i>amount</i> 8-byte chunks of <i>data</i> to a double-precision float</p><p/><p>The <i>amount</i> corresponding to each <i>dataType</i> is an <keyword tag="integer">integer</keyword> or the * <keyword tag="character">character</keyword>. If no <i>amount</i> is specified, the <i>dataType</i> is used for a single <glossary tag="byte">byte</glossary> of data. The * <keyword tag="character">character</keyword> causes the rest of the <i>data</i> to be converted according to the <i>formatType</i>, so it should appear only as the last <keyword tag="character">character</keyword> in the <i>formatsList</i>.</p><p/><p><img src="202653"/> <b>Important!</b> If you specify an <i>amount</i> with a <keyword tag="string">string</keyword> <i>dataType</i> (a or A), the <b>binaryDecode</b> <control_st tag="function">function</control_st> places <i>amount</i> <glossary tag="byte">bytes</glossary> in the next <glossary tag="variable">variable</glossary> of the <i>variablesList</i>. If you specify an <i>amount</i> with a <keyword tag="numeric">numeric</keyword> <i>dataType</i>, the <control_st tag="function">function</control_st> places <i>amount</i> chunks of data in the next <i>amount</i> <glossary tag="variable">variables</glossary> of the <i>variablesList</i>. For example, the <i>dataType</i> "a3" requires only one <glossary tag="variable">variable</glossary>, which will hold a 3-<keyword tag="character">characterstring</keyword>, but the <i>dataType</i> "h3" requires three <glossary tag="variable">variables</glossary>, each of which will hold a single <glossary tag="hexadecimal">hex</glossary> digit.</p><p/><p>The <i>data</i> is a string of <glossary tag="encode">encoded</glossary> <glossary tag="binary data">binary data</glossary>.</p><p/><p>The <i>variablesList</i> is a comma-separated list of <command tag="local">local</command> or <glossary tag="global">global variable</glossary> names. The number of <glossary tag="variable">variable</glossary> names must be the same as the number of <i>dataTypes</i> specified in the <i>formatsList,</i> and the <glossary tag="variable">variables</glossary> must already exist.</p><p/><p><b>Value:</b></p><p>The <b>binaryDecode</b> <control_st tag="function">function</control_st> <glossary tag="return">returns</glossary> the number of <i>dataTypes</i> that were successfully converted and placed in <glossary tag="variable">variables</glossary> (not counting data skipped by the x <i>dataType</i>).</p><p/><p>The actual data is placed in the variables, rather than returned by the function.</p><p/><p><b>Comments:</b></p><p>The binary data format used by <b>binaryDecode</b> is similar to the <function tag="format">format</function> produced by the "pack" function of the Perl programming language.</p><p/><p>You must declare or otherwise create all variables in the <i>variablesList</i> before using them in the <b>binaryDecode</b> <control_st tag="function">function</control_st>. Unlike the <command tag="put">put</command> <glossary tag="command">command</glossary>, the <b>binaryDecode</b> <control_st tag="function">function</control_st> does not automatically create <glossary tag="local variable">local variables</glossary> when you use them.</p><p/><p>Although the x <i>dataType</i> skips the specified number of <glossary tag="byte">bytes</glossary> rather than converting them, you still must provide a <glossary tag="variable">variable</glossary> for instances of x that appear in the <i>formatsList</i>. The <b>binaryDecode</b> <control_st tag="function">function</control_st> does not change the <function tag="value">value</function> of a <glossary tag="variable">variable</glossary> used for the <i>dataType</i> x.</p><p/><p>If the <i>formatsList</i> specifies fewer <glossary tag="byte">bytes</glossary> than are in the <i>data</i>, the <b>binaryDecode</b> <control_st tag="function">function</control_st> ignores the remaining <glossary tag="byte">bytes</glossary>. If the <i>formatsList</i> specifies more <glossary tag="byte">bytes</glossary> than are in the data, the <b>binaryDecode</b> <control_st tag="function">function</control_st> converts as many of the <i>dataTypes</i> as there is data for. Check the <function tag="value">value</function> that the <b>binaryDecode</b> <control_st tag="function">function</control_st> <glossary tag="return">returns</glossary> to determine how much data was actually converted. Here is an example:</p><p/><p> on convertStuff dataToConvert</p><p> global headerData,placeholder,bodyData,footerData</p><p> put binaryDecode("i5x2a24xi2",dataToConvert, \</p><p> headerData,placeholder,bodyData,placeholder,footerData) \</p><p> into convertResult</p><p> if convertResult &lt; 3 then return "Error: data was corrupted"</p><p> end convertStuff</p>

</description>

</doc>