Chapter 3: Sample Session in Character Mode

This sample session will familiarize you with the Character Mode version of 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.

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

Product code
Product name
Cost price
Quantity in stock

All the features covered are described in detail later in this online book.

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.

A familiarity with the basic ideas of COBOL may be helpful in using this tutorial.

Creating a Screenset

In this section you will:

Invoke the Dialog System definition software.
Define a simple Data Block.
Save a screenset to disk, and then load it back.
Paint a panel.
Reposition fields in the panel.
Test the running of your screenset.

Starting Dialog System

Windows:
To start the Dialog System definition software on Windows, from the Net Express IDE, select UNIX, Dialog for UNIX.

UNIX:
On UNIX, the tutorial programs for this product 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, as follows:

Copy the source file TEST1.cbl from $COBDIR/demo into one of your work directories, and cd into that directory.
Enter:
```
tbox
```
Press Ctrl-C to get the Ctrl menu, then press F6.
The Dialog System banner appears, followed by the main menu of Dialog System.

You are now ready to define a screenset.

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.

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 3-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 3-1: The Data Definition Menu

Note:

During the following steps, if you type anything invalid, an error message will be displayed. Use the cursor-left, cursor-right, Tab and Back-tab keys to return to your error and correct it.

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:
- A = Alphabetic
- X = Alphanumeric
- 9 = Numeric
- S = Signed Numeric
Because the field you are defining is alphanumeric, 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, so enter "6".
There are three further columns in the list, called Comp, Rpts and Val. You do not need to use these in this session.
Now enter the details for the next field, the product name. Press Enter to get a new line. The second line is highlighted. Enter the values "P-NAME", "X" and "15" into the Field, Fmt, and Int.Dc columns, respectively.
Enter the remaining two fields as:
- P-COST, numeric (9), three digits before the decimal point, two digits after the decimal point (3.2).
- P-QUANT, signed numeric (S), four digits before the decimal point, no digits after the decimal point (4).
The list of fields should now be as shown in Figure 3-2.

Figure 3-2: The Completed List of Fields
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.

Saving Your Screenset

The next step is to save the screenset on disk.

Type Alt+F4 (that is, hold down the Alt key and press F4). You are prompted to give the screenset a name. A default path, which you can alter, appears.
Windows:
(On Windows, we recommend you use the demo subdirectory of the Dialog System directory - for example c:\netexpress\UNIX\dschar\demo).
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" 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.

Loading a Screenset

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

Press Alt+F2=initialize. You are prompted:
```
Initialize. Are you Sure? Y/N
```
Reply Y.
The word "TEST1" changes back to "New set". You are now ready to start another screenset.
Press Alt+F3=load screenset. The menu prompts for a screenset name. The menu also shows F2=directory.
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.
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.

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.

On the main menu, press F3=panels. The Panel menu appears, as shown in Figure 3-3 (the figure shows just the menu itself, not the whole screen).

Figure 3-3: The Panel Menu
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.
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 out becomes highlighted. This area is going to be your working panel.
Press Enter to define this area as a panel.
You are prompted to give the panel a name. Enter 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 3-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.

Figure 3-4: The Panel Painting Menu

The word "STOCK" appears at the left-hand end of the status line. The menu has a single line drawn along the status line instead of the double line in the main menu.

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.

Try moving the cursor around with the cursor keys and the Tab, Backtab, Home and End keys. Watch the row and column counters.
Press the Ins key. Look at the Ins characters on the status line. When insert mode is on they are highlighted.
Press the Ins key again. Watch the status line.
Press the Caps Lock and Scroll Lock keys and watch the status line.
Turn all these keys off for the moment.
Now 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 add the accompanying text. Move the cursor to row 3, column 10 (remember these numbers are now relative to the panel) and type "Product Code".
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 3-5.

Figure 3-5: The Panel With Text Added
The next step is to define the data entry fields. Move the cursor to row 3, col 24 and press F3=field. The menu changes and the Field Selection panel appears, as shown in Figure 3-6. This is a table showing fields and related information, allowing you to define the properties you want for the entry fields. The fields listed are the fields you defined earlier, and the part of the table containing their names is in a highlighted box.

Figure 3-6: The Field Selection Panel
You use the cursor-up and cursor-down keys to select a data item. A highlighted selection bar indicates the item selected. Select P-CODE and press Enter.
The highlighting now surrounds 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. This entry is the currently selected usage. The default usage is IN, which means this field is to be used for input.

To select a usage, 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, so select this. Then press Tab.
The highlighted surround now moves to the Properties part of the Field Selection Panel, and a selection bar appears there. You can now specify the properties of P-CODE, that is, how the field will behave.
You can 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 de-select a property by pressing the space bar again.

Make sure that AUTO is the only property selected. Then press Tab.
The selection bar now 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. Make sure that ALPHANUMERIC is selected. Then press Tab.
You can now enter the Panel Length. 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.
Make sure that the entry in Panel Length is 6.

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

Figure 3-7: The Completed Field Selection Panel
Press Enter.
Press Esc to return to the Field Selection panel.
A row of six caret characters appears on your panel at the point where the cursor is. The Field Selection panel is now ready for you to position and describe another field.
You now want to position P-NAME.
Move the cursor to row 5, col 33. Press F3=field.
Put the selection bar on P-NAME and press Enter. The highlighted surround moves to the Usage part.
This time you want all the defaults, so you need not go through the description process used above. Simply press Enter a second time. Press Esc to return to the Field Selection panel.
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.
When you have finished positioning and describing the fields, your panel should look similar to Figure 3-8.

Figure 3-8: The Panel With Entry Fields Added
Move the cursor around your panel. You can see that, as the cursor moves across a field, the word field appears on the status line together with the name of the field.

Moving Fields Around

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

Move the cursor to the first caret character of the field P-CODE.
Press F2=mark to turn on marking.
Move the cursor right so that the highlighting covers the entire field P-CODE.
Press F7=cut-to-block.
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 6 character positions so you can line all the fields up underneath each other.
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.
Do the same with the other fields so that they all line up correctly. The panel should finally look something like Figure 3-9.

Figure 3-9: The Panel After Tidying Up
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 Alt+F4.

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.

From the main menu select F6=run. After some disk access the screen shown in Figure 3-10 appears. This is called the Trap window.

Figure 3-10: The Trap Screen
Do not try to understand this window fully at this point. Just be aware that there is a field on the window called control which has the value "N", meaning new screenset.
To run the screenset, press Enter.
What you see now is the panel you have just painted, with the cursor sitting in the first field on the screen. Try to:
- Enter data into these fields.
- Enter alphabetic information into one of the numeric fields.
- Use the cursor-right and cursor-left keys.
  These will allow you to move through and from field to field in either direction.
- Use the Tab and Backtab keys.
- Use the cursor-up and cursor-down keys.
Note the effects these keys have. Some keys do nothing but beep. The section Dialog later in this chapter will explain how to define effects for keys.
When you have finished moving around the screen, press Esc. You return to the Trap window.

Figure 3-11: The Trap After Running the Screenset

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 Ctrl+Break followed by Esc in this case.

This window has changed in several ways (see Figure 3-11):
- The value of the control field has changed to "C". This means continue with the current screenset.
- At the top right of the window the panel name is displayed. There are other values up here that we will use later.
- The list of data fields in the bottom half of the window now contains the values you entered.
Press F3=trap on/off and make sure that "off" is highlighted.
Press Enter again. The screenset resumes running.
If you press Esc, nothing happens because you have turned the trap off. To get back to the trap, press Ctrl+Break to enable the trap, and then press Esc.
This takes you back to the trap. A message to show that Ctrl+Break has been pressed is shown.
Press Esc. This returns you to the main menu.
Press Esc. You are prompted "Exit. Are you sure? Y/N".
Answer Y to exit from the Dialog System definition software.

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

The Program

Use an editor to enter the program test1.cbl below.

$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 COPY-files. They are called ds-cntrl.mf and test1.cpb.

ds-cntrl.mf is provided with the Dialog System software 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.

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 generate test1.cpb from the definition software.

Generating the Data Block

Start up the Dialog System definition software as before, and then load your screenset using Alt+F3.
Press F5=generate.
You are prompted for a name for the copyfile. By default, the copyfile will have the name of your screenset with an extension .cpb. If you wish, you can change the name. The sample COBOL program expects test1.cpb as the name of the copyfile, so press Enter to accept this name.
Select F2=data-descriptions. This starts generation. A message saying generation is under way is displayed. Once generation is complete, this message disappears.
Exit from Dialog System.

Running Your Program

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

Windows:
On Windows:

From the IDE, select File > New, and double-click Project from the list.
You want to create an empty project with a name of test1, and select the \UNIX\dschar\demo directory as the folder to contain the project.
Select Project > Properties and then click IDE > Import >Import. Click on COBCPY and then OK. COBCPY is then displayed. Double-click on this, so that it is shown in the Variable and Value fields at the bottom of the dialog box.
Insert c:\netexpress\unix\dschar\source; at the beginning of the entry in the Value field, and click Set and OK, OK.
Right-click in the left-hand pane of your project window to add files to the project. Select test1.cbl and click Add.
Click Rebuild, and click Yes to rebuild the whole project.
Now, click Run to run your program.

UNIX:
On UNIX:

Enter the COBOL editor as before.
Use Alt+F3 to load the sample program.
Press F2=COBOL.
Press F2=cmpl/animate
Ensure that "Compile" is shown on the status line. If it isn't, press F2=compl/anim until it is.
Press Enter.
The program is compiled.
Press Esc to return to the main menu.
Press F6=run.
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.
When you've finished, Press Esc.
Your program exists to the main menu.

Dialog

This section shows how to improve the screenset's functionality by defining the effect of particular keys.

You do this by defining a dialog. The dialog defines procedures and/or functions to be executed when the user presses a key. Functions include functions to move between fields, cursor functions, and keyboard functions. Dialog can be local to a panel or global to the screenset. You can specify which of these types of dialog is to be resolved first.

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 order in which dialogs are resolved. You change the default setting using the screenset switches option reached from the main menu, Alt+F5.)

Defining Dialog

Go back into Dialog System and load the screenset file test1.
From the main menu select F4=global-dialog. The Dialog Definition menu appears, as shown in Figure 3-12.

Figure 3-12: The Dialog Definition Screen

There is one line 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 returned to the trap.

A dialog entry consists of an event (for example ESC) and one or more functions to be performed if the event occurs. A complete list of Dialog System functions can be found in the chapter Function Code List.
You will 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 selection bar is currently in the top line of the dialog list. Press Enter to move it down one line.
The cursor is now on the second line. This is where you define the key that is pressed. The various keys on the keyboard have mnemonics associated with them. For example, Esc has the mnemonic ESC. To see the list of mnemonics, press F2=list.
A list appears, from which you can select the key that you want.
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.
Press Enter. The mnemonic TAB appears in the key column and the list disappears.
Alternatively, you can simply type the mnemonic TAB yourself, or you can select F9=enter-key followed by the key you want (Tab).
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.
With the cursor in the Function column, press F2=list.
This gives you a list of allowable functions. Move down this list until you find SKNF (the Skip to Next Field function). Select it by pressing Enter. The function name SKNF appears in the key column and the list disappears.
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, so 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 provides you with a list to select from.
Press Esc. The Function Definition panel disappears, and you are ready to define the next key.
The SKNF mnemonic has been placed in the list beside TAB, but its parameters are not visible. This allows you to inspect the functions quickly without bothering about the details of the parameters.
Move down to the next line in the list by pressing Enter. 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.
Press Esc to exit the Function Definition Panel, then press F5=sort dialog.
Your dialog window should now be as shown in Figure 3-13. The order of the items in the dialog does not matter. You can re-order the items using F3=insert-key and F4=delete-key if you wish.

Figure 3-13: The Dialog You Defined

(The >symbol shown against ESC means it is an event key.)
When your dialog is correct, press Esc to return to the main menu and then save the screenset using Alt+F4.
Now run the screenset again, as described in the section the section Running Your Screenset earlier. Try the effect of the Tab and Backtab keys.
When you have run the screenset, press Esc to return to the trap window and then again to get back to the main menu.

Attributes

The panel you have created is rather plain. If you are using a color screen, it would be good to improve the panel's visual effect. When you painted the panel earlier, you might have noticed that the status line on the Panel Painting menu contained the word Attribute. This refers to the color on a color screen, and the attributes of highlighting and underline on a monochrome screen.

In this section, we assume you are using a color screen. If you are using a monochrome screen, changes of color described in this section will appear as changes of highlighting and underlining.

From the main menu, go back to the Panel Painting Menu by pressing F3=panels, then F3=panel-list. Select the panel STOCK. The word Attribute on the status line is shown on the screen in the same color as the text that you typed onto the panel.
Press F6=attribute-roll several times and observe the effect on the word Attribute.
You can see that the color of the word changes. There are six different colors for the word. These colors make up your current attribute palette.
Roll to a color you have not yet used on the panel and then type some text on the panel. The text is typed in the current color.
Move the cursor to a text item and press F5=paint-attribute several times. The current color is painted onto the text.
Move the cursor to a data field and press F5=paint-attribute just once. The current color is painted onto the entire field.
Mark a block which includes both text and data, then press F5. This block must not partly cover any data fields. The entire block is painted with the selected attribute.

The current attribute palette contains six active attributes. One of the six is the default background attribute and the other five are called the roll attributes. These six attributes are preconfigured to behave reasonably on both a color and monochrome screen. You can change the attributes to any of the 256 found on your personal computer.

Your panel is probably a mess now, so return to the main menu and reload the screenset from the clean version of Test1 on disk. Then go to the Panel Painting Menu again.

Select the Stock panel from the panel list again.
Press Alt+F3=attribute-palette. The menu shown in Figure 3-14 appears. The bottom line of this menu contains X characters displaying the 256 attributes. You can select any six of these to reconfigure the current attribute palette.

Figure 3-14: The Attributes Menu
You can see an arrow at the bottom center of the screen pointing at one of the attributes. This attribute is also displayed on the status line on the word attribute.
Using the cursor-left and cursor-right keys or Tab and Backtab, move the cursor left and right along the set of attributes and watch the effect.
Find an attribute you like, then press F7=default-attribute. This sets the default attribute for the panel, so the entire panel changes to this attribute.
Choose five more attributes that you like and select them by pressing each of the keys F2 through F6 in turn.
The attributes shown against these function keys, together with the default attribute, make up the current attribute palette.
Press Esc to return to the panel painting menu.
Use the attributes you have chosen to paint all the text with one attribute and all the data fields with a different attribute.
Save the screenset, then run your program test1.cbl again.

This is the end of the Dialog System Character Mode sample session. There are additional examples in the chapter Tutorials.