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

SAR$ READ
17.1.3.2. SAR_READ Procedure Call
The SAR_READ procedure obtains one image from the input and returns the character
text and attributes of the image to the calling program.
Initial Conditions
The calling program sets the following parameters in the READ packet to appropriate
values before calling SAR_READ:
• Required parameters (described in 17.1.1.1)
TEXT_BUFFER_ADDRESS
TEXT_BUFFER_BYTE_LENGTH
ATTRIBUTE_TABLE_ADDRESS
ATTRIBUTE_TABLE_WORD_LENGTH
• Optional parameters (described in 17.1.1.2)
SELECT_LIST_ADDRESS
SELECT_LIST_BYTE_LENGTH
READ_ADDRESS_SECTOR
READ_ADDRESS_WORD_OFFSET
Calling Format
PROCEDURE SAR_READ
(READ_PACKET_ADDRESS: WORD MACHINE POINTER)
IMPORTED ('SAR$READ$PG');
Returns
Each call to SAR_READ reads one image from the input and returns the character text in
the text buffer, the attributes in the attribute table, and other information in the READ
packet. SAR_READ does not space-fill the text buffer if the text length is shorter than
the text buffer length. If the character text is longer than the text buffer, SAR_READ
truncates the text to the length of the text buffer and returns an error status in
CALL_STATUS.
SAR_READ returns the calling status in the READ packet field CALL_STATUS. If the
status is S'Normal', then the read was successful.
The following fields contain information returned by SAR$ to the caller:
• Character text
SAR_READ returns the character text of the image read in the text buffer and the
character text length in TEXT_LENGTH_IN_BYTES. The length is in 9-bit bytes
(characters).
• Character type
The character set type of the image read is returned in the field CHARACTER_TYPE.
The octal code of the character set type is returned in the field CHARACTER_CODE.
17–14 7833 1733–004