|
|
|
|
This chapter describes how a NOF application:
Uses the NOF API entry points
Schedules asynchronous events
Is compiled and linked to use the NOF API
This chapter also describes the following information:
Target (node or file) for NOF verbs, and how they interact with the target
Ordering and dependencies between NOF verbs
NOF restrictions based on node configuration
How to request single or multiple data entries with QUERY_* verbs
An application accesses the NOF API using the following entry point function calls:
Issues a NOF verb synchronously. SNAP-IX does not return control to the application until verb processing has finished. All NOF verbs except REGISTER_INDICATION_SINK and UNREGISTER_INDICATION_SINK can be issued through this entry point.
An application can use this entry point only if the application can suspend while waiting for SNAP-IX to completely process a verb.
Issues a NOF verb asynchronously. SNAP-IX returns control to the application immediately, with a returned value indicating whether verb processing is still in progress or has completed. If the returned value indicates that verb processing is still in progress, SNAP-IX uses an application-supplied callback routine to return the results of the verb processing. In cases when SNAP-IX is able to completely process the request, the callback routine will not be invoked.
All NOF verbs can be issued through this entry point. The REGISTER_INDICATION_SINK and UNREGISTER_INDICATION_SINK verbs must be issued through this entry point.
An application must use this entry point if either of the following conditions is true:
The application needs to receive NOF indications.
The application cannot suspend while waiting for SNAP-IX to completely process a verb.
When using the asynchronous NOF API entry point, the application must supply a pointer to a callback routine. SNAP-IX uses this callback routine both for completion of a verb and also for returning NOF data and status indications.
The nof and nof_async entry points are defined in the NOF header file /usr/include/sna/nof_c.h. Parameter types such as AP_UINT32, used in these entry points and in the NOF VCBs, are defined in the common header file /usr/include/sna/values_c.h, which is included by the NOF header file nof_c.h.
An application uses the nof entry point to issue a NOF verb synchronously. SNAP-IX does not return control to the application until verb processing has finished.
void nof (
AP_UINT32 target_handle,
void * nofvcb
);
An application supplies the following parameters when it uses the nof entry point:
An identifier that the application uses to identify the target SNAP-IX node or file. This parameter is supplied in one of the following ways:
For the following verbs, this parameter is not supplied; set it to 0 (zero). If the verb completes successfully, SNAP-IX returns the target handle as one of the VCB parameters. The application then uses the target handle for subsequent verbs.
CONNECT_NODE (to access a running node, or to access the node on a server where the SNAP-IX software is started but the node is not yet started)
OPEN_FILE (to access the domain configuration fileor the SNA network data file)
For the following verbs, the application supplies a null value:
QUERY_NODE_ALL (to obtain a list of running nodes)
QUERY_CENTRAL_LOGGER
For all other NOF verbs, the application supplies the value that was returned on the CONNECT_NODE or OPEN_FILE verb.
Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued. The VCB structure for each verb is described in NOF API Verbs. These structures are defined in the NOF API header file /usr/include/sna/nof_c.h.
The NOF VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(nofvcb, 0, sizeof(nofvcb));
The nof entry point does not have a return value. When the call returns, the application should examine the return code in the VCB to determine whether the verb completed successfully and to determine parameters it needs for further verbs. In particular, when the CONNECT_NODE or OPEN_FILE verb completes successfully, the VCB contains the target_handle that the application should use when issuing subsequent verbs.
Only one synchronous verb can be outstanding at any time for each target handle. A synchronous verb fails with the primary return code AP_STATE_CHECK and secondary return code AP_SYNC_PENDING if another synchronous verb for the same target handle is in progress.
An application uses nof_async to issue a NOF verb asynchronously. The application also supplies a pointer to a callback routine. SNAP-IX returns control to the application immediately with a returned value that indicates whether verb processing is still in progress or has completed. In most cases, verb processing is still in progress when control returns to the application. In these cases, SNAP-IX uses the application-supplied callback routine to return the results of the verb processing at a later time. In some cases, verb processing is complete when SNAP-IX returns control to the application, so SNAP-IX does not use the application's callback routine.
AP_UINT16 nof_async(
AP_UINT32 target_handle,
void * nofvcb,
NOF_CALLBACK (*comp_proc),
AP_CORR corr
);
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;
} AP_CORR;
For more information about the parameters in the
An application supplies the following parameters when it uses the nof_async entry point:
This parameter is supplied in one of the following ways:
For the following verbs, this parameter is not used; set it to 0 (zero). If the verb completes successfully, SNAP-IX returns the target handle as one of the VCB parameters. The application then uses the target handle for subsequent verbs.
CONNECT_NODE (to access a running node, or to access the node on a server where the SNAP-IX software is started but the node is not yet started)
OPEN_FILE (to access the domain configuration fileor the SNA network data file)
For the following verbs, the application supplies a null value:
QUERY_NODE_ALL (to obtain a list of running nodes)
QUERY_CENTRAL_LOGGER
For all other NOF verbs, the application supplies the value that was returned on the CONNECT_NODE or OPEN_FILE verb.
Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued. The VCB structure for each verb is described in NOF API Verbs. These structures are defined in the NOF API header file /usr/include/sna/nof_c.h.
The NOF VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(nofvcb, 0, sizeof(nofvcb));
The callback routine that SNAP-IX will call when the verb completes. For more information about the requirements for a callback routine, see The Callback Routine Specified on the nof_async Entry Point.
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.
SNAP-IX 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.
The asynchronous entry point returns one of the following values:
The verb has already completed. The application can examine the parameters in the VCB to determine whether the verb completed successfully. SNAP-IX does not call the supplied callback routine for this verb.
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.
SNAP-IX calls the supplied callback routine to indicate when the verb processing completes. The application can then examine the VCB parameters.
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, SNAP-IX 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.
When using the asynchronous NOF API entry point, the application must supply a pointer to a callback routine. SNAP-IX uses this callback routine both for completion of a verb and also for returning NOF indications. (The REGISTER_INDICATION_SINK verb is also issued as an asynchronous verb that specifies a callback routine; the callback is called each time the indication is received. For other NOF verbs, an indication is received when the verb completes.) The application must examine the opcode parameter in the VCB to determine which event is contained in the callback routine.
This section describes how SNAP-IX uses the callback routine and the functions that the callback routine must perform.
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;
} AP_CORR;
SNAP-IX calls the callback routine with the following parameters:
For NOF indications, SNAP-IX passes the target handle that was supplied with the REGISTER_INDICATION_SINK verb. For completion of verbs, this parameter is undefined.
For NOF indications, a pointer to a VCB supplied by SNAP-IX.
For completion of verbs, a pointer to the VCB supplied by the application. The VCB now includes the returned parameters set by SNAP-IX.
The correlator value supplied by the application. This value enables the application to correlate the returned information with its other processing.
The callback routine need not use all of these parameters (except as described in Using the Callback Routine for Indications). The callback routine can perform all the necessary processing on the returned parameters, or it can simply set a variable to inform the NOF application that the verb has completed.
The callback function does not return any values.
Although the application allocates the VCBs for NOF verbs, SNAP-IX allocates the VCBs for indications. Therefore, the application has access to the VCB information only from within the callback routine; the VCB pointer that SNAP-IX supplies to the callback routine is not valid outside the callback routine. The application must either complete all the required processing from within the callback routine, or make a copy of any VCB data that it needs to use outside this routine.
In the event that the NOF application needs to make a copy of the data supplied on the callback routine and the NOF application is using signal-based scheduling mode, an operating system limitation may prohibit memory allocation. In this case, some memory must be preallocated before the REGISTER_INDICATION_SINK verb is issued.
Each application that needs to use NOF must issue the CONNECT_NODE verb to obtain its own handle. No two NOF applications can use the same NOF target handle.
In particular, if the application that issued CONNECT_NODE later forks to create a child process, the child process cannot issue any NOF verbs that use the target handle obtained by the parent process. However, the child process can issue another CONNECT_NODE to obtain its own target handle.
|
|
|
 |
|