Examples of distributed program link

A COBOL example of a distributed program link command shows the syntax of the command.

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 1. 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 might have different names in the client and server regions. The name you specify on the LINK command depends on whether 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, or to any program name returned by the dynamic routing program. In this situation, 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. You can use this option 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.

    Ensure that you 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.

    When you use a COMMAREA, the program that is linked to must verify that the EIBCALEN field in the EIB of the task matches what the program expects. For more information, see COMMAREA.

  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 SYSID option of the LINK command
    • The REMOTESYSTEM option of the program resource definition
    • The dynamic routing program.
    The rules of precedence are as follows:
    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 lookup to obtain the netname (z/OS Communications Server 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 cannot 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 Enabling for specific invocation types 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:
    • If you specify your own transaction identifier for the distributed link program request, this is passed to the server program in the EIBTRNID field of the EIB.
    • EIBTRNID is set to the TRANSID value as specified in the DPL API or server resource definition. Otherwise, it defaults to the client's transaction code, which is the same value that is in the client's EIBTRNID.
    Note: If the mirror transaction accesses Db2®, EIBTRNID is used to determine which DB2ENTRY definition to use.
  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 2 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 as part of the same syncpoint when the client resources are committed. Figure 3 shows an example of using distributed program link without the SYNCONRETURN option.

Figure 2. Using distributed program link with 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: 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 3. Using distributed program link without the SYNCONRETURN option
Example showing client program in UOW1 issuing LINK to server program that executes in UOW1 and returns to the client program still in UOW1. The client program issues LINK to the server program again to update further resources, still in UOW1, and the server returns to the client program. The client program takes an implicit or explicit syncpoint, which marks the end of 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 clean up. This causes both the client logical unit of work and the server logical unit of work to be backed out.