|
|
|
|
The MC_TEST_RTS_AND_POST or TEST_RTS_AND_POST verb informs the application when a REQUEST_TO_SEND notification has been received from the partner TP.
Normally, if the partner TP issues an [MC_]REQUEST_TO_SEND verb, the local TP will be notified of this by the rts_rcvd parameter on a subsequent verb (this is a received parameter on a number of verbs), or by a successful return code on the [MC_]TEST_RTS verb. The [MC_]TEST_RTS_AND_POST verb enables the local TP to receive the REQUEST_TO_SEND notification asynchronously when it arrives, instead of having to issue verbs repeatedly to obtain the notification.
The definition of the VCB structure for the MC_TEST_RTS_AND_POST verb is as follows:
typedef struct mc_test_rts_and_post
{
AP_UINT16 opcode;
unsigned char opext;
unsigned char format; /* Reserved */
AP_UINT16 primary_rc;
AP_UINT32 secondary_rc;
unsigned char tp_id[8];
AP_UINT32 conv_id;
void (*callback)();
unsigned char reserv3;
} MC_TEST_RTS_AND_POST;
The definition of the VCB structure for the TEST_RTS_AND_POST verb is as follows:
typedef struct test_rts_and_post
{
AP_UINT16 opcode;
unsigned char opext;
unsigned char format; /* Reserved */
AP_UINT16 primary_rc;
AP_UINT32 secondary_rc;
unsigned char tp_id[8];
AP_UINT32 conv_id;
void (*callback)();
unsigned char reserv3;
} TEST_RTS_AND_POST;
The definition of the VCB structure for the MC_TEST_RTS_AND_POST verb is as follows:
typedef struct mc_test_rts_and_post
{
unsigned short opcode;
unsigned char opext;
unsigned char reserv2;
unsigned short primary_rc;
unsigned long secondary_rc;
unsigned char tp_id[8];
unsigned long conv_id;
unsigned char reserv3;
unsigned long sema;
} MC_TEST_RTS_AND_POST;
The definition of the VCB structure for the TEST_RTS_AND_POST verb is as follows:
typedef struct test_rts_and_post
{
unsigned short opcode;
unsigned char opext;
unsigned char reserv2;
unsigned short primary_rc;
unsigned long secondary_rc;
unsigned char tp_id[8];
unsigned long conv_id;
unsigned char reserv3;
unsigned long sema;
} TEST_RTS_AND_POST;
The TP supplies the following parameters to APPC:
Possible values are:
For the MC_TEST_RTS_AND_POST verb.
For the TEST_RTS_AND_POST verb.
Possible values are:
For the MC_TEST_RTS_AND_POST verb.
For the TEST_RTS_AND_POST verb.
Identifier for the local TP.
The value of this parameter was returned by the TP_STARTED verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
Conversation identifier.
The value of this parameter was returned by the [MC_]ALLOCATE verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
Address of the callback routine which APPC is to call when a REQUEST_TO_SEND notification is received. For more information, see Usage Notes.
A Windows event handle, obtained by calling one of the two Win32 functions CreateEvent or OpenEvent. APPC signals this event handle to inform the TP when the REQUEST_TO_SEND notification is received.
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.
When this verb is issued, it returns immediately with a primary_rc which indicates whether or not the verb was issued successfully. The only returned parameters which are valid at this stage are primary_rc and secondary_rc (if the primary_rc is not AP_OK). The possible primary_rc and secondary_rc values are as described later in this section.
If this primary_rc is AP_OK, the verb has successfully begun to wait for REQUEST_TO_SEND notification. When the verb has completed (either because the notification was received, or because it was terminated by the end of the conversation or by an error), APPC calls the supplied callback routine. At this point, the returned parameters are as shown below. The primary_rc and secondary_rc parameters will now have new values indicating whether or not the REQUEST_TO_SEND notification was received, and should be examined again.
If the verb executes successfully, APPC returns the following parameter:
REQUEST_TO_SEND notification was received.
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 value of conv_id did not match a conversation identifier assigned by APPC.
The value of tp_id did not match a TP identifier assigned by APPC.
The reserved field format was set to a nonzero value.
The application issued this verb within a callback routine, using the synchronous APPC entry point. Any verb issued from a callback routine must use the asynchronous entry point.
The callback parameter was set to a null pointer, and the verb was issued using the synchronous entry point (or using the asynchronous entry point with a null pointer to a callback routine). For more information, see Usage Notes.
No state check errors occur for this verb.
This return code cannot be returned as the initial return code, but only as the subsequent return code if the initial return code is AP_OK. If the verb did not execute because it was canceled by another verb issued by the TP, APPC returns the following parameter:
The local TP issued one of the following verbs while [MC_]TEST_RTS_AND_POST was outstanding:
DEALLOCATE with dealloc_type set to
MC_DEALLOCATE with dealloc_type set
to
[MC_]SEND_ERROR
TP_ENDED
Issuing one of these verbs causes the [MC_]TEST_RTS_AND_POST verb to be canceled. The callback routine is not called.
If the verb returns because the conversation has ended, APPC returns the following parameter:
AP_UNSUCCESSFUL
If the verb does not execute because other conditions exist, APPC returns primary return codes (and, if applicable, secondary return codes). For information about these return codes, see Common Return Codes.
Possible return codes are:
APPC does not return secondary return codes with these primary return codes.
The TP can issue [MC_]TEST_RTS_AND_POST when the conversation is in any state except Reset.
The conversation state does not change for this verb.
This section provides additional usage information about the following topics:
Callback routine
Processing while the verb is pending
How the TP uses the verb
Avoiding indefinite waits
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:
void (*callback) (
void * vcb,
unsigned char tp_id[8],
AP_UINT32 conv_id
);
SNAP-IX calls the routine with the following parameters:
Pointer to the VCB supplied by the application, including 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 callback routine need not use all of these parameters. It may perform all the necessary processing on the returned VCB, or may simply set a variable to inform the main program that the verb has completed.
The application can issue further APPC verbs from within the callback routine, if required. However, these must be asynchronous verbs. Any synchronous verbs issued from within a callback routine will be rejected with the return codes AP_PARAMETER_CHECK and AP_SYNC_NOT_ALLOWED .
If the application issues the [MC_]TEST_RTS_AND_POST verb using the asynchronous APPC entry point, there are two callback routines specified: one in the VCB, the other supplied as a parameter to the entry point. In general, APPC uses the callback routine specified in the VCB and ignores the one on the entry point; however, if the application supplies a null pointer for the callback routine in the VCB, APPC uses the callback routine on the entry point.
Because the [MC_]TEST_RTS_AND_POST verb returns immediately without waiting for data to arrive, the TP can continue other processing while waiting for it to complete. However, the following points should be noted:
The VCB supplied to the [MC_]TEST_RTS_AND_POST verb continues to be used until the callback routine returns. The TP must not change any fields in the VCB during this time. If it issues any other APPC verb while [MC_]TEST_RTS_AND_POST is outstanding, it must use another VCB for the new verb.
Only one [MC_]TEST_RTS_AND_POST verb per conversation can be active at any time.
To use the [MC_]TEST_RTS_AND_POST verb, the local TP performs the following steps:
Issues the [MC_]TEST_RTS_AND_POST verb.
Checks the value of the primary return code primary_rc:
If the primary return code is AP_OK, the verb is waiting for a REQUEST_TO_SEND notification from the partner TP. While receiving data asynchronously, the local TP can do the following:
Perform tasks not related to this conversation
Issue other APPC verbs on this conversation
Prematurely cancel the [MC_]TEST_RTS_AND_POST verb by issuing one of the following verbs:
DEALLOCATE with dealloc_type set to
MC_DEALLOCATE with dealloc_type set
to
SEND_ERROR
TP_ENDED
If, however, the primary return code is not AP_OK, the [MC_]TEST_RTS_AND_POST verb has failed. In this case, the local TP does not perform Steps 3 and 4.
Checks that the callback routine (supplied as a parameter on this verb) has been called by APPC. When a REQUEST_TO_SEND notification is received from the partner TP, APPC calls this routine.
Checks the new value of the primary return code primary_rc.
If the primary return code is AP_OK, the partner TP has issued [MC_]REQUEST_TO_SEND.
If the primary return code is not AP_OK, the application should check the primary_rc and secondary_rc parameters to determine the action it should take.
If the local TP issues the [MC_]TEST_RTS_AND_POST verb and subsequently waits for the callback routine to be called, it will be suspended until REQUEST_TO_SEND notification is received from the partner TP. It could wait indefinitely if the partner TP does not issue [MC_]REQUEST_TO_SEND. If you need to have the TP operating continuously, avoid waiting on the callback routine, or use the [MC_]TEST_RTS verb.
|
|
|
 |
|