PreviousComparison of Methods for Creating User Interfaces Low-level Routines for Character InterfacesNext"

Chapter 2: Overview of Character User Interface Methods

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.

2.1 Overview

The available methods are:

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.

2.2 Using ACCEPT and DISPLAY

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.


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.

2.2.2 Micro Focus Enhanced ACCEPT/DISPLAY

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.


Micro Focus Enhanced ACCEPT/DISPLAY:

 1$set ans85 noosvs mf
 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.                                                   *
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*                                                             *
21 special-names.
22     console is crt.
24 working-storage section 
25 01 into-field              pic x(10).
26 01 pass-word               pic x(08).
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.
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.

2.2.3 Using a Mouse with ACCEPT and DISPLAY Statements

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.

2.2.4 Reference Table: Micro Focus or ANSI ACCEPT and DISPLAY Statements

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
ACCEPT identifier FROM CRT Yes
ACCEPT identifier AT location Yes
MF Exceptions

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.

2.2.5 Run-time Considerations with Micro Focus Enhanced ACCEPT/DISPLAY

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:

link myprog+adis+adisinit+adiskey+adisdyna;
32-bit OS/2: 
link386/NOI myprog+adis+adisinit+adiskey+adisdyna;
cob -x myprog

For full details of creating finished applications, see your Object COBOL User Guide.

2.3 Processing Function Keys

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.


Program to accept and identify a function key.

 1$set noosvs mf ans85
 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.                                                  *
12*                                                            *
13*                        FUNKEY.CBL                          *
14*                                                            *
15*    This program demonstrates how to decode function keys   *
16*    using the x"af" call.                                   *
17*                                                            *
19 special-names.
20     crt status is key-status.
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.
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.
37 procedure division.
38     perform enable-keys
39     perform accept-function-key
40     perform tell-which-key-was-pressed
41     perform stop-run.
43 enable-keys.
44     call x"af" using flag user-key-control.
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.
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.
60 stop-run.
61     stop run.

This program is discussed below.

Lines 19-20:

    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:

    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:

    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:

    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

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.

2.4 Using the Screens Facility

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.

2.4.1 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.


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.

2.4.2 Screen Painting

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.

2.4.3 Anatomy of a Screen Handling Program

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:


Screen handling program.

 identification division.
 data division.
 working-storage section.
 copy "myform.wks".
 screen section.
 copy ""
 procedure division.
     display g-myform.
     accept g-myform.
     stop run.

Two COBOL copyfiles were created: myform.wks and 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 is the Screen Section. The rest of the program, as you can see, consists of division headings and ACCEPT and DISPLAY statements. myform.wks: The Working-Storage Section

Here is the copyfile myform.wks:


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. The Screen Section

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.


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
   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
    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.

2.5 Screen Handling Support Functions

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.

2.5.1 Example: Writing Screen Attributes with popup.cbl

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.


Here is the source for popup.cbl:

  1$set ans85 noosvs mf
  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.                                                  *
 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*                                                            *
 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.
 46 01 top-row                   pic 9(2) comp-x value 05.
 47 01 bottom-row                pic 9(2) comp-x value 14.
 49 01 reverse-vid               pic x(15)       value all x"70".
 50 01 black-and-white           pic x(15)       value all x"07".
 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.
 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.
 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.
 70 78 user-fn-key               value "1".
 71 78 adis-fn-key               value "2".
 73 78 f1-key                    value 1.
 74 78 f2-key                    value 2.
 75 78 f3-key                    value 3.
 76 78 f4-key                    value 4.
 78 78 carriage-return           value 0.
 79 78 up-arrow                  value 5.
 80 78 down-arrow                value 6.
 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.
 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.".
 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 " ".
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 "+-----------------------+".
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 "+-----------------------------+".
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.
148 start-up.
149* Display user screen
150     display g-picscrn
152* Move cursor off screen
153     call "CBL_SET_CSR_POS" using cursor-off-screen
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
163* Enable function keys
164     call x"af" using set-bit-pairs
165                      user-key-control
166     .
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.
189 pop-up-help.
191 pop-up-story1.
193 pop-up-story2.
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.
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.
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.
221 clear-block.
222     call "CBL_WRITE_SCR_ATTRS" using screen-position
223                                      black-and-white
224                                      string-length.
227 mark-block.
228     call "CBL_WRITE_SCR_ATTRS" using screen-position
229                                      reverse-vid
230                                      string-length. Data Division in popup.cbl

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. Procedure Division in popup.cbl

In the start-up paragraph, the following actions take place:

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. Use of CBL_WRITE_SCR_CHATTRS

The video I/O routine CBL_READ_SCR_CHATTRS is used to save the initial screen. In clear-pop-up, the screen is redisplayed. Use of CBL_WRITE_SCR_ATTRS

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.

2.6 Panels

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:

2.6.1 Basic Concepts of Panels

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.

2.6.2 How are Panels and Windows Manipulated in Your Program?

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:

2.6.3 How to Use the Panels Facility

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
call "PANELS" using panels-parameter-block

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.

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.


Creating, displaying, and deleting a panel and window:

  1$SET ans85 mf noosvs
  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.                                                  *
 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*                                                            *
 23 working-storage section.
 26*  panels parameter block.
 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.
 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 "                    ".
 76 01 ws-attrib-buffer.
 77    05 filler           pic x(300) value all x"07".
 79 01 ws-accept           pic x.
 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.
 91 redraw-screen.
 92     move 2 to ppb-function 
 93     call "panels" using panels-parameter-block 
 94     perform status-check.
 96 proceed-to-create-a-panel.
 97     display "press return to make the panel appear"
 98     accept  ws-accept 
 99     perform redraw-screen.
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.
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.
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.
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.
145 status-check.
146     if ppb-status not = 0
147        display "bad status" 
148        perform stop-run.
150 stop-run.
151   display "press return to stop the PANDEMO program"
152   accept ws-accept 
153   stop run.

2.6.4 Anatomy of a Panels Program

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:


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:


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:


This paragraph simply prompts the user to press Enter before the panel is created and enabled.

Lines 101-113:


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:

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:


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:

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:


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:


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:


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:


The program is halted.

2.6.5 Other Panels Applications and Sample Programs

The following is a list of other Panels sample programs supplied:


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.

2.7 Customizing Your ACCEPT/DISPLAY Environment with Adiscf

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.

2.7.1 What is Adis?

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.

2.7.2 Why Would You Modify adisctrl?

There are several reasons you might want to modify adisctrl:

2.7.3 How Do You Modify adisctrl?

You modify adisctrl through a configuration utility called Adiscf. You can invoke this utility directly from the command line.

2.7.4 Packaging Considerations When adisctrl is Modified

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.

2.8 Customizing Your Keyboard with Keybcf

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.

2.8.1 Packaging Considerations with a Modified Keyboard Configuration

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.

2.9 Dialog System

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.

2.9.1 Interface Management Technology

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.

2.9.2 Portability

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.

2.9.3 Reduction in Program Code

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.

2.9.4 Cooperative Processing

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.

PreviousComparison of Methods for Creating User Interfaces Low-level Routines for Character InterfacesNext"