Chapter 16: Questions and Answers

This chapter lists and answers questions that are frequently raised with the MERANT Technical Support.

Note: Some of the questions relate to all environments. Some are specific to particular environments. The notation in the left margin indiactes which environment is affected.

The Checker rejects my Data Block that I generated directly from my screenset. What is going wrong?

If you have written your program so that it expects to have all data items in the Data Block prefixed with the screenset ID, you must generate the screenset that way.

For example, the Customer program has the CUSTOMER prefix on all the data items in the Data Block. If you generate the Data Block and do not specify you want the Data Block prefixed with the screenset ID, the data items are not prefixed by CUSTOMER and the checker rejects any reference to the items.

How can I use the Screenset Animator facilities from my program without recompiling?

You have two options:

Make the name of the Dialog System run-time system a variable. For example, the Customer demo can be changed to use the following level-01 data item:
```
    01 dialog-system    pic x(8) value "dsgrun".
```
Then, while debugging your application, you can change the value of dialog-system to "ds". ds is the Dialog System run-time system that enables you to use the Screenset Animator.

Once you have done this, all future calls to the Dialog System run-time will use Screenset Animator (even if you change the value of dialog-system back to dsgrun).
Use the "T" and "O" options in ds-control. Setting ds-control to "T" turns the Screenset Animator on. Setting ds-control to "O" turns the Screenset Animator off.
To turn Screenset Animator on:
1. Set a breakpoint on the Dialog System CALL statement.
2. Change the value of the data item ds-control to "T".
3. Step on the call to Dsgrun.
  The "T" option causes Dialog System to issue an internal call to turn the Screenset Animator facility on and exit.
4. Reset your cursor on the Dialog System CALL statement.
5. Zoom your program again. Screenset Animator will appear the next time a line of dialog is executed.
To turn Screenset Animator off:
1. Change the value of the data item ds-control to "O".
2. Step on the call to Dsgrun.
  Screenset Animator will disappear. As with the "T" option, the "O" option causes Dialog System to issue an internal call to turn the Screenset Animator facility off and then exit.
3. Reset your cursor on the Dialog System CALL statement.
4. Zoom your program. Screenset Animator is turned off.

Why is a dialog box not displayed when I use a SHOW-WINDOW function?

This happens if the dialog box is a modal dialog box, because SHOW-WINDOW does not paint this type of dialog box on the screen. A modal dialog box is shown only when the focus is set on it using the SET-FOCUS function. SHOW-WINDOW does paint a window or a modeless dialog box on the screen.

How do I validate fields as soon as they lose focus?

The most common problem with implementations of field-by-field validation is that the application usually ends up in an infinite loop of validation errors. For example, if an entry field loses focus and is validated and the validation fails, focus is returned to the object. However, this causes another control to lose focus, and if that control is also validated, an infinite loop can result.

Another problem is that you might sometimes not want to validate a field. For example, if a user clicks Cancel or Help in a dialog box, or switches to a different application.

Here is one way to implement field-by-field validation which avoids the infinite looping problems, and allows you to implement Cancel and Help buttons:

Define a flag in your data block:
```
VALIDATION-ERROR-FOUND      C5    1.0
VALIDATION-ERROR-FIELD      C5    2.0
VALIDATION-ERROR-MESSAGE    C5   80.0
```
If you already have an error message field defined in your screenset, you can use that field instead of defining VALIDATION-ERROR-MESSAGE. Otherwise define the VALIDATION-ERROR-MESSAGE field as the error field.
Add the following global dialog:
```
REPORT-VALIDATION-ERROR 
* Report a validation error
     INVOKE-MESSAGE-BOX VALIDATION-ERROR-MBOX VALIDATION-ERROR-MESSAGE $REGISTER
     SET-FOCUS VALIDATION-ERROR-FIELD
     TIMEOUT 1 CLEAR-VALIDATION-ERROR-TIMEOUT
   CLEAR-VALIDATION-ERROR-TIMEOUT
* Reset the validation error flag and TIMEOUT
     MOVE 0 VALIDATION-ERROR-FOUND
     TIMEOUT 0 $NULL
   DO-NOTHING
* Do-nothing procedure. Contains no functions.
```
The REPORT-VALIDATION-ERROR procedure is executed after a short timeout. It reports a validation error that has been detected, then sets focus on the field that is in error. Another timeout is then set to execute the CLEAR-VALIDATION-ERROR-TIMEOUT once all the focus events have been processed. This event clears the flags associated with the validation failure.
Add the following to SCREENSET-INITIALIZED dialog:
```
MOVE 0 VALIDATION-ERROR-FOUND
```
This clears the VALIDATION-ERROR-FOUND flag ready for the first validation error.
Add the following line of dialog as the first line of LOST-FOCUS dialog for any objects which have LOST-FOCUS dialog and which could cause a focus change:
```
IF= VALIDATION-ERROR-FOUND 1 DO-NOTHING
```
In all places where you have dialog which causes a focus change due to a validation error, add the following dialog immediately before the dialog that causes the focus change:
```
MOVE $EVENT-DATA VALIDATION-ERROR-FIELD
     MOVE 1 VALIDATION-ERROR-FOUND
     TIMEOUT 1 REPORT-VALIDATION-ERROR
```
This dialog example assumes that $EVENT-DATA is set to the object ID of the object that failed validation. $EVENT-DATA is set to the object ID when a VAL-ERROR occurs.
If you want to cancel a validation error before it is reported, add the following dialog where you want the error to be canceled:
```
EXECUTE-PROCEDURE CLEAR-VALIDATION-ERROR-TIMEOUT
```
If you want to cancel a validation error on a push button, you need to cancel the error on a GAINED-FOCUS event on the button, not the BUTTON-SELECTED event. A timeout can happen between the GAINED-FOCUS and BUTTON-SELECTED events, which would trigger the validation error message.

It is also particularly important that you cancel any validation error when your application loses focus. Otherwise you will prevent users from switching to a different application and you will also interfere with the operation of Screenset Animator and the Net Express IDE. To cancel any validation error when your application loses focus, implement LOST-FOCUS dialog on the window. Note that this also applies when switching focus to other windows in your application.

When a validation error causes the focus to be changed, this sets both the VALIDATION-ERROR-FOUND flag and a very short TIMEOUT to clear the flag again. Since TIMEOUT events do not happen if there are any events still to be processed, the TIMEOUT event is guaranteed to happen after the LOST-FOCUS event. If the LOST-FOCUS event finds the VALIDATION-ERROR-FOUND flag set, then it doesn't validate the field that lost focus (and so doesn't cause a focus change).

How can I get more information about a Dialog System run-time error?

When an error occurs in your application, the Dialog System run-time returns an error code (DS-ERROR-CODE), and two additional error details (DS-ERROR-DETAILS-1 and DS-ERROR-DETAILS-2), which allow you to determine what went wrong with your application.

However, particularly with error code 17, you need to look up information in several different tables in order to get all the information available about the error. Also, some of the other error codes use the error details to return more information about the error, but you have to refer to the documentation in order to decode these.

Dialog System contains an error reporting module, dsexcept.dll, which can decode the error codes for you, and can also provide additional information that is not available from the error codes alone.

In order for dsexcept.dll to be active, you need to make sure that it is in a directory pointed to by the $COBDIR environment variable. The dsexcept.dll file can be found in your Dialog System \bin directory.

Notes:

dsexcept.dll does not provide as much information for run-time format screensets.
This is to prevent users of your production applications attempting to debug or reverse-engineer your screensets.
Screenset Animator disables the dsexcept.dll module.

How much memory will my screenset take up at run time?

It is impossible to determine exactly how much memory a screenset will take up at run time. It depends on several factors, including the amount of free memory you have available. However, in general the amount memory used by a screenset is not particularly large.

All screensets are held in virtual files that are paged out to disk as memory demands increase. The only memory that each screenset is guaranteed to take up is 512 bytes required by the COBOL run-time system (RTS) to manage the virtual files.

Each virtual file opened will require the 512 bytes (unless it is more than 64K bytes in which case it will require an extra 512 bytes). This means that if Dialog System uses one virtual file for each screenset then the minimum would be 512 bytes for each screenset.

If there is sufficient memory, the RTS will hold as many of the virtual files in memory as it can. When there is insufficient memory, the RTS starts to page the virtual files to disk.

Hence the memory taken up by the screenset is variable, but should never be excessive.

For more information, see the topic Dialog System Limits in the Help.

How do I add color to a text field?

The Dialog System Text object is simply text painted on your window and for this reason is not configurable. It is possible, however, to achieve the effect you require through the use of an Entry Field object. Select the Display-only property of this field, and define its initial text (or master field value) to achieve the same results, but with the colors configurable via the normal means.

How do I make screensets containing list-boxes display more quickly?

If your list-box is tied to a master field group, it is possible to reduce load time by temporarily adjusting the internally recognized size of that group using the SET-DATA-GROUP-SIZE function. This tells Dialog System that internally it should recognize only (n) items in that group array - preventing data in occurrences beyond that figure being inserted into objects. However, the calling program can access all the data items in the group, and you may use the same function to reset the internal size when appropriate.

Why does my application appear to enter a controlled loop when using multiple screensets?

You might experience this when using DS-PUSH-SET and DS-USE-SET combinations in router-based applications. Specifically, the effect is usually attributed to coded dialog script, which forces the application into an event-based loop.

When using multiple screensets in this manner, you use the following dialog to re-activate a previous screenset:

OTHER-SCREENSET
	MOVE 1 OTHER-SET-EVENT-FLAG
	REPEAT-EVENT
	RETC

Your COBOL program then makes a decision based on the DS-EVENT-SCREENSET-ID to reload the screenset on which the event occurred.

The error described is usually caused by setting a value in DS-PROCEDURE, which causes execution of that dialog table in the reloaded screenset. The executed procedure then carries out its own functions, often causing more events in the original screenset, and results in the effect being experienced.

The reason for this effect is explained in the chapter Multiple Screensets, in the section The Sequence of Events.

DS-PROCEDURE should not be set when re-loading a screenset in response to an OTHER-SCREENSET event.

Why, when my selection box has the auto-insert property set to off, can list items become duplicated in the dropdown list?

This is primarily caused by inappropiate use of this control.

Appropriate use of a selection box control is for the selection of an item from a pre-defined list. If required, the user-selected item can be placed in an associated Master field, to be used by the application as appropriate.

The important factor here is that the dialog functions which populate a selection box insert the list items, delimited by the hexadecimal value "0A". You cannot insert items into a selection box from a Master field group.

Duplication occurs when the text in the associated Master field contains a value other than that inserted into the list (that is, is SPACE delimited) and is not delimited by X"0A". Duplication appears to occur but the items are not delimited in the same way.

Incorrect population of the associated Master field, and the REFRESH-OBJECT function are prime mechanisms causing this undesired behavior.

How do I control the tabbing order of controls?

Select the Edit, Controls menu option and re-order the displayed list as required. See the topic Controls in the Help.

Compiling 256-color bitmap resources into a .dll will not work.

256-color bitmaps must be specified as separate files to be included in a Dialog System application, and the MFDSSW /B(n) environment variable must be set. This environment variable determines palette behavior and must be set to enable 256-color support.

Advanced Topics

Sample Programs