<doc>
  <legacy_id>1952</legacy_id>
  <name>read from file</name>
  <type>command</type>
  <syntax>
    <example>read from {file<i> pathName</i> | stdin} [at <i>start</i>] {until {<i>string</i> | end | EOF | empty} | for <i>amount</i> [<i>chunkType</i>]} [in <i>time</i>]</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
  </classification>
  <references>
    <command tag="close file">close file Command</command>
    <constant tag="CRLF">CRLF Constant</constant>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
    <disk access="???"/>
  </security>
  <summary>Takes data from a <keyword tag="file">file</keyword> that has been opened with the <command tag="open file">open file</command> <glossary tag="command">command</glossary>, and places the data in the <keyword tag="it">it</keyword> <glossary tag="variable">variable</glossary>.</summary>
  <examples>
    <example>read from file "Test" for 8 <i>-- reads 8 characters</i></example>
    <example>read from file "COM1:" at 20 until EOF</example>
    <example>read from file (field "Datafile") at -100 for charsToRead</example>
    <example>read from stdin for 1 line</example>
  </examples>
  <description>
    <p>Use the <b>read from file</b> <glossary tag="command">command</glossary> to get data from a <keyword tag="file">file</keyword>.</p><p/><p><b>Parameters:</b></p><p>The <i>pathName</i> specifies the <glossary tag="file path">name and location</glossary> of the <keyword tag="file">file</keyword> 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 file">open file</command> command.</p><p/><p><img src="202653"/> <b>Important!</b> The <i>pathName</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 file">open file</command> <glossary tag="command">command</glossary>.</p><p/><p>If you specify the name of a serial port on Mac OS or Windows systems, LiveCode reads from the specified port. The names of serial ports end in a colon (:).</p><p/><p>The <i>start</i> specifies the <keyword tag="character">character</keyword> or <glossary tag="byte">byte</glossary> position in the <keyword tag="file">file</keyword> where you want to begin reading. A positive number begins <i>start</i> <keyword tag="characters">characters</keyword> after the beginning of the <keyword tag="file">file</keyword>; a <glossary tag="negative">negative</glossary> number begins <i>start</i> <keyword tag="characters">characters</keyword> before the end of the <keyword tag="file">file</keyword>.</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 <keyword tag="file">file</keyword>, it stops reading. If the <i>string</i> is not encountered, the <b>read from file</b> <glossary tag="command">command</glossary> continues reading until it reaches the end of the <keyword tag="file">file</keyword>.</p><p/><p>If you specify any of EOF, end, or empty, the read continues reading until it reaches the end of the file. (If you're reading from a serial port, you must use the form read from file <i>portname</i> until empty.)</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 file</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 from the <keyword tag="file">file</keyword>.</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 file to read from must be opened first with the <b>open file</b> <glossary tag="command">command</glossary>, and the mode the <keyword tag="file">file</keyword> was opened in must be either read or update. If the file is not open or is open write-only, the <function tag="result">result</function> <control_st tag="function">function</control_st> is set to "File is not open for read.".</p><p/><p>If you don't specify a <i>start</i>, LiveCode begins at the position determined by the <command tag="seek">seek</command> <glossary tag="command">command</glossary>, or wherever the last <b>read from file</b> or <command tag="write to file">write to file</command> <glossary tag="command">command</glossary> to that <keyword tag="file">file</keyword> left off, or at the first <keyword tag="character">character</keyword>, if the <keyword tag="file">file</keyword> has not been accessed since being opened, or at the last <keyword tag="character">character</keyword>, if the <keyword tag="file">file</keyword> was opened in append mode.</p><p/><p>The until <i>string</i> form reads data until the specified string is encountered. The until end, until EOF, and until empty forms are synonyms, and read data up to the end of the file. You can read an entire <keyword tag="file">file</keyword> by opening it and reading until the end:</p><p/><p>  open file fileToRead</p><p>  read from file fileToRead until EOF</p><p>  close file fileToRead</p><p/><p>The read from stdin form reads from the standard input (on Unix systems). The standard input is always open, so you can read from it without first opening it.</p><p/><p>The data is placed in the <b>it</b> variable 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 <keyword tag="file">file</keyword>.</p><p/><p>If the <b>read from file</b> <glossary tag="command">command</glossary> encounters the end of the <keyword tag="file">file</keyword>, the <function tag="result">result</function> <control_st tag="function">function</control_st> is set to "eof". If the command was successful and did not encounter the end of the <keyword tag="file">file</keyword>, the <b>result</b> <control_st tag="function">function</control_st> is set to empty.</p><p/><p><img src="202651"/> <b>Tip:</b>  As an alternative to the <command tag="open file">open file</command> and  <b>read from file</b> <glossary tag="command">commands</glossary>, you can also use the <keyword tag="URL">URL</keyword> <glossary tag="keyword">keyword</glossary> with <command tag="get">get</command> and other <glossary tag="command">commands</glossary> to access the contents of a <keyword tag="file">file</keyword>.</p>
  </description>
</doc>