|
|
|
|
An application accesses APPC using the following entry points:
Issues an APPC verb synchronously. SNAP-IX does not return control to the application until verb processing has finished.
Issues an APPC 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. In most cases, verb processing is still in progress when control returns to the application; SNAP-IX then uses an application-supplied callback routine to return the results of the verb processing. In some cases, verb processing is complete when SNAP-IX returns control to the application; SNAP-IX does not use the application's callback routine.
The entry points APPC and APPC_Async are defined in the APPC header file /usr/include/sna/appc_c.h.
An application that performs a single task, and can suspend while waiting for information either from SNAP-IX or from the remote system, need only use the APPC (synchronous) entry point.
If the application performs multiple tasks (such as communicating with more than one remote program at a time, or performing other processing in addition to APPC verbs), you may need to ensure that it does not suspend while waiting for information. In this case, the application should use the APPC_Async (asynchronous) entry point, supplying a callback routine that SNAP-IX can use to return information when it is available.
The following sections describe these entry points, and also describe some additional application-defined functions which the application must supply to them.
An application uses APPC to issue an APPC verb synchronously. SNAP-IX does not return control to the application until verb processing has finished.
void APPC (
void * vcb
);
For compatibility with earlier APPC implementations, SNAP-IX also provides the entry points APPC_C and APPC_P , which can be used in the same way as APPC.
When the application uses the APPC entry point to issue a verb, it supplies the following parameter:
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 APPC Control Verbs and APPC Conversation Verbs. These structures are defined in the APPC header file /usr/include/sna/appc_c.h.
The APPC 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(vcb, 0, sizeof(vcb));
The function does not return a value. When the call returns, the application can examine the parameters in the VCB to determine whether the verb completed successfully.
An application uses APPC_Async to issue an APPC 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. In most cases, verb processing is still in progress when control returns to the application. Later, SNAP-IX uses an application-supplied callback routine to return the results of the verb processing. 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.
unsigned short APPC_Async (
void * vcb,
AP_CALLBACK (*comp_proc),
AP_CORR corr
);
typedef void (*AP_CALLBACK) (
void * vcb,
unsigned char tp_id[8],
AP_UINT32 conv_id,
AP_CORR corr
);
typedef union ap_corr {
void * corr_p;
AP_UINT32 corr_l;
AP_INT32 corr_i;
} AP_CORR;
Parameter types such as AP_UINT32, used in these entry points and in the APPC VCBs, are defined in the common header file /usr/include/sna/values_c.h, which is included by the APPC header file /usr/include/sna/appc_c.h.
When the application uses the APPC_Async entry point to issue a verb, it supplies the following parameters:
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 APPC Control Verbs and APPC Conversation Verbs. These structures are defined in the APPC header file appc_c.h.
The APPC 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(vcb, 0, sizeof(vcb));
The callback routine that SNAP-IX will call when the verb completes. For more information about the requirements for a callback routine, see Callback Routine for Asynchronous Verb Completion.
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).
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 APPC 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 APPC_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 primary return code value AP_PARAMETER_CHECK and secondary return code value 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 [MC_]RECEIVE_AND_POST verb includes a pointer to a callback routine as one of the VCB parameters. This verb can be issued using either the synchronous or the asynchronous entry point. SNAP-IX uses the callback routine specified in the VCB to return the results of this verb. The callback routine specified on the asynchronous entry point is used only if the application supplies a null pointer for the callback routine in the VCB.
The method that an application uses to schedule asynchronous events depends on which of the following types of application it is:
Applications that are based around a single main thread of execution to receive and process requests
Applications that can have several threads of execution receiving and processing requests
Applications that use the Motif interface and for which the application code consists mainly of callbacks from the Motif libraries
To schedule asynchronous events, single-threaded applications use the application scheduling mode or the signal-based scheduling mode.
Application scheduling mode gives the application full control over event scheduling from different sources by integrating SNA callbacks with the application's main processing loop. Use this mode in new applications.
Signal-based scheduling mode provides binary compatibility for existing SNAP-IX Version 5 applications. It should not be used in new applications.
Application scheduling mode provides a way for callback functions to be called from the application's main thread of execution. With this mode of operation, the APPC library has no need for multiple threads or signals.
Application scheduling mode works on the assumption that at the heart of an application there is a scheduling loop which includes a call to select or poll to determine whether there is work from one or more work sources. Application scheduling provides access to the file descriptor the APPC library uses to communicate with the SNAP-IX node. The application adds this file descriptor to its main scheduling select call, and when select indicates events on that file descriptor, the application calls a function to process the events and, if necessary, make the APPC callbacks. For more information about callbacks, see Callback Routine for Asynchronous Verb Completion.
SNA callbacks are not restricted to the event processor. Callbacks can be made from within any SNA library functions.
To use application scheduling mode, incorporate the following steps into your application code:
In the initialization section of the application, indicate that you want to use application scheduling mode by adding the following function call before the first call into any SNA library:
SNA_USE_FD_SCHED();
The SNA_USE_FD_SCHED call has no return value.
Write the main scheduling loop to set up the file descriptors and call select according to the following logic. Note that SNA_GET_FD returns an integer which is either a valid SNA file descriptor or -1 if there is no open SNA file descriptor. (The return of -1 indicates either that there has been no call into any SNA library, or that there has been a serious error resulting in the file descriptor being closed.)
fd= SNA_GET_FD();
if (fd != -1)
{
FD_SET(fd, &fdset);
}
select(nfds, *fdset, *fdset, *fdset, timeout);
If the select call returns with an indication of events on the SNA file descriptor, the application simply calls SNA_EVENT_FD. This function (which has no return value) processes all the events on the SNA file descriptor. If these events cause any APPC verbs to complete, the APPC callback functions will be issued from within SNA_EVENT_FD.
Note that there is not a one-to-one mapping between calls to SNA_EVENT_FD and callbacks. There may be no callbacks (if the event does not complete a verb), or there may be many callbacks (because SNA_EVENT_FD processes all events before it returns).
SNA_EVENT_FD();
In general, SNA_GET_FD returns the same file descriptor each time you call it. However, you should call it before each call to select or poll, because there are some situations (such as when your application has issued the fork call, or in error cases) when the file descriptor may change.
The SNA event handler processes internal control messages between SNAP-IX components, which do not result in a call to your application's callback routine, in addition to processing the completion of APPC verbs. In addition, if your application uses multiple conversations and there are multiple verbs outstanding on different conversations, the SNA event handler may call the callback routine for any of these verbs (because the same file descriptor is used for all conversations).
Because of this, you cannot assume that an event on the SNA file descriptor corresponds to the completion of a particular verb. The correlator information passed to the callback routine is the correct method of checking which verb has completed. The callback routine may either handle the verb completion itself, or pass information to the main processing loop to indicate which verb has completed. For more details of how the callback routine should operate, see Callback Routine for Asynchronous Verb Completion.
Signal-based scheduling mode provides binary compatibility for existing SNAP-IX Version 5 applications. It is not recommended for new applications because support for signal-based scheduling mode may be discontinued in future versions of SNAP-IX.
Asynchronous verbs are implemented by making callbacks to the application from signal catcher context. The disadvantages of signal-based scheduling mode are:
Applications that receive work from multiple sources are difficult to write.
Applications are required to use Solaris V.3 signal calls.
Applications can use only a subset of system calls made from signal catcher context and therefore from the API callback context.
Signaling mode is not thread-safe
To detect work arriving from other components of SNAP-IX, the APPC library makes use of the SIGPOLL signal. Applications can require the SIGPOLL signal for other purposes. Therefore, the library daisy-chains to any existing signal catchers. The first verb issued by the application initializes the library's signal catcher.
When the SIGPOLL signal arrives, either it indicates work for SNAP-IX or it was generated for some other reason. The APPC library's signal catcher processes the signal and then calls the previous signal catcher to allow the signal to be used for other purposes.
The following restrictions apply to SIGPOLL usage:
Applications must not permanently disable this signal. The sighold and sigrelse signal calls can be used to protect a critical region of code, provided that no SNA verbs are issued between sighold and sigrelse.
Applications must preserve the address of the SNAP-IX signal catchers returned by the sigset call when adding signal catchers to applications. Applications must then arrange to call these routines from within the new signal catchers.
Applications must not use the POSIX signal mechanism SIGACTN, which can cause problems in SNAP-IX applications.
The Solaris operating system call sleep can cause problems if applications or their libraries also use signal catchers. Because the SNAP-IX APPC library operates using a signal catcher, do not use the sleep call within an APPC application that uses signal-based scheduling. If necessary, you can use the alarm with a timer to provide the same function.
SNAP-IX API libraries are available for linking with multithreaded applications. When you develop applications to operate in a multithreaded environment, the following restrictions apply:
When an application uses the asynchronous entry point, the application is required to maintain the consistency of its data structures when callbacks are invoked. Consistency of data structures can be maintained using the multithreading lock or mutex facilities. The callbacks are made in the context of a separate thread created and managed from within the SNAP-IX API library. Since asynchronous callbacks run using a separate thread, the application is not required to provide a source of scheduling to enable the callbacks. Do not use application scheduling mode in a multithreaded application.
The application must perform any required cleanup processing (for example, issuing TP_ENDED). The APPC library does not maintain any correlation between threads and APPC verb usage and does not perform this processing automatically when a thread terminates.
Applications that use the Motif interface and whose code consists mainly of callbacks from the Motif libraries are required to add SNA events to the main Xt library scheduling loop. The SNA events allow the SNAP-IX library to run callbacks in order to process asynchronous verb completions.
Add the following lines to your code before the first call into any SNA library:
#include <Xt.h> int app_context; ... XtAppInitialize(app_context...) ... SNA_USE_XT_SCHED(app_context);
The SNA_USE_XT_SCHED call has no return values. It calls the XtAppAddInput function to register the SNA work sources. When work subsequently arrives on the SNA file descriptor, the Xt library scheduling loop calls the SNA event handler, which then makes any required API callbacks to the application.
SNA callbacks can also be made from within other calls into the SNA library.
When using the asynchronous entry point, the application must supply a pointer to a callback routine. This section describes how SNAP-IX uses this routine, and the functions that it must perform.
AP_CALLBACK (*comp_proc);
typedef void (*AP_CALLBACK) (
void * vcb,
unsigned char tp_id[8],
AP_UINT32 conv_id,
AP_CORR corr
);
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:
Pointer to the VCB supplied by the application. The VCB now includes the returned parameters set by SNAP-IX.
The 8-byte TP identifier of the TP in which the verb was issued.
The conversation identifier of the conversation in which the verb was issued.
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. The callback routine can perform all the necessary processing on the returned VCB, or it can simply set a variable to inform the main program that the verb has completed.
The function does not return a value.
When using the callback routine for asynchronous verb completion, the application can issue additional asynchronous APPC verbs from within the callback routine, if required. SNAP-IX rejects any synchronous verbs issued from within a callback routine with the primary and secondary return codes AP_PARAMETER_CHECK and AP_SYNC_NOT_ALLOWED.
|
|
|
 |
|