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

# 10. CICS/ISC Programming Considerations

This section is intended for application programmers who implement and integrate BEA TUXEDO and host enterprise applications using Customer Information Control System/Extended System Architecture (CICS/ESA) commands with the Intersystem Communications (ISC) facility.

## CICS/ISC Programming

This section covers the following topics:

- About CICS/ISC

- Multi-Region versus Multi-Processor Operations

- ISC Operations

- Time-out and Error Handling

  ### About CICS/ISC

  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, eLink SNA software 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. The eLink SNA software 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). The eLink SNA software 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.

  The eLink SNA software does not relate directly to the MRO 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 10-1 for a generic example of the DPL process.

  In most cases, DPL is completely transparent to both the calling and called programs. An application program is not aware that it is calling a program located on a remote system.

  The remote program is minimally constrained. It can access files and databases, as well as link to other programs, but it cannot perform terminal I/O. Also, it does not provide recovery and restart of CICS/ESA-controlled resources, such as files and databases; implicit support is provided automatically 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.

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

  #### 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 10-2 for a generic example of the DTP process.

  > Figure 10-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. The eLink SNA software 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.

  The eLink SNA software 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.

  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.