| Using Dialog | Windows GUI Application Wizard | |
The previous chapters explained how to create a data definition and the user interface of an application. This chapter describes:
This section describes:
The Data Block copyfile contains the definition of the Data Block passed from the calling program to Dialog System at run time. You must include the copyfile in your calling program. The copyfile also contains version checking information.
To generate a copyfile from your screenset:
You can configure the definition software to write the copyfile in various ways. The sort of copyfile you want depends on whether you are writing the calling program using Micro Focus COBOL or ANSI COBOL standards. See the topic Dialog System Configuration in the Help for information on how to configure copyfile options.
A dialog box appears, enabling you to select a name and path for the copyfile. By default, Dialog System uses screenset-name.cpb.
A message box is displayed, which shows the percentage of the copyfile that has been generated and saved. The message box disappears when the save is complete.
There are some options that you should consider when generating a copyfile:
Dialog System inserts a comment to this effect adjacent to the item in the copyfile, quoting the full name.
You can change this option:
To correct this, change one of the data item's name in the Data Definition window and re-generate the copyfile.
Note: You can also generate the Data Block copyfile by specifying a command line similar to the following:
dswin/g screenset-name
This will generate the copyfile and exit.
For more information on generating copyfiles, see the topics Dialog System Overview, The Call Interface and Data Definition and Validation in the Help.
This section describes the most straightforward way to call Dialog System. If you are new to Dialog System, this is all you need to know to develop simple applications.
The structure of the Dialog System call interface is very simple and consists of two blocks of information that are passed between the calling program and Dialog System:
DS-CONTROL-BLOCK
in the control block copyfile - used to carry control data between the
calling program and Dialog System.
DATA-BLOCK in the
Data Block copyfile - used to carry user data between the calling
program and Dialog System.
To use your screenset, your COBOL program must make a call to the Dialog System run-time module Dsgrun using the Dialog System Control Block and the Data Block for your screenset. The basic call to Dialog System has the following format:
CALL "DSGRUN" USING DS-CONTROL-BLOCK,
DATA-BLOCK
The run-time system searches for the screenset first in the current directory and then in the directories specified by the COBDIR environment variable.
If you generate the copyfile with Fields prefixed by screenset ID on in the Screenset configuration dialog box, the Data Block will be prefixed by your screenset name. Therefore you must include this prefix in the call to Dialog System. For example, the sample program entries.cbl in your installation DialogSystem\demo directory uses a screenset with the screenset identifier of "entry", and makes the call as follows:
CALL "DSGRUN" USING DS-CONTROL-BLOCK,
ENTRY-DATA-BLOCK
After making the initial call to Dialog System you might like to specify a routine to use if the call fails:
IF NOT DS-NO-ERROR
MOVE DS-ERROR-CODE TO DISPLAY-ERROR-NO
DISPLAY "DS ERROR NO: " DISPLAY-ERROR-NO
PERFORM PROGRAM-TERMINATE
END-IF
The actual position of the call to Dialog System in your COBOL program is not critical. It is good practice to place it in a separate routine that can be called whenever your program needs to call Dialog System.
The topic The Call Interface in the Help describes the options you can specify in the Control Block to control how your screenset executes.
For more advanced ways to use the call interface, see the chapters Advanced Topics and Multiple Screensets.
The way in which your calling program controls screenset handling should be considered in detail when you design your screenset and calling program. You should consider issues such as:
For more information on the basics of screen control using the Dialog System call interface, see the topic The Call Interface in the Help.
You can use multiple screensets by pushing and popping them from the screenset stack. By definition, this is a first in, last out operation. Pushing and popping screensets is useful to:
There are no pre-conditions for pushing a screenset onto the screenset stack, and any screenset, or occurrence of a screenset, can be pushed or popped. Pushed screensets are normally stacked in memory, but if memory is short they will be paged to disk.
To push a screenset onto the screenset stack and start a new screenset, call Dsgrun using the following:
move ds-push-set to ds-control
call "dsgrun" using ds-control-block,
data-block
ds-push-set places the value "S" in ds-control.
The existing screenset will be pushed onto the screenset stack. When you
pop a screenset off the screenset stack you can use either of the
following:
ds-quit-set, which closes the existing screenset and
pops the first screenset off the top of the screenset stack.
ds-use-set, which pops the specified screenset off the
screenset stack without closing the existing screenset. See the chapter Multiple Screensets for further information.
Dialog System enables your calling program to use multiple instances of the same screenset. This function is useful when working with data groups where each group item has the same format. Using multiple instances of the same screenset, you can have one screenset to display, compare or update the group items as required.
Using multiple instances of the same screenset requires your program to:
When multiple instances are used and a screenset is first started by an "N"
or "S" call, an instance value is allocated and placed in the
ds-screenset-instance Control Block field.
The instance value is unique to that particular screenset instance. Your application must keep track of instance values because they are not assigned in any particular order.
You can track the active instance by examining ds-event-screenset-id
and ds-event-screenset-instance-no within dssysinf.cpy,
which must be copied into your program Working-Storage Section.
For more information on dssysinf.cpy, see the chapter Using Panels V2.
To specify that you want a new instance of a screenset to be loaded, set
ds-control to ds-use-instance-set when you
call Dsgrun.
There is no support for using multiple instances of a screenset when running through the Screenset Animator, using the definition software. If, however, Dsgrun is called from the application then multiple instances are supported.
See the chapter Multiple Screensets for further information.
The Data Block copyfile contains not only the user data but also some version numbers that Dialog System checks against the screenset when it is called. To do this, the calling program must copy them into data items in the Control Block before it calls the Dialog System run-time.
The Control Block is used to carry control information and data between the calling program and Dialog System.
The Control Block consists of:
For example, the names and values of the constants that you use to control the screenset.
For example, error codes and validation fields.
Dialog System is supplied with three versions of the Control Block copyfile:
Use with ANSI-85 conformant COBOL.
Use with Micro Focus conformant COBOL (COMP-5).
Use with Micro Focus conformant COBOL (COMP-X). Use by moving 3 to DS-VERSION-NO instead of VERSION-NO.
When you write your calling program, you must copy the copyfile into the program Working-Storage Section using the statement:
COPY "DS-CNTRL.MF".
If you are using ANSI-85 conformant COBOL, you should use the copyfile ds-cntrl.ans.
The information in the data-block field, together with the Control Block, is passed backward and forward between Dialog System and the calling program whenever control is passed from one to the other.
You also need to make sure that the Control Block contains the name of the screenset and other information that controls Dialog System behavior.
Dialog System enables the user to decide the functions the program performs next, rather than the program dictating user actions. The flags set in the Data Block returned from Dialog System contain values caused by the user's action and tell the program what to do next.
The program can respond in a variety of ways including:
In a simple application, help might be handled entirely by a message box in Dialog System. An alternative way of handling help would be to write a section of code in the program to provide help whenever a Help flag was set.
By returning to Dialog System after saving or clearing the record.
You can see a COBOL program entries.cbl that uses the sample screenset (created in the chapter Tutorial - Creating a Sample Screenset) in the chapter Tutorial - Using the Sample Screenset. This program is provided with your Dialog System software as a demonstration program.
Net Express provides an integrated editing, debugging and animating environment.
When you are debugging an application, the source code of each program is displayed in a separate window. When you animate the code, each line of the source is highlighted in turn as each statement is executed, showing the effect of each statement. You can control the pace at which the program executes and can interrupt execution to examine and change data items. See the topic Debugging in the Help for more information.
After testing your program, you can change the screenset independently of the program. You can continue doing this until you have a combination of screenset and program that meets your requirements.
One of the major benefits of Dialog System is that it is very easy to try out parts of the interface long before the screenset is completed, and before any COBOL program exists. You can prototype an incomplete screenset or a small part of a screenset to give an impression of what it is like, or to try out an idea.
Prototyping is a major aid during interface development and enables many of its tasks to be conducted rapidly. It allows you to build a working model of the system quickly so you and your users can see, on a terminal, what the system looks like when it is operating. You can then make changes quickly and inexpensively.
You can test your screenset without dialog, to make sure that the desktop layout looks good and that you have set up the fields correctly.
Dialog System Screenset Animator is a utility provided with Dialog System to enable you to test and debug the screensets you create. By using the Screenset Animator, you can test the look, feel and function of a screenset even before you write the program that uses it. You can use the Screenset Animator to:
Select Debug from the File menu in the main window. The Screenset Animator window is displayed as shown in Figure 7-1.
Figure 7-1: The Screenset Animator Window
This display is explained in detail in the topic Screenset Animator in the Help.
To run the screenset from the Screenset Animator, select Run from the Execute menu.
When you test the screenset, you should check the main functions of the screenset with altered values, and with the default values.
When the screenset reaches a point where it should return to the calling program, it returns to the Screenset Animator where you can inspect the values it has placed in the Control and Data Blocks.
The Data Block shows the current values of the data passed into Dsgrun. You can alter any of the information visible at this point in the Screenset Animator to test different processing of the screenset. To alter the Data Block, you view it by selecting Examine from the Data menu, and then selecting the Data pushbutton to display your Data Block items, which can be changed via the Select pushbutton.
Again, you can change values and run the screenset again if you want, so you can simulate the action of your intended calling program.
You can change the screenset as required and re-test until you are satisfied with the interface.
See the topic Screenset Animator in the Help for further information.
A user interface is more than just a graphical display. A complete specification also describes how the user and computer interact and how the user interface software interacts with the application software.
Once you have defined the appearance of the display, you must define this run-time interaction between the user and the machine. This interaction is called dialog. Dialog consists of events and functions. When an event occurs, the functions associated with the event are executed. Events can be caused by a key on the keyboard being pressed, or a menu choice or an object being selected.
For example, a Dialog System event such as BUTTON-SELECTED occurs when a user selects a push button (with the mouse or with the keyboard). If the button selected is Enter, the function associated with it might be CREATE-WINDOW, to create a new window for the user to enter more information.
Dialog System lets you create or customize the dialog between the user and the display objects. Control dialog affects an individual control, window dialog affects all the controls in an individual window or dialog box, and global dialog affects all windows and objects. When an event occurs, Dialog System searches first in the relevant control dialog, then the relevant window dialog, then the global dialog.
For more information on dialog statements, see the chapter Using Dialog and the topic Dialog System Overview in the Help.
Save the screenset again, and try running the interface again. Enter data into the fields and choose appropriate radio buttons, list items and other objects in your interface.
After testing your screenset again, you may want to make changes to it (for example, to improve the screen layout). You can repeat any of the steps described in this process until you are satisfied with the screenset.
Now you need to write the COBOL program that will use the user interface contained in your screenset.
The Windows GUI Application Wizard can do this automatically if required. See the chapter Windows GUI Application Wizard. The chapter Sample Programs contains sample code to produce a very simple program that will read the user inputs and store or clear them as indicated by the user.
To create the finished application you must complete various subtasks.
You use the Project facility from within Net Express to build your Dialog System application. See the topic Building Applications in your Help for further details.
The topic Compiling in the Help explains what you must do next to prepare your application for production.
When testing is completed, you are ready to assemble the finished product. A finished product can be copied onto diskettes, sent to a customer and loaded onto another machine to run as an application.
Depending on the size of the application, the finished product consists of one or more of the following:
You can display Windows Help directly from your Dialog System screenset using a Dialog System extension. Dialog System Extensions is the term given to dialog functions implemented by using the CALLOUT dialog function. Dialog System extensions are supplied to enable you to perform many regular programming tasks, such as displaying Windows Help or providing a file selection facility. For more information about Dialog System extensions see the topic Dialog System Extensions in the Help.
The Helpdemo screenset uses the Dsonline Dialog System extension, which is the Dialog System extension that displays Windows Help. The section Adding Help in the chapter Tutorial - Creating a Sample Screenset discusses the Helpdemo screenset in detail.
You can find some hints and tips on how to optimize your COBOL program in the topic Performance Programming in the Help.
This section offers some additional hints for optimizing your Dialog System application. These include:
ds-no-name-info flag. The Path statement tells the operating system to search specific directories on specific drives if a program or file it needs is not in the current directory. Path defines search paths in the order the alternatives are defined.
For the development environment, your Windows system registry is used by the COBOL run-time to identify the location of your Dialog System installation and your current Net Express project.
When you complete the application and it is ready for production, you can modify the Path environment variable so the directories needed by your application are nearer to the beginning of the Path alternatives.
The chapter Using Dialog described the three hierarchical levels of dialog that Dialog System uses when searching for events and procedures:
That is, when an event occurs on a control, for example a push button, Dialog System looks to see if the event is listed in any dialog attached to the control itself. If it finds the event, it carries out the functions listed underneath.
If not, it looks for the event in the dialog attached to the window containing the control. If it does not find the event listed there, it searches in the global dialog.
You should try to:
Of course, the more dialog you have, the slower the execution speed. It is also slowed down by having more events or procedures defined at the global level. Global dialog is useful for collecting common routines, but it also means that it is searched whenever an event occurs that is not found at a lower level.
The UNSHOW-WINDOW and the DELETE-WINDOW functions are similar. They both make the specified window or dialog box invisible and set the input focus elsewhere.
The DELETE-WINDOW function deletes the window and its controls. If you want to show that window again, it must be created again, either explicitly or implicitly. (If a window is not created, the SHOW-WINDOW and SET-FOCUS functions do an implicit create.) Creating dialog boxes and windows (plus all the objects defined on them) does take a little time.
However, the UNSHOW-WINDOW function leaves the window created so it can be shown again quickly.
Therefore, if you have a window or dialog box that you want to make invisible but show it again later, use the UNSHOW-WINDOW function. However, if you are finished with the window or dialog box, such as a system logon window, use the DELETE-WINDOW function, which will free up some resources.
Some objects, such as pushbuttons or check boxes, do not need to be named unless they are referenced in dialog. By only naming those objects that are referenced in dialog, you free a small amount of storage and reduce the time Dialog System takes in searching for objects.
If you distribute your Dialog System application, consider using the Run-time Save Format option. This option enables you to save enough information to run the screenset, but not enough to retrieve and edit it.
This option addresses some security issues and also reduces the amount of disk space needed for your application. The size of a reduced screenset can be as small as one third of the original screenset size.
You also might see a slight performance increase because Dialog System does not have to load so much information.
Note: Once you save your screenset with this option set, you cannot make changes to it. Therefore, is is important to keep a copy of your screenset that you can edit.
If the ds-no-name-info flag in the Control Block is set,
Dialog System does not read the screenset heap to get values for ds-object-name
and ds-window-name on returning to your calling program. If
you are not using either of these two fields, set this flag to
true at initialization. For example:
move 1 to ds-no-name-info
This results in slightly faster exits when you return to your application from Dialog System, for example after the RETC function.
Note that setting this option will prevent you from using Screenset Animator to debug your screensets, as Screenset Animator needs the name information stored in the screenset.
For information on more sophisticated ways of using the call interface, such as the use of multiple screensets, and multiple instances of the same screenset, see the chapter Multiple Screensets.
If you are migrating applications to Net Express from non Win32 environments, see the chapter Migrating to Different Platforms for help with cross-environment issues.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Using Dialog | Windows GUI Application Wizard | |