gtpc2mat | C/C++ Language Support User's Guide |
This function deallocates the specified conversation from the transaction
program. Depending on the value of the deallocate_type and
sync_level characteristics, a FLUSH or CONFIRM may be done
first. If the DEALLOCATE completes successfully, the conversation no
longer exists and the conversation_ID is no longer valid.
Format
#include <tpfmap.h>
void cmdeal(unsigned char *conversation_ID,
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.
- return_code
- This is a pointer to a 4-byte field where the return code is to be
placed.
Return Codes
The following are lists of return codes that can be returned to the program
that called the cmdeal function. A complete list of the
return codes and their definitions can be found in Table 45.
When deallocate_type is CM_DEALLOCATE_SYNC_LEVEL and
sync_level is CM_NONE, or deallocate_type is
CM_DEALLOCATE_FLUSH or CM_DEALLOCATE_ABEND, the possible
return codes are:
- CM_OK
- CM_PRODUCT_SPECIFIC_ERROR
- CM_PROGRAM_PARAMETER_CHECK -- The specified conversation_ID
is invalid.
- CM_PROGRAM_STATE_CHECK -- deallocate_type is
CM_DEALLOCATE_SYNC_LEVEL or CM_DEALLOCATE_FLUSH and the
conversation is not in send or send-pending
state.
When deallocate_type is CM_DEALLOCATE_SYNC_LEVEL and
sync_level is CM_CONFIRM, or when
deallocate_type is CM_DEALLOCATE_CONFIRM, 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_PROGRAM_STATE_CHECK -- The program is not in send or
send-pending state.
- 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.
Programming Considerations
- You can execute this function on any I-stream.
- If deallocate_type is CM_DEALLOCATE_SYNC_LEVEL,
CM_DEALLOCATE_FLUSH, or CM_DEALLOCATE_CONFIRM, the
conversation must be in send or send-pending
state.
- If deallocate_type is CM_DEALLOCATE_ABEND, the
conversation can be in any state.
- The value supplied in conversation_ID must be the conversation ID
returned by the cmaccp or cminit function.
- The following characteristics can affect this function:
- sync_level
- deallocate_type.
- If return_code is CM_OK, the conversation terminates.
- If return_code is CM_PROGRAM_ERROR_PURGING or
CM_SVC_ERROR_PURGING, the conversation enters receive state.
- When the DEALLOCATE is complete, the conversation identified by the
conversation ID is completed, and no further functions can be called for that
conversation.
- If the transaction program exits without deallocating a conversation, the
TPF system does not deallocate that conversation. The program should
call this function for all conversations before exiting.
- This function flushes the send buffer.
- When deallocate_type is CM_DEALLOCATE_SYNC_LEVEL and
sync_level is CM_CONFIRM, or if deallocate_type
is CM_DEALLOCATE_CONFIRM, and the return code indicates an error, the
conversation is not deallocated.
- When deallocate_type is CM_DEALLOCATE_SYNC_LEVEL and
sync_level is CM_CONFIRM, or if deallocate_type
is CM_DEALLOCATE_CONFIRM, TPF's EVENT and POST facility is used
to suspend the ECB until the program receives a confirmation reply.
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 deallocate_type characteristic is set to
CM_DEALLOCATE_CONFIRM, the normal response from the remote
transaction program is CONFIRMED. However, if the remote program issues
a DEALLOCATE TYPE=ABEND, the cmdeal return_code is
CM_DEALLOCATED_ABEND, and the conversation terminates. If the remote
transaction program issues a SEND_ERROR, the local program goes into
receive state, and the conversation continues.
- If deallocate_type is CM_DEALLOCATE_CONFIRM, and the
program does not receive a confirmation reply in a certain amount of time,
TPF/APPC support issues an unbind to terminate the conversation. The
amount of time that the system waits is determined by the value you specify
for the TPRECV parameter on the SNAKEY macro. See TPF ACF/SNA Network Generation for information about the
SNAKEY macro.
Examples
The following example deallocates a specified conversation.
#include <tpfmap.h>
unsigned char convid[8];
signed int rcode;
.
.
/* set conversation_ID with value returned from accept or initialize */
.
.
cmdeal(convid,&rcode);
. /* normal processing path */
.
.
Related Information