7.4.40. LINEIN (Line Input)

Returns count lines read from the character input stream name. The count must be 1 or 0 (To understand the input and output functions, see Chapter 14, Input and Output Streams.) If you omit name, the line is read from the default input stream, STDIN. The default count is 1.

For persistent streams, a read position is maintained for each stream. Any read from the stream starts at the current read position by default. Under certain circumstances, a call to LINEIN returns a partial line. This can happen if the stream has already been read with the CHARIN function, and part but not all of a line (and its termination, if any) has already been read. When the language processor completes reading, the read position is moved to the beginning of the next line.

A line number may be given to set the read position to the start of a specified line. This line number must be positive and within the bounds of the stream, and must not be specified for a transient stream. The read position can be set to the beginning of the stream by giving line a value of 1.

If you give a count of 0, then no characters are read and a null string is returned.

For transient streams, if a complete line is not available in the stream, then execution of the program usually stops until the line is complete. If, however, it is impossible for a line to be completed because of an error or another problem, the NOTREADY condition is raised (see Section 14.5, “Errors during Input and Output”) and LINEIN returns whatever characters are available.

Here are some examples:

Example 7.52. Builtin function LINEIN

LINEIN()                             /* Reads one line from the    */
                                     /* default input stream;      */
                                     /* usually 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.        */

Note

If you want to read complete lines from the default input stream, as in a dialog with a user, use the PULL or PARSE PULL instruction.

The PARSE LINEIN instruction is also useful in certain cases.