XCTL

The following example shows how to request a transfer of control to an application program called PROG2:

EXEC CICS XCTL PROGRAM('PROG2')

COMMAREA(data-area)

Specifies a communication area that is to be made available to the invoked program. In this option, a pointer to the data area is passed after first making a copy of the area if required. In a COBOL receiving program, you must give this data area the name DFHCOMMAREA. (See ../tasks/t_usng_commarea_optn.html#t_usng_commarea_optn.)

LENGTH(data-value)

Specifies, as a 16-bit binary value, the length, in bytes, of the communication area. If a negative value is supplied, zero is assumed. For more information about using this option, see LENGTH option.

INPUTMSG(data-area)

Specifies data that is 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®. For more information about the INPUTMSG option, see ../tasks/t_usng_inputmsg_optn.html#t_usng_inputmsg_optn.

INPUTMSGLEN(data-value)

Specifies a halfword binary value that specifies the length of the data that is passed by INPUTMSG.

PROGRAM(name)

Specifies the name of the program to which control is to be transferred unconditionally. The name can consist of up to eight alphanumeric characters, and must be defined in the Program Definitions (PD) as a local program.

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.

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.

NOTAUTH

Occurs if a resource security check has failed on PROGRAM(name).

Default action: Terminates the task abnormally.

PGMIDERR

Occurs for the following conditions:

• The program has no entry in the PD.
• The program is defined as remote.
• The program is disabled.
• The program could not be loaded because:
  • This was the first load of the program and the program load failed. This is usually because the load module could not be found.
  • This was a subsequent load of the program, but the first load failed.

  Default action: Terminates the task abnormally.

CHANNELERR

1: The name specified on the CHANNEL option contains an illegal character or combination of characters.