The ACCEPT, DISPLAY, and MODIFY verbs, along with screen entries defined in the Screen Section, have several options in common. The syntax details for these options are presented in the individual sections where they are allowed. See:
The following subheadings describe the effects of these options.
AT screen-loc
1. The AT phrase specifies both the row and column position of a screen field or control. The value of screen-loc must be a 4-, 6-, or 8-digit number.
AUTO Phrase
{AUTO }
{AUTO-SKIP }
{AUTOTERMINATE}
1. The AUTO phrase causes a field entry to automatically terminate as soon as the field is filled with data. If the field is the last field in a group of screen items (or the only field), then the ACCEPT statement will terminate when this occurs.
2. If the AUTO phrase is not specified, then the field entry must be terminated by the user's typing a valid termination key (such as the enter key).
3. When you are using RM/COBOL compatibility mode, AUTO is implied by default for any Format 1 ACCEPT statement. This may be overridden with the TAB phrase (see below).
BACKGROUND-HIGH, BACKGROUND-LOW, and BACKGROUND-STANDARD Phrases
{BACKGROUND-HIGH }
{BACKGROUND-LOW }
{BACKGROUND-STANDARD}
1. Specifying BACKGROUND-HIGH causes the background color to be shown in high-intensity . BACKGROUND-LOW causes it to be shown in low intensity.
2. BACKGROUND-STANDARD causes fields and controls to use the current subwindow's background intensity. When a window is created, BACKGROUND-STANDARD causes the window to use the default background intensity for the host system. See the BACKGROUND-INTENSITY runtime configuration variable for more details.
3. If no background intensity is specified, the current subwindow's intensity is used.
WITH [NO] {BELL}
{BEEP}
1. The BELL phrase causes the terminal's bell to ring prior to performing the I/O. The NO BELL phrase inhibits the bell from ringing. The default is NO BELL except that in RM/COBOL compatibility mode, a Format 1 ACCEPT statement defaults to BELL. See also the information on the BELL configuration variable in Appendix H, Book 4, "Appendices."
BLINK Phrase
WITH {BLINKING}
{BLINK }
1. Specifying the BLINK phrase causes the field to have the "blink" video attribute set for it. If the terminal hardware does not support blinking, this phrase is ignored. Note that many implementations of ACUCOBOL-GT will set the foreground and background colors for a field with the BLINK phrase to white-on-black. Note also that BLINK cannot be combined with UNDERLINED. Microsoft Windows does not support blinking.
CCOL, CLINE, CLINES, and CSIZE Phrases
AT CLINE NUMBER cline-num
AT CCOL NUMBER ccol-num
CSIZE {IS} clength [CELL ]
{= } [CELLS]
CLINES {IS} cheight [CELL ]
{= } [CELLS]
1. The CCOL, CLINE, CLINES, and CSIZE phrases provide an alternate method for specifying the placement (row and column) or size (height and width), or both, of a control for display on a non-graphical system. Together these phrases are called the character coordinate phrases. In any context where the COL, LINE, LINES, and SIZE phrases can be specified for a control, you can also specify the corresponding character coordinate phrase. These phrases make it easier to use controls on both graphical and non-graphical systems (see also section 3.6 of Book 2, "User Interface Programming").
2. You specify the character coordinate phrases in exactly the same fashion as their regular counterparts (i.e., CLINE is similar to LINE, CCOL to COL, etc.). All of the syntax supported by one phrase works in the corresponding phrase. For example, a Screen Section control item that has a twin set of column offsets is:
entry-field, col + 2, ccol + 1, ...
When the application is run on a graphical host system, the character coordinate phrases have no effect (exception: in some contexts the values are evaluated, so any relevant table indexes should be set to legal values to prevent access violations). When the application is run on a character-based host, the character coordinate phrases substitute for their counterparts. For example, if you specify both LINE and CLINE for a control, the CLINE specification will be used as the line number on a character-based system. Omitting a character coordinate phrase causes the regular counterpart to be used instead.
3. If you specify the CELLS option in either the SIZE or CSIZE phrase, then you must use the CELLS option in both phrases. The same rule applies to the use of the CELLS option with the LINES and CLINES phrases.
COLOR Phrase
{COLOR } IS color-val
{COLOUR}
1. The COLOR phrase provides an alternate method for setting video attributes. It also allows the specification of colors for screen fields and controls.
2. color-val can be set to different numeric values to express various combinations of colors and video attributes. You may make combinations by adding the appropriate values together. The following color values are accepted:
| Color
| Foreground
| Background
|
| Black
| 1
| 32
|
| Blue
| 2
| 64
|
| Green
| 3
| 96
|
| Cyan
| 4
| 128
|
| Red
| 5
| 160
|
| Magenta
| 6
| 192
|
| Brown
| 7
| 224
|
| White
| 8
| 256 |
| Reverse video
| 1024
|
| Low intensity
| 2048
|
| High intensity
| 4096
|
| Underline
| 8192
|
| Blink
| 16384
|
| Protected
| 32768
|
| Background low-intensity
| 65536
|
| Background high-intensity
| 131072 |
3. Only one foreground color and one background color may be specified. High intensity and low intensity may not both be specified. If neither is specified, the default intensity is used. If either the foreground or background color value is missing, then the corresponding default for the current subwindow is used. (Exception: some control types follow different rules for selecting the default color. These rules are described in chapter 5, Book 2, "User Interface Programming" in the sections that describe each control type).
When a control is assigned a non-zero foreground or background color, that component will no longer revert to the default when assigned the value "0" (zero). Instead, assigning "0" simply reassigns the current color. The runtime uses this behavior to preserve one component (foreground or background) when changing the other.
4. Other video attribute clauses (such as the REVERSED clause) may be specified along with the COLOR clause. The effects of all such clauses are used together. If any conflict exists, the COLOR clause takes precedence.
5. Reverse video exchanges the foreground and background colors.
6. If a terminal does not support color, then all non-black colors are mapped to white at runtime. If this results in a white-on-white combination, then the background color is set to black. However, if you explicitly specify identical foreground and background colors, then the characters will be invisible.
7. The "Protected" attribute applies to only Format 1 Screen Section entries. Any input or update field that has the "Protected" attribute set for it will be ignored during an ACCEPT statement. This enables you to selectively allow entry of certain data fields. Note that the "Protected" attribute does not affect the behavior of the DISPLAY statement.
8. When the COLOR phrase is used with controls, each control type determines the allowable set of colors. Each control class defines its own method of assigning default colors. Note that many host systems limit the ability to define a control's colors. The colors used will be as close to the requested colors as the host system allows.
COLUMN NUMBER Phrase
AT {COLUMN } NUMBER col-num
{COL }
{POSITION}
{POS }
1. The COLUMN phrase specifies the terminal column to use. Column number one (1) indicates the leftmost column of the current subwindow. A column number of zero (0) indicates the current cursor column.
2. When the COLUMN phrase is used with controls and floating windows, the COLUMN NUMBER refers to the left edge of the control or window. You may use CELL(S) or PIXEL(S) to specify the coordinates of controls. With cells, non-integer values are allowed, and with pixels, non-integer values are not allowed.
3. If the COLUMN phrase is missing, the results depend on the compatibility mode being used.
a) .In VAX COBOL and ICOBOL compatibility modes, the current cursor position is used unless the LINE phrase is specified. In this case, column one is used. This rule is always applied when controls are placed, regardless of the compatibility mode being used.
b) .In RM/COBOL compatibility mode, column one is used for the first ACCEPT or DISPLAY operand. For subsequent operands, the current cursor position is used (implies COLUMN 0).
4. If the column number specifies a column value greater than the number of columns in the current window, then one is added to the line number used, and the column number is reduced by the width of the window. This is repeated until the column number specifies a value that is contained within the window.
CONTROL Phrase
CONTROL cntrl-string
1. The CONTROL phrase provides the ability to modify the static attributes of the ACCEPT or DISPLAY statement at runtime. The CONTROL data item is treated as a series of comma-separated keywords that control the action of the statement. Within the CONTROL data item, spaces are ignored and lower-case letters are treated as if they were upper-case. When a CONTROL item conflicts with the statically declared attributes of the ACCEPT or DISPLAY statement, the actions specified in the CONTROL item take precedence.
The keywords allowed in cntrl-string are listed in the following groups. If more than one keyword from within a group appears in cntrl-string, only the rightmost one in the data item is used:
1. ERASE, ERASE EOL, ERASE EOS, NO ERASE.
2. BEEP, NO BEEP
3. HIGH, LOW, STANDARD, OFF
4. BLINK, NO BLINK
5. REVERSE, NO REVERSE
6. TAB, NO TAB
7. PROMPT, NO PROMPT
8. CONVERT, NO CONVERT
9. UPDATE, NO UPDATE
10. ECHO, NO ECHO
11. UPPER, NO UPPER, LOWER, NO LOWER
12. UNDERLINED, NO UNDERLINE
13. LEFT, RIGHT, CENTERED, NO JUST
14. SAME
15. FCOLOR
16. BCOLOR
2. Each of the keywords performs the same action as the statically declared attribute of the same name. The "NO" forms (NO ERASE, NO BLINK, etc.) cancel the effects of the named attribute.
The FCOLOR and BCOLOR keywords are used to set foreground and background colors respectively. These keywords must be followed by an equals sign and the name of a color taken from the following list: BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, and WHITE. The named color becomes the default foreground or background color for the window. Note that this is different from the COLOR phrase, which sets the color only for the current ACCEPT or DISPLAY statement. The FCOLOR and BCOLOR keywords set the default colors for every subsequent ACCEPT and DISPLAY until explicitly changed.
CONVERT Phrase
WITH {CONVERSION}
{CONVERT }
1. Specifying the CONVERT phrase allows non-USAGE DISPLAY items to be accepted or displayed. It also allows for automatic conversion of entered data into the internal format of the destination field.
2. In a DISPLAY statement, the CONVERT phrase affects only numeric and numeric edited data items. For numeric data items, leading zeros are converted into spaces, a decimal point is inserted (if needed), and a leading minus sign is inserted (if the value is negative). The result is then left-justified if RM/COBOL compatibility mode is being used. Numeric edited items are not converted, but they are justified in the same manner as numeric items. This form of the CONVERT phrase is called output conversion.
Floating-point data items are converted from internal format to E-notation.. The format of E-notation is as follows:
3. In an ACCEPT statement, the action of the CONVERT phrase depends on the data type of the receiving field:
a) A nonnumeric field receives the entered data as if it were the destination of a MOVE statement with an alphanumeric source. This causes justification and editing to have their normal effect.
b) A numeric or numeric edited field causes the ACCEPT statement to first check the data for correctness. Legal characters for numeric items include any characters that can appear in a numeric edited data item (digits, plus and minus sign, period, comma, currency symbol, "CR", "DB", and "*"). Any other non-space character is an error. Legal values are then assigned to the receiving field such that the algebraic value remains the same.
c) The input format for floating point numbers consists of the following components in the order given:
1. An optionally signed string of digits (possibly containing a decimal point)
2. An optional exponent field consisting of:
a. "E" or "e"
b. an optional + or -
c. an integer
See section 2.1.2.1 for additional information.
4. If the CONVERT phrase is not specified, the accepted data is placed in the receiving field from left to right with no editing or justification. In RM/COBOL compatibility mode, however, a numeric receiving field causes the data to be assigned from right to left instead.
5. For entries in the Screen Section, conversion is automatically used during input and not used during output. For this reason, Screen Section entries for non-integer numeric fields should specify a numeric edited PICTURE so that the decimal point is visible. Likewise, signed numeric fields should either specify SIGN SEPARATE or be represented by numeric edited items. Note that conversion occurs automatically for all controls.
6. If a conversion error occurs, the runtime system prints an error message and forces the user to correct the field. This behavior can be modified--for more information, see the ACUCOBOL-GT User's Guide, section 4.3.2.1 (subsection 3) "The KEYBOARD variable."
7. Several compile-time and run-time options are available to change various aspects of the CONVERT phrase, including the behavior of conversion errors and justification of the output of numeric items. For details, see the ACUCOBOL-GT User's Guide, section 2.1.8, "Video Options" (specifically the "-Vc" and "-Ve" options). Also, see the Terminal Manager chapter of the User's Guide, section 4.4.2, "The SCREEN Option."
DEFAULT Phrase
{DEFAULT [IS default]}
{UPDATE }
1. The DEFAULT phrase allows for a default value to be displayed in an input field ready for editing by the user. It is displayed in a form that can be accepted with the CONVERT phrase. For numeric receiving fields, this will cause leading spaces to be removed. If a default value is specified, then it is the value displayed. Otherwise the current value of the receiving field is used. The UPDATE phrase is equivalent to the DEFAULT phrase with no default value specified.
2. If the PROMPT phrase is also specified, then the prompt character replaces any trailing spaces in the field.
3. The DEFAULT phrase is automatically implied for any update field specified in the Screen Section. The DEFAULT phrase implies the CONVERT phrase in a Format 1 ACCEPT statement.
ECHO Phrase
ECHO
1. This causes the data entered to be redisplayed in the field. This allows for the action of the OUTPUT phrase to take place. Data will also be redisplayed with output conversion under the following circumstances:
a. In VAX COBOL and ICOBOL compatibility modes, if the CONVERT or UPDATE phrase is used.
b. In RM/COBOL compatibility mode, if the UPDATE phrase is used.
3. See the CONVERT phrase above for details on the effects of output conversion.
ENABLED Phrase
ENABLED {IS} {TRUE }
{= } {FALSE }
{enabled-state}
1. The ENABLED phrase determines whether or not the control can be used. When a control is enabled, it can be used normally. When it is disabled, it can be seen on the screen (if it is also visible), but the user cannot interact with it. If the TRUE phrase is used, then the control is enabled. The FALSE phrase makes the control disabled. If enabled-state is used instead, then its value determines whether the control is enabled. Any non-zero value enables the control; a value of zero (0) disables it. If the ENABLED phrase is omitted, the control is initially created enabled.
Disabled controls are displayed differently than enabled controls. For example, under Windows, disabled controls usually have dimmed text. See the configuration variable DISABLED-CONTROL-COLOR in Appendix H for information on how to configure the appearance of a disabled control when running on a character-based system.
{ERASE} [TO END OF] {LINE } (VAX, ICOBOL)
{BLANK} {SCREEN}
{ERASE} [EOS] (RM)
{BLANK} [EOL]
1. The ERASE phrase specifies that some or all of the current line or screen should be cleared to spaces. The spaces will use the currently selected background color for the active window. Cursor positioning occurs before the ERASE clause takes effect.
2. The ERASE LINE phrase causes the current line to be erased. The ERASE TO END OF LINE and ERASE EOL phrases both erase the line from the current cursor position to the end of the current window.
3. The ERASE and ERASE SCREEN phrases cause the current window to be cleared. The ERASE TO END OF SCREEN and ERASE EOS phrases cause the window to be erased from the current cursor position to the end of the window.
4. The cursor is not moved by these operations except in RM/COBOL compatibility mode, where ERASE (without the EOL or EOS phrases) specified on a Format 1 ACCEPT or DISPLAY verb causes the default cursor location to be line 1, column 1.
5. When ERASE SCREEN is specified in a Screen Section entry, and that entry either contains or is subordinate to a COLOR phrase, then the default window colors are changed to match that COLOR phrase. This also applies to the FOREGROUND-COLOR and BACKGROUND-COLOR phrases.
6. If a control has the TEMPORARY style and its upper-left location is within the erased area, the control will be destroyed. PERMANENT controls, however, are not affected.
FONT Phrase
FONT {IS} font-handle
{= }
1. Font-handle identifies the font to use for the control. If the font phrase is omitted, the window's default font for controls is used.
If you change a control's font after the control has been created, and its size is based on its font (true for controls that do not use the CELLS phrase), the control's dimensions are recomputed using the new font.
FOREGROUND-COLOR and BACKGROUND-COLOR Phrases
{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}
{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}
1. These phrases allow the specification of the foreground or background color. The color is a literal value taken from the following table:
| Value
| Color
|
| 0
| Black
|
| 1
| Blue
|
| 2
| Green
|
| 3
| Cyan
|
| 4
| Red
|
| 5
| Magenta
|
| 6
| Brown
|
| 7
| White
|
| 8
| Dark-Gray
|
| 9
| Bright-Blue
|
| 10
| Bright-Green
|
| 11
| Bright-Cyan
|
| 12
| Bright-Red
|
| 13
| Bright-Magenta
|
| 14
| Yellow
|
Each control type determines the allowable set of colors and the interpretation of foreground color and background color. If either the foreground color or background color is omitted (or its particular value is not meaningful), then default colors are used. Each control class defines its own method of assigning default colors. Note that many host systems limit the ability to define a control's colors. The colors used will be as close to the requested colors as the host system allows.
3. If both the COLOR phrase and the FOREGROUND-COLOR or BACKGROUND-COLOR phrase appear in the statement, the COLOR phrase takes precedence.
4. These phrases are provided for compatibility with other COBOL systems. Note that the color value must be an integer literal or a numeric data item, and it may be an arithmetic expression. Also note that the color number is one less than the corresponding color value in the COLOR phrase (this is done to maintain compatibility with other COBOLs). For a method of assigning colors that can be variable, see the COLOR phrase above.
FULL Phrase
{FULL }
{LENGTH-CHECK}
1. The FULL phrase applies only to input and update fields. When it is specified, the user must either leave the field blank or must enter non-space data into both the first and last character positions of the screen field. The user will not be able to leave the field until these requirements are met.
2. If the user types an exception key (and exception keys are allowed), then the ACCEPT will terminate without forcing the user to meet the requirements of the FULL phrase.
HELP-ID Phrase
HELP-ID {IS} help-id
{= }
1. The HELP-ID phrase establishes help-id as the control's help ID. The help ID is used in conjunction with certain events to provide context-sensitive application help. Usually, each control is given a unique, system-wide value so that it can be easily identified by the help processor. The maximum value of help-id is 2,147,483,647. For more information about HELP-ID and help automation, see chapter 10, Book 2, "User Interface Programming."
HIGH, LOW, and STANDARD Phrases
{HIGHLIGHT}
{HIGH }
{BOLD }
{LOWLIGHT }
{LOW }
{STANDARD }
1. The HIGH, LOW, and STANDARD phrases set the high/low video attributes for the input field. If the terminal hardware does not support high/low intensity, then these phrases are ignored.
2. HIGH sets the video attribute to high intensity. LOW sets the video attribute for the field to low intensity.
3. STANDARD sets the video attribute for the field to be the default intensity for the terminal type being used. This will either be high or low intensity depending on the terminal.
4. If none of these phrases is specified, STANDARD is used. This may be overridden by compile time options to set the default to either HIGH or LOW. For details, see the ACUCOBOL-GT User's Guide, section 2.1.8, "Video Options."
IDENTIFICATION Phrase
{IDENTIFICATION} {IS} control-id
{ID } {= }
1. Use control-id to assign a unique identifier to a control. This identifier is used any time that control must communicate with your program. It is returned with any messages from the control. You can examine the ID to distinguish which control sent the message. This can be more convenient than using the control's handle because you can assign a fixed identifier that is the same in every run of the program.
2. If control-id is omitted, then it will be treated as if it were zero (0), unless the control is defined in the Screen Section. In this case it will be assigned the same value as the control's field number (see Chapter 5, section 5.9, General Rules for Format 2, for a description of how Screen Section field numbers are assigned). Control IDs must be in the range of 0 to 32767.
KEY Phrase
KEY {IS} key-letter
{= }
1. The KEY phrase assigns a key letter to the control. The user can activate the control by typing its key letter in combination with some other special key. Under Microsoft Windows, key letters are typed in conjunction with the "Alt" key. The first character in key-letter becomes the control's key letter. The key letter can be given in lower- or upper-case.
2. If the KEY phrase is omitted, the control's key letter is derived from its title. (See the TITLE phrase for details.) If a key letter is not indicated in the title, the control does not have a key letter. If a key letter is designated in both the title and the KEY phrase, the KEY phrase takes precedence. If the letter specified in the KEY phrase is not the same as the letter indicated in the title, the letter indicated in the title is highlighted and the letter specified in the KEY phrase is the key letter (this could be confusing to the user).
3. The activation technique for key letters is shared with the menu bar handler on most systems. You should avoid assigning duplicate key letters in any one floating window, or assigning key letters that conflict with key letters used by the window's menu bar.
4. Controls that cannot be activated, such as a label, may have key letters (see the example that follows). In this case, the runtime system uses the following rules to determine which control to activate when the key letter is typed.
a. If another control has the same key letter, then the first control created with that key letter is activated when that key letter is pressed; otherwise
b. The next control that can be activated (in the same floating window) is activated. The runtime uses the order in which the controls were created to determine which control is next.
In practice, these rules mean that you can usually assign a key letter in the title of a label and use rule (b) to associate that key letter with a corresponding entry field. In this case, you do not need to use the KEY phrase. If rule (b) does not give you the effect you desire, you can use the KEY phrase and rule (a) to explicitly state the effect you want.
For example, the following Screen Section segment:
03 LABEL "&Customer: ". 03 ENTRY-FIELD USING CUST-NO, COLUMN + 2."
would assign a key letter of "C" to the label (using the implied key letter assignment from the label's title). Since labels cannot be activated, typing Alt-C would activate the CUST-NO entry field because it is the next control that can be activated.
LINE NUMBER Phrase
AT LINE NUMBER line-num
1. The LINE NUMBER phrase is used to position the cursor on a specific line or cell row of the terminal. A line number value of one indicates the top line of the current subwindow. To support fine positioning of controls in graphical environments, non-integer values are allowed. On text-mode systems, non-integer values are rounded down to the nearest whole number.
2. When used with controls and floating windows, the line number positions the top edge of the control or window.
3. If the LINE NUMBER phrase is missing or zero, then the results depend on the compatibility mode being used.
a) In VAX COBOL and ICOBOL compatibility modes, the current cursor line is used. This is used in all cases when the statement refers to controls.
b) In RM/COBOL compatibility mode, the current line is used if the COLUMN phrase specifies a value of zero or the NO ADVANCING phrase is used. Otherwise, the next line is used. In any case, if ERASE is also specified (without EOL or EOS), then line 1 is used instead.
4. If the line number results in a value greater than the number of lines in the current window, the current window is scrolled up one line, and the line number is set to be the bottom line of the current window.
This rule does not apply to controls. If a control is positioned outside of the current subwindow, it is not created.
5. You may use LINE NUMBER with different units, such as CELLS or PIXELS. PIXELS apply only with controls, and not with windows. Non-integer values are allowed with cells, but they are not allowed with pixels.
6. The LINE NUMBER phrase used for entries in the Screen Section has a different format. See section 5.9.4, "LINE Clause" for details.
LINES Phrase
LINES {IS} height
{= }
1. The LINES phrase is used to set a window or control's height. Note that each control type defines exactly how this value is interpreted.
Typically, the height field represents the logical height of the control. Frequently, this is based on the size of the control's title or value. For example, a LABEL control's height of "1" would specify a one-line label. If this phrase is omitted, the control type employs its own method of determining a default size.
2. The CELLS option of the LINES phrase causes the HEIGHT-IN-CELLS control style to be used. This means that the height of the control is specified exactly using the cell size of the owning window. For example:
LINES = 15 CELLS
causes the control to have a height of 15 cells, where the exact height of a cell is inherited from the parent window.
3. You may employ the PIXELS option with the LINES phrase to specify the control's size more precisely using the pixel size of the owning window. For example:
LINES = 60 PIXELS
NO ADVANCING Phrase
WITH NO ADVANCING
1. This phrase inhibits the normal carriage-return, line-feed sequence that is sent to the terminal. In VAX COBOL and ICOBOL compatibility modes, this sequence is normally sent after the ACCEPT or DISPLAY statement executes. In RM/COBOL mode, this sequence is sent before the statement executes. These characters can cause the current terminal window to scroll if the current line is the last line in the window.
2. This phrase is automatically implied when the LINE phrase is used. In VAX COBOL compatibility mode, this phrase is also implied when the COLUMN phrase is used. In RM/COBOL mode, this phrase is also implied when the COLUMN phrase is used with a zero value.
NO ECHO Phrase
{WITH NO ECHO}
{NO-ECHO }
{SECURE }
{OFF }
1. The NO ECHO phrase enables data to be entered without being displayed on the terminal screen. This can be used to enter passwords and other secure data.
OUTPUT Phrase
OUTPUT {JUSTIFIED} {LEFT }
{JUST } {RIGHT }
{CENTERED}
1. The OUTPUT phrase affects the alignment of displayed data. It has no effect in a Format 1 ACCEPT statement unless the ECHO phrase is also specified.
2. The LEFT option causes data to be justified to the left edge of the field, the RIGHT option causes right-justification, and the CENTERED option causes the displayed data to be centered in the field.
3. When the OUTPUT phrase is used, leading and trailing spaces are removed from the data before it is displayed. This is also done before the default size of the field is computed (except for Screen Section entries). Thus the three forms of justification are the same unless the SIZE phrase is also specified with a size larger than the data's length. Computing the default size after stripping the leading and trailing spaces allows fields to be concatenated together on the screen without computing column positions.
PROMPT Phrase
PROMPT [ CHARACTER IS prompt-lit ]
1. The PROMPT phrase causes the input field to be filled with the specified prompt character prior to entry. If the prompt character is omitted, underscores are used.
2. If the DEFAULT phrase is also used, then the prompt character replaces any trailing spaces in the field.
3. The PROMPT phrase is automatically used for every entry in the Screen Section. Thus this phrase is treated as commentary in the Screen Section unless it specifies a prompt character other than underscores.
PROPERTY and Property-Name Phrases
{ property-name } {IS } { prop-option [GIVING result-1] }...
{ PROPERTY property-type } {ARE}
{ method-name } {= }
{ object-expression }
where prop-option is one of the following:
{ property-value [ LENGTH {IS} length-1 ] }
{ {= } }
{ )
{ ( {property-value} ... ) }
{ }
{ { MULTIPLE } property-table }
{ { TABLE } }
{ }
{ parameter }
{ }
{ ( { parameter } ... ) }
1. The PROPERTY phrase assigns a value to one of a control's special properties or invokes a control-specific method. The PROPERTY phrase takes the types of only special properties and methods for controls (for a discussion of Common and Special properties, see section 5.1, Book 2, "User Interface Programming," for a discussion of Methods see section 4.5, Book 2, "User Interface Programming"). Each type of control has its own set of special properties and methods. These are described in the sections documenting each control type. Property-type specifies which special property to modify or which method to invoke (each of a control's special properties and methods is uniquely identified by a number). Property-value is the value to assign to that special property. Property-value must be a data type that is appropriate for the specified property. If property-type specifies a special property that does not exist, it is ignored for most control types. If the control type is ACTIVE-X, then an exception is raised (for a discussion of the ActiveX control types, see section 5.19, Book 2, "User Interface Programming") Each property's unique value is defined in the file "controls.def" or in the ActiveX control's copybook.
2. Property-name and method-name provide an alternate method for identifying which special property to modify or which method to invoke. The compiler knows the names of the special properties and methods that belong to each control type. In situations where the compiler knows which type of control is being acted upon, you can use the appropriate property-name or method-name directly instead of using the special property's or method's identifying number in the PROPERTY phrase.
For example, the MAX-TEXT special property of entry fields is property number "1". You can set the value of this property to "10" with either of the following phrases:
PROPERTY 1 = 10 MAX-TEXT = 10
The second method can be used only when your code makes it clear to the compiler that you're acting on an entry field.
You can use either the PROPERTY phrase or method-name to specify which method to invoke. For example, the LoadFile method of the Microsoft Rich Textbox Control is method number "37". You can invoke this method with either of the following phrases:
PROPERTY 37 ("myfile.rtf", rtfRtf)
LoadFile ("myfile.rtf", rtfRtf)
The second method can be used only when your code makes it clear to the compiler that you're acting on a Microsoft Rich Textbox Control.
3. Some properties return specific values when set. These values are placed in result-1 of the GIVING phrase. The meaning of the value depends on the property being set; see the documentation for the specific property. Properties that do not have a pre-defined return value set result-1 to "1" if the property was set successfully, or "0" if not. When a property is being given multiple values in a single assignment (for example: "Display-Columns = (1, 10, 30)"), then result-1 is set in response to the last value assigned.
4. When multiple special property assignments are made in a single statement, those assignments are performed in the order listed in the statement.
5. If more than one property-value is specified, each one is applied to the property in the order listed. This is normally used for cumulative properties. These are properties that perform some special action each time they have a value assigned to them. For example, you can set three columns in a list box with "DISPLAY-COLUMNS = ( 1, 20, 35 )". In the case of the DISPLAY-COLUMNS property, each time it is assigned a value, it sets a new column location. Note that the parentheses are required.
When you specify property-table, then each element of the table is assigned to the property. The elements are assigned in ascending occurrence order. For example, the following code fragment fills a list box with the names of three colors:
01 COLOR-NAMES.
03 PIC X(10) VALUE "Red".
03 PIC X(10) VALUE "Green".
03 PIC X(10) VALUE "Blue".
01 COLOR-TABLE REDEFINES COLOR-NAMES
OCCURS 3 TIMES
PIC X(10).
PROCEDURE DIVISION.
MAIN-LOGIC.
DISPLAY LIST-BOX, SIZE 10, LINES 3,
ITEM-TO-ADD = TABLE COLOR-TABLE.
6. When the LENGTH option is specified, length-1 establishes the exact size of property-value. The text value presented to the control must not contain trailing spaces or have trailing spaces added. When you specify the LENGTH option, the control uses exactly the number of characters of length-1. However, if length-1 is a value larger than the size of the data item it is modifying, the size of the data item is used instead. If length-1 is negative, it is ignored and the default handling occurs.
7. {parameter}... is a list of parameters to pass when invoking one of a control's methods or setting a multiple-parameter property. When setting a multiple-parameter property, the first parameters identify which aspect of the property to set. The last parameter is the actual property value. For example, to set the the Microsoft Chart Control DataGrid::RowLabel property you must specify the row number and label index. You could use the following phrase:
DataGrid::RowLabel( ROW-NUMBER, ROW-LABEL-INDEX,
"My Row Label" )
8. Object-expression can only be used in the procedure division, not the screen section. It has the following format:
{ {^} property-1 [ ( param-1 ... ) ]
[ :: property-2 [ ( param-2 ... ) ] ]... }
Object-expression specifies a property or method of an object referenced by another object. This object in turn can be referenced by yet another object. The "root" object can be an ActiveX control or OLE object or a graphical control. "^" can only be used in conjunction with Format 5 USE verb (see the documentation for the USE verb for more information). Property-1 is the name of a property of the ActiveX control or OLE object. Property-1 must not be a write-only property. Property-2 is the name of a property of the ActiveX control or OLE object which is the value of property-1. Property-2 must not be a write-only property. Param-1 and param-2 are literals, data items or numeric expressions. Param-1 is the first parameter passed when getting the value of property-1 and param-2 is the first parameter passed when getting the value of property-2.
For example, to set the Microsoft Chart Control legend, you get the value of the Legend property. This value is an object that you may then modify to change the legend. The Legend object has properties whose values are other objects, and so on. The following phrases set properties and invoke methods of the MS Chart Legend object:
Legend::Location::Visible = 1
Legend::Location::LocationType = VtChLocationTypeRight
Legend::TextLayout::HorzAlignment =
VtHorizontalAlignmentRight
Legend::VtFont::VtColor::Set (255, 255, 0)
Legend::BackDrop::Fill::Style = VtFillStyleBrush
Legend::BackDrop::Fill::Brush::Style = VtBrushStyleSolid
Legend::BackDrop::Fill::Brush::FillColor::Set (255, 0, 255)
or assuming the handle to the Microsoft Chart Control is MS-CHART-1:
USE MS-CHART-1 Legend
MODIFY ^Location::Visible = 1
^Location::LocationType = VtChLocationTypeRight
^TextLayout::HorzAlignment =
VtHorizontalAlignmentRight
^VtFont::VtColor::Set ( 255, 255, 0 ).
USE MS-CHART-1 Legend::BackDrop::Fill
MODIFY ^Style = VtFillStyleBrush
^Brush::Style = VtBrushStyleSolid
^Brush::FillColor::Set ( 255, 0, 255 ).
REQUIRED Phrase
{REQUIRED }
{EMPTY-CHECK}
1. The REQUIRED phrase applies only to input and update fields. When it is specified, the user may not leave the field empty--some non-blank data must be entered. If the receiving field is numeric or numeric edited (and input conversion is being used), then the entered value may not be zero. The user will not be able to leave the field without meeting these requirements.
2. In a Screen Section, the REQUIRED phrase forces the user to enter data in the field before terminating the ACCEPT.
This prevents the user from jumping to the last field with the mouse, and thus bypassing a required field. If the user attempts to terminate an ACCEPT while required fields are still blank, an error message is displayed and the cursor is positioned at the first required field that is blank.
3. If the user types an exception key (and exception keys are allowed), the ACCEPT will terminate without forcing the user to meet the requirements of this phrase. Note that leaving a field by clicking on another control with the mouse will cause the REQUIRED check to occur. Therefore, "CANCEL" buttons should always have the SELF-ACT style. The SELF-ACT style does not cause the runtime to change the focus of the current control - the input or update field is not left - and the REQUIRED phrase is not triggered. Without the SELF-ACT style, the CANCEL button will cause focus to shift to itself, triggering the REQUIRED check and preventing the user from "canceling" without first entering some data.
REVERSED Phrase
{REVERSE-VIDEO}
{REVERSE }
{REVERSED }
1. The REVERSED phrase causes the field to have reversed foreground and background colors. If the terminal hardware does not support reverse-video, then this phrase is ignored.
SAME Phrase
SAME
1. The SAME phrase causes the field to use the video attributes currently present at the field's screen location. This allows data on the screen to be changed without changing the screen's video attributes.
2. The SAME phrase may not be specified along with the UNDERLINED, BLINK, REVERSED, HIGH, LOW, STANDARD, COLOR, FOREGROUND-COLOR, or BACKGROUND-COLOR phrases.
SCROLL Phrase
SCROLL [UP ] [ BY scrl-num {LINE } ]
[DOWN] {LINES}
1. The SCROLL phrase specifies the number of lines to scroll the current window. Scrolling is the first operation performed by the ACCEPT or DISPLAY statement--it occurs before any cursor positioning or the operation of any ERASE clauses. Scrolling does not affect the current cursor position.
2. If the UP phrase is specified, the contents of the current window are scrolled upward (normal scrolling). If DOWN is used, then the contents are moved downward (reverse scrolling). A blank line with the default video attributes for the window is introduced at the top or bottom of the window (as appropriate). Upward scrolling is used if neither the UP nor DOWN phrase is specified.
3. If a scrolling value is specified, its value is the number of lines to scroll the screen. If this value is not positive, no scrolling occurs. If the scrolling value is omitted, one line is scrolled.
SIZE Phrase (with a text entry field)
PROTECTED SIZE length
1. The SIZE phrase specifies the size (length) of the field. After the ACCEPT or DISPLAY is finished, the cursor is placed immediately after the field defined by this clause, unless this would place the cursor outside of the current terminal window. In this case, the cursor is wrapped around to the beginning of the next line (scrolling the window if necessary).
2. If the SIZE phrase is not used, then the field length defaults to the size of the item being accepted or displayed. If the CONVERT phrase is used, however, then the size of the field depends on the data type of the item and the verb being used:
a) If the DISPLAY verb is executing, then the size is the same as if the CONVERT phrase were not specified except for numeric items. For numeric items, the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed. This rule also applies to the action of the ECHO phrase of the ACCEPT statement (see below). The remaining cases cover the size when an ACCEPT statement is used.
b) If the item is numeric or numeric edited, then the size is the number of digits in the item, plus one if it is not an integer, plus one if it is signed.
c) If the item is alphanumeric edited, then the size is set to the number of "A" or "X" positions specified in its PICTURE clause.
d) For all other data types, the field size is set to the size of the item (same as if CONVERT were not specified).
SIZE Phrase (with Windows and Controls)
SIZE {IS} length [CELL ]
{= } [CELLS ]
[PIXEL ]
[PIXELS]
1. The SIZE phrase is used to set a window or control's width (length). Non-integer values are allowed. Note that each control type defines exactly how this value is interpreted.
Typically, the length field represents the logical width of the control. Frequently, this is based on the size of the control's title or value. For example, an ENTRY-FIELD's width of "8" would specify a field large enough to enter eight (average size) characters. If this phrase is omitted, the control type employs its own method of determining a default size.
2. The CELLS option of the SIZE phrase causes the WIDTH-IN-CELLS control style to be used. This means that the width of the control is specified exactly using the cell size of the owning window. For example:
SIZE = 15 CELLS
causes the control to have a width of 15 cells, where the exact width of a cell is inherited from the parent window.
3. You may use the SIZE phrase with PIXELS when defining controls. This means that the width of the control is specified exactly using the pixel size of the owning window. For example:
SIZE = 150 PIXELS
causes the control to have a width of 150 pixels, where the exact width of a pixel is inherited from the parent window. Non-integer values are not allowed with pixels.
STYLE Phrase and Style-Name
STYLE {IS} style-flags
{= }
{style-name} ...
1. In the STYLE phrase, style-flags is a numeric field that holds a value that specifies the styles to apply to the control. Each control type defines its own set of styles and how the style-flags value is interpreted. Style-flags holds the sum of the numbers that represent the desired styles. Each style's identifying number is defined in the file "controls.def". If style-flags is omitted, the default style attributes are applied to the control.
2. A style-name is the name of a valid style for the type of control being acted upon. For example, some of the styles that apply to a radio-button include: BITMAP, FRAMED, and NOTIFY. Each style-name causes that style to be applied to the control.
3. You may use both the STYLE phrase and individual style-names for a particular control. The effect is to add the set of specified styles together. You would typically use the STYLE phrase to specify styles that may change at runtime, and style-name for those styles that are fixed.
For more information about control styles, and the STYLE and style-name phrases, see chapter 4, Book 2, "User Interface Programming."
TAB Phrase
TAB
1. The TAB phrase forces the user to finish entering data by typing a valid termination key. It is the opposite of the AUTO phrase. The TAB phrase is the default behavior except in a Format 1 ACCEPT statement when you are using RM/COBOL compatibility mode.
TITLE Phrase
TITLE {IS} title
{= }
1. The value of title sets the control's title. If title is omitted, then the control does not have a title. Some controls (such as entry fields, list boxes, and combo boxes) do not have titles. In these cases, any specified title is ignored.
2. If you change the title of a control and that control was created with the default sizing rules (did not have a size explicitly specified for it), the control is resized based on the length of the new title.
3. You can specify a key letter in a title by including the "&" character immediately before the key letter. The key letter is usually highlighted by the host system (under Windows, the key letter is underlined). The "&" character both defines the key letter and performs the highlighting. The key letter indicates that the user can go to the appropriate field by typing the key letter in combination with another key. Exactly how this occurs is system dependent. Under Windows, the user presses the "Alt" key in conjunction with the key letter. Some systems do not support key letters, in which case the first "&" character in a title is ignored. When the KEY phrase is used and an "&" character appears in title, the KEY phrase specifies the key letter and the character following the "&" indicates the highlighted character.
UNDERLINED Phrase
{UNDERLINE }
{UNDERLINED}
1. The UNDERLINED phrase causes the field to have the underscore video attribute applied to it. If the terminal hardware does not support underlining, then this phrase is ignored. UNDERLINED cannot be combined with BLINK.
UPON Phrase
UPON new-window
1. The UPON phrase is used to update a floating window that is not the current floating window. In this phrase new-window is a USAGE HANDLE or PIC X(10) data item that contains a valid floating window handle. The floating window specified by new-window becomes the current window for the duration of the DISPLAY statement.
2. If you create a new floating window while in the scope of the UPON phrase, the new window becomes the current window after the DISPLAY statement terminates. Otherwise, the window that was current before the DISPLAY UPON statement executed is restored to the current window. For example, if the main application window is current and you execute:
DISPLAY FLOATING WINDOW UPON MAIN-WINDOW, ...
when the DISPLAY statement terminates, the new floating window becomes the current window, instead of the main application window.
The above code creates a new subwindow in WINDOW-1 and then displays two lines in the new subwindow. The UPON WINDOW-1 phrase applies to both the DISPLAY SUBWINDOW operation and the display of the subsequent text items because they are all specified in one DISPLAY statement.
3. When you mix several DISPLAY formats, the logic to determine the current window is applied sequentially through the statement. Here is a complex example:
DISPLAY FLOATING WINDOW UPON WINDOW-1 LINES 10, SIZE 40, BOXED, HANDLE IN WINDOW-99; "Line 1", LINE 1, "Line 2", UPON WINDOW-2, LINE 2 "Line 3", LINE 3.
In this example, the new floating window (WINDOW-99) is created with WINDOW-1 as its parent (because of the first UPON phrase). Normally, this UPON phrase would cause "Line 1" to display in WINDOW-1 too, but the DISPLAY FLOATING WINDOW operation causes the new window to become the current window. So, "Line 1" is shown in WINDOW-99 instead. This would apply to "Line 2" also, but it specifies its own UPON phrase, so it displays in WINDOW-2. "Line 3" also displays in WINDOW-2 because that was the last window specified. At the end of the DISPLAY statement, the new floating window, WINDOW-99, is made the current window.
UPPER and LOWER Phrases
{UPPER}
{LOWER}
1. When the UPPER phrase is specified, all lower-case characters received by the ACCEPT statement are converted to upper-case. If the LOWER phrase is specified, all upper-case characters are converted to lower-case. If the ECHO phrase is also specified, the redisplayed data will be in the converted form.
VALUE {IS} [ MULTIPLE ] value
{= } [ TABLE ]
1. Value sets the value of the control. If the control does not take a value, then the VALUE phrase is ignored. The exact interpretation of value depends on the type of control. A control's value is either an integer or an alphanumeric string. If the control takes an integer value, then value should specify a numeric literal or data item. If the control takes an alphanumeric string, then value may be either numeric or alphanumeric. If value is numeric, it is converted to an alphanumeric string that represents its numeric value.
2. The MULTIPLE phrase is used only with certain control types that allow for multiple values. Its use is described in the sections that discuss those controls. The Screen Section VALUE phrase has some additional rules. See Chapter 5, section 5.9 for details. TABLE is a synonym for MULTIPLE.
VISIBLE Phrase
VISIBLE {IS} {TRUE }
{= } {FALSE }
{visible-state}
1. The VISIBLE phrase determines whether or not the control is shown on the screen. If the VISIBLE phrase is set to TRUE, the control is shown. If it is set to FALSE, the control is invisible. If visible-state is used instead, then its value determines whether the control is shown. Any non-zero value indicates that the control is visible; zero indicates that it is invisible. Controls that are invisible do not appear on the screen and cannot be used. They continue to exist, however, and can be made visible subsequently in the program. If the VISIBLE phrase is omitted, then the control is initially made visible.
ZERO-FILL and NUMERIC-FILL Phrases
{ZERO-FILL }
{NUMERIC-FILL}
1. The ZERO-FILL and NUMERIC-FILL phrases may be applied only to alphanumeric input or update fields. These phrases are ignored for output fields. Only one of these options may be specified for a single field.
2. The ZERO-FILL phrase causes trailing spaces in the entered data to be replaced by the "0" character. If the destination is JUSTIFIED, then leading spaces will be replaced instead.
3. The NUMERIC-FILL phrase causes the runtime system to examine the entered data. If the entered value consists entirely of digits and trailing spaces, then the entered digits are right justified and the leading character positions are replaced by the "0" character. If the entered data is empty, or contains any non-digit characters, the data is left alone.