-Waits for information to arrive on the specified conversation and then receives the information. If
information is already available, the transaction program receives it without waiting. The information can be data, conversation status, or a request for confirmation.
APPC/PC returns control to the transaction program and indicates the type of information received.
The transaction program can issue this verb when the conversation is in either receive or send state. If the conversation is in send state, the LU first flushes its send buffer, sending all buffered information and the SEND indication to the remote transaction program. This action places the local conversation in receive state. The LV then waits for information to arrive from the remote transaction program. The remote transaction program sends data to the local transaction program after it receives the SEND indication.
Supplied Parameters:
TP_ID (variable) CONV_ID (variable) DATA_PTR (variable) MAX_LENGTH (variable) Returned Parameters:
RETURN_CODE (variable) DATA_LENGTH (variable) DATA (see DATA_PTR) WHAT_RECEIVED (variable) REQUEST_TO_SEND_RECEIVED
(YES) (NO)
Supplied Parameters:
TP _ID specifies the identifier for the transaction program issuing this verb. The application subsystem receives this value from APPCjPC when it starts the transaction
program. For more information on the TP _ID parameter, see "CREATE_TP" on page 5-66 or "TP _STARTED" on page 5-58.
CONY _ID specifies the conversation ID of the
conversation on which the local transaction program is to receive data.
DATA_PTR specifies the address of the buffer that is to accept the received data.
MAX_LENGTH specifies the maximum amount of data (in bytes) that the program is to receive. Values between
o
and 65535 are valid for this parameter, but the sum of this value and the offset portion of DATA_PTR must not exceed 65535. This limit keeps the incoming data from crossing a segment boundary.Returned Parameters:
RETURN_CODE indicates the result of verb execution.
The MC_RECEIVE_AND_WAIT return codes are:
• PARAMETER_CHECK
BAD_TP _ID: APPCjPC does not recognize the specified TP _ID.
BAD_CONV_ID: APPCjPC does not recognize the specified CONY _ID.
DATA AREA ACROSS_SEGMENT: The data receiving area crosses a segment boundary .
• STATE_CHECK
RCV_AND_WAIT_BAD STATE: The conversation is not in send or receive state.
For detailed information on the following return codes, see "Understanding Mapped Conversation Return Codes"
on page .6-3 and Appendix C, "Verb Return Codes."
• INCOMPLETE_ALTERED_ VERB
• OK
• PROG_ERROR_NO_TRUNC
• PROG_ERROR_PURGING.
DATA_LENGTH indicates the actual amount of data the transaction program received up to the maximum
(MAX_LENGTH). The value of this variable is 0 if the program receives information other than data, or no information at all.
DATA from the partner transaction program is received in the buffer specified by the address in the DAT A_PTR parameter. APPCjPC does not place any information in this buffer when the program receives information other than data, as indicated by the WHAT_RECEIVED parameter.
WHAT_RECEIVED indicates what the transaction program received. The transaction program should examine this variable only when RETURN_CODE indicates OK. APPCjPC does not place any information in this variable when RETURN_CODE indicates other than OK.
• DATA_ COMPLETE indicates that the transaction program has received a complete data record, or the last remaining portion of a data record.
6-48 MC_RECEIVE_AND_WAIT
• DATA_INCOMPLETE indicates that the transaction program has received an incomplete data record. The transaction program can issue another
MC_RECEIVE_AND_ WAIT or
MC_RECEIVE_IMMEDIATE (or more than one) to receive the remaining data.
• SEND indicates that the remote transaction program has entered receive state, thereby placing the local transaction program in send state. After receiving the SEND indication, the local transaction program can issue the MC_SEND_DATA verb to send data to the remote program.
• CO NFIRM indica tes that the remote transaction program has issued MC_CONFIRM, requesting the local transaction program to respond by issuing MC_CONFIRMED. The program may respond, instead, by issuing MC_SEND_ERROR.
• CONFIRM_SEND indicates that the remote transaction program has issued
MC_PREPARE_TO_RECEIVE with
TYPE(SYNC_LEVEL), and the synchronization level is CONFIRM. The local transaction program can respond by issuing MC_CONFIRMED or
MC_SEND_ERROR.
• CONFIRM_DEALLOCATE indicates that the remote transaction program has issued MC_DEALLOCATE with TYPE(SYNC_LEVEL), and the synchronization level is CONFIRM. The local transaction program can respond by issuing MC_CONFIRMED or
MC_SEND_ERROR.
REQUEST_TO_SEND_RECEIVED indicates whether the local LU has received a REQUEST_TO_SEND. The indication is either YES or NO.
• YES indicates that the local LU has received a REQUEST_TO_SEND notification from the remote transaction program. The remote transaction program has issued MC_REQUEST_TO_SEND, requesting the local transaction program to enter receive state and
thereby place the remote transaction program in send state.
• NO indicates that the local LU has not received a REQUEST_TO_SEND notification from the remote transaction program.
State Changes:
The following state changes occur when the RETURN_CODE parameter indicates OK. For information on state changes when RETURN_CODE indicates other than OK, see "Understanding Mapped Conversation Return Codes" on page 6-3.
• The conversation enters receive state when the verb is issued in send state and WHAT_RECEIVED indicates DATA_COMPLETE or DATA_INCOMPLETE.
• The conversation enters send state when WHAT_RECEIVED indicates SEND.
• The conversation enters confirm state when WHAT_RECEIVED indicates CONFIRM,
CONFIRM_SEND, or CONFIRM_DEALLOCATE.
• No state change occurs when the transaction program issues MC_RECEIVE_AND_WAIT in receive state and WHAT_RECEIVED indicates
DATA_COMPLETE or DATA INCOMPLETE.
Notes:
1. When the transaction program issues
MC_RECEIVE_AND_WAIT in send state, the LU implicitly executes an MC_PREPARE_TO_RECEIVE with TYPE(FLUSH) before executing the
MC_RECEIVE_AND_WAIT. See the description of MC_PREPARE_TO_RECEIVE for details of this function.
2. The mapped conversation protocol boundary provides for sending and receiving only data records. Unlike the logical records defined for the basic conversation
protocol boundary, data records contain only data;
they do not contain the logical record length field.
3. The MC_RECEIVE_AND_WAIT verb can receive only as much of the data record as the program specifies using the MAX_LENGTH parameter. The WHAT_RECEIVED parameter indicates whether the transaction program has received a complete or incomplete data record, as follows:
• The WHAT_RECEIVED parameter indicates DAT A_COMPLETE after the transaction program receives a complete data record or the last portion of a data record. The length of the record (or portion of the record) is equal to (or less than) the length specified on the MAX_LENGTH parameter.
• The WHAT_RECEIVED parameter indicates DATA_INCOMPLETE after the transaction program receives a portion of a data record other than the last remaining portion. APPC fPC detects that the data record is incomplete because the remaining length of the record is greater than the length specified on the MAX_LENGTH parameter.
The amount received equals the length specified.
The transaction program must issue another MC_RECEIVE_AND_WAIT (or possibly more than one) to receive the rest of the data record.
4. A program can use MC_RECEIVE_AND_ WAIT with MAX_LENGTH(O) to determine the type of
information that is available without actually receiving data. The RETURN_CODE and WHAT_RECEIVED parameters provide this information as usual. However, the transaction program receives no data in this case.
5. The transaction program receives only one kind of information at a time. For example, it may receive data or a CONFIRM request, but it cannot receive both at the same time. The RETURN_CODE and WHAT_RECEIVED parameters indicate to the
program the kind of information the program receives.
6. The local transaction program usually receives a REQUEST_TO_SEND notification when it is in send state. APPCjPC reports this request to the local transaction program on an MC_SEND_DATA verb or an MC_SEND_ERROR verb issued in send state.
However, the local transaction program can receive notification when the program is in receive state in the following cases:
• When the local transaction program just entered receive state and the remote transaction program issues MC_REQUEST_TO_SEND before it enters send state.
• When the remote transaction program has just entered receive state by using the
MC_PREPARE_TO_RECEIVE verb (not MC_RECEIVE_AND_ WAIT), and then issuing MC_REQUEST_TO_SEND before the local transaction program responds by entering send state. This ambiguity can occur because
MC_REQUEST_TO_SEND is an expedited request and this request can, therefore, arrive ahead of the request carrying the SEND indication.
The local transaction program might not be able to distinguish this case from the preceding case. The remote transaction program can avoid this
ambiguity by waiting until it receives information from the local transaction program before it issues the MC_REQUEST_TO_SEND.
• The remote program issues the
MC_REQUEST_TO_SEND in send state.