PreviousSample Session Configuring Development ToolsNext

Chapter 4: Sample Session with Dialog System

Dialog System is included in Server Express as a powerful utility for use in creating character mode screens. This sample session will familiarize you with Dialog System.

By creating the sample program Test1 you will learn the basic steps to define the data items for a screenset, design its on-screen appearance, test it, write a program to use it, specify the effects of keys, and set screen attributes.

All the features covered are described in detail in your Dialog System Character Mode User's Guide.

In Dialog System, data areas in memory (known in COBOL as data items) are referred to as fields. This same term is used for areas on the screen; for example data entry fields are areas where data can be entered.

4.1 Creating a Screenset

In this section you will:

  1. Invoke the Dialog System definition software.

  2. Define a simple Data Block.

  3. Save a screenset to disk, and then load it back.

  4. Paint a panel.

  5. Reposition fields in the panel.

  6. Test the running of your screenset.

4.1.1 Starting Dialog System

  1. Enter:
  2. Press F9 on the main menu.

    The Dialog System banner appears, followed by the main menu of Dialog System.

You are now in the Dialog System definition software, ready to define a screenset.

You could alternatively have entered the Dialog System definition software directly from the command line, by entering the command:


This sample session produces a simple data entry screen for entering the following product information:

The sample COBOL program TEST1.cbl is used in a later part of this sample session.

4.1.2 Defining A Data Block

Here you define the Data Block for your screenset. When your application calls the Dialog System run-time software, it passes the Data Block as a parameter. The Data Block contains all the fields that the application wishes to display on the various panels that make up a screenset.

  1. Select F2=data-definition, then select F2=data-fields from the menu that appears.

    The Data Definition menu appears, together with a list, as shown in Figure 4-1. The cursor is positioned in the first entry in this list, under the column heading Field. This is where you are going to enter the description of the first field, P-CODE.

    Figure 4-1: The Data Definition Menu

Note: During the following steps, if you type anything invalid, an error message is displayed. Use the cursor-left, cursor-right, Tab and Backtab keys to return to your error and correct it. Some fields are mandatory, so you may have to enter data before you can leave a field.

  1. Type P-CODE and press the Tab key.

    This takes the cursor to the Fmt column, where you specify the field format. Dialog System supports four field formats:

  2. Type "X" under the Fmt heading.

    The cursor automatically skips to the next column, which is headed Int.Dc. Here you enter the field size, as an integer part and a decimal part. P-CODE is going to be 6 characters long, with no decimal places,

  3. Type "6".

    There are three further columns in the list, called Comp, Rpts and Val. You do not need to use these in this session.

  4. Press Enter to get a new line.

    The second line is highlighted.

  5. Enter the values "P-NAME", "X" and "15" into the Field, Fmt, and Int.Dc columns.

  6. Press Enter to get a new line and specify the next field as:

  7. Press Enter to get a new line and specify the next field as:

    The list of fields should now be as shown in Figure 4-2.

    Figure 4-2: The Completed List of Fields

  8. Press Esc twice to exit from the Data Definition menu. This brings you back to the Dialog System main menu.

What you have just defined has disappeared from the screen, but it has not been lost. Generally, pressing Esc returns you to a higher level menu and retains what you have just defined. To confirm this, enter the Data Definition window again (select F2=data definition and then F2=data fields) to see it. Then press Esc twice to return to the main menu.

4.1.3 Saving Your Screenset

The next step is to save the screenset on disk.

  1. Type F4=save-screenset at the Alternate menu. You are prompted to give the screenset a name.

  2. Enter the name "TEST1" and press Enter. There will be some disk activity, then the main menu returns. However, there is a difference; the words "New set" on the status line have been replaced with the name of the screenset, "TEST1".

The screenset has now been saved. At this point you could if you wished exit Dialog System and come back to this screenset later.

Dialog System saves all character mode screensets with the extension .S, so your screenset TEST1 is stored on disk in a file named TEST1.S.

4.1.4 Loading a Screenset

Although you are not going to exit Dialog System at this point, let's clear the screenset from memory and then reload it from disk just to confirm that it has been saved successfully.

  1. Press F2=initialize in the Alternate menu. You are prompted:
    Initialize. Are you sure? Y/N 
  2. Reply Y.

    The word "TEST1" changes back to "New set". You are now ready to start another screenset.

  3. Press F3=load-screenset in the Alternate menu. The menu prompts for a screenset name. The menu also shows F2=directory.

  4. You can either type the name of the screenset at the prompt, or press F2=directory and select it from the list of existing screensets that is then displayed. To use the directory function, after pressing F2 select TEST1.S with the cursor keys. Then press Enter. This copies the name TEST1.S to the prompt line.

  5. Whether you typed it yourself or used the directory function, you should now have the name TEST1.S at the prompt line. Press Enter.

TEST1 is now loaded and you can begin further development of this screenset.

4.1.5 Painting a Panel

Now that you have defined the fields, you need to specify the visual aspects of the screen. You do this by painting a panel.

  1. On the main menu, press F3=panels. The Panel menu appears, as shown in Figure 4-3.

    Figure 4-3: The Panel Menu

  2. You can move the cursor around using the cursor keys and the Tab, Backtab, Home, and End keys. Move the cursor to row 5, column 10. You can check this from the Row and Col positions displayed on the status line just above the menu.

  3. Press F2=mark/unmark.

    A highlighted character appears in the cursor position. Now move the cursor to row 15, column 70. The entire rectangle thus marked becomes highlighted.

  4. Press Enter to define this area as a panel.

    You are prompted to give it a name.

  5. Type STOCK and press Enter.

    The panel has now been defined and a border is drawn around it.

    The menu has now changed to the Panel Painting menu shown in Figure 4-4. You are in panel painting mode and the cursor is now restricted to being inside the panel. The row and column numbers are now relative to the panel. The word "STOCK" appears at the left-hand end of the status line.

    Figure 4-4: The Panel Painting Menu

Note: If you press Esc, you return to the Panels menu again. If you do this by accident and you want to return to painting the Stock panel again, select F3=panel-list from the Panels menu. This brings down a list of panels - it will have just one entry, STOCK - with a highlighted selection bar. You select a panel by using the cursor-up and cursor-down keys to move the selection bar and pressing Enter at the required panel.

Next you add the data entry fields and their accompanying text to your panel. You put the cursor in the required position and then type the heading, or select and describe the field, that you want. First you add the accompanying text, then the data entry fields.

  1. Move the cursor to row 3, column 10 (remember these numbers are now relative to the panel) and type "PRODUCT CODE".

  2. Similarly, type "PRODUCT DESCRIPTION" at row 5, column 10; "PRODUCT COST PRICE" at row 7, column 10; and "PRODUCT QUANTITY" at row 9, column 10. Your panel should now be as shown in Figure 4-5

    Figure 4-5: The Panel With Text Added

  3. Move the cursor to row 3, column 24 and press F3=field.

    The menu changes and the Field Selection panel appears, as shown in Figure 4-6. This is a table showing fields and related information, enabling you to define properties for the entry fields you defined earlier. The part containing their names is in a highlighted box. You use the cursor-up and cursor-down keys to select a data item. A highlighted selection bar indicates the item selected.

    Figure 4-6: The Field Selection Panel

  4. Ensure P-CODE is selected and press Enter.

    The highlighting moves to the Usage part of the Field Selection panel. This part of the table contains a selection bar too. You can now specify the usage of P-CODE, that is, the purpose for which P-CODE will be used. (Do not confuse this usage with the USAGE clause in COBOL. )

    One of the entries in the Usage list has the symbols > and < beside it, to show it's currently selected. The default usage is IN, which means this field is to be used for input.

    To select a usage, you move the selection bar to it and press the space bar. Only one usage can be active at a time. The usage you want for P-CODE is in fact the default, IN.

  5. Ensure IN is selected and press Tab.

    The highlighted surround now moves to the Properties part of the Field Selection Panel, and a selection bar appears there.

    You select a property by moving the selection bar to it and pressing the space bar. Several properties can be active at one time. You can deselect a property by pressing the space bar again.

  6. Ensure AUTO is the only property selected and press Tab.

    The selection bar moves to the Format part of the Field Selection panel.

    You can have only one format active. The use of formats will be discussed later.

  7. Ensure ALPHANUMERIC is selected and press Tab.

    The selection bar moves to the Panel Length part of the Field Selection panel. This is the length of the field, P-CODE, when it is displayed on your panel. The Panel Length defaults to the length of the field in the Data Block, which in this case is 6. You can make the field length displayed on the panel shorter than 6, but not longer.

  8. Ensure the entry in Panel Length is 6.

    The Field Selection panel at this point should be as shown in Figure 4-7. If you have got any of it wrong use the Tab and Backtab keys to move around and correct it.

    Figure 4-7: The Completed Field Selection Panel

  9. Press Enter to enter the selections you have typed.

  10. Press Esc.

    The Field Selection panel disappears and you can see your panel again. A row of six caret characters appears on your panel at the point where the cursor is. You can move the cursor around your panel.

  11. Move the cursor to row 5, col 33.

    This is where you will position P-NAME

  12. Press F3=field.

    The Field Selection panel appears again, ready for you to describe another field.

  13. Put the selection bar on P-NAME and press Enter.

    The highlighted surround moves to the Usage part.

  14. You want all the defaults, so you need not go through the description process used earlier. Simply press Enter again.
  15. Similarly, insert P-COST at row 7, column 30 and P-QUANT at row 9, column 28. Don't worry if you get these positions wrong, there is a very easy way to correct them.

    Your panel should finish up looking similar to Figure 4-8.

Figure 4-8: The Panel With Entry Fields Added

4.1.6 Moving Fields Around

To make the panel look neater, you can align the data entry fields.

  1. Move the cursor around your panel.

    As the cursor moves into a field, the word "Field" appears on the status line together with the name of the field.

  2. Move the cursor to the first caret character of the field P-CODE.

  3. Press F2=mark.

  4. Move the cursor right so that the highlighting covers the entire field P-CODE.

  5. Press F7=cut-to-block.

    The menu changes to the Block menu.

  6. Press the cursor keys and observe what happens.

    You can move the cut block to anywhere on the panel. You want to keep this field in line with its prompt "Product Code", but move it to the right by approximately 9 character positions so you can line all the fields up underneath each other.

  7. Move the cut block to its correct position and select F2=paste-block.

    The block, containing the field, is pasted back on the panel in the required position.

  8. Do the same with the other fields so that they all line up correctly.

    The panel should finally look something like Figure 4-9.

    Figure 4-9: The Panel After Tidying Up

  9. You have now completed defining the panel for your screenset. Press Esc twice to get back to the main menu. Then save the screenset, using F4=save-screenset in the Alternate menu.

4.1.7 Running Your Screenset

You can run the screenset without writing a program. This will allow you to evaluate and test its behavior, and to alter it by simply returning to the screenset definition. This is useful for prototyping your interface.

Figure 4-10: The Trap Window

  1. From the Dialog System main menu, select F6=run. The screen shown in Figure 4-10 appears. This is called the Trap window.

    Do not try to understand this window fully at this point. Just notice that there is a field on the window called Control which has the value "N", meaning new screenset.

  2. To run the screenset, press Enter.

  3. What you see now is the panel you have just painted, with the cursor sitting in the first field on the screen. Try to:

    You can move between fields using the cursor-right and cursor-left keys, but if you try the Tab, Backtab, cursor-up and cursor-down keys they do nothing but beep. The section Dialog later in this chapter will explain how to define effects for keys.

  4. When you have finished moving around the screen, press Esc. You return to the Trap window.

    If you have not returned to the Trap window, you probably accidentally pressed F3=trap on/off when you were first in the Trap window. Simply press the key configured on your UNIX system to be the Interrupt key, followed by Esc.

    This window has changed in several ways (see Figure 4-11):

  5. Press F3=trap on/off and make sure that "off" is highlighted.

  6. Press Enter again. The screenset resumes running.

  7. If you press Esc, nothing happens because you have turned the Trap off. To get back to the Trap, press the Interrupt key, and then press Esc.

    This takes you back to the Trap. A message to show that the Interrupt key has been pressed is shown.

  8. Press Esc. This returns you to the main menu.

  9. Press Esc. You are prompted "Exit. Are you sure? Y/N".

  10. Answer Y to exit from the Dialog System definition software.

4.2 Writing a Related Program

Dialog System handles the interface between a COBOL application program and a user using screen and keyboard. This means an application program only needs to be concerned with basic data processing tasks, and thus it becomes smaller, simpler and much easier to code and maintain.

In the the section Creating a Screenset you developed a user interface consisting of a panel and four data entry fields. Now you will develop and debug a COBOL program to use this interface.

Before you start, make sure the environment variable COBCPY points to $COBDIR/cpylib so that the COBOL system can find the copyfile DS-CNTRL.MF used in this session.

4.2.1 The Program

For this session you need to create the program TEST1.CBL. Its source is as follows:

$set ans85
 working-storage section.
     copy "DS-CNTRL.MF".
     copy "TEST1.CPB".

 procedure division.

     perform program-initialize
     perform call-screen-manager
     stop run.

     initialize test1-data-block
     initialize ds-input-fields
     move ds-new-set to ds-control
     move test1-data-block-version-no to
     move "test1" to ds-set-name.

     call "DSRUN" using ds-control-block,

This program refers to two copyfiles. They are called DS-CNTRL.MF and TEST1.CPB.

DS-CNTRL.MF is provided with Dialog System and defines the Control Block that your program passes to the Dialog System run-time software. The Control Block contains basic information about running the screenset. It is a fixed part of Dialog System and applies to all screensets. See your Dialog System Character Mode User's Guide for a description of the Control Block.

TEST1.CPB defines the fields passed between your program and Dialog System. These items are called the Data Block. The Data Block is specific to each screenset. Most of the information in the Data Block is information that you entered when you defined your fields using the definition software. You will generate TEST1.CPB using the Dialog System definition software.

4.2.2 Generating the Data Block

  1. Start up Server Express and enter the Dialog System definition software as before.

  2. Use F3 in the Alternate menu to load your screenset.

  3. Press F5=generate.

    You are prompted for a name for the copyfile. By default it has the name of your screenset with extension .CPB. The sample COBOL program TEST1.cbl expects TEST1.CPB as the name of the copyfile.

  4. Press Enter to accept the default name.

  5. Select F2=data-descriptions.

    A message saying generation is under way is displayed. Once generation is complete, this message disappears.

  6. Exit from Dialog System to the main menu of Server Express.

4.2.3 Running Your Program

To run your screenset, you compile and run the program.

  1. Enter the COBOL editor as before.

  2. Use F3 in the Alternate menu to load the sample program.

  3. Press F2=COBOL.

  4. Press F2=cmpl/animate

  5. Ensure that "Compile" is shown on the status line. If it isn't, press F2=compl/anim until it is.

  6. Press Enter.

    The program is compiled.

  7. Press Esc to return to the main menu of Server Express.

  8. Press F6=run.

  9. Press Enter.

    The program runs and displays your panel. Try entering data. You will find it behaves just as it did when you tested it using the Trap.

  10. When you've finished, Press Esc.

    Your program exists to the main menu of Server Express.

4.3 Dialog

This section shows how to define the effect of particular keys.

You do this by defining a dialog. The dialog defines functions to be executed when the user presses a key. These include functions to move between fields, cursor functions, and keyboard functions.

A dialog entry consists of an event such as ESC, meaning "the Esc key has been pressed", and one or one or more functions to be performed if the event occurs. A complete list of Dialog System events and functions is in the Dialog System Character Mode User's Guide.

Dialog can be local to a panel or global to the screenset. You can specify which of these types of dialog takes priority. For example, the next section describes the global dialog associated with the event generated when the Esc key is pressed. The global dialog defines the default behavior whenever Esc is pressed. However, if you define a different local dialog for Esc in one panel, this behavior normally overrides that of the global dialog. (You can change the priority of dialogs, using the F5 screenset switches option in the Alternate menu reached from the main menu of Dialog System.)

4.3.1 Defining Dialog

In this section, you define some dialog so that the Tab key makes the cursor skip to the next field, and Backtab makes the cursor skip to the previous field.

  1. Go back into Dialog System and load the screenset file TEST1.

  2. From the main menu select F4=global-dialog.

    The Dialog Definition menu appears, as shown in Figure 4-12.

    Figure 4-12: The Dialog Definition Screen

    One line is already defined in the dialog. This defines that the event ESC (pressing the Esc key) will cause the action RETC (return to calling program). You have already seen the result of this definition, when you pressed Esc in the running screenset and it exited.

  3. Press Enter to move the selection bar down one line.

  4. Press F2=list.

    A list appears, from which you can select the key whose event you want.

  5. Move up and down this list using the arrow keys (the list scrolls when you reach the bottom) until the selection bar is on the mnemonic for Tab.

  6. Press Enter.

    The list disappears. The mnemonic TAB has appeared in the key column.

    Alternatively, you could have simply typed the mnemonic TAB yourself, or you could select F9=enter-key followed by the key you want, Tab.

  7. Press F6=function-detail.

    The Function Definition panel appears. This is where you define the function or functions to be executed when the Tab key is pressed. Each function consists of a function mnemonic and up to three parameters. The cursor is currently in the Function column.

  8. With the cursor in the Function column, press F2=list.

    This gives you a list of allowable functions.

  9. Move down this list until you find SKNF (the Skip to Next Field function), and press Enter to select it.

    The list disappears. The function name SKNF has appeared in the key column.

    The cursor moves to the Parameter 1 column, where you are required to enter a parameter. The SKNF function requires a parameter saying how many fields to skip. In our case we only wish to skip one field.

  10. Type "0001" into the Parameter 1 column.

    You could also use the name of one of your data fields for this parameter. The skip would then skip to next field as many times as the value in your specified data field at run time.

    Many functions have parameters such as panel name or field name. When a parameter is needed, you are forced to enter it. Again, pressing the F2 key would provide you with a list to select from.

  11. Press Esc.

    The Function Definition panel disappears. The SKNF mnemonic has been placed in the list beside TAB, but its parameters are not visible. This enables you to inspect the functions quickly without bothering about the details of the parameters.

  12. Move down to the next line in the list by pressing Enter.

  13. Enter a dialog line to define that the Backtab key (BTAB) has the function Skip to Previous Field (SKPF). Enter a parameter of "0001" again.

  14. Press Esc to exit the Function Definition Panel, then press F5=sort dialog.

    Your dialog window should now be as shown in Figure 4-13. The order of the items in the dialog does not matter. You can reorder the items using F3=insert-key and F4=delete-key if you wish.

    Figure 4-13: The Dialog You Defined

    The > symbol shown against ESC means it is an event key. This is described in your Dialog System Character Mode User's Guide.

  15. Press Esc to return to the main menu of Dialog System and use F4 in the Alternate menu to save the screenset.

  16. Press Esc to return to the main menu of Server Express and use F6=run to run the screenset.

  17. Try the effect of the Tab and Backtab keys.

    When you ran the screenset earlier, these keys had no effect. Now you will find that they cause the cursor to skip between fields.

  18. When you have run the screenset, press Esc to end the program return to the main menu of Server Express.

This is the end of the Dialog System Character Mode sample session. There are additional examples in the chapter Tutorials in your Dialog System Character Mode User's Guide.

Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousSample Session Configuring Development ToolsNext