Dialog

Generating the Copyfile

Chapter 10: Running the Screenset

The fifth step in developing your Dialog System application is to run your screenset. Dialog System can simulate most of the behavior of the screenset that occurs when you actually produce and run the application program. This means that you can run a screenset before you write or use a program. You can evaluate and test the behavior of the screenset, then modify it if you need to. This is useful to prototype your user interface.

When you have run your screenset, the sixth step in developing your Dialog System application is to modify the screenset by returning to the appropriate step in defining the screenset, described in the earlier chapters in this book. Repeat these two steps until you have the screenset you want.

This chapter explains:

How to run a screenset without a program
How to preview the execution of a line of dialog
How you can use a mouse when you run a screenset

10.1 How to Run the Screenset

To run the screenset, you can use any of the following methods:

Select F6=run from the Main menu.
Invoke the definition software with the /t option.
Invoke the definition software with the /r option.

If you use either of the first two methods, the trap screen is displayed. If you use the third method, you can run the screenset without displaying the trap screen first.

10.1.1 The Trap Screen

The trap screen, shown in Figure 10-1, displays the set of information that would normally pass between a calling program and the run-time system.

Figure 10-1: Trap Screen

The information displayed at the top of the trap screen reflects the information contained in the control block. The left-hand side displays input fields, and the right-hand side displays output fields. The lower part of the trap screen displays the data fields contained in the Data Block described in the chapter Generating the Copyfile. You can alter some of this information, but some is for display purposes only. You can alter displayed data values so that you can test the screenset with values that you choose. The following sections describe the trap screen fields and their relation to the control and data blocks used in the call interface. See the section Trap Screen Menu later in this chapter for information about using the trap screen.

10.1.1.1 Trap Input Fields

The trap input fields contain the parameter values sent to the Dialog System control block. They are displayed on the trap screen so that you can view and change the control block fields passing across the program interface. Where appropriate, the following descriptions include the control block name and level number for these values in parentheses.

Control	A single-character field in which you can enter values indicating the procedure to execute when you press Enter (05 DS-CONTROL). Possible values are:
	N	Start to run a new screenset (78 DS-NEW-SET). This runs the screenset specified in the Screenset Name field, starting with the panel defined as the first panel in the screenset. Control remains inside the screenset and returns to the trap again only when a dialog function such as RETC or an EXIT field is encountered.
	C	Continue to run a screenset (78 DS-CONTINUE). This runs the screenset from the point where control returned to the trap until the next exit from the run-time system. When control returns to the trap from a running screenset, the run-time system automatically sets the control value to "C".
	P	Run a new screenset, but display the data items of the screenset first (predisplay). At this point, the screenset has not been started, and you can amend any of the data values if you wish. When you press Enter, the control parameter is automatically set back to "C" (78 DS-CONTINUE) and the screenset runs using the values set into the data items. If the procedure P000 exists, it is executed.
	D	Enter the definition process. This terminates the run and returns to the screenset definition process. To run the screenset with the trap again, select F6=Run from the main menu.
	L	Load run-time software (78 DS-LOAD-SYSTEM). This preloads the run-time software. You do not have to use this call, but you can use it as part of a normal program initialization routine if required.
Screenset Name	The name of the screenset you wish to run (05 DS-SET-NAME).
Clear Dialog	A field you can use to stop any outstanding dialog from being executed (05 DS-CLEAR-DIALOG). You can enter the following values:
	1	Clear outstanding current dialog entries before continuing. This runs the screenset from the point where it stopped; however, any outstanding entries in the current dialog line are cleared. The screenset then awaits further input.
	0	Continue running the screenset normally. This is the default.
Procedure	The procedure that is invoked before the screenset continues to run with the outstanding dialog (05 DS-PROC-NO). This normally has the value "000", which is the initialization procedure, but you cannot perform this procedure from the trap. You can change this to the number of the procedure you wish to use (see the chapter Dialog for information about defining procedures). The procedure you specify is executed when the screenset continues to run, and, as long as the clear dialog field is not set to "1", the rest of the current dialog is executed. Remember that local dialog is searched before global dialog unless you have changed the Global/Local Dialog First flag (see the chapter Using Dialog System for details about this flag). Be careful to use the clear dialog flag correctly when you run procedures from the trap or program. If you do not set the clear dialog to "1", the procedure is executed and any outstanding procedures are added to the procedure stack. There is a limit of 16 stacked procedures; if this limit is exceeded, an error is returned.
Control Param	A two-byte field whose bit settings determine whether to apply version number checking, whether to clear the current screen before starting the new screenset, or whether to activate Ctrl+Break (DOS)/INTERRUPT (UNIX) detection. This parameter is used with the dialog functions to CALL a new screenset or PUSH a screenset, so it is only applicable when the control variable is set to "N". The bit settings are as follows:
	bit 0	Do not clear the screen before a new screenset starts (78 DS-CONTROL-PARAM-DEFAULT). This is the default.
	bit 1	Do not check the Data Block version number for compatibility with the version of the Data Block in the screenset (78 DS-IGNORE-DB-VER-NO).
	bit 2	Cause Ctrl+Break (DOS)/INTERRUPT (UNIX) to return an error code to the user program (78 DS-CHECK-CTRL-BREAK).
	You can specify the following values with these bit settings:
	0	Clear the screen before the new screenset starts and check the version number.
	1	Do not clear the screen before the new screenset starts, but do check the version number.
	2	Clear the screen before the new screenset starts, but do not check the version number. You must be careful if you use this setting.
	3	Do not clear the screen before the new screenset starts, and do not check the version number. You must be careful if you use this setting.
	4	Clear the screen before the new screenset starts, check the version number, and detect Ctrl+Break/INTR.

10.1.1.2 Trap Output Fields

The trap output fields contain the values returned from the Dialog System control block. These values provide the application program with information about what happened while control was in your screenset. They are displayed on the trap screen so that you can view the control block fields passing across the program interface. These values are output only; the run-time system ignores any changes you make to them.

Panel Name	The name of the panel that is currently active in the running screenset (05 DS-PANEL-NAME).
Error Code	The code for any run-time error message that Dialog System returns (05 DS-SYSTEM-ERROR-NO). If the code displayed is zero, no error was detected. See the chapter Error Messages for descriptions of the Dialog System run-time error messages.
Validation Code	The code that you defined for field validation errors (05 DS-VALIDATION-ERROR-NO). If the code displayed is zero, either no error was detected or you have not defined any error code (see the chapter Data Definition for details on defining validation errors).
Exit Field	A field that identifies whether return to the trap is forced by a Return to Calling (RETC) program function or caused by an exit field (see the chapter Panel Fields for details on defining exit fields), according to the following values (05 DS-EXIT-FIELD):
	0	Return forced by a RETC function.
	1	Return caused by an exit field.
Data Block Versn	The version number of the current Data Block (05 DS-DATA-BLOCK-VERSION-NO). This number is contained inside the screenset. You can view the version number by pressing F7=Set Details from the Main Alt menu. The version number is significant when you run the screenset with a program, because the generated Data Block must match the Data Block definition in the screenset.
Field Number	The number of the input field on which the cursor is currently positioned (05 DS-FIELD-NO). Fields are numbered sequentially according to their order in data definition.
Occurrence	The occurrence number of the field on which the cursor is currently positioned (05 DS-FIELD-OCCURRENCE). This value applies only if the field is in a group; for a non-repeating field, the value is zero.
Field Change	This field identifies whether or not the current input field was changed during the last input (05 DS-FIELD-CHANGE). The field can take the following values:
	0	Not changed during last input.
	1	Changed during last input.
Field Count	The total number of fields defined for the specified screenset, that is, contained in the Data Block (05 DS-FIELD-COUNT).

10.1.1.3 Trap Data Fields

The trap data fields are the fields displayed in the list in the lower portion of the trap screen. You can amend these fields. The fields display the following information contained in the Data Block:

Data Item	Lists the names of all the data fields in the current panel.
Data Values	Lists the current values of the listed data fields. You can alter the values displayed here.

10.1.1.4 Control Blocks

If you are a COBOL programmer, it might be useful to see where these trap screen input and output fields appear in the control block used in the call interface. Two separate control blocks are provided with the Dialog System software: ds-cntrl.mf (Micro Focus constants) and ds-cntrl.ans (ANSI constants). You can use only one of these control blocks in your COBOL program.

10.1.1.4.1 Micro Focus Constants

ds-cntrl.mf (Micro Focus constants) contains the following information:

 01  DS-CONTROL-BLOCK.
    03 DS-VERSION-NUMBERS.
       05 DS-DATA-BLOCK-VERSION-NO  PIC 9(4).
       05 DS-VERSION-NO             PIC 9.
    03 DS-INPUT-FIELDS.
       05 DS-CONTROL                PIC X.
         78 DS-CONTINUE               VALUE "C".
         78 DS-NEW-SET                VALUE "N".
         78 DS-LOAD-SYSTEM            VALUE "L".
         78 DS-QUIT-SET               VALUE "Q".
         78 DS-PUSH-SET               VALUE "S".
         78 DS-PATHNAME               VALUE "P".
         78 DS-ERR-FILE-OPEN          VALUE "E".
         78  DS-MULTI-POP             VALUE "M"
.        78  DS-TRACE-OFF             VALUE "O"
.        78  DS-TRACE-ON              VALUE "T"
.        78  DS-USE-SET               VALUE "U"
.        78  DS-WHAT-SET              VALUE "W"
.       05 DS-CONTROL-PARAM         PIC 9(4) COMP.
         78 DS-CONTROL-PARAM-DEFAULT  VALUE 0.
         78 DS-SCREEN-NOCLEAR         VALUE 1.
         78 DS-IGNORE-DB-VER-NO       VALUE 2.
         78 DS-CHECK-CTRL-BREAK       VALUE 4.
       05 DS-SET-NAME               PIC X(16).
       05 DS-CLEAR-DIALOG           PIC 9.
       05 DS-PROC-TYPE              PIC X.
       05 DS-PROC-NO                PIC 9(4) COMP.
       05 DS-INPUT-RESERVED         PIC X(12).
    03 DS-OUTPUT-FIELDS.
       05 DS-SYSTEM-ERROR-NO        PIC 9(4) COMP.
         88 DS-NO-ERROR               VALUE 0.
         88 DS-NOT-INITIALIZED        VALUE 1.
         88 DS-CANNOT-OPEN-SET        VALUE 2.
         88 DS-ERROR-READING-FILE     VALUE 3.
         88 DS-INVALID-SET            VALUE 4.
         88 DS-CANNOT-CREATE-PANEL    VALUE 5.
         88 DS-DYNAMIC-ERROR          VALUE 6.
         88 DS-INVALID-FUNCTION       VALUE 7.
         88 DS-INVALID-PROC           VALUE 8.
         88 DS-VALIDATION-PROG-ERROR  VALUE 9.
         88 DS-DATA-BLOCK-VERNO-ERROR VALUE 10.
         88 DS-PUSH-LIMIT-REACHED     VALUE 11.
         88 DS-ERROR-FILE-MISSING     VALUE 12.
         88 DS-SUBSCRIPT-ERROR        VALUE 13.
         88 DS-PROC-LIMIT-REACHED     VALUE 14.
         88 DS-CTRL-BREAK-PRESSED     VALUE 15.
         88 DS-ERROR-ON-TRACE-FILE    VALUE 16.
       05 DS-VALIDATION-ERROR-NO    PIC 9(4) COMP.
       05 DS-PANEL-NAME             PIC X(8).
       05 DS-RESERVED-1             PIC X(2).
       05 DS-FIELD-COUNT            PIC 9(4) COMP.
       05 DS-FIELD-OCCURRENCE       PIC 9(4) COMP.
       05DS-MOUSE-DETAILS.             PIC X(6).
        07 DS-OUTPUT-MOUSE-X     PIC 9(2) COMP.
        07 DS-OUTPUT-MOUSE-Y     PIC 9(2) COMP.
        07 DS-OUTPUT-MOUSE-FLD     PIC 9(2) COMP.
        07 DS-OUTPUT-MOUSE-OCCURRENCE     PIC 9(4) COMP.
       05 DS-FIELD-NO               PIC 9(4) COMP.
       05 DS-FIELD-CHANGE           PIC 9.
         88 DS-FIELD-CHANGE-TRUE      VALUE 1.
       05 DS-EXIT-FIELD             PIC 9.
         88 DS-EXIT-FIELD-TRUE        VALUE 1.
       05 DS-OUTPUT-RESERVED        PIC X(16).

10.1.1.4.2 ANSI Constants

ds-cntrl.ans (ANSI constants) contains the following information:

 01 DS-CONTROL-BLOCK.
    03 DS-VERSION-NUMBERS.
       05 DS-DATA-BLOCK-VERSION-NO  PIC 9(4).
       05 DS-VERSION-NO             PIC 9.
    03 DS-INPUT-FIELDS.
       05 DS-CONTROL                PIC X.
       05 DS-CONTROL-PARAM          PIC 9(4) COMP.
       05 DS-SET-NAME               PIC X(16).
       05 DS-CLEAR-DIALOG           PIC 9.
       05 DS-PROC-TYPE              PIC X.
       05 DS-PROC-NO                PIC 9(4) COMP.
       05 DS-INPUT-RESERVED         PIC X(12).
    03 DS-OUTPUT-FIELDS.
       05 DS-SYSTEM-ERROR-NO        PIC 9(4) COMP.
         88 DS-NO-ERROR               VALUE 0.
         88 DS-NOT-INITIALIZED        VALUE 1.
         88 DS-CANNOT-OPEN-SET        VALUE 2.
         88 DS-ERROR-READING-FILE     VALUE 3.
         88 DS-INVALID-SET            VALUE 4.
         88 DS-CANNOT-CREATE-PANEL    VALUE 5.
         88 DS-DYNAMIC-ERROR          VALUE 6.
         88 DS-INVALID-FUNCTION       VALUE 7.
         88 DS-INVALID-PROC           VALUE 8.
         88 DS-VALIDATION-PROG-ERROR  VALUE 9.
         88 DS-DATA-BLOCK-VERNO-ERROR VALUE 10.
         88 DS-PUSH-LIMIT-REACHED     VALUE 11.
         88 DS-ERROR-FILE-MISSING     VALUE 12.
         88 DS-SUBSCRIPT-ERROR        VALUE 13.
         88 DS-PROC-LIMIT-REACHED     VALUE 14.
         88 DS-CTRL-BREAK-PRESSED     VALUE 15.
         88 DS-ERROR-ON-TRACE-FILE    VALUE 16.
       05 DS-VALIDATION-ERROR-NO    PIC 9(4) COMP.
       05 DS-PANEL-NAME             PIC X(8).
       05 DS-RESERVED-1             PIC X(2).
       05 DS-FIELD-COUNT            PIC 9(4) COMP.
       05 DS-FIELD-OCCURRENCE       PIC 9(4) COMP.
       05 DS-RESERVED-2             PIC X(6).
       05 DS-FIELD-NO               PIC 9(4) COMP.


       05 DS-FIELD-CHANGE           PIC 9.
         88 DS-FIELD-CHANGE-TRUE      VALUE 1.
       05 DS-EXIT-FIELD             PIC 9.
         88 DS-EXIT-FIELD-TRUE        VALUE 1.
       05 DS-OUTPUT-RESERVED        PIC X(16).
 01 DS-CONSTANTS.
    03 DS-CONTROL-CONSTANTS.
       05 DS-CONTINUE             PIC X VALUE "C".
       05 DS-NEW-SET              PIC X VALUE "N".
       05 DS-LOAD-SYSTEM          PIC X VALUE "L".
       05 DS-QUIT-SET             PIC X VALUE "Q".
       05 DS-PUSH-SET             PIC X VALUE "S".
       05 DS-PATHNAME             PIC X VALUE "P".
       05 DS-ERR-FILE-OPEN        PIC X VALUE "E".
    03 DS-CONTROL-PARAM-CONSTANTS.
       05 DS-CONTROL-PARAM-DEFAULT  PIC 9(4) COMP VALUE 0.
       05 DS-SCREEN-NOCLEAR       PIC 9(4) COMP VALUE 1.
       05 DS-IGNORE-DB-VER-NO     PIC 9(4) COMP VALUE 2.
       05 DS-CHECK-CTRL-BREAK     PIC 9(4) COMP VALUE 4.

These control blocks contain a number of reserved fields that you must not use. Also, there are some control constants in the control block that are not described in this chapter. These provide advanced programming facilities, which you should not use until you are thoroughly familiar with Dialog System (see the chapter Programming for details of these advanced features).

10.2 Trap Screen Menu

The previous section described the information that is passed between the control block and the COBOL program when a program is run. The following sections describe the menu facilities provided with the trap screen. To use these facilities, you set the options you want, then press Enter to start to run your screenset.

To run a screenset from a previous release of Dialog System through the Trap, you must ensure that the screenset is resaved with the current version number, or there will be an error. You must either run the screenset in a development environment, where the screenset is loaded and automatically resaved with the correct version number before it enters the Trap, or you must run the screenset through the development system to load and save it before you invoke it using a call from an application to Ds.

If you try to run a screenset from a previous release of Dialog System by using a call from an application to Ds (rather than Dsrun), the screenset will load, but it is not resaved, and an error occurs because the version number is wrong.

10.2.1 Trace On/Off (F2)

Pressing F2=trace on/off from the Trap Screen menu toggles the trace facility on and off. The default is trace off.

You can use the trace facility to view the execution of any local or global dialog defined for the panel when the screenset runs. When a keystroke that you defined in your dialog is pressed, the trace screen shown in Figure 10-2 is displayed. For more information about dialog, see the chapter Dialog.

Figure 10-2: Trace Panel

The display fields in the trace panel contain the following information:

Trace	Lists the current dialog line, that is, the specified function and associated parameters. If the current function is a procedure, this field lists the contents of the procedure; if the procedure contains more functions than the screen can display, the list scrolls horizontally as each function begins to execute.
Panel	The name of the panel currently running.
Register	The value contained in the internal register (see the chapter Dialog for details on the internal register).

To use this trace facility from a COBOL program without running the trap, you can use an additional function call to Dsrun. To make this call, enter a value of "T" in the Ds-Control field of the control block. To turn the trace off, enter a value of "O" in the Ds-Control field. When you no longer require use of the trace field, you must remember to place a value of "C" back in Ds-Control.

10.2.1.1 Start/Close File (F2)

Pressing F2=start-file from the Trace menu starts to write trace information to a text output file named screenset-name.trc. The F2 key becomes F2=close-file. To stop writing trace information to the text output file, press F2 again. You can use this function to control what is written to the file by starting and stopping the file writes when you require. You can then examine the file in an editor and look at the path taken through the dialog.

Dialog can be written to the file either in step or zoom mode, described in the next sections. The output file is always extended, so you must erase it from the current directory as necessary.

10.2.1.2 Step (S)

Pressing S=step from the Trace menu executes the dialog displayed in the trace screen one function at a time, performing the current function and then halting. When a function has been completed, press S again to execute the next dialog function.

10.2.1.3 Zoom (Z)

Pressing Z=zoom from the Trace menu executes the entire dialog line, displaying the user screen instead of the individual steps. When you use this facility, the trace screen is disabled until the next return to the trap, where you can turn the trace on again.

10.2.1.4 Move Panel (Home, End, <up-arrow> or<down-arrow>)

This facility on the Trace menu enables you to reposition the trace screen so that you can have an unobstructed view of your user screen. Use the Home key to move the trace screen to the top of the screen, the End key to move it to the bottom of the screen and the <up-arrow> and <down-arrow> keys to move the screen up or down line by line to the desired position.

10.2.1.5 View Parameters (<right-arrow>|, |<left-arrow>)

This facility on the Trace menu enables you to view the parameters defined for the current dialog function without actually executing the function. Press <right-arrow>| to look at the next parameter or |<left-arrow> to look at the previous one.

10.2.2 Trap On/Off (F3)

Pressing F3=trap-on/off from the Trap Screen menu toggles the trap facility on and off. The default is trap on.

When you run the screenset with the trap on, all exits from the run-time system return to the trap screen. Control does not return to the trap if Dialog System is waiting for input; it only returns when dialog functions are being executed. Therefore, to force a return to the trap, you might have to press a key that has dialog associated with it.

When you run the screenset with the trap off, the return to the trap is disabled, even when an RETC function is invoked. To return to the trap screen before the execution of a function that would naturally return to the trap, you must press Ctrl+Break while the screenset is running (DOS only). The trap is then switched on, and you can press Enter to continue running the screenset.

It is also possible to make the call to the Dialog System Run-time System go via the trap. This can be useful when you debug your application program. To do this, change the CALL statement in your COBOL program from:

call "DSRUN" using DS-CONTROL-BLOCK, screenset-DATA-BLOCK.

to:

DOS and OS/2: 
call "DSC" using DS-CONTROL-BLOCK, screenset-DATA-BLOCK.

UNIX: 
call "DSC.gnt" using DS-CONTROL-BLOCK, screenset-DATA-BLOCK.

where screenset is the name of your screenset.

See the chapter Programming for more details of calling Dialog System.

This call displays the trap. However, remember the following points when you call the trap this way:

In DOS environments, the file ds.gnt is in the library ds.lbr, so you must ensure that the file ds.lbr is in your current directory before the call is made. This restriction does not apply to UNIX.
You cannot change the screenset name or the control value in the trap.
The trap defaults to trace mode. However, you can turn the trace off from the trap screen if required.

10.2.3 Initialize Data Fields (F4)

Pressing F4=initialize-data-fields from the Trap Screen menu initializes all numeric fields in the Data Block to zero and all other fields to spaces. You can view this in the trap data field display in the lower part of the trap screen.

10.2.4 Page Data Fields (PgUp, PgDn)

Pressing PgUp and PgDn keys from the Trap Screen menu enables you to page up and down the data field values displayed on the trap screen as required. You cannot change these fields from the trap.

10.2.5 Escape (Esc)

Pressing Escape from the Trap Screen menu returns you to the point of entry to the trap. If you started the trap by selecting F6=run from the main menu, you return to the main menu. If you invoked the trap from the command line using the /t option, you return to the operating system.

The trap enables you to evaluate and change the run-time behavior of the screenset without needing to produce a program. You can use the information you viewed using the trap to write a COBOL application program. You need an application program to control any changes in data values as a result of actions such as file access and calculations. A sample COBOL program called customer.cbl is provided with the Dialog System software.

Dialog

Generating the Copyfile