|
|
|
|
This chapter contains a description of each APPC TP server verb. The following information is provided for each verb:
Definition of the verb.
Structure defining the verb control block (VCB) used by the verb. The structure is defined in the TP Server header file /usr/include/sna/tpsrv_c.h . (Parameters beginning with rsrvd are reserved.)
Parameters (VCB fields) supplied to and returned by APPC. For each parameter, the following information is provided:
Description
Possible values
Additional information
Additional information describing the use of the verb.
TP server verbs do not affect APPC conversations or states.
Most parameters supplied to and returned by APPC for the TP Server verbs
are hexadecimal values. To simplify coding, these values are represented by
meaningful symbolic constants defined in the header file values_c.h,
which is included by the TP Server header file tpsrv_c.h.
For example, the opcode parameter of the REGISTER_TP_SERVER
verb is the hexadecimal value represented by the symbolic constant
It is important that you use the symbolic constant and not the hexadecimal value when setting values for supplied parameters, or when testing values of returned parameters. This is because different Solaris systems store these values differently in memory, so the value shown may not be in the format recognized by your system.
The TP server verbs are described in the following order:
The REGISTER_TP_SERVER verb is used to notify SNAP-IX that the application is capable of automatically starting transaction programs (TPs).
The definition of the VCB structure for the REGISTER_TP_SERVER verb is as follows:
typedef struct register_tp_server
{
AP_UINT16 opcode;
unsigned char rsrvd1; /* Reserved */
unsigned char rsrvd2; /* Reserved */
AP_UINT16 primary_rc;
AP_UINT32 secondary_rc;
AP_UINT32 tps_id;
unsigned char tp_file_updates;
AP_NOTIFY_CB notify_cb;
} REGISTER_TP_SERVER;
typedef void (*AP_NOTIFY_CB) (
unsigned char reason,
unsigned char attach_id[8],
AP_CORR app_corr
);
typedef union ap_corr {
void * corr_p;
AP_UINT32 corr_l;
AP_INT32 corr_i;
} AP_CORR;
The TP supplies the following parameters to APPC:
Requests whether the application should be notified when the sna_tps TP configuration file is updated. Possible values are:
The application requests callbacks to notify it that the sna_tps file has been changed.
The application does not require notification of changes to the sna_tps file.
The address of the notification callback function. APPC uses this function in conjunction with the value of the app_corr parameter specified on the REGISTER_TP verb to notify a TP server that one of the following has occurred:
A suitable Attach is available
The sna_tps TP configuration file
has changed (if the application requested this notification by setting the
tp_file_updates parameter to
For more information on how the notification callback function is used, see Callback Routine.
After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful.
If the verb executes successfully, APPC returns the following parameter:
AP_OK
A unique identifier for this TP server. After an application registers itself as a TP server, the value of the tps_id parameter is valid for that process only. The value of the tps_id parameter is not valid across process boundaries. If another application tries to use this value of the tps_id parameter on another verb, that verb is rejected with a primary_rc value of AP_PARAMETER_CHECK and a secondary_rc value of AP_BAD_TPS_ID.
If the verb does not execute successfully, APPC returns a primary return code parameter to indicate the type of error and a secondary return code parameter to provide specific details about the reason for unsuccessful execution.
If the verb does not execute because of a parameter error, APPC returns the following parameters:
AP_PARAMETER_CHECK
Possible values are:
The callback function address was not valid.
If the application cannot be registered as a TP server, APPC returns the following parameters:
AP_REGISTER_FAIL
If the verb does not execute because other conditions exist, APPC returns the following primary return code. For a list of return codes common to all verbs, see Common Return Codes.
This section provides additional usage information about the callback routine.
The application supplies a pointer to a callback routine as one of the parameters to the VCB. This section describes how SNAP-IX uses this routine and the functions that it must perform.
The callback routine is defined as follows:
typedef void (*AP_NOTIFY_CB) (
unsigned char reason,
unsigned char attach_id[8],
AP_CORR app_corr
);
typedef union ap_corr {
void * corr_p;
AP_UINT32 corr_l;
AP_INT32 corr_i;
} AP_CORR;
SNAP-IX calls the routine with the following parameters:
Type of notification. Possible values are:
An Attach has arrived for a TP registered by this TP server. In this case, the attach_id parameter is passed into the notification callback because the arrival of an Attach is used to do one or more of the following:
Optionally query for more information about automatically starting a TP
Reject the Attach if necessary
Identify which TP to automatically start for RECEIVE_ALLOCATE processing
The sna_tps TP configuration file has been modified.
The ID of the attach, as returned by the attach notification callback.
The correlator value supplied by the application. This value allows the application to correlate the returned information with its other processing. The meaning of the correlator passed into the notification callback depends on the notification type as indicated by the value of the reason flag:
If reason is set to AP_ATTACH , the correlator is the correlator that was specified by the application on the REGISTER_TP verb. This allows the application to correlate the Attach with the correct registered TP.
If reason is set to AP_TP_FILE_CHANGE , the correlator is the value of the tps_id parameter on the REGISTER_TP_SERVER verb.
The callback routine need not use all of these parameters. It may perform all the necessary processing on the returned VCB, or it may simply set a variable to inform the main program that the verb has completed.
|
|
|
 |
|