3.2.13. CHARIN([streamid][,[start][,length]])

This function will in general read characters from a stream, and
return a string containing the characters read. The streamid
parameter names a particular stream to read from. If it is
unspecified, the default input stream is used.

The start parameter specifies a character in the stream, on which
to start reading. Before anything is read, the current read
position is set to that character, and it will be the first
character read. If start is unspecified, no repositioning will be
done.  Independent of any conventions of the operating system, the
first character in a stream is always numbered 1. Note that
transient streams do not allow repositioning, and an error is
reported if the start parameter is specified for a transient
stream.

The length parameter specifies the number of characters to read.
If the reading did work, the return string will be of length
length. There are no other ways to how many characters were read
than checking the length of the return value. After the read, the
current read position is moved forward as many characters as was
read. If length is unspecified, it defaults to 1. If length is 0,
nothing is read, but the file might still be repositioned if start
was specified.

Note that this function read the stream raw. Some operating
systems use special characters to differ between separate lines in
text files.  On these systems these special characters will be
returned as well.  Therefore, never assume that this function will
behave identical for text streams on different systems.

What happens when an error occurs or the End-Of-File (EOF) is seen
during reading, is implementation dependent. The implementation
may choose to set the NOTREADY condition (does not exist in REXX
language level 3.50). For more information, see chapter on Stream
Input and Output .

(Assuming that the file “/tmp/file” contains the first line: “This
is the first line”):

CHARIN()            –>   ‘F’  /*Maybe*/
CHARIN(,,6)              –>   ‘Foobar’  /*Maybe*/
CHARIN(‘/tmp/file’,,6)   –>   ‘This i’
CHARIN(‘/tmp/file’,4,6)  –>   ‘s is t’


 PREV   NEXT