(SYSLIB) Programming Reference Manual - Public Support Login ...

17.2.3.2. Read Procedure Call (S$ARREAD)
SAR$ READ
The S$ARREAD PROC returns one image from the symbolic input to the calling program,
placing the character text in the text buffer and the attributes in the attribute table.
Initial Conditions
The calling program sets the following parameters in the READ packet to appropriate
values before calling S$ARREAD:
• Required parameters (described in 17.2.1.1)
SR$TEXBUF
SR$ATTRIBL
SR$TEXBUFL
SR$ATTRIB
• Optional parameters (described in 17.2.1.2)
SR$ADDRSEC
SR$SELLSTL
SR$ADDRWO
SR$SELLST
Calling Format
S$ARREAD rpkt
error return
end-of-file return
normal return
where rpkt is a label identifying the starting address of the READ packet and data area.
Returns
Each call to S$ARREAD reads one image from the input. If the normal return is taken,
S$ARREAD returns the character text in the text buffer, the attributes in the attribute
table, and other information in the READ packet. S$ARREAD does not space-fill the text
buffer if the text length is shorter than the text buffer length. If the text length is longer
than the text buffer, S$ARREAD truncates the text to the length of the text buffer and
takes the error return. See 17.2.1.3 for a list of the fields that contain information
returned by S$ARREAD to the calling program.
If the error return from S$ARREAD is taken, A1 contains the call status code, A2
contains the I/O status code, and A3 contains the substatus code. These status codes
are also returned in the packet fields SR$CALLST, SR$IOSTAT, and T1 of SR$STATUS,
respectively. See 17.2.4 for an explanation of the status codes.
If the end-of-file return from S$ARREAD is taken, the last read request encountered an
end-of-file condition. A1 contains the call status code, A2 contains the I/O status code,
and A3 contains the substatus code. These status codes are also returned in the packet
fields SR$CALLST, SR$IOSTAT, and T1 of SR$STATUS, respectively.
7833 1733–004 17–29