LINEOUT

 ──LINEOUT(─┬──────┬──┬─────────────────────────┬─)─────
              └─name─┘  └─,─┬────────┬──┬───────┬─┘
                            └─string─┘  └─,line─┘

LINEOUT returns the count of lines remaining after attempting to write string to the character output stream name. The count is either 0 (meaning the line was successfully written) or 1 (meaning that an error occurred while writing the line). string can be the null string, in which case only the action associated with completing a line is taken. LINEOUT adds a line-feed and a carriage-return character to the end of string.

The form of the name is implementation dependent. If name is omitted, the line is written to the default output stream, STDOUT: (normally the display) in OS/2.

For persistent streams, a write position is maintained for each stream. In the OS/2 operating system, this is the same as the read position. Any write to the stream starts at the current write position by default. Characters written by a call to LINEOUT can be added to a partial line. LINEOUT conceptually terminates a line at the end of each call. When the write is completed, the write position is set to the beginning of the line following the one just written. The initial write position is the end of the stream, so that calls to LINEOUT normally append lines to the end of the stream.

You can set the write position to the first character of a persistent stream by giving a value of 1 (the only valid value) for line.

┴╓: In some environments, overwriting a stream using CHAROUT or LINEOUT can erase (destroy) all existing data in the stream. This is not, however, the case in the OS/2 environment.

You can omit the string for persistent streams. If you specify line, the write position is set to the beginning of the stream, but nothing is written to the stream, and 0 is returned. If you specify neither line nor string, the write position is set to the end of the stream. This use of LINEOUT has the effect of closing the stream in environments (such as the OS/2 environment) that support this concept.

Execution of the program normally stops until the output operation is effectively completed. If, however, it is impossible for a line to be written, the NOTREADY condition is raised and LINEOUT returns with a result of 1 (that is, the residual count of lines written).

Here are some examples:

LINEOUT(,'Display this')    /* Writes string to the default   */
                            /* output stream (normally, the   */
                            /* display); returns 0 if         */
                            /* successful                     */

myfile = 'ANYFILE.TXT'
LINEOUT(myfile,'A new line')  /* Opens the file ANYFILE.TXT and */
                              /* appends the string to the end. */
                              /* If the file is already open,   */
                              /* the string is written at the   */
                              /* current write position.        */
                              /* Returns 0 if successful.       */

LINEOUT(myfile,'A new start',1)/* Opens the file (if not already */
                               /* open); overwrites first line   */
                               /* with a new line.               */
                               /* Returns 0 if successful.       */

LINEOUT(myfile,,1)            /* Opens the file (if not already */
                              /* open). No write; sets write    */
                              /* position at first character.   */

LINEOUT(myfile)               /* Closes ANYFILE.TXT             */

LINEOUT is often most useful when called as a subroutine. The return value is then available in the variable RESULT. For example:

Call LINEOUT 'A:rexx.bat','Shell',1
Call LINEOUT ,'Hello'

┴╓: If the lines are to be written to the default output stream without the possibility of error, use the SAY instruction instead.

---

[Back: LINEIN]
[Next: LINES]