Guardian Procedure Calls Reference Manual

Z^COUNT^TRANSFERRED
returns the number of bytes transferred in the completed I/O operation on a Guardian file.
(For OSS files, this field is replaced by Z^COMPLETION^TYPE.)
Z^TAG
for Guardian files, returns the application-defined tag that was specified when the completed
I/O was initiated. This value is undefined if no tag was supplied for that I/O operation. For
OSS files, this field contains 0. For the FILE_COMPLETEL_ procedure, this field is 64 bits.
Considerations
• Completion on a file by a call to the FILE_COMPLETE[L]_ procedure does not remove it from
the set of enabled files. Each file that is enabled for completion is enabled for multiple
completions until your program removes it from the enabled set or closes it.
• Files specified in the complete-element-list parameter (the temporary override list) must
meet the same requirements to be enabled for completion as files specified to the
FILE_COMPLETE_SET_ procedure.
NOTE: For better performance, use the set of files enabled by the FILE_COMPLETE_SET_ procedure
rather than specifying a temporary override list to the FILE_COMPLETE[L]_ procedure.
Guardian Considerations
• An application can use the FILE_COMPLETE[L]_ procedure in parallel with the AWAITIOX
procedure.
• The AWAITIOX procedure Considerations (page 81) generally apply to the FILE_COMPLETE[L]_
procedure. However, note these differences between the FILE_COMPLETE[L]_ and AWAITIOX
procedures:
◦ The FILE_COMPLETE[L]_ procedure allows you to specify either a particular set of files or
all Guardian files for completion (one to be completed by each call).
◦ The FILE_COMPLETE[L]_ procedure does not provide a way for you to obtain the buffer
address associated with an I/O operation or the segment ID of the extended data segment
containing the buffer.
◦ General error conditions are indicated in the return value of the FILE_COMPLETE[L]_
procedure; an error on a particular file is returned in the Z^ERROR field of the
COMPLETION^INFO structure for that file.
◦ Error 26 is only returned by the FILE_COMPLETE[L]_ procedure if the caller specified a
timelimit value of -1D but no I/O operation has been initiated.
◦ Error 40, which is returned by the FILE_COMPLETE[L]_ procedure if a timelimit value
other than -1D is specified and an I/O operation times out, does not cause any outstanding
I/O operation to be canceled; the operation is considered incomplete.
OSS Considerations
• An application can use the FILE_COMPLETE[L]_ procedure in parallel with the OSS select()
function.
• Completion on an OSS file means checking for readiness. The file is ready if data can be
sent, if data can be received, or if an exception occurred. However, an indication of readiness
does not guarantee that a subsequent I/O operation to the file will finish successfully, For
FILE_COMPLETE[L]_ Procedures 371