──CHARIN(─┬──────┬──┬──────────────────────────┬─)─────
└─name─┘ └─,─┬───────┬──┬─────────┬─┘
└─start─┘ └─,length─┘
CHARIN returns a string of up to length characters read from the character input stream name. The form of the name is implementation dependent. If name is omitted, characters are read from the default input stream, STDIN:. The default length is 1.
For persistent streams, a read position is maintained for each stream. In the OS/2 operating system, this is the same as the write position. Any read from the stream will by default start at the current read position. When the read is completed, the read position is increased by the number of characters read. A start value can be given to specify an explicit read position. This read position must be positive and within the bounds of the stream, and must not be specified for a transient stream ( a port or other serial device). A value of 1 for start refers to the first character in the stream.
If you specify a length of 0, then the read position will be set to the value of start, but no characters are read and the null string is returned.
In a transient stream, if there are fewer then length characters available, then execution of the program will normally stop until sufficient characters do become available. If, however, it is impossible for those characters to become available due to an error or other problem, the NOTREADY condition is raised and CHARIN will return with fewer than the requested number of characters.
Here are some examples:
CHARIN(myfile,1,3) -> 'MFC' /* the first 3 */
/* characters */
CHARIN(myfile,1,0) -> '' /* now at start */
CHARIN(myfile) -> 'M' /* after last call */
CHARIN(myfile,,2) -> 'FC' /* after last call */
/* Reading from the default input (here, the keyboard) */
/* User types 'abcd efg' */
CHARIN( ) -> 'a' /* default is */
/* 1 character */
CHARIN(,,5) -> 'bcd e'
Note 1:
CHARIN returns all characters that appear in the stream including control characters such as line feed, carriage return, and end of file.
Note 2:
When CHARIN is used to read from the keyboard, program execution stops until you press the Enter key.