Full-screen feature: Difference between revisions
(83 intermediate revisions by 5 users not shown) | |||
Line 32: | Line 32: | ||
===LFSCB parameter setting=== | ===LFSCB parameter setting=== | ||
<p> | <p> | ||
The system manager sets the <var>[[LFSCB parameter|LFSCB]]</var> parameter (size of full-screen buffer) | The system manager sets the <var>[[LFSCB parameter|LFSCB]]</var> parameter (size of full-screen buffer) during system initialization, or the user sets the LFSCB parameter Online with the UTABLE command. </p> | ||
===Maximum number of screens and menus=== | ===Maximum number of screens and menus=== | ||
<p> | <p> | ||
The maximum number of screens and menus combined is 256 | The maximum number of screens and menus combined per request is 256 (version 7.6 and earlier) or 4095 (version 7.7 and later).</p> | ||
===Global screens and menus=== | ===Global screens and menus=== | ||
<p> | <p> | ||
Line 105: | Line 105: | ||
<p> | <p> | ||
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:</p> | 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:</p> | ||
<p class="code"> EMPLOYEE MENU | <p class="code"> EMPLOYEE MENU | ||
1 ADD EMPLOYEE | 1 ADD EMPLOYEE | ||
2 CHANGE ADDRESS | 2 CHANGE ADDRESS | ||
3 CHANGE INSURANCE | 3 CHANGE INSURANCE | ||
4 ADD DEPENDENT | 4 ADD DEPENDENT | ||
</p> | </p> | ||
===Operator interaction with menu=== | ===Operator interaction with menu=== | ||
<p> | <p> | ||
Line 122: | Line 123: | ||
<p class="code"> EMPLOYEE ADD SCREEN | <p class="code"> EMPLOYEE ADD SCREEN | ||
FILL IN THE FOLLOWING INFORMATION | FILL IN THE FOLLOWING INFORMATION | ||
FOR EACH NEW EMPLOYEE | FOR EACH NEW EMPLOYEE | ||
Line 132: | Line 133: | ||
AGE: | AGE: | ||
SEX: | SEX: | ||
SSN: | SSN: </p> | ||
</p> | |||
<p> | <p> | ||
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.</p> | 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. </p> | ||
<p> | <p> | ||
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 | 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 <var class="product">Model 204</var>. </p> | ||
===Input validation=== | ===Input validation=== | ||
<p> | <p> | ||
The input entered at the terminal is then validated according to criteria specified in the application request. Two types of validation can be performed: | The input entered at the terminal is then validated according to criteria specified in the application request. Two types of validation can be performed: </p> | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
Line 150: | Line 150: | ||
<tr> | <tr> | ||
<td>Automatic</td> | <td>Automatic</td> | ||
<td>Validation criteria (for example, the response must be all-numeric) using special full-screen options. | <td>Validation criteria (for example, the response must be all-numeric) using special full-screen options. </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>Manual</td> | <td>Manual</td> | ||
<td>Statements that check for errors in terminal responses (for example, statements that verify that an input code matches a code in a particular record). | <td>Statements that check for errors in terminal responses (for example, statements that verify that an input code matches a code in a particular record). </td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
Line 169: | Line 169: | ||
CITY: NORFOLK | CITY: NORFOLK | ||
STATE: VA | STATE: VA | ||
ZIP: 501B3 * | ZIP: 501B3 * | ||
AGE:14 * | AGE:14 * | ||
SEX: M | SEX: M | ||
SSN: 042-54-9803 | SSN: 042-54-9803 | ||
</p> | </p> | ||
<p> | <p> | ||
The terminal operator can then correct the items in error and press | 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. </p> | ||
==Application display considerations== | ==Application display considerations== | ||
<p> | <p> | ||
Prior to application design, you should be familiar with the following aspects of the full-screen feature and the terminal display area:</p> | Prior to application design, you should be familiar with the following aspects of the full-screen feature and the terminal display area: </p> | ||
<ul> | <ul> | ||
<li>Positions on the video screen, often described as layout</li> | <li>Positions on the video screen, often described as layout </li> | ||
<li>Terminal display attributes for color and light intensity</li> | <li>Terminal display attributes for color and light intensity </li> | ||
</ul> | </ul> | ||
===Screen display area=== | ===Screen display area=== | ||
<p> | <p> | ||
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. | 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. </p> | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
Line 216: | Line 216: | ||
<tr> | <tr> | ||
<td>Last line, the bottom row on the screen, usually row 24</td> | <td>Last line, the bottom row on the screen, usually row 24</td> | ||
<td><var class="product">Model 204</var> backpaging feature. Backpaging allows the terminal operator to review previous pages of output. | <td><var class="product">Model 204</var> [[Terminal processing#Backpaging|backpaging]] feature. Backpaging allows the terminal operator to review previous pages of output. </td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
Line 223: | Line 222: | ||
===Display attributes=== | ===Display attributes=== | ||
<p> | <p> | ||
The following basic display attributes available on 3270-type terminals can be used within a full-screen application design. | 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: | ||
<p class="code">VISible | </p> | ||
<p class="code">VISible INVisible INVISible | |||
UNPROTected PROTected | |||
BRIGHT DIM | |||
</p> | </p> | ||
===Extended display attributes=== | ===Extended display attributes=== | ||
<p> | <p> | ||
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 <var>[[FSOUTPUT parameter|FSOUTPUT]]</var> parameter must be set. | 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 <var>[[FSOUTPUT parameter|FSOUTPUT]]</var> parameter must be set. </p> | ||
<p> | <p> | ||
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.</p> | 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. </p> | ||
====Highlighting attributes==== | ====Highlighting attributes==== | ||
Line 258: | Line 257: | ||
<tr> | <tr> | ||
<td> | <td><em>No</em> fields with a color attribute set</td> | ||
<td>Base-color mode </td> | <td>Base-color mode </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><em>Any</em> field with a color attribute set </td> | ||
<td>Extended-color mode</td> | <td>Extended-color mode</td> | ||
</tr> | </tr> | ||
Line 293: | Line 292: | ||
<td>BRIGHT, PROTECTED </td> | <td>BRIGHT, PROTECTED </td> | ||
<td>WHITE</td> | <td>WHITE</td> | ||
<td> | <td>N/A</td> | ||
</tr> | </tr> | ||
Line 302: | Line 301: | ||
</tr> | </tr> | ||
</table> | </table> | ||
====Extended-color mode attribute assignments==== | ====Extended-color mode attribute assignments==== | ||
<p> | <p> | ||
Line 349: | Line 348: | ||
===Display attribute rules and restrictions=== | ===Display attribute rules and restrictions=== | ||
<p> | <p> | ||
You should be aware of these rules and restrictions when specifying display attributes:</p> | You should be aware of these rules and restrictions when specifying display attributes: </p> | ||
<ul> | <ul> | ||
<li>The INVISIBLE attribute overrides all other display attributes. </li> | <li>The INVISIBLE attribute overrides all other display attributes. </li> | ||
Line 361: | Line 360: | ||
<li>Highlighting attributes cannot be mixed together.</li> | <li>Highlighting attributes cannot be mixed together.</li> | ||
<li>The PROTECTED attribute implies an autoskip. Autoskip causes a screen item to be skipped by the forward and backward tab keys. | <li>The PROTECTED attribute implies an autoskip. Autoskip causes a screen item to be skipped by the forward and backward tab keys. </li> | ||
</li> | |||
</ul> | </ul> | ||
Line 394: | Line 392: | ||
===Menu and screen variables=== | ===Menu and screen variables=== | ||
<p> | <p> | ||
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.</p> | 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. </p> | ||
<p> | <p> | ||
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:</p> | To avoid the confusion of duplicate names for different menus and screens (for example, a <code>NAME</code> item on an <code>EMPLOYEE</code> screen and a <code>NAME</code> item on a <code>CREDITOR</code> screen), you must refer to a screen or menu name using the following formats: </p> | ||
<ul> | <ul> | ||
<li>Titles and prompts — Named titles or prompts on menus and screens are referenced in the following format: | <li>Titles and prompts — Named titles or prompts on menus and screens are referenced in the following format: | ||
<p class="syntax"><span class="term">%menuname</span>:<span class="term">promptname</span> | <p class="syntax"><span class="term">%menuname</span>:<span class="term">promptname</span> </p> | ||
</p> | |||
<p> | <p> | ||
or</p> | or</p> | ||
<p class="syntax"><span class="term">%screenname</span>:<span class="term">promptname</span> | <p class="syntax"><span class="term">%screenname</span>:<span class="term">promptname</span> </p> | ||
</p> | |||
<p> | <p> | ||
Values for named titles or prompts are specified by an assignment statement of the following format:</p> | Values for named titles or prompts are specified by an assignment statement of the following format: </p> | ||
<p class="syntax"><span class="term">%menuname</span>:<span class="term">promptname</span> = value | <p class="syntax"><span class="term">%menuname</span>:<span class="term">promptname</span> = value </p> | ||
</p> | |||
<p> | <p> | ||
or:</p> | or:</p> | ||
<p class="syntax"><span class="term">%screenname</span>:<span class="term">promptname</span> = value | <p class="syntax"><span class="term">%screenname</span>:<span class="term">promptname</span> = value </p> | ||
</p> | |||
<p> | <p> | ||
For example, this statement:</p> | For example, this statement:</p> | ||
<p class="code">%EMPLOYEE:PNAME = 'ENTER NAME:' | <p class="code">%EMPLOYEE:PNAME = 'ENTER NAME:' </p> | ||
</p> | |||
<p> | <p> | ||
assigns the text string, ENTER NAME:, as the value of the prompt PNAME on the EMPLOYEE screen.</p></li> | assigns the text string, <code>ENTER NAME:</code>, as the value of the prompt <code>PNAME</code> on the <code>EMPLOYEE</code> screen.</p></li> | ||
<li>Input items — Input items entered on screens are referenced in the following format: | <li>Input items — Input items entered on screens are referenced in the following format: | ||
<p class="syntax"><span class="term">%screenname</span>:<span class="term">inputname</span> | <p class="syntax"><span class="term">%screenname</span>:<span class="term">inputname</span> </p> | ||
</p> | |||
<p> | <p> | ||
identifies the input item INNAME entered on the EMPLOYEE screen | For example, this statement identifies the input item <code>INNAME</code> entered on the <code>EMPLOYEE</code> screen:</p> | ||
<p class="code">%EMPLOYEE:INNAME </p></li> | |||
</ul> | </ul> | ||
Line 441: | Line 430: | ||
<tr> | <tr> | ||
<td>%menuname:SELECTION </td> | <td nowrap>%menuname:SELECTION </td> | ||
<td> | <td>Menu selection number entered by a <var>PF</var> key or by tabbing to the desired selection number and pressing <var>ENTER</var>. The value stored in %menuname:SELECTION can be used: | ||
<ul> | |||
Menu selection number entered by a <var>PF</var> key or by tabbing to the desired selection number and pressing <var>ENTER</var>. The value stored in %menuname:SELECTION can be used:< | <li>Directly in either an arithmetic expression or a computed JUMP statement</li> | ||
< | <li>As the target of an assignment statement to specify the initial cursor position for the next menu display</li> | ||
Directly in either an arithmetic expression or a computed JUMP statement</ | </ul> | ||
< | |||
As the target of an assignment statement to specify the initial cursor position for the next menu display | |||
</td> | </td> | ||
</tr> | </tr> | ||
Line 454: | Line 441: | ||
<tr> | <tr> | ||
<td>%screenname:PFKEY </td> | <td>%screenname:PFKEY </td> | ||
<td> | <td>Value of the <var>PF</var> key number entered by the terminal operator for a screen. If the terminal operator presses the <var>ENTER</var> key, a zero is returned in %screenname:PFKEY. | ||
Value of the <var>PF</var> key number entered by the terminal operator for a screen. If the terminal operator presses the <var>ENTER</var> key, a zero is returned in %screenname:PFKEY. | |||
<p> | <p> | ||
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. </p> | 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. </p> | ||
Line 462: | Line 447: | ||
</tr> | </tr> | ||
</table> | </table> | ||
===Screen item name variables=== | ===<b id="scrnItemNameVars"></b>Screen item name variables=== | ||
<p> | <p> | ||
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: </p> | 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: </p> | ||
Line 480: | Line 465: | ||
<p> | <p> | ||
A screen item name variable and a menu or screen variable are actually the same variable. </p> | A screen item name variable and a menu or screen variable are actually the same variable. </p> | ||
==Defining menus== | ==<b id="menuStmt"></b>Defining menus== | ||
<p> | <p> | ||
Use menu | 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.</p> | ||
<p> | <p> | ||
Each menu statement must begin with <var>Menu</var> and end with <var>End Menu</var>. In between, you specify a series of menulines that describe the titles, prompts, and blank lines to appear on the menu.</p> | |||
===Menu statement syntax=== | |||
<p> | <p> | ||
The formats of the <var>Menu</var> block and statement are: </p> | |||
{{Template:Menu statement syntax}} | |||
<p> | <p> | ||
The | Where:</p> | ||
< | <ul> | ||
<li><var class="term">menuName</var> 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 <var>Menu</var> statement is assigned to the menu being defined; it subsequently can be referenced in menu manipulation statements.</li> | |||
<li><var>Declare</var> and <var>Common</var> specify that the menu is a common element in the request. Specifying <var>Common</var> (or specifying neither <var>Common</var> nor <var>Global</var>) results in the menu being stored in the default area (the FSCB) rather than in GTBL. | |||
Common elements, as well as <var>Declare</var> and <var>Common</var>, are discussed in detail in [[Subroutines#Sharing common elements|Sharing common elements]].</li> | |||
<li><var>Global</var> specifies that the menu is stored in GTBL. Global menus have an implied scope of <var>Common</var> (see above). | |||
<p class="note"><b>Note:</b> | |||
Do not specify the <var>Global</var> attribute for multi-page (logical pages) menus. </p></li> | |||
<li><var>Permanent</var> (<var>Perm</var>) can only be used with global menus. <var>Perm</var> global menus persist across request boundaries (they are maintained in GTBL even after a request has been terminated). </li> | |||
<li><var>Temporary</var> (<var>Temp</var>) can only be used with global menus. <var>Temp</var> global menus are allocated in GTBL, but are deleted at request termination. An example of using a <var>Temp</var> global menu would be when you do not need to pass the menu to another request; using <var>Temp</var> global menus eliminates the need for you to explicitly delete globals that do not need to persist. </li> | |||
<li>The number of menulines must not exceed 23 lines. </li> | |||
<p> | <li><p>A <var class="term">menuLine</var> is one of the statements listed below: </p> | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
<th>Statement</th> | <th>Statement</th> | ||
Line 505: | Line 505: | ||
<tr> | <tr> | ||
<td>[[# | <td>[[#TitleStmtMenu|Title]] </td> | ||
<td>Specifies the menu title.</td> | <td>Specifies the menu title.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>[[# | <td>[[#PromptStmtMenu|Prompt]]</td> | ||
<td>Defines a particular menu option.</td> | <td>Defines a particular menu option.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>[[# | <td>[[#SkipStmtMenu|Skip]]</td> | ||
<td>Skips one or more lines on the screen.</td> | <td>Skips one or more lines on the screen.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>[[# | <td>[[#MaxPFKeyStmtMenu|Max PFKey]]</td> | ||
<td>Specifies the maximum <var>PF</var> key value associated with a menu.</td> | <td>Specifies the maximum <var>PF</var> key value associated with a menu.</td> | ||
</tr> | </tr> | ||
</table> | </table></li> | ||
< | |||
<li>Comments and blank lines included in a menu statement are ignored by <var class="product">Model 204</var>. </li> | |||
< | <li>Every menu definition must terminate with <var>End Menu</var>. </li> | ||
</ul> | |||
=== | ==<b id="TitleStmtMenu"></b>TITLE statement for menus== | ||
<p> | <p> | ||
The | The <var>Title</var> statement specifies a character string that is displayed as the menu title on the first line of the screen. </p> | ||
<p> | |||
If a <var>Title</var> statement is not defined in a menu definition, a menu title can be specified when the menu is displayed (see [[#READ MENU statement|READ MENU statement]]). If no title is specified, this system menu title is displayed: | |||
</p> | |||
<p> | |||
If a | |||
<p class="code">INDICATE NUMBER FOR DESIRED SELECTION | <p class="code">INDICATE NUMBER FOR DESIRED SELECTION | ||
</p> | </p> | ||
Line 571: | Line 541: | ||
====Syntax==== | ====Syntax==== | ||
<p> | <p> | ||
A | A <var>Title</var> statement must be the first menuline of a menu definition. The format of the <var>Title</var> statement is:</p> | ||
<p class="syntax"> | <p class="syntax">Title {'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">promptname</span>} [At [Column] <span class="term">n</span>] | ||
[ | [To [Column] <span class="term">m</span> <span class="squareb">|</span> [Len <span class="term">m</span>] [Dp {<span class="term">k</span> <span class="squareb">|</span> *}]] | ||
[ | [Default '<span class="term">value</span>'] | ||
[[ | [[Read] <span class="term">attributes</span>] [Reread <span class="term">attributes</span>] | ||
[ | [Print <span class="term">attributes</span>] | ||
</p> | </p> | ||
Where: | Where: | ||
Line 582: | Line 552: | ||
<li><var class="term">text</var> 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.</li> | <li><var class="term">text</var> 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.</li> | ||
<li><var class="term">promptname</var> is a menu variable to which a value can be assigned before the menu is displayed with the | <li><var class="term">promptname</var> is a menu variable to which a value can be assigned before the menu is displayed with the <var>Read Menu</var> or <var>Print Menu</var> statement. </li> | ||
</li> | |||
</ul> | </ul> | ||
Line 590: | Line 559: | ||
<li>Location options (optional) are listed and described in the following table: | <li>Location options (optional) are listed and described in the following table: | ||
<table> | <table> | ||
<tr class="head"> | |||
<tr> | <th>Option</th> | ||
< | <th>Specifies...</th> | ||
< | |||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><var>At <i>n</i></var></td> | ||
<td>Where the title is to begin on the screen. </td> | <td>Where the title is to begin on the screen. </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><var>To <i>m</i></var></td> | ||
<td>Column where the title is to end.</td> | <td>Column where the title is to end.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><var>Len <i>m</i></var></td> | ||
<td>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.</td> | <td>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.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><var>Dp <i>k</i></var> or <var>Dp *</var></td> | ||
<td> | <td>Number of decimal places displayed in a title. | ||
< | |||
Number of decimal places displayed in a title. | |||
<p> | <p> | ||
<var>Dp <i>k</i></var> displays <var class="term">k</var> decimal places for the title. Any additional decimal places are truncated. </p> | |||
<p> | <p> | ||
<var>Dp *</var> displays all decimal places.</p></td> | |||
</td> | |||
</tr> | </tr> | ||
</table> | </table> | ||
</li> | </li> | ||
<li> | <li><var>Column</var> keyword (optional). An <var class="term">n</var> value of 1 automatically is converted to 2, because a title cannot begin in the reserved first column. If the <var>At</var> option is not included in the <var>Title</var> statement, the title begins at column 2. | ||
<p> | <p> | ||
If the difference between the | If the difference between the <var>At</var> and <var>To</var> specifications or the <var>Len</var> 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 <var>To</var> specification. This <var>Title</var> statement indicates that the text string within single quotes is to be displayed, beginning in column 13: </p> | ||
<p class="code">TITLE 'EMPLOYEE MENU' AT COLUMN 13 | <p class="code">TITLE 'EMPLOYEE MENU' AT COLUMN 13 | ||
</p></li> | </p></li> | ||
<li> | <li><var>Default</var> 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 <var>Title</var> variable. </li> | ||
<li> | <li><var>Read</var> selects the display attributes for the title on execution of a <var>Read</var> statement. The default display attributes for a title are <var>Protected</var>, <var>Dim</var>, and <var>Visible</var>. | ||
<p class="note"><b>Note:</b> | <p class="note"><b>Note:</b> | ||
The | The <var>Unprotected</var> attribute is not allowed in a title. Specifying the <var>Unprotected</var> attribute results in an error message. </p></li> | ||
</li> | |||
<li> | <li><var>Print</var> selects the display attributes for the title on execution of a <var>Print</var> statement. If no <var>Print</var> option is specified, the <var>Read</var> attributes are used during <var>Print</var>. | ||
</li> | </li> | ||
</ul> | </ul> | ||
==PROMPT statement for menus== | ==<b id="PromptStmtMenu"></b>PROMPT statement for menus== | ||
<p> | <p> | ||
The | The <var>Prompt</var> statement specifies a text string for each menu selection option. You supply the text for each prompt and <var class="product">Model 204</var> automatically generates the selection number to accompany each prompt. </p> | ||
<p> | <p> | ||
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. | 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. </p> | ||
====Syntax==== | ====Syntax==== | ||
<p> | <p> | ||
The syntax for the | The syntax for the <var>Prompt</var> statement is:</p> | ||
<p class="syntax"> | <p class="syntax">Prompt {'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">promptname</span>} | ||
[ | [At [Column] <span class="term">n</span>] [To [Column] <span class="term">m</span> <span class="squareb">|</span> [Len <span class="term">m</span>] | ||
[ | [Dp {<span class="term">k</span> <span class="squareb">|</span> *}]] | ||
[ | [Default '<span class="term">value</span>'] [[Read] <span class="term">attributes</span>] | ||
[ | [Reread <span class="term">attributes</span>] | ||
[ | [Print <span class="term">attributes</span>] [Itemid <span class="term">n</span>] | ||
</p> | </p> | ||
Where: | Where: | ||
Line 665: | Line 626: | ||
<li><var class="term">text</var> is a character string enclosed in single quotes with a maximum length of 76 characters.</li> | <li><var class="term">text</var> is a character string enclosed in single quotes with a maximum length of 76 characters.</li> | ||
<li><var class="term">promptname</var> is a menu variable to which a value is assigned before the menu is displayed with the | <li><var class="term">promptname</var> is a menu variable to which a value is assigned before the menu is displayed with the <var>Read Menu</var> or <var>Print Menu</var> statement. </li> | ||
<li>Location options (optional) listed in the following table specify the position of a prompt on the screen. | <li>Location options (optional) listed in the following table specify the position of a prompt on the screen. | ||
Line 675: | Line 636: | ||
<tr> | <tr> | ||
<td> | <td><var>At <i>n</i></var></td> | ||
<td>Where the title is to begin on the screen. </td> | <td>Where the title is to begin on the screen. </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><var>To <i>m</i></var></td> | ||
<td>Column where the title is to end.</td> | <td>Column where the title is to end.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><var>Len <i>m</i></var></td> | ||
<td>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.</td> | <td>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.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td><var>Dp <i>k</i></var> or <var>Dp *</var></td> | ||
<td> | <td>Number of decimal places displayed in a title. | ||
<p> | <p> | ||
<var>Dp <i>k</i></var> displays <var class="term">k</var> decimal places for the title. Any additional decimal places are truncated. </p> | |||
<p> | <p> | ||
<var>Dp *</var> displays all decimal places. </p> | |||
</td></tr> | |||
</table></li> | |||
</td> | |||
</tr> | |||
</table> | |||
</li> | |||
<li> | <li><var>Column</var> (optional). If an AT option is not specified in a <var>Prompt</var> statement, the prompt begins at column 5. If an <var>At</var> option is specified, the prompt begins at the position indicated by <var class="term">n</var>. A prompt cannot start before column 5. If the difference between the <var>At</var> and <var>To</var> specifications or the <var>Len</var> 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. | ||
<p class="note"><b>Note:</b> | <p class="note"><b>Note:</b> | ||
The prompt string is not right-justified at the column indicated by the | The prompt string is not right-justified at the column indicated by the <var>To</var> specification. </p></li> | ||
</li> | |||
<li> | <li><var>Default</var> 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 <var>Prompt</var> variable. </li> | ||
<li> | <li><var>Read</var> selects the display attributes for the item on execution of a <var>Read</var> statement. The default display attributes for prompts are <var>Protected</var>, <var>Dim</var>, and <var>Visible</var>. | ||
<p class="note"><b>Note:</b> | <p class="note"><b>Note:</b> | ||
You incur an error message if you use an | You incur an error message if you use an <var>Unprotected</var> attribute in a prompt.</p></li> | ||
</li> | |||
<li> | <li><var>Print</var> selects the display attributes for the item on execution of a <var>Print</var> statement. If no <var>Print</var> option is specified, the <var>Read</var> attributes are used during <var>Print</var>. | ||
</li> | </li> | ||
</ul> | </ul> | ||
Line 722: | Line 677: | ||
====Usage==== | ====Usage==== | ||
<p> | <p> | ||
Normally, each | Normally, each <var>Prompt</var> 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 <var>Prompt</var> statement. An example of this is shown below. | ||
</p> | |||
<p class="code">PROMPT 'EMPLOYEE ADD' AT 10 '(NEW PERSONNEL ONLY)' AT 10 | <p class="code">PROMPT 'EMPLOYEE ADD' AT 10 '(NEW PERSONNEL ONLY)' AT 10 | ||
</p> | </p> | ||
<p> | <p> | ||
This produces the following output:</p> | This produces the following output: </p> | ||
<p class=" | <p class="output">1 EMPLOYEE ADD | ||
(NEW PERSONNEL ONLY) | (NEW PERSONNEL ONLY) | ||
</p> | </p> | ||
==<b id="SkipStmtMenu"></b>SKIP statement for menus== | |||
< | |||
<p> | <p> | ||
The | The <var>Skip</var> 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 <var>Skip</var>. Skipping beyond 23 lines is not allowed. </p> | ||
====Syntax==== | ====Syntax==== | ||
<p> | <p> | ||
The syntax for the | The syntax for the <var>Skip</var> statement is:</p> | ||
<p class="syntax"> | <p class="syntax">Skip <span class="term">n</span> Line[s] | ||
</p> | </p> | ||
<p> | <p> | ||
Line 750: | Line 703: | ||
causes two blank lines before the next menu line.</p> | causes two blank lines before the next menu line.</p> | ||
<p> | <p> | ||
The | The <var>Skip %variable Line(s)</var> option is <em>not</em> supported for this application of the <var>Skip</var> statement. </p> | ||
< | ==<b id="MaxPFKeyStmtMenu"></b>MAX PFKEY statement for menus== | ||
<p> | <p> | ||
The | The <var>Max PFKey</var> statement specifies the maximum PF-key value associated with a particular menu. </p> | ||
<p> | <p> | ||
If a | If a <var>Max PFKey</var> statement is present and the terminal operator presses a PF key with a value greater than <var class="term">n</var> in response to a <var>Read</var> or <var>Print Menu</var> statement, the PF key value is divided by <var class="term">n</var>. If the <var>PF</var> key value is evenly divided by <var class="term">n</var>, <var class="term">n</var> is returned to <var class="term">%menuname</var>:SELECTION. If the PF key value is not evenly divided by <var class="term">n</var>, the value of the remainder is returned to <var class="term">%menuname</var>:SELECTION. For example, if <code>Max PFKey 12</code> is specified, <var class="product">Model 204</var> returns <var>PF13</var> through <var>PF24</var> as <var>PF1</var> through <var>PF12</var>. </p> | ||
====Syntax==== | ====Syntax==== | ||
<p> | <p> | ||
The syntax for the | The syntax for the <var>Max PFKey</var> statement is:</p> | ||
<p class="syntax"> | <p class="syntax">Max PFKey <span class="term">n</span> | ||
</p> | </p> | ||
<p> | <p> | ||
where <var class="term">n</var> is a number from 1 to 255. If <var class="term">n</var> exceeds 255, a default value of 255 is used. The statement can appear anywhere in the menu definition after the title line. Only one | where <var class="term">n</var> is a number from 1 to 255. If <var class="term">n</var> exceeds 255, a default value of 255 is used. The statement can appear anywhere in the menu definition after the title line. Only one <var>Max PFKey</var> statement is allowed for each menu definition. </p> | ||
==Menu definition example== | ==Menu definition example== | ||
<p> | <p> | ||
In this example, the user defines the format of the EMPLOYEE MENU selection screen: | In this example, the user defines the format of the <code>EMPLOYEE MENU</code> selection screen: </p> | ||
<p class="code">MENU PERSONNEL | <p class="code">MENU PERSONNEL | ||
TITLE 'EMPLOYEE MENU' AT 13 BRIGHT | TITLE 'EMPLOYEE MENU' AT 13 BRIGHT | ||
Line 785: | Line 736: | ||
</p> | </p> | ||
<p> | <p> | ||
The preceding statements result in a menu in the format shown below when displayed by the request.</p | The preceding statements result in a menu in the format shown below when displayed by the request. </p> | ||
<table> | <table> | ||
<caption>Sample menu created by menu statements</caption> | |||
<tr><td> | <tr><td> | ||
<p class="code"> <b>EMPLOYEE MENU</b> | <p class="code"> <b>EMPLOYEE MENU</b> | ||
1 NEW EMPLOYEE ADD | 1 NEW EMPLOYEE ADD | ||
2 EMPLOYEE UPDATE | 2 EMPLOYEE UPDATE | ||
3 EMPLOYEE INQUIRY | 3 EMPLOYEE INQUIRY | ||
4 EMPLOYEE DELETE | 4 EMPLOYEE DELETE | ||
5 YTD EARNINGS INQUIRY | 5 YTD EARNINGS INQUIRY | ||
6 INSURANCE INQUIRY | 6 INSURANCE INQUIRY | ||
7 DONE | 7 DONE | ||
</p> | </p> | ||
</td></tr> | </td></tr> | ||
</table> | </table> | ||
==Menu manipulation== | ==Menu manipulation== | ||
<p> | <p> | ||
Line 813: | Line 765: | ||
===Menu manipulation statements=== | ===Menu manipulation statements=== | ||
<p> | <p> | ||
You can initialize and display a menu and accept a response from the terminal operator. You can specify these statements anywhere in the | 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. </p> | ||
<p> | <p> | ||
Menus are manipulated using the following statements: | Menus are manipulated using the following statements: </p> | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
Line 823: | Line 775: | ||
<tr> | <tr> | ||
<td>MODIFY</td> | <td>[[#MODIFY and PREPARE MENU statements|Modify]]</td> | ||
<td>Changed attributes of a menu item during request execution.</td> | <td>Changed attributes of a menu item during request execution.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>PREPARE MENU</td> | <td>[[#MODIFY and PREPARE MENU statements|Prepare Menu]]</td> | ||
<td>Reinitialized menu.</td> | <td>Reinitialized menu.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>PRINT MENU </td> | <td>[[#PRINT MENU statement|Print Menu]] </td> | ||
<td>Menu on a terminal or as USE output.</td> | <td>Menu on a terminal or as USE output.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>READ MENU </td> | <td>[[#READ MENU statement|Read Menu]] </td> | ||
<td>Menu and accepts a response from the terminal operator.</td> | <td>Menu and accepts a response from the terminal operator.</td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
<p> | <p> | ||
An example program using these statements is described in [[# | An example program using these statements is described in [[#MenuManip|Menu manipulation example]]. </p> | ||
==READ MENU statement== | ==<b id="ReadMenuStmt"></b>READ MENU statement== | ||
<p> | <p> | ||
The | The <var>Read Menu</var> 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. </p> | ||
====Syntax==== | ====Syntax==== | ||
<p> | <p> | ||
The syntax for the | The syntax for the <var>Read Menu</var> statement is:</p> | ||
<p class="syntax"> | <p class="syntax">Read [Menu] <span class="term">menuname</span> [Alert] [Title | ||
{'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span>} | {'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span>} | ||
[ | [At [Column] <span class="term">n</span>] [To [Column] <span class="term">m</span> <span class="squareb">|</span> Len <span class="term">m</span>] | ||
[<span class="term">attributes</span>]] | [<span class="term">attributes</span>]] | ||
</p> | </p> | ||
Line 861: | Line 813: | ||
<li><var class="term">menuname</var> refers to a menu previously defined by a set of menu definition statements. </li> | <li><var class="term">menuname</var> refers to a menu previously defined by a set of menu definition statements. </li> | ||
<li> | <li><var>Alert</var> sounds the audible alarm on the terminal when the menu is displayed.<var>Alert</var> is ignored and no warning is issued if the terminal is not equipped with an alarm. </li> | ||
<li> | <li><var>Title</var> specifies a new title to override the menu title specified in the <var>AlertTitle</var> statement of the original menu definition. This new title is effective only for the current <var>Read</var> statement. The title specified in this option can be either a character string ('<var class="term">text</var>') or a variable that has been set to a string before the <var>Read Menu</var> statement is executed. </li> | ||
</li> | |||
</ul> | </ul> | ||
===AT, TO, LEN, and attributes options for READ MENU=== | ===AT, TO, LEN, and attributes options for READ MENU=== | ||
<p> | <p> | ||
The | The <var>At</var>, <var>To</var>, <var>Len</var>, and <var class="term">attributes</var> options are identical to those described in [[#TITLE statement for menus|TITLE statement for menus]]. If these options are omitted, the <var>At</var>, <var>To</var>, <var>Len</var>, and <var class="term">attributes</var> options defined for the title in the menu definition are used. </p> | ||
==PRINT MENU statement== | ==<b id="PrintMenuStmt"></b>PRINT MENU statement== | ||
<p> | <p> | ||
The | The <var>Print Menu</var> statement lets you display a menu on a terminal or as USE output with all menu items protected. </p> | ||
<p> | <p> | ||
When the | When the <var>Print Menu</var> statement is evaluated, and output is to an IBM 3270 or compatible terminal, the menu is displayed as it normally would appear during a <var>Read</var> except that the tab keys are ineffective. The terminal operator presses the Enter key or a <var>PF</var> key to complete the operation of the <var>Print</var>. The key that the operator pressed is returned to the request. </p> | ||
====Syntax==== | ====Syntax==== | ||
<p> | <p> | ||
The syntax for the | The syntax for the <var>Print Menu</var> statement is:</p> | ||
<p class="syntax"> | <p class="syntax">Print [Menu] <span class="term">menuname</span> [Alert<span class="squareb">]</span> [Title | ||
{'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span>} | {'<span class="term">text</span>' <span class="squareb">|</span> <span class="term">%variable</span>} | ||
[ | [At [Column] <span class="term">n</span>] [To [Column] <span class="term">m</span> <span class="squareb">|</span> Len <span class="term">m</span>] | ||
[<span class="term">attributes</span>]] | [<span class="term">attributes</span>]] | ||
</p> | </p> | ||
Where: | Where: | ||
<p> | <p> | ||
The | The <var>Alert</var>, <var>Title</var>, <var>At</var>, <var>To</var>, <var>Len</var>, and <var class="term">attributes</var> options are identical in [[#TITLE statement for menus|TITLE statement for menus]].</p> | ||
==MODIFY and PREPARE MENU statements== | ==MODIFY and PREPARE MENU statements== | ||
===MODIFY statement=== | ===<b id="ModifyStmtMenu"></b>MODIFY statement=== | ||
<p> | <p> | ||
The | The <var>Modify</var> statement changes the display attributes of a menu item during the execution of a SOUL request. </p> | ||
<p> | <p> | ||
A | A <var>Modify</var> statement changes only those attributes that you wish to change (for example, from <var>Visible</var> to <var>Invisible</var>); the statement leaves other attributes unchanged. If <var>All</var> is specified or the <var>For</var> clause is omitted, the new attributes apply to both <var>Read</var> and <var>Print</var>. </p> | ||
====Syntax==== | ====Syntax==== | ||
<p> | <p> | ||
The syntax for the | The syntax for the <var>Modify</var> statement is:</p> | ||
<p class="syntax"> | <p class="syntax">Modify <span class="term">%menuname</span>:<span class="term">itemname</span> | ||
[ | [To] <span class="term">attributes</span> [All <span class="squareb">|</span> [For] Read <span class="squareb">|</span> Prints] | ||
</p> | </p> | ||
====Usage notes==== | ====Usage notes==== | ||
<p> | <p> | ||
Consider the following when using the | Consider the following when using the <var>Modify</var> statement:</p> | ||
<ul> | <ul> | ||
<li>The | <li>The <var>Unprotected</var> attribute is not allowed for titles and prompts. </li> | ||
<li>The | <li>The <var>Prepare menu</var> statement restores display attributes to their original state. </li> | ||
</li> | |||
</ul> | </ul> | ||
===PREPARE statement=== | ===<b id="PrepareStmtMenu"></b>PREPARE statement=== | ||
<p> | <p> | ||
The | The <var>Prepare</var> statement reinitializes a menu. <var>Prepare</var> can be issued at any point in a request to restore values that were altered by assignment and <var>Modify</var> statements. The <var>Prepare</var> statement restores: </p> | ||
<ul> | <ul> | ||
<li>A cursor that was moved to select a menu option back to its original position</li> | <li>A cursor that was moved to select a menu option back to its original position</li> | ||
<li>Specified default values (those indicated by | <li>Specified default values (those indicated by <var>Default</var> options) to the title and prompts</li> | ||
<li>Null values to prompts specified with variable prompt names that do not have default values</li> | <li>Null values to prompts specified with variable prompt names that do not have default values</li> | ||
<li>Original display attributes if the attributes were overridden by | <li>Original display attributes if the attributes were overridden by <var>Modify</var> statements </li> | ||
</ul> | </ul> | ||
====Syntax==== | ====Syntax==== | ||
<p> | <p> | ||
The syntax for the | The syntax for the <var>Prepare</var> statement is: </p> | ||
<p class="syntax"> | <p class="syntax">Prepare [Menu] <span class="term">menuname</span> | ||
</p> | </p> | ||
Where: | Where: | ||
<p> | <p> | ||
<var class="term">menuname</var> refers to a menu previously described by a set of menu definition statements. | <var class="term">menuname</var> refers to a menu previously described by a set of menu definition statements. </p> | ||
====Use with global menus==== | ====Use with global menus==== | ||
<p> | <p> | ||
Defining a menu as global affects the order in which you should issue | Defining a menu as global affects the order in which you should issue <var>Prepare</var> statements. See [[Global features#Clearing the GTBL work area|Clearing the GTBL work area]] for a discussion of performance considerations related to declaring and clearing global objects from GTBL. </p> | ||
==Menu manipulation example== | ==<b id="menuManip"></b>Menu manipulation example== | ||
<p> | <p> | ||
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.</p> | In this example, the user defines a procedure that prompts the terminal operator for the next function to be performed, sets a global variable, <code>SELECTION</code>, with the user's response, and uses the conditional include capability to include the appropriate procedure. </p> | ||
<p class="code">PROCEDURE PERSONNEL.APPLICATION | <p class="code">PROCEDURE PERSONNEL.APPLICATION | ||
BEGIN | BEGIN | ||
Line 971: | Line 921: | ||
END PROCEDURE | END PROCEDURE | ||
</p> | </p> | ||
==<b id="scrnStmt"></b>Defining screens== | |||
<p> | |||
The <b>Screen block</b> 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. </p> | |||
<p> | <p> | ||
The <var>Screen</var> block must begin with <var>Screen</var> and end with <var>End Screen</var>. In between, you specify a series of <b>screenLines</b> that describe the titles, prompts, input areas, and blank lines to appear on the screen. </p> | |||
<p> | <p> | ||
You must include a | You must include a <var>Screen</var> block in a SOUL request for every screen to be displayed by that request. </p> | ||
<p> | |||
You can also use the <b>Screen statement</b> to define a <var>Common</var> name for a screen defined in an earlier <var>Screen</var> block. </p> | |||
===Screen block and statement syntax=== | |||
<p>The syntax of the <var>Screen</var> block and statement is:</p> | |||
{{Template: Screen statement syntax}} | |||
Where: | |||
<ul> | |||
<li><var class="term">screenName</var> 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 <var>Screen</var> statement is assigned to the screen being defined; it subsequently can be referenced in screen manipulation statements. </li> | |||
<li><var>Declare</var> and <var>Common</var> are used if the screen is a common element in the request. Specifying <var>Common</var> (or specifying neither <var>Common</var> nor <var>Global</var>) results in the screen being stored in the default area (the FSCB) rather than in GTBL. Common elements, as well as <var>Declare</var> and <var>Common</var>, are discussed in detail in [[Subroutines#Sharing common elements|Sharing common elements]]. </li> | |||
<li><var>Global</var> specifies that the screen is stored in GTBL. Global menus have an implied scope of <var>Common</var> (see above). | |||
<p class="note"><b>Note:</b> | |||
Do not specify the <var>Global</var> attribute for multi-page (logical pages) screens.</p></li> | |||
<li><var>Permanent</var> (<var>Perm</var>) can only be used with global screens. <var>Perm</var> global screens persist across request boundaries (they are maintained in GTBL even after a request has been terminated). </li> | |||
<li><var>Temporary</var> (<var>Temp</var>) can only be used with global screens. <var>Temp</var> global screens are allocated in GTBL, but they are deleted at request termination. You might use a <var>Temp</var> global screen when you do not need to pass the screen to another request; using <var>Temp</var> global screens eliminates the need to explicitly delete globals that do not need to persist. </li> | |||
<li>You can include any number of screen lines in a screen definition. | |||
<p> | <p> | ||
Each screen line normally corresponds to a single line on the [[#Logical and physical panels|physical panel]]. The SOUL compiler regards a <var class="term">screenLine</var> as a logical input line. If a screen line is longer than a single request input line, use a hyphen for continuation. </p></li> | |||
< | <li> | ||
< | |||
<p> | <p> | ||
A <var class="term">screenLine</var> can be one of the following: </p> | |||
< | |||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
Line 1,001: | Line 966: | ||
<tr> | <tr> | ||
<td> | <td>[[#DefaultStmtScrn|Default]]</td> | ||
<td>Specifies the various screen item defaults.</td> | <td>Specifies the various screen item defaults.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td>[[#IncludeStmtScrn|Include]]</td> | ||
<td>Includes a stored procedure within a screen definition.</td> | <td>Includes a stored procedure within a screen definition.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td>[[#InputStmtScrn|Input]]</td> | ||
<td>Describes an input item entered by the terminal operator.</td> | <td>Describes an input item entered by the terminal operator.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td>[[#MaxPFKeyStmtScrn|Max PFKey]]</td> | ||
<td>Specifies the maximum PF key value associated with a menu. </td> | <td>Specifies the maximum PF key value associated with a menu. </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td>[[#PromptStmtScrn|Prompt]]</td> | ||
<td>Defines a particular text prompt.</td> | <td>Defines a particular text prompt.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td>[[#SkipStmtScrn|Skip]]</td> | ||
<td>Skips one or more lines on the screen.</td> | <td>Skips one or more lines on the screen.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td>[[#TitleStmtScrn|Title]]</td> | ||
<td>Specifies the screen title.</td> | <td>Specifies the screen title.</td> | ||
</tr> | </tr> | ||
</table> | </table> | ||
</li> | |||
< | <li>Comments or blank lines included in a screen definition (between <var>Screen</var> and <var>End Screen</var>) are ignored by <var class="product">Model 204</var>. </li> | ||
< | <li>Every screen statement must end with <var>End Screen</var>, which terminates the definition of the screen. </li> | ||
Comments or blank lines included in a screen definition (between | </ul> | ||
< | |||
===Logical and physical panels=== | ===Logical and physical panels=== | ||
<p> | <p> | ||
The screen actually displayed to the terminal operator depends on the logical panel and physical panel.</p> | The screen actually displayed to the terminal operator depends on the logical panel and physical panel. </p> | ||
====Logical screen==== | ====Logical screen==== | ||
<p> | <p> | ||
A logical screen (panel) is that part of the logical screen definition which is ended by a | A logical screen (panel) is that part of the logical screen definition which is ended by a <var>New Page</var> or by an <var>End Screen</var> statement. These statements control where the display screen is to end. </p> | ||
====Physical screen==== | ====Physical screen==== | ||
<p> | <p> | ||
A physical screen (panel) is | A physical screen (panel) is the part of the logical panel that fits on the user's physical terminal as determined by the <var>MODEL</var> 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. </p> | ||
<p>If the prompts and/or input items specified in a screen definition exceed the number of lines available on a physical panel, <var class="product">Model 204</var> automatically constructs an overflow panel for the remaining lines. The overflow panel has the same title as the original screen. </p> | |||
==TITLE and PROMPT statements for screens== | ==TITLE and PROMPT statements for screens== | ||
===TITLE statement=== | ===<b id="TitleStmtScrn"></b>TITLE statement=== | ||
<p> | <p> | ||
The TITLE statement specifies a character string to be displayed as the screen title on the first line of the screen.</p> | The TITLE statement specifies a character string to be displayed as the screen title on the first line of the screen.</p> | ||
Line 1,123: | Line 1,053: | ||
</li> | </li> | ||
</ul> | </ul> | ||
===PROMPT statement=== | ===<b id="PromptStmtScrn"></b>PROMPT statement=== | ||
<p> | <p> | ||
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. </p> | 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. </p> | ||
Line 1,153: | Line 1,083: | ||
</li> | </li> | ||
</ul> | </ul> | ||
==INPUT statement== | ==<b id="InputStmtScrn"></b>INPUT statement== | ||
<p> | <p> | ||
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. </p> | 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. </p> | ||
Line 1,176: | Line 1,106: | ||
===AT, TO, LEN, and DP options=== | ===AT, TO, LEN, and DP options=== | ||
<p> | <p> | ||
AT, TO, LEN, and DP options are described in the following table | The AT, TO, LEN, and DP options are described in the following table.</p> | ||
<table> | <table> | ||
<tr> | <tr class="head"> | ||
< | <th>Option</th> | ||
< | <th>Specifies...</th> | ||
</tr> | </tr> | ||
Line 1,201: | Line 1,131: | ||
<tr> | <tr> | ||
<td>DP <i>k</i> or DP *</td> | <td>DP <i>k</i> or DP *</td> | ||
<td> | <td>Number of decimal places displayed in a title. | ||
Number of decimal places displayed in a title. | |||
<p> | <p> | ||
DP <var class="term">k</var> displays <var class="term">k</var> decimal places for the title. Any additional decimal places are truncated. </p> | DP <var class="term">k</var> displays <var class="term">k</var> decimal places for the title. Any additional decimal places are truncated. </p> | ||
Line 1,211: | Line 1,139: | ||
</tr> | </tr> | ||
</table> | </table> | ||
===COLUMN keyword=== | ===COLUMN keyword=== | ||
<p> | <p> | ||
Line 1,420: | Line 1,348: | ||
<p> | <p> | ||
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. </p> | 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. </p> | ||
==DEFAULT statements== | ==<b id="DefaultStmtScrn"></b>DEFAULT statements== | ||
<p> | <p> | ||
Default statements define various screen item defaults, in some cases replacing the need for specification on each screen item. </p> | Default statements define various screen item defaults, in some cases replacing the need for specification on each screen item. </p> | ||
Line 1,440: | Line 1,368: | ||
Where: | Where: | ||
<p> | <p> | ||
The options are the same as described | The options are the same as described for [[#INPUT statement|INPUT statement]].</p> | ||
===Scope of DEFAULT TITLE or PROMPT or INPUT statements=== | ===Scope of DEFAULT TITLE or PROMPT or INPUT statements=== | ||
<p> | <p> | ||
Line 1,469: | Line 1,397: | ||
<p> | <p> | ||
The DEFAULT CURSOR statement can appear anywhere in a screen definition; only one DEFAULT CURSOR statement is allowed for each screen definition. </p> | The DEFAULT CURSOR statement can appear anywhere in a screen definition; only one DEFAULT CURSOR statement is allowed for each screen definition. </p> | ||
==SKIP and NEW PAGE statements== | ==<b id="SkipStmtScrn"></b>SKIP and NEW PAGE statements== | ||
===SKIP statement=== | ===SKIP statement=== | ||
Line 1,489: | Line 1,417: | ||
<p> | <p> | ||
The NEW PAGE statement forces a new page for multi-panel screens. </p> | The NEW PAGE statement forces a new page for multi-panel screens. </p> | ||
==MAX PFKEY statement for screens== | ==<b id="MaxPFKeyStmtScrn"></b>MAX PFKEY statement for screens== | ||
<p> | <p> | ||
The MAX PFKEY statement specifies the maximum PF key value associated with a particular screen. </p> | The MAX PFKEY statement specifies the maximum PF key value associated with a particular screen. </p> | ||
Line 1,513: | Line 1,441: | ||
<p> | <p> | ||
For example, if MAX PFKEY 12 is specified, <var class="product">Model 204</var> returns <var>PF13</var> through <var>PF24</var> as <var>PF1</var> through <var>PF12</var>. </p> | For example, if MAX PFKEY 12 is specified, <var class="product">Model 204</var> returns <var>PF13</var> through <var>PF24</var> as <var>PF1</var> through <var>PF12</var>. </p> | ||
==INCLUDE statement== | ==<b id="IncludeStmtScrn"></b>INCLUDE statement== | ||
<p> | <p> | ||
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. </p> | 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. </p> | ||
<p> | <p> | ||
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#Procedures|Procedures]]) with the optional IN clause. </p> | 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#Procedures|Procedures]]) with the optional IN clause. </p> | ||
==Screen definition example== | ==Screen definition example== | ||
<p> | <p> | ||
Line 1,553: | Line 1,481: | ||
</p> | </p> | ||
<p> | <p> | ||
The preceding statements result in a screen of the format shown in the following figure when displayed by a request | The preceding statements result in a screen of the format shown in the following figure when displayed by a request.</p> | ||
== | <p class="caption" style="width:468px">Sample screen created by a SCREEN statement</p> | ||
< | <p class="code"> | ||
<p class="code"> | <b>UPDATE CURRENT EMPLOYEE INFORMATION | ||
Line 1,567: | Line 1,494: | ||
NAME: AGE: SEX: | NAME: AGE: SEX: | ||
ADDRESS: | ADDRESS: | ||
Line 1,579: | Line 1,505: | ||
SUPERVISOR: | SUPERVISOR: | ||
SALARY: START DATE: | SALARY: START DATE: | ||
</p> | </p> | ||
==Screen manipulation== | ==Screen manipulation== | ||
<p> | <p> | ||
Line 1,600: | Line 1,524: | ||
===Screen manipulation statements=== | ===Screen manipulation statements=== | ||
<p> | <p> | ||
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.</p> | |||
<table> | <table> | ||
<caption>Screen manipulation statements</caption> | <caption>Screen manipulation statements</caption> | ||
Line 1,644: | Line 1,568: | ||
</tr> | </tr> | ||
</table> | </table> | ||
<p class="note"><b>Note:</b> The functions | <p class="note"><b>Note:</b> The functions [[$ChkMod]] and [[$ChkTag]] are particularly useful when performing screen manipulation.</p> | ||
==MODIFY and PREPARE statements for screens== | ==MODIFY and PREPARE statements for screens== | ||
Line 1,669: | Line 1,593: | ||
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. </p> | 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. </p> | ||
===PREPARE statement=== | ===<b id="PrepareStmtScrn"></b>PREPARE statement=== | ||
<p> | <p> | ||
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. </p> | 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. </p> | ||
Line 1,696: | Line 1,620: | ||
<p> | <p> | ||
Defining a screen as global affects the order in which you should issue PREPARE statements.</p> | Defining a screen as global affects the order in which you should issue PREPARE statements.</p> | ||
==PRINT SCREEN statement== | ==PRINT SCREEN statement== | ||
<p> | <p> | ||
Line 1,703: | Line 1,627: | ||
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<var> ENTER</var> key or a <var>PF</var> key to complete the operation of the PRINT. The key that the user presses is returned to the request.</p> | 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<var> ENTER</var> key or a <var>PF</var> key to complete the operation of the PRINT. The key that the user presses is returned to the request.</p> | ||
<p> | <p> | ||
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, | 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|Line-at-a-time terminal support]].</p> | ||
====Syntax==== | ====Syntax==== | ||
Line 1,713: | Line 1,637: | ||
</p> | </p> | ||
<p> | <p> | ||
where the WITH CURSOR attribute option is identical to that described earlier for the READ SCREEN statement, and the other options | where the WITH CURSOR attribute option is identical to that described earlier for the [[#READ SCREEN statement|READ SCREEN statement]], and the other options are the same as those for the [[#READ MENU statement|READ MENU statement]].</p> | ||
==READ SCREEN statement== | ==READ SCREEN statement== | ||
<p> | <p> | ||
Line 1,772: | Line 1,696: | ||
where <var class="term">screenname</var> refers to a screen that was previously described in a screen definition.</p> | where <var class="term">screenname</var> refers to a screen that was previously described in a screen definition.</p> | ||
<p> | <p> | ||
The WITH CURSOR attribute option is identical to | The WITH CURSOR attribute option is identical to that described earlier for the [[#READ SCREEN statement|READ SCREEN statement]]. The other options are the same as those for the [[#READ MENU statement|READ MENU statement]].</p> | ||
<p> | <p> | ||
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:</p> | 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:</p> | ||
Line 1,780: | Line 1,704: | ||
ENDIF | ENDIF | ||
</p> | </p> | ||
==TAG and CLEAR TAG statements== | ==TAG and CLEAR TAG statements== | ||
Line 1,793: | Line 1,717: | ||
</p> | </p> | ||
<p> | <p> | ||
where <var class="term">%screenname</var>:<var class="term">inputname</var> identifies the item to be tagged. The attributes and WITH '<var class="term">c</var>' options are the same as those described earlier for the TAG option of the INPUT statement. | where <var class="term">%screenname</var>:<var class="term">inputname</var> identifies the item to be tagged. The attributes and WITH '<var class="term">c</var>' options are the same as those described earlier for the [[#TAG option|TAG option]] of the INPUT statement.</p> | ||
<p> | <p> | ||
The last TAG or MODIFY statement executed (referred to below as the "active" statement) defines the attributes. </p> | The last TAG or MODIFY statement executed (referred to below as the "active" statement) defines the attributes. </p> | ||
Line 1,817: | Line 1,741: | ||
</tr> | </tr> | ||
</table> | </table> | ||
===CLEAR TAG statement=== | ===CLEAR TAG statement=== | ||
<p> | <p> | ||
Line 1,892: | Line 1,816: | ||
<p> | <p> | ||
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. </p> | 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. </p> | ||
===Using cursor setting=== | ===Using cursor setting=== | ||
<p> | <p> |
Latest revision as of 20:28, 15 April 2019
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.
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 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
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)
Screens and menus can include:
- Title (name of the screen or menu)
- Prompts
- Input areas (for screens only)
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).
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
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 promptPNAME
on theEMPLOYEE
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 theEMPLOYEE
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:
|
%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.
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.
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.
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)
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.
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.
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.
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.
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:
- The item named by %screenname:ITEMNAME, if the variable's value is not null and appears in the screen definition.
- The item identified by %screenname:ITEMID, if the variable's value is not 0 and appears in the screen definition.
- 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.
- 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.
- 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.
- 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:
- 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).
- If there is no automatic reread to perform, the logical panel that contains the cursor position is handled (skip to Step 4).
- Otherwise, the first logical panel is handled.
- 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.
- If there is no automatic reread to perform, the physical panel with the cursor position is displayed (skip to Step 7).
- Otherwise, the first physical panel is displayed.
- Input is accepted for the current physical panel.
- 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).
- If the ENTER key is used, the next physical panel, if any, is displayed for input (return to Step 7).
- 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).
- If ENTER continues to be pressed, all remaining logical panels in the logical screen are handled.
- %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.