Distributed program link (DPL)

The distributed program link function enables a CICS® program (the client program) to call another CICS program (the server program) in a remote CICS region. There are several reasons why you might want to design your application to use distributed program link. Some of these are:

There are several ways in which you can specify that the program to which an application is linking is remote:

  1. By specifying the remote system name on a LINK command
  2. By specifying the remote system name on the installed program resource definition4
  3. By specifying the remote system name using the dynamic routing program (if the installed program definition specifies DYNAMIC(YES) or there is no installed program definition)4
  4. By specifying the remote system name in a XPCREQ global user exit

The basic flow in distributed program link is described in the CICS Intercommunication Guide. The following terms, illustrated in Figure 97, are used in the discussion of distributed program link:

Client region
The CICS region running an application program that issues a link to a program in another CICS region.
Server region
The CICS region to which a client region ships a link request.
Client program
The application program that issues a remote link request.
Server program
The application program specified on the link request, and which is executed in the server region.

Figure 97. Illustration of distributed program link
 This example shows client program PROG1 in client region CICX issuing the CICS command LINK PROGRAM(PROG2) SYSID (CICY). The CICS mirror program DFHMIRS is invoked in server region CICY to run server program PROG2. PROG2 issues RETURN and control returns to PROG1.

Using the distributed program link function

The distributed program link function provides a number of options. You can specify:

A server program can itself issue a distributed program link and act as a client program with respect to the program it links to.

The options shown in Table 34 are used on the LINK command, and the options shown inTable 35 are used in the PROGRAM resource definition in support of the distributed program link facility.

Table 34. Options on LINK command to support DPL
Keyword Description
DATALENGTH Specifies the length of the contiguous area of storage (from the start of the COMMAREA) that the application is sending to a server program.
SYSID Specifies the name of the connection to the server region to which you want the client region to ship the program link request.
Note:
A remote SYSID specified on the LINK command overrides a REMOTESYSTEM name specified on the program resource definition or a sysid returned by the dynamic routing program.
SYNCONRETURN Specifies that you want the server region to take a syncpoint on successful completion of the server program.
Note:
This option is unique to the LINK command and cannot be specified on the program resource definition.
TRANSID Specifies the name of the transaction that the server region is to attach for execution of the server program.
Note:
TRANSID specified on the LINK command overrides any TRANSID specified on the program resource definition.
Note:
Programming information, including the full syntax of the LINK command, is in the CICS Application Programming Reference manual, but note that for a distributed program link you cannot specify the INPUTMSG or INPUTMSGLEN options.
Table 35. Options in the PROGRAM resource definition to support DPL
Keyword Description
REMOTESYSTEM Specifies the name of the connection to the server region (SYSID) to which you want the client region to ship the program link request.
REMOTENAME Specifies the name by which the program is known in the server region (if different from the local name).
DYNAMIC Specifies whether the program link request can be dynamically routed. For detailed information about the dynamic routing of DPL requests, see the CICS Recovery and Restart Guide.
EXECUTIONSET Specifies whether the program is restricted to the distributed program link subset of the CICS API.
Note:
This option is unique to the program definition and cannot be specified on the LINK command.
TRANSID Specifies the name of the transaction that the server region is to attach for execution of the server program.

Examples of distributed program link

A COBOL example of a distributed program link command is shown in Figure 98. The numbers down the right-hand side of the example refer to the numbered sections, following the figure, which give information about each option.

Important

If the SYSID option of the LINK command specifies the name of a remote region, any REMOTESYSTEM, REMOTENAME, or TRANSID attributes specified on the program definition or returned by the dynamic routing program have no effect.

Figure 98. COBOL example of a distributed program link
EXEC CICS LINK PROGRAM('DPLPROG')            1
               COMMAREA(DPLPRO-DATA-AREA)    2
               LENGTH(24000)                 2
               DATALENGTH(100)               2
               SYSID('CICR')                 3
               TRANSID('AC20')               4
               SYNCONRETURN                  5
    
  1. The program name of the server program

    A program may have different names in the client and server regions. The name you specify on the LINK command depends on whether or not you specify the SYSID option.

    If you specify the name of a remote region on the SYSID option of the LINK command, CICS ships the link request to the server region without reference to the REMOTENAME attribute of the program resource definition in the client region, nor to any program name returned by the dynamic routing program. In this case, the PROGRAM name you specify on the LINK command must be the name by which the program is known in the server region.

    If you do not specify the SYSID option on the LINK command, or you specify the name of the local client region, the PROGRAM name you specify on the LINK command must be the name by which the program is known in the client region. CICS looks up the program resource definition in the client region. Assuming that the REMOTESYSTEM option of the installed program definition specifies the name of a remote region, the name of the server program on the remote region is obtained from:

    1. The REMOTENAME attribute of the program definition
    2. If REMOTENAME is not specified, the PROGRAM option of the LINK command.

    If the program definition specifies DYNAMIC(YES), or there is no installed program definition, the dynamic routing program is invoked and can accept or change the name of the server program.

  2. The communication data area (COMMAREA)

    To improve performance, you can specify the DATALENGTH option on the LINK command. This allows you to specify the amount of COMMAREA data you want the client region to pass to the server program. Typically, you use this option when a large COMMAREA is required to hold data that the server program is to return to the client program, but only a small amount of data needs to be sent to the server program by the client program, as in the example.

    If more than one server program updates the same COMMAREA before it is passed back to the client program, use the DATALENGTH option to specify the length of the COMMAREA. Ensure that if any of the server programs use an XCTL command to pass the COMMAREA to the next server program, they specify the same length and address for it. This ensures that the original COMMAREA is returned to the client program. If a different length or address are specified, the invoked program will receive a copy of the COMMAREA, rather than the original COMMAREA, and so the original COMMAREA will not be returned to the client program. COMMAREA has more information about using COMMAREAs to pass data to other programs.

  3. The remote system ID (SYSID)

    You can specify the 4-character name of the server region to which you want the application region to ship a program link request using any of the following:

    The rules of precedence are:

    1. If the SYSID option on the EXEC CICS LINK command specifies a remote CICS region, CICS ships the request to the remote region.

      If the program definition specifies DYNAMIC(YES)--or there is no program definition--the dynamic routing program is invoked for notification only--it cannot re-route the request.

    2. If the SYSID option is not specified or specifies the same name as the local CICS region:
      1. If the program definition specifies DYNAMIC(YES)--or there is no installed program definition--the dynamic routing program is invoked, and can route the request.

        The REMOTESYSTEM option of the program definition, if specified, names the default server region passed to the dynamic routing program.

        Note:
        If the REMOTESYSTEM option names a remote region, the dynamic routing program cannot route the request locally.
      2. If the program definition specifies DYNAMIC(NO), CICS ships the request to the remote system named on the REMOTESYSTEM option. If REMOTESYSTEM is not specified, CICS runs the program locally.

    The name you specify is the name of the connection definition installed in the client region defining the connection with the server region. (CICS uses the connection name in a table look-up to obtain the netname (VTAM® APPLID) of the server region.) The name of the server region you specify can be the name of the client region, in which case the program is run locally.

    If the server region is unable to load or run the requested program (DPLPROG in our example), CICS returns the PGMIDERR condition to the client program in response to the link request. Note that EIBRESP2 values are not returned over the link for a distributed program link request where the error is detected in the server region. For errors detected in the client region, EIBRESP2 values are returned.

    You can also specify, or modify, the name of a server region in an XPCREQ global user exit program. See the CICS Customization Guide for programming information about the XPCREQ global user exit point.

  4. The remote transaction (TRANSID) to be attached

    The TRANSID option is available on both the LINK command and the program resource definition. This enables you to tell the server region the transaction identifier to use when it attaches the mirror task under which the server program runs. If you specify the TRANSID option, you must define the transaction in the server region, and associate it with the supplied mirror program, DFHMIRS. This option allows you to specify your own attributes on the transaction definition for the purpose of performance and fine tuning. For example, you could vary the task priority and transaction class attributes.

    If the installed program definition specifies DYNAMIC(YES), or there is no installed program definition, the dynamic routing program is invoked and (provided that the SYSID option of the LINK command did not name a remote region) can change the value of the TRANSID attribute.

    The order of precedence is:

    1. If the SYSID option of the LINK command specified a remote region, a TRANSID supplied on the LINK
    2. A TRANSID supplied by the dynamic routing program
    3. A TRANSID supplied on the LINK command
    4. The TRANSID attribute of the program definition.
    5. The mirror TRANSID, CSMI.

    You are recommended to specify the transaction identifier of the client program as the transaction identifier for the server program. This enables any statistics and monitoring data you collect to be correlated correctly under the same transaction.

    The transaction identifier used on a distributed link program request is passed to the server program as follows:

  5. The SYNCONRETURN option for the server program

    When you specify the SYNCONRETURN option, it means that the resources on the server are committed in a separate logical unit of work immediately before returning control to the client; that is, an implicit syncpoint is issued for the server just before the server returns control to the client. Figure 99 provides an example of using distributed program link with the SYNCONRETURN option. The SYNCONRETURN option is intended for use when the client program is not updating any recoverable resources, for example, when performing screen handling. However, if the client does have recoverable resources, they are not committed at this point. They are committed when the client itself reaches a syncpoint or in the implicit syncpoint at client task end. You must ensure that the client and server programs are designed correctly for this purpose, and that you are not risking data integrity. For example, if your client program has shipped data to the server that results in the server updating a database owned by the server region, you only specify an independent syncpoint if it is safe to do so, and when there is no dependency on what happens in the client program. This option has no effect if the server program runs locally in the client region unless EXECUTIONSET(DPLSUBSET) is specified. In this case, the syncpoint rules governing a local link apply.

    Without the SYNCONRETURN option, the client commits the logical unit of work for both the client and the server resources, with either explicit commands or the implicit syncpoint at task end. Thus, in this case, the server resources are committed at the same time as the client resources are committed. Figure 100 shows an example of using distributed program link without the SYNCONRETURN option.

Figure 99. Using distributed program link with the SYNCONRETURN option
dfhp3j07
Note:
This includes three logical units of work: one for the client and two for the server. The client resources are committed separately from the server.
Figure 100. Using distributed program link without the SYNCONRETURN option
 Example showing client program in UOW1 issuing LINK to server program that executes in UOW2 and issues a SYNCPOINT command to commit UOW2 and start UOW3, which is then committed and terminated by an implicit SYNCPOINT on return to the client program, which continues to update resources in UOW1.
Note:
The implicit or explicit syncpoint causes all client and server resources to be committed. There is only one logical unit of work because the client is responsible for determining when both the client and server resources are committed.

You need to consider the case when the client has a HANDLE ABEND command. When the client is handling abends in the server, the client gets control when the server abends. This is also true when the SYNCONRETURN option has been specified on the LINK command. In this case, it is recommended that the client issues an abend after doing the minimum of cleanup. This causes both the client logical unit of work and the server logical unit of work to be backed out.

Programming considerations for distributed program link

There are some factors you should consider when writing application programs that use distributed program link.

Issuing multiple distributed program links from the same client task

A client task cannot request distributed program links to a single CICS server region using more than one transaction code in a single client unit of work unless the SYNCONRETURN option is specified. It can issue multiple distributed program links to one CICS server system with the same or the default transaction code.

Sharing resources between client and server programs

The server program does not have access to the lifetime storage of tasks on the client, for example, the TWA. Nor does it necessarily have access to the resources that the client program is using, for example, files, unless the file requests are being function shipped.

Mixing DPL and function shipping to the same CICS system

Great care should be taken when mixing function shipping and DPL to the same CICS system, from the same client task. These are some considerations:

See the CICS Intercommunication Guide for more information about function shipping.

Mixing DPL and DTP to the same CICS system

Care should be taken when using both DPL and DTP in the same application, particularly using DTP in the server program. For example, if you have not used the SYNCONRETURN option, you must avoid taking a syncpoint in the DTP partner which requires the DPL server program to syncpoint.

Figure 101. Example of mixing DPL and DTP
 Example showing a client program using DPL to LINK to a server program. The server program then uses DTP to communicate with a DTP partner.

Restricting a program to the distributed program link subset

When a program executes as the result of a distributed program link, it is restricted to a subset of the full CICS API called the distributed program link subset. The commands that are prohibited in a server program are summarized in Table 36.

You can specify, in the program resource definition only, that you want to restrict a program invoked by a local LINK command to this subset with the EXECUTIONSET(DPLSUBSET) option. The use of any prohibited commands can then be detected before an application program is used in a distributed environment. The EXECUTIONSET(DPLSUBSET) option should be used for very early testing purposes only, and should never be used in production.

When the server program is running locally the following considerations apply:

Determining how a program was invoked

The 2-byte values returned on the STARTCODE option of the ASSIGN command are extended in support of the distributed program link function enabling the server program to find out that it is restricted to the distributed program link subset. See the CICS Application Programming Reference manual for programming information about EXEC CICS commands.

Accessing user-related information with the ASSIGN command

The values returned with the USERID and OPID keywords of the ASSIGN command in the server program depend on the way the ATTACHSEC option is defined for the connection being used between the client CICS region and the server CICS region. For example, the system could be defined so that the server program could access the same USERID and OPID values as the client program or could access different values determined by the ATTACHSEC option.

If ATTACHSEC(LOCAL) is specified, the userid to which the OPID and USERID parameters correspond is one of the following, in the order shown:

  1. The userid specified on the USERID parameter (for preset security) of the SESSIONS resource definition, if present
  2. The userid specified on the SECURITYNAME parameter of the connection resource definition, if present and no preset security userid is defined on the sessions
  3. The userid specified on the DFLTUSER system initialization parameter of the server region, if neither the sessions nor connection definitions specify a userid

If any value other than LOCAL is specified for ATTACHSEC, the signed-on userid is the one received in the function management header (FMH5) from the client region.

See the CICS RACF Security Guide for more information about link security and DPL security with MRO.

Another security-related consideration concerns the use of the CMDSEC and RESSEC options of the ASSIGN command. These are attributes of the transaction definition for the mirror transaction in the server region. They can be different from the definitions in the client region, even if the same TRANSID is used.

Exception conditions for LINK command

There are error conditions introduced in support of DPL.

Exception conditions returned to the client program

Condition codes returned to a client program describe such events as "remote system not known" or "failure to commit" in the server program. There are different reasons, identified by EIBRESP2 values, for raising the INVREQ and LENGERR conditions on a LINK command. The ROLLEDBACK, SYSIDERR, and TERMERR conditions may also be raised. See the CICS Application Programming Reference manual for programming information about these commands.

If the mirror transaction in the remote region fails, the application program that issued the DPL request can handle the abend of the mirror, and commit its own local resources, only if both the following are true:

  1. The application program explicitly handles the abend caused by the mirror’s failure, and either:
  2. The remote mirror transaction performed no recoverable work within the scope of the application program’s unit of work. That is, the mirror was invoked only for a distributed program link (DPL) request with SYNCONRETURN.

In all other cases--that is, if the application program does not handle the abend, or the mirror does any recoverable work (for example, a file update, even to a non-recoverable file)--CICS forces the transaction to be backed out.

The PGMIDERR condition is raised on the HANDLE ABEND PROGRAM, LOAD, RELEASE, and XCTL commands if the local program definition specifies that the program is remote. This exception is qualified by an EIBRESP2 value of 9.

Exception conditions returned to the server program

The INVREQ condition covers the use of prohibited API commands. INVREQ is returned, qualified by an EIBRESP2 value of 200, to a server program if it issues one of the prohibited commands summarized in Table 36. If the server program does not handle the INVREQ condition, the default action is to abend the mirror transaction under which the server program is running with abend code ADPL.

For programming information about the DPL-related exception conditions, see the CICS Application Programming Reference manual.

Table 36. API commands prohibited in programs invoked by DPL
Command Options
ASSIGN ALTSCRNHT ALTSCRNWD APLKYBD APLTEXT BTRANS COLOR DEFSCRNHT DEFSCRNWD DELIMITER DESTCOUNT DESTID DESTIDLENG DS3270 DSSCS EWASUPP EXTDS FACILITY FCI GCHARS GCODES GMMI HILIGHT INPARTN KATAKANA LDCMNEM LDCNUM MAPCOLUMN MAPHEIGHT MAPLINE MAPWIDTH MSRCONTROL NATLANGINUSE NEXTTRANSID NUMTAB OPCLASS OPSECURITY OUTLINE PAGENUM PARTNPAGE PARTNS PARTNSET PS QNAME SCRNHT SCRNWD SIGDATA SOSI STATIONID TCTUALENG TELLERID TERMCODE TERMPRIORITY TEXTKYBD TEXTPRINT UNATTEND USERNAME USERPRIORITY VALIDATION
CONNECT PROCESS all
CONVERSE all
EXTRACT ATTRIBUTES all
EXTRACT PROCESS all
FREE all
HANDLE AID all
ISSUE ABEND CONFIRMATION ERROR PREPARE SIGNAL PRINT ABORT ADD END ERASE NOTE QUERY RECEIVE REPLACE SEND WAIT
LINK INPUTMSG INPUTMSGLEN
PURGE MESSAGE all
RECEIVE all
RETURN INPUTMSG INPUTMSGLEN
ROUTE all
SEND CONTROL MAP PARTNSET TEXT TEXT(MAPPED) TEXT(NOEDIT) PAGE
SIGNOFF all
SIGNON all
Start of changeSTARTEnd of change Start of changeTERMIDEnd of change
SYNCPOINT Can be issued in server region if SYNCONRETURN specified on LINK
WAIT TERMINAL all
XCTL INPUTMSG INPUTMSGLEN

The following commands are also restricted but can be used in the server region if SYNCONRETURN is specified on the LINK:

Where only certain options are prohibited on the command, they are shown. All the APPC commands listed are prohibited only when they refer to the principal facility. One of these, the CONNECT PROCESS command, causes an error even if it refers to the principal facility in a non-DPL environment. It is included here because, if a CONNECT PROCESS command refers to its principal facility in a server program, the exception condition raised indicates a DPL error.


4.
By "installed program definition" we mean a program definition that has been installed statically, by means of autoinstall, or by an EXEC CICS CREATE command.

[[ Contents Previous Page | Next Page Index ]]