──LINEIN(─┬──────┬──┬────────────────────────┬─)─────
└─name─┘ └─,─┬──────┬──┬────────┬─┘
└─line─┘ └─,count─┘
LINEIN returns count (0 or 1) lines read from the character input stream name. The form of the name is implementation dependent. If name is omitted, the line is read from the default input stream, STDIN: in OS/2. The default count is 1.
For persistent streams, a read position is maintained for each stream. In the OS/2 operating system, this is the same as the write position. Any read from the stream starts at the current read position by default. A call to LINEIN will return a partial line if the current read position is not at the start of a line. When the read is completed, the read position is moved to the beginning of the next line. The read position may be set to the beginning of the stream by giving line a value of 1- the only valid value for line in OS/2.
If a count of 0 is given, then no characters are read and the null string is returned.
For transient streams, if a complete line is not available in the stream, then execution of the program will normally stop until the line is complete. If, however, it is impossible for a line to be completed due to an error or other problem, the NOTREADY condition is raised and LINEIN returns whatever characters are available.
Here are some examples:
LINEIN() /* Reads one line from the */
/* default input stream; */
/* normally this is an entry */
/* typed at the keyboard */
myfile = 'ANYFILE.TXT'
LINEIN(myfile) -> 'Current line' /* Reads one line from */
/* ANYFILE.TXT, beginning */
/* at the current read */
/* position. (If first call, */
/* file is opened and the */
/* first line is read.) */
LINEIN(myfile,1,1) ->'first line' /* Opens and reads the first */
/* line of ANYFILE.TXT (if */
/* the file is already open, */
/* reads first line); sets */
/* read position on the */
/* second line. */
LINEIN(myfile,1,0) -> '' /* No read; opens ANYFILE.TXT */
/* (if file is already open, */
/* sets the read position to */
/* the first line). */
LINEIN(myfile,,0) -> '' /* No read; opens ANYFILE.TXT */
/* (no action if the file is */
/* already open). */
LINEIN("QUEUE:") -> 'Queue line' /* Read a line from the queue; */
/* If the queue is empty, the */
/* program waits until a line */
/* is put on the queue. */
┴╓: If the intention is to read complete lines from the default character stream, as in a simple dialogue with a user, use the PULL or PARSE PULL instructions instead for simplicity and for improved programmability. The PARSE LINEIN instruction is also useful in certain cases.