| Sample Session | Configuring Development Tools | |
Dialog System is included in Object COBOL as a powerful utility for use in creating character mode screens. This sample session will familiarize you with Dialog System.
Using 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 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.
The tutorial programs supplied with Object COBOL are in subdirectory demo in the directory pointed to by the $COBDIR environment variable.
Before you use any of them, we recommend you copy them to your own work directory to avoid the danger of other users working with them at the same time.
tbox
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:
ds
This sample session will produce 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.
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.
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.
This takes the cursor to the Fmt column, where you specify the field format. Dialog System supports four field formats:
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,
There are three further columns in the list, called Comp, Rpts and Val. You do not need to use these in this session.
The second line is highlighted.
The list of fields should now be as shown in Figure 4-2.
Figure 4-2: The Completed List of Fields
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.
The next step is to save the screenset on disk.
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.
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.
Initialize. Are you sure? Y/N
The word "test1" changes back to "New set". You are now ready to start another screenset.
TEST1 is now loaded and you can begin further development of this screenset.
Now that you have defined the fields, you need to specify the visual aspects of the screen. You do this by painting a panel.
Figure 4-3: The Panel Menu
A highlighted character appears in the cursor position. Now move the cursor to row 15, column 70. The entire rectangle thus marked becomes highlighted.
You are prompted to give it a name.
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.
Figure 4-5: The Panel With Text Added
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
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.
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.
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.
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.
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
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.
This is where you will position P-NAME
The Field Selection panel appears again, ready for you to describe another field.
The highlighted surround moves to the Usage part.
Your panel should finish up looking similar to Figure 4-8.
Figure 4-8: The Panel With Entry Fields Added
To make the panel look neater, you can align the data entry fields.
As the cursor moves into a field, the word "Field" appears on the status line together with the name of the field.
The menu changes to the Block menu.
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.
The block, containing the field, is pasted back on the panel in the required position.
The panel should finally look something like Figure 4-9.
Figure 4-9: The Panel After Tidying Up
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
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.
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.
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):
Figure 4-11: The Trap After Running the Screenset
This takes you back to the Trap. A message to show that the Interrupt key has been pressed is shown.
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 previous section, the section Creating a Screenset, you developed a user interface consisting of a panel and four data entry fields. Now you will develop and animate a COBOL program to use this interface.
Before you start, make sure the environment variable COBCPY points to $COBDIR/src/dialog so that the COBOL system can find the copyfile DS-CNTRL.MF used in this session.
In this session you use the supplied sample program TEST1.cbl referred to earlier. Its source is a follows:
$set ans85
working-storage section.
copy "DS-CNTRL.MF".
copy "TEST1.CPB".
procedure division.
main-process.
perform program-initialize
perform call-screen-manager
stop run.
program-initialize.
initialize test1-data-block
initialize ds-input-fields
move ds-new-set to ds-control
move test1-data-block-version-no to
ds-data-block-version-no
move "test1" to ds-set-name.
call-screen-manager.
call "DSRUN" using ds-control-block,
test1-data-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 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.
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.
A message saying generation is under way is displayed. Once generation is complete, this message disappears.
To run your screenset, you compile and run the program.
The program is compiled.
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.
Your program exists to the main menu of Object COBOL.
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 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 Alt+F5 screenset switches option reached from the main menu of Dialog System.)
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.
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.
A list appears, from which you can select the key whose event you want.
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.
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.
This gives you a list of allowable functions.
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,
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.
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.
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 Guide.
When you ran the screenset earlier, these keys had no effect. Now you will find that they cause the cursor to skip between fields.
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 Guide.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Sample Session | Configuring Development Tools | |