OS/2 Procedures Language 2/REXX


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


CHARIN




 >>--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.   

Inf-HTML End Run - Successful