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:
  1. 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.
  2. 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.