gtpc2mb1C/C++ Language Support User's Guide

cmrcv-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.

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.

Programming Considerations

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