Data Manipulation Language Statements › #XCTL

#XCTL

The #XCTL statement transfers control and sends an optional parameter list to a specified program. Control does not return to the issuing program when the specified program ends.

Syntax

►►─┬─────────┬─ #XCTL PGM=program-name-pointer ───────────────────────────────►
   └─ label ─┘

 ►─┬────────────────────────────────────────┬─────────────────────────────────►
   └─ ,PLIST= ─┬─ SYSPLIST ◄ ─────────────┬─┘
               └─ parameter-list-pointer ─┘

 ►─┬────────────────────────────────────┬─────────────────────────────────────►◄
   └─ ,PARMS= ─┬─ NO ◄ ────────────────┬┘
               └─ (parameter-pointer) ─┘

Parameters

PGM=

Specifies the 1- to 8-character name of the program to which control is transferred.

program-name

A register that points to a field that contains the program name, the symbolic name of a user-defined field that contains the program name, or the program-name literal enclosed in quotation marks.

PLIST=

Specifies the location of the storage area that contains one or more parameters to be passed to the program receiving control.

SYSPLIST

(Default); is the symbolic name of the storage area in which the system builds the parameter list.

parameter-list-pointer

Either a register that points to the area in which the system builds the list or the symbolic name of the area.

The size of the parameter-list area is equal to two fullwords plus one fullword for each parameter listed. Thus, if no parameters are specified (PARMS=NO), the length of the storage area is two fullwords; if one parameter is specified, the length is three fullwords.

PARMS=

Specifies whether parameters will be passed to the program receiving control.

NO

(Default); specifies that no parameters will be passed to the program.

parameter-pointer

Specifies that parameters will be passed to the program. Parameter-register is either a register that contains the address of the parameter or the symbolic name of a user-defined field that contains the parameter.

Example

The #XCTL statement shown below transfers control to the Cloud Airlines flight booking program and passes parameters that specify the flight, the city of departure, and the flight destination.

#XCTL PGM='CLBOOK',PARMS=(FLT,DEPART,DEST)

Status Codes

By default, the #XCTL request is unconditional. Error conditions that can occur are described below:

• A no-space-available-in-program-pool condition is caused when there is not enough storage in the program pool to accommodate the program. The system delays processing until sufficient storage becomes available. If such a wait would cause a deadlock, the system aborts the program.
• A nonconcurrent-program-in-use condition is caused when a copy of the program is already in use and is marked as nonconcurrent (indicating that this program can be used by one task at a time). The system delays processing until the program becomes available.
• A storage-conflict condition is caused when a copy of the previously loaded program is temporarily overlayed while being used by a waiting task. The system delays processing until the program is replaced in the program pool.
• Any abnormal condition causes the system to terminate the program abnormally. Conditions in this category include:
  • An I/O error
  • A program not found in the PDT (program definition table) or marked out-of-service
  • A wait-on-storage (default action resulting from the no-space-available-in-program-pool condition) would result in a deadlock