ATMI to CPI-C Function Mapping

The following tables list the most common ATMI function calls and show how their parameters map to CPI-C verbs. The mappings are listed by function call in the following order:

The tables show the parameters of the ATMI call, the contents or meaning of the parameters, and notes on usage with the CPI-C verbs.

Table 1-1 tpcall
tpcall()	Parameters	Contents	CPI-C Notes
svc		Service Name	Used in CMALLC to identify the CICS transaction to be invoked.
idata		User data	This data is sent in CMSENDs until completely transmitted.
len		Length of User data
odata		Reply data	CMRCV receives the data until it has been completely transmitted (data_received is set to CM_COMPLETE_DATA_RECEIVED) and return code is set to CM_OK or CM_DEALLOCATE_NORMAL.
olen		Reply data length
flags	`TPNOTRAN`	Not part of a transaction
	`TPNOCHANGE`	N/A	Local
	`TPNOBLOCK`	N/A	Local
	`TPNOTIME`	N/A	Local
	`TPSIGRSTRT`	N/A	Local

Table 1-2 tpacall
tpacall()	Parameter	Contents	CPIC Notes
svc		Service Name	Used in CMALLC to identify the CICS transaction to be invoked.
data		User data	This data is sent in CMSENDs until completely transmitted.
len		Length of user data
flags	`TPNOREPLY`	false	The last data is sent with a CMSEND with send_type set to CMSEND_AND_PREP_TO_RECEIVE. This changes the state of the conversation to receive and a CMRCV is issued to await the reply.
	`TPNOREPLY`	true	Since no reply is expected, a CMDEAL deallocates the conversation after all data has been received.
	`TPNOTRAN`	Not part of a transaction
	`TPNOBLOCK`	N/A	Local
	`TPNOTIME`	N/A	Local
	`TPSIGRSTRT`	N/A	Local

Table 1-3 tpgetrply
tpgetrply()	Parameters	Contents	CPIC Notes
cd		call descriptor	The call descriptor is mapped to the CONVID returned by the CMINIT when the LU6.2 was initiated.
data		User data	Data received from CMRCV if WHAT_RECEIVED set to DATA_COMPLETE.
len		Length of user data
flags	`TPGETANY`	If true, data is returned from any conversation. If false, data is returned from conversation associated with the `cd`	Data available on any conversation is returned to the requestor.
	`TPNOCHANGE`	Local to the requestor	Limited buffer types supported.
	`TPNOBLOCK`	N/A	Local
	`TPNOTIME`	N/A	Local
	`TPSIGRSTRT`	N/A	Local

Table 1-4 tpservice
tpservice()	Parameters	Contents	CPIC Notes
svcinfo		Service information and data	User Data captured from a CMRCV populates the TPSVCINFO structure user data area. Service characteristics are obtained from the service attributes in the DMCONFIG and UBBCONFIG files.
name		Service name	The service name associated with the 8 character RNAME sent from CICS.
data		User data	Data captured from CMRCV.
len		Length of user data
cd		call descriptor	The call descriptor associated with the CONVID returned by the CMINIT when the LU6.2 was initiated.
appkey		32-bit key (if used)	For security.
cltid		set by Oracle Tuxedo	For security.
flags	`TPCONV`	If true, service is conversational.
	`TPTRAN`	N/A	.
	`TPNOREPLY`	If true, requestor not expecting a reply.	The conversation is terminated with a CMDEAL normal.
	`TPSENDONLY`	N/A	If set, the CPIC conversation in CICS should be in receive state. If not set, the CICS CPIC conversation state will be in send state.
	`TPRECVONLY`	N/A	If set, the CPIC conversation in CICS remains in send state.

Table 1-5 tpreturn
tpreturn()	Contents	CPIC Notes
rval	`TPSUCCESS`	Set to TPSUCCESS when conversation terminates with a normal deallocation.
rval	`TPSVCERR`	Set to TPESVCERR when the conversation has terminated with a non-normal deallocation type or other error.
rcode	Set by the application	N/A
data	User data	Data is returned to the CICS transaction from a successful CMRCV with data received set to CM_DATA_COMPLETE and return code of CM_DEALLOCATE_NORMAL. If the service fails, no data is returned to the caller and the conversation is deallocated abnormally.
len	Length of data returned	0 < data <= 32K
flags	N/A	N/A

Table 1-6 tpcancel
tpcancel()	Parameters	Contents	CPIC Notes
cd		The connection descriptor on which a `tpgetreply()` is waiting.	CMDEAL abnormal is issued on the conversation with CONVID mapped from call descriptor.

Table 1-7 tpconnect
tpconnect()	Parameters	Contents	CPIC Notes
svc		The local service name representing the service to be invoked. in CICS	The name is used to find the RNAME. The RNAME should match the TPName in CICS and will be used by CMINIT and CMALLC to initiate and allocate the conversation.
data		User data	This data is sent in CMSENDs until completely transmitted.
len		Length of User data
flags	`TPNOTRAN`	True
	`TPSENDONLY`	If true, the conversation stays in or changes to send state	The conversation remains in send state. This is the default.
	`TPRECVONLY`	If true, the conversation stays in or changes to receive state	Immediately after the allocate Oracle Tuxedo sends a CMSEND with no data and send_type set to CM_SEND_AND_PREP_TO_RECEIVE.
	`TPNOBLOCK`	N/A	Local
	`TPNOTIME`	N/A	Local
	`TPSIGRSTRT`	N/A	Local

Table 1-8 tpsend
tpsend()	Parameters	Contents	CPIC Notes
cd		The connection descriptor	This locally assigned connection descriptor has been mapped to the CONVID returned in the CMINIT and CMALLC on behalf of the `tpconnect().`
data		User data	ASCII/EBCDIC conversion may be required before sending to CICS.
len		Length of User data
flags	`TPRECVONLY`	If true, the conversation changes to receive state.	The state of the conversation changes from send to receive. A CMSEND is sent with send_type set to CM_SEND_AND_PREP_TO_RECEIVE.
	`TPNOBLOCK`	N/A	Local
	`TPNOTIME`	N/A	Local
	`TPSIGRSTRT`	N/A	Local
revent	`TPEV_DISCONIMM`	If set, the LU6.2 conversation has been terminated abnormally.	If the return code from a CMRCV is deallocate_abnormal, the conversation is terminated. A disconnect event is sent to the sending process.
	`TPEV_SVCERR`	If set, the LU6.2 conversation has been terminated abnormally.	Any return code other than CM_OK or CM_DEALLOCATE_NORMAL is treated as a TPEV_SVCERR.
	`TPEV_SVCFAIL`	If set, the LU6.2 conversation has been terminated abnormally.	If the return code from CMRCV is CM_TP_NOT_AVAIL_NO_RETRY or CM_TP_RESOURCE_FAILURE_NO_RETRY, `revent` is set to TPEV_SVCFAIL.

Table 1-9 tprecv
tprecv()	Parameters	Contents	CPIC Notes
cd		The connection descriptor	This locally assigned connection descriptor has been mapped to the CONVID returned in the CMINIT and CMALLC issued by the initiator of this conversation.
data		User data	Date to be received using a CMRCV_immediate and returned to the Oracle Tuxedo service.
len		Length of User data
flags	`TPNOCHANGE`	Local	Must be a supported buffer type.
	`TPNOBLOCK`	N/A	Local
	`TPNOTIME`	N/A	Local
	`TPSIGRSTRT`	N/A	Local
revent	`TPEV_DISCONIMM`	If set, the LU6.2 conversation has been terminated abnormally.	If the return code from a CMSEND is deallocate_abnormal, the conversation is terminated. A disconnect event is sent to the sending process.
	`TPEV_SENDONLY`	If set, the LU6.2 conversation changes to send if partner allows it.	The sending partner has sent a CMSEND with send_type set to CM_SEND_AND_PREP_TO_RECEIVE.
	`TPEV_SVCERR`	If set, the LU6.2 conversation has been terminated abnormally.	Any return code other than CM_OK or CM_DEALLOCATE_NORMAL is treated as a TPEV_SVCERR.
	`TPEV_SVCFAIL`		If the return code from CMRCV is CM_TP_NOT_AVAIL_NO_RETRY or CM_TP_RESOURCE_FAILURE_NO_RETRY, `revent` is set to TPEV_SVCFAIL.
	`TPEV_SVCSUCC`	If set, the conversation has completed normally.	The return code from CMRCV was set to CM_DEALLOCATE_NORMAL. This indicates that the sending TP has completed and deallocated the conversation normally.

Table 1-10 tpdiscon
tpdiscon()	Parameters	Contents	CPIC Notes
cd		The connection descriptor	This connection descriptor in mapped to the CONVID returned from CMINIT or CMACCP to the originator of the conversation.

Table 1-11 tpforward
tpforward ()	Contents	CPIC Notes
svc	Service name	tpforward() is treated as if it were a `tpacall()`. A CMINIT and subsequent CMALLC are issued to initialize and allocate a session for a conversation. ClientID must be propagated to the CICS transaction in a TPSVCINFO record.
data	User data	Data is sent using CMSEND. The last CMSEND is sent with send_type of deallocate_normaL.
len	Length of data returned
flags	Refer to `tpacall`()

Reference Guide

ATMI to CPI-C Function Mapping