| Comparison of Methods for Creating User Interfaces | Low-level Routines for Character Interfaces | |
There are many specialized features in COBOL that make it easy for you to create sophisticated and user-friendly character user interfaces for your applications. This chapter introduces you to some of them.
The available methods are:
Also, there is the ability to customize the behavior of ACCEPT and DISPLAY statements or modify a key on the keyboard
At the end of this chapter, there is a discussion of another Micro Focus product that enables you to create and manipulate user interfaces rapidly. This product is called Dialog System; it allows you to change your user's interface without changing the processing in your application. Dialog System also enables you to create and "run" user interfaces without having to write a program to drive them.
There are two types of ACCEPT and DISPLAY statements in COBOL: ANSI ACCEPT and DISPLAY and Micro Focus enhanced ACCEPT/DISPLAY. The enhanced ACCEPT/DISPLAY uses a run-time component called Adis.
Adis provides many enhancements and extensions over standard ANSI ACCEPT and DISPLAY statements. For instance, Adis provides screen positioning with ACCEPT and DISPLAY statements and performs formatting on numeric fields when accepting numeric data items.
The simplest form of an ACCEPT or DISPLAY statement is called an ANSI ACCEPT or DISPLAY. This statement meets the ANSI'85 requirements for an ACCEPT or DISPLAY statement and is very limited in scope.
For ACCEPT, there are two formats:
The following example shows typical use of ANSI ACCEPT and DISPLAY. Notice there is no facility for screen positioning of the data fields.
Example
The following code is an example of the use of ANSI ACCEPT and DISPLAY operations.
working-storage section.
01 into-field pic x(10).
procedure division.
display "Enter data to be accepted"
accept into-field
display "The data you entered was " into-field
stop run.
This is, of course, a very simple example, and does not show every feature of the ANSI ACCEPT and DISPLAY.
For screen handling potential, however, there is nothing else to show. The ANSI ACCEPT and DISPLAY is essentially a line mode feature. The programmer has no control over screen positioning - the data to be displayed and accepted is positioned at the current cursor position.
The Micro Focus Enhanced ACCEPT/DISPLAY facility contains extensive enhancements to the ANSI ACCEPT and DISPLAY base.
DOS, Windows and OS/2:
The COBOL systems for DOS, Windows and OS/2 contain the program smplaccp.cbl,
which illustrates some of the most commonly used features offered by the
Micro Focus Enhanced ACCEPT/DISPLAY facility.
This program is in your cobol\demo directory. You might want to compile and run it with this discussion.
Example
Micro Focus Enhanced ACCEPT/DISPLAY:
1$set ans85 noosvs mf 2 3*************************************************************** 4* Copyright Micro Focus Limited 1990. All Rights Reserved. * 5* This demonstration program is provided for use by users of * 6* Micro Focus products and may be used, modified and * 7* distributed as part of your application provided that you * 8* properly acknowledge the copyright of Micro Focus in this * 9* material. * 10*************************************************************** 11 12*************************************************************** 13* * 14* SMPLACCP.CBL * 15* * 16* This program demonstrates some simple screen handling * 17* extensions. It uses DISPLAY and ACCEPT statements to show * 18* how you could achieve password masking and reverse-video. * 19* * 20*************************************************************** 21 special-names. 22 console is crt. 23 24 working-storage section 25 01 into-field pic x(10). 26 01 pass-word pic x(08). 27 28 procedure division 29 display spaces upon crt. 30 display "Please enter your password" at 0310 upon 31 crt with underline. 32 accept pass-word at 0338 with no-echo. 33 display "Enter data to be accepted" at 0510. 34 accept into-field at 0538 with 35 reverse-video 36 blink. 37 display "The data you entered was =>" at 0710. 38 display into-field at 0738. 39 40 stop run.
The first line in the Procedure Division is DISPLAY SPACES UPON CRT. This statement is a Micro Focus Enhanced ACCEPT/DISPLAY to clear the screen.
The next two verbs (lines 30 through 32) show a common technique for having a user enter a password. The UPON CRT WITH UNDERLINE clause on the DISPLAY statement causes the literal to be underlined (on a monochrome terminal) or highlighted (on a color terminal). The WITH NO-ECHO clause on the ACCEPT statement prevents the user's response from being seen on the screen.
Also illustrated on these two lines, and in every ACCEPT and DISPLAY in the program, is the ability to position literals and variables (and the cursor) anywhere on the screen. For instance, AT 0310 means "At line 3 and column 10 on the CRT".
The ACCEPT INTO-FIELD statement (line 34) includes the phrases REVERSE-VIDEO and BLINK. These phrases state that the field where data is entered is in reverse video, and the data blinks when typed in.
When you run the program, you get a good idea of the control you have over a screen you design with COBOL.
Note: The use of Screen Section (a COBOL extension) provides more extensive screen control capabilities than ACCEPT and DISPLAY statements. You can find more information in the section Using Screens and in your Language Reference.
DOS, Windows and OS/2:
On DOS, Windows and OS/2, you can write COBOL applications allowing
a mouse interface for your users, using Micro Focus Enhanced
ACCEPT/DISPLAY and the x"AF" routine or certain call-by-name
routines.
These features are described in detail in the chapter Mouse Support in COBOL.
If you are using the Micro Focus Enhanced ACCEPT/DISPLAY facility, you must be sure that certain submodules can be accessed at run time. These modules are called Adis modules (this is why the term "Adis" is often used interchangeably with "Micro Focus Enhanced ACCEPT/DISPLAY").
This table shows how to determine if an ACCEPT or DISPLAY statement is ANSI or Micro Focus.
The general rule is, if the Special-Names paragraph is not present, then:
and if "SPECIAL-NAMES. CONSOLE IS CRT." is present, then:
This information can be useful both in debugging an existing application, or in creating a new application where you want to be sure if you are using ANSI or Micro Focus Enhanced ACCEPT/DISPLAY statements.
In the following table, a Micro Focus ACCEPT or DISPLAY statement is denoted by MF; an ANSI statement is denoted by ANSI.
| Statement | Is Special-Names. CONSOLE IS CRT. coded in program? | Type |
|---|---|---|
| ACCEPT identifier | Yes
No |
MF
ANSI |
| ACCEPT identifier FROM CONSOLE | Yes
No |
ANSI
ANSI |
| ACCEPT identifier FROM CRT | Yes
No |
MF
MF |
| ACCEPT identifier AT location | Yes
No |
MF
MF |
If the identifier is a Screen Section item, ACCEPT identifier is automatically a Micro Focus ACCEPT statement.
The use of any Micro Focus extensions (such as AT, UPON CRT-UNDER, WITH REVERSE-VIDEO, and so on) causes the ACCEPT statement to be treated as a Micro Focus ACCEPT statement.
No matter how you are creating your finished application, you need to include the Adis modules in your application, when using Micro Focus Enhanced ACCEPT/DISPLAY.
The modules you need to include in some way in your application are:
Note: The modules adis, adisinit and adiskey are always required. adisdyna is required if you are going to modify attributes dynamically through the CONTROL clause. For more information, see your Language Reference.
These files exist in both generated code and object code format. If you are using the Run-time Environment, you use the generated code files. If you are linking applications, you use the object code files.
For example, if you are using object code files, to link your program with the Adis modules, enter the following command line:
16-bit:
link myprog+adis+adisinit+adiskey+adisdyna;
32-bit OS/2:
link386/NOI myprog+adis+adisinit+adiskey+adisdyna;
UNIX :
cob -x myprog
For full details of creating finished applications, see your Object COBOL User Guide.
This section illustrates the basic methods for function key handling in COBOL.
The basic process in function key handling with COBOL is to:
DOS, Windows and OS/2:
On DOS, Windows and OS/2, a sample program, funkey.cbl, is
supplied.
It is provided in the demo subdirectory within your COBOL
system directory. You might want to compile and run this program with this
discussion.
Example
Program to accept and identify a function key.
1$set noosvs mf ans85 2************************************************************** 3* Copyright Micro Focus Limited 1991. All Rights Reserved. * 4* This demonstration program is provided for use by users of * 5* Micro Focus products and may be used, modified and * 6* distributed as part of your application provided that you * 7* properly acknowledge the copyright of Micro Focus in this * 8* material. * 9************************************************************** 10 11************************************************************** 12* * 13* FUNKEY.CBL * 14* * 15* This program demonstrates how to decode function keys * 16* using the x"af" call. * 17* * 18************************************************************** 19 special-names. 20 crt status is key-status. 21 22 working-storage section. 23 01 flag pic 9(2) comp-x value 1. 24 01 user-key-control. 25 05 enable-fn-keys pic 9(2) comp-x value 1. 26 05 filler pic x value "1". 27 05 first-user-key pic 9(2) comp-x value 1. 28 05 number-of-keys pic 9(2) comp-x value 10. 29 30 01 key-status. 31 05 key-type pic x. 32 05 key-code-1 pic 9(2) comp-x. 33 05 filler pic x. 34 01 any-data pic x. 35 01 key-code-1-display pic z9. 36 37 procedure division. 38 perform enable-keys 39 perform accept-function-key 40 perform tell-which-key-was-pressed 41 perform stop-run. 42 43 enable-keys. 44 call x"af" using flag user-key-control. 45 46 accept-function-key. 47 display spaces upon crt 48 display "Press a function key: F1 to F10" at 0505 49 accept any-data at 0540. 50 51 tell-which-key-was-pressed. 52 evaluate key-type 53 when 0 display "You pressed <Enter>" at 0705 54 when 1 55 move key-code-1 to key-code-1-display 56 display "You pressed function key" at 0705 57 display key-code-1-display at 0730 58 end-evaluate. 59 60 stop-run. 61 stop run.
This program is discussed below.
Lines 19-20:
special-names
crt status is key-status.
The Special-Names paragraph contains one clause: CRT STATUS IS
KEY-STATUS. The presence of this clause causes the system to update the
associated data item after every Micro Focus ACCEPT operation with
information as to which keystroke ended the ACCEPT operation. For our
purposes, key-status contains the data that tells you which
function key was pressed.
Lines 23-28:
01 flag pic 9(2) comp-x value 1.
01 user-key-control.
05 enable-fn-keys pic 9(2) comp-x value 1.
05 filler pic x value "1".
05 first-user-key pic 9(2) comp-x value 1.
05 number-of-keys pic 9(2) comp-x value 10.
The first two items defined in the Working-Storage Section are flag
and user-key-control. These two items are parameters to the
x"AF" routine, which turns function key handling on. (There is a
configuration option to do this permanently; for more details, see the
section Customizing Your ACCEPT/DISPLAY Environment with Adiscf in
this chapter.)
The flag data item must always be equal to 1 when using x"AF"
for function key handling.
The data item, user-key-control is a four-byte group item.
The first byte, enable-fn-keys, should be set to 1 for
enabling function keys, and to zero for disabling them.
Since we are enabling the keys here, it is set to 1.
The following elementary item is a FILLER item that must be set to 1.
The next two elementary items are first-user-key and
number-of-keys. As their data-names indicate, they contain
values for the first key to be enabled, and the number of keys to be
enabled. The values given for these keys are the user function key numbers
supplied with your COBOL system. For a quick reference of user function
key numbers mapped onto actual keys, see the chapter Adis.
Lines 30-33:
01 key-status.
05 key-type pic x.
05 key-code-1 pic 9(2) comp-x.
05 filler pic x.
The key-status group item (referred to by the CRT STATUS
clause in the Special Names paragraph) contains information about the type
of key that terminated the ACCEPT operation.
The first elementary item in this group item is key-type.
If this value is 1, a function key was pressed. If key-type
is equal to 0, Enter was pressed.
The second elementary item is key-code-1. If key-type
is 1, key-code-1 tells you which function key was pressed.
The next elementary item is a one-byte FILLER item. It has no function in your program, but must be in place.
Lines 34-35:
01 any-data pic x. 01 key-code-1-display pic z9.
The any-data data item is a PIC X field that is accepted
into the program. This data item is not used afterward, because the
purpose of the program is to determine the function key pressed, which it
does through key-type and key-code-1.
The key-code-1-display data item is a display field for
the function key.
Line 37:
procedure division.
The structure of the program can be seen from the PERFORM statements on lines 38 through 41. First, the function keys are enabled. Second, a function key is accepted. Third, the user is told which key was pressed; and fourth, the program is terminated.
Lines 43-44:
enable-keys.
call x"af" using flag user-key-control
Function keys must always be enabled before they can be used in a program compiled with COBOL. They are enabled using a call to the x"AF" routine (or through Adiscf, as is described in the section Customizing Your ACCEPT/DISPLAY Environment with Adiscf later in this chapter).
The x"AF" routine gives you very fine control over your ACCEPT and DISPLAY options, but the use of x"AF" we discuss here is the enabling and disabling of function keys.
Note the parameters that are passed: flag and user-key-control.
All values for these parameters were established through VALUE clauses in
the Data Division.
However, if later calls to x"AF" are to be made, the parameter fields should be refreshed, as their values can be changed by the call under certain circumstances.
Lines 46-49:
accept-function-key.
display spaces upon crt
display "Press a function key: F1 to F10" at 0505
accept any-data at 0540.
The first statement in the accept-function-key paragraph
is to clear the screen: display spaces upon crt.
Following that, the user is asked to press a function key, and the
function is accepted into the crt-status field. Any data
keyed in addition to the function key is accepted into the any-data
item.
The ACCEPT operation is not terminated until the user presses either a function key or Enter.
Lines 51-58:
tell-which-key-was-pressed.
evaluate key-type
when 0 display "You pressed <Enter>" at 0705
when 1
move key-code-1 to key-code-1-display
display "You pressed function key" at 0705
display key-code-1-display at 0730
end-evaluate.
In this paragraph, the user is told which function key was pressed. If
key-type is 0, the user is informed that Enter was
pressed, rather than a function key. If key-type is 1, the
user is told which function key was pressed.
First, key-code-1 must be moved to key-code-1-display,
to enable it to be displayed.
In a typical application, of course, you would probably perform an
EVALUATE on key-code-1 and perform the appropriate action in
your program, rather than simply telling the user which key was pressed.
The Screens facility provides advanced screen design capabilities for the COBOL programmer. These capabilities include the ability to paint a user screen and generate the code automatically to produce the screen from your COBOL program.
The screen image is coded in a COBOL extension known as the Screen Section.
The Screen Section is a collection of screen definitions; each definition describes the layout of a screen. The Screen Section is part of the Data Division.
Example
Structure of a program containing a Screen Section.
data division.
file section.
...
working-storage section.
...
screen section.
01 screen-1.
...
01 screen-2.
...
procedure division.
As a means of taking a closer look at the Screen Section, let's start by looking at the process of painting screens.
This section and the next provide an introduction to painting a screen using the Screens facility in COBOL.
The Screens facility enables you to paint a screen and, by pressing a few keys, generate the code needed to create the screen in your program. This generated code goes into a COBOL language extension known as the Screen Section.
If you completed the Screens tutorial, the program you generated is called myform.cbl (as the tutorial requested).
This program looks similar to the following:
Example
Screen handling program.
identification division. data division. working-storage section. copy "myform.wks". screen section. copy "myform.ss"
procedure division.
display g-myform.
accept g-myform.
stop run.
Two COBOL copyfiles were created: myform.wks and myform.ss. The directory containing these copyfiles depends on the directory you were in when you invoked Screens.
myform.wks is the Working-Storage Section of your program, and myform.ss is the Screen Section. The rest of the program, as you can see, consists of division headings and ACCEPT and DISPLAY statements.
Here is the copyfile myform.wks:
Example
Screen handling copyfile for your Working-Storage Section.
01 order-name pic x(25).
01 filler.
03 occurs 5.
05 order-addr pic x(30).
01 order-phone pic x(19).
It contains the Working-Storage descriptions for the fields you defined in the Screens tutorial. The names and sizes of these fields can vary, but this is the format.
The Address field, defined as a group, is declared in the COBOL program
as a table item: order-addr.
Most of the code generated from a painted screen under Screens is in the Screen Section. The Screen Section can include many level-01 items, where each level-01 item describes the layout of a separate screen: the attributes, behavior, size, and location of the items in the screen.
Below is a Screen Section item called g-myform, generated
from the Screens tutorial. The screen you created is similar to this,
although many of the particulars (such as line and column numbers, and
data-names) might be different.
Example
Screen handling copyfile for your Screen Section.
01 g-myform.
02 blank screen.
02 line 3 col 1 background-color 2 foreground-color 4 value "name:".
02 col 36 background-color 3 foreground-color 0 value "telephone no:".
02 line 6 col 1 background-color 3 foreground-color 0 value "address:".
02 line 15 col 34 background-color 2 foreground-color 4 value "warning ".
02 line 17 col 34 background-color 2 foreground-color 4 value "message ".
02 line 3 col 7 background-color 3 foreground-color 0 pic x(25) using
order-name auto.
02 line 6 col 9.
02 g-001.
03 occurs 5.
04 background-color 3 foreground-color 0 pic x(30) using order-addr
auto.
04 line + 1 col - 29.
02 line 3 col 51 background-color 3 foreground-color 0 pic x(19) using
order-phone auto.
Each line of the code is explained below, so the individual items can be discussed separately.
The level-01 item above is describing a screen called g-myform.
The first level-02 item in g-myform is blank screen.
This causes the screen to be blanked out before the user screen is
displayed. Without this item, any data on the screen remains.
02 line 3 col 1 background-color 2 foreground-color 4 value "name:".
The next item describes the literal field, Name. The item specifies the line and column where the literal is to be positioned on the screen, and assigns colors. Color 2 is green; color 4 is red. Further reference on the color and number assignments for the Screen Section can be found in the Language Reference.
02 col 36 background-color 3 foreground-color 0 value "telephone no:". 02 line 6 col 1 background-color 3 foreground-color 0 value "address:".
The next pair of level-02 items perform the same function for the
Telephone No and Address fields. There is no line
specification on the level-02 item describing Telephone No above: if the
line is not specified, the item is positioned on the last
line specified.
02 line 15 col 34 background-color 2 foreground-color 4 value "warning ". 02 line 17 col 34 background-color 2 foreground-color 4 value "message ".
The next pair of level-02 items perform the same function for the WARNING MESSAGE field.
02 line 3 col 7 background-color 3 foreground-color 0 pic x(25) using order-name auto.
The next level-02 item defines the field that is to be associated with
the Name literal. Recall that you named this field order-name.
On typing the last character of a field with AUTO specified, the cursor
advances to the next field on the screen or terminates the ACCEPT
operation if no further fields are defined. The USING clause indicates
that this is an input/output field.
02 line 6 col 9.
02 g-001.
03 occurs 5.
04 background-color 3 foreground-color 0 pic x(30) using order-addr
auto.
04 line + 1 col - 29.
The next five Screen Section lines combine to process the declaration
for the group definition of the Address field. The group item is named
g-001; the cursor is positioned at line 6, column 9.
The OCCURS clause specifies that this is a table item: a 1-by-5 table.
The first occurrence of order-addr is on line 6, column 9.
Each of the four following items is positioned according to the line
+ 1 col - 29 clause. That is, the next item is on line 7, column 9;
the following item is on line 8, column 9, and so on. (The col - 29
tells COBOL to subtract 29 columns after the end of the field, which is
column 38.)
02 line 3 col 51 background-color 3 foreground-color 0 pic x(19) using order-phone auto.
Finally, the input field for Telephone No, (order-phone)
is defined.
It is a PIC X(19) field positioned at line 3 and column 51.
Notice that we went from line 17 back to line 3. The line numbers in the Screen Section do not have to be sequential for any particular screen definition.
The order of the declarations for these items (order-name,
order-addr and order-phone) is extremely
important: recall that during the tutorial you specified that you wanted
the Name field defined first, followed by the Address and Telephone No
fields.
It is that decision that determines the order they are defined here, and thus the order that they are accepted by the user.
There are many callable subroutines supplied with COBOL that provide sophisticated screen handling capabilities. These routines are called video I/O routines.
The capabilities of the video I/O routines include the ability to read and write characters and attributes, to scroll or clear the screen, manipulate the cursor, and perform other related functions.
DOS, Windows and OS/2:
On DOS, Windows and OS/2, a sample program is supplied that
illustrates the use of video I/O routines. This program is called popup.cbl,
and is provided in the demo subdirectory within your COBOL
system directory.
You might want to compile and run popup.cbl yourself with this discussion. You also might want to animate it, as this is an excellent way to familiarize yourself with new programs.
popup.cbl provides examples of the following video I/O routines:
popup.cbl also shows you how to implement a pick-and-point menu system and construct popup panels.
Example
Here is the source for popup.cbl:
1$set ans85 noosvs mf 2 3************************************************************** 4* Copyright Micro Focus Limited 1989. All Rights Reserved.* 5* This demonstration program is provided for use by users of * 6* Micro Focus products and may be used, modified and * 7* distributed as part of your application provided that you * 8* properly acknowledge the copyright of Micro Focus in this * 9* material. * 10************************************************************* 11 12************************************************************** 13* * 14* POPUP.CBL * 15* * 16* * 17* This program illustrates how to simulate POPUP MENUS * 18* * 19* Internal calls used by this program: * 20* * 21* x"af" - Used to detect the use of cursor * 22* keys. * 23* * 24* x"e5" - Used to sound the audible alarm. * 25* * 26* CBL_READ_SCR_CHATTRS - Used to read the characters and * 27* attributes on the screen. * 28* * 29* CBL_WRITE_SCR_CHATTRS- Used to write the characters and * 30* attributes on the screen. * 31* * 32* CBL_WRITE_SCR_ATTRS - Used to set the characters * 33* on the screen. * 34* * 35* CBL_SET_CSR_POS - Used to turn the cursor off. * 36* * 37* * 38************************************************************** 39 40 working-storage section. 41 01 screen-position.
42 05 screen-row pic 9(2) comp-x value 05. 43 05 screen-col pic 9(2) comp-x value 15. 44 01 string-length pic 9(4) comp-x value 15. 45 46 01 top-row pic 9(2) comp-x value 05. 47 01 bottom-row pic 9(2) comp-x value 14. 48 49 01 reverse-vid pic x(15) value all x"70". 50 01 black-and-white pic x(15) value all x"07". 51 52 01 screen-origin pic 9(4) comp-x value 0. 53 01 screen-buffer pic x(2000). 54 01 screen-attrs pic x(2000). 55 01 screen-string-length pic 9(4) comp-x value 2000. 56 57 01 get-single-char pic 9(2) comp-x value 26. 58 01 key-status. 59 05 key-type pic x. 60 05 key-code-1 pic 9(2) comp-x. 61 05 key-code-2 pic 9(2) comp-x. 62 63 01 set-bit-pairs pic 9(2) comp-x value 1. 64 01 user-key-control. 65 05 user-key-setting pic 9(2) comp-x value 1. 66 05 filler pic x value "1". 67 05 first-user-key pic 9(2) comp-x value 1. 68 05 number-of-keys pic 9(2) comp-x value 4. 69 70 78 user-fn-key value "1". 71 78 adis-fn-key value "2". 72 73 78 f1-key value 1. 74 78 f2-key value 2. 75 78 f3-key value 3. 76 78 f4-key value 4. 77 78 78 carriage-return value 0. 79 78 up-arrow value 5. 80 78 down-arrow value 6. 81 82 01 cursor-off-screen. 83 05 row-number pic 99 comp-x value 255. 84 05 col-number pic 99 comp-x value 255. 85 86 87 screen section. 88 01 g-picscrn. 89 05 blank screen.
90 05 line 6 col 16 value "Option one". 91 05 line 9 col 16 value "Option two". 92 05 line 12 col 16 value "Option three". 93 05 line 15 col 16 value "Option four". 94 05 line 21 col 10 value "F1=Help F2=Window1 95-" F3=Window3 F4=Clear windows". 96 05 line 22 col 10 value "Use or to point to an 97-"item, and <Enter> to Terminate.". 98 99 01 hilite3-00 highlight. 100 05 line 06 col 37 value "+----------------------+". 101 05 line 07 col 37 value "|this is popup menu #1 |". 102 05 line 08 col 37 value "| |". 103 05 line 09 col 37 value "|this menu could be |". 104 05 line 10 col 37 value "|your help menus |". 105 05 line 11 col 37 value "| |". 106 05 line 12 col 37 value "|It was brought up with|". 107 05 line 13 col 37 value "|F1. |". 108 05 line 14 col 37 value "+----------------------+". 109 05 line 15 col 37 value " ". 110 111 01 hilite4-00 reverse-video. 112 05 col 1. 113 05 line 04 value "+-----------------------+". 114 05 line 05 value "|this is popup menu #2 |". 115 05 line 06 value "| |". 116 05 line 07 value "|notice that the menus |". 117 05 line 08 value "|can overlay one another|". 118 05 line 09 value "| |". 119 05 line 10 value "|the attribute you use |". 120 05 line 11 value "|is determined in the |". 121 05 line 12 value "|screen section |". 122 05 line 13 value "| |". 123 05 line 14 value "|this screen is turned |". 124 05 line 15 value "|on by F2 |". 125 05 line 16 value "+-----------------------+". 126 127 01 hilite5-00 . 128 05 line 13 value "+-----------------------------+". 129 05 line 14 value "|This screen is popup menu 3 |". 130 05 line 15 value "| |". 131 05 line 16 value "|Take turns in pressing F1, F2|". 132 05 line 17 value "|F3 and F4 in any order. |". 133 05 line 18 value "|You can overlay any menus. |". 134 05 line 19 value "|F4 will clear to the |". 135 05 line 20 value "|original menu. |". 136 05 line 21 value "|function key #3 pops up |". 137 05 line 22 value "|this screen. |".
138 05 line 23 value "+-----------------------------+". 139 140 procedure division. 141 main-line. 142 perform start-up 143 perform which-key-loop 144 until key-type = adis-fn-key 145 and key-code-1 = carriage-return 146 stop run. 147 148 start-up. 149* Display user screen 150 display g-picscrn 151 152* Move cursor off screen 153 call "CBL_SET_CSR_POS" using cursor-off-screen 154 155* Read the current screen for later re-display 156 call "CBL_READ_SCR_CHATTRS" using screen-origin 157 screen-buffer 158 screen-attrs 159 screen-string-length 160* Display first block 161 perform mark-block 162 163* Enable function keys 164 call x"af" using set-bit-pairs 165 user-key-control 166 . 167 168 169 which-key-loop. 170 call x"af" using get-single-char 171 key-status 172 evaluate key-type 173 when user-fn-key 174 evaluate key-code-1 175 when f1-key display hilite3-00 176 when f2-key display hilite4-00 177 when f3-key display hilite5-00 178 when f4-key perform clear-pop-up 179 when other call x"e5" 180 end-evaluate 181 when adis-fn-key 182 evaluate key-code-1 183 when up-arrow perform move-block-up 184 when down-arrow perform move-block-down 185 when other call x"e5"
186 end-evaluate 187 end-evaluate. 188 189 pop-up-help. 190 191 pop-up-story1. 192 193 pop-up-story2. 194 195 clear-pop-up. 196* recover the original screen * 197 call "CBL_WRITE_SCR_CHATTRS" using screen-origin 198 screen-buffer 199 screen-attrs 200 screen-string-length 201 perform mark-block. 202 203 move-block-up. 204 perform clear-block 205 if screen-row top-row 206 subtract 3 from screen-row 207 else 208 move bottom-row to screen-row 209 end-if 210 perform mark-block. 211 212 move-block-down. 213 perform clear-block 214 if screen-row bottom-row 215 add 3 to screen-row 216 else 217 move top-row to screen-row 218 end-if 219 perform mark-block. 220 221 clear-block. 222 call "CBL_WRITE_SCR_ATTRS" using screen-position 223 black-and-white 224 string-length. 225 226 227 mark-block. 228 call "CBL_WRITE_SCR_ATTRS" using screen-position 229 reverse-vid 230 string-length.
The Working-Storage Section in popup.cbl is mostly parameters for video I/O routine calls, values returned from these calls, or parameters to and from other COBOL system library routines.
The Screen Section contains the user screens and panels that can appear during execution of the program. For more information on the Screen Section, see the section Using the Screens Facility earlier in this chapter.
In the start-up paragraph, the following actions take
place:
g-picscrn.
The which-key-loop is the main processing loop of the
program. This loop is performed until Enter is pressed to end the
program.
The popup menus are displayed if the user presses a user function key.
This is shown in the EVALUATE statement in which-key-loop.
The video I/O routine CBL_READ_SCR_CHATTRS is used to save the initial
screen. In clear-pop-up, the screen is redisplayed.
The video I/O routine CBL_WRITE_SCR_ATTRS is used in the clear-block
and mark-block paragraphs to change the block designated by
the cursor position either to reverse video or black and white.
Panels is a module supplied with COBOL that you can call from your COBOL program to create and manipulate user windows in a character-based application.
With Panels, you can perform the following functions:
The following sections describe the fundamentals of Panels: panels, screens, windows, and buffers.
A program can create any number of panels, and can display up to 254 sets of data (panels) in overlapping rectangular views (windows) on a screen.
Text and attributes (for example, highlighting or reverse video) are written to the panel using text buffers.
A panel can be larger or smaller than the user screen, up to a maximum of 65,535 bytes.
For each panel you define a window - a view into the panel. A window is an area on the screen of your CRT - it is described in the program in terms of height, width, and screen position.
Here are the things you can do with a window:
The Panels facility provides the basic primitives to manipulate windows and panels from your application. This is done by calling a subprogram called Panels.
Panels can be called from a COBOL program in one of the following forms:
call "PANELS" using panels-parameter-block
call "PANELS" using panels-parameter-block
text-buffer
call "PANELS" using panels-parameter-block
text-buffer
attribute-buffer
panels-parameter-block has to be provided on every call to
Panels. This is a group item - you need to fill in the required fields
(elementary items) for any particular Panels function, and it tells Panels
what to do. text-buffer and attribute-buffer
need to be supplied when the panel is being written to, read from or
scrolled.
Each call to Panels is typically preceded by MOVE statements to fill in these parameters.
This sample program shows the basic use of Panels to create, display, and delete a panel. These are the functions needed to pop up a help window.
The program is called pandemo.cbl and is provided in the demo subdirectory within your COBOL system directory. You might want to compile the program and run it with the discussion that follows this program.
UNIX:
On UNIX, the sample program is slightly differently from the one
printed here, but you can ignore these differences. For example, some
procedures and calls are in upper case.
Example
Creating, displaying, and deleting a panel and window:
1$SET ans85 mf noosvs 2 3************************************************************** 4* Copyright Micro Focus Limited 1992. All Rights Reserved.* 5* This demonstration program is provided for use by users of * 6* Micro Focus products and may be used, modified and * 7* distributed as part of your application provided that you * 8* properly acknowledge the copyright of Micro Focus in this * 9* material. * 10************************************************************** 11 12************************************************************** 13* PANDEMO.CBL: Shows how to use the Panels facility to * 14* create, write to, enable and disable a * 15* user panel under COBOL. * 16* * 17* calls used by this program: * 18* * 19* panels: subroutine for handling panel * 20* functions. * 21* * 22************************************************************** 23 working-storage section. 24 25************************************************************** 26* panels parameter block. 27************************************************************** 28 29 01 panels-parameter-block. 30 03 ppb-function pic 9(2) comp. 31 03 ppb-status pic 9(2) comp. 32 03 ppb-panel-id pic 9(4) comp. 33 03 ppb-panel-width pic 9(4) comp. 34 03 ppb-panel-height pic 9(4) comp. 35 03 ppb-visible-width pic 9(4) comp. 36 03 ppb-visible-height pic 9(4) comp. 37 03 ppb-first-visible-col pic 9(4) comp. 38 03 ppb-first-visible-row pic 9(4) comp. 39 03 ppb-panel-start-column pic 9(4) comp. 40 03 ppb-panel-start-row pic 9(4) comp. 41 03 ppb-buffer-offset pic 9(4) comp. 42 03 ppb-vertical-stride pic 9(4) comp. 43 03 ppb-update-group. 44 05 ppb-update-count pic 9(4) comp. 45 05 ppb-rectangle-offset pic 9(4) comp. 46 05 ppb-update-start-col pic 9(4) comp. 47 05 ppb-update-start-row pic 9(4) comp. 48 05 ppb-update-width pic 9(4) comp. 49 05 ppb-update-height pic 9(4) comp. 50 03 ppb-fill. 51 05 ppb-fill-character pic x. 52 05 ppb-fill-attribute pic x. 53 03 ppb-update-mask pic x. 54 03 ppb-scroll-direction pic 9(2) comp. 55 03 ppb-scroll-count pic 9(4) comp. 56 57 01 ws-save-panel-id pic 9(4) comp-x. 58 01 ws-text-buffer. 59 05 filler pic x(20) value " ". 60 05 filler pic x(20) value " ". 61 05 filler pic x(20) value "********************". 62 05 filler pic x(20) value "********************". 63 05 filler pic x(20) value "********************". 64 05 filler pic x(20) value "********************". 65 05 filler pic x(20) value "** Hello, I am a **". 66 05 filler pic x(20) value "** panel. To see **". 67 05 filler pic x(20) value "** me disappear, **". 68 05 filler pic x(20) value "** press return. **". 69 05 filler pic x(20) value "********************". 70 05 filler pic x(20) value "********************". 71 05 filler pic x(20) value "********************". 72 05 filler pic x(20) value "********************". 73 05 filler pic x(20) value " ". 74 05 filler pic x(20) value " ". 75 76 01 ws-attrib-buffer. 77 05 filler pic x(300) value all x"07". 78 79 01 ws-accept pic x. 80 81 procedure division. 82 main-line. 83 perform redraw-screen 84 perform proceed-to-create-a-panel 85 perform create-a-panel 86 perform write-to-the-panel 87 perform enable-the-panel 88 perform disable-the-panel 89 perform stop-run. 90 91 redraw-screen. 92 move 2 to ppb-function 93 call "panels" using panels-parameter-block 94 perform status-check. 95 96 proceed-to-create-a-panel. 97 display "press return to make the panel appear" 98 accept ws-accept 99 perform redraw-screen. 100 101 create-a-panel. 102 move 20 to ppb-panel-width 103 move 15 to ppb-panel-height 104 move 5 to ppb-panel-start-row 105 move 20 to ppb-panel-start-column 106 move 20 to ppb-visible-width 107 move 15 to ppb-visible-height 108 move 0 to ppb-first-visible-row 109 move 0 to ppb-first-visible-col 110 move 3 ppb-function 111 call "panels" using panels-parameter-block 112 perform status-check 113 move ppb-panel-id to ws-save-panel-id. 114 115 write-to-the-panel. 116 move ws-save-panel-id to ppb-panel-id 117 move 15 to ppb-update-height 118 move 20 to ppb-update-width 119 move 0 to ppb-update-start-row 120 move 0 to ppb-update-start-col 121 move 300 to ppb-update-count 122 move 0 to ppb-rectangle-offset 123 move x"03" to ppb-update-mask 124 move 1 to ppb-buffer-offset 125 move 20 to ppb-vertical-stride 126 move 11 to ppb-function 127 call "panels" using panels-parameter-block 128 ws-text-buffer 129 ws-attrib-buffer 130 perform status-check. 131 132 enable-the-panel. 133 move ws-save-panel-id to ppb-panel-id 134 move 7 to ppb-function 135 call "panels" using panels-parameter-block 136 perform status-check. 137 138 disable-the-panel. 139 accept ws-accept 140 move ws-save-panel-id to ppb-panel-id 141 move 8 to ppb-function 142 call "panels" using panels-parameter-block 143 perform status-check. 144 145 status-check. 146 if ppb-status not = 0 147 display "bad status" 148 perform stop-run. 149 150 stop-run. 151 display "press return to stop the PANDEMO program" 152 accept ws-accept 153 stop run.
Lines 29-55:
01 panels-parameter-block.
Note the organization of the Panels parameter block, the first group item in the Working-Storage Section in the pandemo.cbl program. Certain fields in this block have to be initialized before any call to Panels.
This parameter block is very similar to one provided in a file called Bpanlink.cpy, supplied in the demo subdirectory within your COBOL system directory.
This copyfile also contains a full description of each of the Panels functions. You can include this copyfile in your program if you want.
The individual items in the Panels parameter block are discussed as they are needed in the pandemo.cbl program.
Lines 58-77:
ws-text-buffer and ws-attrib-buffer
These two parameters need to be specified if the panel is being read
from, written to, or scrolled. The text buffer, as you can see, contains
the text for the panel, and the attribute buffer contains the display
attributes. The value x"07" in ws-attrib-buffer
indicates that the panel has a simple "white on black"
attribute.
Lines 57 and 79:
ws-save-panel-id and ws-accept
The ws-save-panel-id data item (line 57) is used to
demonstrate that you should always save the identifier of a panel (panel-id)
after you create it. In a typical application you can create several
panels before writing to any of them or enabling them (making them
visible). You should have Working-Storage Section items containing the
identifiers for your panels.
The ws-accept data item (line 79) is used for all ACCEPT
statements in the program. All of the ACCEPT statements in pandemo.cbl
are simple ANSI ACCEPT statements that wait for Enter to be
pressed.
Lines 82-89:
main-line.
The main-line paragraph contains the structure that
defines the necessary steps to create panels, make them visible, and make
them disappear.
Since these steps correspond to the actual order of the paragraphs in pandemo.cbl, they are presented in that order.
Lines 91-94:
redraw-screen.
The redraw-screen paragraph clears the screen if no panels
have been created. That is, the purpose of redraw-screen is
to refresh all the panels that are currently visible on the screen. The
only item in the panels parameter block that needs to be updated is
ppb-function: it needs to be set to 2, indicating that a
Redraw Screen function is to be performed.
After the call to Panels, the status-check paragraph is
performed. Whenever you call Panels in your applications, you need to
perform some status checking on the ppb-status data item.
Here, the status checking is minimal, since this is a simple demonstration
program.
Lines 96-99:
proceed-to-create-a-panel.
This paragraph simply prompts the user to press Enter before the panel is created and enabled.
Lines 101-113:
create-a-panel.
Before a panel can be used, it has to be created. To do this, you need
to fill in the following information in panels-parameter-block:
ppb-panel-height |
height of the panel |
ppb-panel-width |
width of the panel |
ppb-panel-start-row |
starting row for the window |
ppb-panel-start-column |
starting column for the window |
ppb-visible-width |
width of the window |
ppb-visible-height |
height of the window |
ppb-first-visible-row |
first row visible in the panel |
ppb-first-visible-col |
First column visible in the panel |
As you can see in the program, these fields are filled in before the Create Panel routine is called. Following the call, routine status checking is performed.
After the create panel call, ppb-panel-start-row and
ppb-panel-start-column specify the position of the top left
corner of the window on the screen.
A field identifying the created panel is returned from Panels after the
Create Panel routine is called. This field, in the panels-parameter-block
group, is called ppb-panel-id. After calling the Create
Panel routine, you should always move this field into a Working-Storage
item so you can refer to this panel later.
Lines 115-130:
write-to-the-panel.
Writing to a panel is one way of filling in the panel with some data
before enabling it (making it visible). This is accomplished by a Write To
Panel function, ppb-function number 11.
The fields that need to be initialized in panels-parameter-block
before a call to write to a panel are:
ppb-update-height |
number of rows to update |
ppb-update-width |
number of columns to update |
ppb-update-start-row |
first row of panel to update |
ppb-update-start-col |
first column of panel to update |
ppb-update-count |
total number of characters to update |
ppb-rectangle-offset |
specifies how many characters not to update in the rectangle. This field enables applications to update irregular shaped areas of a rectangle. |
ppb-update-mask |
whether screen is to be automatically updated; whether text or attributes are to be updated; where the data to fill the update area is found |
ppb-buffer-offset |
where the first update character in the text buffer is found |
ppb-vertical-stride |
distance between the start of one row in a buffer and the start of the next row (the row length, usually) |
In addition to panels-parameter-block, the text buffer (ws-text-buffer)
and attribute buffer (ws-attribute-buffer) are needed in the
call to write to a panel.
Lines 132-136:
enable-the-panel.
After the panel is filled in, it is made visible on the screen through
the function to enable a panel, ppb-function number 7.
Note, again, that ws-save-panel-id is being moved to
ppb-panel-id. Although this is not necessary in this simple
one-panel program, it is included to remind you that you typically fill in
the ppb-panel-id data item with the Working-Storage Section
data item into which you saved your ppb-panel-id upon its
creation.
Lines 138-143:
disable-the-panel.
The panel is made invisible through the function to disable a panel,
ppb-function number 8.
In pandemo.cbl, an ACCEPT statement is executed in this paragraph so that the user can pause between the enabling and the disabling of the panel.
Lines 145-148:
status-check.
This is a simplified example of the status checking that should be performed after every Panels call.
Explanations of non-zero status codes received from Panels can be found in the chapter Panels.
Lines 150-153:
stop-run.
The program is halted.
The following is a list of other Panels sample programs supplied:
pantutor.cbl
panelex1.cbl
panelex2.cbl
panbigsc.cbl
panbordr.cbl
Panels is commonly used with Micro Focus Enhanced ACCEPT/DISPLAY facilities (Adis) to allow users to accept data from panels. A program that illustrates how to use this facility and gives a thorough tutorial on the Panels function is pantutor.cbl.
Panels can also provide users with a screen that is larger that a standard 25x80 display. A program that illustrates how to do this is panbigsc.cbl, in the demo subdirectory within your COBOL system directory.
panbordr.cbl demonstrates how you create a panel and put a border around the visible part of the panel.
There is a configuration file for your Micro Focus Enhanced ACCEPT/DISPLAY facility. It is called adisctrl.
adisctrl is essentially a database that specifies the editing functions to be used by the Adis function keys. It is a file containing several possible configuration options, one of which you choose.
By editing this file using the Adis Configuration utility (Adiscf), you change the behavior of Adis, customizing it to your needs.
Adis was introduced briefly in the introduction to the section Using ACCEPT and DISPLAY earlier in this chapter. Here, Adis is described in more detail.
The term Adis refers to the component of COBOL that handles extended (that is, non-ANSI) ACCEPT and DISPLAY processing.
Adis needs to know about machine-independent information such as:
All of this information is stored in a modifiable file called adisctrl.
When Adis is executed, it reads this information from adisctrl, if an adisctrl file is present. adisctrl does not have to be present; the default values are available without adisctrl.
Note: If you did not request Adis configuration when you installed COBOL through Setup, you do not have an adisctrl file present. You simply get Micro Focus ACCEPT/DISPLAY defaults in this case. If you want to change these defaults, you need adisctrl, adiscf.exe and adiscf.lbr from your COBOL disks.
There are several reasons you might want to modify adisctrl:
You modify adisctrl through a configuration utility called Adiscf. You can invoke this utility directly from the command line.
When adisctrl is modified to change your Adis environment, you need to ensure that the modified copy is available to COBOL at run time. When you are testing, therefore, you need to have the modified copy either in your current directory or in a directory specified by the COBDIR environment variable.
When you hand the system over to your users, the same consideration applies: make sure they receive the modified adisctrl with the product you send.
You also can change the values of keys on your keyboard using the Keyboard Configuration Utility (Keybcf).
For example, you can make your COBOL system treat F10 like Enter.
This is a much less commonly used feature, but you should know it is available.
When you run Keybcf, there is a file that is created and maintained called cobkeymp. This is a control file containing the scan codes for the keys on your keyboard. Unlike adisctrl, cobkeymp is only created if Keybcf is run.
The same considerations apply here as with adisctrl. That is, if you want a modified keyboard configuration for your users, you must ensure that the modified cobkeymp file is included with the product you provide. At run time, cobkeymp must either be in the current directory or the COBOL system directory.
If you run the example, simply delete cobkeymp at the end to restore your keys to their current values.
Dialog System is user interface management technology that provides portable user interface solutions across a variety of graphical and character-based operating environments.
Depending on your needs, Dialog System user interfaces can be very simple, such as a single data entry panel, or very complex with full graphics features such as, windows, pulldown menus, radio buttons, action bars, help, mouse support and validation. Your application program, unchanged, could drive either user interface.
Dialog System is a development and execution system that enables separation of the user interface from the underlying business application logic. Dialog System also supports multiple interfaces on the same business logic resulting in user interfaces that are flexible and able to change according to the needs of the people who use them.
When you need to change the user interface, Dialog System enables you to modify and test your changes without impacting the application code. This lets you change the look and feel of an application, without the risk of introducing errors to the application program.
User interfaces created with 16-bit Dialog System graphical mode can run under Presentation Manager, Windows and DOS (using the GUI emulation feature).
User interfaces created with Dialog System character mode can run under DOS, OS/2 and UNIX.
Using Dialog System, changes can be made to the user interface independent of the underlying program code. This can result in a reduction of up to 70% in the amount of code in a typical business application.
Cooperative processing with IBM CICS OS/2 is supported with sample programs provided with Dialog System. Cooperative processing is also supported using the COBOL APPC or HLLAPI Application Programming Interface (API) support in the Compiler as well as the protocol independent Common Communications Interface (CCI) for network applications.
For application development Dialog System requires Micro Focus COBOL which is the IBM SAA COBOL compiler. This means that your application program need only be concerned with basic data processing tasks. Since much of the complexity of a traditional program is there to handle the user interface, the use of Dialog System means that your programs are smaller, simpler and much easier to code.
For more information on Dialog System, see your Micro Focus sales representative.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Comparison of Methods for Creating User Interfaces | Low-level Routines for Character Interfaces | |