<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>