OSI/AS Programming Manual

Wait and Nowait Mode
APS Procedures Programming Concepts
2–22 056783 Tandem Computers Incorporated
7. When you are completely finished using the static subdevice, call
APS_SUBDEVICE_DISCARD_ to delete the subdevice.
Wait and Nowait Mode The APS procedures use the Guardian 90 file system by calling the file-system
procedures internally for file-system I/O operations. When you request the
establishment of a connection by calling APS_ASSOC_ATTACH_ or
APS_ASSOC_CONNECTREQ_ , you use api-environment to specify whether you
want the connection to be in wait or nowait mode. This choice determines the way in
which OSI/AS handles the procedure calls that initiate file-system I/O operations.
Wait Mode In wait mode, the APS procedure waits for the completion of the file-system I/O
operation and then returns a completion status code to you. For example, when you
call the APS_ACTIVITY_ENDREQ_ procedure in wait mode, the procedure does not
return control to your program until the activity end request has been sent or OSI/AS
has encountered an error. Note that you do not know at this stage whether the remote
application has received the request. You know this information when you receive an
activity end confirm by calling APS_EVENT_RECEIVE_ and APS_STATUS_. For an
explanation of the sequence of messages (known as primitives) from request to
confirm, see “Primitives,” earlier in this section.
Nowait Mode In nowait mode, the APS procedure initiates the operation but does not wait for file-
system I/O operations to complete. The API checks the validity of the procedure call
and returns any output that is immediately available. To wait for completion of the
operation, you must call the MFM_AWAITIOX_ procedure, which is described in the
following subsection.
Using MFM_AWAITIOX_
Typically, your program contains a mixture of file-system and APS procedure calls.
As an API user, you should use MFM_AWAITIOX_ (never AWAITIO or AWAITIOX)
to complete nowait operations for both types of procedures. (If you are modifying an
existing program that calls AWAITIOX, you can easily change the AWAITIOX calls to
MFM_AWAITIOX_ calls by altering the parameters to the format specified in
Appendix C and sourcing in or including the MFM_AWAITIOX_ procedure
declaration from $SYSTEM.SYSTEM.EXTDECS0.)
Because the API is invoking file-system I/O operations on your behalf, the API
receives the completion information for the operations. The MFM_AWAITIOX_
procedure enables you to obtain this information from the API.
You can use the tag parameter of MFM_AWAITIOX_ to match calls with
completions. Specify the CEPI (the connection endpoint identifier, described earlier in
this section) or -1 as filenum . Here, -1 means wait for the next completion of either
an APS or a file-system procedure. However, note that if you do not specify -1,
OSI/AS will be unable to perform any operations that require the API to issue
multiple file-system operations. For example, the API may need to issue multiple file-
system operations for large data requests. Therefore, it is usually best to specify -1.
Details of the MFM_AWAITIOX_ procedure are given in Appendix B.