|  | BEA eLink for Mainframe SNA 3.2 Information Center
HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW
| TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC

# 8. Application to
Application Programming Considerations

## Overview

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

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

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

- 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 programming techniques (refer to APPC/IMS Programming Considerations).

- 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 (refer to CICS/ISC Programming Considerations).

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

  This section illustrates the most effective ways to implement eLink SNA domain APPC programming options.

  ## Application-to-Application Programming

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

  - Distributed Program Link (DPL)

  - Distributed Transaction Processing (DTP)

  - CPI-C Programming

    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 the eLink SNA gateway, BEA 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 BEA TUXEDO services. This feature is available to either new or existing CICS/ESA programs and BEA 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.

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

  #### Special Treatment of TRANSID for DPL

  The eLink SNA software employs a special feature that enables BEA TUXEDO clients to invoke CICS/ESA server programs and, conversely, CICS/ESA client programs to invoke BEA TUXEDO services. Based on the IBM CICS/ESA mirror transaction, this feature facilitates DPL requests to/from a remote region. The feature is called Mirror Transaction Identifier Support and it involves special treatment of the transaction ID (`TRANSID`) that is part of every DPL request.

  This subsection discusses DPL fundamentals related to this feature and describes how eLink SNA software does the following:

  - Processes DPL requests by implicitly attaching a `TRANSID` to outbound requests only

  - Processes both inbound and outbound requests by allowing you to explicitly attach a `TRANSID` to the requests

  ##### CICS/ESA Fundamentals Relating to Alternate Mirror TRANSID

  In the CICS/ESA context, DPL requests are treated as mirror transactions, which include attachment of the server program to the requestor's `TRANSID`. Two scenarios are possible: implicit attachment (default) and explicit attachment.

  When a server program receives a DPL request from a remote region, the mirror task services the request. The task attaches the request to a mirror transaction, typically CVMI for SYNCONRETURN requests or CSMI for transactional requests. The mirror task then attaches the appropriate mirror transaction to the requestor's `TRANSID`, found in the requestor's `EIBTRNID` field. This is implicit attachment (default).

  Note: Implicit attachment of alternate mirror transaction identifier is not supported for inbound DPL requests to BEA TUXEDO services.

  The other scenario is explicit attachment. The DPL requestor names the `TRANSID` that should be attached to the request instead of the default CSMI or CVMI.

  For outbound requests from BEA TUXEDO domains to remote CICS/ESA regions, this `TRANSID` can be included in the API command (`tpcall`). The `TRANSID` must be defined in the program resource definition for the destination region and it must point to the mirror task DFHMIRS.

  For inbound requests from a remote CICS/ESA region to a local BEA TUXEDO domain, the `TRANSID` is paired with a `PROGRAM` name to explicitly name an advertised service.

  ##### Implicit Attachment of TRANSID

  Figure 8-1 depicts an implicit attachment using the requestor's `TRANSID`. The outbound `tpcall` invokes a service from the remote CICS/ESA region, but does not explicitly name a `TRANSID`. Instead, the `TRANSID` of the requestor is passed to the region as an invoking `TRANSID`. The mirror transaction (CSMI or CVMI) is attached and starts the mirror program, which attaches the requestor's `TRANSID` found in its `EIBTRNID` field. The mirror task then calls the application program.

  Note: The eLink SNA software does not support implicit attachment of TRANSID to inbound requests for BEA TUXEDO services.

  > Figure 8-1 Implicit Attachment of TRANSID (Outbound Requests Only)

  1. The BEA TUXEDO 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.

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

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

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

  Explicit attachment names the `TRANSID` to be attached instead of the default mirror transaction, CSMI or CVMI. The client might use the explicit method for the following reasons:

  - The system administrator wants to restrict the use of a specific `TRANSID`, or impose scheduling constraints on the transaction itself.

  - The remote server might base its response on the value specified in the `EIBTRNID` field, thus causing possible unexpected results when the implicit method is used.

  - The request might be forwarded to another remote CICS/ESA region before the mirror program is invoked, thus bypassing attachment of the `TRANSID`.

  Explicit attachment can be used for both outbound and inbound DPL requests. You can specify the `TRANSID` in the API command or in the `RNAME` parameter for the service definition in the DMCONFIG file.

  The following example shows how to provide a `TRANSID` in the API command:

  >     EXEC CICS LINK PROGRAM("SERVICE1")
  >     	SYSID("AIX1")
  >     	TRANSID("TRN1")

  A `TRANSID` for an outbound DPL request is specified in the DM_REMOTE_SERVICES section of the DMCONFIG file. Conversely, a `TRANSID` for an inbound DPL request is specified in the DM_LOCAL_SERVICES section. The format for the `TRANSID` and server name in the DMCONFIG file entry is as follows:

  `RNAME=AAAA:BBBBBBBB`

  where:

  `AAAA`
    is a 1-4 character alternate mirror `TRANSID`

  `BBBBBBBB`
    is a 1-8 character CICS/ESA program name.

  The colon is required to indicate the `TRANSID`/program name combination. The `TRANSID` must be composed of acceptable CICS/ESA characters:

  `A-Za-z0-9$@#./-_%&Q¢?!|"=,;<>`

  The following paragraphs discuss explicit attachment of `TRANSID` to both outbound requests for remote CICS/ESA services and to inbound requests for BEA TUXEDO services.

  ##### Outbound Requests

  Figure 8-2 depicts the explicit attachment of the `TRANSID` to an outbound request for services in a remote CICS/ESA region. The `TRANSID` can be provided in the API command or in the remote-service definition in the DMCONFIG file. The `RNAME` value in the DMCONFIG file is used to create the alternate mirror ID and invoke the remote server.

  The request passes the transaction ID of the mirror transaction to the remote CICS/ESA region. This transaction ID is defined in the remote region and must point to the mirror program DFHMIRS. When the mirror program invokes the application program, the transaction ID is passed to the program in the `EIBTRNID` field.

  > Figure 8-2 Explicit Attachment of TRANSID for Outbound Requests

  1. The BEA TUXEDO 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.

  2. The request extracts `TRN1` as an alternate mirror transaction ID for the remote region, along with the remote program name `SERVICE1`.

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

  4. The mirror program `DFMMIRS` calls the server application program, passing the `TRN1` ID in the `EIBTRNID` field.

  ##### Inbound Requests

  Figure 8-3 depicts the explicit attachment of the `TRANSID` to inbound request for services in a BEA TUXEDO local domain. The `TRANSID` can be provided in the API command or in the local-service definition in the DMCONFIG file. The `TRANSID` named in the API command or in the requested program name must exactly match an `RNAME` in the DM_LOCAL_SERVICES section of the DMCONFIG file.

  > Figure 8-3 Explicit Attachment of TRANSID for Inbound Requests

  1. The CICS/ESA program makes a request to `INSVC1`, which is a local BEA TUXEDO 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.

  2. The `PROGRAM` and mirror `TRANSID` are extracted from the DPL request. These are used to find an exact `RNAME` match in the DM_LOCAL_SERVICES section of the DMCONFIG file.

  3. The service `SERVICE1,` which is advertised locally in the BEA TUXEDO application, is initiated.

  ##### Explicit Attachment Usage Notes

  You must enter the alternate mirror transaction and remote server name as `RNAME` values in both the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES sections of the DMCONFIG file, using the format shown previously in the "Inbound Requests" section.

  For outbound requests to a CICS/ESA server, the `RNAME` value in the DMCONFIG file is used to create the alternate mirror ID and invoke the remote server.

  For inbound requests, the `TRANSID` named in the API command or in the `PROGRAM` definition is used along with the requested program name to exactly match an `RNAME` associated with a local service entry.

  Note: If an `RNAME` is not found with both the transaction ID and the `PROGRAM` name, an error is returned to the CICS/ESA client.

  Do not insert trailing spaces between the `TRANSID` and colon in the `RNAME` option. The eLink SNA software automatically discards trailing spaces before attempting to match `RNAME` values.

  If the specified `TRANSID`/`PROGRAM` combination in a service name (either local or remote) is not a DPL, eLink SNA software returns an error which is not detected until run time.

  #### Specifying the Size of a DPL Commarea

  To translate a TUXEDO ATMI request to an EXEC CICS LINK request, the eLink SNA gateway uses the INBUFTYPE and OUTBUFTYPE of the remote service to create the COMMAREA for the DPL program.

  For each remote service defined in the DMCONFIG file REMOTE_SERVICES section, INBUFTYPE is a description of the data that the service receives (the format of the request) and OUTBUFTYPE is a description of the data that the service sends as a response.

  When a DPL program is invoked, it receives the request data in a COMMAREA. When the program completes, it returns this same COMMAREA to the program that invoked it. The DPL program cannot change the size of the COMMAREA; therefore, the COMMAREA must be large enough to hold both the request and the reply.

  Before the gateway invokes a DPL program, it uses the INBUFTYPE and OUTBUFTYPE to calculate this size. Because CARRAY and STRING do not have sizes associated with them, the maximum size is used (4096 bytes).

  Note: You cannot specify a response buffer in a `tpcall` or a `tpacall` for the purpose of sizing a COMMAREA. The gateway is unaware of the size of the response buffer that is specified in the `tpcall`, and in `tpacall`, the response buffer is not specified until the reply is retrieved with `tpgetreply`.

  The best approach is to use VIEW types as the `INBUFTYPE` and `OUTBUFTYPE` of DPL programs. This allows the size of the request and response to be described in exact detail. Refer to the examples below:

  > Listing 8-1 Example of DMCONFIG File Entry Specifying VIEWS to Size the COMMAREA

  >     *DM_REMOTE_SERVICES

  >     SIMPDPLV AUTOTRAN=N

  >             LDOM="simpsnad"

  >             RDOM=SIMPSNAG

  >             CONV=N

  >             RNAME="TOUPDPLS"

  >             INBUFTYPE="VIEW:reqstr"

  >             OUTBUFTYPE="VIEW:respstr"

  >             FUNCTION="DPL"

  The following listing shows the corresponding view descriptions:

  > Listing 8-2 Descriptions of VIEWS for Sizing COMMAREA

  >     VIEW reqstr

  >     #TYPE   CNAME           FBNAME          COUNT   FLAG    SIZE    NULL

  >     string  reqstring       -               1       -       20      " "

  >     END

  >     VIEW respstr

  >     #TYPE   CNAME           FBNAME          COUNT   FLAG    SIZE    NULL

  >     string  respstring       -               1       -       50      " "

  >     END

  The following listing shows the code used for a client that requests the `SIMPDPLV` application:

  > Listing 8-3 Program Using Views to Size COMMAREA

  >     /* Include header file generated by views -n myviews.v */

  >     #include "myviews.h"

  >     sendbuf = (struct reqstr *) tpalloc("VIEW", "reqstr", sizeof(struct reqstr));

  >     rcvbuf = (struct respstr *) tpalloc("VIEW", "respstr", sizeof(struct respstr));

  >     tpcall("SIMPDPLV", (char *) sendbuf, 0,  (char **) &rcvbuf, &rcvlen, (long)0);

  In the previous examples, the two VIEWs describe a request string of length 20 and a response string of length 50; therefore, the COMMAREA created can hold a string of 50 characters.

  #### DPL Examples

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

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

  > Figure 8-4 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 8-5 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 8-6 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 8-7 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 8-8 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 8-9 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 8-10 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 8-11 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 BEA TUXEDO service invocations.

  The recommended method of performing DTP services is to use BEA TUXEDO conversational services instead of request/response services. The conversational service enables a client and a server to communicate as needed over the eLink 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.

  The examples in this section represent a few of the many programming scenarios available for using DTP and BEA TUXEDO service invocations. These examples employ the most natural and efficient approaches.

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

  > Figure 8-12 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 8-13 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 8-14 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 8-15 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 8-16 TUXEDO Conversational Client to CICS/ESA DTP, Client Sends/Receives Data

  #### Step-by-Step Description: TUXEDO Conversational Client to CICS/ESA DTP, Client Sends/Receives Data

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

  8. The server processes the data.

  9. The `EXEC CICS SEND WAIT LAST` returns `OUT-BUFFER` data in the `tprecv` `odata` buffer, along with notification that the conversation is over.

     > Figure 8-17 TUXEDO Conversational Client to CICS/ESA DTP, Client Grants Control

  #### Step-by-Step Description: TUXEDO Conversational Client to CICS/ESA DTP, Client Grants 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`, along with notification that the server has relinquished control.

  8. The `EXEC CICS RETURN` ends the conversation, communicated to the `tprecv` as `TPEV_SVCSUCC`.

     > Figure 8-18 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 BEA 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` command to send the contents of the `OUT-BUFFER` to the BEA TUXEDO service in the `tpsvcinfo->data` buffer. The contents might be sent immediately.

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

  7. The BEA TUXEDO service processes data.

  8. The CICS/ESA server processes data.

  9. The TUXEDO `tpreturn` data returns data to the `EXEC CICS RECEIVE`, along with notification that the conversation completed successfully.

     > Figure 8-19 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 BEA 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 8-20 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 8-21 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 8-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 BEA 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 BEA 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 BEA TUXEDO conversational services instead of request/response services. The conversational service enables a client and a server to communicate as needed over the eLink 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 aDPL 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.

  The examples in this section represent a few of the many programming scenarios available for using CPI-C and BEA TUXEDO 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 eLink SNA software must be licensed for sync-level 2 operations.

  > Figure 8-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 8-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 8-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 8-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 8-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 conversation is relinquished with the `TPRECVONLY` flag.

  6. The `TOUPCPIC` program processes data.

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

     > Figure 8-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 `TPRECVONLY` is passed to the `tprecv`, relinquishing control of the conversation.

  10. The `cmdeal` indicates a successful completion of the conversation to the `tprecv`; no data is passed.

      > Figure 8-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 8-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 8-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 8-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 8-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 8-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 8-35 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

  Copyright © 1999 BEA Systems, Inc. All Rights Reserved.
  Required browser version: Netscape Communicator version 4.0 or higher, or Microsoft Internet Explorer version 4.0 or higher.
  Last update: October 1, 1999.