A Perspective on CICS "DPL" by Bob Yelavich --------------------------------------------------- All too often, I read or hear someone say "one program will DPL to the other program", implying the use of CICS' Distributed Program Link. But, in fact, the example being discussed may actually be using CICS' External Call Interface (ECI) or External CICS Interface (EXCI). The person might then say "well, it's all the same". But maybe it's not! The purpose of this article is to draw critical technical attention to the similarities and differences among the various generic CICS linkage commands. Whereas they may appear to be quite similar, there is very good cause to be specific about each type of linkage and to know its characteristics. Let's assume you're the person responsible for "Program B", an application which may be called on from a variety of "front-end" programs. Program B's purpose in life is to perform certain programming functions and return to its caller. The functions of Program B might include writing a message to the terminal which initiated the unit of work which caused Program B to execute. A second function might be to commit changes to protected, recoverable resources, modified during the current invocation of Program B, or not to commit any changes until the entire unit of work is completed, implying that Program B might be entered multiple times during the same unit of work. SCENARIO #1 - A CICS LINK EXAMPLE Let's consider various implementations of Program B. First, let's assume that Program A is invoked from a terminal, perhaps modifies one or more protected resources and then LINKs to Program B, which modifies a protected resource, writes a message to the terminal which initiated the unit of work, issues a CICS syncpoint and then returns to Program A, which completes its processing and ends the unit of work. (Figure 1) If Program A and B are in the same CICS system, the preceding scenario is possible. A terminal initiates the transaction which begins with Program A's execution. Program A modifies one or more protected resources and then LINKs to Program B. The changes made by Program A are not yet committed. Since Program B is executing in the same CICS system, the "principal facility" (the terminal) is known to Program B and it can send a message to the terminal. Program B modifies a protected resource and commits that change by issuing a CICS syncpoint. What must be understood in this scenario is that the syncpoint issued at this time by Program B also commits the changes to protected resources made by Program A, even before control is returned to Program A, which finally ends the transaction. More specifically, the syncpoint issued by Program B causes the initial recoverable unit of work (UOW) to end and a new UOW to begin. The end of the transaction would cause an implicit syncpoint, committing any updates which may have occurred after Program B's explicit syncpoint. If the design intent is for Program B not to commit any of its changes to protected resources as they occur but instead wait until the entire unit of work is done, this too can be done. Program B could be LINKed to repeatedly, make changes on every invocation and commit no changes immediately. When the entire unit of work is completed, for instance with Program B returning to Program A and Program A finally ending, an implicit syncpoint would commit all changes made during the entire unit of work. If Program B commits changes as they occur, if the transaction fails in a later UOW, the committed changes made earlier are not backed out. If Program B does not commit changes as they occur, should Program A or Program B fail at anytime, that failure causes uncommitted updates from either Program A or Program B to be backed out. If neither Program A or B issue an explicit syncpoint, on normal termination of the transaction, a single UOW by definition, all uncommitted changes are then committed with an implied syncpoint. SCENARIO #2 - A CICS DISTRIBUTED PROGRAM LINK (DPL) EXAMPLE Now, let's modify the environment and put Program A and B in two different CICS systems, possibly two regions in the same MVS system or two CICS systems in two different MVS systems. Let's call the two (CICS) systems, System A and System B. (Figure 2) A terminal attached to System A will initiate a transaction, cause Program A to execute and when it LINKs to Program B, the definition of Program B as being remote on System B, will cause the LINK command to be function shipped to System B, where Program B will be entered, execute and return to its caller, Program A on System A. All's well? Ah, not so, I'm afraid. As in the first scenario, Program A can certainly be initiated and modify protected resources on System A before issuing the LINK command. However when Program B is linked-to and begins to execute, it cannot issue any command to the terminal on System A because knowledge of the principal facility is not passed via DPL. If the function of sending a message to the terminal is required, a different method would have to be designed, such as passing message information back to Program A via the COMMAREA, and letting Program A send a message to the terminal, if there was a terminal involved. Assuming Program B did not attempt to send a message to the terminal, is there any concern for Program B issuing an explicit syncpoint after modifying protected resources on System B? Well, comparing Scenarios 1 and 2, yes, there is a difference and probably a concern for consistent behavior. In Scenario 1, a syncpoint by Program B also committed changes made by Program A because they were both executing in the same UOW in System A. This is not the case in Scenario 2, since Program B is subject to SYNCONRETURN status. Program B is forbidden to issue a syncpoint unless Program A specified SYNCONRETURN on the LINK request. If SYNCONRETURN was not specified, the syncpoint command in Program B will cause an ABEND. And, in a SYNCONRETURN environment, Program B's syncpoint would only commit changes made in System B. Program B's syncpoint is not propagated back to its caller. Program B should use the ASSIGN STARTCD() command to determine if SYNCONRETURN was specified by the invoking program. If SYNCONRETURN was specified, then Program B is allowed to issue its own syncpoint or rollback commands. If SYNCONRETURN is not in effect, Program B must not use these commands, and will abend if it does. In addition to controlling Program B's ability to issue syncpoint commands, SYNCONRETURN will cause an automatic syncpoint to be issued when Program B terminates and control is returned to Program A. Earlier it was said that Program B should be capable of being invoked several times within the same (global) unit of work, not committing any changes as they occur but instead waiting until the UOW was completed and then having all changes which may have been made by repetitive invocations of Program B, committed at the same time. As with the local LINK example, Program B being invoked with repetitive DPL requests without SYNCONRETURN, can return to its caller without issuing a syncpoint each time, and later when Program A ends the transaction, an implicit syncpoint would commit all changes made by Program B (and Program A) during the life of the unit of work (the transaction, assuming no intervening explicit syncpoints). SCENARIO #3 - AN EXTERNAL CALL INTERFACE (ECI) REQUEST CICS introduced the CICS Client some years back and its three basic functions are 1) terminal emulation (sometimes called transaction routing), 2) External Call Interface (ECI) and 3) External Presentation Interface (EPI). (Figure 3) Assuming the CICS Client is installed on OS/2 Warp or a Windows machine, the user cannot execute a so-called full function CICS application program which is coded to issue EXEC CICS commands. The CICS Client is sometimes called a "thin client" because it is a small amount of CICS-provided code which is capable only of the three basic functions. With the CICS Client installed, the user could enter a transaction on the workstation, and using terminal emulation, that transaction could be routed to a designated full function CICS system, executed and the results returned to the workstation and the CICS Client. If the customer wrote an application, using a programming language appropriate for the workstation, that application could issue either an ECI or EPI call and the CICS Client can send that request to a designated full function CICS system, sometimes called a CICS server. The EPI function is intended for workstation applications which want to send 3270 data streams to the target CICS system, execute a Basic Mapping Support (BMS) or Terminal Control (TC) 3270 application, and have its output returned to the workstation application. An ECI call is similar to a DPL request in that it appears to the target system that it has been entered due to a DPL request and presented with parameters in a COMMAREA. It is important that you understand just how "similar to a DPL request" this is or is not. Assume a generic Program A is to be run on the CICS Client system, System A, and Program B, let's say is running on an MVS CICS system, System B. A process could be initiated on System A, invoke Program A on System A, and it could alter protected resources on System A before issuing an ECI request to Program B on System B. Program B receives a COMMAREA and can perform updates on System B. Program B cannot issue terminal requests as in Scenario 1 because a principal facility is not known to Program B. As mentioned earlier, if Program B is expected to produce message information to be sent to the end user, it could return such data in the COMMAREA, and Program A could display the message. When the application design calls for Program A to call Program B multiple times within a single UOW, the ECI program specifies extend mode by coding ECI_EXTENDED.} Program A could call Program B multiple times and then terminate normally. On termination, an implicit syncpoint would be propagated from System A to System B, causing changes made by Program B to now be committed. This syncpoint only encompasses the CICS resources updated by Program B, not any of the resources altered by Program A. The ECI program may explicitly notify Program B to issue a syncpoint by coding ECI_COMMIT or by identifying a request as the last in the UOW through ECI_NO_EXTEND. And lastly, if Program A were to fail for some reason, that failure would be propagated to System B, causing uncommitted changes made by Program B to be backed out. If Program B issues a syncpoint after updating a protected resource, that syncpoint is not propagated back to Program A. Full function CICS is not running on System A. If any resources are updated on System A and commit/abort functions are expected, those must be provided by the user. Termination of Program A will cause an implicit syncpoint to be propagated by the CICS Client support to Program B, causing updates not yet committed there to be committed. Again, Program B is only allowed to issue its own syncpoint requests if the ECI program passed SYNCONRETURN to Program B by specifying ECI_NO_EXTEND in its initial call. SCENARIO #4 - EXTERNAL CICS INTERFACE (EXCI) CICS introduced EXCI so as to enable applications running in non-CICS MVS regions to issue "DPL-like" requests to a designated CICS system. (Figure 4) Initially, this was limited to CICS regions in the same MVS, but with the advent of MVS' Cross Systems Coupling, it is now also possible to issue an EXCI from a region on say MVS A and have it routed to a CICS region on MVS B within the same sysplex. CICS support for EXCI comes in two 'flavors'. There is the LINK request which performs all necessary functions to connect to the target CICS system, pass the "DPL-like" request and get a response back. The LINK form of EXCI is usually used where the non-CICS application issues just one or few requests to the target CICS system. If the non-CICS application intends to issue multiple EXCI requests to the target CICS system, the CALL form of EXCI should be used. The call form is more primitive such that one call can be issued to set up the connection between the non-CICS region and the target CICS region, and then some number of functional requests could be issued on the established connection, and finally a request could be issued to terminate the connection. The call form is a better performer for the repetitive request scenario because it re-uses an established connection. For CICS systems earlier than CICS Transaction Server for OS/390 1.3, the EXCI function had one major consideration and that was that a SYNCONRETURN was mandatory on each EXCI request. If we call the non-CICS region, System A, and its application, Program A, and call the CICS region, System B, with Program B, then let's re-examine the application flows discussed previously. Program A could perform some change to one or more resources. Before CICS TS 1.3 do realize that there was no CICS-provided support (or any other support, for that matter) for syncpointing and committing changes made in System A. This would have been a user-provided function, if it existed at all. If Program A made changes to resources and then used EXCI to invoke Program B in CICS, Program B would be designed as though it had been LINKed to and passed parameters in a COMMAREA. Program B cannot issue terminal commands because no principal facility is known to Program B. Program B could pass 'messages' back to Program A as values in the COMMAREA. With CICS systems earlier than CICS TS 1.3, if Program B made one or more changes to protected resources, those changes were committed as part of its return to its EXCI caller. This limitation has now been removed with CICS TS 1.3. Program A will now be able invoke Program B multiple times, without those changes being committed, until Program A ends normally (an implicit syncpoint) or Program A issues an explicit syncpoint. The syncpoint function in OS/390 2.5 is an MVS function, not a CICS-provided function. When issued, the syncpoint function is propagated to the connected CICS TS 1.3 system, Program B in our example. As with earlier discussions, if Program B in CICS TS 1.3 commits its changes as they occur, this is not propagated back to Program A. If Program B makes multiple changes without committing those changes, they will be committed by Program A's explicit or implicit syncpoint. If Program A were to terminate abnormally, that would cause uncommitted changes in System B to be backed out. With LINK and ECI, Program B can issue an ASSIGN command to determine if SYNCONRETURN has been requested. This will be valid with CICS TS 1.3 also. In these cases, Program B would commit its updates before returning to its caller. SUMMARY What has been the point of this discussion? If careful planning has been done, Program B can be invoked from multiple, different environments. Generally speaking, Program B should not issue terminal requests, should expect its input and output via a COMMAREA, and it should behave like a server, not issuing syncpoints but permitting the calling client to cause commit or abort (backout) processing. It's all to easy to say "it's DPL-like" but there is always the concern that this will be taken too casually where in fact there are differences among the DPL-like facilities. There are things you can do with one form of linkage that you cannot do with another. A word to the wise. About the author ---------------- Bob Yelavich retired from IBM in 1996 after 40 years of service and a 30 year association with CICS. Bob has received a number of awards from IBM for his work with CICS. Bob is now an independent consultant, conducting worldwide CICS seminars and writing CICS newsletters. Bob can be reached at yelavich@ibm.net.