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.
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.
Options
CHANNEL(name)
specifies
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
a-z
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

- 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.
The value of DATALENGTH is only checked 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 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
CHANNELERR
RESP2
values: - 1
- The name specified on the CHANNEL option contains an illegal character
or combination of characters.

- 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.
50
The Language Environment® options
specified in DFHJVMRO are too long.
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: - There is no local queuing in the event of a SYSIDERR.
- 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 doesn't support it. (MRO connections
only)
- 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.
If
SYNCONRETURN was not specified on the LINK then the client program
must decide whether to abend or rollback on receipt of this condition.
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')