PreviousUsing Dialog Windows GUI Application WizardNext

Chapter 7: Using the Screenset

The previous chapters explained how to create a data definition and the user interface of an application. This chapter describes:

7.1 The Call Interface

This section describes:

  1. Generating the COBOL copyfile from a screenset.

  2. The call interface - its structure and how to use it.

  3. Writing the COBOL application program.

  4. Debugging and animating the screenset and your COBOL program.

  5. Packaging your application.

7.1.1 Generating the Data Block Copyfile

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: Generating Copyfile Options

There are some options that you should consider when generating a 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.

7.1.2 The Structure of the Call Interface

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:

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:


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:


After making the initial call to Dialog System you might like to specify a routine to use if the call fails:


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. Controlling the Use of 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. Using Multiple Screensets

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,

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:

See the chapter Multiple Screensets for further information. Using Multiple Instances of the Same Screenset

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.

7.1.3 Writing the COBOL Application Program

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

The Control Block is used to carry control information and data between the calling program and Dialog System.

The Control Block consists of:

Dialog System is supplied with three versions of the Control Block copyfile:

When you write your calling program, you must copy the copyfile into the program Working-Storage Section using the statement:


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:

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.

7.1.4 Debugging and Animating the Screenset and Your COBOL Program

NetExpress 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. Testing the Screenset

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. Using the Screenset Animator

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.

Screenset animator
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. Defining Dialog

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. Testing the Screenset Again

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. Changing the Screenset

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.

7.1.5 Packaging Your Application

To create the finished application you must complete various subtasks.

You use the Project facility from within NetExpress 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:

7.2 Adding Help

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.

7.3 Optimizing the Application

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:

7.3.1 Limiting the Directory Search

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

7.3.2 Searching for Event Dialog

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.

7.3.4 Minimize Naming of Objects

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.

7.3.5 Run-time Save Format

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.

7.3.6 Using ds-no-name-info

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.

7.4 Further Information

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 NetExpress from non Win32 environments, see the chapter Migrating to Different Platforms for help with cross-environment issues.

Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousUsing Dialog Windows GUI Application WizardNext