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:

•

tpcall()

•	tpacall() with or without reply

•	tpgetrply()

•	tpservice()

•	tpreturn()

•	tpcancel()

•	tpconnect()

•

tpsend()

•

tprecv()

•	tpdiscon()

•	tpforward ()

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.
		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()	Parameters	Contents	CPIC Notes
rval		TPSUCCESS	Set to TPSUCCESS when conversation terminates with a normal deallocation.
		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 ()	Parameters	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()