OSI/FTAM Programming Guide

NonStop FTAM Programming
HP NonStop OSI/FTAM Programming Guide—528612-001
3-9
Wait and Nowait Modes
Using MFM_AWAITIOX_
The FTAM API invokes I/O operations on behalf of your application. Therefore, the
NonStop operating system returns I/O completion information to the FTAM API instead
of to your program. While in nowait mode, your program retrieves I/O completion
information from the FTAM API by calling the MFM_AWAITIOX_ procedure.
Typically, your application contains a mixture of file-system, APS general-support, and
FTM protocol procedure calls. To complete nowait operations for all these types of
procedures, you use the MFM_AWAITIOX_ procedure, rather than the Guardian
AWAITIO or AWAITIOX procedure. The reason for this practice is that a single request
from your application can cause an FTM or APS procedure to make multiple internal
calls that perform I/O operations. Each of those internal calls has its own completion,
reported to the FTAM API, and the API reports completion to your application after all
internal calls are complete. If your application used the Guardian AWAITIO or
AWAITIOX procedure, it might be misled as to the actual completion status of its
request, and the FTAM API might not get the information it needs for processing the
internal calls. The safest strategy is to use the MFM_AWAITIOX_ procedure to wait for
completion of all calls requiring I/O operations—also includes calls you make to
Guardian file-system procedures.
To call the MFM_AWAITIOX_ procedure, specify the CEPI or the value -1 as its
filenum parameter. Here, -1 means wait for the next completion of a file-system,
APS, or FTM procedure. Use the tag parameter of the MFM_AWAITIOX_ procedure
to match calls with completions. For details on the use of the tag parameter, see Tag
Parameter on page 3-10.
Do not use the MFM_AWAITIOX_ procedure to complete a procedure call if an error
(status code not equal to 0) is returned immediately after you make the call. In such
cases, an I/O operation is not initiated because an error has occurred. Also, do not call
the MFM_AWAITIOX_ procedure to complete FTM calls that do not cause I/O
operations; in such cases, there is no I/O completion for which to wait because the call
is local to your application process.
For a list of FTM procedure calls that cause I/O operations and therefore require you to
use MFM_AWAITIOX_ if you use nowait mode, see Table 4-1 on page 4-2. For more
information on the use of the MFM_AWAITIOX_ procedure call, see the OSI/FTAM
Programming Reference Manual.
Limits on Outstanding Nowait Operations
There are limits on the number of FTAM calls that can be waiting for completion in
nowait mode. Your application can have these calls outstanding for each CEPI:
•
No more than one call to the APS_EVENT_RECEIVE_ procedure
Note. Never use the Guardian procedures AWAITIO or AWAITIOX in an application program
using FTM and APS procedures. Doing so can interfere with the correct operation of the FTAM
API. Always use the MFM_AWAITIOX_ procedure call to complete nowait operations.