Envoy Application Programming Manual

File-System Procedures
Envoy Application Programming Manual—427159-001
C-3
Buffer Parameter
the tag value associated with the I/O call being completed. For example, the following
sequence in Example C-2 shows the use of a tag:
In this case, issuing an AWAITIO[X] call with a line^number of -1 causes Envoy to
wait for a completion on any line that has an outstanding I/O request. An AWAITIO[X]
completion returns the line number and tag specified in the calling sequence associated
with the particular I/O request. The line^number variable tells you on which line the
completion occurred, and the tag tells you whether it was a READ[X] or a WRITE[X]
request that completed.
Buffer Parameter
The data buffers in an application program used to transfer data between the application
process and the file system must be integer (INT) or double integer (INT(32)). They
must reside in the program’s data area (’P’-relative read-only arrays are not permitted).
Count Transferred Parameter
The count transferred parameter of file-system procedures always refers to the number
of bytes to be transferred. For a data communications line, any number of bytes from 3
to 4095 can be transferred in one operation. This value may be limited by the physical
characteristics of the particular device involved and the amount of buffer space assigned
to the device at system generation.
Condition Codes
All file-system procedures return a condition code indicating the outcome of the
operation. Because arithmetic operations may affect condition codes, it is good practice
to check condition codes immediately after a file-system procedure call has been made
and before arithmetic or assignment statements. Generally, the condition codes have the
following meanings:
Example C-2. Use of the Tag Parameter
INT line^number;
INT(32) tag;
CALL READ (line^one,buffer^A,102,,1D);
CALL WRITE (line^two,buffer^B,102,,2D);
CALL READ (line^three,buffer^C,102,,1D);
line^number := -1;
CALL AWAITIO (line^number,,,tag);
< (CCL) An error occurred (call the file-system FILEINFO procedure to
determine the error)
= (CCE) Operation was successful
> (CCG) A warning message (typically indicating end of file, but see the
individual procedures for the meaning of CCG or call FILEINFO to
obtain an error number)