Link to another program expecting return.
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: CHANNELERR, INVREQ, 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,
or in a remote CICS region
over an IPIC connection. It is non-threadsafe when it is used to link
to a program in a remote CICS region over another type of connection.
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.
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
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 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 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.
A server
program running in the server region is restricted to a DPL subset
of the CICS API. In summary,
the server program cannot issue these commands:
- Terminal control commands that reference the principal facility
- Options of ASSIGN that return terminal attributes
- BMS commands
- Sign-on and sign-off commands
- Batch data interchange commands
- Commands that address the TCTUA
For details of the restricted DPL subset of the API, see
Exception conditions for LINK command.
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 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.
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 _.
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. 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.
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.
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.
- 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.
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: - No local queuing takes place 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 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.
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')