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

LINK
>>-LINK--PROGRAM(name)--RETCODE(data-area)--+--------------+---->
'-SYNCONRETURN-'
>--+-----------------------------------------+------------------>
'-COMMAREA(data-area)--LENGTH(data-value)-'
>--+--------------+--+---------------+-------------------------->
'-APPLID(name)-' '-TRANSID(name)-'
>--+------------------------+----------------------------------><
'-DATALENGTH(data-value)-'
Error conditions:LENGERR, LINKERR, NOTAUTH, PGMIDERR,
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 book describes only those parameters that you can use with the external CICS interface. For programming information about the EXEC CICS LINK PROGRAM
command, see the CICS Application Programming Reference manual.
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 generic 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 URMAPPL parameter. You can also use the URMAPPL parameter
in DFHXCURM to override an applid specified on the LINK command. See The EXCI user-replaceable module for information about the URMAPPL 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 the CICS Application Programming Guide 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, to be passed to the invoked
program. If the amount of data being passed in a COMMAREA is small, but the
COMMAREA itself is large so that the linked-to program can return the requested
data, you should specify DATALENGTH in the interest of performance.
- LENGTH(data-value)
- Specifies a halfword binary value that is the length in bytes of the
communication area.
This value may not exceed 32 500 bytes 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 32k 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
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 follows:
- 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.

[[ Contents Previous Page | Next Page Index ]]