Easytrieve SCREEN Statement

Statement Format

1
2
3
4
5
6
7
8
9
SCREEN [NAME screen-name] [COMMIT (...)] +
  [UPPERCASE] [ROWCOUNT rows] [LINESIZE columns] +
  [ROW screen-start-row] [COL screen-start-column] +
  [BACKGROUND ATTR attribute-name] +
  [BORDER {SINGLE|DOUBLE|WIDE|'literal'} [ATTR ...]] +
  [SHADOW]
 
  * Declaration section (DEFAULT first, then KEY/TITLE/ROW in any order)
  * Screen procedures (special-name and user-defined)

The SCREEN header names the activity, optionally sets commit and layout attributes, then introduces declaration statements and procedures. Broadcom structures a SCREEN activity as: SCREEN statement, screen declaration statements, then screen procedures. DEFAULTs must appear first in the declaration section; KEY, TITLE, and ROW declarations follow in any order. Procedures—including INITIATION, BEFORE-SCREEN, AFTER-SCREEN, TERMINATION, and your own PROC labels—may appear in any order after declarations, though teams usually group special-name hooks predictably for maintenance readability.

SCREEN Activity Structure

NAME Parameter

NAME screen-name optionally labels the activity for documentation and EXECUTE references. Screen-name may be up to 128 characters, can begin with A–Z, 0–9, or national characters (#, @, $), must not be all numeric, and may contain any non-delimiter character. A PROGRAM or another SCREEN activity EXECUTEs a named SCREEN when flow must jump to a specific transaction. Meaningful names like MAIN-MENU or EMP-INQUIRY help operators and auditors trace online design documents to source.

Layout and Presentation Options

ROWCOUNT and LINESIZE override the default terminal dimensions from the Site Options Table. On the mainframe each may range from 1 to 255. When the screen dimensions exceed the physical terminal, only a portion displays—test on representative terminal models in your shop. ROW and COL set the starting position of the screen on the display; defaults are row 1 and column 1. When LINESIZE and ROWCOUNT are less than the terminal size, Easytrieve displays the screen as a pop-up window. Fields from previous screens that remain visible receive ASKIP so operators cannot type into stale panels underneath the pop-up. In TSO and CMS, when the terminal supports two presentation sizes, Easytrieve picks presentation size from screen dimensions; pop-up sizing uses the larger of prior display size or pop-up size.

BORDER and BACKGROUND Attributes

BORDER draws a frame around the screen using SINGLE, DOUBLE, WIDE, or a one-character border literal in quotes. Optional ATTR on BORDER names a declared screen attribute or attribute keyword list for border color and intensity. BACKGROUND ATTR sets background presentation. Broadcom ignores CURSOR, NUMERIC, INVISIBLE, MUSTFILL, MUSTENTER, TRIGGER, and ALARM for BORDER—those apply to field-level ATTR, not the frame. DECLARE statement documentation lists attribute keywords your release supports; keep attribute names in Library or screen declaration sections consistent with shop standards.

Declaration Statements

After the SCREEN header, declaration statements describe what the operator sees. TITLE supplies a screen title string. ROW places literal text and fields at row/column coordinates—ROW 8 COL 10 'Option ===>' WS-REPLY VALUE ('V' 'E' 'D' 'X') shows allowed input values with ERROR message text when validation fails. KEY defines function keys: KEY F3 NAME 'Exit' EXIT terminates; KEY F1 NAME 'Help' IMMEDIATE processes without waiting for Enter. DEFAULT sets default attributes for fields unless overridden. Beginners should code DEFAULT before other declarations per Broadcom ordering rule even when samples interleave KEY and ROW for readability in manuals.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 DEFINE WS-REPLY  W 1 A
 SCREEN NAME MAIN-MENU
 
   TITLE 'Employee File Main Menu'
   ROW  6 COL 10 'Type an option, then press Enter.'
   ROW  8 COL 10 'Option ===>' WS-REPLY VALUE ('V' 'E' 'D' 'X') +
                     ERROR 'Please type V, E, D, or X'
   ROW 10 COL 22 'V View employee'
   ROW    COL 22 'E Edit employee'
   ROW    COL 22 'D Delete employee'
   ROW    COL 22 'X Exit'
   KEY F1  NAME 'Help' IMMEDIATE
   KEY F3  NAME 'Exit' EXIT
   KEY F12 NAME 'Cancel' EXIT IMMEDIATE

How SCREEN Activities Start and End

SCREEN activities execute when a PROGRAM or another SCREEN issues EXECUTE, or when no PROGRAM exists and the first SCREEN in source order is automatically executed. Processing continues until EXIT, STOP, or TRANSFER runs—Broadcom compiles an error if none of these appear, because an endless screen loop would strand operators. Use EXIT for normal screen activity termination (analogous to polite good-bye). STOP ends the current activity and may run FINISH-style cleanup depending on context. TRANSFER passes control per online runtime rules. Do not confuse EXIT (screen-normal end) with STOP EXECUTE (abnormal halt of all Easytrieve execution).

COMMIT on SCREEN

COMMIT on SCREEN controls recoverable work units—database updates, held records, SQL cursors. ACTIVITY commits at normal activity termination; NOACTIVITY (default) skips end-of-activity commit. TERMINAL commits during terminal I/O; on CICS this enables pseudo-conversational mode. NOTERMINAL suppresses commit on each terminal I/O. If a parent activity specified NOTERMINAL, child SCREEN activities perform terminal I/O as if NOTERMINAL applied. You may also code explicit COMMIT and ROLLBACK for controlled units of work inside procedures when shop standards require finer granularity than defaults.

SCREEN Versus JOB

JOB activities loop on file records with automatic INPUT. SCREEN activities respond to operator events—each key press or Enter may trigger a cycle through BEFORE-SCREEN, display, and AFTER-SCREEN. JOB produces batch reports and extracts on a schedule; SCREEN presents panels during business hours. Both share Library FILE and DEFINE definitions. A common pattern: SCREEN gathers approval, updates a master file online, then EXECUTE a named JOB that PRINTs the formatted report using existing REPORT definitions.

Screen Procedures Inside SCREEN

Special-name procedures bracket runtime events: INITIATION once at activity start, BEFORE-SCREEN before each terminal send, AFTER-SCREEN after input, TERMINATION at activity end. User-defined PROC names modularize validation shared across multiple ROW layouts. Broadcom forbids certain statements inside specific procedures—GOTO SCREEN in BEFORE-SCREEN, for example. Place procedures after executable screen logic or interleave per team standards; the compiler accepts any order among procedures but readability suffers when hooks are scattered far from related ROW declarations.

Testing SCREEN Programs

1. Verify compile enforces EXIT, STOP, or TRANSFER somewhere in the activity.
2. Walk each KEY path—EXIT, IMMEDIATE, and normal Enter processing.
3. Test pop-up ROWCOUNT/LINESIZE smaller than terminal; confirm ASKIP on underlying fields.
4. Validate UPPERCASE when shop expects forced upper-case keys without changing literals.
5. EXECUTE batch JOB from SCREEN in test region; confirm spool and file updates.

Common SCREEN Mistakes

• Missing EXIT/STOP/TRANSFER—compile failure.
• Coding SCREEN logic in batch-only environments without Online runtime.
• Validation in BEFORE-SCREEN before operator input exists—belongs in AFTER-SCREEN.
• Ignoring COMMIT defaults on CICS—unexpected commit frequency or held locks.
• ROW coordinates overlapping—fields overwrite each other on display.
• Expecting implied PROGRAM to run JOB after SCREEN without EXECUTE.

Explain It Like I'm Five

SCREEN is like opening a new chapter in a choose-your-own-adventure book for the computer screen. The SCREEN line is the chapter title and frame size. TITLE and ROW sentences draw the pictures and blanks on the page. KEY lines are the special buttons at the bottom—Exit, Help, Forward. The computer keeps showing this chapter until you write an ending sentence called EXIT or STOP. BEFORE-SCREEN and AFTER-SCREEN are little helpers that get the page ready before the person looks and check answers after the person types.

Exercises

1. Write a SCREEN NAME header with TITLE and two ROW lines plus F3 EXIT KEY.
2. List four SCREEN header options and what each changes for the operator.
3. Explain when a screen becomes a pop-up window.
4. Contrast EXIT and STOP for ending a SCREEN activity.
5. Sketch SCREEN EXECUTE JOB flow for online approval then batch report.