 |
» |
|
|
|
An application accesses the NOF API using the following entry
point function calls: - nof
Issues a NOF verb synchronously. SNAplus2 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 only this entry point if the application
can suspend while waiting for SNAplus2 to completely process a verb. The nof entry point is defined in the NOF header file nof_c.h. - nof_async
Issues a NOF verb asynchronously. SNAplus2 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, SNAplus2
uses an application-supplied callback routine to return the results
of the verb processing. In cases when SNAplus2 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 SNAplus2
to completely process a verb.
The nof_async entry point is defined in the NOF header file nof_c.h. - nof_async callback routine
When using the asynchronous NOF API entry point, the
application must supply a pointer to a callback routine. SNAplus2
uses this callback routine both for completion of a verb and also
for returning NOF data and status indications.
Synchronous
Entry Point: nof | |
An application uses the nof entry point to issue a NOF verb synchronously. SNAplus2
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: - target_handle
An identifier that the application uses to identify
the target SNAplus2 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, SNAplus2 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 SNAplus2 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)
For all other NOF verbs, the application supplies the
value that was returned on the CONNECT_NODE or OPEN_FILE verb.
- nofvcb
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 Chapters 3, 4, and 5. These structures
are defined in the NOF API header file nof_c.h.
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. Using
the Synchronous Entry PointOnly 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. Asynchronous
Entry Point: nof_async | |
An application uses nof_async to issue a NOF verb asynchronously. The application also
supplies a pointer to a callback routine. SNAplus2 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, SNAplus2 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 SNAplus2
returns control to the application, so SNAplus2 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;
int corr_i;
} AP_CORR; |
For more information about the parameters in the NOF_CALLBACK structure, see “The
Callback Routine Specified on the nof_async Entry Point”. An application supplies the following parameters when it uses
the nof_async entry point: - target_handle
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, SNAplus2 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 SNAplus2 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)
For all other NOF verbs, the application supplies the
value that was returned on the CONNECT_NODE or OPEN_FILE verb.
- nofvcb
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 Chapters 3, 4, and 5. These structures
are defined in the NOF API header file nof_c.h. - comp_proc
The callback routine that SNAplus2 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”. - 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, unsigned
long, or 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.
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 PointWhen 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
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 SNAplus2 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;
int corr_i;
} AP_CORR; |
SNAplus2 calls the callback routine with the following parameters: - target_handle
For NOF indications, SNAplus2 passes the target handle
that was supplied with the REGISTER_INDICATION_SINK verb. For completion of
verbs, this parameter is undefined. - nofvcb
One of the following: For NOF indications, a pointer to
a VCB supplied by SNAplus2. For completion of verbs, a pointer to the VCB supplied
by the application. The VCB now includes the returned parameters
set by SNAplus2.
- corr
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. Using
the Callback Routine for IndicationsAlthough the application allocates the VCBs for NOF verbs,
SNAplus2 allocates the VCBs for indications. Therefore, the application
has access to the VCB information only from within the callback
routine; the VCB pointer that SNAplus2 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 it must 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 a 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. For more information
about signal-based scheduling mode, see “Signal-Based
Scheduling Mode”. Scope
of Target Handle | |
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. |
Printable version
