OS/2 Procedures Language 2/REXX


Inf-HTML [About][Toc][Index] 0.9b (c) 1995 Peter Childs


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. 
Note:    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'
 
 
 Note:    If the lines are to be written to the default output stream 
          without the possibility of error, use the SAY instruction 
          instead. 
   

Inf-HTML End Run - Successful