Reference Guide
Application-to-Application Programming Examples
This section provides the following transaction scenarios for the programming environments supported by Tuxedo Mainframe Adapter for SNA:
Caution: The scenarios in this section demonstrate how ATMI calls relate to CICS/ESA programming structures. They are not intended for use in developing application code, or for the replacement of existing application code. The use of any of these examples in actual situations may have unpredictable results.
Each example provides a graphical illustration of the scenario followed by a description of each step of the scenario.
Distributed Program Link (DPL) Examples
The examples in this section represent a few of the many programming scenarios available for using DPL and ATMI service invocations. These examples employ the most natural and efficient approaches.
Note: To run transaction client/server scenarios, the Tuxedo Mainframe Adapter for SNA software must be licensed for sync-level 2 operations.
ATMI Client Request/Response to CICS/ESA DPL
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpcall
for SIMPDPL
, which is advertised in the DM_REMOTE_SERVICES
section of the DMCONFIG file.
- Host mirror transaction starts
TOUPDPLS
program and passes idata
buffer contents for processing.
- The
TOUPDPLS
program processes data.
- The CICS/ESA server returns the
commarea
into the client's odata
buffer.
ATMI Client Asynchronous Request/Response to CICS/ESA DPL
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpacall
for SIMPDPL
, which is advertised in the DM_REMOTE_SERVICES
section of DMCONFIG file.
- Host mirror transaction starts
TOUPDPLS
program and passes idata
buffer contents for processing.
- The
TOUPDPLS
program processes data.
- The CICS/ESA system returns the
commarea
into the client's tpgetreply odata
buffer.
ATMI Client Asynchronous Request/Response with No Reply to CICS/ESA DPL
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpacall
for SIMPDPL
, which is advertised in the DM_REMOTE_SERVICES
section of DMCONFIG file. The toupsrv
service uses TPNOREPLY
to specify that no reply is expected.
- Host mirror transaction starts
TOUPDPLS
program and passes idata
buffer contents for processing.
- The
TOUPDPLS
program processes data.
CICS/ESA DPL to ATMI Request/Response Server
- User-entered
HOPL
invokes MIRRDPLC
program.
- The
EXEC CICS LINK
command causes the advertised service mapped to MIRRDPLS
(in the DM_LOCAL_SERVICES section of the DMCONFIG file) to execute.
- The
MIRROR
service processes the data received in the service TPSVCINFO
data buffer from the EXEC
CICS LINK
.
- The
tpreturn
call returns the data into the COMM-AREA
buffer.
CICS/ESA DPL to ATMI Request/Response Server, Service in Autonomous Transaction
- User-entered
H0PL
invokes MIRRDPLC
program.
- The
EXEC CICS LINK
command causes the advertised service mapped to MIRRDPLS
(in the DM_LOCAL_SERVICES section of the DMCONFIG file) to execute. The SYNCONRETURN
option indicates that the invoked service will not participate in the CICS/ESA transaction.
- The
MIRROR
service request tpbegin
incorporates all further operations in a transaction.
- The
MIRROR
service processes the data.
- The
tpcommit
indicates the end of the transaction; all updates performed within the service transaction are to be committed.
- The
tpreturn
call returns the data into the commarea
buffer.
- The
EXEC CICS SYNCPOINT
is an explicit commit request. All updated resources in the CICS/ESA transaction are committed.
ATMI Client Request/Response to CICS/ESA DPL, Autonomous Transaction
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpbegin
to start the transaction.
- The
toupsrv
service issues tpcall
for SIMPDPL
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file. The TPNOTRAN
parameter indicates the CICS/ESA application does not participate in the service transaction.
- Host mirror transaction starts
TOUPDPLS
program and passes idata
buffer contents for processing.
- The
TOUPDPLS
program processes data.
- The
EXEC CICS SYNCPOINT
is an explicit commit request. All updated resources in the CICS/ESA transaction are committed.
- The CICS/ESA server returns the
commarea
into the client's odata
buffer.
- The
toupsrv
service tpcommit
request signals the successful completion of the transaction, causing a commit of its own updated resources.
Transactional ATMI Client Multiple Requests/Responses to CICS/ESA DPL
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpbegin
to start the transaction.
- The
toupsrv
service issues tpcall
for SIMPDPL
, which is advertised in the DM_REMOTE_SERVICES
section of the DMCONFIG file. The tpcall
is requested multiple times within the same transaction.
- Host mirror transaction starts
TOUPDPLS
program and passes idata
buffer contents for processing. The host mirror transaction remains as a long-running task to service all further requests on the transaction.
- The
TOUPDPLS
program processes data.
- The CICS/ESA system returns the
commarea
into the client's odata
buffer.
- Step 3 through Step 6 are repeated until the
toupsrv
service loop end conditions are met.
- The
tpcommit
request indicates the successful completion of the transaction, causing a commit of its own resources and the resources held by the host mirror transaction.
Transactional CICS/ESA DPL to ATMI Request/Response Server
- User-entered
H2PL
invokes MIRRDPLC
program.
- The
EXEC CICS LINK
command causes the advertised service mapped to MIRRDPLS
(in the DM_LOCAL_SERVICES section of the DMCONFIG file)
to execute. The invoked service participates in the CICS/ESA transaction.
- The
MIRROR
service processes the data.
- The
tpreturn
call returns the data into the commarea
buffer.
- The
EXEC CICS SYNCPOINT
is an explicit commit request indicating a successful end of the conversation. All updated resources in the transaction are committed.
Distributed Transaction Processing (DTP) Examples
The following examples represent programming scenarios for using DTP and ATMI service invocations.
Although it is most suited for the DPL environment, the tpcall
is usually used for the DPL environment, it can also be used for a request/response to a DTP server.
The examples in this section represent some of the programming scenarios available for using DTP and ATMI service invocations. These examples employ the most natural and efficient approaches.
Note: To run transactional client/server scenarios, the Tuxedo Mainframe Adapter for SNA software must be licensed for sync-level 2 operations.
ATMI Client Request/Response to CICS/ESA DTP
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpcall
for SIMPDTP
, which is advertised in the DM_REMOTE_SERVICES
section of DMCONFIG file.
- User transaction
DTPS
starts TOUPDTPS
program.
- It is recommended you save the
eibtrmid
to a program variable. This value may be used to identify the specific conversation in your CICS/ESA APPC verbs.
- The
EXEC CICS RECEIVE
command receives the idata
buffer contents for processing.
- The
TOUPDTPS
program processes data.
- The
EXEC CICS SEND
command returns the OUT-BUFFER
contents into the clients odata
buffer. LAST indicates the conversation is finished. WAIT suspends processing until the data has successfully been received.
ATMI Client Asynchronous Request/Response to CICS/ESA DTP
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpacall
for SIMPDTP
, which is advertised in the DM_REMOTE_SERVICES
section of the DMCONFIG file.
- User transaction DTPS starts
TOUPDTPS
program.
- It is recommended you save the
EIBTRMID
to a program variable. This value may be used to identify the specific conversation in your CICS/ESA APPC verbs.
- The
EXEC CICS RECEIVE
command receives the idata
buffer contents for processing.
- The
TOUPDTPS
program processes data.
- The
EXEC CICS SEND
command returns the OUT-BUFFER
contents into the clients tpgetreply odata
buffer. LAST
indicates the conversation is finished. WAIT
suspends processing until the data has successfully been received.
ATMI Client Asynchronous Request/Response with No Reply to CICS/ESA DTP
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpacall
with a TPNOREPLY
request for SIMPDTP
, which is advertised in the DM_REMOTE_SERVICES
section of DMCONFIG file.
- User transaction DTPS starts
TOUPDTPS
program.
- It is recommended you save the
EIBTRMID
to a program variable. This value may be used to identify the specific conversation on your CICS/ESA APPC verbs.
- The
EXEC CICS RECEIVE
command receives the idata
buffer contents for processing.
- The
TOUPDTPS
program processes data.
ATMI Conversational Client to CICS/ESA DTP, Server Gets Control
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpconnect
for SIMPDTP
, which is advertised in the DM_REMOTE_SERVICES
section of DMCONFIG file. The TPRECVONLY
flag indicates the server gets control and the first conversation verb toupsrv
can issue is tprecv
. Data is sent on the tpconnect
in the idata
buffer.
- User transaction DTPS starts
TOUPDTPS
program.
- It is recommended you save the
EIBTRMID
to a program variable. This value may be used to identify the specific conversation on your CICS/ESA APPC verbs.
- The
EXEC CICS RECEIVE
command receives the idata
buffer contents for processing.
- The
TOUPDTPS
program processes data.
- The
EXEC CICS SEND
command returns the OUT-BUFFER
contents into the clients tprecv odata
buffer. WAIT
suspends processing in TOUPDTPS
until the data has successfully been received. LAST
indicates the conversation is finished and is communicated to the tprecv
as TPEV_SVCSUCC
.
ATMI Conversational Client to CICS/ESA DTP, Client Sends/Receives Data
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpconnect
for SIMPDTP
, which is advertised in the DM_REMOTE_SERVICES
section of DMCONFIG file. The TPSENDONLY
indicates the client retains control and continues to send data. Data is sent on the tpconnect
in the idata
buffer.
- User transaction DTPS starts
TOUPDTPS
program.
- It is recommended you save the
EIBTRMID
to a program variable. This value may be used to identify the specific conversation on your CICS/ESA APPC verbs.
- The
EXEC CICS RECEIVE
command receives the tpconnect
idata
buffer contents for processing.
- The
TOUPDTPS
program processes data.
- The
EXEC CICS RECEIVE
command receives the tpsend idata
contents into the server's IN-BUFFER
.
- The server processes the data.
- The
EXEC CICS SEND WAIT LAST
returns OUT-BUFFER
data in the tprecv
odata
buffer, along with notification that the conversation is over.
ATMI Conversational Client to CICS/ESA DTP, Client Grants Control
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpconnect
for SIMPDTP
, which is advertised in the DM_REMOTE_SERVICES
section of DMCONFIG file. The TPRECVONLY
indicates the server gets control and the first conversation verb toupsrv
can issue is tprecv
.
- User transaction DTPS starts
TOUPDTPS
program.
- It is recommended you save the
EIBTRMID
to a program variable. This value may be used to identify the specific conversation on your CICS/ESA APPC verbs.
- The
EXEC CICS RECEIVE
command receives a send state
indicator from the tpconnect
TPRECVONLY
flag. No data is received into the INBUFFER
.
- The
EXEC CICS SEND
command returns the OUT-BUFFER
contents into the clients tprecv odata
buffer. The EXEC CICS SEND
command relinquishes control to the client by using the INVITE
option. This is communicated to the tprecv
as TPEV_SENDONLY
.
- The
EXEC CICS RECEIVE
command receives the tpsend
idata
contents into the server's IN-BUFFER
, along with notification that the server has relinquished control.
- The
EXEC CICS RETURN
ends the conversation, communicated to the tprecv
as TPEV_SVCSUCC
.
CICS/ESA DTP to ATMI Conversational Server, Client Retains Control
- User-entered
H0TP
invokes MIRRDTPC
program.
- The
EXEC CICS ALLOCATE
acquires a session to the remote Tuxedo domain.
- Save the conversation ID returned in
EIBRSRCE
to a program variable. This value is used to identify the specific conversation in your CICS/ESA APPC verbs.
- The
EXEC CICS CONNECT PROCESS
command initiates the advertised service mapped to MIRROR
in the DM_LOCAL_SERVICES section of the DMCONFIG file.
- Execute the
EXEC CICS SEND
command to send the contents of the OUT-BUFFER
to the Tuxedo service in the tpsvcinfo->data
buffer. The contents might be sent immediately.
- The
EXEC CICS SEND INVITE WAIT
command sends out-buff
contents into the tprecv odata
buffer. The INVITE
parameter relinquishes control of the conversation, seen as a TPEV_SENDONLY
in the reevent
parameter on the tprecv
command. The data is sent immediately, along with the data from the previous SEND
operation.
- The Tuxedo service processes data.
- The CICS/ESA server processes data.
- The ATMI
tpreturn
data returns data to the EXEC CICS RECEIVE
, along with notification that the conversation completed successfully.
CICS/ESA DTP to ATMI Conversational Server, Client Relinquishes Control
- User-entered HOTP invokes
MIRRDTPC
program.
- The
EXEC CICS ALLOCATE
acquires a session to the remote Tuxedo domain.
- Save the conversation ID returned in
EIBRSRCE
to a program variable. This value is used to identify the specific conversation in your CICS/ESA APPC verbs.
- The
EXEC CICS CONNECT PROCESS
command initiates the advertised service mapped to MIRROR
in the DM_LOCAL_SERVICES section of the DMCONFIG file.
- The
EXEC CICS SEND
command relinquishes control with the INVITE WAIT
option.
- The
EXEC CICS RECEIVE
command receives the tpsend
idata
buffer contents into the IN-BUFFER
.
- The
tpreturn
request tears down the conversation and indicates on the EXEC CICS RECEIVE
that the conversation is over.
Transactional ATMI Client Request/Response to CICS/ESA DTP
Note: This is not the recommended method of performing a DTP transactional service. Please refer to the transactional DPL using request/response for the recommended method.
- ATMI client
toupclt
invokes toupsrv
service. (Note that each tpcall
made in the program must be bookended with a tpbegin
and a tpcommit
.)
- The service issues
tpbegin
to start a transaction.
- The
toupsrv
service issues tpcall
for SIMPDTP
, which is advertised in the DM_REMOTE_SERVICES
section of the DMCONFIG file.
- User transaction DTPS starts
TOUPDTPS
program.
- Save the
EIBTRMID
to a program variable. This value is used to identify the specific conversation on your CICS/ESA APPC verbs.
- The
EXEC CICS RECEIVE
command receives the idata
buffer contents for processing.
- The
TOUPDTPS
program processes data.
- The
EXEC CICS SEND
command returns the OUT-BUUFER
contents into the clients odata
buffer. CONFIRM
indicates the conversation is finished. INVITE
allows the client to respond with a COMMIT
request.
- The
toupsrv
service issues tpcommit
to end the transaction. The COMMIT
is received on the EXEC
CICS RECEIVE
verb and the server issues EXEC
CICS RETURN
to commit the resources, terminate the transaction, and free the outstanding conversation.
Transactional ATMI Conversational Client to CICS/ESA DTP, Server Gets Control
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpbegin
to start the transaction.
- The
toupsrv
service issues tpconnect
for SIMPDTP
, which is advertised in the DM_REMOTE_SERVICES
section of DMCONFIG file. The TPRECVONLY
indicates the server gains control and the first conversation verb toupsrv
can issue is tprecv
. Data is sent on the tpconnect
in the idata
buffer.
- User transaction DTPS starts
TOUPDTPS
program.
- It is recommended you save the
EIBTRMID
to a program variable. This value may be used to identify the specific conversation on your CICS/ESA APPC verbs.
- The
EXEC CICS RECEIVE
command receives the idata
buffer contents for processing.
- The
TOUPDTPS
program processes data.
- The
EXEC CICS SEND
command returns the OUT-BUFFER
contents into the clients tprecv odata
buffer. CONFIRM
indicates that the conversation is finished and is communicated to the tprecv
as TPEV_SVCSUCC
. INVITE
enables the client to respond with a COMMIT
request.
- The
toupsrv
service issues tpcommit
to end the transaction. The COMMIT
is received on the EXEC
CICS RECEIVE
verb and the server issues EXEC
CICS RETURN
to commit the resources, terminate the transaction, and free the outstanding conversation.
Transactional CICS/ESA DTP to ATMI Conversational Server, Host Client Relinquishes Control
- User-entered H2TP invokes
MIRRDTPC
program.
- The
EXEC CICS ALLOCATE
acquires a session to the remote Tuxedo domain.
- Save the conversation ID returned in
EIBRSRCE
to a program variable. This value is used to identify the specific conversation on your CICS/ESA APPC verbs.
- The
EXEC CICS CONNECT PROCESS
command initiates the advertised service mapped to MIRRDTPS
. The SYNCLEVEL(2)
parameter indicates the inclusion of the ATMI service in the CICS/ESA transaction.
- The
EXEC CICS SEND INVITE WAIT
command causes the client to immediately relinquish control to the Tuxedo server. This is communicated to the service in TPSVCINFO
as TPSENDONLY
. No data is sent to the server on this request.
- The
EXEC CICS RECEIVE
command receives the tpsend
idata buffer contents into the IN-BUFFER
. The EXEC CICS RECEIVE
command receives a confirm request indicating the conversation should be terminated.
- The
EXEC CICS ISSUE CONFIRMATION
verb responds positively to the confirm request.
- The
EXEC CICS SYNCPOINT
is an explicit commit request to end the conversation and update all resources in the transaction.
- The
EXEC CICS FREE
verb explicitly frees the outstanding conversation.
CPI-C Programming Examples
The examples in this section show the protocol exchanges between the local ATMI platform and remote host application program. The type of ATMI service request determines the nature of the client/server communication model. For requests initiated by the host application, the configuration information for the local service determines the protocol exchanges on the conversation.
Although it is most suited for the DPL environment, the tpcall
is usually used in the DPL environment but can also be used for a request/response to an APPC server.
The examples in this section represent a few of the many programming scenarios available for using CPI-C and ATMI service invocations. These examples employ the most natural and efficient approaches.
Note: To run transactional client/server scenarios or the CPI Resource Recovery interface, the Tuxedo Mainframe Adapter for SNA software must be licensed for sync-level 2 operations.
ATMI Client Request/Response to Host CPI-C
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpcall
for SIMPCPIC
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file.
- The remote service with the
tpname
TPNCPIC
invokes TOUPCPIC
program.
- The server accepts the conversation with the
cmaccp
call. The conversation id returned on the request in convid
is used for all other requests on this conversation.
- The
cmrcv
request receives the idata
buffer contents for processing
- The
TOUPCPIC
program processes data.
- The
cmsst
request prepares the next send request by setting the send type to CM_SEND_AND_DEALLOCATE
.
- The
cmsend
request returns the obuffer
contents into the client odata
buffer. The buffer is flushed, and the conversation ended.
ATMI Client Asynchronous Request/Response to Host CPI-C
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpacall
for SIMPCPIC
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file.
- The remote service with
tpname
TPNCPIC
invokes TOUPCPIC
program.
- The server accepts the conversation with the
cmaccp
call. The conversation id returned on the request in convid
is used for all other requests on this conversation.
- The
cmrcv
request receives the idata
buffer contents for processing.
- The
TOUPCPIC
program processes data.
- The
cmsend
command returns the obuffer
contents into the client tpgetreply odata
buffer. The data may not be immediately sent to the tpgetreply odata
buffer on this request.
- The
cmdeal
flushes the data to the client, and indicates the conversation is finished.
ATMI Client Asynchronous Request/Response to Host CPI-C with No Reply
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpacall with a TPNOREPLY
request for SIMPCPIC
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file.
- The remote service with
tpname TPNCPIC
invokes TOUPCPIC
program.
- The server accepts the conversation with the
cmaccp
call. The conversation id returned on the request in convid
is used for all other requests on this conversation.
- The
cmrcv
request receives the idata
buffer contents for processing, and notification that the conversation has ended with the return code value of CM_DEALLOCATED_NORMAL
.
- The
TOUPCPIC
program processes data.
ATMI Conversational Client to Host CPI-C, Server Gets Control
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpconnect
for SIMPCPIC
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file. The TPRECVONLY
indicates the server gains control and the first conversation verb the toupsrv
can issue is tprecv
. Data is sent on the tpconnect
in the idata
buffer.
- The remote service with
tpname TPNCPIC
invokes TOUPCPIC
program.
- The server accepts the conversation with the
cmaccp
call. The conversation ID returned on the request in convid
is used for all other requests on this conversation.
- The
cmrcv
request receives the idata
buffer contents for processing.
- The
TOUPCPIC
program processes data.
- The
cmsst
request prepares the next send request by setting the send type to CM_SEND_AND_FLUSH.
- The
cmsend
command returns the obuffer
contents into the client tprecv
odata
buffer. The data is immediately flushed on the send request.
- The
cmdeal
request ends the conversation.
ATMI Conversational Client To Host CPI-C, Client Retains Control
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpconnect
for SIMPCPIC
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file. The TPSENDONLY indicates the client retains control and continues to send data. No data is sent with the tpconnect
.
- The remote service with
tpname
TPNCPIC
invokes TOUPCPIC
program.
- The server accepts the conversation with the
cmaccp
call. The conversation id returned on the request in convid
is used for all other requests on this conversation.
- The
cmrcv
request receives the tpsend
idata
buffer contents for processing. The conversation is relinquished with the TPRECVONLY
flag.
- The
TOUPCPIC
program processes data.
- The
cmsend
returns a response in the tprecv
idata
buffer, along with notification from the cmdeal
command that the conversation is over. The cmdeal
flushes the data buffer and the tprecv reevent
parameter is set to TPEV_SUCCESS
.
ATMI Conversational Client to Host CPI-C, Client Grants/gets Control
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpconnect
for SIMPCPIC
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file. The TPRECVONLY indicates the server gains control and the first conversation verb the toupsrv
can issue is tprecv
.
- The remote service with
tpname
TPNCPIC
invokes TOUPCPIC
program.
- The server accepts the conversation with the
cmaccp
request. The conversation id returned on the request in convid
is used for all other requests on this conversation.
- The
cmrcv
requests receives the indicator that control has been granted to the server.
- The
cmsend
request returns its obuffer
contents into the first client tprecv
odata
buffer. The data may not immediately be sent.
- The
cmsend
request returns its obuffer
contents into the second client tprecv odata
buffer. The data may not immediately be sent.
- The
cmptr
request flushes the data to the client, and grants control to the client.
- The
cmrcv
request receives the tpsend
idata
buffer contents for processing. The TPRECVONLY
is passed to the tprecv
, relinquishing control of the conversation.
- The
cmdeal
indicates a successful completion of the conversation to the tprecv
; no data is passed.
Host CPI-C to ATMI Asynchronous Request/Response Server with No Reply
- The CPI-C application program
MIRRCPIC
is invoked using environment start-up specifications.
- The
MIRRCPIC
client requests cminit
to establish conversation attributes and receive a conversation ID that will be used on all other requests on this conversation. The remote server and service are named in the CPI-C side information entry MIRRSIDE
.
- The
cmallc
request initiates the advertised service mapped to MIRRORSERV
in the DM_LOCAL_SERVICES section of the DMCONFIG file.
- The
cmsend
request sends the contents of obuffer
to the ATMI service in the tpsvcinfo->data
buffer.
- The
cmdeal
request flushes the data, and indicates the conversation is finished with the TPNOREPLY in the tpsvcinfo->flag
field.
- The service completes with the
tpreturn
.
Host CPI-C to ATMI Server Request/Response
- The CPI-C application program MIRRCPIC is invoked using environment start-up specifications.
- The
MIRRCPIC
client requests cmini
t to establish conversation attributes and receive a conversation id that will be used on all other requests on this conversation. The remote server and service are named in the CPI-C side information entry MIRRSIDE
.
- The
cmallc
request initiates the advertised service mapped to MIRRORSERV
in the DM_LOCAL_SERVICES section of the DMCONFIG file.
- The
cmsst
request prepares the next send request by setting the send type to CM_SEND_AND_PREP_TO_RECEIVE
.
- The
cmsend
request immediately sends the contents of obuffer
to the ATMI service in the tpsvcinfo->data
buffer and relinquishes control to the mirrorserv
service.
- The
cmrcv
request receives the contents of the odata
returned on the ATMI tpreturn
service, and notification that the conversation has ended with the return code value of CM_DEALLOCATED_NORMAL
.
Host CPI-C to ATMI Conversational Service, Client Retains Control
- The CPI-C application program MIRRCPIC is invoked using environment start-up specifications.
- The
MIRRCPIC
client requests cminit
to establish conversation attributes and receive a conversation id that will be used on all other requests on this conversation. The remote server and service are named in the CPI-C side information entry MIRRSIDE
.
- The
cmallc
request initiates the advertised service mapped to MIRRORSERV
in the DM_LOCAL_SERVICES section of the DMCONFIG file.
- The
cmsend
request sends the contents of obuffer
to the ATMI service in the tpsvcinfo->data
buffer.
- The
cmdeal
request flushes the data and ends the conversation, as indicated by TPNOREPLY
in the tpsvcinfo->flag
field.
Host CPI-C ATMI to Conversational Service, Client Grants Control
- The CPI-C application program
MIRRCPIC
is invoked using environment start-up specifications.
- The
MIRRCPIC
client requests cminit
to establish conversation attributes and receive a conversation ID that will be used on all other requests on this conversation. The remote server and service are named in the CPI-C side information entry MIRRSIDE
.
- The
cmallc
request initiates the advertised service mapped to MIRROR
in the DM_LOCAL_SERVICES section of the DMCONFIG file.
- The
cmptr
relinquishes control of the conversation to the ATMI service indicated as TPSENDONLY
in the tpsvcinfo->flag
field. No data is passed in the tpsvcinfo->data
field.
- The
cmrcv
receives the contents of the tpsend odata
into the ibuffer
. The end of the conversation is passed from the tpreturn
service as return code value CM_DEALLOCATED_NORMAL
.
Transactional ATMI Client Request/Response to Host CPI-C
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpbegin
to start the transaction.
- The
toupsrv
service issues tpcall
for SIMPCPIC
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file. Data is sent from the idata
buffer on the tpconnect
.
- The remote service with
tpname
TPNCPIC
invokes TOUPCPIC
program.
- The server accepts the conversation with the
cmaccp
call. The conversation ID returned on the request in convid
is used for all other requests during this conversation.
- The
cmrcv
request receives the idata
buffer contents for processing.
- The
cmsst
and cmsptr
prepare the next send request by setting the send type to CM_SEND_AND_PREP_TO_RECEIVE
and by setting the prepare-to-receive type to CM_PREP_TO_RECEIVE_CONFIRM
.
- The
cmsend
request immediately returns the obuffer
contents into the client's odata
buffer. The server relinquishes control to the server and indicates the end of the conversation with the CONFIRM
request.
- The
toupsrv
issues the tpcommit
to successfully complete the transaction and commit all updated resources. The cmrcv
request receives the commit request, and responds explicitly to the request with the SAA Resource/Recovery commit call srrcmit
. The conversation is ended after the successful commit exchange.
Transactional ATMI Conversational Client to Host CPI-C, Server Gets Control
- ATMI client invokes
toupsrv
service.
- The
toupsrv
service issues tpbegin
to start the transaction.
- The
toupsrv
service issues a tpconnect
service request for SIMPCPIC
, which is advertised in the DM_REMOTE_SERVICES section of the DMCONFIG file. Data is sent in the idata
buffer on the tpconnect
.
- The remote service with
tpname
TPNCPIC
invokes TOUPCPIC
program.
- The server accepts the conversation with the
cmaccp
call. The conversation ID returned on the request in convid
is used for all other requests during this conversation.
- The
cmrcv
request receives the idata
buffer contents sent on the tpconnect
for processing.
- The
TOUPCPIC
program processes the data.
- The
cmsend
returns the obuffer
contents into the client's tprecv
odata
buffer. The buffer contents may not be sent immediately.
- The
cmsptr
prepares the prepare-to-receive request with CM_PREP_TO_RECEIVE_CONFIRM
. The cmptr
request with CONFIRM
indicates that the conversation is finished and is communicated to the tprecv
as TPEV_SVCSUCC
.
- The
toupsrv
issues the tpcommit
to successfully complete the transaction and commit all updated resources. The cmrcv
request receives the commit request and responds explicitly to the request with the SAA Resource/Recovery commit call srrcmit
. The conversation is ended after the successful commit exchange.
Transactional Host CPI-C to ATMI Conversational Server, Client Grants Control
- The CPI-C application program
MIRRCPIC
is invoked using environment start-up specifications.
- The
MIRRCPIC
client requests cminit
to establish conversation attributes and receive a conversation ID that will be used on all other requests on this conversation. The remote server and service are named in the CPI-C side information entry MIRRSIDE
.
- The
cmssl
sets the conversation attributes to sync-level 2 with CM_SYNCPOINT
. This allows the ATMI service to participate in the transaction.
- The
cmallc
request initiates the advertised service mapped to MIRRORSERV
in the DM_LOCAL_SERVICES section of the DMCONFIG file.
- The MIRRCPIC causes the client to relinquish control to the ATMI server with a prepare-to-receive request. The
cmsptr
sets the prepare-to-receive type to CM_RECEIVE_AND_FLUSH. The cmptr
request immediately relinquishes control.
- The
MIRROR
service sends the data contents of the odata
buffer to the cmrcv
ibuffer
. The cmrcv
receives a confirm request from the server indicating the conversation should be terminated.
- The client replies positively to the confirm request with
cmcfmd
.
- The
MIRRCPIC
client prepares to free the conversation with the cmdeal
request. The conversation in CM_DEALLOCATE_SYNC_LEVEL commits all updated resources in the transaction and waits for the SAA resource recovery verb, srrcmit
. After the commit
sequence has completed, the conversation terminates.
CICS/ESA Mirror Transaction Examples
Implicit Attachment of TRANSID (Outbound Requests Only)
Figure 2-1 Implicit Attachment of TRANSID (Outbound Requests Only)
The following list describes the process for implicit attachment as illustrated in Figure 2-1:
- The ATMI service makes a request to the service
TRN1DATA
, which is advertised as a remote service in the DMCONFIG
file. It is a DPL request to a program named SVC1
in the CICS/ESA region.
- The first four characters of the remote service tag name (
TRN1
) are extracted and passed to the CICS/ESA region as the invoking TRANSID
. No CICS/ESA resource definition for the TRANSID
is required in the region.
- The mirror transaction CSMI is attached in the CICS/ESA region, starting the mirror program
DFHMIRS
. The program performs the DTP requests for the service.
- The mirror program now attaches the invoking
TRANSID
(TRN1
) and then invokes the application service program SVC1
.The program can interrogate the EIBTRNID
field to find this value.
Explicit Attachment of TRANSID for Outbound Requests
Figure 2-2 Explicit Attachment of TRANSID for Outbound Requests
The following list describes the process for explicit attachment as illustrated in Figure 2-2:
- The ATMI program makes a service request for
SERVICE1
, which is advertised as a remote service in the DMCONFIG
file. The FUNCTION
option indicates the remote service is invoked as a DPL.
- The request extracts
TRN1
as an alternate mirror transaction ID for the remote region, along with the remote program name SERVICE1
.
- The
TRN1
ID is attached instead of the default mirror transaction, CSMI
or CVMI
. The TRN1
ID must be defined as a transaction resource in the remote region and must point to the mirror transaction program DFHMIRS
.
- The mirror program
DFMMIRS
calls the server application program, passing the TRN1
ID in the EIBTRNID
field.
Explicit Attachment of TRANSID for Inbound Requests
Figure 2-3 Explicit Attachment of TRANSID for Inbound Requests
The following list describes the process for implicit attachment as illustrated in Figure 2-3:
- The CICS/ESA program makes a request to
INSVC1
, which is a local ATMI service. The SYSID
and PROGRAM
values in the request identify the local system and the name of the local service. The TRANSID
option indicates the mirror transaction to be initiated.
- The
PROGRAM
and mirror TRANSID
are extracted from the DPL request and are used to find an exact RNAME
match in the DM_LOCAL_SERVICES
section of the DMCONFIG
file.
- The service
SERVICE1,
which is advertised locally in the ATMI platform application, is initiated.
Additional Information
Additional information about CICS/ESA Intersystem Communications may be found in the following IBM publications:
- CICS/ESA Intercommunication Guide, IBM publication No. SC33-0657
- CICS/ESA Distributed Transaction Programming Guide, IBM publication No. SC33-00783
- CICS/ESA Recovery and Restart Guide, IBM publication No. SC33-0658