Full-screen feature

Overview

The Model 204 full-screen feature provides data entry capability invoked through User Language. The full-screen feature allows the entire screen of a video display terminal (an IBM 3270) to be formatted, displayed, and accepted as a single entity, rather than field by field.

User Language also supports line-at-a-time screen handling, which is described in this topic.

Menus and screens

The full-screen feature provides two major capabilities:

Capability	Displays...
Menu	Options or programs that can be selected by a terminal operator.
Screen	Information for inquiry or updating purposes. Screens frequently are used for data entry applications in which a terminal operator views a formatted screen and enters data in response to specific prompts. The application then validates the entered data, flags errors, and prompts for corrections.

You can define and manipulate each display type in a User Language request.

Most statements used with screens also apply to menus, with some minor differences. The first part of this topic discusses menu definition and manipulation, and the second part discusses screen definition and manipulation.

LFSCB parameter setting

The system manager sets the LFSCB parameter (size of full-screen buffer) during system initialization, or the user sets the LFSCB parameter Online with the UTABLE command.

Maximum number of screens and menus

The maximum number of screens and menus combined per request is 256 (version 7.6 and earlier) or 4095 (version 7.7 and later).

Global screens and menus

Global screens and menus provide a means for passing screen and menu data from one request to another, and for efficiently managing more than one screen or menu in one request.

Although there are some differences in the way you use the DECLARE SCREEN and DECLARE MENU statements, you generally define global screens and menus in the same way as non-global screens and menus. See Global images and screens for a discussion.

This topic describes these statements for global and non-global screens:

• DECLARE MENU
• DECLARE SCREEN
• MODIFY
• PREPARE

Screen and menu formatting

The full-screen feature specifies:

• Where screen items are to appear on the video display terminal
• How screen items are displayed (for example, highlighted and/or in color)

Screen and menu items

Screens and menus can include:

• Title (name of the screen or menu)
• Prompts
• Input areas (for screens only)

Screen and menu definition

Screen and menu definitions begin with a SCREEN or MENU statement, respectively, and end with a corresponding END SCREEN or END MENU statement. The screen or menu definition is made up a series of statements that define the screen/menu components: title, prompt(s), and input area(s).

Screen and menu manipulation

User Language provides a number of statements that read previously defined screens and then accepting input items from the terminal operator. You can also use screen manipulation statements to redisplay corrected screens, restore previous default values for screen items, and flag incorrect values.

Full-screen variables

Full-screen application design normally requires the use of special variables:

• Menu and screen variables — Refer to titles, prompts, and input items.
• Reserved variables — Have special meaning to Model 204; used to perform special functions.
• Screen item name variables — Refer indirectly to screen items.

Full-screen processing

To design data entry applications using the full-screen feature, you must accommodate the sequence of events that normally occurs during a data entry session.

Menu displayed

The application request normally begins the application by displaying a menu to the terminal operator. A menu typically contains a title and formatted prompting information. For example:

EMPLOYEE MENU 1 ADD EMPLOYEE 2 CHANGE ADDRESS 3 CHANGE INSURANCE 4 ADD DEPENDENT

Operator interaction with menu

The operator (application end user) selects a menu option by indicating the appropriate option number with a Program Function (PF) key or by tabbing to the desired selection number (using →, ←, or ↵) and pressing the ENTER key. Control is then transferred to the selected option's program. The operator is reprompted if the cursor is not positioned correctly.

Screen displayed

The screen for the selected option is then displayed. A screen typically contains a title, formatted prompting information, and areas in which the user can enter data. For example:

EMPLOYEE ADD SCREEN FILL IN THE FOLLOWING INFORMATION FOR EACH NEW EMPLOYEE NAME: STREET: CITY: STATE: ZIP: AGE: SEX: SSN:

In this example, each prompt is followed by an input area in which data can be entered. Titles and prompts are protected and cannot be modified by the operator.

The operator presses the tab key on the terminal to move between input areas, filling in data. The operator can tab backward or forward on the screen, entering data. The input areas can be filled in any order, and can be corrected if erroneous data is entered, as long as the screen has not been transmitted. When data entry for the screen is completed, the operator presses the Enter key or a PF key to transmit the data to Model 204.

Input validation

The input entered at the terminal is then validated according to criteria specified in the application request. Two types of validation can be performed:

Type of validation	Request can specify...
Automatic	Validation criteria (for example, the response must be all-numeric) using special full-screen options.
Manual	Statements that check for errors in terminal responses (for example, statements that verify that an input code matches a code in a particular record).

Items that do not pass the validation criteria are tagged with an error indicator. If the screen is redisplayed for correction, the error indicator appears in column 80 of the line containing the error. An example of a screen redisplayed for correction is shown below.

EMPLOYEE ADD SCREEN REENTER VALUES MARKED WITH * NAME: JOE SMITH STREET: 87 OAK DRIVE CITY: NORFOLK STATE: VA ZIP: 501B3 * AGE:14 * SEX: M SSN: 042-54-9803

The terminal operator can then correct the items in error and press Enter when all corrections have been made. This cycle is repeated until all items on the screen pass the validation criteria. Control is then returned to the request to continue processing.

Application display considerations

Prior to application design, you should be familiar with the following aspects of the full-screen feature and the terminal display area:

• Positions on the video screen, often described as layout
• Terminal display attributes for color and light intensity

Screen display area

The typical 3270-type video display terminal consists of 24 rows of 80 columns. Every screen position, except the system-reserved positions specified below, can be used for menus and screens.

Position	Is reserved for...
Column 1 (the leftmost column)	Internal system use.
Columns 2 through 4	System-generated menu selection numbers when menus are displayed. These columns are not reserved for menu titles or for screen use.
Column 80, the rightmost column	Error indicators when user-defined screens are displayed. This column is not reserved for menu use.
Line 1, the top row on the screen	Screen and menu titles that can be specified by the user.
Last line, the bottom row on the screen, usually row 24	Model 204 backpaging feature. Backpaging allows the terminal operator to review previous pages of output.

Display attributes

The following basic display attributes available on 3270-type terminals can be used within a full-screen application design. Required letters are capitalized; Invisible has two variations:

VISible INVisible INVISible UNPROTected PROTected BRIGHT DIM

Extended display attributes

In addition, extended display attributes available on some 3278 and 3279-type terminals can be used within an application to alert the terminal operator to areas of the display and error conditions. To use extended attributes, the FSOUTPUT parameter must be set.

Extended attributes are a combination of display attributes selected from the categories listed below. Abbreviations are capitalized. Consult the appropriate hardware support person within your installation to determine if extended attributes are supported.

Highlighting attributes

NOUnderSCORE NOBLINK NOREVerse UnderSCORE BLINK REVerse

Color attributes

BLUE TURQuoise GREEN WHITE PINK YELLOW RED

How display colors are assigned

3270-type display devices — both actual 3278 and 3279 terminals, and terminal emulators — operate according to a protocol defined by IBM. Display devices operate in either base-color or extended-color mode. Each time a screen is displayed, one of these modes is selected for display.

If Model 204 displays a screen with...	Then 3270 selects...
No fields with a color attribute set	Base-color mode
Any field with a color attribute set	Extended-color mode

Base-color mode attribute assignments

In base-color mode, fields have no color explicitly specified. The display color is determined by whether the field is DIM or BRIGHT and whether the field is PROTECTED or UNPROTECTED, as follows:

Color attributes	Color displayed	Default color for...
DIM, PROTECTED	BLUE	TITLE and PROMPT fields
DIM, UNPROTECTED	GREEN	INPUT fields
BRIGHT, PROTECTED	WHITE	N/A
BRIGHT, UNPROTECTED	RED	TAG fields

Extended-color mode attribute assignments

In extended-color mode, each screen field has a color associated with it. If a field does not have a color explicitly specified, the field is displayed, as follows:

Color attributes	Color displayed	Default color for...
DIM	GREEN	TITLE, PROMPT and INPUT fields
BRIGHT	WHITE	TAG fields

Note: The display of a field without a specified color might be altered if a change to extended-color mode is triggered by the modification of some other field in the screen.

Most terminal emulators provide a mechanism to modify color mappings. Any change to the color mapping using this mechanism is local, and is not reported to Model 204.

Consult the following IBM manuals for additional screen display information:

Part no.	IBM Title
GA23-0059	3270 Data Stream Programmer's Reference
GA23-0218	3174 Establishment Controller - Functional Description

Display attribute rules and restrictions

You should be aware of these rules and restrictions when specifying display attributes:

• The INVISIBLE attribute overrides all other display attributes.
• A color attribute overrides the BRIGHT and DIM attributes.
• Color and highlighting attributes can be mixed.
• Color attributes cannot be mixed together.
• Highlighting attributes cannot be mixed together.
• The PROTECTED attribute implies an autoskip. Autoskip causes a screen item to be skipped by the forward and backward tab keys.

Full-screen variables

Types of variables used

Full-screen application design normally requires the use of special types of variables.

Type of variable	Refers to...
Menu and screen	Titles, prompts, and input items
Reserved	Special meaning to Model 204 and are used to perform special functions
Screen item name	Screen items, indirectly

Menu and screen variables

Every input item area on a screen must have a name. Optionally, a menu, screen title, or prompt also can have a name to which a value is assigned before the menu or screen is displayed.The name must be unique within a particular screen or menu definition. However, the same name can be used on multiple screens or menus.

To avoid the confusion of duplicate names for different menus and screens (for example, a NAME item on an EMPLOYEE screen and a NAME item on a CREDITOR screen), you must refer to a screen or menu name using the following formats:

• Titles and prompts — Named titles or prompts on menus and screens are referenced in the following format:

  %menuname:promptname

  or

  %screenname:promptname

  Values for named titles or prompts are specified by an assignment statement of the following format:

  %menuname:promptname = value

  or:

  %screenname:promptname = value

  For example, this statement:

  %EMPLOYEE:PNAME = 'ENTER NAME:'

  assigns the text string, ENTER NAME:, as the value of the prompt PNAME on the EMPLOYEE screen.

• Input items — Input items entered on screens are referenced in the following format:

  %screenname:inputname

  For example, this statement identifies the input item INNAME entered on the EMPLOYEE screen:

  %EMPLOYEE:INNAME

Reserved variables

Model 204 provides the following reserved variables for storing values entered by the terminal operator:

Reserved variable	Stores...
%menuname:SELECTION	Menu selection number entered by a PF key or by tabbing to the desired selection number and pressing ENTER. The value stored in %menuname:SELECTION can be used: Directly in either an arithmetic expression or a computed JUMP statement As the target of an assignment statement to specify the initial cursor position for the next menu display
%screenname:PFKEY	Value of the PF key number entered by the terminal operator for a screen. If the terminal operator presses the ENTER key, a zero is returned in %screenname:PFKEY. You can use the value stored in %screenname:PFKEY to select the next group of statements to be executed. Typically, this is accomplished with a series of IF statements or a computed JUMP statement.

Screen item name variables

Screen item name variables refer indirectly to screen item names, thereby allowing portions of a request, such as subroutines, to be generalized. A screen item name variable is indicated in the following format:

:%screen-item-name

During the evaluation of a request, a string value can be assigned to a %variable, as illustrated below:

%SCRVAR = 'SCREEN:AGE'

and that %variable can then be used in statements where screen item names normally appear.

For example, to tag the screen item AGE, enter:

TAG :%SCRVAR

A screen item name variable and a menu or screen variable are actually the same variable.

Defining menus

Use menu statements to define and format menus. Formatting involves specifying a title and all prompts to be displayed on the screen. A menu definition must be included in the User Language request for every menu to be displayed by that request.

Each menu statement must begin with Menu and end with End Menu. In between, you specify a series of menulines that describe the titles, prompts, and blank lines to appear on the menu.

Menu statement syntax

The formats of the Menu block and statement are:

Menu block:

[Declare] Menu menuName [Global [Permanent | Temporary] | Common] menuLine menuLine ... End Menu

Menu statement, referring to a menu defined elsewhere in a Menu block:

[Declare] Menu menuName [Global [Permanent | Temporary] | Common]

Where:

• menuName is a user-defined string from 1 to 255 characters in length. Every menu name defined in a request must be unique. The menu name specified in the Menu statement is assigned to the menu being defined; it subsequently can be referenced in menu manipulation statements.
• Declare and Common specify that the menu is a common element in the request. Specifying Common (or specifying neither Common nor Global) results in the menu being stored in the default area (the FSCB) rather than in GTBL. Common elements, as well as Declare and Common, are discussed in detail in Sharing common elements.
• Global specifies that the menu is stored in GTBL. Global menus have an implied scope of Common (see above).

  Note: Do not specify the Global attribute for multi-page (logical pages) menus.

• Permanent (Perm) can only be used with global menus. Perm global menus persist across request boundaries (they are maintained in GTBL even after a request has been terminated).
• Temporary (Temp) can only be used with global menus. Temp global menus are allocated in GTBL, but are deleted at request termination. An example of using a Temp global menu would be when you do not need to pass the menu to another request; using Temp global menus eliminates the need for you to explicitly delete globals that do not need to persist.
• The number of menulines must not exceed 23 lines.

• A menuLine is one of the statements listed below:

  Statement	Description
  Title	Specifies the menu title.
  Prompt	Defines a particular menu option.
  Skip	Skips one or more lines on the screen.
  Max PFKey	Specifies the maximum PF key value associated with a menu.

• Comments and blank lines included in a menu statement are ignored by Model 204.
• Every menu definition must terminate with End Menu.

TITLE statement for menus

The Title statement specifies a character string that is displayed as the menu title on the first line of the screen.

If a Title statement is not defined in a menu definition, a menu title can be specified when the menu is displayed (see READ MENU statement). If no title is specified, this system menu title is displayed:

INDICATE NUMBER FOR DESIRED SELECTION

Syntax

A Title statement must be the first menuline of a menu definition. The format of the Title statement is:

Title {'text' | promptname} [At [Column] n] [To [Column] m | [Len m] [Dp {k | *}]] [Default 'value'] [[Read] attributes] [Reread attributes] [Print attributes]

Where:

• text is a character string enclosed in single quotes with a maximum length of 79 characters. If the string exceeds 79 characters, a compilation error occurs.
• promptname is a menu variable to which a value can be assigned before the menu is displayed with the Read Menu or Print Menu statement.

Location options

• Location options (optional) are listed and described in the following table:

  Option	Specifies...
  At n	Where the title is to begin on the screen.
  To m	Column where the title is to end.
  Len m	Length of a title beginning at the n specified in the AT option. If a menu variable is used to supply the title, and you do not specify a length, the default length is the remainder of the line.
  Dp k or Dp *	Number of decimal places displayed in a title. Dp k displays k decimal places for the title. Any additional decimal places are truncated. Dp * displays all decimal places.

• Column keyword (optional). An n value of 1 automatically is converted to 2, because a title cannot begin in the reserved first column. If the At option is not included in the Title statement, the title begins at column 2.

  If the difference between the At and To specifications or the Len specification is less than the length of the string, the string is truncated. If the specified length exceeds the length of the string, spaces are used to pad the end of the title. Note that the title string is not right-justified at the column indicated by the To specification. This Title statement indicates that the text string within single quotes is to be displayed, beginning in column 13:

  TITLE 'EMPLOYEE MENU' AT COLUMN 13

• Default lets you provide a default literal value for a named title. The value must be enclosed in single quotes. This option eliminates the need to use an assignment statement to set the initial value of a Title variable.
• Read selects the display attributes for the title on execution of a Read statement. The default display attributes for a title are Protected, Dim, and Visible.

  Note: The Unprotected attribute is not allowed in a title. Specifying the Unprotected attribute results in an error message.

• Print selects the display attributes for the title on execution of a Print statement. If no Print option is specified, the Read attributes are used during Print.

PROMPT statement for menus

The Prompt statement specifies a text string for each menu selection option. You supply the text for each prompt and Model 204 automatically generates the selection number to accompany each prompt.

The menu selection number is displayed at columns 2 and 3. The numbers are assigned in sequence, beginning with 1, and incremented by one for each additional prompt.

Syntax

The syntax for the Prompt statement is:

Prompt {'text' | promptname} [At [Column] n] [To [Column] m | [Len m] [Dp {k | *}]] [Default 'value'] [[Read] attributes] [Reread attributes] [Print attributes] [Itemid n]

Where:

• text is a character string enclosed in single quotes with a maximum length of 76 characters.
• promptname is a menu variable to which a value is assigned before the menu is displayed with the Read Menu or Print Menu statement.
• Location options (optional) listed in the following table specify the position of a prompt on the screen.

  Option	Specifies...
  At n	Where the title is to begin on the screen.
  To m	Column where the title is to end.
  Len m	Length of a title beginning at the n specified in the AT option. If a menu variable is used to supply the title, and you do not specify a length, the default length is the remainder of the line.
  Dp k or Dp *	Number of decimal places displayed in a title. Dp k displays k decimal places for the title. Any additional decimal places are truncated. Dp * displays all decimal places.

• Column (optional). If an AT option is not specified in a Prompt statement, the prompt begins at column 5. If an At option is specified, the prompt begins at the position indicated by n. A prompt cannot start before column 5. If the difference between the At and To specifications or the Len specification is less than the length of the string, the string is truncated. If the specified length exceeds the length of the string, spaces are used to pad the end of the prompt.

  Note: The prompt string is not right-justified at the column indicated by the To specification.

• Default lets you provide a default literal value for a named prompt. The value must be enclosed in single quotes. This option eliminates the need to use an assignment statement to set the initial value of a Prompt variable.
• Read selects the display attributes for the item on execution of a Read statement. The default display attributes for prompts are Protected, Dim, and Visible.

  Note: You incur an error message if you use an Unprotected attribute in a prompt.

• Print selects the display attributes for the item on execution of a Print statement. If no Print option is specified, the Read attributes are used during Print.

Usage

Normally, each Prompt statement starts a new line of text on the screen. However, multiple-line prompts can be handled by repeating text or promptname for a single Prompt statement. An example of this is shown below.

PROMPT 'EMPLOYEE ADD' AT 10 '(NEW PERSONNEL ONLY)' AT 10

This produces the following output:

1 EMPLOYEE ADD (NEW PERSONNEL ONLY)

SKIP statement for menus

The Skip statement passes over one or more lines on the screen between menu options. Do not exceed the total number of lines on a screen when using Skip. Skipping beyond 23 lines is not allowed.

Syntax

The syntax for the Skip statement is:

Skip n Line[s]

where n is a positive integer that specifies the number of lines to be left blank on the screen. For example:

SKIP 2 LINES

causes two blank lines before the next menu line.

The Skip %variable Line(s) option is not supported for this application of the Skip statement.

MAX PFKEY statement for menus

The Max PFKey statement specifies the maximum PF-key value associated with a particular menu.

If a Max PFKey statement is present and the terminal operator presses a PF key with a value greater than n in response to a Read or Print Menu statement, the PF key value is divided by n. If the PF key value is evenly divided by n, n is returned to %menuname:SELECTION. If the PF key value is not evenly divided by n, the value of the remainder is returned to %menuname:SELECTION. For example, if Max PFKey 12 is specified, Model 204 returns PF13 through PF24 as PF1 through PF12.

Syntax

The syntax for the Max PFKey statement is:

Max PFKey n

where n is a number from 1 to 255. If n exceeds 255, a default value of 255 is used. The statement can appear anywhere in the menu definition after the title line. Only one Max PFKey statement is allowed for each menu definition.

Menu definition example

In this example, the user defines the format of the EMPLOYEE MENU selection screen:

MENU PERSONNEL TITLE 'EMPLOYEE MENU' AT 13 BRIGHT MAX PFKEY 12 SKIP 2 LINES PROMPT 'NEW EMPLOYEE ADD' AT 10 PROMPT 'EMPLOYEE UPDATE' AT 10 PROMPT 'EMPLOYEE INQUIRY' AT 10 PROMPT 'EMPLOYEE DELETE' AT 10 PROMPT 'YTD EARNINGS INQUIRY' AT 10 PROMPT 'INSURANCE INQUIRY' AT 10 PROMPT 'DONE' AT 10 END MENU

The preceding statements result in a menu in the format shown below when displayed by the request.

Sample menu created by menu statements

EMPLOYEE MENU 1 NEW EMPLOYEE ADD 2 EMPLOYEE UPDATE 3 EMPLOYEE INQUIRY 4 EMPLOYEE DELETE 5 YTD EARNINGS INQUIRY 6 INSURANCE INQUIRY 7 DONE

Menu manipulation

Menu manipulation involves reading a previously defined menu and then accepting input items from the terminal operator.

Menu manipulation statements

You can initialize and display a menu and accept a response from the terminal operator. You can specify these statements anywhere in the SOUL request, except within a menu or screen definition.

Menus are manipulated using the following statements:

Statement	Displays...
Modify	Changed attributes of a menu item during request execution.
Prepare Menu	Reinitialized menu.
Print Menu	Menu on a terminal or as USE output.
Read Menu	Menu and accepts a response from the terminal operator.

An example program using these statements is described in Menu manipulation example.

READ MENU statement

The Read Menu statement lets you display a defined menu on the screen and accept user selections from that menu. When the menu is displayed, the cursor automatically is positioned under the first menu selection number.

Syntax

The syntax for the Read Menu statement is:

Read [Menu] menuname [Alert] [Title {'text' | %variable} [At [Column] n] [To [Column] m | Len m] [attributes]]

Where:

• menuname refers to a menu previously defined by a set of menu definition statements.
• Alert sounds the audible alarm on the terminal when the menu is displayed.Alert is ignored and no warning is issued if the terminal is not equipped with an alarm.
• Title specifies a new title to override the menu title specified in the AlertTitle statement of the original menu definition. This new title is effective only for the current Read statement. The title specified in this option can be either a character string ('text') or a variable that has been set to a string before the Read Menu statement is executed.

AT, TO, LEN, and attributes options for READ MENU

The At, To, Len, and attributes options are identical to those described in TITLE statement for menus. If these options are omitted, the At, To, Len, and attributes options defined for the title in the menu definition are used.

PRINT MENU statement

The Print Menu statement lets you display a menu on a terminal or as USE output with all menu items protected.

When the Print Menu statement is evaluated, and output is to an IBM 3270 or compatible terminal, the menu is displayed as it normally would appear during a Read except that the tab keys are ineffective. The terminal operator presses the Enter key or a PF key to complete the operation of the Print. The key that the operator pressed is returned to the request.

Syntax

The syntax for the Print Menu statement is:

Print [Menu] menuname [Alert] [Title {'text' | %variable} [At [Column] n] [To [Column] m | Len m] [attributes]]

Where:

The Alert, Title, At, To, Len, and attributes options are identical in TITLE statement for menus.

MODIFY and PREPARE MENU statements

MODIFY statement

The Modify statement changes the display attributes of a menu item during the execution of a SOUL request.

A Modify statement changes only those attributes that you wish to change (for example, from Visible to Invisible); the statement leaves other attributes unchanged. If All is specified or the For clause is omitted, the new attributes apply to both Read and Print.

Syntax

The syntax for the Modify statement is:

Modify %menuname:itemname [To] attributes [All | [For] Read | Prints]

Usage notes

Consider the following when using the Modify statement:

• The Unprotected attribute is not allowed for titles and prompts.
• The Prepare menu statement restores display attributes to their original state.

PREPARE statement

The Prepare statement reinitializes a menu. Prepare can be issued at any point in a request to restore values that were altered by assignment and Modify statements. The Prepare statement restores:

• A cursor that was moved to select a menu option back to its original position
• Specified default values (those indicated by Default options) to the title and prompts
• Null values to prompts specified with variable prompt names that do not have default values
• Original display attributes if the attributes were overridden by Modify statements

Syntax

The syntax for the Prepare statement is:

Prepare [Menu] menuname

Where:

menuname refers to a menu previously described by a set of menu definition statements.

Use with global menus

Defining a menu as global affects the order in which you should issue Prepare statements. See Clearing the GTBL work area for a discussion of performance considerations related to declaring and clearing global objects from GTBL.

Menu manipulation example

In this example, the user defines a procedure that prompts the terminal operator for the next function to be performed, sets a global variable, SELECTION, with the user's response, and uses the conditional include capability to include the appropriate procedure.

PROCEDURE PERSONNEL.APPLICATION BEGIN MENU PERSONNEL TITLE 'EMPLOYEE MENU' AT 13 BRIGHT MAX PFKEY 12 SKIP 2 LINES PROMPT 'NEW EMPLOYEE ADD' AT 10 PROMPT 'EMPLOYEE UPDATE' AT 10 PROMPT 'EMPLOYEE INQUIRY' AT 10 PROMPT 'EMPLOYEE DELETE' AT 10 PROMPT 'YTD EARNINGS INQUIRY' AT 10 PROMPT 'INSURANCE INQUIRY' AT 10 PROMPT 'DONE' AT 10 END MENU READ MENU PERSONNEL IF $SETG ('SELECTION',%PERSONNEL:SELECTION) THEN PRINT 'GLOBAL TABLE FULL' END IF END IF SELECTION=1,ADD.EMPLOYEE IF SELECTION=2,UPDATE.EMPLOYEE IF SELECTION=3,INQUIRE.EMPLOYEE IF SELECTION=4,DELETE.EMPLOYEE IF SELECTION=5,INQUIRE.EARNINGS IF SELECTION=6,INQUIRE.INSURANCE IF SELECTION=7,CLEANUP.EMPLOYEE END PROCEDURE

Defining screens

The Screen block is used to define and format a screen. Formatting involves specifying a title and all prompts to be displayed on the screen, and describing input items to be entered by the terminal operator.

The Screen block must begin with Screen and end with End Screen. In between, you specify a series of screenLines that describe the titles, prompts, input areas, and blank lines to appear on the screen.

You must include a Screen block in a SOUL request for every screen to be displayed by that request.

You can also use the Screen statement to define a Common name for a screen defined in an earlier Screen block.

Screen block and statement syntax

The syntax of the Screen block and statement is:

Screen block:

[Declare] Screen screenName [Global [Permanent | Temporary] | Common] screenLine screenLine ... End Screen

Screen statement, referring to a screen defined earlier in a Screen block:

[Declare] Screen screenName Common

Where:

• screenName is a user-defined string from 1 to 255 characters in length. Every screen name defined in a request must be unique. The screen name specified in the Screen statement is assigned to the screen being defined; it subsequently can be referenced in screen manipulation statements.
• Declare and Common are used if the screen is a common element in the request. Specifying Common (or specifying neither Common nor Global) results in the screen being stored in the default area (the FSCB) rather than in GTBL. Common elements, as well as Declare and Common, are discussed in detail in Sharing common elements.
• Global specifies that the screen is stored in GTBL. Global menus have an implied scope of Common (see above).

  Note: Do not specify the Global attribute for multi-page (logical pages) screens.

• Permanent (Perm) can only be used with global screens. Perm global screens persist across request boundaries (they are maintained in GTBL even after a request has been terminated).
• Temporary (Temp) can only be used with global screens. Temp global screens are allocated in GTBL, but they are deleted at request termination. You might use a Temp global screen when you do not need to pass the screen to another request; using Temp global screens eliminates the need to explicitly delete globals that do not need to persist.
• You can include any number of screen lines in a screen definition.

  Each screen line normally corresponds to a single line on the physical panel. The SOUL compiler regards a screenLine as a logical input line. If a screen line is longer than a single request input line, use a hyphen for continuation.

• A screenLine can be one of the following:

  Statement	Description
  Default	Specifies the various screen item defaults.
  Include	Includes a stored procedure within a screen definition.
  Input	Describes an input item entered by the terminal operator.
  Max PFKey	Specifies the maximum PF key value associated with a menu.
  Prompt	Defines a particular text prompt.
  Skip	Skips one or more lines on the screen.
  Title	Specifies the screen title.

• Comments or blank lines included in a screen definition (between Screen and End Screen) are ignored by Model 204.
• Every screen statement must end with End Screen, which terminates the definition of the screen.

Logical and physical panels

The screen actually displayed to the terminal operator depends on the logical panel and physical panel.

Logical screen

A logical screen (panel) is that part of the logical screen definition which is ended by a New Page or by an End Screen statement. These statements control where the display screen is to end.

Physical screen

A physical screen (panel) is the part of the logical panel that fits on the user's physical terminal as determined by the MODEL parameter. The full-screen formatting feature defines screens independently of the terminal operator's 3270 terminal model; the correct length is displayed when the request is evaluated.

If the prompts and/or input items specified in a screen definition exceed the number of lines available on a physical panel, Model 204 automatically constructs an overflow panel for the remaining lines. The overflow panel has the same title as the original screen.

TITLE and PROMPT statements for screens

TITLE statement

The TITLE statement specifies a character string to be displayed as the screen title on the first line of the screen.

If you do not specify a TITLE statement

If a TITLE statement is not defined in a menu definition, a menu title can be specified when the menu is displayed (see the section titled READ SCREEN statement). If no title is specified, the following system menu title is displayed:

INDICATE NUMBER FOR DESIRED SELECTION

Syntax

If a you specify a TITLE statement, the statement must be the first menuline defined in a menu definition. The format of the TITLE statement is:

TITLE {'text' | promptname} [AT [COLUMN] n] [TO [COLUMN] m | [LEN m] [DP {k | *}]] [DEFAULT 'value'] [[READ] attributes] [REREAD attributes] [PRINT attributes]

Where:

• text is a character string enclosed in single quotes with a maximum length of 79 characters.
• promptname is a screen variable to which a value can be assigned before the screen is displayed with the READ SCREEN, REREAD SCREEN, or PRINT SCREEN statement.
• REREAD selects the display attributes for the title on execution of a REREAD statement. If no REREAD option is specified, the READ attributes are used during REREAD.
• The other options for the TITLE statement used with screens are the same as the options described in TITLE statement for menus.

PROMPT statement

The PROMPT statement specifies the text to be displayed as a prompt for the terminal operator. A prompt usually asks the operator to enter a particular data value.

Syntax

The syntax for the PROMPT statement is:

PROMPT {'text' | promptname} [AT [COLUMN] n] [AT [COLUMN] m | [LEN m] [DP {k | *}]] [DEFAULT 'value'] [[READ] attributes] [REREAD attributes] [PRINT attributes] [ITEMID n]

Where:

• text is a character string in single quotes; use up to 78 characters.
• promptname is a screen variable to which a value can be assigned before the screen is displayed with the READ SCREEN, REREAD SCREEN, or PRINT SCREEN statement.

  Note: Each prompt can start a new line of text on the screen or multiple prompts can be defined for one screenline. However, each prompt must occupy its own position on a screenline.

• REREAD selects the display attributes for the prompt on execution of a REREAD statement. If no REREAD option is specified, the READ attributes are used during REREAD.
• ITEMID assigns a number from 1 to 32767 to a prompt. This number is used for reference by the cursor variable %screenname:ITEMID. For more information about %screenname:ITEMID, refer to the section titled Cursor handling.
• The other options for the PROMPT statement used with screens are the same as the options for the PROMPT statement used with menus, as described in PROMPT statement for menus.

INPUT statement

The INPUT statement defines the characteristics of an input value to be entered by the terminal operator, usually in response to a prompt. An INPUT statement typically is defined in conjunction with one or more PROMPT statements. Any mixture of INPUT and PROMPT statements can be included on the same logical screenline in a screen definition.

Syntax

The format of the INPUT statement is:

INPUT inputname [AT [COLUMN] n] [TO [COLUMN] m | [LEN m] [DP {k | *}]] [UPCASE | NOCASE] [DEFAULT 'value'] [DEBLANK | NODEBLANK] [PAD WITH 'c'] [automatic-validation-options] [[READ attributes] [REREAD attributes] [PRINT attributes] [TAG [attributes] [WITH 'c']] [ITEMID n]

Where:

inputname indicates the name of the data item entered by the terminal operator.

AT, TO, LEN, and DP options

The AT, TO, LEN, and DP options are described in the following table.

Option	Specifies...
AT n	Where the title is to begin on the screen.
TO m	Column where the title is to end.
LEN m	Length of a title beginning at the n specified in the AT option. If a menu variable is used to supply the title, and you do not specify a length, the default length is the remainder of the line.
DP k or DP *	Number of decimal places displayed in a title. DP k displays k decimal places for the title. Any additional decimal places are truncated. DP * displays all decimal places.

COLUMN keyword

COLUMN (optional). If the AT specification is omitted, and the input item is the first item on the screenline, the input area begins in column 2. If it is not the first item on the screenline, the input area begins, following one blank space, to the right of the text displayed by the previous PROMPT statement or space reserved by the previous INPUT statement.

When both AT and TO are specified, space is reserved for the input item on the current line at locations n through m inclusive. For example, the ADDRESS item defined below:

INPUT ADDRESS AT 15 TO 29

reserves space on the screen in positions 15-29. The length of the ADDRESS is thus 15 characters (m-n+1).

When AT and LEN are both specified, space is reserved for the input item on the current line starting at position n and extending m characters (to position n+m). The following statement also reserves space on the screen in positions 15-29:

INPUT ADDRESS AT 15 LEN 15

UPCASE and NOCASE options

UPCASE and NOCASE allow one item (or multiple items) on a screen to be specified with a case attribute that differs from the rest of the screen. UPCASE forces case translation and NOCASE prevents case translation. See UPCASE and NOCASE options.

Case translation

Case translation specifies whether screen input is displayed on the screen as entered, or displayed as uppercase. If case translation is in effect, all input to the screen is displayed in upper case, regardless of whether it is entered in upper or lower case. For input items, case translation specifies how the screen input is stored in Model 204.

Case translation is based on:

• The setting for *LOWER
• The setting of UPCASE or NOCASE
• The value of the LANGUSER parameter

The settings of UPCASE and NOCASE take precedence over the setting for *LOWER and *UPPER. Even if *UPPER is in effect, if an item is specified as NOCASE, it is stored or displayed in the case in which it was entered. Conversely, if *LOWER is in effect and an item is specified as UPCASE, the item is translated and stored or displayed in uppercase.

When UPCASE is specified, the value of the LANGUSER parameter is checked to determine the language that is in use, and, consequently, the correct case translation rules to use. See the Model 204 Language Support Summary for more information on language processing and the LANGUSER parameter.

DEFAULT option

The DEFAULT option specifies a default or initial value for an input item. The value must be enclosed in single quotes.

This default is shown as the value of the input item when the screen is first displayed. It can be changed at that time by the terminal operator.

If the default string exceeds the length specified for the input item, the string is truncated. If the length of the default string is less than the specified length, the default is padded with spaces at the end. The value must be enclosed in single quotes.

This option eliminates the need to use an assignment statement to set the initial value of an INPUT variable.

DEBLANK or NODEBLANK option

The DEBLANK option specifies that leading and trailing blanks on the input item are to be removed from any value entered into the input item by the terminal operator. The NODEBLANK option specifies that leading and trailing blanks are to be retained. DEBLANK is the system default.

Default values and values assigned to an input item by the request are not affected by this option.

PAD WITH 'c' option

The PAD WITH 'c' option displays an input item as padded with a user-specified character. The keyword WITH is optional; 'c' can be any character you select.

This option helps to delineate the length of an input item. It differs from the DEFAULT option because the pad character are not retained as part of the input (any leading or trailing pad characters are removed).

Be careful when combining the PAD WITH 'c' option with the DEBLANK option (which is the default). If both options are present, any leading or trailing mixture of blanks and pad characters are removed. If PAD WITH 'c' is specified with NODEBLANK and the input item begins or ends with blanks, any adjacent pad characters are not removed.

Automatic validation options

Automatic validation options specify the criteria by which Model 204 automatically validates an input value before that value is used in the request. See Automatic validation options for INPUT for more information.

READ option

The READ option selects the display attributes for the item on execution of a READ statement. The default display attributes for input items are UNPROTECTED, DIM, and VISIBLE.

REREAD option

The REREAD option selects the display attributes for the item on execution of a REREAD statement. For an input item, the REREAD attributes are used only if the item is not tagged. If no REREAD option is specified, the READ attributes are used during REREAD

PRINT option

The PRINT option selects the display attributes for the item on execution of a PRINT statement. If no PRINT option is specified, the READ attributes other than UNPROTECTED are used during PRINT.

TAG option

The TAG option specifies the display attributes for an item on the execution of a REREAD statement when the item is tagged. You also can specify the character to be displayed as the error indicator when an input value does not meet the automatic validation criteria. If a TAG option is not specified for a particular input item, the default error indicator, an asterisk (*), is displayed in column 80. If more than one value on the same screenline is in error, the error indicator of the rightmost item is used as the tag character.

Syntax

The format of the TAG option is:

TAG [attributes] [WITH 'c']

where:

• attributes indicate any valid display attribute supported by the user's terminal (see the section titled Display attributes). The default TAG attributes are UNPROTECTED, BRIGHT, and VISIBLE.
• WITH 'c' specifies the character (c) to be displayed in column 80 as the error indicator; any EBCDIC character can be specified. The default character is * (asterisk).

  The use of BRIGHT, highlighting, and/or color attributes for tagged items is especially useful when more than one input item appears on the same line on the screen. If you do not wish an error indicator to be displayed, a space must be explicitly specified as the tag character, as shown below.

  INPUT CODE TAG BRIGHT WITH ' '

ITEMID option

The ITEMID option assigns a number from 1 to 32767 to an input item. This number is used for reference by the cursor variable %screenname:ITEMID. For more information on %screenname:ITEMID, as it relates to cursor handling, refer to Reserved cursor variables.

Automatic validation options for INPUT

Automatic validation options specify the criteria by which Model 204 automatically validates an input value before that value is used in the request. Automatic validation is performed after the DEBLANK option is processed. For more information on automatic input validation, refer to Input validation.

Automatic validation is performed by specifying any of the options listed below in an INPUT statement. If validation requirements are not met, the error is tagged and an error indicator is displayed if the screen is redisplayed with a REREAD statement.

Option	If specified for an input item...
ALPHA	Only upper- and lowercase alphabetic characters (for the language specified by the LANGUSER parameter) are accepted.
ALPHANUM	Only upper- and lowercase alphabetic characters (for the language specified by the LANGUSER parameter) and/or digits (0-9) are accepted.
MUST FILL	Either the number of characters entered must match the specified length, or no characters must be entered. Otherwise, an error is signaled. If both the DEBLANK and MUST FILL options are specified and the terminal operator has entered leading and/or trailing spaces, the input item is tagged as in error. REQUIRED must be specified if null input values are not acceptable.
NUMERIC	Only digits (0-9), minus sign, and one decimal point are accepted. A minus sign must be in the leftmost character position.
ONEOF value[,value]...	Value entered must be one of a specified set of values. You can include any number of values in the list; values are separated by commas. Enclose values containing commas or spaces with quotation marks. (for example, '1,000,000'). The following example specifies that an entered value is one of the New England states: INPUT STATE ONEOF MA, CT, RI, NH, VT, ME
RANGE	Only numbers or character strings in the specified range are allowed in the input value. RANGE performs range checking in the form: [NUMERIC] [RANGE lo [TO] hi [AND lo [TO] hi] ... If the NUMERIC option is specified immediately before RANGE, the number entered must be greater than or equal to lo, and less than or equal to hi. If the input value falls within either range, it is accepted. Numbers used with this option can be integers and/or fractions. If the NUMERIC option is not specified, a character range is assumed. The string you specify must be between lo and hi, inclusive, in EBCDIC collating sequence. A string that contains more than one word (containing either a space or a character that normally ends a word, such as right parenthesis or =) must be quoted, as shown below. INPUT NAME RANGE ADAMS TO 'LE BLANC' Both types of range option allow any number of ranges to be specified using AND. The following statement tests for two distinct ranges of numbers: INPUT CODE NUMERIC RANGE 1001 TO 2999 AND 5001 TO 6999 If the input value falls within either range, it is accepted.
REQUIRED	Item is tagged when a null value is entered.
VERIFY 'characters'	Only the specified set of characters can be included in the input value. Each character can appear in the input value any number of times and in any order. For example, the following statement ensures that input IDs contain only, but not necessarily all, the specified characters INPUT ID VERIFY 'ABCDXYZ.:-&' Thus, the following IDs are acceptable: A.B DD XCZ -: and the following IDs are unacceptable: A,B MNO AB*

Multiple validation criteria

With the exception of REQUIRED, multiple validation criteria for a single input item are treated as if they were connected by OR Boolean operators. If an input value satisfies any one of the item's criteria, the value is accepted. Note that both numeric and nonnumeric validation criteria can be specified for a single input item. If REQUIRED is specified, the input value is checked for a null value before the input value is validated against other item criteria.

DEFAULT statements

Default statements define various screen item defaults, in some cases replacing the need for specification on each screen item.

The DEFAULT TITLE (or PROMPT or INPUT) statement sets the READ, REREAD, TAG, and PRINT display attributes globally for screen items. The DEFAULT CURSOR statement defines the default cursor position for the defined screen.

Syntax

The format for the DEFAULT TITLE (or PROMPT or INPUT) statement is:

DEFAULT {TITLE | PROMPT | INPUT [DEBLANK | NODEBLANK] [PAD WITH 'c'] [LEN m [DP [k | *}]] [UPCASE | NOCASE] | [TAG [attributes] [WITH 'c']} [[READ] attributes] [REREAD attributes] [PRINT attributes]

Where:

The options are the same as described for INPUT statement.

Scope of DEFAULT TITLE or PROMPT or INPUT statements

The scope of a particular DEFAULT statement is either until another DEFAULT statement for the same screen item type or until the END SCREEN statement. Any display attribute defined explicitly for a screen item overrides the corresponding display attribute specified in the DEFAULT statement.

For example:

DEFAULT INPUT READ YELLOW BLINK . . . INPUT MSGLINE READ WHITE

results in WHITE and BLINK attributes for the MSGLINE item.

The DEFAULT statement does not affect items defined earlier in the screen.

Syntax

The format for the DEFAULT CURSOR statement is:

DEFAULT CURSOR [READ | REREAD | PRINT] {ITEMID n | itemname | ROW n COLUMN m}

Where:

ITEMID, itemname, or ROW and COLUMN specify where the cursor is positioned initially on the execution of a READ, REREAD, or PRINT SCREEN statement, unless overriding cursor setting information exists (a WITH CURSOR option). For more information on cursor positioning, refer to Cursor handling.

The DEFAULT CURSOR statement can appear anywhere in a screen definition; only one DEFAULT CURSOR statement is allowed for each screen definition.

SKIP and NEW PAGE statements

SKIP statement

The SKIP statement passes over one or more lines on the screen.

Syntax

The format for the SKIP statement is:

SKIP n LINE[S]

where n is a positive integer that specifies the number of lines to be left blank on the screen. For example, this statement causes two blank lines to appear before the next screenline:

SKIP 2 LINES

NEW PAGE statement

The NEW PAGE statement forces a new page for multi-panel screens.

MAX PFKEY statement for screens

The MAX PFKEY statement specifies the maximum PF key value associated with a particular screen.

Syntax

The format for the MAX PFKEY statement is:

MAX PFKEY n

where n is a number from 1 to 255. If n exceeds 255, a default value of 255 is used. The MAX PFKEY n statement can appear anywhere in the screen definition after the title line. Only one MAX PFKEY statement is allowed per screen definition.

How the pressing of PF keys greater than n is handled

If a MAX PFKEY statement is present and the terminal operator presses a PF key with a value greater than n in response to a READ, REREAD, or PRINT SCREEN statement, the PF key value is divided by n.

• If the PF key value is evenly divided by c, c is returned to %screenname:PFKEY.
• If the PF key value is not evenly divided by n, the value of the remainder is returned to %screenname:PFKEY.

For example, if MAX PFKEY 12 is specified, Model 204 returns PF13 through PF24 as PF1 through PF12.

INCLUDE statement

The INCLUDE statement includes a stored procedure within a screen definition. The stored procedure can contain screen definition statements, followed by any other valid procedure input.

The INCLUDE statement must occur at the beginning of a screen definition line. The format of this statement is the same as that for the INCLUDE statement (see Procedures) with the optional IN clause.

Screen definition example

In the following screen definition example, the user defines the format of the UPDATE CURRENT EMPLOYEE INFORMATION screen:

SCREEN UPDATE MAX PFKEY 12 DEFAULT CURSOR READ NBR TITLE 'UPDATE CURRENT EMPLOYEE INFORMATION' AT 19 BRIGHT SKIP 2 LINES * *THE TEXT FOR MSGLINE IS DEFINED LATER IN THE REQUEST * INPUT MSGLINE BRIGHT SKIP 2 LINES PROMPT 'ENTER EMPLOYEE NUMBER OR PRESS PF3 TO QUIT:' - BRIGHT INPUT NBR LEN 4 NUMERIC SKIP 2 LINES PROMPT 'NAME:' INPUT NAME LEN 50 - PROMPT 'AGE:' AT 59 INPUT AGE LEN 2 NUMERIC - PROMPT 'SEX:' AT 67 INPUT SEX LEN 1 UPCASE ONEOF M,F PROMPT 'ADDRESS:' INPUT ADDRESS1 INPUT ADDRESS2 AT 11 INPUT ADDRESS3 AT 11 INPUT ADDRESS4 AT 11 PROMPT 'TELEPHONE:' INPUT PHONE SKIP 2 LINES PROMPT 'SUPERVISOR:' INPUT SUPER PROMPT 'POSITION:' INPUT POSITION LEN 20 - PROMPT 'DEPARTMENT NO:' AT 35 INPUT DEPT LEN 5 DP * PROMPT 'SALARY:' INPUT SALARY LEN 8 DP 2 - PROMPT 'START DATE:' AT 35 INPUT DATE END SCREEN

The preceding statements result in a screen of the format shown in the following figure when displayed by a request.

Sample screen created by a SCREEN statement

UPDATE CURRENT EMPLOYEE INFORMATION **TYPE OVER CURRENT INFO TO CHANGE OR PRESS PF3 TO QUIT** ENTER EMPLOYEE NUMBER OR PRESS PF3 TO QUIT: NAME: AGE: SEX: ADDRESS: TELEPHONE: POSITION: SUPERVISOR: SALARY: START DATE:

Screen manipulation

Screen manipulation involves reading a previously defined screen and accepting input items from the terminal operator. You manipulate screens by using screen manipulation statements that:

• Initialize and display a screen
• Accept responses from the terminal operator
• Validate input
• Highlight errors.
• Control cursor placement (refer to Cursor handling).

You can specify screen manipulation statements anywhere in the User Language request, except within a screen definition (between a SCREEN and an END SCREEN statements).

Screen manipulation statements

The following table lists and briefly describes the screen manipulation statements. Each of these statements, along with cursor handling, is discussed separately on the pages that follow. In addition, a discussion is provided on the sequence in which screens are evaluated when a READ SCREEN, REREAD SCREEN, or PRINT SCREEN statement is executed. An example illustrating screen manipulation appears at the end of the discussion.

Screen manipulation statements

Statement	Description
CLEAR TAG	Clears the error indicator.
MODIFY	Changes display attributes of a screen item.
PREPARE SCREEN	Reinitializes a screen during request execution.
PRINT SCREEN	Displays a screen on a terminal or as USE output.
READ SCREEN	Displays a screen and accepts responses from the terminal operator.
REREAD SCREEN	Redisplays a screen for correction.
TAG	Highlights invalid responses with an error indicator.

Note: The functions $ChkMod and $ChkTag are particularly useful when performing screen manipulation.

MODIFY and PREPARE statements for screens

MODIFY statement

The MODIFY statement changes the display attributes of a screen item during the execution of a User Language request.

Note these considerations when using the MODIFY statement:

• The UNPROTECTED attribute is not allowed for titles and prompts.
• The PREPARE SCREEN statement restores display attributes to their original state.

Syntax

The format for the MODIFY statement is:

MODIFY %screenname:itemname [TO] attributes [ALL | READ | [FOR] REREAD | TAG | PRINT]

A MODIFY statement changes only those attributes that you wish to change (for example, from BRIGHT to DIM); the statement leaves other attributes unchanged. If ALL is specified or the FOR clause is omitted, the new attributes apply to READ, REREAD, TAG, and PRINT.

PREPARE statement

The PREPARE statement reinitializes the values of all input items and other text displayed on a screen. PREPARE can be issued at any point in a request to restore values that were altered by READ, REREAD, TAG, MODIFY, and assignment statements.

The PREPARE statement performs the following operations:

• Restores specified default values (those indicated by DEFAULT options) to the title, prompts, and input items
• Restores null values to items that do not have default values
• Clears all tags
• Restores the original display attributes if the attributes were overridden by a MODIFY statement

Syntax

The format of the PREPARE statement is:

PREPARE [SCREEN] screenname

where screenname refers to a screen that was previously described in a screen definition.

Use with global screens

Defining a screen as global affects the order in which you should issue PREPARE statements.

PRINT SCREEN statement

The PRINT SCREEN statement displays a screen on a terminal or as USE output with all screen items protected. With the PRINT statement, a single screen definition can be used for both data entry and reporting purposes.

When the PRINT SCREEN statement is evaluated, and output is to an IBM 3270 or compatible terminal, the screen is displayed on the terminal in panels as normally would appear during a READ. All INPUT items are protected. The terminal operator presses the ENTER key or a PF key to complete the operation of the PRINT. The key that the user presses is returned to the request.

If a USE command has been issued prior to executing a PRINT SCREEN statement, the output is formatted in the same manner as PRINT SCREEN output on a line-at-a-time terminal (item spacing is preserved). For more information, see Line-at-a-time terminal support.

Syntax

The format for the PRINT SCREEN statement is:

PRINT SCREEN screenname [ALERT] [[WITH] CURSOR] [TITLE {'text' | %variable} [AT [COLUMN] n] [TO [COLUMN] m | LEN m] [attributes]]

where the WITH CURSOR attribute option is identical to that described earlier for the READ SCREEN statement, and the other options are the same as those for the READ MENU statement.

READ SCREEN statement

The READ SCREEN statement lets you perform these activities:

• Display a user-formatted screen on the terminal.
• Cause Model 204 to wait for the terminal operator to enter appropriate input values. Model 204 then performs automatic validation on those values.
• Make input values available for further validation and processing.
• Optionally redisplay the screen for corrected input.

The first time a particular READ SCREEN statement is executed for a request, the items on the screen are displayed either as null or with the default values specified in the DEFAULT option on the INPUT statement or assigned by the request. Subsequent READ statements for that screen clear all old tags and display the values entered by the terminal operator.

Syntax

The format of the READ SCREEN statement is:

READ [SCREEN] screenname [ALERT] [NO REREAD] [[WITH] CURSOR] [TITLE {'text' | %variable} [AT [COLUMN] n] [TO [COLUMN] m | LEN m] [attributes]]

Where:

• screenname refers to a screen previously defined by a set of screen definition statements.
• Except as noted below, the other components of the READ SCREEN statement are the same as the corresponding ones for the READ MENU statement.

NO REREAD option

The NO REREAD option cancels the automatic redisplay of the screen when errors are detected in input items. In this case, Model 204 performs the automatic validation and tags invalid items, but the terminal operator is not prompted to correct them.

NO REREAD is used in application requests that specify both automatic validation (using INPUT statement validation options) and manual validation (using other statements in the request). This option allows the user-specified error checking statements within the request to detect errors, tag invalid items, and then redisplay the screen using the REREAD statement. The redisplayed screen shows both the system- and user-tagged errors and allows the terminal operator to correct both types of errors at the same time.

WITH CURSOR option

The WITH CURSOR option positions the cursor using a cursor setting variable. Refer to Cursor handling for a detailed description of how the WITH CURSOR option is used to position the cursor.

REREAD SCREEN statement

The REREAD statement redisplays a screen so that the terminal operator can correct the values on input items tagged as errors.

Note: If no items are tagged, the screen is not redisplayed.

REREAD is the only statement that allows the operator to correct input values tagged as a result of manual validation. The terminal operator can modify items other than tagged items when the screen is redisplayed.

All input is validated again using the automatic validation options on the INPUT statements before it is returned to the User Language request for manual validation. However, the screen is not redisplayed automatically if any of the input fails automatic validation.

Syntax

The format of the REREAD SCREEN statement is:

REREAD [SCREEN] screenname [ALERT] [[WITH] CURSOR] [TITLE {'text' | %variable} [AT [COLUMN] n] [TO [COLUMN] m | LEN m] [attributes]]

where screenname refers to a screen that was previously described in a screen definition.

The WITH CURSOR attribute option is identical to that described earlier for the READ SCREEN statement. The other options are the same as those for the READ MENU statement.

Do not reread a screen which has no TAG fields. You can either explicitly tag a field before using REREAD, or use the following construct:

IF $CHKTAG('screenname') THEN REREAD SCREEN screenname * process screen ENDIF

TAG and CLEAR TAG statements

TAG statement

The TAG statement activates the error indicator associated with an input item.

Syntax

The format of the TAG statement is:

TAG %screenname:inputname [attributes] [WITH 'c']

where %screenname:inputname identifies the item to be tagged. The attributes and WITH 'c' options are the same as those described earlier for the TAG option of the INPUT statement.

The last TAG or MODIFY statement executed (referred to below as the "active" statement) defines the attributes.

If the TAG statement is specified...	Then the input item...
Without options	Is tagged with the character specified in the TAG option of the INPUT statement.
Without attributes	Attributes are those specified on the TAG option of the INPUT statement, unless there is an active MODIFY statement that applies to the input item.
With attributes	Attributes are those specified on the TAG statement, even if there is an active MODIFY statement in effect. Furthermore, the NUMERIC and INVISIBLE attributes are preserved, if they are present.

CLEAR TAG statement

The CLEAR TAG statement clears an activated tag for a particular input item, or clears the tags for all input items on a screen.

Syntax

The format of the CLEAR TAG statement is:

CLEAR TAG {screenname | %screenname:inputname}

If you omit inputname, all tags for the specified screen are cleared. If you include inputname, only the tag associated with the specified input item is cleared.

Cursor handling

Model 204 provides the following cursor handling features that can be used in the manipulation of screens:

Cursor handling feature	During the execution of a READ, REREAD, or PRINT SCREEN statement, selects...
Cursor setting	Initial position of the cursor
Cursor sensing	Final position of the cursor.

Cursor setting or sensing is implemented by using special reserved cursor handling variables.

Reserved cursor variables

The reserved variables listed below are used when performing cursor setting or sensing. The format for each is:

%screenname:variable

These variables can be used to tie a cursor to a particular screen item or to a specific row and column number.

Variable	Use to perform cursor...
COLUMN	Setting and sensing. The range values for COLUMN is 1 through 80. The column number is relative to the beginning of the screen as it is defined logically, which is the same as its physical display position.
ITEMID	Setting and sensing. The number corresponds to an ITEMID option specified in a prompt or input definition.
ITEMNAME	Setting only. %screenname:ITEMNAME sets the cursor under a particular screen item. The value is a character string identical to one of the item names in the screen definition.
ROW	Setting and sensing. The row number is relative to the beginning of the screen as it is defined logically. Defined rows (TITLE, PROMPT, INPUT, or SKIP statements) in the logical screen are all included in the calculation of %screenname:ROW. A logical row number is the same as its physical display position only within the first display panel of a SCREEN. For example, on a 24-row terminal, the first 23 rows of the SCREEN (including the title) are rows 1 through 23. The title line of the second panel is row 1. The second line of the second panel is row 24. Rows would continue to be numbered in this manner, with each physical panel accounting for 22 rows. The title line is always row 1.

After the execution of a READ, REREAD, or PRINT statement, the cursor variables contain values. These values are not reset by a PREPARE statement. It is the responsibility of the User Language request to reset the variables, if necessary, before the next READ, REREAD, or PRINT statement.

Using cursor setting

You specify the cursor setting by assigning values to cursor setting variables and using the WITH CURSOR option on the READ, REREAD, or PRINT SCREEN statements.

The order of precedence for where the cursor is placed under:

1. The item named by %screenname:ITEMNAME, if the variable's value is not null and appears in the screen definition.
2. The item identified by %screenname:ITEMID, if the variable's value is not 0 and appears in the screen definition.
3. The position indicated by %screenname:ROW and %screenname:COLUMN, if one or both variables are not zero and both are within the screen definition.

   Note: If one of the variables is 0, a 1 is forced.

4. The position indicated by the DEFAULT CURSOR statement in the screen definition if all cursor setting variables have a null, 0, or invalid value, or if there is no WITH CURSOR option.
5. The first UNPROTECTED input item on the current panel for READ, under the first UNPROTECTED tagged input item on the current panel for REREAD, or in the upper left corner of the screen for PRINT.
6. If the above conditions fail, the cursor is placed in the upper left corner.

The screen panel with the position selected by these rules is the first one displayed, with the cursor properly positioned. Variables that have higher precedence must be cleared explicitly by the request to allow variables that have lower precedence to take effect.

Be careful when coding requests that loop around READ, REREAD, or PRINT SCREEN statements with the WITH CURSOR option. If the variables are not explicitly changed before each statement, the previous input cursor position is used for the new output position.

Example of cursor setting

BEGIN SCREEN A TITLE ' SCREEN A' AT 2 SKIP 2 LINES DEFAULT INPUT TAG RED WITH ' ' PROMPT ' ENTER PFKEY3 TO QUIT:' - INPUT NMR PROMPT ' ENTER YOUR FAVORITE COLOR ' - AT 11 INPUT COLOR PROMPT ' ENTER YOUR FAVORITE CAR ' - AT 15 INPUT CAR END SCREEN %A:ITEMNAME='CAR' READ SCREEN A WITH CURSOR IF %A:PFKEY EQ 3 THEN STOP END IF REREAD SCREEN A END

Using cursor sensing

After a READ, REREAD, or PRINT SCREEN statement is executed, the cursor sensing variables contain information on the position of the cursor in the logical screen definition. Cursor position variables are set as follows:

Variable	Value
%screenname:COLUMN	Logical screen column
%screenname:ITEMID	Value of ITEMID on the PROMPT or INPUT statement, or 0
%screenname:ITEMNAME	Null
%screenname:ROW	Value of 1 on the TITLE statement, or logical screen row

Model 204 returns ROW and COLUMN values beyond the bounds of the logical screen if that is where the terminal operator has placed the cursor. The request is responsible for validating the input cursor position.

READ, REREAD, and PRINT evaluation sequence

The rules that govern the evaluation of the READ SCREEN, REREAD SCREEN, and PRINT SCREEN statements are:

1. If the cursor has been explicitly set, the logical panels preceding the one holding the cursor position are validated on a READ SCREEN or REREAD SCREEN statement. If a READ SCREEN statement is executed with the automatic reread enabled and tagged items exist, the first tagged logical panel is displayed first (skip to Step 4).
2. If there is no automatic reread to perform, the logical panel that contains the cursor position is handled (skip to Step 4).
3. Otherwise, the first logical panel is handled.
4. If the cursor has been explicitly set, the physical panels preceding the one holding the cursor position is validated on a READ SCREEN or REREAD SCREEN statement.
5. If there is no automatic reread to perform, the physical panel with the cursor position is displayed (skip to Step 7).
6. Otherwise, the first physical panel is displayed.
7. Input is accepted for the current physical panel.
8. The physical panel is automatically validated on a READ SCREEN or REREAD SCREEN statement. If the automatic reread is enabled and any item is tagged, the panel is redisplayed (return to Step 7).
9. If the ENTER key is used, the next physical panel, if any, is displayed for input (return to Step 7).
10. If a PF key is pressed, all remaining physical panels are validated for a READ SCREEN or REREAD SCREEN statement. If there are any tagged items and the automatic reread is in effect, the next physical panel following the panel on which the PF key was pressed is displayed (return to step 7). If an automatic reread is not in effect, each remaining logical panel is validated. If any item fails validation, the first physical panel on that logical panel is displayed (return to Step 7).
11. If ENTER continues to be pressed, all remaining logical panels in the logical screen are handled.
12. %screenname:ROW, %screenname:COLUMN, %screenname:PFKEY, and %screenname:ITEMID all reflect values from the last physical panel displayed on the terminal.

Screen manipulation example

The following request uses the UPDATE CURRENT EMPLOYEE INFORMATION screen defined in Screen definition example to allow the terminal operator to display an employee record. The operator selects the record to be displayed by entering the employee number. Once the record is displayed, the operator can change the employee information.

Once all the necessary information has been changed, the record is updated. A message is immediately displayed in order to notify the operator as to whether the update process was successful.

BEGIN * * DEFINE SCREEN FOR EMPLOYEE UPDATE PROMPTING FOR EMPLOYEE * NUMBER * SCREEN UPDATE MAX PFKEY 12 DEFAULT CURSOR READ NBR TITLE 'UPDATE CURRENT EMPLOYEE INFORMATION' AT 19 BRIGHT SKIP 2 LINES INPUT MSGLINE BRIGHT SKIP 2 LINES PROMPT 'ENTER EMPLOYEE NUMBER OR PRESS PF3 TO QUIT:' - BRIGHT INPUT NBR LEN 4 NUMERIC SKIP 2 LINES PROMPT 'NAME:' INPUT NAME LEN 50 - PROMPT 'AGE:' AT 59 INPUT AGE LEN 2 NUMERIC - PROMPT 'SEX:' AT 67 INPUT SEX LEN 1 UPCASE ONEOF M,F PROMPT 'ADDRESS:' INPUT ADDRESS1 INPUT ADDRESS2 AT 11 INPUT ADDRESS3 AT 11 INPUT ADDRESS4 AT 11 PROMPT 'TELEPHONE:' INPUT PHONE SKIP 2 LINES PROMPT 'POSITION:' INPUT POSITION PROMPT 'SUPERVISOR:' INPUT SUPER PROMPT 'POSITION:' INPUT POSITION LEN 20 - PROMPT 'DEPARTMENT NO:' AT 35 INPUT DEPT LEN 5 DP * PROMPT 'SALARY:' INPUT SALARY LEN 8 DP 2 - PROMPT 'START DATE:' AT 35 INPUT DATE END SCREEN * * PROMPT USER FOR EMPLOYEE ID NUMBER. IF NOT FOUND THEN * GIVE MESSAGE. * IF FOUND THEN GET RECORD AND DISPLAY CURRENT INFO. * READ.SCRN: READ SCREEN UPDATE CANCEL: IF %UPDATE:PFKEY EQ 3 THEN SKIP 3 LINES PRINT 'REQUEST CANCELLED - RECORD - NOT UPDATED' AT COLUMN 10 STOP END IF GET.EMP: FIND ALL RECORDS FOR WHICH ENUM=%UPDATE:NBR END FIND CT.RECS: COUNT RECORDS IN GET.EMP IF COUNT IN CT.RECS EQ 0 THEN %UPDATE:MSGLINE =- '**THERE IS NO EMPLOYEE WITH THIS - RECORD NUMBER PLEASE CHANGE OR PRESS PF3**' READ SCREEN UPDATE %UPDATE:MSGLINE= JUMP TO CANCEL END IF * * RETRIEVE CURRENT INFO TO DISPLAY ON SCREEN * GET.INFO: FOR EACH RECORD IN GET.EMP %UPDATE:NAME=NAME %UPDATE:AGE=AGE %UPDATE:SEX=SEX %UPDATE:PHONE=PHONE %UPDATE:POSITION=POSITION %UPDATE:DEPARTMENT NO=DEPT %UPDATE:SUPER=SUPERVISOR %UPDATE:SALARY=SALARY %UPDATE:DATE=SDATE FOR %I FROM 1 TO 4 %ADDR='UPDATE:ADDRESS' WITH %I  :%ADDR=ADDRESS(%I) END FOR END FOR %UPDATE:MSGLINE =- ' **TYPE OVER CURRENT INFO TO CHANGE OR - PRESS PF3 TO QUIT**' READ SCREEN UPDATE %UPDATE:MSGLINE= IF %UPDATE:PFKEY EQ 3 THEN SKIP 3 LINES PRINT 'REQUEST CANCELLED - RECORD NOT - UPDATED' AT COLUMN 10 STOP END IF IF NOT $chkmod('UPDATE') THEN SKIP 3 LINES PRINT 'NO CHANGES WERE ENTERED - RECORD - NOT UPDATED' AT COLUMN 10 STOP END IF * * UPDATE CURRENT EMPLOYEE RECORD * UPDT.REC: FOR EACH RECORD IN GET.EMP CHANGE NAME TO %UPDATE:NAME CHANGE AGE TO %UPDATE:AGE CHANGE SEX TO %UPDATE:SEX CHANGE PHONE TO %UPDATE:PHONE CHANGE POSITION TO %UPDATE:POSITION CHANGE DEPARTMENT NO TO %UPDATE:DEPT CHANGE SUPERVISOR TO %UPDATE:SUPER CHANGE SALARY TO %UPDATE:SALARY CHANGE DATE TO %UPDATE:SDATE FOR %I FROM 1 TO 4 %ADDR='UPDATE:ADDRESS' WITH %I CHANGE ADDRESS(%I) TO :%ADDR END FOR END FOR * * DISPLAY SUCCESSFUL COMPLETION MESSAGE * UPDT.GOOD: SKIP 3 LINES PRINT 'EMPLOYEE RECORD SUCCESSFULLY UPDATED' - AT 10 STOP END

Line-at-a-time terminal support

Although the full-screen features described in this topic are oriented to the use of IBM 3270 video display terminals, requests that invoke menus and screens can be run from line-at-a-time terminals as well. Model 204 automatically changes its mode of full-screen operation to match the characteristics of the line-at-a-time terminal.

The following discussion applies to all line-at-a-time terminals.

Menus

Menu output is handled on a line-by-line basis. When a READ MENU statement is issued, each line of the menu is displayed on a separate terminal line, preceded by the system-generated selection number. At the end of the menu, Model 204 prompts the terminal operator by displaying:

ENTER SELECTION, CR FOR n

where n is the current value of %menuname:SELECTION. If the terminal operator enters an invalid menu selection number, Model 204 reprompts.

If the terminal operator decides not to view the entire menu, the attention key (for example, BREAK or ATTN) can be pressed to stop the display. Model 204 then skips automatically to the ENTER SELECTION prompt shown above.

Pressing the attention key at any time other than when a menu is being displayed either causes the ON ATTENTION unit (if present) to be executed or the request to be cancelled.

When a PRINT MENU statement is issued and output is sent to a line-at-a-time terminal, each line of the menu is sent a row at a time. Item spacing from the menu definition is preserved.

Screens

All screen inputs and outputs are handled on a line-by-line basis. When a READ SCREEN statement is issued, each TITLE, PROMPT, and INPUT statement included in the screen definition is handled as a separate interaction with the terminal. The titles, prompts, and default input values are shown in the order of appearance in the screen definition. Titles and prompts are displayed on separate lines on the terminal. Consecutive prompts that have no intervening INPUT statements are displayed on the same line. Every INPUT statement included in the request causes the terminal operator to be prompted for input.

If an input item already has a value when the READ is issued, the value is displayed as follows:

DEFAULT:value

The user can indicate acceptance of the default value by pressing carriage return. Alternatively, the user can enter a new value.

If an invisible item is specified, the item is preceded by a user-specified prompt, or by the default prompt:

INVISIBLE INPUT:

Default values of invisible items are not displayed.

If an input value has automatic validation options specified for it; see the section titled Screen manipulation. Model 204 checks the response immediately, and the user is not able to proceed until a correct value is entered. Note, however, that if the NO REREAD option was specified in the READ statement, Model 204 moves on to the next item whether or not the terminal operator enters the correct value.

The operation of the REREAD SCREEN statement is similar to that of READ SCREEN. REREAD displays the title:

THE FOLLOWING ITEMS HAVE INVALID VALUES:

before the user-specified title. Following these titles, only items that have been tagged as errors are displayed. The prompt preceding the tagged input item in the screen definition is displayed, followed by the tagged input.

When a PRINT SCREEN statement is issued and output is to a line-at-a-time terminal, each line of the screen is sent a row at a time. Item spacing from the screen definition is preserved.