S

S-COBOL Structures

Description:

An APS program can be coded in APS Structured COBOL (S-COBOL) language structures, either in combination with or instead of COBOL statements. S-COBOL structures are procedural, and extend the power of native COBOL, yet simplify and shorten the amount of code you must write.

You can write a complete APS program in S-COBOL. There are no differences between S-COBOL and batch COBOL in the Identification, Environment, and Data Divisions. The major differences exist in the Procedure Division.

S-COBOL reserved words are the same as ANSI COBOL, plus the following. For a complete list of all APS reserved words and symbols, see Reserved Words.

ALWAYS	ELSE-IF	ESCAPE
EVALUATE	FALSE	FALSX
NEVER	REPEAT	SAGE-TRACE-FLAG
TRUE	TRUX	UNTIL
USERNAME (IMS only)	WHILE

You code the S-COBOL structures in paragraphs and statement blocks. A paragraph is denoted by the keyword PARA and a paragraph name, followed by clauses or a statement block. Within a paragraph, indentation determines the exact positioning of statements. A paragraph ends with the next appearance of any Procedure Division keyword.

Indentation determines how the statements execute. For example, when you indent a statement under a conditional statement, the indentation tells APS that this statement is subordinate to the condition.

APS reads an S-COBOL program from top to bottom. The first paragraph performs all other paragraphs. Within paragraphs and statement blocks, statements execute sequentially until conditional statements, PERFORMs, or CALLs modify the sequence of operations. Indentation controls the logical sequence in which lines of source code execute.

Code S-COBOL structures in the Program Painter for batch, report, or complex online programs, or in the Online Express Specification Editor for an Express program.

List of Structures:

The following are the S-COBOL structures.

Verbs

ENTRY	Establish entry point for subprogram.
ESCAPE	Exit from the current paragraph.
EVALUATE	Evaluate one or more conditions; program a decision table.
EXIT PROGRAM	End the execution sequence.
PERFORM	Execute a particular paragraph or section, with or without arguments.
REPEAT	Establish a loop for testing.
SEARCH	Establish looping or conditionals for each WHEN condition.
STOP RUN	Return control to the operating system.
TRUE/FALSE	Establish true and false flags; test the flags.
UNTIL/WHILE	Form a loop with a test.
USERNAME	Title a procedure generated by the APS Precompiler.

Conditionals

AT END/INVALID KEY	Test for end-of-file or invalid key condition.
EVALUATE	Evaluate one or more conditions; program a decision table.
IF/ELSE-IF/ELSE	Evaluate one or more conditions.
SEARCH	Establish looping or conditionals for each WHEN condition.
TRUE/FALSE	Establish true and false flags; test the flags.

Error Handling

AT END/INVALID KEY	Test for end-of-file or invalid key condition.
TRUE, FALSE, ALWAYS, NEVER	Use these APS-supplied flags for testing.
TRUE/FALSE	Establish true and false flags; test the flags.
SAGE-TRACE-FLAG	Debug with the Trace facility.

Flags

TRUE, FALSE, ALWAYS, NEVER	Use these APS-supplied flags for testing.
SAGE-TRACE-FLAG	Debug with the Trace facility.

Looping

REPEAT	Establish a loop for testing.
UNTIL/WHILE	Form a loop with a test.

Transferring Program Control

ENTRY	Establish entry point for subprogram.
ESCAPE	Exit from the current paragraph.
EXIT PROGRAM	End the execution sequence.
STOP RUN	Return control to the operating system.

Syntax Rules:

Observe the following rules and conventions when coding an S-COBOL program.

When coding paragraph names, at least one character within the first 24 characters must be unique for each paragraph in the program.
Code only one verb per source code line.
Do not code punctuation in the Procedure Division. It is unnecessary and therefore disregarded.
Code punctuation within the Identification, Environment, and Data Divisions that conforms to COBOL rules.
Code structures with consistent indentation. The level of indentation can vary with each new statement block; however, it cannot vary within a statement block of code. We recommend using four additional spaces for each new level of indentation.

Do not code the following structures.

```
PERFORM ... THRU statement
```

PERFORM paragraphname(arg1, arg2, ..., argN)
... UNTIL condition

```
GO TO statement
```

SORT|MERGE THRU ... sectionname with INPUT PROCEDURE or
				OUTPUT PROCEDURE.

```
NEXT SENTENCE
```

Avoid using the double-hyphen (--). The S-COBOL translator frequently creates procedures and flags required for generating ANSI COBOL that are unnecessary and sometimes invalid in S-COBOL. Generated names for these procedures or flags always contain a double-hyphen to avoid conflict with programmed names. Under IMS, the USERNAME parameter can change double hyphens to single hyphens at S-COBOL processing time.
Continue a structure on subsequent lines by coding an ellipsis followed by a space (... ).
Continue a non-numeric literal by splitting the literal and concatenating the parts, which APS then treats as separate literals. Concatenate non-numeric literals by separating them with an ellipsis, space, two ampersands, and space (... && ), for example,
```
-KYWD-  12--*--20---*----30----*---40
           REGISTER = " THIS IS A VERY,"
           ... && "VERY LONG LITERAL"
```
Enclose literals with quotation marks. S-COBOL allows both single and double quotation marks within the same program.

Use any of the following relational operators to make comparisons.

Type of Comparison	Relational Operator
Greater than	IS GREATER THAN IS >
Not greater than	IS NOT GREATER THAN IS NOT > IS <=
Less than	IS LESS THAN IS <
Not less than	IS NOT LESS THAN IS NOT < IS >=
Equal to	IS EQUAL TO IS =
Not equal to	IS NOT EQUAL TO IS NOT =
Greater than or equal to	>=
Less than or equal to	<=

Create compound conditions by using ANDs or ORs.

Optionally, use a simplified syntax

Abbreviated Syntax	S-COBOL/COBOL Equivalent
A = B	MOVE B TO A
A B = C	MOVE C TO A B
A = B + C	COMPUTE A = B + C
B = B + C	COMPUTE B = B + C
A = B - C	COMPUTE A = B - C
A = B * C	COMPUTE A = B * C
A = B / C	COMPUTE A = B / C
A = B + (C * D)	COMPUTE A = B + (C * D)
A <+ B	COMPUTE A = A + B
A </ B	COMPUTE A = A / B
A << B	MOVE B TO A
A <* B	COMPUTE A = A * B

Use the above simplified syntax with any of these verbs - ADD, COMPUTE, DIVIDE, MOVE, MULTIPLY, SUBTRACT

The following syntax is ambiguous, so results are unpredictable:

IF condition = condition
ELSE-IF condition = condition
    ELSE-IF condition = condition

To achieve correct results, code:

IF condition = condition
ELSE-IF condition = condition
ELSE-IF condition = condition

or:

IF condition = condition
ELSE-IF condition = condition
    IF condition = condition
    ELSE-IF condition = condition

Example:

The following example demonstrates control logic without interrupting the flow or readability of the program with a GO TO. Program control is handled entirely by S-COBOL indentation.

-LINE- -KYWD-  12--*--20---*----30----*---40---*----50---*--
001030  PARA   PAYROLL-CALCULATION  /*PARAGRAPH NAME
001040         IF EMPLOYEE-TYPE = 'HRLY'
001050             IF HOURS-WORKED > 40
001060                 HOURS-BASE = HOURS-WORKED * 2
001070                 HOURS-BASE = HOURS-BASE - 40
001080             ELSE
001090                 HOURS-BASE = HOURS-WORKED
001100                 GROSS-PAY = HOURS-BASE * HOURS-RATE
001110             ELSE
001120                 GROSS-PAY = EMPLOYEE-SALARY

Because IF conditions generally require an alternative action, you generally code an ELSE-IF or ELSE statement at the same level of indentation as the IF. In the previous example, if EMPLOYEE-TYPE is not equal to HRLY (line 1040), control passes to the corresponding ELSE statement on line 1110. On the other hand, if EMPLOYEE-TYPE is equal to HRLY, lines 1050-1100 execute. In this case, if HOURS-WORKED is not greater than 40, control passes to the ELSE statement at the same indentation (line 1080). Thus, lines 1060-1070 execute only for hourly employees who have worked over 40 hours, while line 1090 executes for hourly employees who have worked 40 hours or less.

Line 1100 executes for all hourly employees, because these lines are at the same level as the preceding IF/ELSE. Line 1120 executes for employees who are not hourly.

See...	For other information about coding S-COBOL programs...
See PARA and Paragraphs	Coding statement blocks
See Limits	S-COBOL limits

Scenario Definition Report (CN01)

Category:

APS-generated report (see Application Reports)

Description:

The Scenario Definition Report displays the Scenario Painter components as they are painted, along with descriptive information such as comments and screen title, as well as each screen in the scenario as painted. Use this report to document scenarios for end users, so they can help you determine whether your scenarios cover all of the required cases.

Comment:

Produce the Scenario Definition Report from the Report Generator by selecting Actions and then the set of members you want. Or, enter 1, 2, or 3 in the Option field. If you enter 3, enter a member name or range of member names for selecting report data and then enter cn in the Library field. Press Enter to submit a job to produce the report.

Example:

REPORT CODE: CN01                APS APPLICATION PAINTER                     PAGE     1
                                SCENARIO DEFINITION REPORT               01/18/92 15:00
                                       CLSAPS.CLS2
SELECTION CRITERIA:
           TDDEMO1
****************************************************************************************
SCENARIO: TDDEMO1                                                      CREATED: 10/17/90
TITLE:                                                                 UPDATED: 10/17/90
****************************************************************************************

LINE     SCREEN           SCREEN TITLE                             USER COMMENT
----     --------         ---------------------------------------- ------------------
0001     TDME             CUSTOMER ORDER MAIN MENU                 MENU SELECTS ONLY
0002     TDCM             CUSTOMER MAINTENANCE                     BROWSE ONLY
0003     TDPL             PARTS INVENTORY LIST
0004     TDOM             ORDER RECORD MAINTENANCE
0005     TDOT             ORDER COST TOTALS                        SUMMARY SCREEN
0006     TDOJ             CUSTOMER ORDERS INQUIRY                  BROWSE ONLY
0007     TDOU             GIFT CERTIFICATES
0008     TDCS             ORDERS DELIVERY LIST
0009     TDPF             PART LIST SELECTIVE INFO
0010     TDPM             PART RECORD MAINTENANCE                  UPDATE

Screen Hardcopy/Field Attribute Report (SC01)

Category:

APS-generated report (see Application Reports)

Description:

The Screen Hardcopy/Field Attribute Report provides a mock-up of the screens you select as they are painted. In addition, the report includes sections that describe field attributes and field edits.

The Field Attribute portion lists the attribute values for each field in the order it appears on the screen. The report indicates default values with periods (..). The Occ(urrence) column shows the number of field occurrences within a repeated block. The end of the report shows the total number of screens on the report.

The Field Edits section lists the field edits applied to the fields.

Comments:

Produce the Screen Hardcopy/Field Attribute Report from the Report Generator, Painter Menu, or Application Painter.

You can then set or change generation options for the report. To do so, access the Report Options screen in one of the following ways.

From the Report Generator screen, select Options Report Options, or enter 4 in the Option field.
From any APS screen, select Options Report Options from the action bar, or enter opt in the Command or Options field. From the APS Options Menu that displays, select Actions Report Options from the action bar, or enter option 4 in the Options field.

Complete the fields on the Report Options screen.

Field

Values

Left Justify Report

Print the Screen Hardcopy Report (SC01) starting in column 1 to fit an 8.5 x 11 inch page.

Default. Center the report.

Field Attributes Report

Default. Print the Field Attributes Report with the Screen Hardcopy Report.

Do not print the Field Attributes Report.

Field Edits Report

Default. Print the Field Edits Report with the Screen Hardcopy Report.

Do not print the Field Edits Report.

Example:

REPORT CODE: REPT               APS 1.8  ENTITY REPORT FACILITY                    PAGE     1
   CLSAPS.CLS2                                                          01/18/92        15:04
REPORT CRITERIA:
           ALL SCREENS IN THE APPLICATION : TDDEMO
*********************************************************************************************
           LIBRARY       ENTITY
           TYPE          NAME            STATUS        REMARKS
           -------       ------          --------      --------------------------------------
           AP            TDDEMO          REPORTED
           SC            TDCM            REPORTED
           SC            TDCS            REPORTED
           SC            TDME            REPORTED
           SC            TDOJ            REPORTED
           SC            TDOM            REPORTED
           SC            TDOT            REPORTED
           SC            TDOU            REPORTED
           SC            TDPF            REPORTED
           SC            TDPL            REPORTED
           SC            TDPM            REPORTED

REPORT CODE: AP01                   APS APPLICATION PAINTER                      PAGE     1
                                 APPLICATION DEFINITION REPORT         01/18/92       15:04
                                          CLSAPS.CLS2
SELECTION CRITERIA:
 TDDEMO
*******************************************************************************************
APPLICATION: TDDEMO                                                       CREATED: 02/15/90
TITLE      :                                                              UPDATED: 08/30/90
AUTHOR     :CLSTR1                                                        DC TARGET: CICS
                                                                          DB TARGET: VSAM
*************************************************************************************************
-LINE-    PROGRAMS    SCREENS    IO    REPORTS    DATA STR   TY   SBSC/PSB   USERMACS   LOC
------    --------    -------    --    -------    --------   --   --------   --------   ---
000001    TDME        TDME       IO
000002    TDCM        TDCM       IO                               TDDB2
000003    TDPL        TDPL       IO                               TDDB2
000004    TDOM        TDOM       IO                               TDDB2
000005    TDOT        TDOT       IO                               TDDB2
000006    TDOJ        TDOJ       IO                               TDDB2
000007    TDOU        TDOU       IO                               TDDB2
000008    TDCS        TDCS       IO                               TDDB2
000009    TDPF        TDPF       IO                               TDDB2
000010    TDPM        TDPM       IO                               TDDB2

REPORT CODE: SC01                APS SCREEN PAINTER                           PAGE     1
                               SCREEN HARDCOPY REPORT                  01/18/92    15:04
                                    CLSAPS.CLS2
SELECTION CRITERIA:
  SCREEN-NAME = TDCM
*********************************************************************************************
ENTITY:  TDCM                                                         CREATED:  09/13/89
TITLE:                                                                UPDATED:  03/20/90
*********************************************************************************************
-+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8
                  CUSTOMER ORDER ENTRY SYSTEM

                      APS DEVELOPMENT CENTER

                   CUSTOMER RECORD MAINTENANCE

  FUNCTION ==========> X (Q-QUERY  U-UPDATE  A-ADD  D-DELETE)

 CUSTOMER NUMBER ===> XXXXXX              XXXXXXX
 CUSTOMER NAME =====> XXXXXXXXXXXXXXXXXXXX
 CUSTOMER ADDRESS ==> XXXXXXXXXXXXXXXXXXXX
 CUSTOMER CITY =====> XXXXXXXXXXXXXXXXXXXX
 CUSTOMER ZIP ======> XXXXXXXXX

 Enter CUSTOMER NUMBER TO QUERY A RECORD


 PF3 = MAIN MENU

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+---8

*********************************************************************************************
REPORT CODE: SC01                        APS SCREEN PAINTER                    PAGE     1
                                       FIELD ATTRIBUTE REPORT         01/18/91      15:04
      CLSAPS.CLS2
SELECTION CRITERIA:
  SCREEN-NAME = TDCM



*********************************************************************************************
ENTITY:  TDCM                                                         CREATED:  09/13/89
TITLE:                                                                UPDATED:  03/20/90
*********************************************************************************************
                                                               EDIT  HI-   INIT
FIELD         OCC ROW COL TYPE INTEN      MDT NUM DET MASK MOD COLOR LITE  CURS
---------------------------------------------------------------------------------------------

FUNCTION       7  29   1  UNPR BRIGHT      .   .   .   ..   .   ..   .....  T  .. .
CUSTOMER-NO    9  29   6  UNPR BRIGHT      .   .   .   ..   .   ..   .....  .  .. .
SAVEKEY        9  49   7  PROT DARK        .   .   .   ..   .   ..   .....  .  .. .
CUSTOMER-NAME 10  29  20  UNPR BRIGHT      .   .   .   ..   .   ..   .....  .  .. .
CUSTOMER-ADDR 11  29  20  UNPR BRIGHT      .   .   .   ..   .   ..   .....  .  .. .
CUSTOMER-CITY 12  29  20  UNPR BRIGHT      .   .   .   ..   .   ..   .....  .  .. .
CUSTOMER-ZIP  13  29   9  UNPR BRIGHT      .   .   .   ..   .   ..   .....  .  .. .
MESSAGE       24   2  79  PROT BRIGHT      .   .   .   ..   .   ..   .....  .   . .

REPORT CODE: ED01              APS SCREEN PAINTER                              PAGE    1
                                FIELD EDIT REPORT                      01/18/92    15:04
    CLSAPS.CLS2
SELECTION CRITERIA:
  SCREEN-NAME = TDCM

*********************************************************************************************
ENTITY:  TDCM                                                               CREATED: 09/13/89
TITLE:                                                                      UPDATED: 03/20/90
*********************************************************************************************

DEFAULT SCREEN LEVEL ERROR PROCESSING:
--------------------------------------
    SYSMSG FIELD: MESSAGE
    ERROR ATTRIBUTING: POS+BRT
    ERROR MESSAGE         : FIELD AT CURSOR IS IN ERROR
    REQUIRED FIELD MESSAGE: FIELD AT CURSOR IS REQUIRED

CONDITIONS TO BYPASS INPUT EDITING:
-----------------------------------
    BYPASS INPUT EDITS IF
    FUNCTION = 'Q'

    BYPASS INPUT EDITS IF
    PF01 ==>       PF09 ==>       PF17 ==>       PA01  ==>      
    PF02 ==>       PF10 ==>       PF18 ==>       PA02  ==>      
    PF03 ==>  S    PF11 ==>       PF19 ==>       CLEAR ==>      
    PF04 ==>       PF12 ==>       PF20 ==>       Enter ==>      
    PF05 ==>       PF13 ==>       PF21 ==>                      
    PF06 ==>       PF14 ==>       PF22 ==>                      
    PF07 ==>       PF15 ==>       PF23 ==>                      
    PF08 ==>       PF16 ==>       PF24 ==>                      


FIELD
----------------

CUSTOMER-NO       LEN:   6  ROW:   9  COL:  29  INTERNAL PICTURE: X(06)

                  INPUT EDITING:
                      REQUIRED
                      NUMERIC TEST

                  ERROR PROCESSING:
                      ERROR ATTRIBUTING: POS+BRT
                      ERROR MESSAGE         : YOU MUST Enter A NUMERIC VALUE
                      REQUIRED FIELD MESSAGE: YOU MUST Enter A CUSTOMER NUMBER


REPORT CODE: ED01                APS SCREEN PAINTER                         PAGE    2
                                  FIELD EDIT REPORT                01/18/92     15:04
                                     CLSAPS.CLS2
SELECTION CRITERIA:
  SCREEN-NAME = TDCM

CUSTOMER-NAME  LEN:  20  ROW:  10  COL:  29  INTERNAL PICTURE: X(20)

               INPUT EDITING:
                   REQUIRED
                   INPUT MASK: ADDDDDDDDDDDDDDDDDDD

               ERROR PROCESSING:
                    ERROR ATTRIBUTING: POS+BRT
                    ERROR MESSAGE         : CUSTOMER NAME MUST NOT BE NUMERIC
                    REQUIRED FIELD MESSAGE: YOU MUST Enter CUSTOMER NAME

CUSTOMER-ADDR     LEN:  20  ROW:  11  COL:  29  INTERNAL PICTURE: X(20)

                  INPUT EDITING:
                      REQUIRED

                  ERROR PROCESSING:
                      ERROR ATTRIBUTING: POS+BRT
                      REQUIRED FIELD MESSAGE: CUSTOMER ADDRESS MUST BE ENTERED

CUSTOMER-CITY     LEN:  20  ROW:  12  COL:  29  INTERNAL PICTURE: X(20)

                  INPUT EDITING:
                      REQUIRED

                  ERROR PROCESSING:
                      ERROR ATTRIBUTING: POS+BRT
                      REQUIRED FIELD MESSAGE: YOU MUST Enter THE CUSTOMER CITY

CUSTOMER-ZIP      LEN:   9  ROW:  13  COL:  29  INTERNAL PICTURE: X(09)

                  INPUT EDITING:
                      REQUIRED

                  ERROR PROCESSING:
                      ERROR ATTRIBUTING: POS+BRT
                      REQUIRED FIELD MESSAGE: YOU MUST Enter THE POSTAL CODE

Screen Redefinition

Description:

During screen generation, APS automatically generates record definitions describing the data layout and format of a screen. You can redefine the entire generated screen record, selected tables in the screen, or selected fields in the screen.

To do so, you set a flag to enable redefinition, and create user macros to generate the redefinition code. APS provides macro name suffixes that the flags recognize and invoke automatically.

To redefine multiple screens, see SCRNLIST.

Procedure:

To set a flag to enable redefinition, go to the APS CNTL file GENSYMB2 and set one of the following flags to 1.

&SCRGEN-RDF-REC

Use for redefining an entire screen record description. The flag invokes the $screenname-RECORD-RDF macro, which you write.

&SCRGEN-RDF-TAB

Use for redefining a screen table. The flag invokes the $screenname-TABLE-n-RDF macro, which you write.

&SCRGEN-RDF-FLD

Use for redefining a screen field. The flag invokes the $screenname-fieldname-RDF macro, which you write.

In the USERMACS macro library, create a macro to redefine your screen record description. Use the following macro naming conventions.

Entire record description

$screenname-RECORD-RDF

Field in a record description

$screenname-fieldname-RDF

Table in a record description

$screenname-TABLE-n-RDF

Where n is the table position in sequence with other tables on the screen, counting from top to bottom on the screen.

Comments:

When using the TP-ATTR call in a macro, use the original screen name, not the new (redefined) name.
When redefining a screen, include the attribute bytes as part of the redefinition.

Examples:

Redefine field PARTNO on screen INVENT. Note that all field names within the screen are prefixed with the screen name.

% DEFINE $INVENT-PARTNO-RDF
    &12+05 INVENT-PARTNO-Z99 &36+REDEFINES INVENT-PARTNO
                            &40+PIC Z99.

Redefine a table definition for a repeat block field named PART-NO-ROW on screen INVENT. The variable &INVENT-TABLE-1-MAX contains the number of occurrences for the repeated row block. The rule $SC-REP-FIELD-HEADER-0 generates the native attribute fields depending on the DC target. The field INVENT-PART-NO-ROW-EDITED contains the picture that is used to edit the data for output display.

% DEFINE $INVENT-TABLE-1-RDF
    &12+05  FILLER  &46+REDEFINES INVENT-TABLE-1.
        &16+10  FILLER  &46+OCCURS &INVENT-TABLE-1-MAX.
            $SC-REP-FIELD-HEADER-0("PART-NO-ROW")
            &20+15  INVENT-PART-NO-ROW-EDITED  &46+PIC ZZZ9.
% END

SCRNLIST

Category:

Data communication call (see Data Communication Calls)

Compatibility:

CICS, DDS, IMS DC, ISPF Dialog, and ISPF prototyping targets

Description:

Enable your program to use multiple screens and generate:

Procedural code to receive each specified screen
Screen records in the Working-Storage or Linkage Sections

SCRNLIST automatically generates when you specify multiple I/O screens for a program in the Application Painter. To redefine a single screen, see Screen Redefinition.

Syntax

CICS

[TP-]SCRNLIST screenname1 [... screenname12]
... [MAPSET(mapsetname)]
... [LINKAGE]
... [REDEFINE|NOREDEF]

IMS DC

Format 1:

[TP-]SCRNLIST screenname1 [.../screenname40]

Format 2:

[TP-]SCRNLIST screenname1 [... screenname40]

ISPF Dialog

Format 1:

[TP-]SCRNLIST screenname1[(LK)] [... screenname40[(LK)]]

Format 2:

[TP-]SCRNLIST screenname1[ ... screenname40]
... [LINKAGE]

ISPF prototyping

Any target syntax.

Parameters:

(LK) LINKAGE	Generate every screen record in the Linkage Section instead of in Working-Storage.
mapsetname	Mapset containing the screen(s) received by the program; must be a literal (maximum 7 characters).
NOREDEF	Screen records do not redefine each other. Ignored when coded with LINKAGE.
REDEFINE	Default. Screen records redefine each other.

Comments:

Code the SCRNLIST call to override the generated TP-SCRNLIST, or if coding outside the APS Painters.
Code SCRNLIST only once, before NTRY, and do not code a screen name with NTRY.
APS generates 88-level flags indicating the received screen.

TP-SCRN-RECEIVED                   PIC X(08)
    88  TP-screenname-RECEIVED     VALUE 'screenname'.

CICS

To generate multiple-map mapsets, access APS Utilities Menu, select the APS Precompiler screen, and then select option 2X, Generate BMS Multiple Map Mapset.

IMS DC

Label each screen in the APS Screen Painter. A labeled screen contains eight extra bytes (appended to the MID) that contain the screen name. NTRY logic determines which screen named in SCRNLIST was received, moves the data to the appropriate screen record description in Working-Storage, and performs any specified field editing.
Screens separated with a slash (/) instead of a space redefine each other in Working-Storage, limiting the size of Working-Storage.
A maximum of 30 screens can be listed in the Application Painter (and thus appear in the automatically-generated TP-SCRNLIST).

You can write macros to customize SCRNLIST processing for some or all screens in the screen list, using an APS-supplied predefined macro name.. APS executes the macros at locations immediately before and after the following APS-generated paragraphs.

APS Paragraph	Paragraph Function
APS-CHK-SCRN-RECEIVED-PARA	Checks which screen was received
APS-screenname-RECEIVED-PARA	Receives the screen
APS-SCRNLIST-EDIT-PARA	Determines which screen has field edits
APS-screenname-INP-EDIT-PARA	Processes screen field edits

Define the macros using these predefined macro name formats.

$TP-PRE-CHK-SCRN-RECEIVED
$TP-POST-CHK-SCRN-RECEIVED
$TP-PRE-screenname-RECEIVED
$TP-POST-screenname-RECEIVED
$TP-PRE-SCRNLIST-EDIT
$TP-POST-SCRNLIST-EDIT
$TP-PRE-screenname-INP-EDIT
$TP-POST-screenname-INP-EDIT

Examples:

CICS

Generate screen records SCRA and SCRB, that redefine each other, in Working-Storage. Both screens are in mapset SCRASET.

SCRNLIST SCRA SCRB MAPSET(SCRASET)

Generate a screen record in the Linkage Section for screen SCRA.

SCRNLIST SCRA MAPSET(SCRASET) LINKAGE

Generate screen records that do not redefine each other.

SCRNLIST SCRA SCRB NOREDEF

IMS DC

Code logic that receives either SCREENA, SCREENB, or SCREENC, and always sends SCREENC as the output screen:

IF TP-SCREENA-RECEIVED
    SCREENC-FIELD-1 = SCREENA-FIELD-X
    SCREENC-FIELD-2 = SCREENA-FIELD-Y
    SCREENC-FIELD-3 = SCREENA-FIELD-Z
          .
          .
IF TP-SCREENB-RECEIVED
    SCREENC-FIELD-1 = SCREENB-FIELD-XX
    SCREENC-FIELD-2 = SCREENB-FIELD-YY
    SCREENC-FIELD-3 = SCREENB-FIELD-ZZ

Code logic where, during a single execution, the program can receive either SCREENA or SCREENB. Let SCREENA and SCREENB redefine each other; keep SCREENC separate (not involved in the redefinition in the SCRNLIST call) in order to prevent any improper overlaying (and thus destruction) of data fields.

SCRNLIST SCREENA/SCREENB SCREENC

ISPF Dialog

Generate screen records SCRA and SCRB in Working-Storage:

SCRNLIST SCRA SCRB

Generate screen record SCRA in Working-Storage, and screen record SCRB in the Linkage Section

SCRNLIST SCRA SCRB(LK)

SD

Category:

Program Painter and Specification Editor keyword (see Keywords)

Description:

Include a sort file description.

Syntax:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SD     sortfilename
        [Applicable COBOL SD clauses]

Comments:

Use one SD keyword per sort file description.
Follow each file description with the file record description, using the 01, DS, REC, or ++ keywords.

Example:

-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-RECORD            PIC X(80)
               .
               .
 FD     OUTPUT-FILE 
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 01     OUTPUT-RECORD            PIC X(80)
               .
               .
 SD     SORT-FILE
        RECORD CONTAINS 80 CHARACTERS
        DATA RECORD IS SORT-RECORD 
 01     SORT-RECORD            PIC X(80)
               .
               .

SEARCH

Category:

S-COBOL structure (see S-COBOL Structures)

Description:

Use in the same manner as the COBOL SEARCH verb, including conditionals and looping for each WHEN condition.

Syntax:

Format 1:

SEARCH identifier1 VARYING indexname|identifier2
... [[AT] END]
    statementblock
[WHEN searchcondition1
    statementblock  ]
         .
         .
         .
[WHEN searchconditionN
    statementblock  ]

Format 2:

SEARCH ALL identifier [[AT] END]
    statementblock
WHEN searchcondition
    statementblock

Example:

Use SEARCH to achieve the NEXT SENTENCE concept. If the condition in lines 1040-1050 is true, pass control to line 1110.

-LINE- -KYWD-  12-*----20---*----30---*----40---*----50---*-
001010  PARA   SEARCH-TABLE
001020             SEARCH STOCK-ELEMENT AT END
001030                 PERFORM END-ROUTINE
001040             WHEN QUAN-ON-HAND (STOCK-INDEX) NOT < 
001050             ... QUAN-NEEDED (STOCK-INDEX)
001060             WHEN QUAN-ON-HAND (STOCK-INDEX) = ZERO
001070                 PERFORM NO-STOCK-ROUTINE
001080             WHEN QUAN-ON-HAND (STOCK-INDEX) <
001090             ... QUAN-NEEDED (STOCK-INDEX)
001100                 PERFORM DETERMINE-IF-ORDER-ROUTINE
001110             WORK-QUAN = QUAN-ON-HAND (STOCK-INDEX)

SEND

Category:

Data communication call (see Data Communication Calls)

Description:

Display screen data for end user response. Additionally:

Under CICS, generate a CICS SEND MAP command to send screen data to a terminal for user response, as well as a CICS RETURN command to return control to CICS.
Under IMS DC, send screen messages, in screen or record layout form, to terminals or printers.

Syntax:

CICS

[TP-]SEND screen[(mapsetname)] [errorpara]
... [TRANSID(name)]
... [NORETURN] [NOERASE]
... [CICSoption [CICSoption] ...]

ISPF Dialog

[TP-]SEND screen [errorpara]
... [CONTINUE|NOCONTINUE]

IMS DC

 [TP-]SEND screenname|recordname [errorpara]
 ... [lterm]
 ... [keyword[+keyword] ...]

ISPF Prototyping

Valid syntax is the CICS syntax, the ISPF Dialog syntax, and:

[TP-]SEND screenname|recordname [errorpara]
... [lterm]

Parameters:

CONTINUE

Execute the next instruction after the call. See also "Comments" below.

errorpara

User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.

keyword

Valid keywords are:

NOALTRESP	Default. Do not use the alternate response IO PCB to send the response to the terminal.
ALTRESP	Use the alternate response IO PCB to send the response to the terminal.
NOCONT	Default. Control returns to the top of the program to process another input message.
CONT	Execute the next instruction after the call.
CONTCOND	TP-CONTCOND determines if control passes to the next instruction or returns to the top of the program.
NOEXPRESS	Default. Do not send a message for abnormal program termination.
EXPRESS	Send a message at program termination.
NOENDCONV	Default. Do not blank out TRANCODE in the SPA.
ENDCONV	Blank out TRANCODE in the SPA.
SCREEN	Default. Input is an APS-painted screen. Multisegment screens are not supported.
RECORD	Input is recordname. See also "Comments" below.
NOPURG	Send all messages to the same destination as one multi-segmented message. Default with NOEXPRESS keyword.
PURG	After inserting the message, send it as one single-segmented message. Default with EXPRESS keyword.

lterm

Logical terminal or printer where program sends message; can be a literal (maximum 8 characters) or COBOL data name (maximum 9 characters). Default is device that sends an input message to the program.

mapsetname

Mapset containing the screen(s) the program receives; must be a literal (maximum 7 characters). When not specified, APS generates a default mapset name as per NTRY.

NOCONTINUE

Default. Return control to the top of the program. See also "Comments" below.

NOERASE

Suppress default generation of ERASE.

NORETURN

Suppress default generation of CICS RETURN command (after a generated CICS SEND MAP command).

recordname

User-defined I/O area in Working-Storage. See also "Comments" below.

screenname

Screen name; must be literal (maximum 8 characters).

TRANSID (name)

Transaction code identifying the program where control returns; can be a literal (maximum 4 characters) or COBOL data name (minimum 5 characters).

userparm

Pass linkage data area(s). Code with TP-LINKAGE, which names the 01-level user-defined area in the Linkage Section.

Comments:

ISPF Dialog

With NOCONTINUE, enter your return code checking routine under TP-SCREEN-INVOKED logic. With CONTINUE, enter your return code routine checking under SEND.

The following APS-provided structure checks the return code after a SEND.

APS-TP-SEND-RC           PIC 9(08).
    88  OK-ON-SEND       VALUE 0.
    88  NTF-ON-SEND      VALUE 4.
    88  END-ON-SEND      VALUE 8.
    88  AB-ON-SEND       VALUE 12 16 20

IMS DC

For recordname, move the MOD name to IM-SCREEN-RECORD-MODNAME (an APS-generated field) prior to SEND. Multisegment screens are not supported.
Use the PURG and NOPURG keywords to control how APS sends messages. When issuing multiple inserts to the same destination before reaching a SYNC point, IMS sends the messages as one multi-segmented message. If you send the message via an Express PCB, APS issues a PURG after the insert and sends it as one single-segmented message.
When coding RECORD and recordname in conversational programs, code the following statement if recordname differs from your application trancode.
```
SYM1    % &recordname-TRANCODE = "trancode"
```
When sending screens with edited fields, the value of the field variable (the COBOL name assigned during screen painting) moves to a field defined with a display format. The edited fields must contain valid values on output or the screen returns for correction.
To allow end users to send invalid or empty screen values, specify NORETRY with the NTRY keyword and use the generated flags to test for input data validity.
SEND logically terminates a program when executed; however, the program actually runs as a loop that processes multiple input messages.
To retain control in the program after sending a screen, code the CONT keyword. You can then send more than one screen or message from a program while processing a single transaction, or send multiple pages of output to the same destination.
When coding a conversational program in Online Express, APS checks your alternate IO PCB for the following parameters.
```
EXPRESS=YES
MODIFY=YES
ALTRESP=YES
```
If any parameters are missing, a message warns you that, if an error occurs after successful database updates, APS does not send a message to the originating terminal--the program simply terminates and performs a rollback of the updates.
In a single program execution, the terminal operator can page forward and backward with MFS logical paging commands. To do this:
1. Ensure that all pages are for the same screen format.
2. Ensure that all generated APS screens contain a single DPAGE.
3. Specify operator logical paging on the Screen Generation Parameters screen in the Screen Painter.
4. Specify that the trancode comes either from a screen field or from PF keys. If PF keys provide all or part of the trancode, define the PF key values on the MFS Function Key screen.

Examples:

CICS

Send screen map SCRA.

Program Painter source

SEND SCRA

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    CURSOR
    ERASE
    FREEKB END-EXEC.
EXEC CICS RETURN
    TRANSID( 'SCRA')
    COMMAREA(TP-COMMAREA)
    LENGTH(169) END-EXEC.
GO TO APS-USER-MAIN-PARA--EXIT.

Generate a CICS SEND MAP for map SCRA in mapset SCRASET; return to CICS with transaction code WXYZ. Override the default TRANSID specified in the Screen Painter.

SEND SCRA(SCRASET) * TRANSID('WXYZ')

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    CURSOR
    ERASE
    FREEKB END-EXEC.
EXEC CICS RETURN
    TRANSID( 'WXYZ')
    COMMAREA(TP-COMMAREA)
    LENGTH(169) END-EXEC.
GO TO APS-USER-MAIN-PARA--EXIT.

Generate a CICS SEND MAP for map SCRA.

SEND SCRA * NORETURN

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    END-EXEC.

DDS and DLG

Display screen SCRA. Determine whether END or RETURN was entered on the screen.

NTRY  SCRA
      IF TP-PROGRAM-INVOKED
          PERFORM  INITIALIZE-SCREEN-FIELDS
      ELSE-IF TP-SCREEN-INVOKED
          IF  END-ON-SEND
          ... OR SCRA-FUNCTION = 'E'
              /* USER ENTERED END OR RETURN
              TERM
          ELSE-IF OK-ON-SEND
              PERFORM  PROCESS-SCREEN-DATA
          ELSE
              SCRA-SYSMSG = 'INVALID OPTION'
      SEND SCRA * NOCONTINUE

Display screen SCRA. Determine whether END or RETURN was entered on the screen. Perform return code checking immediately following the SEND.

REPEAT
    SEND SCRA * CONTINUE
UNTIL APS-TP-SEND-RC > 0
    PERFORM  PROCESS-SCREEN-DATA
TERM

IMS DC

Send the single screen defined as output for the program.

SEND

In a program with multiple output screens, qualify the screens to send.

SEND SCRA

Send a screen using the EXPRESS PCB.

SEND SCRA * * EXPRESS

Send a screen using an alternate PCB and return to the next instruction following the call.

SEND SCRA * * CONT+ALTRESP

SOURCE

Category:

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

Compatibility:

Batch environments

Description:

Map Data Division items to output fields.

Syntax:

SOURCE [IS] dataname [iterativeexpression] [PIC picclause]
    [BLANK [WHEN] ZERO]
    [CHANGE INDICATE|GROUP INDICATE]
    [JUSTIFIED|JUST [RIGHT]
    [DATA-NAME [IS] fieldname]

Keywords/Parameters:

BLANK WHEN ZERO	Print spaces when SOURCE dataname is zero. COBOL usage rules apply.
CHANGE INDICATE	Print value of SOURCE dataname whenever it changes. See also "Comments:" below.
dataname	Data item being referenced; can be report mock-up field or a Working-Storage field. See also "Comments" below.
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 the DATA-NAME clause 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.
GROUP INDICATE	Identify an item, such as a header, that prints on the first occurrence of its report group after a control break or a page advance. You can use GROUP INDICATE when a DETAIL type defines a printable item; specify GROUP INDICATE for elementary items. If the RED keyword does not contain a PAGE or a CONTROL clause, a GROUP INDICATE item prints the first time its DETAIL line prints after INITIATE processing. See also "Comments" below.
iterative expression	Generate multiple SOURCE statements for suffixed data items or elements of an array. See the APS *User's Guide* chapter Creating Reports with Report Writer.
JUSTIFIED RIGHT	Right justify the field value. COBOL usage rules apply.
PIC picclause	Specify the format of dataname. If dataname is a report mock-up field instead of a Working-Storage field, the next matching COBOL picture in the report mock-up is the picclause for dataname.

Comments:

SOURCE immediately follows the MOCKUP or OVERPRINT clause.
SOURCE designates that the item is described in the program Data Division, is the special Report Writer register LINE-COUNTER or PAGE-COUNTER, or is the internal sum accumulator established by Report Writer.
In CONTROL FOOTING, PAGE HEADING, PAGE FOOTING, and REPORT FOOTING report groups, SOURCE cannot reference controls or data items referencing controls.
To map PAGE-COUNTER when there is more than one report in a program, code SOURCE PAGE-COUNTER OF reportname.
In a DETAIL type entry, use CHANGE INDICATE instead of GROUP INDICATE to suppress printing the item after a page break.
In a report mock-up, use PIC clauses instead of COBOL masks when formatting dates and times containing / $ or :. See Report Mock-Ups.

Example:

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    DETAIL-LINE TYPE IS DETAIL.
       MOCKUP LINE 16
       SOURCE WS-LOCATION-CODE    GROUP INDICATE
       SOURCE WS-LAST-COUNT-MONTH PIC 99
       SOURCE WS-LAST-COUNT-DAY   PIC 99
       SOURCE WS-LAST-COUNT-YEAR  PIC 99
       SOURCE WS-QTY-IN-STOCK     JUSTIFIED RIGHT
       SOURCE WS-QTY-ISSUED       JUSTIFIED RIGHT
       SOURCE WS-QTY-RECEIVED     JUSTIFIED RIGHT
       REFERENCE WS-NO-OF-SALES   PIC 9999

Special Registers

Compatibility

SQL target

Description:

Use selected APS/SQL calls to reference and test special registers as column values. Special registers include:

CURRENT DATE
CURRENT TIME
CURRENT TIMESTAMP
CURRENT TIMEZONE

Use special registers in DB-DECLARE, DB-OBTAIN, and DB-PROCESS calls to:

Store and display the special register values.
Evaluate special register values in WHERE clauses for conditional processing.

Comment:

Do not use SQL function names,such as HOUR, TIMESTAMP, as column names.

Examples:

Store the value of CURRENT-DATE in a Working-Storage field.

DB-OBTAIN REC D2TAB-REC
... PM_PART_NO
... PM_COLOR (WS-COLOR)
... CURRENT DATE (WS-CURR-DATE)
... WHERE PM_PART_SHORT_DESC = 'WIDGET'
... AND PM_COLOR = 'RED'

Select rows by comparing column SHIP_DATE with the special register CURRENT DATE.

DB-PROCESS REC D2INVEN-REC
... DB-PROCESS-ID D2INV-ID
... IN_PART_NO
... IN_PART_SHORT_DESC
... IN_QTY_ONHAND
... WHERE SHIP_DATE = CURRENT DATE

SPNM

Category:

Program Painter and Specification Editor keyword (see Keywords)

Purpose

Create a Special-Names paragraph in the generated program.

Syntax

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SPNM   statement1
    .
    .
    .
 SPNM   statement1

Example:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SPNM   C01 IS TOP-OF-PAGE

SQL

Category:

Program Painter and Specification Editor keyword (see Keywords)

Compatibility:

SQL target

Description:

Designate a DB2 table or cursor declaration in the Working-Storage or Linkage Section. Additionally, code native SQL statements and pass them through, without translation, to the precompile process.

Syntax:

Format 1, Working-Storage and Linkage Sections:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SQL    SQLdatastructurestatement
   .
   .
   .

Format 2, Procedure Division:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
        SQL nativecall
   .
   .
   .

Comments:

Use one SQL keyword for each SQL call. APS generates EXEC SQL and END-EXEC statements before the first and last statements, respectively.
In the Data Division, the SQL keyword designates a DB2 table or one or more cursor declarations in the Working-Storage or Linkage Section. Use one SQL keyword for each SQL call. APS generates EXEC SQL and END-EXEC statements before the first and last statements, respectively.
In the Procedure Division, start every SQL Procedure Division statement with the SQL verb, coded in columns 12 through 72. Begin subsequent lines of the statement with continuation ellipses. All statements pass to the precompiler without translation. SQL statements can be coded anywhere after the PARA, PROC, or NTRY keywords.

Examples:

Program Painter code:

-KYWD-  12--*--20---*----30----*---40---*---50---*---60---
 SQL
        DECLARE DSN8.TDEPT TABLE
        ... (DEPTNO CHAR(3) NOT NULL,
        ... DEPTNAME CHAR(36) NOT NULL,
        ... MGRNO CHAR(3) NOT NULL,
        ... ADMRDEPT CHAR(3) NOT NULL)
 REC    WS-DEPARTMENT
           DEPARTMENT-NUM       X3
           DEPARTMENT-NAME      X36
           DEPARTMENT-MGR-NO    X3
           DEPARTMENT-ADMIN     X3
 NTRY
        SQL
            ... SELECT DEPTNO, DEPTNAME,
            ... MGRNO, ADMRDEPT
            ... INTO :DEPARTMENT-NUM,
            ... :DEPARTMENT-NAME,
            ... :DEPARTMENT-MGR-NO,
            ... :DEPARTMENT-ADMIN
            ... FROM DSN8.TDEPT
            ... WHERE DEPTNO > 0
        IF SQLCODE > +0
            PERFORM ERROR-DISPLAY

Generated code:

%   &AP-GEN-VER = 1719
%   &AP-PGM-ID = "TSTSQL"
%   &AP-GEN-DC-TARGET = "ISPF"
%   &AP-TP-ENTRY-KYWD-SEEN = 1
%   &AP-SUBSCHEMA = ""
%   &AP-APPLICATION-ID = "TSTSQL"
%   &AP-GEN-DATE = "861219"
%   &AP-GEN-TIME = "16063323"
IDENTIFICATION DIVISION.
PROGRAM-ID.                     TSTSQL.
AUTHOR.                         AP-SYSTEM GENERATED.
DATE-WRITTEN.                   861219.
DATE-COMPILED.                  &COMPILETIME.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.                &SYSTEM.
OBJECT-COMPUTER.                &SYSTEM.
DATA DIVISION.
WORKING-STORAGE SECTION.
 $TP-WS-MARKER
    EXEC SQL INCLUDE SQLCA
    END-EXEC.
    EXEC SQL
    DECLARE DSN8.TDEPT TABLE             /*
        (DEPTNO CHAR(3) NOT NULL,        /*
      DEPTNAME CHAR(36) NOT NULL,        /*
        MGRNO CHAR(3) NOT NULL,          /*
        ADMRDEPT CHAR(3) NOT NULL)       /*
    END-EXEC.
 01  WS-DEPARTMENT.
     05  DEPARTMENT-NUM          PIC X(3).
     05  DEPARTMENT-NAME         PIC X(36).
     05  DEPARTMENT-MGR-NO       PIC X(3).
     05  DEPARTMENT-ADMIN        PIC X(3).
 $TP-COMMAREA
 $TP-ENTRY ("", "")
     SQL
         ... SELECT DEPTNO, DEPTNAME,
         ... MGRNO, ADMRDEPT
         ... INTO :DEPARTMENT-NUM,
         ... :DEPARTMENT-NAME,
         ... :DEPARTMENT-MGR-NO,
         ... :DEPARTMENT-ADMIN
         ... FROM DSN8.TDEPT
         ... WHERE DEPTNO > 0
     IF SQLCODE > +0
         PERFORM ERROR-DISPLAY

STOP RUN

Category:

S-COBOL structure (see S-COBOL Structures)

Description:

Return control to the operating system.

Syntax:

STOP RUN

Comments:

STOP RUN can appear anywhere in an S-COBOL program.
APS generates a STOP RUN at the end of the first paragraph of an S-COBOL program and at the end of the first paragraph of a called program that compiles independently of the main program.

STUB

Category:

Program Painter and Specification Editor keyword (see Keywords)

Purpose:

Include a program stub, or a reusable program module, that is available to any program in the application.

Syntax:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 STUB   stubname

Comments:

During generation, APS inserts the program stub where the keyword STUB appears.
To continue programming after a stub, code another keyword.

Example:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 NTRY   MSCR
        IF ENTER-KEY
            PERFORM READ-RTN (MSCR-PART-NBR, 
            ... MSCR-NEW-PART-NBR,
            ... MSCR-OLD-PART-NBR, 
            ... MSCR-SHORT-DESC, MSCR-UNITS,
            ... MSCR-BASE-PRICE, 
            ... MSCR-DIMENSIONS, 
            ... MSCR-ERR-MSG)
        ELSE
            MSCR-ERR-MSG = 'INVALID PF KEY ENTERED'
        SEND MSCR
 STUB   STUBPGM
 PARA   PROCESS-PARA

Subselect Clause

Compatibility:

SQL target

Desciption:

Create subselect clause by embedding a complete DB-OBTAIN call within a WHERE clause.

Syntax:

Embed a DB-OBTAIN call by enclosing it in parentheses. The syntax for the embedded DB-OBTAIN is the same as that for a standard DB-OBTAIN.

Comments:

Create subselect code in a DB-DECLARE, DB-OBTAIN, DB-PROCESS, or DB-STORE call.
All standard SQL requirements for a subselect clause apply to the embedded DB-OBTAIN.
The number and type of columns coded must match the DB-OBTAIN column sequence; both calls must specify columns from different tables.
When you code a DB-STORE call, make sure that you:
- Make the number of selected columns for DB-STORE match the number of columns in the result table for the subselect.
- Do not code the same copylibname-REC in both the DB-STORE and subselect calls.
- Do not code DB STORE FROM dataname.
- Do not code alternate values for any columns in DB-STORE.
- Do not enclose the subselect statement in parentheses, as you do for other DB calls.

Example:

DB-OBTAIN REC A.D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE
... WHERE EXISTS
... (DB-OBTAIN REC D2INVEN-REC
... WHERE IN_PART_NO = A.PM_PART_NO)
DB-DECLARE D2MAST-CURSOR D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE PM_COLOR
... WHERE PM_PART_NO IN
... (DB-OBTAIN
... REC D2INVEN-REC IN_PART_NO
... WHERE IN_QTY_ONHAND > 100)
... AND PM_UNIT_BASE_PRICE BETWEEN 50 and 100
DB-PROCESS REC D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE PM_COLOR
... WHERE PM_UNITS <
... (DB-OBTAIN REC D2TAB-REC
... AVG(PM_UNITS))
DB-STORE REC D2INVEN-REC
... IN_PART_NO IN_QTY_ONHAND
... DB-OBTAIN REC D2TAB-REC
... PM_PART_NO PM_PART_SHORT_DESC
... WHERE PM_UNITS > '99'

SUM

Category:

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

Compatibility:

Batch environments

Description:

Sum data items, and generate an internal SUM accumulator for a SOURCE or REFERENCE data field to be used in a control footing group.

Syntax:

SUM|+ [IS] dataname [iterativeexpression|dataname] ...
    [UPON detlineidentifier [detlineidentifier] ...]
    [RESET [ON] [FINAL] controlname]
    [DATA-NAME [IS] fieldname]
    [PICTURE|PIC [IS] picclause]

Parameters:

dataname	Data item to reference; can be report mock-up field or a Working-Storage field. Define as a numeric data item. See also "Comments" below.
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.
iterative expression	Generate multiple SUM statements for numerically suffixed data items or elements of an array. See the "Iterative Expressions" topic in the APS *User's Guide* chapter Creating Reports with Report Writer.
PIC picclause	Specify the format of dataname. If dataname is a report mock-up field instead of a Working-Storage field, the next matching COBOL picture in the report mock-up is the picclause for dataname. Picclause determines the size of the internal SUM accumulator.
RESET controlname	Set the SUM accumulator to zero after a control break on controlname. If RESET is not coded, the internal SUM accumulator resets to zero after each control break.
UPON detline-identifier	Sum on the printing of a specific detail line, when there is more than one detail line. Detlineidentifier is the name of DETAIL report group.

Comments:

To set up a SUM accumulator, identify the data field with a SOURCE or REFERENCE on the detail line, and sum it with a SUM clause on the control footing line. APS adds the value of dataname1 to its internal sum accumulator each time the dataname1 data item prints for a detail group.
SUM is valid for a CONTROL FOOTING report group only. It follows MOCKUP or OVERPRINT clause.
The internal SUM accumulator value prints with the CONTROL FOOTING group and then clears.
If the description for a printable data item contains a SUM clause, the internal SUM accumulator serves as a data item, that is, Report Writer moves the internal accumulator value to the data item for printing.
APS sums data field values into internal SUM accumulators during GENERATE and TERMINATE processing.

Examples:

Each time DEBIT-LINE generates, add SOURCE amount to the DEBIT-LINE and CREDIT-LINE amount accumulators.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    DEBIT-LINE TYPE IS DETAIL.
       MOCKUP LINE 1
       SOURCE AMOUNT               PIC 9(5)
 01    CREDIT-LINE TYPE IS DETAIL.
       MOCKUP LINE 2
       SOURCE AMOUNT               PIC 9(5)
 01    TYPE IS CONTROL FOOTING WS-PRODUCT-CODE.
       MOCKUP LINE 3
       SUM AMOUNT UPON DEBIT-LINE  PIC 9(6)
       SUM AMOUNT UPON CREDIT-LINE PIC 9(6)

Print CONTROL FOOTING and RESET the SUM accumulator to zero after the final control break.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE.
       MOCKUP LINE 15 THRU 21
       SUM WS-QTY-IN-STOCK RESET ON FINAL

RESET the WS-LOCAL-SALES field to continue accumulating a sum until the WS-REGION-SALES control break occurs.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 RED   SALES REPORT
       CONTROLS ARE FINAL WS-REGION-SALES 
          WS-LOCAL-SALES
 01     TYPE IS CONTROL FOOTING WS-LOCAL-SALES.
       MOCKUP LINE 5
       SUM WS-LOCAL-SALES RESET ON 
           WS-REGION-SALES

Move the value of the NO-OF-SALES accumulator to the TOT-SALES field.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE.
       MOCKUP LINE 12
       SUM NO-OF-SALES DATA-NAME TOT-SALES

Print all values for WS-QTY-IN-STOCK on the detail line in the report and the total of those values in the control footing of the report. Print the total only for WS-NO-OF-SALES in the control footing. When the detail line is prints, add the REFERENCE field value to the SUM accumulator.

-KYWD- 12-*----20---*----30---*----40---*----50---*----60
 01    DETAIL-LINE TYPE IS DETAIL.
       MOCKUP LINE 16
       SOURCE WS-QTY-IN-STOCK    PIC ZZZ,ZZ9
       REFERENCE WS-NO-OF-SALES  PIC 9999
 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE.
       MOCKUP LINES 17 THRU 23
       SUM WS-QTY-IN-STOCK    PIC Z,ZZZ,ZZ9
       SUM WS-NO-OF-SALES     PIC ZZZ9

SUPPRESS (IMS DB Option)

Compatibility:

IMS DB target

Description:

Suppress the generation of IMS database calls when prototyping under ISPF.

Description:

The &IM-SUPPRESS-DB-CALL field prevents DB calls from being generated in your program. During prototyping, this call enables you to code APS/IMS DB calls before you are ready to access the database.

This field resides in the APS CNTL file APSDBDC; set it to YES to suppress DB call generation; the default is NO.

Note: In Online Express, this is handled via the Database Calls field in the Express Parms screen in Online Express.

SUPPRESS (Report Writer)

Category:

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

Description:

Inhibit printing a report group named in a USE BEFORE REPORTING clause.

Syntax:

SUPPRESS PRINTING

Comments:

Use SUPPRESS only with USE BEFORE REPORTING.
This structure suppresses the following report group functions.
- Line printing
- LINE NUMBER and NEXT GROUP processing
- LINE-COUNTER adjusting
APS generates the COBOL statement MOVE 1 TO PRINT-SWITCH. When this statement is processed the warning message, NEXT GROUP WILL BE SUPPRESSED, displays.

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

SUPRA

Category:

S-COBOL structure (see S-COBOL Structures)

Description:

Code native SUPRA DBMS procedural statements in the Procedure Division of an S-COBOL program.

Syntax:

S-COBOL source input

WS
01   [viewname] INCLUDE logicalviewname [(userfieldlist)]
    .
    .
    .
     SUPRA suprastatement
     ...   suprastatement 
     ...  .
     ...  .
     ...  .

COBOL source output

WORKING-STORAGE SECTION.
01  [viewname] INCLUDE logicalviewname [(userfieldlist)]
    .
    .
    .
    suprastatement
        suprastatement 
    .
    .
    .

Comments:

SUPRA statements pass through the APS precompiler unchanged.
You must code a native SUPRA INCLUDE statement in the Working-Storage Section.
PASS can be substituted for SUPRA to get the same results.

SY* Keywords

Description:

Specify in a program the location where the generator places source code.

Syntax:

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYBT   source
 SYEN   source
 SYDD   source
 SYFD   source
 SYIO   source
 SYLT   source
 SYLK   source
 SYM1   source
 SYM2   source
 SYRP   source
 SYWS   source

Locations in Generated Code

Location	Keyword	Explanation
Top of program	SYM1	At the beginning of the program, before rule libraries that you include at the beginning of the program
	SYM2	After rule libraries that you include at the beginning of the program
Environment Division	SYEN	In the Environment Division, after the Special-Names paragraph
	SYIO	In the Input-Output Section, after rule libraries that you include at the beginning of the Input-Output Section
Data Division	SYDD	At the beginning of the Data Division
	SYFD	In the File Section, after rule libraries that you include at the beginning of the File Section
	SYWS	In the Working-Storage Section, after rule libraries and data structures that you include in Working-Storage
	SYLT	In the Linkage Section, after rule libraries and data structures that you include at the beginning of Linkage
	SYLK	In the Linkage Section, after source code that you include with the SYLT keyword
	SYRP	In the Report Section, after any rule libraries that you include at the beginning of the Report Section
Procedure Division	SYBT	At the end of the program

Comments:

The effect of a SY* keyword ends with the appearance of another keyword in the KYWD column.
The generation process shifts the source to start in column 8.

Examples:

Include a rule at the top of the program.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYM1   % INCLUDE USERMACS(MY-RULE)

Include a rule at the bottom of the program.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYBT   % INCLUDE USERMACS(MY-RULE)

Place a variable assignment statement at the top of the program.

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

Include a copybook in Working-Storage.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYWS   % INCLUDE COPYLIB(MY-COPYBOOK)

Include a copybook in Linkage.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 SYLK   % INCLUDE COPYLIB(MY-COPYBOOK)

System Service Calls

Category:

IMS system service calls

Compatibility:

IMS DB and IMS DC targets

Description:

Ensure successful recovery from error conditions. Monitor and control database services; define regular checkpoints from which you can request a service for the database and check for error conditions; perform error recovery from the last successful checkpoint status check.

Syntax:

IM-CHKP pcbname checkpointID
... [length1 dataarea1 [... length7 dataarea7
 
IM-XRST pcbname
... [length1 area1 [... length7 area7]]
... [checkpointID maxiolength]
IM-CHKP-OSVS pcbname checkpointID
IM-DEQ pcbname deqcharacter
IM-GSCD pcbname
IM-LOG pcbname logcode loglength message
IM-ROLB pcbname [msgarea]
IM-ROLL
IM-STAT-DBAS-FULL pcbname
IM-STAT-DBAS-UNFORMATED pcbname
IM-STAT-DBAS-SUMMARY pcbname
IM-STAT-VBAS-FULL pcbname
IM-STAT-VBAS-UNFORMATED pcbname
IM-STAT-VBAS-SUMMARY pcbname

Parameters:

checkpointid	An 8-character COBOL data name or a literal that specifies the ID for this checkpoint
dataarea	Name of the data area designated in Working-Storage
deqcharacter	A COBOL data name or single character literal string
length	Length of data area as defined in Working-Storage
logcode	A COBOL data name or literal character string containing a code that must be greater than or equal to X'A0' and less than or equal to X'E0'
loglength	Length of record, excluding the 5-byte header
maxiolength	Length of the largest program I/O area; can be variable or literal; default is the longest path call I/O area, or 0 if no path call exists
message	A COBOL data name or literal string
msgarea	Name of area in program where IMS returns the message segment being processed
pcbname	Database view; can be up to 20 characters; default is IO-PCB

Comments:

These calls generate Working-Storage areas as arguments.
For checkpoint/restart functions:
- These calls neither redefine the IMS facilities nor change the considerations for their use. Consult your appropriate IMS reference manuals for information.
- Checkpoint and restart are normally not applicable to online programs. This is because the database updates associated with processing an online message represent a single work unit, which executes for only a brief period of time.
- Batch and BMP programs may require this facility based on the expected duration of execution, number of database updates, and the potential for conflict with other concurrent processes.
- Checkpoint calls establish both an IMS commit point and a place where the program can be restarted. There are two types of checkpoints.
  Symbolic checkpoints can specify up to seven data areas in the program to checkpoint. The program restarts from the last checkpoint call issued, before the abend or from a specific checkpoint named in the restart call IM-XRST. APS restores checkpoint areas to the condition they were when the program abended.
  
  Basic checkpoints do not restart the program; you must provide your own logic. No data areas can be restored.
- Use IM-CHKP for both symbolic and basic checkpoint processing.
- Use IM-XRST for symbolic checkpoint and restart processing.
- IM-XRST is the first IMS call executed by the program. Next, the program should interrogate the IM-XRST-AREA field (generated by this macro). If the field is not equal to spaces, perform restart processing.
- A checkpoint cancels all database positioning. After a checkpoint or restart, the program must reestablish the database positioning with fully qualified DB-OBTAIN calls.
- In batch programs, the program needs the compatibility option available in its PSB (CMPAT=YES).
- Symbolic checkpoints do not support OS/VS files; basic checkpoints do not support OS/VS or GSAM files.

Example:

The following code is from an APS batch program using a symbolic checkpoint restart.

-KYWD-  12-*----20---*----30---*----40---*----50---*----60
 WS     CHKPT-WORKAREAS
            CHKPT-ID
                FILLERX4 V'CID1'
                CHKPT-ID-CTR    9(4) V 0
            CHKPT-LIMIT  S9(5) V 0 COMP-3
                88 CHKPT-LIMIT-REACHED    V+50
 WS     CHECKPOINT-AREA-1
            PREV-PART-NO X8  V LOW-VALUES
 NTRY
        IM-XRST IO 8 CHECKPOINT-AREA-1
        IF NOT IM-OK
            PERFORM ERROR-PARA
 /*     IF IM-XRST-AREA IS NOT BLANK,
 /*         PROGRAM IS BEING RESTARTED
        IF IM-XRST-AREA NOT = SPACES
            MOVE IM-XRST-CHECKPOINT TO CHKPT-ID
            TRUE RESTART
        ELSE
 /*         PERFORM FIRST CHECK POINT
            PERFORM SYMB-CHKPT-RTN
        REPEAT
            PERFORM READ-DB
        UNTIL END-ON-REC
            PERFORM PROCESS-DB-REC
 /*         INCREMENT COUNTER FOR EACH RECORD READ
            CHKPT-LIMIT = CHKPT-LIMIT + 1
            IF CHKPT-LIMIT-REACHED
                PERFORM SYMB-CHKPT-RTN
 PARA   SYMB-CHKPT-RTN
 /*     INCREMENT CHKPT-ID CNTR
        CHKPT-ID-CTR = CHKPT-ID-CTR + 1
        IM-CHKP IO CHKPT-ID
        ... 8 CHECKPOINT-AREA-1
        IF NOT IM-OK
            PERFORM ERROR-PARA
        CHKPT-LIMIT = 0

The following code:

$IM-CHKP ("IO", "'MYCHKP'", 25, "AREA-1",
% ... 37, "AREA-2")
$IM-CHKP ("IO", "MY-BASIC-CHKP-NAME")
$IM-XRST ("IO", 25, "AREA-1")

Generates in Working-Storage:

01  IM-CBLTDLI-ARGUMENTS.
    05  IM-CHKP   PIC X(4) VALUE 'CHKP'.
    05  IM-DEQ    PIC X(4) VALUE 'DEQ '.
    05  IM-LOG    PIC X(4) VALUE 'LOG '.
    05  IM-STAT   PIC X(4) VALUE 'STAT'.
    05  IM-XRST   PIC X(4) VALUE 'XRST'.
    05  OSVSCHKP  PIC X(8) VALUE'OSVSCHKP'.
    05  IM-CALL-FUNCTION    PIC X(4).
    05  IM-IO-AREA-LEN PIC S9(9) COMP VALUE +0.
    05  IM-IO-MAXAREA-LEN PIC S9(9) COMP VALUE +0.
    05  IM-LEN-25 PIC S9(9) COMP VALUE +25.
    05  IM-LEN-37 PIC S9(9) COMP VALUE +37.
01  IM-LOG-AREA.
    05  IM-LOG-LEN     PIC S9(4) COMP.
    05  FILLER    PIC S9(4) COMP VALUE +0.
    05  IM-LOG-CODE    PIC X.
    05  IM-LOG-RECORD  PIC X(55).
01  IM-DEQ-CHR   PIC X.
01  IM-XRST-AREA.
    05  IM-XRST-CHECKPOINT PIC X(8).
    05  FILLER    PIC X(4) VALUE SPACES.
01  IM-CHECKPOINT-ID   PIC X(8).
01  IM-STAT-FUNCTION.
    05  FILLER    PIC X(4).
    05  IM-STAT-FORMAT PIC X.
    05  FILLER    PIC X(4).
01  IM-STATISTICS  PIC X(120).

Generates in the Procedure Division:

MOVE 'MYCHKP'
... TO IM-CHECKPOINT-ID
IF IM-IO-MAXAREA-LEN < IM-IO-AREA-LEN
    MOVE IM-IO-AREA-LEN
... TO IM-IO-MAXAREA-LEN
CALL 'CBLTDLI' USING
... IM-CHKP IO-PCB
... IM-IO-MAXAREA-LEN
... IM-CHECKPOINT-ID
... IM-LEN-25 AREA-1
... IM-LEN-37 AREA-2
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
MOVE MY-BASIC-CHKP-NAME
... TO IM-CHECKPOINT-ID
CALL 'CBLTDLI' USING
... IM-CHKP IO-PCB
... IM-CHECKPOINT-ID
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
MOVE 'MYOSVSCP'
... TO IM-CHECKPOINT-ID
CALL 'CBLTDLI' USING
... IM-CHKP IO-PCB
... IM-CHECKPOINT-ID
... IM-OSVSCHKP
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
MOVE 'A' TO IM-DEQ-CHR
CALL 'CBLTDLI' USING
... IM-DEQ IO-PCB
...IM-DEQ-CHR
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
COMPUTE IM-LOG-LEN = 38 + 5
MOVE LOG-CODE-1 TO IM-LOG-CODE
MOVE LOG-MESSAGE-1
... TO IM-LOG-RECORD
CALL 'CBLTDLI' USING
... IM-LOG IO-PCB
... IO-LOG-AREA
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
COMPUTE IM-LOG-LEN = 55 + 5
MOVE LOG-CODE-2 TO IM-LOG-CODE
MOVE LOG-MESSAGE-2
... TO IM-LOG-RECORD
CALL 'CBLTDLI' USING
... IM-LOG IO-PCB
... IO-LOG-AREA
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
MOVE 'VBAS'
... TO IM-STAT-FUNCTION /* CLR TAIL
MOVE 'S' TO IM-STAT-FORMAT
CALL 'CBLTDLI' USING
... IM-STAT BE1PARTS-PCB
... IM-STATISTICS
... IM-STAT-FUNCTION
MOVE BE1PARTS-PCB-STATUS
... TO IM-STATUS
MOVE BE1PARTS-PCB
... TO IM-DB-PCB
MOVE SPACES
... TO IM-XRST-AREA
IF IM-IO-AREA-LEN > IM-IO-MAXAREA-LEN
    MOVE IM-IO-AREA-LEN
... TO IM-IO-MAXAREA-LEN
CALL 'CBLTDLI' USING
... IM-XRST IO-PCB
... IM-IO-AREA-LEN
... IM-XRST-AREA
... IM-LEN-25 AREA-1
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS

Description:

List of Structures:

Verbs

Conditionals

Error Handling

Flags

Looping

Transferring Program Control

Syntax Rules:

Example:

Related Topics:

Category:

Description:

Comment:

Example:

Category:

Description:

Comments:

Example:

Description:

Procedure:

Comments:

Examples:

Category:

Compatibility:

Description:

Syntax

CICS

IMS DC

ISPF Dialog

ISPF prototyping

Parameters:

Comments:

CICS

IMS DC

Examples:

CICS

IMS DC

ISPF Dialog

Category:

Description:

Syntax:

Comments:

Example:

Category:

Description:

Syntax:

Example:

Category:

Description:

Syntax:

CICS

ISPF Dialog

IMS DC

ISPF Prototyping

Parameters:

Comments:

ISPF Dialog

IMS DC

Examples:

CICS

DDS and DLG

IMS DC

Category:

Compatibility:

Description:

Syntax:

Keywords/Parameters:

Comments:

Example:

Compatibility

Description:

Comment:

Examples:

Category:

Purpose

Syntax

Example:

Category:

Compatibility: