XCTL

XCTL either transfers control from a program at one logical level to a AMB or non-AMB application program at the same level, and passes the Commarea, or it operates identically to LINK.

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

CICS
DLG

CICS

Transfer control from a program at one logical level to a AMB or non-AMB application program at the same level, and pass the Commarea.

Syntax: for Format 1

Transferring to a AMB program

[TP-]XCTL programname [errorpara]
... [LENGTH(value)]
... [DLIUIB pcbname [pcbname ...]]
... [userparm [userparm] ...]

Syntax: for Format 1

Transferring to a non-AMB program

[TP-]XCTL programname(NONAPS) [errorpara]
... [LENGTH(value)]

General Rules:

When transferring control to a AMB program, XCTL transfers control to the program specified in the call and passes the TP-COMMAREA. Ensure that the Commarea in the transferred-to program is the same length as the TP-COMMAREA you pass.
When transferring to a non-AMB program, XCTL transfers control to the specified program and passes the TP-USERAREA. Ensure that the Commarea in the transferred-to program is the same length as the TP-USERAREA you pass. (TP-USERAREA gets its value from &TP-USER-LEN.) Additionally, code the following before your NTRY statement.
```
% &TP-PROGRAM-INVOCATION = "NONAPS"
```

Parameters:

DLIUIB `pcbname`	DLI interface block and the Program Control Block required by the next program.
`errorpara`	User-defined error routine to perform when an abnormal condition occurs. `Errorpara` is positional; if omitted, code an asterisk (*) in its place.
LENGTH (`value`)	Maximum length of data; can be a literal or COBOL data name defined as S9(04)COMP. Can also be a partial length.
(NONAPS)	The program is not a AMB program.
NOTERM	Do not terminate the screen display for the calling program, that is, display screens for both the called and the calling program.
`programname`	Program name; can be a literal, variable, or combination. If you precede a variable name with a slash (/), AMB moves the literal to it. There is no active PSB and no passing of arguments.

Examples:

Transfer control to PGM001. There is no active PSB and no passing of arguments.

XCTL PGM001

Transfer control to the program whose name is stored in WS-PROGNAME. There is no active PSB and no passing of arguments.

XCTL /WS-PROGNAME

Move the value PGM003 to WS-PROGNAME and transfer control to that program. There is no active PSB and no passing of arguments.

XCTL PGM003/WS-PROGNAME

Transfer control to PGM004; execute an error routine for an abnormal condition. There is no active PSB and no passing of arguments.

XCTL PGM004 ERR-PARA

Transfer control to PGM005. A PSB is scheduled and the transferred-to program uses PCB ABC-PCB.

XCTL PGM005 * DLIUIB ABC-PCB

Transfer control to a non-AMB program, PROG001.

XCTL PROG001(NONAPS)

DLG

XCTL, which calls a subprogram at the next lower level, operates identically to LINK. XCTL invokes LINK, providing no additional functionality and does not pass the COMMAREA; XCTL is provided for upward compatibility.