Figure 11-1: Trap Screen
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:
To run the screenset, you can use any of the following methods:
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.
The trap screen, shown in Figure 11-1, displays the set of information that would normally pass between a calling program and the run-time system.
Figure 11-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.
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:
|
|||||||||||||||||
| 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:
|
|||||||||||||||||
| 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:
You can specify the following values with these bit settings:
|
|||||||||||||||||
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):
|
|||||
| 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:
|
|||||
| Field Count | The total number of fields defined for the specified screenset, that is, contained in the Data Block (05 DS-FIELD-COUNT). | |||||
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. |
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.
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.
05 DS-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).
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).
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 throught 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.
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 11-2 is displayed. For more information about dialog, see the chapter Dialog.
Figure 11-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 of 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.
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.
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.
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.
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 do wn line by line to the desired position.
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.
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 (Windows only). The trap is then be 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:
Windows:
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:
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.
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.
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.
Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.