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

SAR$ READ
• Text buffer
The text buffer is used to return the characters contained in the image to the calling
program. The characters are taken from the image buffer and placed sequentially in
the text buffer, regardless of the format of the original image or any attributes that
may apply to them. The text buffer provides one part of internal format (see 16.2).
The calling program using the READ and WRITE functions can use the same text
buffer for both functions.
• Attribute table
The attribute table is used to return to the calling program the attributes that apply to
the characters in the text buffer. Each attribute has a one-word entry in the attribute
table which follows the format in Figure 17–1.
index type value
0 17 18 26 27 35
Figure 17–1. SAR$: Attribute Table Entry
The attribute table provides the other part of internal format (see 16.2). If the images
read by SAR$ do not contain any attributes or if UNTRANSLATE_MODE is set to
S'On', then the attribute table may be omitted by setting
ATTRIBUTE_TABLE_ADDRESS to null (zero). The calling program using the READ
and WRITE functions can use the same attribute table buffer for both functions.
• Select list
The select list is used to determine which SAR$ attributes are returned to the calling
program. It contains a sequential list of attribute types that are returned. Attribute
types that are not on the select list are not returned. For example, if the calling
program wants attribute types 3, 4, and 5 returned, the first word of the select list
would be 003004005000. If the select list is omitted, all attribute types are returned
to the calling program.
The calling program must provide all buffers and tables. The type definitions for the
buffers and tables, and definitions for the default buffer and table lengths, are contained
in the element SAR$DEFN. SAR$DEFN is in the SYSLIB file (SYS$LIB$*SYSLIB) or
SYS$*RLIB$. This element is obtained with the COPY statement. These definitions
simplify the creation of required tables and buffers for the calling program.
7833 1733–004 17–11