7.4.15. CHAROUT (Character Output)

Returns the count of characters remaining after attempting to write string to the character output stream name. (To understand the input and output functions, see Chapter 14, Input and Output Streams.) If you omit name, characters in string are written to STDOUT (generally the display), which is the default output stream. The string can be a 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. Any write to the stream starts at the current write position by default. When the language processor completes writing, the write position is increased by the number of characters written. When the stream is first opened, the write position is at the end of the stream so that calls to CHAROUT append characters to the end of the stream.

You can give a start value to specify an explicit write position for a persistent stream. This write position must be a positive whole number. A value of 1 for start refers to the first character in the stream.

You can omit the string 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 you do not specify start or string, the stream is closed and 0 is returned.

Execution of the program usually stops until the output operation is 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 all the characters to be written, the NOTREADY condition is raised (see Section 14.5, “Errors during Input and Output”) and CHAROUT returns with the number of characters that could not be written (the residual count).

Here are some examples:

Example 7.21. Builtin function CHAROUT

CHAROUT(myfile,"Hi")     -->   0   /* typically        */
CHAROUT(myfile,"Hi",5)   -->   0   /* typically        */
CHAROUT(myfile, ,6)      -->   0   /* now at char 6    */
CHAROUT(myfile)          -->   0   /* at end of stream */
CHAROUT(,"Hi")           -->   0   /* typically        */
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:

Example 7.22. Builtin function CHAROUT

Call CHAROUT myfile,"Hello"
Call CHAROUT myfile,"Hi",6
Call CHAROUT myfile