gtpc2mb1 | 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.
Format
#include <tpfmap.h>
void cmrcv(unsigned char *conversation_ID,
unsigned char *buffer,
signed int *requested_length,
signed int *data_received,
signed int *received_length,
signed int *status_received,
signed int *request_to_send_received,
signed int *return_code);
- conversation_ID
- This is a pointer to an 8-byte character array that contains the
conversation ID. This conversation ID must be the ID returned by the
cminit (INITIALIZE) or cmaccp (ACCEPT_CONVERSATION) that
started this conversation.
- buffer
- This is a pointer to an array of characters where the data is placed on
return. The area only contains data if return_code is CM_OK or
CM_DEALLOCATED_NORMAL and data_received is not
CM_NO_DATA_RECEIVED. The area must be large enough to hold the
number of bytes specified by requested_length.
- requested_length
- This is a pointer to a 4-byte field that specifies the maximum amount of
data the program is to receive. The value must be from
0-32 767.
- data_received
- This is a pointer to a 4-byte field that indicates if the program received
data. This indication is valid only if return_code is CM_OK or
CM_DEALLOCATED_NORMAL. Possible values are:
- CM_NO_DATA_RECEIVED
- This value indicates that no data was received.
- CM_COMPLETE_DATA_RECEIVED
- This value indicates that a complete logical record or the last remaining
portion of a logical record was received.
- CM_INCOMPLETE_DATA_RECEIVED
- This value indicates that less than a complete logical record was received
by the local TPF transaction program. Another cmrcv must be
called to get the remaining data.
- received_length
- This is a pointer to a 4-byte field that, on return, contains the number
of bytes of data that were received. If the program does not receive
data, this parameter is invalid.
- status_received
- This is a pointer to a 4-byte field that, on return, contains an
indication of the conversation status. The possible values are:
- CM_NO_STATUS_RECEIVED
- This value indicates that no conversation status was received by the
program. Data may have been received.
- CM_SEND_RECEIVED
- This value indicates that the remote program has entered
receive state. If data_received is
CM_COMPLETE_DATA_RECEIVED, the local program enters
send-pending state. If data_received is
CM_NO_DATA_RECEIVED, the local program enters send
state.
- CM_CONFIRM_RECEIVED
- This value indicates that the remote program requested the local program
to do a cmcfmd function to synchronize processing. The local
program must call a cmcfmd, cmserr, or cmdeal
function (with deallocate_type set to
CM_DEALLOCATE_ABEND).
- CM_CONFIRM_SEND_RECEIVED
- This value indicates that the remote program has entered
receive state and requested confirmation. The local program
must call a cmcfmd, cmserr, or cmdeal
function (with deallocate_type set to
CM_DEALLOCATE_ABEND).
- CM_CONFIRM_DEALLOC_RECEIVED
- This value indicates that the remote program has deallocated the
conversation with confirmation requested. The local program must call a
cmcfmd, cmserr, or cmdeal function (with
deallocate_type set to CM_DEALLOCATE_ABEND).
- request_to_send_received
- This is a pointer to a 4-byte field where a REQUEST_TO_SEND notification
is placed. Possible values are:
- CM_REQ_TO_SEND_RECEIVED
- This value indicates that the local program received a REQUEST_TO_SEND
notification from the remote program. This is a request that the local
program enter receive state, which allows the remote program to
enter send state.
- CM_REQ_TO_SEND_NOT_RECEIVED
- This value indicates that a REQUEST_TO_SEND notification was not
received.
- return_code
- This is a pointer to a 4-byte field where the return code is to be
placed.
Return Codes
The following is a list of return codes that can be returned to the program
that called the cmrcv function. A complete list of the
return codes and their definitions can be found in Table 45.
- CM_OK
- CM_CONVERSATION_TYPE_MISMATCH
- CM_DEALLOCATED_ABEND
- CM_DEALLOCATED_NORMAL
- CM_PRODUCT_SPECIFIC_ERROR
- CM_PROGRAM_ERROR_NO_TRUNC
- CM_PROGRAM_ERROR_PURGING
- CM_PROGRAM_PARAMETER_CHECK -- Either conversation_ID or
requested_length is invalid.
- CM_PROGRAM_STATE_CHECK -- The conversation is not in send,
send-pending, or receive state.
- CM_RESOURCE_FAILURE_NO_RETRY
- CM_RESOURCE_FAILURE_RETRY
- CM_SVC_ERROR_NO_TRUNC
- CM_SVC_ERROR_PURGING
- CM_SYNC_LVL_NOT_SUPPORTED_PGM
- CM_TP_NOT_AVAILABLE_NO_RETRY
- CM_TP_NOT_AVAILABLE_RETRY
- CM_TPN_NOT_RECOGNIZED.
Programming Considerations
- You can execute this function on any I-stream.
- The conversation must be in one of the following states:
receive
send
send-pending.
- The value supplied in conversation_ID must be the conversation ID
returned by the cmaccp or cminit function.
- There are no characteristics that modify this function.
- The conversation enters receive state if the conversation was
in send or send-pending state, return_code is
CM_OK, and status_received is CM_NO_STATUS_RECEIVED.
- The conversation enters send state if status_received
is CM_SEND_RECEIVED and data_received is
CM_NO_DATA_RECEIVED.
- The conversation enters send-pending state if
status_received is CM_SEND_RECEIVED and
data_received is CM_COMPLETE_DATA_RECEIVED.
- The conversation enters confirm state when
status_received is CM_CONFIRM_RECEIVED.
- The conversation enters confirm-send state when
status_received is CM_CONFIRM_SEND_RECEIVED.
- The conversation enters confirm-deallocate state when
status_received is CM_CONFIRM_DEALLOC_RECEIVED.
- The mapped conversation support must be able to write to the
buffer.
- Both data and status can be returned on the same cmrcv.
A REQUEST_TO_SEND also can be returned on the same call with data or
status.
- 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.
- If the program does not receive any data in a certain amount of time, the
conversation is terminated and cmrcv returns with
return_code set to CM_PRODUCT_SPECIFIC_ERROR. The amount of
time that the system waits is determined by the value you specify for the
TPRECV parameter of the SNAKEY macro. See TPF
ACF/SNA Network Generation for information about the SNAKEY
macro.
- If return_code is CM_PROGRAM_STATE_CHECK or
CM_PROGRAM_PARAMETER_CHECK when the function ends, no other variable contains
valid information.
- When the program receives a complete data record or the last portion of a
data record, the data_received parameter is set to
CM_COMPLETE_DATA_RECEIVED. The amount of data is less than or
equal to the requested_length parameter.
- When the program receives a partial data record, data_received
parameter is set to CM_INCOMPLETE_DATA_RECEIVED. The amount of
data is less than or equal to the requested_length parameter.
- If requested_length is set to 0, the function acts as usual,
except no data is received once it is available.
Examples
The following example waits for information to arrive on the specified
conversation and then receives the information.
#include <tpfmap.h>
unsigned char convid[8];
unsigned char *buff;
signed int req_len;
signed int data_rec;
signed int rec_len;
signed int status;
signed int rtsr;
signed int rcode;
.
.
/* set conversation_ID with value returned from accept or initialize */
.
.
cmrcv(convid,buff,&req_len,&data_rec,&rec_len,&status,&rtsr,&rcode);
. /* normal processing path */
.
.
Related Information