XCTL

Transfer program control.

Start of change
Read syntax diagramSkip visual syntax diagram
XCTL

>>-XCTL--PROGRAM(name)------------------------------------------>

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

>--+--------------------------------------------------+--------><
   '-INPUTMSG(data-area)--+-------------------------+-'   
                          '-INPUTMSGLEN(data-value)-'     

Conditions: Start of changeCHANNELERR, End of changeINVREQ, LENGERR, NOTAUTH, PGMIDERR

This command is threadsafe.

End of change

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

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 channels 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 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
End of change
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

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
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.
Start of change50End of change
Start of changeThe Language Environment® options specified in DFHJVMRO are too long.End of change
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')