HP-UX SNAplus2 R7 NOF Programmer's Guide

Writing NOF Applications
Windows Considerations
The callback routine that SNAplus2 will call when the verb completes. For more information about the
requirements for a callback routine, see Section 2.2.1, NOF API Entry Points for Windows.
corr
An optional correlator for use by the application. This parameter is defined as a C union so that the application
can specify any of three different parameter types: pointer, 32–bit integer, or 16–bit integer.
SNAplus2 does not use this value, but passes it as a parameter to the callback routine when the verb completes.
This value enables the application to correlate the returned information with its other processing.
Returned Values
The asynchronous entry point returns one of the following values:
AP_COMPLETED
The verb has already completed. The application can examine the parameters in the VCB to determine
whether the verb completed successfully. SNAplus2 does not call the supplied callback routine for this verb.
AP_IN_PROGRESS
The verb has not yet completed. The application can continue with other processing, including issuing other
NOF verbs, provided that they do not depend on the completion of the current verb. However, the application
should not attempt to examine or modify the parameters in the VCB supplied to this verb.
SNAplus2 calls the supplied callback routine to indicate when the verb processing completes. The application
can then examine the VCB parameters.
Using the Asynchronous Entry Point
When using the asynchronous entry point, note the following:
• If an application specifies a null pointer in the comp_proc parameter, the verb will complete synchronously (as
though the application issued the verb using the synchronous entry point).
• If the call to
nof_async is made from within an application callback, specifying a null pointer in the comp_proc
parameter is not permitted. In such cases, SNAplus2 rejects the verb with a primary return code value of
AP_PARAMETER_CHECK and a secondary return code value of
AP_SYNC_NOT_ALLOWED.
• The application must not attempt to use or modify any parameters in the VCB until the callback routine has
been called.
• Multiple verbs do not necessarily complete in the order in which they were issued. In particular, if an application
issues an asynchronous verb followed by a synchronous verb, the completion of the synchronous verb does not
guarantee that the asynchronous verb has already completed.
The Callback Routine Specified on the nof_async Entry Point
When using the asynchronous NOF API entry point, the application must supply a pointer to a callback routine.
SNAplus2 uses this callback routine to indicate verb completion. This section describes how SNAplus2 uses the
callback routine and the functions that the callback routine must perform.
Callback Function
NOF_CALLBACK (*comp_proc);
typedef void (*NOF_CALLBACK) (
AP_UINT32 target_handle,
void * nofvcb,
AP_CORR corr
AP_UINT32 indic_length
);
typedef union ap_corr {
void * corr_p;
AP_UINT32 corr_l;
AP_INT32 corr_i;
72