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:
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:
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.
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. |
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. |
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.
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.
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
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:
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.
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.
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:
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.
The REMOTESYSTEM option of the program definition, if specified, names the default server region passed to the dynamic routing program.
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.
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:
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:
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.
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.
There are some factors you should consider when writing application programs that use distributed program link.
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.
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.
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.
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.
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:
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.
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:
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.
There are error conditions introduced in support of DPL.
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:
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.
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.
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 |
![]() ![]() |
![]() ![]() |
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.