Command: read

Syntax

read <channel> {,<ident> ... }

Description

Read identifier values from a system input channel.

Parameters

• <channel>
  A channel identifier, which should be currently open.

• <ident>
  The identifier(s) whose values are to be read from <channel>. They must already exist.

Switches

• -del=<string>
  Define the delimiter between fields on an input line. <string> may be a one or two character string, containing a delimiting character and optionally a space to indicate that white space is also permitted. If this switch is omitted the default delimiter for the channel is used, or if no channel delimiter has been set, ', ' is assumed, i.e a comma and/or white space. Any occurrences of the delimiter within pairs of double quotes are treated as data not as delimiters.

• -h
  Treat comment lines (beginning with '#') as bona fide input lines. The default is to ignore comment lines.

• -k
  If there is not enough data on an input line to satisfy the identifier list, keep reading lines until all identifiers have been satisfied.

• -l
  When reading the values, take the value of a string identifier as the whole input line.

• -q
  Quiet mode. If there is an end-of-file encountered during the read, do not print an error message.

Notes

The read command may only be used on channels opened for reading, i.e. modes r and rw.

If there are no identifiers specified on the command line, a line will be read from <channel> and its contents discarded.

If the data on <channel> is exhausted, an error will be recorded. This may be tested using the channel structure member channel.eof.

If <channel> is connected to an external process, lines read from <channel> beginning with a | character are interpreted as command lines and executed. The read command will then continue to be executed until a line not beginning with a | is read.

If the last character in a file is a backslash character, it is treated as a line continuation character.

The system will wait until the read has been satisfied. A time-out can be set to prevent a never-ending block, in which case when the time is up the read will be aborted without reading anything. The time-out is set via the channel.timeout structure element. A time-out of 0, the default for new channels, implies no time-out.

Examples

Read two numerics.

numeric x,y
read chan1,x,y

Read a complete line into a string identifier.

string s<
read ch,s,-l,-h
if (ch.eof) !We have run out of stuff

See Also