Creating a Web Database Application | Completing and Running Your Windows GUI Application |
In this and the next session you create a Windows graphical application.
In this session, you use Windows GUI Application Wizard and Dialog System to create the user interface and the program to process the data. You use the IDE to run the application to see the appearance of the interface.
In the next session, Completing and Running Your Windows GUI Application, you add the business logic to the program and run the complete application.
You need to have read the chapter Start Here for the Tutorials and worked through the first session, Using NetExpress, before you do this session.
You use Windows GUI Application Wizard to create windows and dialog boxes for display on a Windows system. These are the user interface to your application. From within this Wizard, you enter Dialog System, where you design and edit their layout. The set of windows and dialog boxes you design is called a screenset. Dialog System creates a screenset file defining the windows and dialog boxes you create.
You also use Dialog System to generate a COBOL program to handle the screenset. This is called the associated program.
There are four steps in creating a screenset:
You write the dialog mentioned in Step 4 in Dialog System's own scripting language.
Generally, the Dialog System documentation uses the term graphical objects, or just objects, when talking about controls.
If you have closed NetExpress, open it as before. If any project window or other windows are open, close them.
In this sample session you:
You could start by creating a project in the way described in the chapter Using NetExpress, but if you go straight ahead and create the screenset NetExpress will give you an opportunity to create the project. To create the screenset:
The project window for the project appears. So does the first page of Windows GUI Application Wizard.
A Single Document Interface (SDI) consists of just one window. An MDI consists of a number of windows and/or dialog boxes, with one window as their parent.
This specifies that the main window is to have a status bar and toolbar, and also a menu bar - the toolbar and menu bar are created together.
The two dialog boxes you are skipping enable the use of Dialog System Extensions, and enable you to modify run-time behavior. We will accept the defaults.
The next dialog box shows a summary of what you have selected.
The Windows GUI Application Wizard generates the screenset and program, and finishes. The names of the generated files are added to the project, then the project is scanned for dependencies.
Then Dialog System is loaded.
You screen now looks something like Figure 12-1. The positions of the three individual windows may vary. You may want to move them around your screen so you can see them all clearly.
Figure 12-1: The Screen with Dialog System Loaded
The two new windows are:
The window titled "WIN-01 Window Title" is where you will design your screenset. This window WIN-01 is the main window of your screenset. A child window, WIN-02, is shown within it because we specified it as an MDI.
This consists of menu bar, toolbars and status bar, with the title "Dialog System - Welcome.gs" above and "Editing WIN-01" below. Initially it may overlap WIN-01 on your screen.
You may want to bring the project window to the foreground (click in it) to see how the project has changed. Then click in Dialog System and WIN-01 to bring them to the foreground again.
On-screen objects that contain data - objects such as entry fields - need to be associated with data items. Data is passed between these data items and the on-screen objects.
In this tutorial we define the data items now and the objects in a later section. It's not essential to do it this way round. As you'll see later, you can test the appearance and behavior of your screenset without data. However, it's generally best to define your data first, so that you have a clear idea of what information has to be passed to, and obtained from, the user. You can change the appearance of the screenset without changing any data definitions.
The data items you define are called the data block. When the generated program calls Dialog System's run-time support module, DSGRUN, it passes the data block as a parameter. This is how data is passed between the COBOL program and the screenset.
To define data items, you use the Dialog System window. Ignore WIN-01 for now.
Dialog System provides two modes of entering data field definitions. In Prompted mode you are prompted with lists of choices and dialog boxes to complete. This helps if you are not familiar with the syntax of data declarations in Dialog System. In unprompted mode (also called editor mode) you type the declarations directly. We will use unprompted mode.
The Data Definition window appears. Specialized edit windows like this are used throughout Dialog System for entering different kinds of information. It has its own menu, which we will be using in the next few steps.
You can see some data declarations already present. These were automatically generated when the screenset was created. They are used in the maintenance of the MDI, toolbar, menu bar, and status bar, and you can ignore them.
The line is automatically formatted. You can even type in lower case, and it will be changed automatically to upper case. You have now defined your first data item, I-NAME. The X means it is alphanumeric, and the 12.0 means it is 12 characters long with no decimal spaces. The ".0" must be present, even though the field is alphanumeric; however, you can omit it, and it will be automatically inserted.
Because these data items will be accessed from the generated COBOL program as well as from Dialog System, you have to avoid COBOL reserved words (no warning is given if you use one). This is why we've called it I-NAME rather than NAME.
This is your second data item, GREETING. It is alphanumeric and 22 characters long.
The Data Definition window should now look like Figure 12-2.
Figure 12-2: Data Definition Window with Data Declarations
Although the data definitions disappear from the screen, they are still loaded in memory. They will not be saved to disk till you do a Save later to save the screenset.
When Dialog System generated the screenset and the COBOL program earlier, it generated a copyfile (.cpb) containing a definition of the data block, in COBOL. This copyfile is used in the Working-Storage Section of the generated program, which is where the data is actually held. Now that you have changed the data block you must regenerate this copyfile.
Always remember to regenerate this copyfile whenever you change the data block.
Before going on to the next section, let's save the screenset to safeguard our work so far.
Next you specify the appearance of the user interface. We have already added a status bar, toolbar and menu bar, when we created the screenset, but we now need to add text and entry fields. Controls such as these are generally referred to as "objects" in Dialog System.
The window now visible on the screen, WIN-01, is the parent, or main window, of your screenset. The rectangular outline at the top, marked Welcome TBar, indicates the presence of a menu bar and tool bar, and the one at the bottom, marked Welcome SBar, indicates the presence of a status bar.
In an MDI, the parent window is only a frame for the child windows; you cannot put objects on it. The child windows are what the user actually uses. We have created an MDI with two child windows to show how it's done, but we will use only one of the child windows.
You add objects by using the Object menu or the object toolbar. The object toolbar is quick and easy for mouse users, whereas the menu can also by used by keyboard users. The two are completely equivalent. This session uses the object toolbar.
Dialog System gives all the windows the same initial size. Let's start by resizing them so you can see the whole of WIN-02 within WIN-01.
The Window Properties dialog box is displayed for you to edit the properties of WIN-02.
This creates an entry field - a field where your end-user can enter or display data - at the place where you clicked. You can drag it around with the mouse after you have placed it. Put it towards the right-hand side of the window.
The Entry Field Properties dialog box appears for you to define the properties of the entry field.
This gives the name I-NAME-DISP to the entry field.
The Master Fields dialog box is displayed. This lists the fields in the Data Block, so you can link the appropriate data field with the entry field.
The "Master field" field now displays I-NAME, and the "Picture string" field is automatically set to X(12). This means the entry field I-NAME-DISP will be 12 characters long, alphanumeric, and will display whatever data is in the data item I-NAME.
The Pushbutton Properties dialog box appears for you to define the properties of the button.
You should now have a screenset that looks something like Figure 12-3.
Figure 12-3: Your Screenset with the Entry Fields, Text Fields and
Pushbutton
Before going on to the next section, let's save the screenset to safeguard our work so far.
So far you have defined the appearance of your window, and defined data items to hold data received from (or for display on) the fields on the window. But when the user uses the window - for example, clicks the Start button - nothing will happen. You define the effect of user actions by writing dialog script, generally referred to as just dialog.
User actions, such as pressing a key or clicking a mouse button, generate events. You write procedures to be executed in response to each event.
You can attach dialog to a particular object - a control or a window - or make it global. This is called the scope of that dialog. Dialog attached to an object is called local. When an event happens on an object, Dialog System looks first for dialog attached to that object. If there is none, Dialog System looks for dialog attached to the window that the object is on. If there is none, Dialog System looks for global dialog.
We need to write dialog so that when the user clicks the Start button, DSGRUN returns to the calling program. Of course we want the data that the user has entered to be moved into the fields in the data block first, but this happens automatically because of the master field associations you defined earlier - you don't need to write dialog to do this.
As with defining data, Dialog System provides a choice of prompted mode or unprompted mode. We will use unprompted mode.
In this example we don't need to write any global dialog, but it will be useful to look at some that has been generated automatically.
The Dialog Definition window appears. You can see some dialog already present. This was automatically generated when the screenset was created, to implement the run-time behavior defaults selected in the Wizard.
The first procedure consists of the event ESC and the two functions MOVE and RETC. This specifies that on the event ESC (generated when the user presses Esc), DSGRUN will move 1 to the data item EXIT-FLAG and then return to the calling program.
Because this dialog is global, this procedure will be executed whenever Esc is pressed, regardless of what object currently has focus - unless that object, or the window it is on, has its own dialog for ESC.
The second procedure specifies the same effect for the event CLOSED-WINDOW (generated when the user closes a window).
The rest of this dialog maintains the MDI, menu bar, toolbar and status bar, and you can ignore it.
A procedure in Dialog System is called a dialog table. It consists of an event or procedure-name followed by one or more functions that will be performed if the event occurs or the procedure-name is explicitly performed from another procedure. A complete list of Dialog System events and functions can be found in the Help.
The order in which procedures appear does not matter - unlike in COBOL, control does not fall through from the end of one procedure into the next. At the end of a procedure, DSGRUN simply stops and looks for the next event (unless the last function was RETC, which returns to the calling program).
Now let's write the dialog to make the Start button work. Since this dialog applies only to this one object, we will make it local dialog, attached to this object.
The Dialog Definition window appears. Dialog System has started the dialog off for you by inserting the name of the event you're most likely to want to write dialog for on this type of object. BUTTON-SELECTED (generated when the user clicks the button) is indeed what we want.
The highlight is already positioned on the line below the event, ready for you to type.
Anything after an asterisk on a line is treated as a comment.
The line is automatically formatted. You can even type in lower case, and it will be changed automatically to upper case. Dialog System recognizes RETC as the name of a function, and positions it indented.
The dialog should now be as follows:
BUTTON-SELECTED * The Start button returns to the calling program RETC REFRESH-OBJECT GREETING-DISP
RETC makes DSGRUN return to the COBOL program. When DSGRUN is next called, it continues from where it left off. Often RETC is the last function in a procedure, and so DSGRUN, when it is reentered, finds the procedure finished and simply waits for the next event. However, in this case we want DSGRUN to do something more when it's reentered - we need GREETING-DISP updated with the updated data that the COBOL program will have put in its master field GREETING. The REFRESH-OBJECT function does this.
The syntax of functions is given in the topic Dialog Statements: Functions in the Dialog System Help.
You have now created your user interface. The Wizard and Dialog System have created the following files for you and added them to the project (you may have to expand the tree view in the project window by clicking the "+" signs to see them):
It has also added to the project the following object files, created when you build the project:
It has also created several copyfiles (extensions .cp*).
Although the filenames are shown above in lower case, some might appear in upper case in the project. Filenames are not case sensitive.
If you ever need to update the screenset, you simply double-click on Welcome.gs in the project window, and Dialog System opens. When you save the updated screenset, the copyfiles are regenerated, so you should not edit them directly.You can however edit the .cbl program that the Wizard generated.
To build the application:
NetExpress compiles the programs, and builds the executable file. Wait until the message "Rebuild Complete" appears in the Output window before continuing.
You can run the screenset within Dialog System, without the associated program. This enables you to evaluate and test its behavior, then alter it, if needed, by simply returning to the screenset definition. This is useful for prototyping your interface.
You had to build before doing this, as the toolbar/menu and status bar programs are executed during this testing.
The Dialog System window and the WIN-01 window disappear, and WIN-01 is displayed as it will appear at run time. Notice that it has a toolbar, menu bar and status bar, as you specified in the Wizard. WIN-02 is visible within it.
Figure 12-4: The Screenset as Displayed by the Run Function
The toolbar and menu bar created by the Wizard are created by generated control programs using the NetExpress Class Library. For details, and to see how to amend the Wizard-created toolbar and menu bar, see the Dialog System User Guide. When you create menus yourself on your windows, you have the additional option of using Dialog System's own integrated system for creating menus. See the chapter Windows and Objects in theDialog System User Guide for details of this.
A small dialog box also appears at the bottom right of your screen, with Debug and Abort buttons. When you use this screenset testing facility in Dialog System, the screenset is run under control of the Screenset Animator. This is a debugger for dialog, similar in concept to the COBOL debugging features in the IDE. The dialog box enables you to do the following:
The dialog box shown in Figure 12-5 appears.
Figure 12-5: RETC dialog box
When you clicked Start, the dialog you wrote for this button was executed, and as you'll remember this includes a RETC command. Whenever a RETC is executed, Screenset Animator changes to this dialog box and you must choose what to do next:
If ever you want to debug dialog when you are running a screenset within an application, there is a parameter to DSGRUN to enable the Screenset Animator. The Screenset Animator is documented in the Dialog System Help.
In the next session, Completing and Running Your Windows GUI Application, you get this application working fully. If you're planning to go onto that session right away, you can keep the project open. If you want to take a break first, you can close the project, and open it again at the start of the next session. Or you can close NetExpress entirely, with or without closing the project first.
Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Creating a Web Database Application | Completing and Running Your Windows GUI Application |