7.4.40. LINEOUT (Line Output)


>>-LINEOUT(--+------+--+--------------------------+--)---------><
             +-name-+  +-,--+--------+--+-------+-+
                            +-string-+  +-,line-+

Returns 0 if successful in writing string to the character output stream name, or 1 if an error occurs while writing the line. (To understand the input and output functions, see Chapter 14, Input and Output Streams.) If you omit string but include line, only the write position is repositioned. If string is a null string, LINEOUT repositions the write position (if you include line) and does a carriage return. Otherwise, the stream is closed. LINEOUT adds a line-feed and a carriage-return character to the end of string.

If you omit name, the line is written to the default output stream STDOUT (usually the display).

For persistent streams, a write position is maintained for each stream. Any write to the stream starts at the current write position by default. (Under certain circumstances the characters written by a call to LINEOUT can be added to a partial line previously written to the stream with the CHAROUT routine. LINEOUT stops a line at the end of each call.) When the language processor completes writing, the write position is set to the beginning of the line following the one just written. When the stream is first opened, the write position is at the end of the stream, so that calls to LINEOUT append lines to the end of the stream.

You can specify a line number to set the write position to the start of a particular line in a persistent stream. This line number must be positive and within the bounds of the stream unless it is a binary stream (though it can specify the line number immediately after the end of the stream). A value of 1 for line refers to the first line in the stream. Note that, unlike CHAROUT, you cannot specify a position beyond the end of the stream for non-binary streams.

You can omit the string for persistent streams. If you specify line, the write position is set to the start of the line that was given, nothing is written to the stream, and the function returns 0. If you specify neither line nor string, the stream is closed. Again, the function returns 0.

Execution of the program usually stops until the output operation is effectively complete. For example, when data is sent to a printer, the system accepts the data and returns control to Rexx, even though the output data might not have been printed. Rexx considers this to be complete, even though the data has not been printed. If, however, it is impossible for a line to be written, the NOTREADY condition is raised (see Section 14.5, “Errors during Input and Output”), and LINEOUT returns a result of 1, that is, the residual count of lines written.

Here are some examples:

Example 7.53. Builtin function LINEOUT

LINEOUT(,"Display this")          /* Writes string to the default   */
                                  /* output stream (usually, 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:

Example 7.54. Builtin function LINEOUT call

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

Note

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