LINK

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 definition is local, and the linked-to program is not already in main storage, CICS loads it.

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

This command operates in the current application context. If the command is issued by a program that is running under a task for an application deployed on a platform, CICS searches first for the named program in the private program directory for the application. If the named program is not found there, CICS then searches the public program directory.

When this command is used to link to a program that is declared as an application entry point for an application deployed on a platform, the CICS bundle where the application entry point is declared must have a status of AVAILABLE. The link is made to the highest numbered version of the application that is installed, enabled, and available. To link to a specified version of an application deployed on a platform, use the INVOKE APPLICATION command instead of the LINK command.

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

The external CICS interface (EXCI) provides a LINK command that performs all six commands of the interface in one invocation. See The EXCI CALL interface for information about EXCI.

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 Using the HANDLE CONDITION command 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 Using the HANDLE CONDITION command for further details about the relationship between LINK and HANDLE ABEND.

Distributed program link

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 runs the linked-to program (the server program) on behalf of the program that issues 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 DFH7230E indicating conflicting options.

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 main 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 that you cannot route a DFHEMTA or DFHEDAP request to a remote CICS.

Options

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. This new channel remains in scope until the link level changes. 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 used to name them to A-Z a-z 0-9 & : = , ; < > . - and _.

You can specify the channel name DFHTRANSACTION to use a transaction channel. 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 do one of the following:

• Have already created the channel by using one or more PUT CONTAINER CHANNEL or PUT64 CONTAINER commands.
• Specify its current channel, by name.
• Name a channel that does not currently exist. A new empty channel is created.

COMMAREA(data-area)

Specifies a communication area that is to be made available to the called program. In this option the data area is passed, and you must give it the name DFHCOMMAREA in the receiving program. COMMAREA is not supported for LINK to Liberty. See Passing data to other 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 called 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, specify DATALENGTH in the interest of performance.

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

DATALENGTH cannot be used at the same time as INPUTMSG.

INPUTMSG(data-area)

Specifies data to be supplied to the called program when it first issues a RECEIVE command. This data remains available until the execution of a RECEIVE or RETURN command. A called program can call 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 run 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. In this situation, the original INPUTMSG data is no longer available.

INPUTMSG cannot be used at the same time as DATALENGTH. INPUTMSG is not supported for LINK to Liberty.

For more information about the INPUTMSG option, see INPUTMSG.

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 must not exceed 24 KB if the COMMAREA is to be passed between any two CICS servers (for any combination of product, version, and release). This limit allows for the COMMAREA and space for headers.

Ensure that the value you specify matches the length of the data being passed in the COMMAREA. Do not specify 0 (zero) for LENGTH, because the resulting behavior is unpredictable and the EXEC CICS LINK command might fail.

When you use a COMMAREA to pass data, the program that is linked to must verify that the EIBCALEN field in the EIB of the task matches what the program expects. Discrepancies might result in storage violations or system failures. For more information, see COMMAREA.

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 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. It a data area is used to contain the program name, this data area must be defined as an 8 byte field in working storage.

Note: When a link is made to a CICS 3270 program that is to run 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 sync point 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 running. The client program handles the condition and ensures 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.

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

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.

Specifying the TRANSID option with a blank transaction name is not valid. The error response in this case depends on how the link request is handled:

• If the linked-to program is defined locally, the link request succeeds in this situation.
• If the request is statically routed to a remote region, an INVREQ response is returned to the program initiating the link.
• If the request is dynamically routed to a remote region, a valid connection ID is returned, but after checking the TRANSID, CICS calls the dynamic routing program again with the parameter DYRFUNC set to 1 and the parameter DYRERROR set to 8. If the dynamic routing program responds by running the program locally, the link request succeeds. If the dynamic routing program responds by retrying without success, the link request is rejected, and a PGMIDERR response is returned to the program initiating the link.

Conditions

122 CHANNELERR

RESP2 values:

1

The name specified on the CHANNEL option contains an illegal character or combination of characters.

16 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 is specified in the client region, or the MIRRORLIFE IPCONN setting is specified as task or UOW in the remote 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, probably because a link request was made in a first stage PLT.

48

A LINK has been attempted to a Java™ program, but the user class cannot be found.

51

A LINK has been attempted to a Java program, but the JVMSERVER resource cannot be found.

52

A LINK has been attempted to a Java program, but the JVMSERVER resource is not enabled.

53

A LINK has been attempted to an application in a Liberty JVM server, but the LINK listener process was not available. The most likely cause of this error is that the feature cicsts:link-1.0 is not enabled. To resolve this, add this feature to the server.xml.

54

The COMMAREA option is specified, but it is invalid when linking to an application in a Liberty JVM server.

55

The INPUTMSG option is specified, but it is invalid when linking to an application in a Liberty JVM server.

Default action: end the task abnormally.

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

22 LENGERR

RESP2 values:

11

The COMMAREA length is less than 0 or greater than the permitted length.

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 nonzero.

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: end the task abnormally.

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

70 NOTAUTH

RESP2 values:

101

A resource security check has failed on PROGRAM(name).

Default action: end the task abnormally.

27 PGMIDERR

RESP2 values:

1

A program has no installed resource definition and either program autoinstall was switched off or the program autoinstall control program indicated that the program should not be autoinstalled.

This RESP2 can also occur if the program is a private program for an application, which is not defined as entry point, and the tasks current application context does not permit it to be called.

2

A program is disabled.

3

A program was not loaded because

• This load of the program was the first one and the program load failed, typically because the load module was not found.
• This load of the program was a subsequent load, but the first load failed.

To reset the load status, the load module must be in the DFHRPL concatenation, and a SET PROGRAM NEWCOPY is 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 is written to the CSPL.

22

The model returned by the program autoinstall control program was not defined to CICS or was not enabled.

23

The program autoinstall control program returned invalid data.

24

Define for the program failed because autoinstall returned an invalid program name or definition.

25

The dynamic routing program rejected the link request.

26

A LINK has been attempted to an application in a Liberty JVM server, but the request has failed and the target application was not invoked. Message DFHSJ1207 gives more details about why the application could not be invoked.

27

A LINK has been attempted to an application in a Liberty JVM server, but the request timed out and the target application was not invoked. For more information, see Troubleshooting Liberty JVM servers and Java web applications.

Default action: end the task abnormally.

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

121 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: call again the dynamic routing program for route selection failure.

82 ROLLEDBACK

RESP2 values:

29

The SYNCONRETURN option is specified and the server program cannot successfully take a sync point. The server program has taken a rollback, and all changes made to recoverable resources in the remote region, in the current unit of work, are backed out.

Default action: end the task abnormally.

53 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. No local queuing takes place in the event of a SYSIDERR.
2. RESP2 values are not returned for conditions occurring on DPL requests.

21

The CHANNEL option was used and the LINK request was shipped or routed to a remote system which does not support it. (IPIC and MRO connections.)

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 failed because the session allocation queue is full or has been purged.

Default action: end the task abnormally.

81 TERMERR

RESP2 values:

17

An unrecoverable error occurs during the conversation with the mirror; for example, if the session fails, or if the server region fails.

Default action: end the task abnormally.

If the SYNCONRETURN option was not specified on the LINK, the client program must decide whether to abend or roll back on receipt of this condition.

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