LINK

Link to another program expecting return. The external CICS® interface (EXCI) provides a LINK command that performs all six commands of the interface in one invocation. See the CICS External Interfaces Guide for information about the EXCI.

Read syntax diagramSkip visual syntax diagram
LINK

>>-LINK--PROGRAM(name)------------------------------------------>

>--+-------------------------------------------------------------------------+-->
   +-COMMAREA(data-area)--+--------------------+--+------------------------+-+   
   |                      '-LENGTH(data-value)-'  '-DATALENGTH(data-value)-' |   
   '-CHANNEL(name)-----------------------------------------------------------'   

>--+------------------------------------------------------------+-><
   +-INPUTMSG(data-area)--+-------------------------+-----------+   
   |                      '-INPUTMSGLEN(data-value)-'           |   
   '-+-------------------+--+--------------+--+---------------+-'   
     '-SYSID(systemname)-'  '-SYNCONRETURN-'  '-TRANSID(name)-'     

Conditions: Start of changeCHANNELERR, End of changeINVREQ, LENGERR, NOTAUTH, PGMIDERR, RESUNAVAIL, ROLLEDBACK, SYSIDERR, TERMERR

This command is threadsafe when it is used to link to a program in a local CICS region. It is non-threadsafe when it is used to link to a program in a remote CICS region.

 

Description

LINK passes control from an application program at one logical level to an application program at the next lower logical level.

If the requested program is not defined to CICS, and AUTOINSTALL is active, CICS supplies a definition for the program. If this is a local definition, and the linked-to program is not already in main storage, CICS loads it.

In some circumstances, the linked-to program may reside on another CICS region—see Distributed program link.

When the RETURN command is executed in the linked-to program, control is returned to the program initiating the link at the next sequential executable instruction.

The linked-to program operates independently of the program that issues the LINK command with regard to handling conditions, attention identifiers, abends, and execution key. For example, the effects of HANDLE CONDITION commands in the linking program are not inherited by the linked-to program, but the original HANDLE CONDITION commands are restored on return to the linking program. See the CICS Application Programming Guide for more information and an illustration of the concept of logical levels.

You can use the HANDLE ABEND command to deal with abnormal terminations in other link levels. See the CICS Application Programming Guide for further details about the relationship between LINK and HANDLE ABEND.

Distributed program link

In any of the following cases, the link is a distributed program link (DPL):
  • You specify a remote region name on the SYSID option (with or without the associated TRANSID and SYNCONRETURN options).
  • The REMOTESYSTEM option on the installed PROGRAM definition 1 specifies the name of a remote region.
  • The installed program definition specifies DYNAMIC(YES)—or there is no installed program definition—and the dynamic routing program routes the link request to a remote region.

In response to a distributed program link, the local CICS region (the client region) ships the link request to the remote region (the server region). The server region executes the linked-to program (the server program) on behalf of the program issuing the link request (the client program).

The SYSID and INPUTMSG options are mutually exclusive. If you specify both options on a LINK command, the translator issues error message DFH7230 (severity E) indicating conflicting options. See the DFH7xxx (DFHExP command translator diagnostic) messages entry in the CICS Messages and Codes manual for an explanation of severity E for the different supported languages.

A server program running in the server region is restricted to a DPL subset of the CICS API. Briefly, the server program cannot issue:
  • Terminal control commands that reference the principal facility
  • Options of ASSIGN that return terminal attributes
  • BMS commands
  • Signon and signoff commands
  • Batch data interchange commands
  • Commands that address the TCTUA.

For details of the restricted DPL subset of the API, see API restrictions for distributed program link.

Abends in the server program

If a server program abends, the abend code is returned to the client program. If the client program is not written to handle the abend returned by the server program, the client program abends with the same abend code returned by the server program.

You cannot use DPL to link to the CICS master terminal program, DFHEMTA, or to the RDO program, DFHEDAP. The addresses passed as parameters to DFHEMTA and DFHEDAP are valid only in the region that issues the EXEC CICS LINK command, which means you cannot route a DFHEMTA or DFHEDAP request to a remote CICS.

Important: For examples of the use of the LINK command when the linked program is remote, see the CICS Application Programming Guide. For information about writing a dynamic routing program, see the CICS Customization Guide.

Options

Start of changeCHANNEL(name)End of change
Start of changespecifies the name (1–16 characters) of a channel that is to be made available to the invoked 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.

Channel names are always in EBCDIC. The allowable set of characters for channel names, listed above, includes some characters that do not have the same representation in all EBCDIC code pages. We therefore recommend that, if containers are to be shipped between regions, the characters used in naming them should be restricted to A-Z Start of changea-zEnd of change 0-9 & : = , ; < > . - and _.

The program that issues the LINK command may:
  • Have created the channel by means of one or more PUT CONTAINER CHANNEL commands
  • Specify its current channel, by name
  • Name a non-existent channel, in which case a new, empty, channel is created
End of change
COMMAREA(data-area)
specifies a communication area that is to be made available to the invoked program. In this option the data area is passed, and you must give it the name DFHCOMMAREA in the receiving program. (See the section about passing data to other programs in the CICS Application Programming Guide.)
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. For a remote LINK request, 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.

Start of changeThe value of DATALENGTH is only checked when the LINK request is remote or dynamic. It is not checked for static local links.End of change

DATALENGTH cannot be used at the same time as INPUTMSG.

INPUTMSG(data-area)
specifies data to be supplied to the invoked program when it first issues a RECEIVE command. This data remains available until the execution of a RECEIVE or RETURN command. An invoked program can invoke a further program and so on, creating a chain of linked programs. If a linked-to chain exists, CICS supplies the INPUTMSG data to the first RECEIVE command executed in the chain. If control returns to the program that issued the LINK with INPUTMSG before the INPUTMSG data has been accepted by a RECEIVE command, CICS assumes that a RECEIVE command has been issued. This means that the original INPUTMSG data is no longer available.

INPUTMSG cannot be used at the same time as DATALENGTH.

See also the CICS Application Programming Guide for more information about the INPUTMSG option.

INPUTMSGLEN(data-value)
specifies a halfword binary value to be used with INPUTMSG.
LENGTH(data-value)
specifies a halfword binary value that is the length in bytes of the COMMAREA (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).
PROGRAM(name)
specifies the identifier (1–8 characters) of the program to which control is to be passed unconditionally.
In any of the following cases, the linked-to program is a server program in a remote region:
  • The SYSID option specifies a remote region.
  • The REMOTESYSTEM option on the installed PROGRAM definition 2 specifies the name of a remote region.
  • The installed program definition specifies DYNAMIC(YES)—or there is no installed program definition—and the dynamic routing program routes the link request to a remote region.
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 actual program name.
Note: When linking to a CICS 3270 program that is to be executed under the Link3270 bridge mechanism, the PROGRAM name must be DFHL3270, not the name of the target 3270 program.
SYNCONRETURN
specifies that the server region named on the SYSID option is to take a syncpoint on successful completion of the server program.
Changes to recoverable resources made by the server program are committed or rolled-back independently of changes to recoverable resources made by the client program issuing the LINK request, or changes made by the server in any subsequent LINK.
  • The NORMAL condition is returned if changes to recoverable resources are committed before return from the server program.
  • The ROLLEDBACK condition is returned if changes to recoverable resources are rolled back before return from the server program.
  • The TERMERR condition is raised following failure of the communications link or the system in which the server program is executing. The client program is responsible for handling the condition and ensuring that data consistency is restored.

Synconreturn is only applicable to remote LINKs, it is ignored if the LINK is local.

SYSID(systemname)
specifies the system name of a CICS server region to where the program link request is to be routed.

If you do not specify a remote system name in the SYSID option or omit the SYSID option, CICS uses the REMOTESYSTEM attribute defined in the installed PROGRAM definition. If you specify a local system name in the SYSID option or the REMOTESYSTEM attribute, CICS ignores the name.

A remote system name specified on the SYSID option takes priority over any remote system name specified on the PROGRAM resource definition or returned by the dynamic routing 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, reference is made to PROGRAM resource definitions held locally if the installed PROGRAM definition specifies remote attribute DYNAMIC(YES). Otherwise, the server region attaches either CSMI, CPMI, or CVMI by default.

The transaction name you specify on the LINK command takes priority over any transaction specified on the program resource definition. Whilst 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.

Conditions

Start of changeCHANNELERREnd of change
Start of changeRESP2 values:
1
The name specified on the CHANNEL option contains an illegal character or combination of characters.
End of change
INVREQ
RESP2 values:
8
A LINK command with the INPUTMSG option is issued for a program that is not associated with a terminal, or that is associated with an APPC logical unit, or an IRC session.
14
The SYNCONRETURN option is specified but the program issuing the link request (the client program) is already in conversation with a mirror task in the remote region specified on the SYSID option. (That is, a unit of work (UOW) is in progress, or the system initialization parameter MROFSE=YES has been specified in the client region.) In this case, the client program is in an incorrect state to support the SYNCONRETURN option.
15
The program issuing the link request is already in conversation with a mirror task and the TRANSID specified is different from the transaction identifier of the active mirror.
16
The TRANSID specified is all blanks.
17
The TRANSID supplied by the dynamic routing program is all blanks.
19
A LINK command with the INPUTMSG option is issued for a program that is the subject of a DPL request; that is, SYSID is also specified.
30
The program manager domain has not yet been initialized. This is probably due to a link request having been made in a first stage PLT.
44
A LINK has been attempted to a Java™ program, but the JVMpool is disabled.
45
A LINK has been attempted to a Java program, but the JVM profile cannot be found.
46
A LINK has been attempted to a Java program, but the JVM profile is not valid.
47
A LINK has been attempted to a Java program, but the system properties file cannot be found.
48
A LINK has been attempted to a Java program, but the user class cannot be found.
49
The shared class cache is STOPPED and autostart is disabled, so a Java program requesting use of the shared class cache cannot be executed.
Start of change50End of change
Start of changeThe Language Environment® options specified in DFHJVMRO are too long.End of change

Default action: terminate the task abnormally.

Note: RESP2 values are not returned to the client for conditions occurring in a DPL server program.
LENGERR
RESP2 values:
11
The COMMAREA length is less than 0 or greater than 32767.
12
The length specified on the DATALENGTH option is a negative value.
13
The length specified on the DATALENGTH option is greater than the length specified on the LENGTH option.
26
The COMMAREA address is zero, but the COMMAREA length is non zero.
27
The INPUTMSG length is less than 0 or greater than 32767.
also occurs (RESP2 not set) in any of the following situations:
  • The length specified on the LENGTH option is greater than the length of the data area specified in the COMMAREA option, and while that data was being copied a destructive overlap occurred because of the incorrect length.

Default action: terminate the task abnormally.

Note: RESP2 values are not returned to the client for conditions occurring in a DPL server program.
NOTAUTH
RESP2 values:
101
A resource security check has failed on PROGRAM(name).

Default action: terminate the task abnormally.

PGMIDERR
RESP2 values:
1
A program has no entry in the PPT and either program autoinstall was switched off, or the program autoinstall control program indicated that the program should not be autoinstalled.
2
A program is disabled.
3
A program could not be loaded because
  • This was the first load of the program and the program load failed, usually because the load module could not be found.
  • This was a subsequent load of the program, but the first load failed.

In order to reset the load status the load module must be in the DFHRPL concatenation, and a SET PROGRAM NEWCOPY will be required.

21
The program autoinstall control program failed either because the program autoinstall control program is incorrect, incorrectly defined, or as a result of an abend in the program autoinstall control program. Program autoinstall is disabled and message DFHPG0202 or DFHPG0203 written to the CSPL.
22
The model returned by the program autoinstall control program was not defined in the PPT table, or was not enabled.
23
The program autoinstall control program returned invalid data.
24
Define for the program failed due to autoinstall returning an invalid program name or definition.
25
The dynamic routing program rejected the link request.

Default action: terminate the task abnormally.

Note: RESP2 values are not returned to the client for conditions occurring in a DPL server program.
RESUNAVAIL
RESP2 values:
0
A resource required by the linked-to program is unavailable on the target region. The RESUNAVAIL condition applies to dynamically-routed distributed program link (DPL) requests.

RESUNAVAIL is returned on the EXEC CICS LINK command executed by the mirror in the target region, if an XPCERES global user exit program indicates that a required resource is unavailable on the target region. It is not returned to the application.

Default action: reinvoke the dynamic routing program for route selection failure.

ROLLEDBACK
RESP2 values:
29
The SYNCONRETURN is specified and the server program is unable successfully to take a syncpoint. The server program has taken a rollback, and all changes made to recoverable resources in the remote region, within the current unit of work, are backed out.

Default action: terminate the task abnormally.

SYSIDERR
RESP2 values:
18
The SYSID specified cannot be found in the intersystem table.
20
The remote system specified by SYSID is an LUTYPE6.1-connected system. Distributed program link requests are not supported on LUTYPE6.1 connections.
Note:
  1. There is no local queuing in the event of a SYSIDERR.
  2. RESP2 values are not returned for conditions occurring on DPL requests.
Start of change21End of change
Start of changeThe CHANNEL option was used and the LINK request was shipped or routed to a remote system which doesn't support it. (MRO connections only)End of change
28
The remote system specified by SYSID is not in service.This response can also indicate that the transaction has not been defined on the remote system.
29
The remote system specified by SYSID is in service, but there are no sessions available, and the dynamic routing program has chosen not to queue the link request.
31
The request to allocate a session to the remote system has been rejected.
32
The queue of allocate requests for sessions to the remote system has been purged.

Default action: terminate the task abnormally.

TERMERR
RESP2 values:
17
An irrecoverable error occurs during the conversation with the mirror (for example, if the session fails, or if the server region fails).

Default action: terminate the task abnormally.

Start of changeIf SYNCONRETURN was not specified on the LINK then the client program must decide whether to abend or rollback on receipt of this condition.End of change

Note: RESP2 values are not returned to the client for conditions occurring in a DPL server program.

Examples

The following example shows how to request a link to an application program called PROGNAME:
EXEC CICS LINK PROGRAM(PROGNAME)
               COMMAREA(COMA) LENGTH(LENA)
               DATALENGTH(LENI) SYSID('CONX')
1 By “installed program definition” we mean a program definition that has been installed statically, by means of autoinstall, or by an EXEC CICS CREATE command.
2 By “installed program definition” we mean a program definition that has been installed statically or dynamically by means of autoinstall, or by an EXEC CICS CREATE command.