gtpc2mag | C/C++ Language Support User's Guide |
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
- 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.
- The transaction program must check both the return code and the
WHAT_RECEIVED (whatrcv) indicator.
- Note:
- If the return code is not LU62RC_OK, whatrcv has no meaning and
should not be examined.
- If the value for length and data is NULL and the
WHAT_RECEIVED indicator indicates that data is returned to the transaction
program, one of the following occurred:
- The program received a complete logical record or the last remaining
portion of a complete logical record.2 The WHAT_RECEIVED indicator is set to
RECEIVE_WHATRCV_DATACOMPLETE.
- The program receives an incomplete logical record because it was
truncated.3
The data is presented in a 4KB working storage block on data level 0 in
AMSG format (defined by the AM0SG DSECT).
If an entire logical record or the beginning of a truncated record is
received, the complete logical record length is placed in the first 2 bytes of
the logical record (AM0TXT), followed by the text of the record.
If the last remaining portion of a logical record is received, the text of
the record is not preceded by a logical length field and begins at
AM0TXT.
If the complete logical record does not fit in a single block, the
remainder of the logical record is chained in 4KB, short-term file pool
records. The standard TPF forward chain field (AM0FWD) contains the
file address of the next segment of a logical record. A forward chain
field containing zeros denotes the end of the chain. The standard TPF
message length field (AM0CCT) contains the number of bytes of text in each of
the segments.4
If the entire logical record (or the beginning of a truncated record) is
received, the logical record length presented in the first 2 bytes of a
logical record is the length of the complete logical record, while the
contents of the AM0CCT field contains the physical length of each segment of a
logical record. If the completion of a logical record is received, the
sum of the AM0CCT fields of the segment indicates the total amount of data
received.
- If you specify the data and length parameters and the
WHAT_RECEIVED indicator indicates that data is returned to the transaction
program, one of the following occurred:
- The program received a complete logical record or the last remaining
portion of a complete logical record. The length of the record or
portion of the record is equal to or less than the length specified on the
length parameter. If the length received is less than the
value pointed to by the length parameter, the value is updated to
indicate the actual amount of data received. The WHAT_RECEIVED
indicator is set to RECEIVE_WHATRCV_DATACOMPLETE.
- The program receives an incomplete logical record, which can occur
because:
- The length of the logical record is greater than the length specified by
the length parameter; in this case, the amount received equals
the length specified.
- Only a portion of the logical record is available because it was
truncated, the portion being equal to or less than the length specified by the
length parameter. 3
The WHAT_RECEIVED indicator is set to
RECEIVE_WHATRCV_DATAINCOMPLETE. The program must issue another
tppc_receive (or possibly multiple tppc_receives) to
receive the remainder of the logical record.
- Note:
- A length parameter value of zero has no special significance.
The type of information available is indicated by the rcode parameter
and the whatrcv parameters, as usual. If data is available,
the whatrcv parameter contains
RECEIVE_WHATRCV_DATAINCOMPLETE, but the program receives no
data.
- The maximum size of a logical record is 32 767.
- On return, the value pointed to by the length parameter may have
been changed to show the amount of data actually received.
- If there is no data available, TPF's EVENT and POST facility is used
to suspend the ECB until data arrives. Because the ECB is suspended,
all unnecessary resources should be released before this verb is
issued. Failure to do so can cause serious system degradation.
- Note:
- You can avoid the problem of suspended ECBs by using the
tppc_activate_on_receipt function instead of
tppc_receive. See tppc_activate_on_receipt-Activate a Program after Information Received for more information.
- If the program does not receive any data in a certain amount of time,
TPF/APPC support issues a tppc_deallocate with
DEALLOCATE_TYPE_ABENDP to terminate the conversation. The
amount of time that the system waits is determined by the value you specify
for the TPRECV parameter on the SNAKEY macro. See TPF ACF/SNA Network Generation for information about the
SNAKEY macro.
- See Programming Considerations for Basic Conversation Functions for additional programming considerations relating to the
TPF/APPC basic conversation functions.
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).