<doc>
  <legacy_id>1784</legacy_id>
  <name>read from process</name>
  <type>command</type>
  <syntax>
    <example>read from process <i>processName</i> [at <i>start</i>] {until {<i>strin</i>g | empty | end | EOF} | for<i> amoun</i>t <i>[chunkTyp</i>e]} [in<i> time</i>]</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>The System Environment</category>
  </classification>
  <references>
    <command tag="read from driver">read from driver Command</command>
    <command tag="close process">close process Command</command>
    <constant tag="EOF">EOF Constant</constant>
    <keyword tag="int1">int1 Keyword</keyword>
    <keyword tag="int2">int2 Keyword</keyword>
    <keyword tag="int4">int4 Keyword</keyword>
    <command tag="open process">open process Command</command>
    <function tag="openProcesses">openProcesses Function</function>
    <command tag="write to process">write to process Command</command>
    <keyword tag="real8">real8 Keyword</keyword>
    <keyword tag="uInt1">uInt1 Keyword</keyword>
    <keyword tag="uInt2">uInt2 Keyword</keyword>
    <keyword tag="stdin">stdin Keyword</keyword>
    <keyword tag="uInt4">uInt4 Keyword</keyword>
    <keyword tag="real4">real4 Keyword</keyword>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
    <changed version="2.0"></changed>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
  </classes>
  <security>
    <process/>
  </security>
  <summary>Accepts the output of a <glossary tag="process">process</glossary> that was opened with the <command tag="open process">open process</command> <glossary tag="command">command</glossary>, placing the data in the <keyword tag="it">it</keyword> <glossary tag="variable">variable</glossary>.</summary>
  <examples>
    <example>read from process "compileData" for 20</example>
    <example>read from process "/etc/pr" at 2 until linefeed <i>-- skip 2 chars</i></example>
    <example>read from process myProcess for 10 int4s in 250 milliseconds</example>
  </examples>
  <description>
    <p>Use the <b>read from process</b> <glossary tag="command">command</glossary> to get the output data from another program.</p><p/><p><b>Parameters:</b></p><p>The <i>processName</i> specifies the <glossary tag="file path">name and location</glossary> of the <glossary tag="process">process</glossary> you want to read from. It must be the same as the <glossary tag="file path">path</glossary> you used with the <command tag="open process">open process</command>  <glossary tag="command">command</glossary>.</p><p/><p><img src="202653"/> <b>Important!</b> The <i>processName</i> is <href tag="../glossary/casedashsensitive.xml">case-sensitive</href>, even on <glossary tag="platform">platforms</glossary> where file names are not <href tag="../glossary/casedashsensitive.xml">case-sensitive</href>. It must be exactly the same--including the case of characters--as the name you used with the <command tag="open process">open processcommand</command>.</p><p/><p>The <i>start</i> specifies the <keyword tag="character">character</keyword> or <glossary tag="byte">byte</glossary> position in the <glossary tag="process">process</glossary> output where you want to begin reading.</p><p/><p>The <i>string</i> is any <glossary tag="expression">expression</glossary> that <glossary tag="evaluate">evaluates</glossary> to a <keyword tag="string">string</keyword>. When LiveCode encounters the <i>string</i> in the <glossary tag="process">process</glossary> output, it stops reading. If the <i>string</i> is not encountered, the <b>read from process</b> <glossary tag="command">command</glossary> continues reading as long as there is data to be read.</p><p/><p>The <i>amount</i> is a positive <keyword tag="integer">integer</keyword> and specifies how much data to read.</p><p/><p>The <i>chunkType</i> is one of chars, characters, words, items, lines, int1, uInt1, int2, uint2, int4, or uint4. The <b>read from process</b> <glossary tag="command">command</glossary> reads <i>amount</i> of the specified <i>chunkType</i>. If you don't specify a <i>chunkType</i>, <i>amount</i> <keyword tag="characters">characters</keyword> are read.</p><p/><p>The <i>time</i> is the time to wait for the read to be completed, in <function tag="milliseconds">milliseconds</function>, seconds, or <function tag="ticks">ticks</function>.</p><p/><p><b>Comments:</b></p><p>The process to read from must be opened first with the open process <glossary tag="command">command</glossary>, and the mode the <glossary tag="process">process</glossary> was opened in must be read or update. If the process is not running or is write-only, the <function tag="result">result</function> <control_st tag="function">function</control_st> is set to "Process is not open for read.".</p><p/><p>The until <i>string</i> form reads data until the specified string is encountered.  The until <i>end</i> and until <i>eof</i>  forms read data until the process specifies it is finished.  When until <i>empty</i> is used the data is read in at specified time intervals.  If, when checked, the data is empty the <function tag="openProcesses">openProcesses function</function> is used to check whether the process has finished.</p><p/><p>The data is placed in the <glossary tag="variable">it variable</glossary> after reading. If you specified a <glossary tag="binary data">binary data</glossary> <i>chunkType</i> (int1, uInt1, int2, uint2, int4, or uint4), the data consists of a comma-separated list of numbers, one for the numerical value of each chunk that was read. Otherwise, the data is placed in the <keyword tag="it">it</keyword> <glossary tag="variable">variable</glossary> as it appears in the output.</p><p/><p>If the <b>read from process</b> <glossary tag="command">command</glossary> encounters the end of the data output, the <function tag="result">result</function> <control_st tag="function">function</control_st> is set to "eof". If you specify a <i>time</i> and the read is not completed when that time has elapsed, the <function tag="result">result</function> <control_st tag="function">function</control_st> is set to "time out". If the read was successful, the result is set to empty.</p><p/><p><b>Changes:</b></p><p>Support for using the <b>read from process</b> <glossary tag="command">command</glossary> on <glossary tag="OS X">OS X systems</glossary> was added in version 2.0.</p>
  </description>
</doc>