EXEC CICS LINK command (EXCI)
Link from an MVS™ client program to the specified server program in a server CICS® region.
Format
Error conditions: CCSIDERR , CHANNELERR , CODEPAGEERR , CONTAINERERR , 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
- 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.
- CHANNEL( name )
-
Specifies the name (1 - 16 characters) of a channel that is to be
made available to the called
program. The acceptable characters are A - Z a - z 0 - 9 $ @ # / % &
? ! : | " = ¬ , ; < > .
- and _. Leading and embedded blank characters are not permitted.
If the name supplied is less than
16 characters, it is padded with trailing blanks up to 16
characters. If the channel does not exist,
it is created. As there is only one LINK level for an EXCI client,
this channel remains in scope.
For more information about channel scope, see
The scope of a channel.
Channel names are always in EBCDIC. The set of allowed characters for channel names, as listed earlier, includes some characters that do not have the same representation in all EBCDIC code pages. Therefore, if channels are to be shipped between regions, it is advisable to restrict the characters that are used to name channels to A-Z a-z 0-9 & : = , ; < > . - and _.
You can specify the channel name DFHTRANSACTION to use a transaction channel. In CICS, a transaction channel does not go out of scope when the link level changes: it is always accessible in the transaction. For more information, see Channels and containers.
The program that issues the LINK command can specify the name of a channel on the command. The specified channel might already exist, created by the program using one or more PUT CONTAINER commands. Alternatively, the program can specify the name of a channel that does not currently exist, in which case a new empty channel is created.
- 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 quotation marks:
EXEC CICS LINK PROGRAM('PROGX')
PROGX is in quotation marks 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 in . .
Error codes
- LENGERR
- 22
- PGMIDERR
- 27
- SYSIDERR
- 53
- NOTAUTH
- 70
- TERMERR
- 81
- ROLLEDBACK
- 82
- CONTAINERERR
- 110
- RESUNAVAIL
- 121
- CHANNELERR
- 122
- CCSIDERR
- 123
- CODEPAGEERR
- 125
These exception condition codes are returned in the RESP field.
- 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.
- 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.