XCTL

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.

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 for the named program in the private program directory for the application. This command cannot be used to change application context.

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. 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 task. For more information, see Channels and containers.

The program that issues the XCTL command can do one of the following:

• Create the channel before issuing the XCTL command, 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 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 Passing data to other programs.

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 using 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 suitable 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.

Note the use of quotes:

EXEC CICS XCTL PROGRAM('PROGX')

PROGX is in quotes because it is the program name.

EXEC CICS XCTL 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.

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

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 because an XCTL request was made in a first stage PLT.

31

An XCTL command is issued from a program that is running with an application context, to another program that is an application entry point.

32

An XCTL command is issued from a program that would invoke a Java EE application in a Liberty JVM server. This operation is not supported.

33

An XCTL command is issued from a public program to another program that is an application entry point.

34

An XCTL command is issued from a program that is running with an application context, to a public program.

200

An XCTL command with the INPUTMSG option is issued in a program invoked by DPL.

Default action: terminate the task abnormally.

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

70 NOTAUTH

RESP2 values:

101

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

Default action: terminate 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

The program is disabled.

3

A program could not be loaded for one of the following reasons:

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

To reset the load status, the load module must be in the DFHRPL or dynamic LIBRARY 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 or 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 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.

Default action: terminate the task abnormally.