[Top] [Prev] [Next] [Bottom]

# Chapter 7. Programming Considerations

## Overview

This chapter is intended for application programmers who implement and integrate TUXEDO and host enterprise applications using Application Program-to-Program Communication (APPC). Although primarily oriented toward TUXEDO application developers, it is also useful for non-TUXEDO application developers seeking to understand the relationship between the environments.

Connect SNA gives TUXEDO applications access to host APPC programs acting as servers. At the same time, APPC applications can act as clients and access TUXEDO system services. Because the client and server programs must be written for separate and very different environments, BEA Connect SNA allows the applications to be written using native programming facilities:

- The application programmer in a TUXEDO environment uses the familiar Application-Transaction Monitor Interface (ATMI) primitives in the application code. Service requests can be made to the Connect SNA Domain gateway just as they would be made to any other TUXEDO system server or gateway.

- The application programmer in the CICS/ESA environment can use CICS APPC API verbs. In addition, the programmer can use Distributed Program Link (DPL) techniques as either a client or server.

- The application programmer in the APPC environment can use Customer Information Control System/Extended System Architecture (CICS/ESA) verbs for SNA-based applications.

- The application programmer in the Information Management System (IMS) environment can use implicit IMS verbs.

Programmers in each environment can continue to use the tools with which they are familiar to develop application software. It is not important that a programmer be well versed in the programming facilities of the other environments. What is important, however, is proper coordination between the applications running in each environment.

This chapter explains the various options offered by the Connect SNA domain and illustrates the most effective ways to implement these options.

## APPC/IMS Programming

BEA Connect SNA supports non-transactional IMS servers using either the implicit APPC support for IMS or the explicit APPC interface using APPC/MVS calls from a user application.

Implicit APPC is similar and more convenient than the CICS/ESA DPL. Any IMS program that gets from and puts messages to the IMS message queue can be used without change as either a client or server.

To use the implicit APPC capabilities of IMS, you must modify the APPCM file in the SYS1.PARMLIB library provided with your Connect SNA product software. The configuration parameters in this file associate the LU with the IMS scheduler. You must identify the LU representing the application name used by Connect SNA to access the IMS region and the IMS system ID which provides scheduling for inbound requests.It is important to discuss with mainframe support personnel the changes you make to the APPCM file.

In Listing 7-1, the VTAM application major node is designated to be MVSLUO1 and the scheduling facility is designated to be the IMS control region IVP4.

> Listing 7-1 APPCM File in SYS1.PARMLIB Library (Example Only)

>     SYS1.PARMLIB(APPCMxx)

>     LUADD ACBNAME(MVSLU01) BASE TPDATA(SYS1.APPCTP),
>     SCHED(IVP4),
>     SIDEINFO DATASET(SYS1.APPCSI)

>     SYS1.VTAMLST(MVSLU01)

>     MVSLU01 APPL   ACBNAME=MVSLU01,        ACBNAME FOR APPC                C
>                    APPC=YES,                                               C
>                    AUTOSES=3,                                              C
>                    DDRAINL=NALLOW,                                         C
>                    DLOGMOD=APPCHOST,                                       C
>                    DMINWNL=3,                                              C
>                    DMINWNR=3,                                              C
>                    DRESPL=NALLOW,                                          C
>                    DSESLIM=6,                                              C
>                    LMDENT=19,                                              C
>                    MODETAB=APPCTAB,                                        C
>                    PARSESS=YES,                                            C
>                    SECACPT=CONV,                                           C
>                    SRBEXIT=YES,                                            C
>                    VPACING=1

The job which starts the IMS subsystem should have the APPC parameter set to Y. The example in Listing 7-2 illustrates such a job, but is not intended to be used under actual conditions. Use your own custom job for starting IMS.

> Listing 7-2 IMS Subsystem Start Job (Example Only

>     )IVP51F41 EXEC,PROC=IMSFP,TIME=(1440),,
>              AGN=IVP,               AGN NAME
>              SOUT='*',              SYSOUT CLASS
>              MBR=DFSIVAG,           PROGRAM NAME
>              PSB=DFSIVPG,           PSB     NAME
>              NBA=06,                INITIAL FAST PATH DB BUFFERS
>              OBA=05,                SECONDARY FAST PATH DB BUFFERS
>              TLIM=10,               IFP TERMINATION LIMIT
>              SOD=,                  SPIN-OFF DUMP CLASS
>              IMSID=IVP4,            IMSID OF IMS CONTROL REGION
>              APPC=Y,                ENABLE IMPLICIT APPC
>              PREINIT=DC             PROCLIB DFSINTXX MEMBER

## CICS/ISC Programming

The CICS/ESA Intersystem Communications (ISC) facility permits multiple independent CICS/ESA systems, normally executing on different hosts and possibly different computing platforms, to cooperate while performing various computing tasks.

CICS/ESA defines a set of five distinct services with ISC as a common foundation:

- Asynchronous Processing (AP)

- Function Request Shipping (FRS)

- Transaction Routing (TR)

- Distributed Program Link (DPL)

- Distributed Transaction Processing (DTP)

The first four ISC services are categorized as implicit. These services are not used directly by user-written CICS/ESA applications, but are employed indirectly and automatically by the CICS/ESA system on behalf of them. The services are supported between peer CICS/ESA systems; for example, between two mainframe CICS/ESA systems connected by an ISC link. Currently, Connect SNA supports DPL for BEA TUXEDO.

DTP, on the other hand, is an explicit service that can be used by CICS/ESA applications to cooperatively distribute business functionality. BEA Connect SNA supports DTP services between peer CICS/ESA systems, as well as between CICS/ESA systems and non-CICS/ESA systems (for example, a DTP application conversing with an APPC/MVS application). BEA Connect SNA also supports DTP for BEA TUXEDO ATMI applications.

### Multi-Region versus Multi-Processor Operations

CICS/ESA applications may also use another form of intersystem communication, called Multi-Region Operation (MRO). MRO is typically used to improve the performance of a CICS/ESA system by partitioning it into multiple, physically distinct regions.

MRO can be compared to a BEA TUXEDO Multi-Processor (MP) environment. In a two-platform MP application domain, the first platform might be dedicated to handle terminal and workstation clients, and the second platform might be dedicated to handle the application logic and file services. In a similar MRO configuration, all terminals might be placed in one CICS/ESA region (called a terminal-owning region), and applications and data stores might be placed in another CICS/ESA region (called an application-owning or file-owning region).

The biggest difference between this MP environment and the MRO configuration is that the MP environment spans multiple platforms, whereas the MRO configuration resides on a single host.

BEA Connect SNA does not relate directly to MRO due to MRO's single platform nature. However, it does support ISC operations.

### ISC Operations

The ISC facility provides a mechanism for multiple CICS/ESA systems operating on different host computers to communicate with each other, but ISC is more than a simple communications mechanism. It implements a well-defined set of protocols by which connected CICS/ESA systems cooperate in the execution of recoverable, distributed units of work. This important concept is fundamental to understanding the relationship between connected CICS/ESA systems.

IBM's Systems Network Architecture (SNA) defines the protocols for communications between IBM systems in a multi-system environment. ISC is an implementation of a specific SNA protocol known as Advanced Program-to-Program Communications (APPC, also referred to as LU TYPE 6.2 or LU 6.2).

The ISC for APPC is not a strict implementation of the SNA architecture specification. In particular, CICS/ESA makes use of special Function Management Headers (FMH) which are not part of the SNA architecture specification. Other deviations are documented in the IBM Distributed Transaction Programming Guide.

Although ISC can be used to connect CICS/ESA systems residing on a single host computer, ISC is normally used to connect CICS/ESA systems which reside on physically-distinct host computers. Furthermore, systems which are geographically separated may be connected.

IBM's Advanced Communication Facility / Virtual Telecommunications Access Method (AFC/VTAM) is used to define and implement a logical connection between two CICS/ESA systems. Using the VTAM facilities, CICS/ESA systems establish one or more concurrent sessions for communications. Each session supports one logical conversation between the two systems. These logical conversations carry the inter-system traffic associated with the various ISC functions.

Similar to BEA TUXEDO conversational service requests, LU 6.2 is a half-duplex protocol; that is, session traffic can flow in only one direction at a time. The session partners are responsible for coordinating their use of the session such that when one is sending, the other is receiving. Both session partners cannot send (or receive) at the same time.

#### Asynchronous Processing

This ISC service allows an application to start a transaction on a remote system. Unlike DPL and Function Request Shipping, the calling application does not wait for the remote task to complete. The calling transaction initiates an asynchronous process with the CICS/ESA interval START command. Information can be passed to the back-end transaction in the FROM option of the START COMMAND. The back-end transaction can then issue a RETRIEVE command to get this data. The transaction can be defined as remote, indicating the system on which the transaction is to be run, or the remote system can be named explicitly in the SYSID option of the START command.

#### Function Request Shipping

Remote resources, such as VSAM files, DLI requests, Transient Data Queues, and Temporary Storage Queues can be made available to a local application. The application is not necessarily aware that the requested resource is on another CICS/ESA region. Files and Queues are defined as remote with system administration utilities, but could optionally be specified as remote using the SYSID option of the resource request command.

#### Transaction Routing

Transaction routing provides a terminal connected to a CICS/ESA region with the ability to run a transaction on another CICS/ESA region in a fashion transparent to the terminal user. A transaction can be defined as a remote transaction in the system initialization table. This definition indicates on which remote system the transaction is to run.

#### Distributed Program Link

Distributed Program Link (DPL) allows a CICS/ESA program to call (link to) another CICS/ESA program located on a remote system. This is a synchronous process; control does not return to the calling program until the called program has finished executing. See Figure 7-1 for a generic example of this process.

> Figure 7-1 Generic DPL Transaction

#### Step-by-Step Description: Generic DPL Transaction

1. CICS/ESA transaction TRN1, executing on CICS/ESA System A, issues an EXEC CICS LINK to program `PRG002`, which resides on CICS/ESA System B. TRN1 "waits" while the LINK request is processed.

2. The LINK implementation internally initiates a special mirror transaction on system B, using an APPC conversation.

3. The mirror transaction runs the system program DFHMIR. It starts the user program PRG0002 and passes any input data to it. The mirror program uses APPC verbs to pass data to and from the user program.

4. Upon completion, PRG0002 returns control to the mirror program which sends any return data back to PGM0001. PGM001 continues execution and may invoke multiple DPL requests using the same conversation and mirror program task.

5. The conversation with the mirror program remains active and available to PGM0001 until a SYNCPOINT is issued. The conversation is used to coordinate the SYNCPOINT processing and is deallocated when the SYNCPOINT is complete.

The functionality of the remote program is minimally constrained. It can access files and databases as well as linking to other programs, but does not do terminal I/O. In general, an application program is not aware that it is calling a program located on a remote system. In most cases, Distributed Program Link is completely transparent to both the calling and called programs. Implicit support for full recovery and restart of all CICS/ESA-controlled resources, such as files and databases, is automatically provided by the CICS/ESA system.

Note: If a client sends a data buffer to a remote CICS/ESA system as part of a DPL and no data is modified, the remote system returns no data and the length is zero.

#### Distributed Transaction Processing

Distributed Transaction Processing (DTP) is the only ISC services that provides for direct, application-to-application communications. DTP takes place between two conversation partners, both of which are normally user-written CICS/ESA applications. One conversation partner initiates a conversation with a counterpart on a remote system, and must explicitly identify the remote system. The conversation partner on the remote system must accept the requested conversation. Using the full capabilities of ISC, DTP applications send and receive application-defined data streams and engage in a series of application-defined interactions. (See Figure 7-2 for a generic example of this process.)

> Figure 7-2 Generic DTP Transaction

#### Step-by-Step Description: Generic DTP Transaction

1. Transaction `TRN1`, invokes program `PGM0001` executing on CICS/ESA System A.

2. Program `PGM0001` initiates (requests) a conversation with transaction `TRN2`, located on CICS/ESA System B, which in turn, invokes program `PGM0002`.

3. Transaction `TRN2`, executing on CICS/ESA System B, invokes program `PGM002`.

4. Program `PGM0001` sends data to program `PGM0002`, then relinquishes control to`PGM002`.

5. Program `PGM0002` sends data to `PGM0001`, perhaps the response to the previous request. `PGM0001` receives the data sent by `PGM0002`.

6. `PGM0001` and `PGM0002` synchronize the data, acknowledge the conversation, and end the conversation.

DTP offers the best of two worlds. On one hand, it provides support for completely customized application protocol semantics. On the other hand, it allows the applications to select the desired level of support for resource recovery and restart:

- At sync-level 0, the conversation partners elect to forego CICS/ESA system-assisted synchronization altogether.

- At sync-level 1, the conversation partners can exchange special synchronization verbs as an aid in maintaining synchronization.

- At sync-level 2, the CICS/ESA system provides full recovery and restart of all controlled resources, such as files and databases. More specifically, a task can initiate tasks on other systems and the collection of tasks can be synchronized into a common unit of work. If there is a failure in any of the tasks, the entire collection can be rolled back.

  Note: It is important to understand that, by definition, ISC operates only at sync-level 2.

DTP conversations are LUTYPE 6.2 conversations. They are a half-duplex form of data exchange between two transactions. It is half-duplex because only one side of the conversation can send data at a time. A conversation is initiated by the application using the Application Program-to-Program Communication (APPC) protocol. Because of this, the application must be coded to respect the various conversation states. These states are documented in the IBM CICS/ESA Intercommunication Guide and identify which APPC verbs are legal at the various stages of a conversation. LUTYPE 6.2 conversations can be mapped or unmapped conversations.

Unmapped or base-level conversation support is the minimum support level required for LUTYPE 6.2 product implementation. Mapped conversations are at a higher level than base conversations and do not require the application to be aware of the SNA data stream format. The state transitions are less restrictive and the command set is more robust. In addition to this, the application has access to CICS/ESA data areas to determine the status of the conversation and the results of certain APPC commands.

#### CICS/ESA Sync-Levels

In general, the synchronization level determines the cooperation between communicating partners needed to coordinate changes to their respective resources (such as files and databases). It also defines specific protocol flows required to support a requested synchronization level. The APPC architecture defines three distinct levels of synchronization. These three levels are Level 0, Level 1, and Level 2 (corresponding to the SNA-defined levels of NONE, CONFIRM, and SYNCPOINT, respectively).

##### Level 0 (NONE)

No synchronization at the protocol level is provided. This level is used when synchronization is not required or supported. This is very similar to non-transactional TUXEDO System service requests.

##### Level 1 (CONFIRM)

This level supports the exchange of private, application-level, synchronization requests between conversing partners. These partners, or applications, are totally responsible for defining and executing the synchronization process to ensure the integrity of all resources. The CICS/ESA system is not involved in the synchronization process at this level. There is no confirm capability in the TUXEDO System. Any CICS/ESA application attempting to initiate a sync-level 1 operation with TUXEDO causes an error condition.

##### Level 2 (SYNCPOINT)

At this level, the CICS/ESA system is fully involved in the synchronization process and provides complete, automatic support of sync-pointing, including rollback. The CICS/ESA system defines and coordinates the synchronization process and is responsible for ensuring the integrity of all CICS/ESA-managed resources.

In the case of DTP, the communicating applications participate in the synchronization process and are responsible for the management and integrity of any non-CICS/ESA resources to which they gain access.

Because DTP takes place between two application-level conversation partners, it may operate at any of the three defined synchronization levels. In other words, the conversation partners are permitted to specify the desired level of synchronization and participate in the synchronization process only to the extent specified.

If the user DTP conversation is at sync-level 0 or 1, the CICS/ESA system does not propagate sync-points from one system to another via the conversation. Thus the user can explicitly suspend CICS/ESA ACID Properties. A DTP conversation at sync-level 2 causes a CICS/ESA system to propagate sync-points automatically via the conversation as well as via subordinate conversations.

DPL can also operate at sync-level 1, in which case the user is responsible for maintaining the ACID properties. Sync-level 1 DPL conversations usually occur because one or both of the systems are incapable of operating at sync-level 2. BEA Connect SNA can support DPL requests at both sync-levels 1 and 2, and can support DTP conversations at sync-levels 0 and 1.

### Time-out and Error Handling

The /Domain's global timer is used to determine excessive time for a service request. If a time-out occurs, a FAILURE indication is raised and `tperrno` is set to TPETIME. The domain gateway cleans up any resources allocated to the failed communication.

Connect SNA sets `tperrno` values when an error occurs. Appendix B, "ATMI to CPI-C Function Mapping," describes the CPI-C return codes and their mapping to ATMI return codes.

Refer to Appendix D, "Error Messages," for error code listings.

## Application-to-Application Programming

This section provides Transaction scenarios for the following programming environments supported by Connect SNA:

- Distributed Program Link (DPL)

- Distributed Transaction Processing (DTP)

- CPI-C

  Caution: The scenarios in this section demonstrate how TUXEDO ATMI calls relate to CICS/ESA programming structures. They are intended neither for use in developing application code, nor for the replacement of existing application code. The use of any of these examples in actual situations may have unpredictable results.

### Distributed Program Link (DPL)

Using Connect SNA, TUXEDO applications can make ATMI service calls to invoke programs running in a remote CICS/ESA DPL environment. CICS/ESA programs can in turn use the `EXEC` `CICS LINK` command to invoke user-defined TUXEDO services. This feature is available to either new or existing CICS/ESA programs and TUXEDO applications. DPL can only be used by BEA TUXEDO application domains connected to a CICS/ESA system.

Consider the program issuing the distributed link request or ATMI service request to be the Client program. Consider the executing remote program or service to be the Server program. The client does not have to be aware of the server's location.

TUXEDO programs can use both the request/response and conversational models to invoke programs on the host. (However, request/response models are preferred.)

Local and remote services are defined with the `FUNCTION=DPL` option in the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES section in the DMCONFIG file, indicating that the DPL ISC function is invoked.

Host DPL requests, in turn, can also be compared to TUXEDO services using either call model. The request/response model is very similar to DPL. The conversational model, although supported in DTP, is less efficient and programmatically more complex than the request/response model. It is recommended that you use a DTP model when invoking conversational transactions.

It is also recommended you use a DPL model when invoking the same request/response or conversational request multiple times in a single transaction. With DPL, ISC starts a long-running mirror transaction to the CICS/ESA DPL server, enabling the server to process each of the requests over the same conversation. With DTP, each of the requests establishes a separate conversation with the server and the conversation remains outstanding until the transaction is committed.

The following examples represent a few of the many programming scenarios available for using DPL and TUXEDO service invocations. These examples employ the most natural and efficient approaches.

Note: To run Transaction client/server scenarios, the Connect SNA software must be licensed for sync-level 2 operations.

> Figure 7-3 TUXEDO Client Request/Response to CICS/ESA DPL

#### Step-by-Step Description: TUXEDO Client Request/Response to CICS/ESA DPL

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpcall` for `SIMPDPL`, which is advertised in the *DM_REMOTE_SERVICES section of the DMCONFIG file.

3. Host mirror transaction starts `TOUPDPLS` program and passes `idata` buffer contents for processing.

4. The `TOUPDPLS` program processes data.

5. The CICS/ESA server returns the `commarea` into the client's `odata` buffer.

   > Figure 7-4 TUXEDO Client Asynchronous Request/Response to CICS/ESA DPL

#### Step-by-Step Description: TUXEDO Client Asynchronous Request/Response to CICS/ESA DPL

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpacall` for `SIMPDPL`, which is advertised in the *DM_REMOTE_SERVICES section of DMCONFIG file.

3. Host mirror transaction starts `TOUPDPLS` program and passes `idata` buffer contents for processing.

4. The `TOUPDPLS` program processes data.

5. The CICS/ESA system returns the `commarea` into the client's `tpgetreply odata` buffer.

   > Figure 7-5 TUXEDO Client Asynchronous Request/Response with No Reply to CICS/ESA DPL

#### Step-by-Step Description: TUXEDO Client Asynchronous Request/Response with No Reply to CICS/ESA DPL

1. TUXEDO client invokes `toupsrv` service.

2. 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.

3. Host mirror transaction starts `TOUPDPLS` program and passes `idata` buffer contents for processing.

4. The `TOUPDPLS` program processes data.

   > Figure 7-6 CICS/ESA DPL to TUXEDO Request/Response Server

#### Step-by-Step Description: CICS/ESA DPL to TUXEDO Request/Response Server

1. User-entered `HOPL` invokes `MIRRDPLC` program.

2. The `EXEC CICS LINK` command causes the advertised service mapped to `MIRRDPLS` (in the DM_LOCAL_SERVICES section of the DMCONFIG file) to execute.

3. The `MIRROR` service processes the data received in the service `TPSVCINFO` data buffer from the `EXEC` `CICS LINK`.

4. The `tpreturn` call returns the data into the `COMM-AREA` buffer.

   > Figure 7-7 CICS/ESA DPL to TUXEDO Request/Response Server, Service in Autonomous Transaction

#### Step-by-Step Description: CICS/ESA DPL to TUXEDO Request/Response Server, Service in Autonomous Transaction

1. User-entered `H0PL` invokes `MIRRDPLC` program.

2. 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.

3. The `MIRROR` service request `tpbegin` incorporates all further operations in a transaction.

4. The `MIRROR` service processes the data.

5. The `tpcommit` indicates the end of the transaction; all updates performed within the service transaction are to be committed.

6. The `tpreturn` call returns the data into the `commarea` buffer.

7. The `EXEC CICS SYNCPOINT` is an explicit commit request. All updated resources in the CICS/ESA transaction are committed.

   > Figure 7-8 TUXEDO Client Request/Response to CICS/ESA DPL, in Autonomous Transaction

#### Step-by-Step Description: TUXEDO Client Request/Response to CICS/ESA DPL, in Autonomous Transaction

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpbegin` to start the transaction.

3. 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.

4. Host mirror transaction starts `TOUPDPLS` program and passes `idata` buffer contents for processing.

5. The `TOUPDPLS` program processes data.

6. The `EXEC CICS SYNCPOINT` is an explicit commit request. All updated resources in the CICS/ESA transaction are committed.

7. The CICS/ESA server returns the `commarea` into the client's `odata` buffer.

8. The `toupsrv` service `tpcommit` request signals the successful completion of the transaction, causing a commit of its own updated resources.

   > Figure 7-9 Transactional TUXEDO Client Multiple Requests/Responses to CICS/ESA DPL

#### Step-by-Step Description: Transactional TUXEDO Client Multiple Requests/Responses to CICS/ESA DPL

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpbegin` to start the transaction.

3. 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.

4. 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.

5. The `TOUPDPLS` program processes data.

6. The CICS/ESA system returns the `commarea` into the client's `odata` buffer.

7. Step 3 through Step 6 are repeated until the `toupsrv` service loop end conditions are met.

8. 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.

   > Figure 7-10 Transactional CICS/ESA DPL to TUXEDO Request/Response Server

#### Step-by-Step Description: Transactional CICS/ESA DPL to TUXEDO Request/Response Server

1. User-entered `H2PL` invokes `MIRRDPLC` program.

2. 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.

3. The `MIRROR` service processes the data.

4. The `tpreturn` call returns the data into the `commarea` buffer.

5. 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)

The following examples represent a few programming scenarios for using DTP and TUXEDO service invocations.

The recommended method of performing DTP services is to use TUXEDO conversational services instead of request/response services. The conversational service enables a client and a server to communicate as needed over the Connect SNA session conversation.

Although it is most suited for the DPL environment, the `tpcall` is used in the examples for a request/response to a DTP server.

It is recommended you use a DPL model when invoking multiple request/response calls in a single transaction. With DPL, a long-running mirror transaction to the CICS/ESA DPL server is started, enabling the server to process each of the requests over the same conversation. With DTP, each of the ATMI requests will establish a separate conversation; the conversation remains outstanding until the transaction is committed.

Note: To run transactional client/server scenarios, the Connect SNA software must be licensed for sync-level 2 operations.

> Figure 7-11 TUXEDO Client Request/Response to CICS/ESA DTP

#### Step-by-Step Description: TUXEDO Client Request/Response to CICS/ESA DTP

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpcall` for `SIMPDTP`, which is advertised in the *DM_REMOTE_SERVICES section of DMCONFIG file.

3. User transaction `DTPS` starts `TOUPDTPS` program.

4. 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.

5. The `EXEC CICS RECEIVE` command receives the `idata` buffer contents for processing.

6. The `TOUPDTPS` program processes data.

7. 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.

   > Figure 7-12 TUXEDO Client Asynchronous Request/Response to CICS/ESA DTP

#### Step-by-Step Description: TUXEDO Client Asynchronous Request/Response to CICS/ESA DTP

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpacall` for `SIMPDTP`, which is advertised in the *DM_REMOTE_SERVICES section of the DMCONFIG file.

3. User transaction DTPS starts `TOUPDTPS` program.

4. 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.

5. The `EXEC CICS RECEIVE` command receives the `idata` buffer contents for processing.

6. The `TOUPDTPS` program processes data.

7. 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.

   > Figure 7-13 TUXEDO Client Asynchronous Request/Response with No Reply to CICS/ESA DTP

#### Step-by-Step Description: TUXEDO Client Asynchronous Request/Response with No Reply to CICS/ESA DTP

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpacall` with a `TPNOREPLY` request for `SIMPDTP`, which is advertised in the *DM_REMOTE_SERVICES section of DMCONFIG file.

3. User transaction DTPS starts `TOUPDTPS` program.

4. 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.

5. The `EXEC CICS RECEIVE` command receives the `idata` buffer contents for processing.

6. The `TOUPDTPS` program processes data.

   > Figure 7-14 TUXEDO Conversational Client to CICS/ESA DTP, Server Gets Control

#### Step-by-Step Description: TUXEDO Conversational Client to CICS/ESA DTP, Server Gets Control

1. TUXEDO client invokes `toupsrv` service.

2. 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.

3. User transaction DTPS starts `TOUPDTPS` program.

4. 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.

5. The `EXEC CICS RECEIVE` command receives the `idata` buffer contents for processing.

6. The `TOUPDTPS` program processes data.

7. 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`.

   > Figure 7-15 TUXEDO Conversational Client to CICS/ESA DTP, Client Retains Control

#### Step-by-Step Description: TUXEDO Conversational Client to CICS/ESA DTP, Client Retains Control

1. TUXEDO client invokes `toupsrv` service.

2. 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.

3. User transaction DTPS starts `TOUPDTPS` program.

4. 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.

5. The `EXEC CICS RECEIVE` command receives the `tpconnect` `idata` buffer contents for processing.

6. The `TOUPDTPS` program processes data.

7. The `EXEC CICS RECEIVE` command receives the `tpsend idata` contents into the server's `IN-BUFFER`, along with notification that the conversation is over.

8. The server processes the data.

   > Figure 7-16 TUXEDO Conversational Client to CICS/ESA DTP, Client Grants/Gets Control

#### Step-by-Step Description: TUXEDO Conversational Client to CICS/ESA DTP, Client Grants/Gets Control

1. TUXEDO client invokes `toupsrv` service.

2. 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`.

3. User transaction DTPS starts `TOUPDTPS` program.

4. 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.

5. The `EXEC CICS RECEIVE` command receives a `send state` indicator from the `tpconnect` `TPRECVONLY` flag. No data is received into the `INBUFFER`.

6. 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`.

7. The `EXEC CICS RECEIVE` command receives the `tpsend` `idata` contents into the server's `IN-BUFFER`.

   > Figure 7-17 CICS/ESA DTP to TUXEDO Conversational Server, Client Retains Control

#### Step-by-Step Description: CICS/ESA DTP to TUXEDO Conversational Server, Client Retains Control

1. User-entered `H0TP` invokes `MIRRDTPC` program.

2. The `EXEC CICS ALLOCATE` acquires a session to the remote TUXEDO domain.

3. 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.

4. The `EXEC CICS CONNECT PROCESS` command initiates the advertised service mapped to `MIRROR` in the DM_LOCAL_SERVICES section of the DMCONFIG file.

5. Execute the `EXEC CICS SEND WAIT` command to send immediately the contents of the `OUT-BUFFER` to the TUXEDO service in the `tpsvcinfo->data` buffer.

6. The TUXEDO service processes data.

7. The `revent` parameter on the `tprecv` receives a value of `TPEV_SVCSUCC` as a result of the `EXEC CICS SEND LAST` command issued by the host client. `WAIT` suspends processing until the data has successfully been received.

   > Figure 7-18 CICS/ESA DTP to TUXEDO Conversational Server, Client Relinquishes Control

#### Step-by-Step Description: CICS/ESA DTP to TUXEDO Conversational Server, Client Relinquishes Control

1. User-entered HOTP invokes `MIRRDTPC` program.

2. The `EXEC CICS ALLOCATE` acquires a session to the remote TUXEDO domain.

3. 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.

4. The `EXEC CICS CONNECT PROCESS` command initiates the advertised service mapped to `MIRROR` in the DM_LOCAL_SERVICES section of the DMCONFIG file.

5. The `EXEC CICS SEND` command relinquishes control with the `INVITE WAIT` option.

6. The `EXEC CICS RECEIVE` command receives the `tpsend` `idata` buffer contents into the `IN-BUFFER`.

7. The `tpreturn` request tears down the conversation and indicates on the `EXEC CICS RECEIVE` that the conversation is over.

   > Figure 7-19 Transactional TUXEDO Client Request/Response to CICS/ESA DTP

#### Step-by-Step Description: Transactional TUXEDO 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.

1. TUXEDO client `toupclt` invokes `toupsrv` service. (Note that each `tpcall` made in the program must be bookended with a `tpbegin` and a `tpcommit`.)

2. The service issues `tpbegin` to start a transaction.

3. The `toupsrv` service issues `tpcall` for `SIMPDTP`, which is advertised in the *DM_REMOTE_SERVICES section of the DMCONFIG file.

4. User transaction DTPS starts `TOUPDTPS` program.

5. Save the `EIBTRMID` to a program variable. This value is used to identify the specific conversation on your CICS/ESA APPC verbs.

6. The `EXEC CICS RECEIVE` command receives the `idata` buffer contents for processing.

7. The `TOUPDTPS` program processes data.

8. 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.

9. 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.

   > Figure 7-20 Transactional TUXEDO Conversational Client to CICS/ESA DTP, Server Gets Control

#### Step-by-Step Description: Transactional TUXEDO Conversational Client to CICS/ESA DTP, Server Gets Control

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpbegin` to start the transaction.

3. 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.

4. User transaction DTPS starts `TOUPDTPS` program.

5. 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.

6. The `EXEC CICS RECEIVE` command receives the `idata` buffer contents for processing.

7. The `TOUPDTPS` program processes data.

8. 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.

9. 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.

   > Figure 7-21 Transactional TUXEDO Conversational Client to CICS/ESA DTP, Client Grants/Gets Control

#### Step-by-Step Description: Transactional TUXEDO Conversational Client to CICS/ESA DTP, Client Grants/Gets Control

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpbegin` to start the transaction.

3. 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`.

4. User transaction DTPS starts `TOUPDTPS` program.

5. 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.

6. The `EXEC CICS RECEIVE` command receives a `send state` indicator from the `tpconnect` `TPRECVONLY` flag. No data is received into the `INBUFFER`.

7. 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. The data might not be sent immediately.

8. The `EXEC CICS RECEIVE` command flushes the request and receives the `tpsend` `idata` contents into the server's `IN-BUFFER`.

9. 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.

   > Figure 7-22 Transactional CICS/ESA DTP to TUXEDO Conversational Server, Host Client Relinquishes Control

#### Step-by-Step Description: CICS/ESA DTP to Transactional TUXEDO Conversational Server, Host Client Relinquishes Control

1. User-entered H2TP invokes `MIRRDTPC` program.

2. The `EXEC CICS ALLOCATE` acquires a session to the remote TUXEDO domain.

3. 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.

4. The `EXEC CICS CONNECT PROCESS` command initiates the advertised service mapped to `MIRRDTPS`. The `SYNCLEVEL(2)` parameter indicates the inclusion of the TUXEDO service in the CICS/ESA transaction.

5. 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.

6. 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.

7. The `EXEC CICS ISSUE CONFIRMATION` verb responds positively to the confirm request.

8. The `EXEC CICS SYNCPOINT` is an explicit commit request to end the conversation and update all resources in the transaction.

9. The `EXEC CICS FREE` verb explicitly frees the outstanding conversation.

### CPI-C Programming

The Common Programming Interface for Communications (CPI-C) is an implementation choice for program-to-program communications. The reason that CPI-C may be used over other implementations is that CPI-C defines a single programming interface to the underlying network protocols across many different programming languages and environments.

Also, you can use the CPI Resource Recovery interface to provide a consistent interface to system services that allow your programs to coordinate data exchange and updates of databases and resources.

The examples in this section show the protocol exchanges between the local BEA TUXEDO and remote host application program. With BEA TUXEDO, 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.

The recommended method of performing APPC services is to use TUXEDO conversational services instead of request/response services. The conversational service enables a client and a server to communicate as needed over the Connect SNA session conversation.

Although it is most suited for the DPL environment, the `tpcall` is used in the examples for a request/response to an APPC server.

It is recommended you use a DPL model when invoking multiple request/response calls in a single transaction. With DPL, a long-running mirror transaction to the CICS/ESA DPL server is started, enabling the server to process each of the requests over the same conversation. With APPC, each of the ATMI requests will establish a separate conversation; the conversation remains outstanding until the transaction is committed.

Note: To run transactional client/server scenarios or the CPI Resource Recovery interface, the Connect SNA software must be licensed for sync-level 2 operations.

> Figure 7-23 TUXEDO Client Request/Response to Host CPI-C

#### Step-by-Step Description: TUXEDO Client Request/Response to Host CPI-C

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpcall` for `SIMPCPIC`, which is advertised in the *DM_REMOTE_SERVICES section of the DMCONFIG file.

3. The remote service with the `tpname TPNCPIC` invokes `TOUPCPIC` program.

4. 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.

5. The `cmrcv` request receives the `idata` buffer contents for processing

6. The `TOUPCPIC` program processes data.

7. The `cmsst` request prepares the next send request by setting the send type to `CM_SEND_AND_DEALLOCATE`.

8. The `cmsend` request returns the `obuffer` contents into the client `odata` buffer. The buffer is flushed, and the conversation ended.

   > Figure 7-24 TUXEDO Client Asynchronous Request/Response to Host CPI-C

#### Step-by-Step Description: TUXEDO Client Asynchronous Request/Response to Host CPI-C

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpacall` for `SIMPCPIC`, which is advertised in the *DM_REMOTE_SERVICES section of the DMCONFIG file.

3. The remote service with `tpname` `TPNCPIC` invokes `TOUPCPIC` program.

4. 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.

5. The `cmrcv` request receives the `idata` buffer contents for processing.

6. The `TOUPCPIC` program processes data.

7. 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.

8. The `cmdeal` flushes the data to the client, and indicates the conversation is finished.

   > Figure 7-25 TUXEDO Client Asynchronous Request/Response to Host CPI-C with No Reply

#### Step-by-Step Description: TUXEDO Client Asynchronous Request/Response to Host with No Reply

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues tpacall with a `TPNOREPLY` request for `SIMPCPIC`, which is advertised in the *DM_REMOTE_SERVICES section of the DMCONFIG file.

3. The remote service with `tpname TPNCPIC` invokes `TOUPCPIC` program.

4. 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.

5. 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`.

6. The `TOUPCPIC` program processes data.

   > Figure 7-26 TUXEDO Conversational Client to Host CPI-C, Server Gets Control

#### Step-by-Step Description: TUXEDO Conversational Client to Host CPI-C, Server Gets Control

1. TUXEDO client invokes `toupsrv` service

2. 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.

3. The remote service with `tpname TPNCPIC` invokes `TOUPCPIC` program.

4. 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.

5. The `cmrcv` request receives the `idata` buffer contents for processing.

6. The `TOUPCPIC` program processes data

7. The `cmsst` request prepares the next send request by setting the send type to `CM_SEND_AND_FLUSH.`

8. The `cmsend` command returns the `obuffer` contents into the client `tprecv` `odata` buffer. The data is immediately flushed on the send request.

9. The `cmdeal` request ends the conversation.

   > Figure 7-27 TUXEDO Conversational Client To Host CPI-C, Client Retains Control

#### Step-by-Step Description: TUXEDO Conversational Client to Host CPI-C, Client Retains Control

1. TUXEDO client invokes `toupsrv` service.

2. 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`.

3. The remote service with `tpname` `TPNCPIC` invokes `TOUPCPIC` program.

4. 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.

5. The `cmrcv` request receives the `tpsend` `idata` buffer contents for processing. The end of conversation is passed from the `tpreturn` service as `CM_DEALLOCATED_NORMAL`.

6. The `TOUPCPIC` program processes data.

   > Figure 7-28 TUXEDO Conversational Client to Host CPI-C, Client Grants/gets Control

#### Step-by-Step Description: TUXEDO Conversational Client to Host CPI-C, Client Grants/Gets Control

1. TUXEDO client invokes `toupsrv` service.

2. 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`.

3. The remote service with `tpname` `TPNCPIC` invokes `TOUPCPIC` program.

4. 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.

5. The `cmrcv` requests receives the indicator that control has been granted to the server.

6. The `cmsend` request returns its `obuffer` contents into the first client `tprecv` `odata` buffer. The data may not immediately be sent.

7. The `cmsend` request returns its `obuffer` contents into the second client `tprecv odata` buffer. The data may not immediately be sent.

8. The `cmptr` request flushes the data to the client, and grants control to the client.

9. The `cmrcv` request receives the `tpsend` `idata` buffer contents for processing. The end of conversation is passed from the `tpreturn` service as `CM_DEALLOCATED_NORMAL`.

   > Figure 7-29 Host CPI-C to TUXEDO Asynchronous Request/Response Server with No Reply

#### Step-by-Step Description: Host CPI-C to TUXEDO Asynchronous Request/Response Server with No Reply

1. The CPI-C application program `MIRRCPIC` is invoked using environment start-up specifications.

2. 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`.

3. The `cmallc` request initiates the advertised service mapped to `MIRRORSERV` in the DM_LOCAL_SERVICES section of the DMCONFIG file.

4. The `cmsend` request sends the contents of `obuffer` to the TUXEDO service in the `tpsvcinfo->data` buffer.

5. The `cmdeal` request flushes the data, and indicates the conversation is finished with the TPNOREPLY in the `tpsvcinfo->flag` field.

6. The service completes with the `tpreturn`.

   > Figure 7-30 Host CPI-C to TUXEDO Server Request/Response

#### Step-by-Step Description: HOST CPI-C to TUXEDO Server Request/Response

1. The CPI-C application program MIRRCPIC is invoked using environment start-up specifications.

2. 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`.

3. The `cmallc` request initiates the advertised service mapped to `MIRRORSERV` in the DM_LOCAL_SERVICES section of the DMCONFIG file.

4. The `cmsst` request prepares the next send request by setting the send type to `CM_SEND_AND_PREP_TO_RECEIVE`.

5. The `cmsend` request immediately sends the contents of `obuffer` to the TUXEDO service in the `tpsvcinfo->data` buffer and relinquishes control to the `mirrorserv` service.

6. The `cmrcv` request receives the contents of the `odata` returned on the TUXEDO `tpreturn` service, and notification that the conversation has ended with the return code value of `CM_DEALLOCATED_NORMAL`.

   > Figure 7-31 Host CPI-C to TUXEDO Conversational Service, Client Retains Control

#### Step-by-Step Description: Host CPI-C to TUXEDO Conversational Service, Client Retains Control

1. The CPI-C application program MIRRCPIC is invoked using environment start-up specifications.

2. 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`.

3. The `cmallc` request initiates the advertised service mapped to `MIRRORSERV` in the DM_LOCAL_SERVICES section of the DMCONFIG file.

4. The `cmsend` request sends the contents of `obuffer` to the TUXEDO service in the `tpsvcinfo->data` buffer.

5. The `cmdeal` request flushes the data and ends the conversation, as indicated by `TPNOREPLY` in the `tpsvcinfo->flag` field.

   > Figure 7-32 Host CPI-C TUXEDO to Conversational Service, Client Grants Control

#### Step-by-Step Description: TUXEDO Conversational Service, Client Grants Control

1. The CPI-C application program `MIRRCPIC` is invoked using environment start-up specifications.

2. 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`.

3. The `cmallc` request initiates the advertised service mapped to `MIRROR` in the DM_LOCAL_SERVICES section of the DMCONFIG file.

4. The `cmptr` relinquishes control of the conversation to the TUXEDO service indicated as `TPSENDONLY` in the `tpsvcinfo->flag` field. No data is passed in the `tpsvcinfo->data` field.

5. 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`.

   > Figure 7-33 Transactional TUXEDO Client Request/Response to Host CPI-C

#### Step-by-Step Description: Transactional TUXEDO Client Request/Response to Host CPI-C

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpbegin` to start the transaction.

3. 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`.

4. The remote service with `tpname` `TPNCPIC` invokes `TOUPCPIC` program.

5. 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.

6. The `cmrcv` request receives the `idata` buffer contents for processing.

7. 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`.

8. 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.

9. 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.

   > Figure 7-34 Transactional TUXEDO Conversational Client to Host CPI-C, Server Gets Control

#### Step-by-Step Description: Transactional TUXEDO Conversational Client to Host CPI-C, Server Gets Control

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpbegin` to start the transaction.

3. 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`.

4. The remote service with `tpname` `TPNCPIC` invokes `TOUPCPIC` program.

5. 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.

6. The `cmrcv` request receives the `idata` buffer contents sent on the `tpconnect` for processing.

7. The `TOUPCPIC` program processes the data.

8. The `cmsend` returns the `obuffer` contents into the client's `tprecv` `odata` buffer. The buffer contents may not be sent immediately.

9. 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`.

10. 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.

    > Figure 7-35 Transactional TUXEDO Conversational Client to Host CPI-C, Client Grants/Gets Control

#### Step-by-Step Description: Transactional TUXEDO Conversational Client to Host CPI-C, Client Grants/Gets Control

1. TUXEDO client invokes `toupsrv` service.

2. The `toupsrv` service issues `tpbegin` to start the transaction.

3. The `toupsrv` service issues a `tpconnect` service request 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 `toupsrv` can issue is `tprecv`.

4. The remote service with `tpname` `TPNCPIC` invokes `TOUPCPIC` program.

5. 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.

6. The server receives control of the conversation on the `cmrcv` request.

7. The `cmsend` request sends the `obuffer` data contents into the `tprecv idata` buffer. The data might not be sent immediately.

8. The `cmrcv` request relinquishes control of the conversation and waits to receive the `tpsend ibuffer` data contents in the `odata` buffer.

9. 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 terminated after the successful commit exchange.

   > Figure 7-36 Transactional Host CPI-C to TUXEDO Conversational Server, Client Grants Control

#### Step-by-Step Description: Transactional Host CPI-C to TUXEDO Conversational Server, Client Grants Control

1. The CPI-C application program `MIRRCPIC` is invoked using environment start-up specifications.

2. 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`.

3. The `cmssl` sets the conversation attributes to sync-level 2 with `CM_SYNCPOINT`. This allows the TUXEDO service to participate in the transaction.

4. The `cmallc` request initiates the advertised service mapped to `MIRRORSERV` in the DM_LOCAL_SERVICES section of the DMCONFIG file.

5. The MIRRCPIC causes the client to relinquish control to the TUXEDO 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.

6. 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.

7. The client replies positively to the confirm request with `cmcfmd`.

8. 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.

### Where to Find Additional Information

Additional information on the subject of 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

[Top] [Prev] [Next] [Bottom]