Using EXEC CICS LINK command

Link from an MVS™ client program to the specified server program in a server CICS® region.

Format

LINK

Notes:

Error conditions:LENGERR, LINKERR, NOTAUTH, PGMIDERR, RESUNAVAIL, ROLLEDBACK, SYSIDERR, TERMERR, WARNING

Comments

With the exception of the APPLID and RETCODE parameters, the external CICS interface parameters for an EXEC CICS LINK command are the same as for a CICS-CICS DPL command.

This information describes only those parameters that you can use with the external CICS interface. For programming information about the EXEC CICS LINK PROGRAM command, see LINK.

Note that the LENGTH and DATALENGTH parameters specify halfword binary values, unlike the corresponding COMMAREA_len and data_len parameters of the EXCI CALL interface, which specify fullword values.

An external CICS interface EXEC CICS LINK command always uses a generic connection.

Parameters

The parameters that you can use on the external CICS interface form of the LINK command, are as follows:

APPLID(name)

Specifies the APPLID of the target CICS server region.

Although an applid is required for an external CICS interface command, this parameter is optional on the LINK command itself because you can also specify it in the user-replaceable module, DFHXCURM. If you omit the generic APPLID from the LINK command, you must ensure it is specified by the user-replaceable module, DFHXCURM, on the URMCICS parameter. You can also use the URMCICS parameter in DFHXCURM to override an applid specified on the LINK command. See The EXCI user-replaceable module for information about the URMCICS parameter.

COMMAREA(data-area)

Specifies a communication area that is to be made available to the invoked program. In this option, a pointer to the data area is passed.

See Passing data to other programs for more information about passing data to CICS application programs.

DATALENGTH(data-value)

Specifies a halfword binary value that is the length of a contiguous area of storage from the start of the COMMAREA. If the amount of data in a COMMAREA is small, but the COMMAREA itself is large, specify DATALENGTH to improve performance.

LENGTH(data-value)

Specifies a halfword binary value that is the length in bytes of the COMMAREA.

This value should not exceed 24 KB if the COMMAREA is to be passed between any two CICS servers (for any combination of product/version/release), otherwise, if you are confident that the COMMAREA will not be passed on a further LINK request, you can use a COMMAREA up to 32763 in length.

PROGRAM(name)

Specifies the program name (1-8 characters) of the CICS server application program to which control is to be passed unconditionally. The specified name must either have been defined as a program to CICS, or the CICS server region must be capable of autoinstalling a definition for the named program.

Note the use of quotes:

  EXEC CICS LINK PROGRAM('PROGX')

PROGX is in quotes because it is the program name.

  EXEC CICS LINK PROGRAM(DAREA)

DAREA is not in quotes because it is the name of a data area that contains the 8-character program name.

RETCODE(data-area)

Specifies a 20-byte area into which the external CICS interface places return code information. This area is formatted into five 1–word fields as follows:

RESP: The primary response code indicating whether the external CICS interface LINK command caused an exception condition during its execution.
RESP2: The secondary response code that further qualifies, where necessary, some of the conditions raised in the RESP parameter.
ABCODE: Contains a valid CICS abend code if the server program abended in the server region.
MSGLEN: Indicates the length of the message (if any) issued by the CICS server region during the execution of the server program. Note that the length is the actual length of the message text only, and does not include this 1—word length field.
MSGPTR: This is the address of the message text returned by the CICS server region.

Note: MSGLEN and MSGPTR are only valid on a LINKERR condition, with the RESP2 value 414.

SYNCONRETURN

Specifies that the CICS server region, named on the APPLID parameter, is to take a syncpoint on successful completion of the server program.

TRANSID(name)

Specifies the name of the mirror transaction that the remote region is to attach, and under which it is to run the server program. If you omit the TRANSID option, the CICS server region attaches CSMI.

Note: The TRANSID option specified on the LINK command overrides any TRANSID option specified on the program resource definition installed in the CICS server region.

While you can specify your own name for the mirror transaction initiated by DPL requests, the transaction must be defined in the server region, and the transaction definition must specify the mirror program, DFHMIRS. Defining your own transaction to invoke the mirror program gives you the freedom to specify appropriate values for some other options on the transaction resource definition.

See also the important rules about specifying transid with a DPL_Request on topic transid, parameter of DPL_Request command.

Error codes

Most of the exception conditions that are returned on the external CICS interface LINK command are the same as for the CICS-to-CICS distributed program link command. Those that are the same, and their corresponding numeric values are as follows:

LENGERR: 22
PGMIDERR: 27
SYSIDERR: 53
NOTAUTH: 70
TERMERR: 81
ROLLEDBACK: 82
RESUNAVAIL: 121

These exception condition codes are returned in the RESP field.

RESP and RESP2: References to the RESP and RESP2 fields in this section are to the first two fields of the RETCODE parameter.

The exception conditions that are specific to the external CICS interface are as follows:

The RESP2 values on the error condition LENGERR is specific to the external CICS interface.
The exception conditions WARNING and LINKERR are specific to the external CICS interface.

The WARNING and LINKERR exceptions are a result of responses to individual EXCI calls issued by the external CICS interface in response to an EXEC CICS LINK command. These WARNING and LINKERR exceptions correspond to EXCI call responses as indicated in the descriptions.

WARNING (RESP value 4): This is returned when the EXCI module handling the EXEC CICS LINK request receives a USER_ERROR or SYSTEM_ERROR response to a Close_Pipe or Deallocate_Pipe request issued on behalf of an EXEC CICS LINK command. The RESP value is set to WARNING because the DPL request to CICS completed successfully, but an error occurred in subsequent processing.
The RESP2 field is set to the EXCI reason code, which gives more information about the error.
LINKERR (RESP value 88): This is returned when the EXCI module handling the EXEC CICS LINK request receives a RETRYABLE, USER_ERROR, or SYSTEM_ERROR response to an EXCI call issued on behalf of the EXEC CICS LINK command. The DPL request has failed. The RESP2 field is set to the EXCI reason code, which gives more information about the error.

See Response and reason codes returned on EXCI calls for descriptions of EXCI reason codes.

Note: The external CICS interface ignores any WARNING conditions that occur in response to EXCI calls it issues on behalf of an EXEC CICS LINK command. It treats the WARNING on an EXCI call as a good response and continues normally. If no other errors occur, the EXEC CICS command completes with a zero response in the EXEC_RESP field.