Use the TPPCC general macro with the RECEIVE verb specified to wait for
information to arrive on the specified conversation and then receive the
information. If information is already available, the information is
received without waiting. The information received can be data,
conversation status, or a confirmation request.
The transaction program can issue this verb 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
- label
- A symbolic name can be assigned to the macro statement.
- RECEIVE
- Directs the TPPCC macro to perform the RECEIVE verb function.
- RESID
- Specifies the symbolic name of a field or a register pointing to a field
This is a 4-byte field in which the resource ID is supplied. This
resource ID must be the one assigned on the initial ALLOCATE for this
conversation or one that was assigned by an incoming ATTACH.
- FILL
- LL specifies that the program is to receive one 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.
TPF does not support the BUFFER option defined by the LU 6.2
architecture.
- WAIT
- YES is the only supported option, which performs the function of
RECEIVE_AND_WAIT. TPF does not support the RECEIVE_IMMEDIATE verb
function defined by the LU 6.2 architecture.
- LENGTH2
- Specifies the symbolic name of a field or a register pointing to a
field. This is a 2-byte field in which the maximum length of data to
receive is supplied. The value can be from 0 to 32767. When
control is returned to the TP, this variable contains the actual amount of
data the program received up to the maximum. If the TP receives
information other than data, this variable remains unchanged.
- DATA2
- Specifies the symbolic name of a field or a register pointing to a field
in which the program is to receive the data.
- RCODE
- Specifies the symbolic name of a field or a register pointing to a field
This is a 6-byte field in which the return code is placed. The return
code consists of a 2-byte primary return code followed by a 4-byte secondary
return code. The actual values returned are listed in Return Conditions.
- WHATRCV
- Specifies the symbolic name of a 1-byte field or a register that contains
the WHAT_RECEIVED indication. The WHAT_RECEIVED indication is one of
the following values:
- LU62WR_DATACOMPLETE
- Indicates that a complete logical record or the last remaining portion of
a logical record is received.
- LU62WR_DATAINCOMPLETE
- Indicates that less than a complete logical record was received by the
local TPF transaction program. This can be caused by the remote
transaction program issuing a verb that causes data truncation, such as
DEALLOCATE with one of the abend parameters.
- LU62WR_LL_TRUNCATED
- 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.
- LU62WR_CONFIRM
- Indicates that the remote program issued CONFIRM, requesting the local TPF
transaction program to respond by issuing CONFIRMED. The local TPF
transaction program can instead issue SEND_ERROR.
- LU62WR_CONFIRMSEND
- Indicates the remote program issued PREPARE_TO_RECEIVE with
TYPE=CONFIRM. The local TPF transaction program can respond by issuing
CONFIRMED or SEND_ERROR.
- LU62WR_SEND
- Indicates the remote program has entered receive state, placing
the local program in send state. The local TPF transaction
program can now issue SEND_DATA.
- LU62WR_CONFIRMDLLOC
- Indicates the remote program issued DEALLOCATE with TYPE=CONFIRM.
The local TPF transaction program can respond by issuing CONFIRMED or
SEND_ERROR.
- RTSRCVD
- Specifies the symbolic name of a 1-byte field or a register that contains
a value that indicates whether a REQUEST_TO_SEND has been received. The
REQUEST_TO_SEND_RECEIVED indication is:
- LU62_RTSND_RCVDYES
- Indicates a REQUEST_TO_SEND indication has been received from the remote
transaction program. The remote program issued REQUEST_TO_SEND,
requesting the local TPF transaction program to enter receive state
and placing the remote transaction program in send state.
Any other value indicates that a REQUEST_TO_SEND notification has not been
received.
Entry Requirements
- If you omit the DATA and LENGTH parameters, D0 must be available for
use. RECEIVE passes data to the transaction program on this data level
as described in the programming considerations.
- If you specify the DATA and LENGTH parameters, the entire area referenced
by the DATA and LENGTH must be addressable by the TPF/APPC support
code.
- The conversation must be in send or receive
state.
- See Entry Requirements for the entry requirements relating to the TPPCC macro in
general.
Return Conditions
- If the LENGTH parameter was specified, the field can be updated to
indicate the amount of data received.
- The results of the verb are indicated by the value returned in
RCODE. The valid return codes are listed in the following section,
"Return Codes".
- See Return Conditions for the return conditions relating to the TPPCC macro in
general.
- The following table contains a list of the primary and secondary return
codes that can be returned to the program that issued the RECEIVE verb.
A complete list of return codes and their definitions can be found in Table 11 and in Table 12.
Symbolic Name
| Primary Code
| Secondary Code
|
LU62RC_OK
| 0000
|
|
LU62RC_PARAMETER_CHECK
| 0001
|
|
LU62RC_PK_BAD_TCBID
| ....
| 00000001
|
LU62RC_PK_BAD_CONVID
| ....
| 00000002
|
LU62RC_INVALID_LENGTH
| ....
| 00000006
|
LU62RC_STATE_CHECK
| 0002
|
|
LU62RC_SKRECEV_BADSTATE
| ....
| 000000B1
|
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_NORETRY
| 0010
|
|
LU62RC_SVCERR_NOTRUNC
| 0011
|
|
LU62RC_SVCERR_TRUNC
| 0012
|
|
LU62RC_SVCERR_PURGING
| 0013
|
|
LU62RC_TPF_ABEND
| FFFF
|
|
Programming Considerations
- If you specify a register for a keyword value, the register must be
enclosed in parentheses and in the range R1-R7.
- The value supplied in RESID must be the resource ID returned by the
ALLOCATE verb 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 you do not specify the LENGTH and DATA parameters and the WHAT_RECEIVED
indicator indicates that data is returned to the transaction program, then one
of the following occurred:
- The program received a complete logical record or the last remaining
portion of a complete logical record.3 The WHAT_RECEIVED indicator is set to
LU62WR_DATACOMPLETE.
- The program received an incomplete logical record because it was
truncated.4
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.5
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 segments' AM0CCT fields 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, then 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
LU62WR_DATACOMPLETE.
- The program received 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. 4
The WHAT_RECEIVED indicator is set to LU62WR_DATAINCOMPLETE. The
program must issue another RECEIVE (or possibly multiple 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 LU62WR_DATAINCOMPLETE, but the program receives no data.
- The maximum size of a logical record is 32,767.
- If there is no data available, TPF's EVENT and POST facility is used
to suspend the ECB until data arrives. Since 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 ACTIVATE_ON_RECEIPT
verb instead of RECEIVE. See TPPCC ACTIVATE_ON_RECEIPT for more information.
- If the program does not receive any data within a certain amount of time,
the TPF/APPC support issues a DEALLOCATE TYPE=ABEND 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 the programming considerations relating to the TPPCC
macro in general.
Examples
SYMB100 TPPCC RECEIVE, X
RESID=EBW004, X
FILL=LL, X
DATA=(R3), X
LENGTH=(R2), X
WAIT=YES, X
RCODE=EBW064, X
WHATRCV=EBW016, X
RTSRCVD=EBSW01
Footnotes:
- 2
-
The LENGTH parameter is a supplied and returned parameter. If used,
both DATA and LENGTH must be specified.
- 3
-
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 LU62WR_DATAINCOMPLETE.
- 4
-
Truncated logical records can be received if the remote transaction program
caused data truncation by issuing SEND_ERROR or DEALLOCATE TYPE=any
ABEND.
- 5
-
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).