OS/2 Procedures Language 2/REXX


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


CHAROUT




 >>--CHAROUT(-+------+--+--------------------------+-)-----><
              +-name-+  +-,-+--------+--+--------+-+
                            +-string-+  +-,start-+

CHAROUT returns the count of characters remaining after attempting to 
write string to the character output stream name. The form of the name is 
implementation dependent. If name is omitted, characters in string will be 
written to the default output stream, STDOUT: (normally the display) in 
the OS/2 operating system. string can be the null string, in which case no 
characters are written to the stream and 0 is always returned. 
For persistent streams, a write position is maintained for each stream. In 
the OS/2 implementation, this is the same as the read position. Any write 
to the stream starts at the current write position by default.  When the 
write is completed the write position is increased by the number of 
characters written.  The initial write position is the end of the stream, 
so that calls to CHAROUT normally append to the end of the stream. 
A start value can be given to specify an explicit write position for a 
persistent stream. This write position must be a positive whole number 
within the bounds of the stream (though it can specify the character 
position immediately after the end of the stream). A value of 1 for start 
refers to the first character in the stream. 
Note:    In some environments, overwriting a stream with CHAROUT or 
         LINEOUT can erase (destroy) all existing data in the stream. 
         However, this is not the case in the OS/2 environment. 
 
 The string can be omitted for persistent streams. In this case, the write 
 position is set to the value of start that was given, no characters are 
 written to the stream, and 0 is returned. If neither start nor string are 
 given, the write position is set to the end of the stream. This use of 
 CHAROUT can also have the side effect of closing or fixing the file in 
 environments which support this concept.  Again, 0 is returned. If you do 
 not specify start or string, the stream is closed. Again, 0 is returned. 
 Processing of the program normally stops until the output operation is 
 effectively complete. If, however, it is impossible for all the 
 characters to be written, the NOTREADY condition is raised and CHAROUT 
 returns with the number of characters that could not be written (the 
 residual count). 
 Here are some examples: 

 CHAROUT(myfile,'Hi')     ->   0   /* normally */
 CHAROUT(myfile,'Hi',5)   ->   0   /* normally */
 CHAROUT(myfile,,6)       ->   0   /* now at char 6 */
 CHAROUT(myfile)          ->   0   /* at end of stream */
 CHAROUT(,'Hi')           ->   0   /* normally */
 CHAROUT(,'Hello')        ->   2   /* maybe */
 
 
 Note:    This routine is often best called as a subroutine. The residual 
          count is then available in the variable RESULT. 
 For example: 

 Call CHAROUT myfile,'Hello'
 Call CHAROUT myfile,'Hi',6
 Call CHAROUT myfile
 
   

Inf-HTML End Run - Successful