T-Z

TERM

Category:

Data communication call (see Data Communication Calls)

Description:

Terminate programs and transaction operations.

Under ISPF Dialog, perform internal program cleanup, terminate the program via GOBACK statement, and return control to the calling program.

Syntax:

[TP-]TERM

Comments:

CICS

APS generates a CICS RETURN without a TRANSID or COMMAREA. Program control returns to either the next higher-level linked program or to CICS.
Code TERM in a linked-to program that returns to the calling program and ensures that TP-COMMAREA data is passed back. When returning to a calling program, TP-COMMAREA moves to DFHCOMMAREA.
Call does not terminate an active PSB that is passed via LINK.

IMS DC

Use TERM after sending output messages (SEND or MSG-SW) with CONTINUE. Do not use TERM prior to sending at least one response; this causes a user terminal in response mode to remain locked, awaiting a response.

Example:

Terminate a program when SCRA-FUNCTION = 'E' or PF3 is pressed.

IF  SCRA-FUNCTION = 'E' OR PF3
    TERM

TERMINATE

Category:

Report Writer statement (see Report Writer Structures and the Report Writer chapter in your APS User's Guide)

Compatibility:

Batch environments

Description:

End report processing. TERMINATE:

Adds all SUM operands and saves their values
Saves current values of all CONTROL items
Produces all CONTROL FOOTING report groups beginning with the minor CONTROL FOOTING and ending with FINAL
Produces PAGE FOOTING and PAGE HEADING report groups if a page break occurred
Produces REPORT FOOTING report group
Resets all CONTROL items to their values when TERMINATE was executed

Syntax:

TERMINATE reportname1 [,reportname2] ...

Parameter:

reportname

Identify the report. Define reportname in a RED statement in the Report Section of the Data Division.

Comments:

If GENERATE processing was not executed for a report between its INITIATE and TERMINATE, TERMINATE does not produce any report groups or perform any related processing. If INITIATE processing does not execute, TERMINATE does not execute.
TERMINATE does not close the report file; to do so, code a COBOL CLOSE statement. TERMINATE every INITIATEd report before a CLOSE.

TP-BACKOUT

Category:

Data communication call (see Data Communication Calls)

Compatibility:

CICS and IMS DC targets

Pupose

ABEND the program.

Syntax:

CICS

TP-BACKOUT [ABORT[(name)]|NOABORT]

IMS DC

TP-BACKOUT [ABORT|NOABORT]

Parameters:

CICS

ABORT(name)

Invoke CICS ABEND to terminate task. Name specifies a formatted dump of main storage; can be literal or COBOL data name (maximum 4 characters).

NOABORT

Nonfunctional--allowed for compatibility with IMS.

IMS DC

ABORT	Cancel program and do not reschedule.
NOABORT	Default. Return next input message for processing.

Comments:

IMS DC

Use ABORT if the detected error prevents other messages from processing successfully.
Use NOABORT if the detected error is specific to the processing message.
This call invokes the IMS dynamic backout feature, canceling all database updates and messages sent since running the program or since receipt of the most recent input message.
To send a message and use TP-BACKOUT, use the EXPRESS keyword with either SEND or MSG-SW.
Coding NOABORT calls an IMS ROLB with the current input message discarded; ABORT calls an IMS ROLL.
The IMS option of issuing a ROLB with an IOAREA to reread the current input message is not supported by TP-BACKOUT. For further information on ROLL and ROLB, see the appropriate IMS manuals.

Examples:

The following three examples execute identically. Each terminates a task abnormally by invoking a CICS ABEND code.

TP-BACKOUT
TP-BACKOUT ABORT
TP-BACKOUT NOABORT

Specify a recovery option and code name to identify a main storage dump related to the task.

TP-BACKOUT ABORT('PGM1')

TP-COMMAREA

CICS

Description:

TP-COMMAREA generates a Working-Storage record for passing data between programs. This record contains APS information as well as user data.

There is no need to code a TP-COMMAREA call; APS generates it. The value of &TP-USER-LEN--the default is 80--determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the APS default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields.

The following calls pass a Commarea.

SEND	Send a screen to the terminal and terminate the program. CICS saves the data stored in the TP-COMMAREA and makes it available to the next program when APS returns the screen to CICS.
LINK	Link to a subprogram, passing it the TP-COMMAREA address. Define COMMAREA identically in each program.
XCTL	Transfer control to another program, passing a copy of TP-COMMAREA. Define TP-COMMAREA identically in both programs.

You can redefine TP-USERAREA to fit program requirements.

Code the redefinition in the Data Structure Painter. You must also specify the Commarea redefinition in Application View--code its name in the Data Str field and specify its type as CA (Commarea).
Code the redefinition in the Program Painter. Two keywords are available to redefine TP-USERAREA--CA, where you code the redefinition in Data Structure Painter syntax, CA05 and CA, where you code it in COBOL syntax.

Optionally, you can code the redefinition in a copybook or rule that you include.

Example:

Redefine TP-USERAREA in the Program Painter.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYM1   % * SET THE LENGTH OF TP-USERAREA TO
        % * 21 BYTES
        % &TP-USER-LEN = 21
 CA     AACA-USERAREA
            CA-DATE                X8
            CA-TIME                X8
            CA-CUST-NUMBER         X5
-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYM1   % * SET THE LENGTH OF TP-USERAREA TO
        % * 21 BYTES
        % &TP-USER-LEN = 21
 CA05   AACA-USERAREA
        10  CA-DATE                X8
        10  CA-TIME                X8
        10  CA-CUST-NUMBER         X5

Redefine TP-USERAREA in the Data Structure Painter.

AACA-USERAREA
    CA-DATE                X8
    CA-TIME                X8
    CA-CUST-NUMBER         X5

Each of the above generates:

01  TP-COMMAREA
          .
          .
          .
01  FILLER REDEFINES TP-COMMAREA.
    05  FILLER                PIC X(40).
    05  TP-USERAREA           PIC X(21).
    05  AACA-USERAREA   REDEFINES TP-USERAREA.
        10  CA-DATE           PIC X(08).
        10  CA-TIME           PIC X(08).
        10  CA-CUST-NUMBER    PIC X(05).

IMS DC

Description:

TP-COMMAREA coordinates the placement of the APS-generated Commarea structure with a user-provided redefinition of that structure. Use it only with conversational IMS programs--nonconversational IMS programs do not use a Commarea.

In IMS, the Commarea is called a SPA (Scratch Pad Area). Its reserved prefix includes an IMS LLZZ field, the input trancode, and the APS invocation mode flag.

There is no need to code a TP-COMMAREA call; APS generates it. The value of &TP-USER-LEN--the default is 0--determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the APS default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields. You must define the Commarea in Working-Storage.

To redefine TP-USERAREA as a group-level data structure, the length must be the same as the value specified for &TP-USER-LEN. A CA01 keyword generates an 05-level REDEFINES TP-USERAREA statement.

To generate a single-field Commarea in Working-Storage called TP-USERAREA, assign a value to the APS variable &TP-USER-LEN. Code the following on one line.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
  SYM1   % &TP-USER-LEN = number

SYM1 indicates &TP-USER-LEN is a Customizer variable and places the variable at the top of the program.
&TP-USER-LEN = number specifies the size of TP-USERAREA; it should be large enough to store all fields of data on the screen that the program receives. Caution: An undefined &TP-USER-LEN defaults to zero; when prototyping, the default is 2048.

Example:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYM1   % &TP-USER-LEN = 100 
 CA05   MY-REDEF
        10 CA-FLD-A            PIC X(10).
        10 CA-FLD-B            PIC S9(4) COMP.
        10 CA-FLD-C            PIC X(20).

Generated source:

% &TP-USER-LEN = 100
IDENTIFICATION DIVISION
          .
          .
WORKING-STORAGE SECTION.
$TP-WS-MARKER
$TP-COMMAREA
    05  MY-REDEF REDEFINES TP-USERAREA.
        10 CA-FLD-A            PIC X(10).
        10 CA-FLD-B            PIC S9(4) COMP.
        10 CA-FLD-C            PIC X(20).

ISPF Dialog

Description

TP-COMMAREA generates a Working-Storage record for passing data between programs. This record contains APS information and user data.

There is no need to code a TP-COMMAREA call; APS generates it. The value of &TP-USER-LEN - the default is zero - determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the APS default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields. You must define the Commarea in Working-Storage.

To redefine TP-USERAREA as a group-level data structure, the length must be the same as the value specified for &TP-USER-LEN. A CA01 keyword generates an 05-level REDEFINES TP-USERAREA statement.

To generate a single-field Commarea in Working-Storage called TP-USERAREA, assign a value to the APS variable &TP-USER-LEN. Code the following on one line.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYM1    % &TP-USER-LEN = number

SYM1 indicates &TP-USER-LEN is a Customizer variable and places the variable at the top of the program.
&TP-USER-LEN = number specifies the size of TP-USERAREA; it should be large enough to store all fields of data on the screen that the program receives. The default for number is zero.
To receive TP-COMMAREA as a passed data area from a calling program, code this assignment statement before NTRY.
```
-KYWD-  12-*----20---*----30---*----40---*----50---*----60
        % &DLG-COMMAREA-IN-LINKAGE = "YES" 
```
The results are:
- APS generates the following in the Linkage Section.
```
01  DLG-LINKAGE-COMMAREA  PIC X(&TP-USER-LEN).
```
- APS generates the Procedure Division statement with
```
... USING DLG-LINKAGE-COMMAREA
```
Generated logic maps the data between TP-COMMAREA and DLG-LINKAGE-COMMAREA at the following points.
- Upon program invocation, from DLG-LINKAGE-COMMAREA to TP-COMMAREA
- Before execution of LINK or XCTL, from TP-COMMAREA to DLG-LINKAGE-COMMAREA
- After execution of LINK or XCTL, from DLG-LINKAGE-COMMAREA to TP-COMMAREA
- Before program termination, from TP-COMMAREA to DLG-LINKAGE-COMMAREA

Example:

Redefine TP-USERAREA.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYM1   % &TP-USER-LEN = 49 
CA05   PGM-USERAREA
            10  CA-EMPLOYEE-NAME    PIC X(20).
            10  CA-EMPLOYEE-TITLE   PIC X(20).
            10  CA-EMPLOYEE-SSN     PIC X(09).

Generated source:

01 TP-COMMAREA.
   05  TP-USERAREA              PIC (X49).
   05  PGM-USERAREA REDEFINES TP-USERAREA.
       10  CA-EMPLOYEE-NAME     PIC X(20).
       10  CA-EMPLOYEE-TITLE    PIC X(20).
       10  CA-EMPLOYEE-SSN      PIC X(09).

TP-LINKAGE

Category:

Data communication call (see Data Communication Calls)

Compatibility:

CICS, IMS DC, and ISPF Dialog

Description:

Handle addressability of Linkage Section data records in a called program.

Syntax:

TP-LINKAGE linkdataname[/copybookname|macrofilename]
... [linkdataname[/copybookname|macrofilename] ...]

Parameters:

/copybookname	Name of copybook that you INCLUDE or COPY prior to this call. See also "Comments" below.
linkdataname	01-level Linkage Section data area identical to the linkdataname in the associated call.
/macrofilename	Name of macro file that you INCLUDE or COPY prior to this call. See also "Comments" below.

Comments:

List data items in the order that they appear in the Linkage Section, copybook, or macro file.
Make sure that each linkdataname you specify is defined in the Linkage Section. Choose one of the following methods.
- Define them yourself.
- Include (using TP-LINKAGE) a copybook or macro file that contains the linkdatanames.
To generate a COBOL COPY statement, instead of a % INCLUDE statment, code &TP-COPY-LINKAGE = 1 prior to the TP-LINKAGE call.
In Online Express, list the records in the order they pass from the calling program.

CICS

Use TP-LINKAGE with calls that use the SET option.
Coding TP-LINKAGE with the SYLT keyword ensures that the APS-generated DFHCOMMAREA is the first record in the Linkage Section. This prevents the CICS translator from generating an additional one.
One BLL cell is generated per 4,096 bytes. Linkage records longer than 4,096 bytes require additional BLL cells to establish addressability to the entire record.
To generate additional BLL cells, code dummy records after the record that is greater than 4,096 bytes. A dummy record name must be prefixed with DUMMY and its copybook name must be DUMMY.
BLL cells are not used with COBOL/2.

IMS DC

Code the call on the first line of the Linkage Section, and inconjunction with NTRY or PROC to generate parameters for the PROCEDURE DIVISION USING statement.
Do not define PCBs with TP-LINKAGE; the subschema defines them.

ISPF Dialog

APS provides this call for compatibility with APS/CICS and APS/IMS--it is not required to handle addressability of Linkage Section records.
Make the linkdataname a PARM area and the only area defined in the Linkage Section, if the PROGRAM CONTROL TRANSFER option is SELECT.

Examples:

Define records LINK-REC-1 and LINK-REC-2. Include definitions from USERMACS macro members LINKR1 and LINKR2.

TP-LINKAGE LINK-REC-1/LINKR1 LINK-REC-2/LINKR2

Define records LINK-REC-1 and LINK-REC-2 and copy their definitions from COPYLIB members LINKR1 and LINKR2.

% &TP-COPY-LINKAGE = 1
TP-LINKAGE LINK-REC-1/LINKR1 LINK-REC-2/LINKR2

Define records LINK-REC-1 and LINK-REC-2, coded in the Linkage Section.

TP-LINKAGE LINK-REC-1 LINK-REC-2

Define records LINK-REC-1 and LINK-REC-2. LINK-REC-1 has been coded in the Linkage Section; LINK-REC-2 is copied from COPYLIB member LINKR2.

% &TP-COPY-LINKAGE = 1
TP-LINKAGE LINK-REC-1 LINK-REC-2/LINKR2
LINK-REC-1       PIC X(100).

CICS

Linkage record containing 10,000 bytes.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYLK   TP-LINKAGE LINK-REC
        ... DUMMY-LINK-REC-BLL1/DUMMY
        ... DUMMY-LINK-REC-BLL2/DUMMY
 LK01   LINK-REC.
        05  LINK-REC-1-4096       PIC X(4096).
        05  LINK-REC-2-8192       PIC X(4096).
        05  LINK-REC-3-10000      PIC X(1808).
 OPT    PROG
 NTRY
        CIC-GETMAIN
        ... SET(LINK-REC)
        ... LENGTH(10000)
        /* PROGRAM HAS ADDRESSABILITY TO
        /* THE FIRST 4,096 BYTES.
        ADD 4096 LINK-REC--P
        ... GIVING DUMMY-LINK-REC-BLL1--P
        ... GIVING DUMMY-LINK-REC-BLL2--P
        /* PROGRAM HAS ADDRESSABILITY TO 
        /* ALL 10,000 BYTES.

ISPF Dialog

Define a PARM area for use by TP-LINK and TP-ENTRY. The PROGRAM CONTROL TRANSFER option has been set to SELECT. PGM-PARM-DATA is coded inline. Note: You can place the PGM-PARM-DATA area in Linkage without the use of TP-LINKAGE.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYLK   TP-LINKAGE PGM-PARM-DATA
 LK01   PGM-PARM-DATA.
            05  PGM-PARM-DATA-LEN   PIC S9(04) COMP.
            05  PGM-PARM-EMPNBR     PIC X(05).
            05  FILLER              PIC X(95).

TP-NULL

Category:

Data communication call (see Data Communication Calls)

Compatibility:

CICS, IMS DC, and ISPF Dialog targets

Description:

Move LOW-VALUES to all fields in a specified screen record.

Syntax:

TP-|SC-NULL screenname

Parameter:

screenname

Screen name; value must be literal.

Comment:

This call does not alter the field attributes.

Example:

Move LOW-VALUES to all fields on screen SCRA.

TP-NULL SCRA

TP-PERFORM

Category:

Data communication call (see Data Communication Calls)

Description:

Perform a paragraph, with or without passing arguments.

Syntax:

Format 1, perform a paragraph:

TP-PERFORM paragraphname

Format 2, perform a paragraph and pass arguments:

TP-PERFORM paragraphname actualargument1[[,]
... actualargument2[,] ... actualargument8]
          .
          .
          .
paragraphname ([+|-]formalargument1[[,]
... [+|-]formalargument2[,] ... [+|-]formalargument8])

Parameters:

+\|-	A plus (+) or minus (-) sign preceding a formalargument passes values between actual arguments and formal arguments, as follows: With a plus sign (+), PERFORM passes the actualargument value to formalargument after the paragraph executes. The program does not return the formalargument value to actualargument. With a minus sign (-), PERFORM passes the formalargument value to the actualargument after the paragraph executes. If there is no prefix, the PERFORM passes the actualargument to its corresponding formalargument. After the paragraph executes, PERFORM passes the formalargument back to its corresponding actualargument.
actualargument	Values you send or receive from a formalargument in the paragraph; can be literals, identifiers, arithmetic expressions, or index names.
formalargument	Values you receive from or send to an actualargument in the PERFORM statement.
paragraphname	Name of paragraph to perform.

Comments:

When continuing a list of arguments onto one or more other lines, do not break an argument.
The number of actual arguments must equal the number of formal argument names and be in the same order.

TRUE/FALSE

Category:

S-COBOL structure (see S-COBOL Structures)

Description:

Establish flags, set them to true and false, and then test them.

Syntax:

TRUE|FALSE dataname1 [dataname2 [... datanameN]]

Comments:

For each dataname coded, S-COBOL provides an 02-level conditional variable and an associated 88-level condition name entry in an 01 GENERATED-FLAGS area of Working-Storage. APS adds a --FLG suffix to dataname to create the 02-level entry, and dataname itself becomes the 88-level entry. APS always assigns VALUE 'T' to the 88-level condition name, never VALUE 'F'. For example:
The following code in the Procedure Division:
```
       .
       .
       .
TRUE THERE-ARE-NO-ERRORS
FALSE WITHIN-RANGE
       .
       .
       .
```
Generates:
```
WORKING-STORAGE SECTION.
       .
       .
       .
02  THERE-ARE-NO-ERRORS--FLG    PIC X.
 88  THERE-ARE-NO-ERRORS    VALUE 'T'.
02  WITHIN-RANGE--FLG    PIC X.
    88  WITHIN-RANGE    VALUE 'T'.
```

If, for debugging purposes, you want to display a generated flag, add the --FLG suffix to dataname in the DISPLAY statement. For example:

TRUE THERE-ARE-NO-ERRORS generates 
MOVE TRUE TO THERE-ARE-NO-ERRORS--FLG.

If only true statements, such as TRUE WITHIN-RANGE, or only false statements, such as FALSE WITHIN-RANGE, are coded for dataname, a warning message indicates a logic error.
S-COBOL minimizes the code required to test the flags established and set by the TRUE/FALSE verbs.
- Code WHILE THERE-ARE-NO-RECORDS instead of WHILE THERE-ARE-NO-RECORDS--FLG = TRUE.
- Code IF NOT WITHIN-RANGE instead of IF WITHIN-RANGE--FLG = FALSE.

Example:

Set two undefined flags, THERE-ARE-NO-ERRORS and WITHIN-RANGE to TRUE (line 3030). Define these flags in Working-Storage (88-level condition name flags), because this is the first TRUE or FALSE statement for either flag in this program. If the condition in line 3060 is true, set the THERE-ARE-NO-ERRORS flag to FALSE. If either condition in line 3110 is true, set the WITHIN-RANGE flag to FALSE. As long as the value of the THERE-ARE-NO-ERRORS flag is TRUE, perform the loop. Inside the loop test the other flag, WITHIN-RANGE. If the value is TRUE, execute the subordinate statement block.

-LINE- -KYWD-  12-*----20---*----30---*----40---*----50---*
   .
003030         TRUE THERE-ARE-NO-ERRORS 
003031         ... WITHIN-RANGE
   .
003060         IF CODE-IN NOT NUMERIC
003070             FALSE THERE-ARE-NO-ERRORS
   .
003110         IF COUNT > 372 OR COUNT < 50
003120             FALSE WITHIN-RANGE
   .
003150         WHILE THERE-ARE-NO-ERRORS
003160             IF WITHIN-RANGE

TRUE, FALSE, ALWAYS, NEVER

Category:

S-COBOL flag (see S-COBOL Structures)

Description:

TRUE, FALSE, ALWAYS, NEVER are data names whose meanings are reserved and automatically provided by S-COBOL.

Syntax:

Automatically generated in Working-Storage

01  GENERATED-FLAGS.
    02  TRUX        PIC X  VALUE 'T'.
        88  ALWAYS         VALUE 'T'.
        88  NEVER          VALUE 'F'.
    02 FALSX        PIC X  VALUE 'F'.

Comment:

Because TRUE and FALSE are reserved words on some systems, S-COBOL changes every occurrence of TRUE and FALSE to TRUX and FALSX, and generates the flags accordingly.

TYPE

Category:

Report Writer statement (see Report Writer Structures and the APS User's Guide chapter Create Reports with Report Writer)

Compatibility:

Batch environments

Description:

Identify a report group, such as a header line, detail line, or footer line.

Syntax:

Format 1, page header:

TYPE [IS] PAGE HEADING|PH

    [LINE [NUMBER IS] number     ]  [.]
                      PLUS number

Format 2, page footer:

TYPE [IS] PAGE FOOTING|PF
    [LINE [NUMBER IS] number]

    [NEXT GROUP [IS] number     ]  [.]
                     PLUS number

Format 3, report header:

TYPE [IS] REPORT HEADING|RH

    [LINE [NUMBER IS] number     ]
                      PLUS number

                     number
    [NEXT GROUP [IS] PLUS number]  [.]
                     NEXT PAGE

Format 4, report footer:

TYPE [IS] REPORT FOOTING|RF

                      number
    [LINE [NUMBER IS] PLUS number]  [.]
                      NEXT PAGE

Format 5, control headers and footers:

TYPE [IS] CONTROL HEADING|CH [FINAL] controldataname
          CONTROL FOOTING|CF
                      number
 
    [LINE [NUMBER IS] PLUS number]
                      NEXT PAGE
                     number

    [NEXT GROUP [IS] PLUS number]  [.]
                     NEXT PAGE

Format 6, detail lines:

detaildataname TYPE [IS] DE[TAIL]

                      number
    [LINE [NUMBER IS] PLUS number]
                      NEXT PAGE

                     number
    [NEXT GROUP [IS] PLUS number]  [.]
                     NEXT PAGE

Keywords/Parameters:

CONTROL FOOTING\| CF	Print group totals immediately following the detail lines each time a control group ends, that is, when a control break occurs.
CONTROL HEADING\| CH	Print heading line(s) before each detail group, that is, when a control break occurs.
controldataname	Designate control data name. Unless FINAL, code controldataname in the corresponding RED keyword CONTROL clause.
DETAIL\|DE	Specify the body group, that is, lines containing data items of a report. See also "Comments" below.
detaildataname	Name of detail line.
FINAL	Specify the highest, most inclusive, control group. Implicit; does not have to be coded in order to be used in a CONTROL FOOTING.
LINE number	Designate the line number where the current header, footer, or detail line prints. Number (maximum 3 digits) must be within the defined page limits. Specify the RED keyword PAGE LIMIT clause.
LINE NEXT PAGE	Print the current header, footer, or detail line on a new page.
LINE PLUS number	Designate the line where the current header, footer, or detail line prints, and optionally insert blank lines. Number (maximum 3 digits) must be within the defined page limits. PLUS increments the line number by number, causing blank lines. A simpler way to print blank lines, however, is to include them in your mock-up.
NEXT GROUP number	Designate the line number where the next TYPE entity prints (for example, a detail line, header, or footer). Number (maximum 3 digits) must be within the defined page limits. Specify the RED keyword PAGE LIMIT clause. See also "Comments" below.
NEXT GROUP PLUS number	Designate the line where the next TYPE entity prints, and optionally insert blank lines (for example, a detail line, header, or footer). Number (maximum three digits) must be within the defined page limits. PLUS increments the line number number, causing blank lines. A simpler way to print blank lines, however, is to include them in your mock-up. See also "Comments" below.
NEXT GROUP NEXT PAGE	Print the next TYPE entity on a new page (for example, a detail line, header, or footer). Do not code NEXT PAGE with PAGE FOOTING.
PAGE HEADING\|PH	First line(s) on each page. APS processes PAGE HEADING as the first report group on each page, unless a REPORT HEADING, that is not on a page by itself, precedes it. APS ignores PAGE HEADING on a page that contains only a REPORT HEADING or REPORT FOOTING. See also "Comments" below.
PAGE FOOTING\|PF	Last line(s) on each page. APS processes PAGE FOOTING as the last report group on each page of a report, unless a REPORT FOOTING, that is not on a page by itself, follows it. APS ignores PAGE FOOTING on a page that contains only a REPORT HEADING or REPORT FOOTING. See also "Comments" below.
REPORT FOOTING\|RF	Last line(s) of the report. The TERMINATE statement processes REPORT FOOTING as the last report group.
REPORT HEADING\|RH	First line(s) of the report. It is the first report group and processes once per report.

Comments:

Enter at least one TYPE statement per report.
Code a TYPE statement for each report group in the report, that is, each type of report line.
Code at least one detail line for each report, including a summary report. Without a detail line, SUM accumulators are not summed.
APS ignores NEXT GROUP with CONTROL FOOTING, unless CONTROL FOOTING is at the highest level for a control break.
Code LINE NUMBER and NEXT GROUP clauses on separate lines.
Specify the PAGE HEADING and PAGE FOOTING report groups only if the RED statement has a PAGE LIMIT clause. Specify the CONTROL HEADING or CONTROL FOOTING in the RED CONTROL clause. FINAL is implicit.

Examples:

01     TYPE IS REPORT HEADING    
           NEXT GROUP IS NEXT PAGE.   
01     TYPE IS PAGE HEADING.  
       SOURCE IS PAGE-COUNTER        PIC ZZZ9
01     PART-DETAIL TYPE IS DETAIL. 
       MOCKUP LINES 5 THRU 6   
       SOURCE IS PM-PART-NO          PIC XXXXXXXX
       SOURCE IS PD-LONG-DESC        PIC X(50) 
       SOURCE IS PM-UNIT-BASE-PRICE  PIC $$$,$$9.99
01     TYPE IS CONTROL FOOTING.  
       MOCKUP LINES 7    
       SUM PM-UNIT-BASE-PRICE        PIC $$$$,$$9.99

Print a report heading on line 20.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    TYPE IS REPORT HEADING LINE 20.

Insert blank lines in the report by incrementing the line number by two before printing the footer.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    TYPE IS REPORT FOOTING LINE PLUS 2.

Print two blank lines between groups. Indentation causes continuation when coding NEXT GROUP PLUS 2.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE
          NEXT GROUP PLUS 2.

Increment the page counter after printing a line.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01   TYPE IS REPORT HEADING
          NEXT GROUP NEXT PAGE.

UNION

Category:

Database access clause

Compatibility:

SQL target

Description:

Unite a DB-DECLARE or DB-PROCESS call with one or more DB-OBTAIN calls via the UNION keyword, which collects similar columns from two or more tables into one new table. The DB-OBTAIN calls in a union can select rows from one or many tables; the union results in a single table containing the rows selected by each call.

Syntax:

With DB-DECLARE:

DB-DECLARE cursorname [correlname1.]copylibname-REC
          .
          .
... UNION [ALL]
DB-OBTAIN REC copylibname-REC
          .
          .
          .
... [ORDER 
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

With DB-PROCESS

DB-PROCESS REC [correlname1.]copylibname-REC
          .
          .
          .
... UNION [ALL]
DB-OBTAIN REC copylibname-REC 
          .
          .
          .
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Parameters:

See the applicable database call for parameter descriptions.

Comments:

To create a union of tables, code all keywords and parameters for each DB-DECLARE, DB-OBTAIN, and DB-PROCESS call just as you do for a single call.
When coding a UNION, the columns selected in the DB-PROCESS or DB-DECLARE statements in the UNION determine the host variables the FETCH uses. Specify return-fields only in the DB-DECLARE or DB-PROCESS statements of the UNION. See the last example below.
Because a UNION places all rows in a single table, code INTO only in the last DB-OBTAIN call. However, if a DB-OBTAIN call joins tables, do not code INTO, which puts the results from only one table's host-area into the alternate area. A joined table has only part of its contents placed into the alternate area named by INTO.
The column selection list for DB-DECLARE, DB-PROCESS, and each DB-OBTAIN must adhere to standard SQL rules for UNION.
To identify the source call that produces each row in a UNION, include numeric and character literals in your column specifications for each call. Each row then includes a column that identifies the specific DB-DECLARE, DB-OBTAIN, or DB-PROCESS call that retrieved it.
Although you can code a literal for a column in any APS/SQL call, its primary use is for UNIONs.
UNION ALL includes all rows selected from the source tables in the new table. To eliminate duplicate rows from the new table, do not code ALL.
APS/SQL statements adhere to all other SQL requirements for tables created through a union.
UNION combines tables with the same number of columns. The rows of each table must contain column sequences that match in data type and length.
To sort rows in a table, code the ORDER clause, as follows.
- Code ORDER only once, as the final statement in the last DB-OBTAIN call. The ORDER clause applies to the result table produced by UNION.
- Specify sort columns by their position in the selection list (for example, 1 or 2), rather than by name.

Examples:

Unite DB-DECLARE with one DB-OBTAIN; eliminate duplicate rows; sort the combined table in ascending order by PM_PART_NO, then in descending order by PM_UNIT_BASE_PRICE and PM_UNITS. Note that the column literals STMT1 and STMT2 identify which call retrieves each row.

DB-DECLARE D2MAST-CURSOR D2TAB-REC
... DISTINCT
... PM_PART_NO PM_UNIT_BASE_PRICE PM_UNITS 'STMT1'
... WHERE PM_PART_SHORT_DESC = :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE BETWEEN 50 AND 150
... UNION
DB-OBTAIN REC D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE PM_UNITS 'STMT2'
... WHERE PM_PART_SHORT_DESC = :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE > 300
... AND PM_UNITS > 1000
... ORDER 1,2 DESC, 3 DESC

Unite DB-PROCESS with one DB-OBTAIN call. Sort the combined table in ascending order by PM_PART_NO, then in descending order by PM_UNIT_BASE_PRICE and PM_UNITS.

DB-PROCESS REC D2TAB-REC
... DB-PROCESS-ID D2UNION-ID
... DISTINCT
... PM_PART_NO PM_UNIT_BASE_PRICE PM_UNITS
... WHERE PM_PART_SHORT_DESC = :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE > 50
... AND PM_UNIT_BASE_PRICE < 150
... DB-LOOP-MAX=500
... UNION
DB-OBTAIN REC D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE PM_UNITS
... WHERE PM_PART_SHORT_DESC = :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE > 300
... AND PM_UNITS > 1000
... ORDER 1,2

Because return-fields are not specified for JOB_NAME and PROC_NAME, the host variables of those same names are used. In the case of the literal P, no host variable exists so a return-field must be specified. Specify return-fields only in the DB-DECLARE or DB-PROCESS statements.

DB-PROCESS
... REC A.HTJCLD-REC
... DB-PROCESS-ID SHARED-ID
... JOB_NAME
... PROC_NAME
... REC B.HTJOBR-REC
... 'P'  (WS-HOLD-ACTION)
... WHERE B.RESOURCE = :WS-RESOURCE AND 
... B.JOB_NAME = :WS-JOB-NAME
... UNION ALL
DB-OBTAIN REC A.HTJCLD-REC
... DISTINCT JOB_NAME
... PROC_NAME
... REC B.HTJSTEP-REC
... 'A'
... WHERE B.JOB_NAME = :WS-JOB-NAME
... ORDER 01 03 02

UNTIL/WHILE

Category:

S-COBOL structure (see S-COBOL Structures)

Description:

Form a loop with a test at the beginning that allows a subordinate statement block to execute repeatedly, either until or while a single or compound condition is satisfied.

Syntax:

Format 1:

REPEAT
        .
        .
        .
UNTIL|WHILE condition1 [AND|OR condition2 
... [... AND|OR conditionN]]
    statementblock

Format 2:

REPEAT
    statementblock1
UNTIL condition
      statementblock2

Format 3:

REPEAT
    statementblock1
UNTIL condition
      statementblock2
statementblock3

Comments:

Use these statements with REPEAT to test a condition at the middle or end of a loop.
In the Format 2, APS tests the condition after the REPEAT statementblock1 executes. Be careful using this format for reading records--it can read the last record twice.
In the Format 3, APS tests the condition after the REPEAT statementblock1 executes, but before the UNTIL statementblock2 executes. When the UNTIL condition is true, the UNTIL statemenblock2 does not execute.

Examples:

Find the first X in a string of characters.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 PARA   FIND-X
            A-SUB = 1
            UNTIL A-SUB > 100
            ... OR CHAR (A-SUB) = "X"
                A-SUB = A-SUB + 1
            IF A-SUB <= 100  
                CHARACTER-COUNT = A-SUB
            ELSE
               .
               .
               .

Use WHILE to achieve the same results.

        WHILE A-SUB <= 100
        ... AND CHAR (A-SUB) NOT = 'X'

USE BEFORE REPORTING

Category:

Report Writer clause (see Report Writer Structures and the APS User's Guide chapter Create Reports with Report Writer)

Compatibility:

Batch environments

Description:

Code declarative procedures to modify any heading or footing report group before it prints. You can specify special processing requirements, including calculations in addition to those specified in the SUM clause, and edits to a report line.

Syntax:

USE BEFORE REPORTING identifier

Parameters:

identifier

Designate a HEADING or FOOTING report group. Identifier cannot appear in more than one USE BEFORE REPORTING.

Comments:

USE BEFORE REPORTING identifies declarative statements that execute before HEADING or FOOTING report groups print. You name the report group in the Report Section of the Data Division.
A USE statement follows a section header in a declaratives section and ends with a period and space. The section can consist of paragraphs that define procedures.
A USE BEFORE REPORTING statement cannot alter the value of any control data item.
The INITIATE, GENERATE, or TERMINATE clauses cannot appear in a paragraph within a USE BEFORE REPORTING.
Report Writer ensures that the designated statements execute just before the specified report group.
Declarative statements cannot reference non-declarative statements; conversely, non-declarative statements cannot reference a statement name appearing in the declarative portion. The COBOL PERFORM statement is the only exception of a non-declarative that refers to a declarative statement.

Example:

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 NTRY  OPEN INPUT
       OPEN OUTPUT
       PERFORM MAIN-PARA
 DPAR  SUPPRESS-CH-REGION SECTION
       USE BEFORE REPORTING CH-REGION
 DPAR  SUPPRESS-CH-REGION-PARA
          IF FIRST-FLG = TRUE
             SUPPRESS PRINTING

User Help

Category:

User application Help

Description:

Create the help source file.

Procedure

To create the help source file, follow these steps,

From the APS Main Menu, enter option 2 in the Command field. Then enter option 6 in the Command field. APS displays the User Help Facility screen.
From the User Help Facility screen, enter 1 in the Command field. APS displays the User Help Source Utility screen.
Select a utility to create your help source file. If you select , Applications, APS displays the Applications Utility screen. If you select Data Elements, APS displays the Data Elements Utility screen. If you select Screens, APS displays the Screens Utility screen.

Complete the fields for the utility selected.

Field	Screen	Description
Context Name	Data Elements	Enter the context name associated with the field to display all the fields with that context. Leave this field blank to display the fields with no context. Enter all to display all the fields with their contexts.
Context List	Data Elements	Display a context list.
Application Name	Applications	Enter the user application name, or leave this field blank and press Enter to display a selection list. Select a name from the selection list by entering s next to it.
Field Name	Data Elements	Type a field name or leave this field blank to display a selection list.
Screen Name	Screens	Type a screen name, or leave this field blank to display a selection list.
Edit Business Name	All	Select to assign a business name a descriptive name that easily identifies the user application and its components). If you do not assign a business name, it defaults to the user application name.
Edit text	All	Select to create help text.
Include Screens	Applications	Select to create screen help.
Include Fields	Applications	Select to create field help.
Local Fields	Applications and Screens	Select to create field help.
Create Values	All	Select to create field value help.
Help Source File Name	All	Help source file name, TMP.APSEXT. If this file already exists, it is overlaid. Note: Do not use an extension with this filename.

Examples:

USERNAME

Category:

S-COBOL structure (see S-COBOL Structures)

Description:

Direct either the current APS paragraph name or one you designate to name a procedure generated by the APS Precompiler, so that your program follows the conventions, requirements or preferences of a given application or installation.

Syntax:

USERNAME paragraphname

Comments:

To activate any USERNAME statement, select the USERNAME option at compile time from the APS Precompiler Options screen; otherwise, the paragraph name for a generated procedure is G--nnn, where G means generated and nnn begins with 001 and increases by one for each generated paragraph name in top-down order.
When USERNAME is selected, APS creates paragraph names as follows.
- APS generates single dashes instead of double dashes.
- APS uses the current paragraph name, unless USERNAME is coded in a paragraph. Then it uses that paragraph name until the end of the paragraph.
USERNAME paragraph applies only to names assigned for procedures generated as the direct result of code within the paragraph where USERNAME appears. When more than one USERNAME is coded in a paragraph, APS assigns the first user-designated paragraph name until it is overridden by a second name in the APS processing sequence.
USERNAME does not appear in the generated code.
Be careful to avoid any naming conflicts that can arise with USERNAME.

VALUE (Data Structure)

Category:

Data Structure Painter construct (see Data Structures)

Description:

Code VALUE clauses in your data structures.

Syntax:

dataname PICformat
[...] [VALUE|V] 'valueclause'

Comments:

Valueclause can be as long as you need, continuing on subsequent lines with the continuation symbol.
You can code valueclause on the same line as dataname, if it fits entirely on that line.
Do not enclose numeric values in single quotation marks.

Examples:

Data Structure Painter format:

-LINE- ----- Data Structure Painter ----------
000001  WRK1-FIELD-7 X(120)
000002  ... VALUE 'A LONG LITERAL MAY BE
000003  ...  CONTINUED ON ONE OR
000004  ...  MORE LINES'
000005  WRK1-FIELD-8 X(80)
000006  ... V 'A VALUE CLAUSE THAT SPANS
000007  ...  TWO OR MORE LINES MUST BEGIN
000008  ...  ON ITS OWN LINE'

Generated COBOL code:

01  WRK1-FIELD-7    VALUE 'A LONG LITERAL MAY BE CONT
    'INUED ON ONE OR MORE LINES'
                           PIC X(120).
 01  WRK1-FIELD-8    VALUE 'A VALUE CLAUSE THAT SPANS
   'TWO OR MORE LINES MUST BEGIN ON ITS OWN LINE'
                           PIC X(80).

Data Structure Painter format:

-LINE- ------- Data Structure Painter ---------
000001  WRK1-FIELD-5 x(18) V'18 CHARACTERS LONG'
000002  WRK1-FIELD-6 x(13)
000003  ... V'13 CHARS LONG'

Generated COBOL code:

01  WRK1-FIELD-5 PIC X(18)
                 VALUE '18 CHARACTERS LONG'.
01  WRK1-FIELD-6 VALUE '13 CHARS LONG'
                 PIC X(13).

VALUE (Report Writer)

Category:

Report Writer clause (see Report Writer Structures and the APS User's Guide chapter Create Reports with Report Writer)

Compatibility:

Batch environments

Description:

Designate, as literals, any values that can be interpreted as PIC characters, such as embedded Xs and 9s to a mock-up text field.

APS considers two or more consecutive COBOL PIC characters a COBOL PIC clause and all other strings as literals, with the following exceptions.

The letter A is a literal character
A single hyphen is a COBOL picture character; a string of hyphens is a literal.
A 9 or an X bounded by spaces is a COBOL PIC; any other character surrounded by spaces is a literal.
Lower case letters are literals, not I/O fields.

To distinguish literals from PIC strings, such as the literal EXXON, which would be interpreted as the literal E, followed by the PIC string XX, and the literal ON, paint the word as a data field in the report mock-up and use the VALUE clause when coding the detail line data item description in your program.

Syntax:

VALUE "characterstring" [PIC picclause]
    [DATA-NAME [IS] fieldname]

Keywords/Parameters:

"character
string"

Designate a literal as follows.

Enter the text field on the mock-up as a data field (that is, a series of Xs).
Code VALUE "characterstring", where characterstring is the literal value of the text field.

DATA-NAME fieldname

Name a sum accumulator established by a SUM or REFERENCE clause. Do not define fieldname in Working-Storage. At generation, APS inserts fieldname after the level number in the generated report group. DATA-NAME moves the value of the internal SUM accumulator to fieldname.

Code DATA-NAME when a SUM UPON clause references DETAIL report group, when the program references a sum accumulator, or when a sum accumulator requires a data name for qualification.

PIC clause

Specify the format of characterstring.

Example:

Create the report heading QUARTERLY REPORT FOR EXXPERT.

====
QUARTERLY REPORT FOR XXXXXXX
====
-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    TYPE IS PAGE HEADING.
       MOCKUP LINE 1
       VALUE 'EXXPERT' PIC X(7)

Values, Conversion Values, and Value Ranges

Category:

Screen Painter feature (see Field Edits)

Description:

Ensure that the end user enters only certain values in a screen field by assigning values and value ranges or conversion values to that field.

Note: You can assign values or conversions, but not both.

Procedure:

To assign values to a field, follow these steps.

From the Screen Painter, access the Field Edit Facility.
Access the Values or Conversions screen by selecting the Values or Conversions prompt on any Field Edit screen.
Assign a specific value or a range of values using the following syntax formats.
```
value
lowvalue TO|THRU highvalue
lowvalue UP
highvalue DOWN
```

Assign conversion values using the following syntax format.

(input1, input2, ..., inputN, I=internalvalue, O=outputvalue)

To specify that the listed conversions are the only valid input values, select the Verify Conversion Values option.

Comments:

Follow these rules when you specify values.

Separate each entry with a comma.
Do not code commas in an entry.
Code only numeric values or ranges for numeric fields.
Ensure that the value length meets the restrictions of the Internal Picture format.
Use negative values only if the internal data representation is signed.
Use decimals only if the internal data representation includes a decimal.
For example:
```
1000 to 30000, 50 down
NORTH, SOUTH, EAST, WEST
25.5 to 35.5, 45.5 to 55.5, 100
-10 to 25, 50.5 up
```
Follow these rules when you specify conversions.
Separate each entry with a comma.
Code the internal storage conversion format in internalvalue.
Code the output display in outputvalue.
Ensure that the internalvalue and outputvalue are valid input data.
For example, the entry (ja,jan,i=1,o=January) means that the end user can enter ja or jan; APS converts and stores the ja or jan to 1; and APS displays the output as January.

Variable Length File Support

Compatibility:

VSAM batch target

Description

APS locates a variable length record description directly under the associated FD and places the fixed length record descriptions in Working-Storage.

WRITE ROUTINE

Category:

Report Writer clause (see Report Writer Structures and the APS User's Guide chapter Create Reports with Report Writer)

Compatibility:

Batch environments

Description:

Override the COBOL WRITE statement and execute your own routine.

Syntax:

WRITE ROUTINE [IS] paragraphname

Comments:

If you code WRITE ROUTINE, you can define your report record as a group-level record in the File Section and reference it in your WRITE ROUTINE paragraph.
APS generates a single-field 01-level report record when you code REPORT IS in the FD statement. You can replace REPORT IS with a definition of a group-level record--that is, an 01-level record with elementary data items. APS generates a 248-byte 01-level report record in Working-Storage, for the largest possible report; it generates a 250-byte record if the RED keyword CODE clause is coded.
If FDs are not included in your program, as when accessing GSAM files, you can still create a WRITE routine by defining an 01-level user file record. Report Writer uses this record to generate an 01-level report file record in Working-Storage that stores the report records.

Example:

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 FD    INPUT-FILE
       LABEL RECORDS ARE STANDARD
       BLOCK CONTAINS 0 RECORDS.
 01    PART-STOCK-REC                 PIC X(80).
 FD    REPORT-OUTPUT-FILE
       LABEL RECORDS ARE STANDARD
 01    USER-REPORT-RECORD.
       03  USER-REPORT-APS-PART       PIC X(248).
       03  USER-REPORT-USER-PART      PIC X(7).
   .
 RED   STOCK-REPORT
   .
       WRITE ROUTINE IS USER-DEFINED-PARA
   .
 NTRY
   .
 PARA  USER-DEFINED-PARA
   .
       MOVE STOCK REPORT RECORD TO 
       ...USER-REPORT-APS-PART

WS

Category:

Program Painter and Specification Editor keyword (see Keywords)

Description:

Define or include data structures in the Working-Storage Section.

Syntax:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 WS
 kywd   associated data structure

Comment:

Associated data structure keywords are 01, DS, REC, or ++.

Example:

Use Section keywords to code Working-Storage data structures.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 IO     INPUT-FILE ASSIGN TO UT-S-INPUT
 IO     OUTPUT-FILE ASSIGN TO UT-S-OUTPUT
 SPNM   C01 IS TOP-OF-PAGE
 FD     INPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 01     INPUT-REC         PIC X(80).
 DS01   INPUT-REC
 FD     OUTPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 REC    OUTPUT-REC       X80
 01     OUTPUT-REC-R REDEFINES OUTPUT-REC.
        ... COPY OUTREC.
 WS 
 REC     WS-INPUT-REC
            WS-IN-PART-NO       N8
            WS-IN-DESC          X50
            WS-IN-BASE-PRICE    N6V2
 01     WS-OUT-REC
 DS05   WSOUTREC

XCTL

Category:

Data communication call (see Data Communication Calls)

Compatibility:

CICS, ISPF Dialog, and ISPF Prototyping, targets

Description:

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

Syntax:

CICS

Transferring to a APS program:

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

Transferring to a non-APS program:

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

ISPF Prototyping

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

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 an APS 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 (/), APS moveS the literal to it.

Comments:

When transferring control to an APS 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 control to a non-APS 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"
```

ISPF Dialog

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.

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-APS program, PROG001.

XCTL PROG001(NONAPS)