gtpc2ma5 | C/C++ Language Support User's Guide |
This function is an extension to the LU 6.2 architecture.
This function allows the issuing TPF ECB to exit after sending out a
tppc_confirm, tppc_deallocate with
DEALLOCATE_TYPE_CONFIRM or tppc_prepare_to_receive with
PREP_TO_RECEIVE_TYPE_CONFIRM request. TPF/APPC then activates
a different ECB at the program specified when the reply to the confirm request
has arrived and has been processed.
Format
#include <tppc.h>
void tppc_activate_on_confirmation(unsigned int *resid,
struct tppc_return_codes *rcode,
enum t_aoc_verb verb,
enum t_aoc_dl level,
unsigned char *field,
unsigned char *pgm);
- resid
- This is a pointer to a 4-byte field that contains the resource ID.
This resource ID must be the ID assigned on the initial ALLOCATE for this
conversation or one that was assigned by an incoming ATTACH.
- rcode
- This is a pointer to the structure tppc_return_codes, defined
in tppc.h, where the return code will be placed.
- verb
- This specifies the verb function that is to be executed. This
argument must belong to the enumeration type t_aoc_verb, defined in
tppc.h. Use one of the following values:
- AOC_CONFIRM
- This value specifies that the tppc_confirm function should be
executed.
- AOC_DEALLOC
- This value specifies that the tppc_deallocate function should
be executed with type=DEALLOCATE_TYPE_CONFIRM.
- AOC_P_T_R
- This value specifies that the tppc_prepare_to_receive function
should be executed with type=PREP_TO_RECEIVE_TYPE_CONFIRM.
- level
- This specifies a data level that contains a working storage block to be
passed to the activated program. After the reply to the CONFIRM request
arrives and is processed, the contents of the block on the data level
specified is passed from the ECB issuing this verb to a 4K block on the same
data level of the ECB created. This argument must belong to the
enumeration type t_aoc_dl, defined in
tppc.h. Use a value in the range of AOC_D0
to AOC_DA. If no block is to be passed, use the value
AOC_NO_DL.
- field
- This is a pointer to an 8-byte field that is passed to the program
specified by pgm when it is activated. The data in this field
is copied to EBX000 of the new ECB that is created when the reply to the
CONFIRM request has arrived and has been processed. If the
level parameter is used instead, this parameter must have a value of
NULL.
- pgm
- This is a pointer to a 4-byte field that contains the name of the TPF
real-time program to be activated after the reply to the CONFIRM request has
arrived and has been processed. This TPF real-time segment must be
defined in the TPF transaction program name table (TPNT) as an
ACTIVATE_ON_RECEIPT target program. This is done with the ITPNT macro
by specifying TYPE=AOR and by specifying the segment name as both the TPN name
and the PGM name. See TPF General Macros for more information about the ITPNT macro.
Return Codes
The following table contains a list of the primary and secondary return
codes that can be returned to the program that called the
tppc_activate_on_confirmation function. A complete list of
the return codes and their definitions can be found in Table 37 and Table 38.
Symbolic Name
| Primary Code
| Secondary Code
|
LU62RC_OK
| 0000
|
|
LU62RC_AOC_INCOMPLETE
| ....
| 00000009
|
LU62RC_PARAMETER_CHECK
| 0001
|
|
LU62RC_PK_BAD_TCBID
| ....
| 00000001
|
LU62RC_PK_BAD_CONVID
| ....
| 00000002
|
LU62RC_PKDLLOC_BADTYPE
| ....
| 00000051
|
LU62RC_PKPTRCV_INVTYPE
| ....
| 000000A1
|
LU62RC_PK_BAD_PROG
| ....
| 000000F2
|
LU62RC_PK_BAD_PARM
| ....
| 000000F3
|
LU62RC_PK_BAD_OPTION
| ....
| 00C62074
|
LU62RC_STATE_CHECK
| 0002
|
|
LU62RC_SKCNFRM_BADSTATE
| ....
| 00000032
|
LU62RC_SKCNFRM_INVALID
| ....
| 00000033
|
LU62RC_SKDLLOC_CONFIRM
| ....
| 00000053
|
LU62RC_SKPTRCV_BADSTATE
| ....
| 000000A3
|
LU62RC_TPF_ABEND
| FFFF
|
|
The following table contains a list of the primary and secondary return
codes that can be passed to the program specified by pgm when it is
activated. The return codes are based on the reply to the CONFIRM
request.
Symbolic Name
| Primary Code
| Secondary Code
|
LU62RC_OK
| 0000
|
|
LU62RC_ALLOC_ERROR
| 0003
|
|
LU62RC_TP_NOT_AVAIL_RETRY
| ....
| 084B6031
|
LU62RC_TP_NOT_AVAIL_NO_RETRY
| ....
| 084C0000
|
LU62RC_TPN_NOT_RECOGNIZED
| ....
| 10086021
|
LU62RC_PIP_NOT_SPECIFIED_CORRECTLY
| ....
| 10086032
|
LU62RC_CONV_TYPE_MISMATCH
| ....
| 10086034
|
LU62RC_SYNLVL_NOTSUPORT
| ....
| 10086041
|
LU62RC_DLLOC_ABEND_PGM
| 0006
|
|
LU62RC_DLLOC_ABEND_SVC
| 0007
|
|
LU62RC_DLLOC_ABEND_TMR
| 0008
|
|
LU62RC_PGMERR_PURGING
| 000E
|
|
LU62RC_CONVFAIL_RETRY
| 000F
|
|
LU62RC_CONVFAIL_NO_RETRY
| 0010
|
|
LU62RC_SVCERR_PURGING
| 0013
|
|
LU62RC_TPF_ABEND
| FFFF
|
|
Programming Considerations
- The conversation must be in send state.
- The value supplied in resid must be the resource ID returned by
the tppc_allocate function or one that was assigned by an incoming
ATTACH.
- You can call this function instead of tppc_confirm,
tppc_deallocate with DEALLOCATE_TYPE_CONFIRM or
tppc_prepare_to_receive with
PREP_TO_RECEIVE_TYPE_CONFIRM. After the reply to the
confirmation request arrives and is processed, TPF/APPC support activates the
program specified by pgm. The return codes are passed to the
new ECB in contiguous memory starting at EBX008. An ECB is not
suspended while waiting for the reply to the CONFIRM request.
- Note:
- The structure of the tppc_return_codes requires 2 alignment bytes
between the primary and secondary return codes. This structure cannot
be used to overlay the area starting at EBX008.
- If the return code is LU62RC_OK, the ECB is no longer connected to the
transaction program or the conversation. The ECB cannot issue any more
TPF/APPC verbs.
- If the return code is any value other than LU62RC_OK, the ECB is still
connected to the transaction program and the conversation. However,
because all other return codes indicate a serious error, this also indicates
that a DEALLOCATE ABEND occurred for the conversation. The ECB cannot
issue any more TPF/APPC verbs for this conversation but can issue TPF/APPC
verbs for other conversations associated with the transaction program
instance.
- Note:
- The transaction program is identified with the transaction program identifier
(TCB ID), and the conversation is identified with the conversation control
block identifier (CCB ID). Both identifiers are defined in the ECB as
EBTCBID and EBCCBID respectively.
- You must specify either the level parameter or the field
parameter, but not both.
- Any working storage block passed on a data level to the activated program
is released by TPF/APPC.
- See Programming Considerations for Basic Conversation Functions for additional programming considerations relating to the
TPF/APPC basic conversation functions.
Examples
#include <tppc.h>
unsigned int resource_id;
struct tppc_return_codes return_code;
unsigned char pgm[4];
.
.
.
.
tppc_activate_on_confirmation(&resource_id,&return_code, \
AOC_CONFIRM,AOC_D5,NULL,pgm);
. /* Normal processing path */
.
.
Related Information