gtpc2magC/C++ Language Support User's Guide

tppc_receive-Receive Information

This function waits for information to arrive on the specified conversation and then receives the information. If information is already available, the information is received without waiting. The information received may be data, conversation status, or a confirmation request.

The transaction program can call this function when the conversation is in send state. In this case, the SEND indication is sent to the remote transaction program, and the local TPF side of the conversation is changed to receive state and waits for information to arrive. The remote program can send data to the local program after it receives the SEND indication.

Format

#include   <tppc.h>
void       tppc_receive(unsigned int *resid,
                        struct tppc_return_codes *rcode,
                        enum t_receive_whatrcv *whatrcv,
                        enum t_rtsrcvd *rtsrcvd,
                        enum t_receive_fill fill,
                        enum t_receive_wait wait,
                        unsigned char *data,
                        unsigned short int *length);

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.

whatrcv
This is a pointer to a 1-byte field that contains the enumeration type t_receive_whatrcv, where the WHAT_RECEIVED indication is placed. The WHAT_RECEIVED indication is one of the following:

RECEIVE_WHATRCV_DATACOMPLETE
This value indicates that a complete logical record or the last remaining portion of a logical record is received.

RECEIVE_WHATRCV_DATAINCOMPLETE
This value indicates that less than a complete logical record is received by the local TPF transaction program. This can be caused by the remote transaction program calling a function that causes data truncation, such as, tppc_deallocate with one of the abend parameters.

RECEIVE_WHATRCV_LL_TRUNCATED
This value indicates that the 2-byte length field of a logical record was truncated after the first byte. The TPF/APPC support code discards the truncated length field; it is not received by the program.

RECEIVE_WHATRCV_CONFIRM
This value indicates that the remote program called tppc_confirm requesting the local TPF transaction program to respond by issuing tppc_confirmed. The local TPF transaction program can instead call tppc_send_error.

RECEIVE_WHATRCV_CONFIRMSEND
This value indicates that the remote program called tppc_prepare_to_receive with type=PREP_TO_RECEIVE_TYPE_CONFIRM. The local TPF transaction program can respond by issuing tppc_confirmed or tppc_send_error.

RECEIVE_WHATRCV_SEND
This value indicates that the remote program has entered receive state, placing the local program in send state. The local TPF transaction program can now call tppc_send_data.

RECEIVE_WHATRCV_CONFIRMDLLOC
This value indicates that the remote program called tppc_deallocate with type=DEALLOCATE_TYPE_CONFIRM. The local TPF transaction program can respond by issuing tppc_confirmed or tppc_send_error.

rtsrcvd
This is a pointer to a 1-byte field that contains the enumeration type t_rtsrcvd, where the REQUEST_TO_SEND_RECEIVED indication is placed. The value of the REQUEST_TO_SEND_RECEIVED indication is RTSRCVD_YES, indicating that a REQUEST_TO_SEND indication was received from the remote transaction program. The remote program called tppc_request_to_send requesting the local TPF transaction program to enter receive state and placing the remote transaction program in send state.

fill
This argument must belong to the enumeration type t_receive_fill, defined in tppc.h. Use the value RECEIVE_FILL_LL, which specifies that the program is to receive 1 complete or truncated logical record, or a portion of a logical record that is equal to the length specified by the length parameter. See the programming considerations for an explanation of the record format.

Note:
The TPF system does not support the BUFFER option defined by the LU 6.2 architecture.

wait
This argument must belong to the enumeration type t_receive_wait, defined in tppc.h. Use the value RECEIVE_WAIT_YES, which performs the function of RECEIVE_AND_WAIT.
Note:
The TPF system does not support the RECEIVE_IMMEDIATE function defined by the LU 6.2 architecture.

data
This is a pointer to the location in memory that will receive the data. It can also be a NULL pointer, which indicates the data is to be placed in a block on data level 0 in AM0SG format.1

length
This is a pointer to a 2-byte field that specifies the maximum length of data the program can receive. The value can be from 0-32 767. The value can also be a NULL pointer but only if data is also NULL.1 If both arguments are NULL, the length of the data received is determined by the logical record length.

When control is returned to the transaction program, the value is the actual amount of data the program received up to the maximum. If the program receives information other than data, the value remains unchanged.

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_receive 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_PARAMETER_CHECK 0001  
  LU62RC_PK_BAD_TCBID .... 00000001
  LU62RC_PK_BAD_CONVID .... 00000002
  LU62RC_PK_BAD_OPTION .... 00C62074
  LU62RC_INVALID_LENGTH .... 00000006
LU62RC_STATE_CHECK 0002  
  LU62RC_SKRECEV_BADSTATE .... 000000B1
LU62RC_ALLOC_ERROR 0003  
  LU62RC_SECURITY_NOT_VALID .... 080F6051
  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_NORETRY 0010  
LU62RC_SVCERR_NOTRUNC 0011  
LU62RC_SVCERR_TRUNC 0012  
LU62RC_SVCERR_PURGING 0013  
LU62RC_TPF_ABEND FFFF  

Programming Considerations

Examples

The following example waits for information to arrive on the specified conversation and then receives the information.

#include <tppc.h>
 
      unsigned int               resource_id;
      struct   tppc_return_codes return_code;
      enum     t_receive_whatrcv what_received;
      enum     t_rtsrcvd         request_received;
      unsigned short int         length;
      unsigned char              *data;

  ·
  ·
  ·
/* set up resource_id with the value returned from the allocate verb */
  ·
  ·
  ·
tppc_receive(&resource_id,&return_code,&what_received,&request_received, \ RECEIVE_FILL_LL,RECEIVE_WAIT_YES,data,&length); /* normal processing path */
  ·
  ·
  ·

Related Information


Footnotes:

1
If either data or length is NULL while the other parameter is not NULL, a parameter check is issued.

2
The last remaining portion of a complete logical record can be returned if this RECEIVE followed a RECEIVE that used the data and length parameters and had a WHAT_RECEIVED indicator of RECEIVE_WHATRCV_DATAINCOMPLETE.

3
Truncated logical records can be received if the remote transaction program caused data truncation by issuing tppc_send_error or tppc_deallocate type= any ABEND.

4
The AM0CCT field is equal to the actual text count in this block plus 5, which is the length of the AM0SG filler. Thus the physical length of data in a block is (AM0CCT - 5).