──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.
┴╓: 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 */
┴╓: 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