gtpc2mb6 | C/C++ Language Support User's Guide |
This function informs the remote transaction program that the local TPF
transaction program detected an error.
Format
#include <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 45.
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 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
TPF transaction program to enter receive state and thereby place
the remote program in send or send-pending state.
The local 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
TPF transaction program detected an error.
#include <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 */
.
.
Related Information