cmserr: Send error notification

This function informs the remote transaction program that the local z/TPF transaction program detected an error.

Format

#include   <tpf/tpfmap.h>
void       cmserr(unsigned char *conversation_ID,
                  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.
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 cmserr function. A complete list of the return codes and their definitions can be found in Table 1.

When the conversation is in send state, the possible return codes are:
  • CM_OK
  • CM_CONVERSATION_TYPE_MISMATCH
  • CM_DEALLOCATED_ABEND
  • CM_PRODUCT_SPECIFIC_ERROR
  • CM_PROGRAM_ERROR_PURGING
  • CM_PROGRAM_PARAMETER_CHECK — The specified conversation_ID is invalid.
  • CM_RESOURCE_FAILURE_NO_RETRY
  • CM_RESOURCE_FAILURE_RETRY
  • 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.
When the conversation is in receive state, the possible return codes are:
  • CM_OK
  • CM_DEALLOCATED_NORMAL
  • CM_PRODUCT_SPECIFIC_ERROR
  • CM_PROGRAM_PARAMETER_CHECK — The specified conversation_ID is invalid.
  • CM_RESOURCE_FAILURE_NO_RETRY
  • CM_RESOURCE_FAILURE_RETRY.
When the conversation is in send-pending state, the possible return codes are:
  • CM_OK
  • CM_DEALLOCATED_ABEND
  • CM_PRODUCT_SPECIFIC_ERROR
  • CM_PROGRAM_ERROR_PURGING
  • CM_PROGRAM_PARAMETER_CHECK — The specified conversation_ID is invalid.
  • CM_RESOURCE_FAILURE_NO_RETRY
  • CM_RESOURCE_FAILURE_RETRY
  • CM_SVC_ERROR_PURGING.
When the conversation is in confirm, confirm-send, or confirm-deallocate state, possible return codes are:
  • CM_OK
  • CM_PRODUCT_SPECIFIC_ERROR
  • CM_PROGRAM_PARAMETER_CHECK — The specified conversation_ID is invalid.
  • CM_RESOURCE_FAILURE_NO_RETRY
  • CM_RESOURCE_FAILURE_RETRY.
If the conversation is not in one of the states listed previously, the only possible return codes are:
  • CM_PROGRAM_PARAMETER_CHECK — The specified conversation_ID is invalid.
  • CM_PROGRAM_STATE_CHECK.

Programming considerations

  • You can execute this function on any I-stream.
  • The conversation can be in any state except initialize.
  • The value supplied in conversation_ID must be the conversation ID returned by the cmaccp or cminit function.
  • When the conversation is in send-pending state, the error_direction characteristic affects the way an error is reported to the remote program.

    If error_direction is set to CM_RECEIVE_ERROR, the return_code of the subsequent mapped conversation verb received by the remote program is set to CM_PROGRAM_ERROR_PURGING.

    If error_direction is set to CM_SEND_ERROR, the return_code of the subsequent mapped conversation verb received by the remote program is set to CM_PROGRAM_ERROR_NO_TRUNC. (See cmsed: Set the error_direction characteristic for more information on the send-pending state and the error_direction characteristic.)

  • When the conversation is in send or receive state, the remote program is informed of the error by one of the following return codes:
    • CM_PROGRAM_ERROR_NO_TRUNC — This indicates that the local program is in send state and found an error while processing data to be sent to the remote program.
    • CM_PROGRAM_ERROR_PURGING — This indicates that the local program is in receive state and found an error in the data received from the remote program.
  • When return_code is CM_OK, the local program enters send state.
  • If the conversation was in send state, this call causes the local program's send buffer to be flushed.
  • The transaction programs can use this function for various application level functions. For example, the program can call this function to truncate an incomplete logical record, to inform the remote program of an error it detected in data it received, or to reject a confirmation request.
  • If the local z/TPF transaction program calls cmserr while in receive state, purging of all buffered input occurs. The incoming information that is purged includes both data (logical records) and confirmation requests. In addition, if the confirmation request was due to the remote transaction program's calling cmdeal with deallocate_type set to CM_DEALLOCATE_CONFIRM, the DEALLOCATE request is also purged. After issuing the cmserr function from receive state, the local transaction program is in send state, and the remote transaction program is in receive state.
  • When the request_to_send_received parameter is CM_REQ_TO_SEND_RECEIVED, the remote program is requesting the local z/TPF transaction program to enter receive state and thereby place the remote program in send or send-pending state. The local z/TPF transaction program enters receive state by issuing cmrcv or cmptr. The remote partner program enters the corresponding send or send-pending state when it calls cmrcv and receives the SEND indication on the status_received parameter.
  • This verb resets or cancels posting. If posting is active and the conversation was posted, or if posting is active and the conversation was not posted, posting is canceled.
  • The truncation implied by the use of this verb can cause any of the following to be truncated:
    • Data sent by means of the cmsend function
    • Confirmation requests sent by means of cmcfm, cmptr, or cmdeal
    • Deallocation request sent by means of cmdeal with deallocate_type set to CM_DEALLOCATE_CONFIRM.

Examples

The following example informs the remote transaction program that the local z/TPF transaction program detected an error. 
#include <tpf/tpfmap.h>

      unsigned char convid[8];
      signed int    rtsr;
      signed int    rcode;
      .
      .
/* set conversation_ID with value returned from accept or initialize */
      .
      .
cmserr(convid,&rtsr,&rcode);
      .                       /*  normal processing path             */
      .
      .