Using the distributed program link function

Use these tables to understand the options on the distributed program link function.

You can specify:
  • The name of the remote system (the server region).
  • The name of the server program, if it is known by a different name in the server region.
  • That you want to run the linked program locally, but restrict it to the distributed program link subset of the application programming interface (API) for testing purposes. (Server programs cannot use the entire CICS API when executed remotely; the restrictions are listed in Table 1.
  • That the server program takes a syncpoint independently from the client.
  • The name of the transaction you want the program to run under in the server region.
  • The data length of the COMMAREA being passed.

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 1 are used on the LINK command, and the options shown in Table 2 are used in the PROGRAM resource definition in support of the distributed program link facility.

Table 1. 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.
LENGTH Specifies a halfword binary value that is the length in bytes of the COMMAREA. Specify a valid value (not zero) for the LENGTH option, because a length of zero when used on a DPL request can lead to unpredictable results and possibly a program failure.
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 sync point 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 CICS command summary , but note that for a distributed program link you cannot specify the INPUTMSG or INPUTMSGLEN options.
Table 2. 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 Dynamically routing DPL requests.
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.