Transfer program control.
Description
XCTL transfers control from one application
program to another at the same logical level. The program from which control
is transferred is released. If the program to which control is transferred
is not already in main storage, it is loaded.
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 channels 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 XCTL 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 to be made available to the invoked program. In this
option the contents of the data-area are passed. In COBOL, you must give this
data area the name DFHCOMMAREA in the receiving program. (See the section
about passing data to other programs in the CICS® Application
Programming Guide.)
- INPUTMSG(data-area)
- specifies
data to be passed to the invoked program when it first issues a RECEIVE command.
If the invoked program passes control to another program by a LINK command,
a linked chain is created, as described under the INPUTMSG option of the LINK
command. The INPUTMSG data remains available until a RECEIVE command is issued
or until control returns to CICS.
- INPUTMSGLEN(data-value)
- specifies
a halfword binary value that specifies the length of the data passed by INPUTMSG.
- LENGTH(data-value)
- specifies
the length (halfword binary data value) in bytes of the communication area.
For a description of a safe upper limit, see LENGTH options in CICS commands.
- PROGRAM(name)
- specifies
the identifier (1–8 alphanumeric characters) of the program to which control
is to be passed unconditionally. The specified name must have been defined
as a program to CICS, though if AUTOINSTALL is active a definition is autoinstalled.
Conditions
CHANNELERR
RESP2
values: - 1
- The name specified on the CHANNEL option contains an illegal character
or combination of characters.

- INVREQ
- RESP2
values:
- 8
- An XCTL 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.
- 29
- EXEC XCTL is not allowed in a GLUE or TRUE.
- 30
- The program manager domain has not yet been initialized. This is probably
due to a XCTL request having been made in a first stage PLT.
50
The Language Environment® options specified in DFHJVMRO are too long.
- 200
- An XCTL command with the INPUTMSG option is issued in a program invoked
by DPL.
Default action: terminate the task abnormally.
- LENGERR
- RESP2
values:
- 11
- LENGTH is less than 0 or greater than 32763.
- 26
- The COMMAREA address passed was zero, but LENGTH was non-zero.
- 27
- INPUTMSGLEN was less than 0 or greater than 32767.
- 28
- LENGTH or INPUTMSGLEN is greater than the length of the data area specified
in the COMMAREA or INPUTMSG options, and while that data was being copied
a destructive overlap occurred because of the incorrect length.
Default action: terminate the task abnormally.
- 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
- The 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
- 9
- The installed program definition is for a remote program.
- 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.
Default action: terminate the task abnormally.
Examples
The following example shows how to request
a transfer of control to an application program called PROG2:
EXEC CICS XCTL PROGRAM('PROG2')