A screen description entry specifies the characteristics of a single screen item. Many of the phrases permitted in a Screen
Description Entry are explained in
Common Screen Options.
General Format
Format 1
level-number [ screen-name ]
[ FILLER ]
Remaining phrases are optional, can appear in any order.
GRAPHICAL
CHARACTER
{PICTURE} IS picture-string
{PIC }
[ [FROM from-item] [TO to-item] ]
[ USING using-item ]
[USAGE IS] DISPLAY
[SIGN IS] {LEADING } SEPARATE CHARACTER
{TRAILING}
OCCURS table-size TIMES
{JUSTIFIED} RIGHT
{JUST }
BLANK WHEN ZERO
VALUE IS value-lit
{BLANK} {SCREEN}
{ERASE} {LINE }
{EOS }
{EOL }
LINE [ NUMBER IS [PLUS] line-no ]
[ + ]
[ - ]
{COLUMN } [ NUMBER IS [PLUS] col-no ]
{COL } [ + ]
{POSITION} [ - ]
{POS }
SIZE IS length
COLOR IS color-val
COLOUR
FOREGROUND-COLOR IS fg-color
FOREGROUND-COLOUR
BACKGROUND-COLOR IS bg-color
BACKGROUND-COLOUR
{BACKGROUND-HIGH }
{BACKGROUND-LOW }
{BACKGROUND-STANDARD }
{BELL}
{BEEP}
{UNDERLINED}
{UNDERLINE }
{HIGHLIGHT}
{HIGH }
{BOLD }
{LOWLIGHT }
{LOW }
{STANDARD }
{BLINKING}
{BLINK }
{REVERSE-VIDEO}
{REVERSED }
{REVERSE }
SAME
OUTPUT {LEFT }
{RIGHT }
{CENTERED}
{NO-ECHO}
{NO ECHO}
{SECURE }
{OFF }
PROMPT [ CHARACTER IS prompt-lit ]
{UPPER}
{LOWER}
{AUTO }
{AUTO-SKIP }
{AUTOTERMINATE}
{TAB }
{REQUIRED }
{EMPTY-CHECK}
{FULL }
{LENGTH-CHECK}
{ZERO-FILL }
{NUMERIC-FILL}
HELP-ID {IS} help-id
{= }
ENABLED {IS} enabled-state
{= }
VISIBLE {IS} visible-state
{= }
{BEFORE } PROCEDURE IS { proc-1 [{THROUGH} proc-2] }
{AFTER } {THRU }
{EXCEPTION} { NULL }
Format 2
level-number [ screen-name ]
[ FILLER ]
{control-type-name}
{OBJECT control-type}
[ title ]
Remaining phrases are optional, can appear in any order.
GRAPHICAL
CHARACTER
{IDENTIFICATION} {IS} control-id
{ID } {= }
{PICTURE } IS picture-string
{PIC}
{FROM } [MULTIPLE] from-item
{VALUE} [TABLE ]
TO [MULTIPLE] to-item
{USING} [MULTIPLE] using-item
{VALUE} [TABLE ]
OCCURS table-size TIMES
LINE [ NUMBER IS [PLUS] line-no ] [CELL ]
[ + ] [CELLS ]
[ - ] [PIXEL ]
[PIXELS]
{COLUMN } [ NUMBER IS [PLUS] col-no ] [CELL ]
{COL } [ + ] [CELLS ]
{POSITION} [ - ] [PIXEL ]
{POS } [PIXELS]
CLINE NUMBER cline-num
CCOL NUMBER ccol-num
SIZE {IS} length [CELL ]
{= } [CELLS ]
[PIXEL ]
[PIXELS]
LINES {IS} height [CELL ]
{= } [CELLS ]
[PIXEL ]
[PIXELS]
CSIZE {IS} clength [CELL ]
{= } [CELLS]
CLINES {IS} cheight [CELL ]
{= } [CELLS]
MAX-HEIGHT {IS} max-height
{= }
MAX-WIDTH {IS} max-width
{= }
MIN-HEIGHT {IS} min-height
{= }
MIN-WIDTH {IS} min-width
{= }
TITLE {IS} title
{= }
KEY {IS} key-letter
{= }
STYLE {IS} style
{= }
{style-name} ...
FONT {IS} font-handle
{= }
{COLOR } IS color-val
{COLOUR}
{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}
{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}
{BACKGROUND-HIGH }
{BACKGROUND-LOW }
{BACKGROUND-STANDARD }
{BELL}
{BEEP}
{HIGHLIGHT}
{HIGH }
{BOLD }
{LOWLIGHT }
{LOW }
{STANDARD }
{REVERSE-VIDEO}
{REVERSED }
{REVERSE }
{REQUIRED }
{EMPTY-CHECK}
LAYOUT-DATA {IS} layout-data
{= }
ENABLED {IS} {enabled-state}
{= }
VISIBLE {IS} {visible-state}
{= }
HELP-ID {IS} help-id
{= }
EVENT-LIST {IS} ( event-value { event-value ... } )
{= }
AX-EVENT-LIST {IS} ( ax-event-value { ax-event-value ... } )
{= }
EXCLUDE-EVENT-LIST {IS} list-state
{= }
{property-name } {IS } { property-value }
{PROPERTY property-type } {ARE} { ( {property-value} ... ) }
{= } { {MULTIPLE} property-table }
{TABLE }
{BEFORE } PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
{AFTER } {THRU }
{EXCEPTION} { NULL }
{EVENT }
Format 3
level-number [ screen-name ]
[ FILLER ]
{assembly-name}
{OBJECT assembly-name}
[ title ]
NAMESPACE { IS } "namespace"
CLASS-NAME { IS } "class-name"
Remaining phrases are optional.
HANDLE { IS } handle-1
VERSION { IS } "version"
CULTURE { IS } "culture"
STRONG-NAME { IS } "strong-name"
CONSTRUCTOR { IS } CONSTRUCTOR[n] parameters...
MODULE { IS } "module"
FILE-PATH { IS } "file-path"
SIZE {IS} length [CELL ]
{= } [CELLS ]
[PIXEL ]
[PIXELS]
LINES {IS} height [CELL ]
{= } [CELLS ]
[PIXEL ]
[PIXELS]
Syntax Rules
- Each screen description entry must start with a
level-number from 01 through 49.
- Each level 01 screen description entry must have a
screen-name specified.
screen-name is a user-defined word.
- A
screen-name may be referenced only in those contexts where it is explicitly allowed.
- An ACCEPT statement may reference only a
screen-name that has a TO or USING clause specified for it, or is a group item that contains such a screen entry.
- from-item and
using-item are data items.
- to-item is a literal or a data item.
- table-size is an integer literal.
- fg-color,
bg-color,
cline-num,
ccol-num,
clength,
cheight,
color-val,
control-id,
layout-data,
enabled-state,
visible-state, and
help-id are integer literals or data items.
- max-height,
max-width,
min-height, and
min-width are numeric data items or numeric literals.
- line-no,
col-no,
length, and
height are numeric literals or data items. In Format 1, these must be integer values.
- value-lit is a alphanumeric literal or a figurative constant.
- prompt-lit is a single-character alphanumeric literal or the figurative constant SPACE, ZERO, or QUOTE.
- control-type-name is one of the control type reserved words known by the compiler.
- control-type is a numeric literal or data item. It may not be subscripted or reference modified.
- title and
key-letter are alphanumeric literals or data items.
- font-handle is a USAGE HANDLE or HANDLE OF FONT data item that contains a valid font handle.
- syle-name is the name of a style associated with the class of control being described. If the
control-type-name phrase is omitted, then you may not use the
style-name phrase. The STYLE phrase may be used instead.
- property-name is the name of a property specific to the type of control being referenced. If the type of control is unknown to the compiler
(as in a
DISPLAY OBJECT object-1 statement), then
property-name may not be used. You must use the PROPERTY
property-name option instead.
- property-name is a numeric literal or data item. It may not be subscripted or reference modified. It identifies the property to use. The
numeric values that identify the various control properties can be found in the COPY library
controls.def.
- property-value is a literal or data item. Note that the parentheses in the phrase are required.
- property-table is a data item that appears in a one-dimensional table. No index should be specified.
- In Format 1, if the PICTURE clause is used, then at least one of the FROM, TO, or USING clauses must also be used. The VALUE
clause cannot be used. In Format 2, if the PICTURE clause is used, then you must specify one of the FROM, TO, USING, or VALUE
phrases.
- The MULTIPLE option and the PICTURE phrase cannot be used in the same entry.
- The JUSTIFIED and BLANK WHEN ZERO clauses may be specified only if the PICTURE clause is also specified.
- The COLOR clause may not be specified if either the FOREGROUND-COLOR or BACKGROUND-COLOR clause is specified.
- You may not use either the FROM or TO phrase if you use the USING phrase.
- In a Format 1 entry, if the VALUE phrase is used, then its meaning depends on the following data element. If it is a literal,
then VALUE is synonymous with FROM. Otherwise, it is synonymous with USING.
- If you use the MULTIPLE option of either the FROM, TO, or USING phrase, the following data element must contain an OCCURS
clause or be subordinate to an OCCURS clause. The corresponding table must be one-dimensional. The data element should not
be subscripted.
- The following items may reference a table containing the appropriate type of data items, providing its entry is subordinate
to an OCCURS clause: COLOR, HELP-ID, VISIBLE, ENABLED, ID, STYLE, FONT, TITLE, LINE, COL, SIZE, LINES, CCOL, CLINE, CSIZE,
CLINES, KEY, and PROPERTY. See the description of the
OCCURS Clause.
- In Format 1, HELP-ID, VISIBLE, and ENABLED may be specified only for group items. The effect is to apply the phrase to each
control contained in the group. You can override the setting for a particular control or sub-group by specifying another HELP-ID,
VISIBLE, or ENABLED phrase. These phrases have no effect on screen items that are not controls.
- event-value and
ax-event-value are numeric literals or data items that identify an event type. List elements must be enclosed by parentheses. Elements must
be separated by a space. If the list contains a single element, the parentheses can be omitted.
- list-state is an integer literal or numeric data item. Valid values are
0 and
1.
- assembly-name is the name of a .NET assembly defined in a COPY file created by NETDEFGEN. This must be the DLL name of a graphical control,
not an executable file. Graphical controls are generated by Visual Studio when a developer selects a
Windows Control Library project type.
- handle-1 is a USAGE HANDLE or PIC X(10) data item.
- A value surrounded by quotation marks is an alphanumeric literal and is case-sensitive. Literal values for assembly parameters
are located in the COPY file generated by NETDEFGEN. The same COPY file must be included in the SPECIAL-NAMES paragraph of
your program.
- The optional phrases may be specified in any order.
- CELL(S) and PIXEL(S) are mutually exclusive for the same phrase.
- In Format 2, the PLUS phrase requires PIXEL(S) to follow if the preceding LINE Number or COLUMN Number also used PIXEL(S).
- You may mix PIXEL and conventional coordinates/sizing in the same statement, as shown here:
DISPLAY push-button AT 00100200 PIXELS
LINES 50 PIXELS
SIZE 5.
- CELL and CELLS are equivalent.
- PIXEL and PIXELS are equivalent.
- IS and "=" are synonymous.
Note: Because the Screen Section is not part of ANSI-standard COBOL, there is substantial variation in the syntax supported by
various COBOL vendors. ACUCOBOL-GT supports a superset of most other Screen Section implementations. This situation results
in a large number of reserved words with the same meaning. These synonyms are detailed in each of the following rules. We
recommend that you restrict yourself to one of the synonyms for each option in order to improve your program's clarity.
- AUTO, AUTO-SKIP, and AUTOTERMINATE are equivalent.
- NO-ECHO, NO ECHO, OFF, and SECURE are equivalent.
- PIC is an abbreviation for PICTURE.
- JUST is an abbreviation for JUSTIFIED.
- BLANK and ERASE are equivalent.
- COLUMN, COL, POSITION, and POS are equivalent.
- BELL and BEEP are equivalent.
- UNDERLINE and UNDERLINED are equivalent.
- HIGHLIGHT, HIGH, and BOLD are equivalent.
- LOWLIGHT and LOW are equivalent.
- BLINK and BLINKING are equivalent.
- REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
- REQUIRED and EMPTY-CHECK are equivalent.
- FULL and LENGTH-CHECK are equivalent.
- MULTIPLE and TABLE are equivalent.
General Rules
- When a
screen-name is referenced by an ACCEPT or DISPLAY statement, that screen entry and all subordinate screen entries are acted upon at once.
This allows you to accept or display many fields with one statement.
- The word NULL in the PROCEDURE phrase indicates that there is no procedure. It has the same effect as omitting the PROCEDURE
phrase altogether and is essentially commentary.
- Screen Section entries may include the labels
GRAPHICAL and
CHARACTER. These markings have the effect of restricting the display of the elements nested within them. The elements contained in
a GRAPHICAL Screen Section entry are displayed only when the program is run on a graphical system. The contents of a CHARACTER
Screen Section entry are displayed only when the program is run on a character-based system. When the program attempts to
execute a marked entry on a system of the opposite type, that entry is ignored.
The purpose of these phrases is to better allow you to develop and support two distinct user interfaces in one program; a
user interface for graphical systems, and a user interface for character-based systems. The GRAPHICAL and CHARACTER labels
allow you to place and maintain all of the screen definition code in one place (the Screen Section), while also allowing you
to customize the look and function of the user interface for these two classes of systems. For many developers, this approach
is easier and produces more satisfying results than attempting to develop a single, generic user interface that works well
on both types of systems.
The following code provides an example of this approach. Suppose you want a label that describes a set of function keys to
be displayed along the bottom of the screen. However, when you run the program on a graphical system you want to display push
buttons instead.
A Screen Section entry to do this might look like:
01 function-key-screen.
03 line 24.
03 character.
05 "F1 = Exit, F2 = Lookup, F3 = Help".
03 graphical.
05 push-button, "E&xit", self-act,
exception-value = 1,
column 3.
05 push-button, "&Lookup", self-act,
exception-value = 2,
column + 3.
05 push-button, "&Help", self-act,
exception-value = 3,
column + 3.
When the program executes a "DISPLAY FUNCTION-KEY-SCREEN" statement, it displays the line of text on character-based systems,
or the set of push buttons on a graphical system.
Note: The use of these labels also allows you to create two screen description entries with the same name. In statements where
a Screen Section name is allowed, you may now reference an ambiguous (duplicate) Screen Section name. When you do so, the
name must resolve to exactly two Screen Section items, one having the CHARACTER attribute and the other having the GRAPHICAL
attribute. The compiler constructs conditional code for these cases. The Screen Section item with the CHARACTER attribute
is used when the program runs on a character-based system; the GRAPHICAL item is used on graphical host systems. One use for
this feature is to keep a program's original screen layouts for use on character systems while creating all new screens for
graphical systems. By giving the screens the same name, you can keep the existing processing logic unchanged.
Format 1 Only Rules
- A Format 1 statement describes any of three types of screen description entries:
- If a VALUE clause is specified, the screen entry is a display literal.
- If a PICTURE, TO, FROM, or USING clause is specified, then the screen entry is a data field.
- If VALUE, PICTURE, TO, FROM, or USING is not specified, then the screen entry is a group item.
- A LINE, COLUMN, BLANK, or BELL clause specified for a group item is acted upon immediately when that group item is accessed
by an ACCEPT or DISPLAY statement. All other clauses specified for a group item are applied to each screen entry subordinate
to that group item.
- If the same clause is specified more than once for a particular screen entry, the clause specified at the lowest level within
the hierarchy is the one which takes effect.
- The
level-number,
screen-name, USAGE, SIGN, JUSTIFIED, and BLANK WHEN ZERO clauses follow the rules for data items appearing in Working Storage. These
rules are in
Data Description Entry.
- The PICTURE, OCCURS, and VALUE clauses have meanings similar to those clauses in Working Storage, but have some additional
properties when used in the Screen Section.
- The HELP-ID, VISIBLE, and ENABLED phrases may be specified only for group items. The effect is to apply the phrase to each
control contained in the group. You can override the setting for a particular control or sub-group by specifying another HELP-ID,
VISIBLE, or ENABLED phrase. These phrases do not affect screen items that are not controls.
- All other clauses are described in
Common Screen Options.
Format 2 (SCREEN CONTROLS) only Rules
- A Format 2 Screen Section entry defines a screen control.
- control-type-name identifies the type of the control. Use the OBJECT
control-type phrase when the type of the control is not known at compile time.
control-type must contain the identifying number of a control type known to the system. If it does not correspond to any control type,
the Screen Section entry is ignored. The identifying number of each control type is defined in the
controls.def file.
- When you DISPLAY a Screen Section control, the following steps are performed:
- If this is the first DISPLAY of this control, the runtime builds a new control of the specified type.
- The various properties specified by the Screen Section control phrases are set. Unspecified properties are then assigned default
values when the control is initially created. Properties are assigned in the order listed in the Screen Section, except that
the VALUE property is always assigned last.
- The control is displayed or updated on the screen.
- The cursor is positioned after the control.
- When you ACCEPT a Screen Section control, that control receives the input focus, and the runtime system processes user actions
until the user terminates the ACCEPT according to the rules for the ACCEPT verb.
- When you DISPLAY a Screen Section group item, each subsidiary Screen Section entry is displayed. This can be a mix of textual
fields and graphical controls. When you ACCEPT a Screen Section group item, the cursor (or input focus) is placed according
to the rules for the ACCEPT verb, and the runtime proceeds to accept data from the user for each field or control. The runtime
automatically handles cursor movements between the fields and controls.
- Screen Section controls are assigned field numbers in the same way as Format 1 Screen Section entries. If the control is activatable
(the user can interact with the control), it is given a field number. Controls that cannot take user input (e.g., LABEL controls)
are not given field numbers. Field numbers are assigned sequentially, starting with
1, for each appropriate Format 1 or Format 2 Screen Section entry subordinate to a given 01-level group item. For Screen Section
controls that omit the ID phrase, but have an implied field number, the corresponding control is given that field number as
its ID.
Note that the field number is not assigned until the control is created.
- If you specify a PICTURE, the memory for that picture is allocated in the Screen Section entry. Each DISPLAY of that entry
moves the data in the FROM or USING data item to itself using the standard MOVE rules. That entry is then used as the value
of the control. Each ACCEPT of that entry stores the control's value in the Screen Section entry and then moves the entry
into the TO or USING data item in accordance with the standard MOVE rules. If you omit the PICTURE phrase, the control's value
is retrieved directly from the FROM or USING item and stored directly in the TO or USING item. Note that specifying a PICTURE
allocates additional memory. As a result, it is preferable to specify a PICTURE only in cases where you need to reformat the
data (e.g., by specifying a numeric-edited PICTURE).
- The MULTIPLE phrase in the FROM, TO, or USING clause indicates that you want the control's value to be mapped to the corresponding
data item on a line-by-line basis. Each line of data in the control corresponds to one element in the data table. This should
be used only with controls that have the concept of multiple lines of data (e.g., an ENTRY-FIELD that contains multiple lines
of text). For example, the following Working-Storage and Screen Section definitions would construct a five-line entry field
on the screen, and place each line of input into a separate data item in the Working-Storage table:
WORKING-STORAGE SECTION.
01 ENTRY-LINES OCCURS 5 TIMES PIC X(30).
SCREEN SECTION.
01 ENTRY-FIELD, USING MULTIPLE ENTRY-LINES,
LINES 5, SIZE 30.
- If you specify a FROM or USING item, and you do not specify a
title, the runtime will substitute the
from-item or
using-item for the
title if the corresponding control type does not take a value (i.e., is a LABEL, PUSH-BUTTON, or FRAME). This allows you to associate
a PICTURE with a LABEL control. Because the picture formats the value of the control, and because a LABEL does not take a
value, this rule allows the
picture-string to set the value of the label's title.
- The REQUIRED phrase is meaningful only for controls that take alphanumeric input (e.g., entry fields). When specified, it
forces the user to enter non-space data into the control before the ACCEPT will terminate. The user can also terminate the
ACCEPT by generating an exception. See
Common Screen Options for more information about the REQUIRED phrase.
- The EVENT option of the PROCEDURE phrase establishes an event procedure for the control. Event procedures are different from
the other Screen Section embedded procedures in that an event procedure becomes part of the control when it is created, and
is executed directly by the control (the BEFORE, AFTER, and EXCEPTION procedures execute as part of the flow of control of
the Screen Section). An event procedure can potentially execute any time after its owning control has been created, even when
the defining Screen Section item is not being ACCEPTed. For more about event procedures, see PROCEDURE Clause.
- All phrases not described here or in
Common Screen Options are treated in the same manner as in a Format 1 Screen Section entry.
Format 2 Screen Section example:
SCREEN SECTION.
01 SEARCH-SCREEN.
03 LABEL "Search for", LINE 1, COL 5.
03 ENTRY-BOX USING SEARCH-TEXT, COL + 1,
SIZE 30.
03 PUSH-BUTTON, TITLE "Ok", LINE 3, COL 10,
DEFAULT-BUTTON, TERMINATION-CODE IS 13.
03 PUSH-BUTTON, TITLE "Cancel", COL 25,
CANCEL-BUTTON, EXCEPTION-CODE IS 27.
Format 3 (.NET ASSEMBLIES) only Rules
- A Format 3 Screen Section entry defines a graphical .NET assembly.
- Literal values for assembly parameters are located in the COPY file generated by the NETDEFGEN utility. The same COPY file
must be included in the SPECIAL-NAMES paragraph of your program.
- Graphical assemblies show the keyword "VISUAL" in the COPY file after the CLASS keyword. If the word "VISUAL" does not appear,
use the CREATE statement to instantiate the assembly. A Format 3 Screen Section is for graphical .NET assemblies only.
- assembly-name is the name of a .NET assembly defined in the NETDEFGEN COPY file. This must be the DLL name of a graphical control, not
an executable file. Graphical controls are generated by Visual Studio when a developer selects a "Windows Control Library"
project type.
- namespace is a NameSpace in the assembly, as it appears in the COPY file.
- class-name is a class in the NameSpace.
- handle-1 receives a handle to the assembly when it is created.
- version is the version number of the assembly.
- culture is cultural information related to the assembly.
- strong-name is the cryptographic key required to access the assembly, if any. If the assembly requires such a key, as all assemblies
in the Global Assembly Cache (GAC) do, it is shown in the COPY file under the keyword STRONG.
- All classes that result in an object have a CONSTRUCTOR, which is a unique method. If you see a CONSTRUCTOR identifier in
the COPY file without a parameter list, then the field may be omitted from your COBOL program. If all listed CONSTRUCTORs
have parameters, then you must choose which CONSTRUCTOR and parameters to use.
constructor(n) is the constructor that you want to use followed by its parameter data.
- module identifies a file where a combination of NameSpaces and Classes resides. It is used when the assembly is constructed of other
assemblies.
- file-path is the path of an XML file, and that XML file contains the path where the .NET assembly is located. Use FILE-PATH when the
assembly that you want to access does not reside in the GAC or in the same directory as
wrun32.exe. Assemblies that reside in the GAC will have the STRONG keyword in the NETDEFGEN COPY file.
- LINES and SIZE default to the design control height and width.
Format 3 Screen Section example:
SCREEN SECTION.
01 screen-1.
03 SOME-NETCONTROL, "@My.Assembly",
LINE 1, COL 2,
NAMESPACE IS "My.Test.Namespace",
CLASS-NAME IS "UserControl1",
CONSTRUCTOR IS CONSTRUCTOR2(PARM1, PARM2, PARM3,
PARM4, PARM5, PARM6, PARM7),
EVENT PROCEDURE IS USERCONTROL-EVENTS.