Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (D-E)
Guardian Procedure Calls Reference Manual—522629-013
4-35
DEFINEREADATTR Procedure
•
If an error occurs, the contents of the data array are undefined.
•
Both attribute-name and cursor can be present. If cursor is present, it is
used to “name” the attribute whose value is to be returned, and
attribute-name
returns the name of the attribute.
•
When the cursor parameter is used, parameter info-word is returned even
though the attribute can be absent from the DEFINE working set.
•
To use the cursor mode, initialize cursor to 0 and repeatedly call this procedure
without changing
cursor to sequentially read attributes. The caller should not, for
example, set
cursor to 7 and then call this procedure.
•
To implement a command similar to the TACL SHOW DEFINE command, a
process would typically call DEFINEREADATTR with
define-name omitted and
with
read-mode equal to 1; to implement the SHOW DEFINE * command, it would
call DEFINEREADATTR with
define-name omitted and with read-mode equal to
2.
•
To implement the detailed version of the INFO DEFINE command, command
interpreters would call DEFINEREADATTR passing it the
define-name and with
read-mode of 0.
•
When the cursor option is being used, and the last attribute is read, then cursor
returns the next attribute number consistent with the
read-mode parameter.
When this attribute is read, 2061 (no more attributes) is returned instead of 0. The
2061 code should be interpreted as success; however, if a process (such as a
command interpreter) is calling DEFINEREADATTR in a loop using the cursor
option, then code 2061 should be used to terminate the loop.
•
attribute-name should not be declared as a P-relative array. In general, a
reference parameter should not be declared as a P-relative array.
Example
LITERAL define^vol^len = 25; ! value buffer length
STRING .EXT define^name [0:23];
STRING .EXT volume [0:15]; ! attribute name
STRING .EXT volid [0:define^vol^len]; ! value buffer
INT len^read := 0; ! len of external rep.
.
.
define^name ':=' ["=mytape "];
volume ':=' ["volume "];
volid ':=' " " & volid[ 0 ] for define^vol^len;
error := DEFINEREADATTR ( define^name, volume, , volid,
define^vol^len, len^read );
IF error <> THEN ...