gtpc2ma6 | 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 and activate a different ECB
at the program specified after information has been received. The
information received may be data, conversation status, or a confirmation
request.
Format
#include <tppc.h>
void tppc_activate_on_receipt(unsigned int *resid,
struct tppc_return_codes *rcode,
enum t_aor_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 is to be placed.
- level
- This specifies a data level that contains a working storage block to be
passed to the activated program. After the information is received, 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_aor_dl, defined in tppc.h. Use a value
in the range of AOR_D1 to AOR_DA. If no block will be
passed, use the value AOR_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 after the information is
received. 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 information is received. 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_receipt 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_AOR_INCOMPLETE
| ....
| 00000009
|
LU62RC_PARAMETER_CHECK
| 0001
|
|
LU62RC_PK_BAD_TCBID
| ....
| 00000001
|
LU62RC_PK_BAD_CONVID
| ....
| 00000002
|
LU62RC_PK_BAD_PROG
| ....
| 000000F2
|
LU62RC_PK_BAD_PARM
| ....
| 000000F3
|
LU62RC_STATE_CHECK
| 0002
|
|
LU62RC_SKRECEV_BADSTATE
| ....
| 000000B1
|
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 processing of the RECEIVE
function.
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_DLLOC_NORMAL
| 0009
|
|
LU62RC_PGMERR_NOTRUNC
| 000C
|
|
LU62RC_PGMERR_TRUNC
| 000D
|
|
LU62RC_PGMERR_PURGING
| 000E
|
|
LU62RC_CONVFAIL_RETRY
| 000F
|
|
LU62RC_CONVFAIL_NO_RETRY
| 0010
|
|
LU62RC_SVCERR_NOTRUNC
| 0011
|
|
LU62RC_SVCERR_TRUNC
| 0012
|
|
LU62RC_SVCERR_PURGING
| 0013
|
|
LU62RC_TPF_ABEND
| FFFF
|
|
Programming Considerations
- The conversation must be in send or receive
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 the tppc_receive
function. If there is no information available to satisfy a RECEIVE
when the tppc_activate_on_receipt function is called, an ECB is not
suspended while waiting for the information to arrive. When information
arrives, TPF/APPC support creates a new ECB, performs a RECEIVE, and activates
the program specified by pgm. The information that was
received is passed to the activated program.
- When the program specified by pgm is activated, this indicates
that a RECEIVE was done. The return codes are passed to the program in
contiguous memory starting at EBX008. Check these codes to determine
the success of the RECEIVE. If the return code is LU62RC_OK, check the
WHAT_RECEIVED field (passed at EBX014) to see what was received. If
WHAT_RECEIVED is DATA (COMPLETE or INCOMPLETE), the data is passed to the
program on D0.
- 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 there is information available when the
tppc_activate_on_receipt function is called, TPF/APPC activates the
program specified by pgm right away with a new ECB. The
information is not returned to the program that calls this function.
- 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 field[8];
unsigned char pgm[4];
·
·
·
tppc_activate_on_receipt(&resource_id,&return_code, \
AOR_NO_DL,field,pgm);
/* Normal processing path */
·
·
·
Related Information