| Error Messages | Dialog System Limits | |
This chapter contains a set of tutorials, each of which addresses a particular component or function of Dialog System. The tutorials illustrate many of the features of Dialog System, and were, of course, produced by Dialog System.
Before you start these tutorials, you might find it useful to select F8=tutorial from the top menu. This gives you an on-line overview of the facilities offered by Dialog System. You can step through the tutorial by pressing Enter. (Escape exits the tutorial).
The tutorials in this chapter follow on from the Character Mode sample session in the chapter Sample Session in Character Mode in your Getting Started With Dialog System. You should work through that sample session before you start on the tutorials presented here. You need to work through these tutorials in sequence, because some of them require screensets created in earlier ones.
You can cut and paste across multiple lines containing mixtures of text and data.
Experiment with cutting and pasting using the following steps:
A list of panels appears (at present you only have one).
To cut a block:
position the cursor at the top left corner of the block
press F2=mark/unmark
move the cursor to the bottom right corner of the block
press F7=cut-to-block
To paste a block:
move the block to the required position using cursor keys
press F2=paste
You are prevented from doing two things:
When you are moving a block around you can see that the menu enables you to use the copy-from-block function.
A copy of the block you cut is placed at the desired position and you still have the cut block to move elsewhere. This means that you can place multiple copies at various parts of the panel. You can see that you can copy not only text, but also fields, together with all the field details, in this way.
You return to the panel painting menu without pasting or copying the block. Instead, the block you cut has been placed in a stack (maximum of 16). You can pop the block from the stack by selecting F9=restore-block.
When you pop a block, it acts as if it had just been cut or copied, and you can move it to the required location and paste it. If necessary, you can push it back onto the stack instead.
The only block function you have not yet used is the F8=copy-to-block function on the panel menu.
You can see that this function behaves in the same way as the cut except that a copy of the block is left in the original position.
It should be obvious by now that you do not need to make the original panel a perfect design right from the start. You only need to get the text and the data fields onto the panel, then you can cut, copy, and paste blocks later to improve the layout.
This is the end of Tutorial 1.
In this tutorial you will perform the following actions:
The next steps describe how to modify Test2.
The first thing to do is to modify the Data Block. For this example, we have decided that our product has a number of different selling prices. In fact, there are a maximum of 50 different selling prices for each product. For each of these prices, there must be a description.
S-PRICE, numeric (9), 3 Digits + 2 decimal places (3.2);
S-DESC, alphanumeric (X), 20 characters (20).
Figure 22-1: Defining the Group
You should now have the cursor in the top left hand corner of the screen and the STOCK panel visible on the screen.
You have now placed the group fields on the screen. However, you have only placed one occurrence of them on the screen and there are 50 in the Data Block. There is, in fact, only room for four occurrences on this screen.
This defines the marked area, including the fields, as a group. You are prompted for a name for the group.
The menu now enables you to add occurrences to the group by pressing the down cursor.
Figure 22-2: Four Occurrences on the Panel
If you try to run the screenset, it would run in the same way as the original screenset (TEST1) because we have not yet defined any dialog that will enable us to use this second panel.
We need to choose a keystroke to use on this panel that will cause the second panel (SELLING) to be displayed at run time. Let's use the F10 key. You can put some text on the panel as a reminder for this key.
Note: If you paint the text on the border, the text will not appear at run time, because the border takes precedence. (You can remove the border if you wish – see later).
Now you can set up the dialog that enables the F10 key to display the second panel. Previously you have defined global dialog that operated across the entire screenset. Now you just wish to define dialog that is local to the current panel.
This invokes the dialog menu that you have seen before. The keystroke we wish to define is F10.
The action we want is that when F10 is pressed, the second panel is activated. We can decide how to return from the second panel later. However, when we return from the second panel, we want to return to the STOCK panel in the place we left off. To do this, associate the following dialog functions with the F10 key:
Function PUSH with parameter $NULL
Function GOP with parameter SELLING
The two functions (PUSH and GOP) each require one parameter. Most functions you can use require between zero and three parameters.
For this simple example, the single parameter for the PUSH function is a null parameter, which is named $NULL. Later examples show the PUSH function with a parameter that is not null.
For the GOP function, the single parameter is the name of a panel.
The first function in the dialog pushes the current state of the screen onto a stack, which you can pop from the stack later. The second function means Go To the Panel named SELLING.
Let's decide to use Escape to go back to the previous panel.
There is already a function defined for the Escape key in the global dialog. This local version, however, overrides that definition for this panel only. (You can select to have global overriding local, or the opposite, from the main ALT menu using the F5=screenset-switches option).
You will find that you can enter data only into the first occurrence, so we need to rectify this.
To accept data into more than just the first occurrence in a group, you need to define a selection bar for this group.
This enables you to paint the attributes for a selection bar on the top of the first occurrence of the group. You can use F6 to roll around the current attributes and F5 to paint the selected attribute.
If you do not like any of the attributes, you need to exit group definition to set up some alternative attributes.
When you exit select bar definition and group definition, the select bar attributes apparently disappear. They have not actually disappeared, which you can confirm by going back into select bar definition again.
At run time, all data accepted into this group is accepted at the position of the selection bar. Therefore we need to define in the local dialog how to move the selection bar. An obvious choice is to allow the cursor down key to move the selection bar down and the cursor up key to move the selection bar up.
You will see that you can enter data into all four entries in the screen group. Better than that, you can enter data into all 50 entries in the data group. The group automatically scrolls when you reach the top and bottom of the list.
This is the end of Tutorial 2.
In this tutorial you will perform the following actions:
The following table shows the fields in the Data Block for Test3 and the validation criteria we wish to apply to each field:
| Data Block Field | Validation Criteria |
| P-CODE | must not be emptymust be either "AAAAAA", "BBBBBB","CCCCCC", or greater than or equal to "ZAAAAA" |
| P-NAME | must not be empty |
| P-COST | must be greater than 1.50 |
| P-QUANT | must be in the range 10 to 400 inclusive |
| S-PRICE | no validation |
| S-DESC | no validation |
You can then select the function to define range/table and null validation. The status line (see Figure 22-3) shows which validation types have already been defined.
Figure 22-3: Validation Selected
The panel shown in Figure 22-4 appears. You can see in this panel that a number of range and table validation values have been entered.
Figure 22-4: Range/Table Validation Screen
You can enter a mixture of range and table validations on this panel.
Enter the upper range value by selecting F7=add-range.
You will see that the toggle F5=true/false is set to true. This is what we want. You can test for the values being false if you wish.
This particular field is obviously required to be in upper case only. The next three steps show how to do this.
This forces upper case to be entered at run time.
When you return to the data definition menu, you will see that each of these fields have now got a V beside them.
You will see that two things happen when you put an invalid value in any of the validated fields.
We can control the error attribute. We can also ensure that a suitable error message appears on the panel.
You will also see that if you press F10 when the current field is invalid, you cannot go to the other panel. There is a way to change this, which is described in a later tutorial.
One of the entries on this menu is F6(error). This is the attribute that is used on the current panel when a validation error occurs.
You have set up the error attribute for the STOCK panel. This attribute can be different for every panel.
We now need to define some error messages to appear whenever a validation error occurs. Error messages are held in a relative file at run time and are accessed by their relative key automatically. This file can be common to many applications and does not need to relate to just one screenset.
To define the use of such a file in relation to a particular screenset we need to define:
You have defined the name of the file.
001 Field must not be empty
002 Only A..A, B..B, C..C, and Z.. allowed
003 Cost must be more than 1.50
004 Quantity in range 10 – 400
We must now allocate each message to the particular validation(s) to which it refers.
When you select a validation type such as range/table or null, there is a menu entry F9=error-message. Select this option. You can either type in the error message number, or pick the number from the error message file by moving the selection bar to the appropriate message and pressing the space key.
There are two final things to do before you can use any of the above effectively; create a field in the Data Block that the error message can be moved to, and position the field on the appropriate panel.
The error message field appears to be like any other field in the Data Block. However, when we define this field as the error message field, the run-time system treats it differently. If the run-time system finds an error, it fills this field with the correct value from the error message file, and when the error is resolved, it replaces the value with spaces.
The symbol E appears beside the field. You can define only one field in this way.
We now wish to ensure this field is visible on the STOCK panel.
You should also ensure that this field has the same background attribute as the rest of the panel, so that it is not visible when it is empty.
You might wish to have the error field in a panel of its own that appears only when a validation error occurs. This is quite straightforward and is described in a later example.
You will see that all the validations you defined are handled and all the messages are correctly set up and removed.
This is the end of Tutorial 3.
In this tutorial you will produce a text listing of the screenset.
This displays a list of print options that you can select and de-select using the space bar. We want all the options, so leave this list with every item marked.
This produces a detailed listing of your screenset into a file called test3.lis. If you print a screenset that does not have a name because you have not yet saved it, the list file is written to ds.lis.
Whenever you encounter a new screenset from now on, you might find it useful to print off the details of the screenset.
If your printer cannot handle some of the graphics characters you have used, you can configure these to your printer by altering the file dsdef.cfg. This is described in detail in the chapter Setting Up the Configuration File.
This is the end of Tutorial 4.
In this tutorial you will learn how to trace the dialog using the trap.
There is a menu entry F2=trace on/off.
A separate panel appears, shown in Figure 22-5, which contains the following information:
Figure 22-5: Trace Panel
| Panel: | The name of the current active panel (in our example, STOCK). |
| Register: | An internal register that we will use later for some dialog functions. Its current value is 0. |
| Dialog line: | The current dialog line that is active. It displays the name of the key that activated the dialog, and the entries in the dialog line with the parameters for the current function. |
You can move the trace panel anywhere on the screen to a more suitable position if required, using the cursor up and down keys and the home and end keys.
The following additional keys are now valid:
| S | single step through each dialog function. |
| Z | zoom through all dialog functions until the next return to the trap. |
| F2=start file | causes the trace to be written to a file (until F2 is pressed again). The trace file is the screenset name with extension .trc. This file is always extended so you can write several traces successively. |
One other useful function on the trap screen is F4=initialize-data-fields.
This enables you to clear all the data fields in the way that a calling program might.
This is the end of Tutorial 5.
In this tutorial you will perform the following action:
Now we will define a help panel that will appear whenever F1 is pressed. We will make this help panel quite small and fit more text into it than it is apparently capable of holding (virtual text).
The following menu appears (see Figure 22-6):
Figure 22-6: Fixed Text Group Menu
The group is now surrounded with a highlighted border and the following menu appears (see Figure 22-7):
Figure 22-7: Virtual Text Definition Menu
You can now enter the text you would like on the help screen. There can, of course, be more text than can fit on the visible panel.
Note: There is a counter on the status line, which tells you how many lines there are and which line you are currently on.
We now need to define how to activate this help panel.
We now need to define the dialog for the panel HELP.
We need to be able to move up and down the virtual text. We have seen so far how to move a selection bar up and down a data group. You can also do this with a virtual text group.
The functions we are about to use are concerned with moving around the underlying group. This applies to data groups, virtual text groups and virtual attribute groups (as we shall see later).
We can think of the virtual text as hidden data that we cannot alter at run time.
Key Function Parameters Action
CURU PDUP HELP-TXT Positions the data up
0001 by one line
CURD PDDN HELP-TXT Positions the data down
0001 by one line
PGUP PDUP HELP-TXT Positions the data up
0009 by nine lines
PGDN PDDN HELP-TXT Positions the data down
0009 by nine lines
We also need to define how to exit from help.
We could choose that any key other than the five already listed causes a pop back to the screen that invoked the help panel. To do this, you define this as key ANYO (ANY Other) with function POP.
You will see that this is not behaving quite as you would like. If you press F1, you get an error message on the field you are positioned on. This is because the field is being validated and the F1 keystroke produces a validation error.
You must suppress validation for each field when the F1 key is pressed, by defining the F1 key as an event key. The Escape key in the global dialog was defined as an event key. That is why validation is not carried out when you press Escape.
This places a > symbol beside the F1, indicating that it is an event key.
You have just defined the F1 key in global dialog. More often, you might wish to define the help key locally for each panel, because you might require a different help panel for each of your data entry panels.
There are two further problems you might notice.
When you press the Escape key on the help screen, the global definition of Escape key is used so there is a return to the calling program. You almost certainly do not want this.
Also, if you press F1 inside the help panel, nothing appears to happen. Think about this, and if you are still not sure what is happening, trace the screenset.
Observe how the double push and pop going to the screen SELLING, then to the screen HELP, then back again, is working. There is a maximum of 16 pushes.
This is the end of tutorial 6.
In this tutorial you will perform the following actions:
Virtual attribute groups behave in a similar way to virtual text groups. Instead of entering text against each occurrence in the group, you enter attributes. The two major differences are that a virtual attribute group cannot have a selection bar and can only be one line high.
Figure 22-8: Define New Data Items
Now we will produce a menu so that we can select from one of the three panels STOCK, CUSTOMER and SALESMAN.
A border is not drawn because the panel is only one line high. It might be useful to change the default attribute of the panel so you can see it more clearly.
Figure 22-9: Column Headings
A prompt appears asking you to decide whether the group is an attribute group or a text group (see Figure 22-10).
Figure 22-10: Group Selection Menu
The menu changes to the Virtual Attribute Group menu (see Figure 22-11).
Figure 22-11: Virtual Attribute Group Menu
The menu changes to the Attribute Definition menu (see Figure 22-12).
Figure 22-12: Dsdemo1; Data Block
You are now ready to paint the virtual attributes in a similar way as you did inside selection bar definition.
You want to produce four attribute entries where:
entry 1 highlights "Stock Details"
entry 2 highlights "Customer Details"
entry 3 highlights "Salesman Details"
entry 4 highlights "Exit"
Remember that to get to the third entry from the second, you need to press Enter rather than cursor down, because the default is to begin with just two entries in the list.
Key Function Parameters
CURR PDDN MENU
0001
CURL PDUP MENU
0001
P021 PUSH $NULL
GOP STOCK
P022 PUSH $NULL
GOP CUSTOMER
P023 PUSH $NULL
GOP SALESMAN
P024 RETC
CR BPD MENU
P021
The CURR dialog line refers to the cursor right key. The number 0001 is the number of lines to position the data down.
The CURL dialog is similar, but for the cursor left key.
The next four entries are "procedure" lines. The key entry in these lines are not keystrokes but procedure entries. The procedure numbers are P021, P022, P023 and P024. You can see that these procedures use the PUSH and GOP functions (except P024, which is a return to the calling program). They are invoked from the last dialog entry line.
The last line of dialog refers to the Enter key. When Enter is pressed, the function is BPD (Branch to procedure depending on data position). This causes procedure P021 to be executed if the attribute data of the MENU group is in position 1, P022 if the attribute in position 2, and so on.
Procedures are named P000 through P255. You can also define procedures in global dialog. If you use the same numbering, the local procedures take default over global procedures unless you have set the reverse as default on the Alt+F5=screenset-switches menu from the main menu.
If you use procedure P000, it has a special significance. This is the panel initialization procedure, which is executed when that panel is activated, before any keystrokes. P000 in global dialog is the screenset initialization procedure.
You need one more change before you can run this screenset. You must define that the first panel that is entered is the menu panel.
This selects the MENU panel as the first panel. You can reorder this list, if you wish, using the F9=relocate-panel function.
You will see that cursor right and cursor left from the menu apparently move the highlighted bar left and right along the line. One thing you might wish to alter is that if you attempt to move beyond the fourth entry, the first entry is highlighted, and vice versa. This gives the effect of rolling round the top of the list.
Key Function Parameters
P001 SD MENU
0001
P002 SD MENU
0004
The first of these procedures, if activated, causes the data to be set "SD"=Set Data) at position 1 in the MENU group, and has the effect of displaying the first virtual attribute entry (that is, position 1).
The second procedure sets the data at position 4.
To activate either of these procedures, we are using the concept of an internal exception condition. For example, if you try to move down the virtual attribute group beyond the last entry, an internal exception condition is created. You might have already observed that this normally causes a beep, but you can also intercept this exception.
The dialog entry for CURR consists of moving one line down the data. Place the following before the PDDN, using F3=insert-function:
Key Function Parameters CURR BPE P001
This causes any exception on the PDDN function to branch to procedure P001.
This is the end of Tutorial 7.
The remainder of the tutorials are based upon sample screensets and programs that are provided on your issue disks.
In this tutorial you will perform the following actions:
The file you need for this tutorial is dsdemo1.s
Figure 22-13: Dsdemo1; Panel
You can see that there is a group item with three fields. Also the date field is validated. The validation message is in the file dsdemo.err.
Figure 22-14: Dsdemo1: Local Dialog
Figure 22-15: Dsdemo1: Local Dialog Function Parameters
Figure 22-16: Dsdemo2; Data Block
There are three new functions you have not yet used:
| IBP | Insert at bar position. This inserts a blank line in the group at the selection bar position. |
| DBP | Delete at bar position. This deletes the line at the selection bar position. |
| GOF | Go to field. This forces the cursor to go to the specified field. The 0000 in the PRODUCT entry indicates the current bar line. A non zero value in here would indicate a specific array element. |
This is the end of Tutorial 8.
In this tutorial you will perform the following actions:
The files you need for this tutorial are dsdemo2.s and dsdemo.err.
Figure 22-17: Dsdemo2: definition mode
You can see that there are some groups in this Data Block and some validations. The validations have been assigned error message numbers, but these are not shown on the data field panel. To see them, you can select F8=validation on the appropriate fields.
| XP | execute procedure – forces a procedure to execute. |
The input-attribute is turned on for some of the panels but not for others. If you turn the input attribute on, it forces the chosen input attribute to be used when there is input to a field. You will see the behavior when you run the screenset.
This affects how a user can move from field to field in a group accepting input at run time. If this flag is set to "bar", any attempt to move off the last field of the current group occurrence moves on to the first field outside the group. If the flag is set to "end", a move off the last field of an occurrence moves on to the first field of the next occurrence of the group. This continues up to the last field of the last occurrence of the group, that is the end of the group. The cursor then moves to the first field outside the group.
This is the end of Tutorial 9.
In this tutorial you will see some examples of:
The file you need for this tutorial is dsdemo3.s.
There is no Data Block in this screenset. It is purely a demonstration of fixed text groups, virtual text groups and attribute groups. The example it uses is the list of mnemonics in Dialog System and their structure. Because it is an example, the lists are not strictly up to date. You might want to make them up to date as an exercise.
Study the dialog for some of these panels, then run the screenset using trace.
This is the end of Tutorial 10.
In this tutorial you will see some examples of data validation.
The files you need for this tutorial are dsdemo4.s and dsdemo.err.
Figure 22-18: Customer Data Block; Part 1
Look at the dialog for the main panel. You can see that there is an entry for a "key" called ERR. This is not a key at all, but the name for a reserved procedure that is executed when a validation error occurs. You can see that this procedure pushes the current panel and goes to the error panel. If you look at the dialog for the error panel, you can see that every keystroke causes a POP, but the RPKY causes that keystroke to be repeated when the POP is complete.
This is the end of Tutorial 11.
In this tutorial you will see a simple update program interfacing to a screenset. This and the next three tutorials use the same program with four different screensets. The screensets will behave in very different ways, but the underlying program in each case is identical.
The files you need for this tutorial are:
customer.s1
customer.cbl
ds-cntrl.mf
customer.cpb (you must generate this file)
customer.err
This generates the customer.cpb file for you. You can set various defaults for this generation, which are described in the chapter Generating the Copyfile. Do not worry about them here.
The program customer.cbp updates an indexed customer file.
$SET ANS85
******** IDENTIFICATION DIVISION **********
identification division.
program-id. customer.
******** ENVIRONMENT DIVISION *************
environment division.
*-----------------------------------------*
input-output section.
file-control.
select customer-file assign "cust.ism"
organization is indexed
record key is file-c-code
access is dynamic.
******** DATA DIVISION ********************
data division.
*-----------------------------------------*
file section.
fd customer-file.
01 customer-record.
03 file-c-code pic x(5).
03 file-c-name pic x(15).
03 file-c-addr1 pic x(15).
03 file-c-addr2 pic x(15).
03 file-c-addr3 pic x(15).
03 file-c-addr4 pic x(15).
03 file-c-limit pic 9(4) comp.
03 file-c-area pic x.
03 file-c-order.
78 no-of-orders value 10.
05 file-c-order-entry occurs no-of-orders.
07 file-ord-no pic 9(6).
07 file-ord-date pic 9(6).
07 file-ord-val pic 9(4)v99 comp.
07 file-pay-val pic 9(4)v99 comp.
*-----------------------------------------*
working-storage section.
* copy "ds-cntrl.mf".
*******************************************
* Control Block (Micro Focus Constants)
*******************************************
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".
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-INITIALISED 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-FIELD-NAME PIC X(8)
05 DS-OUTPUT-RESERVED PIC X(8).
*******************************************
* End of Control Block
*******************************************
*copy "customer.cpb".
*******************************************
* Data Block for Set CUSTOMER
*******************************************
01 CUSTOMER-DATA-BLOCK-VERSION-NO PIC 9(4) VALUE 36.
01 CUSTOMER-VERSION-NO PIC 9 VALUE 1.
01 CUSTOMER-SET-BUILD-NO PIC 9(4) VALUE 50.
01 CUSTOMER-DATA-BLOCK.
03 CUSTOMER-C-CODE PIC X(5).
03 CUSTOMER-C-NAME PIC X(15).
03 CUSTOMER-C-ADDR1 PIC X(15).
03 CUSTOMER-C-ADDR2 PIC X(15).
03 CUSTOMER-C-ADDR3 PIC X(15).
03 CUSTOMER-C-ADDR4 PIC X(15).
03 CUSTOMER-C-LIMIT PIC S9(4).
03 CUSTOMER-C-AREA PIC X.
03 CUSTOMER-GROUP-001.
04 CUSTOMER-GROUP-ITEM-001 OCCURS 10.
05 CUSTOMER-ORD-NO PIC S9(6).
05 CUSTOMER-ORD-DATE PIC 9(6).
05 CUSTOMER-ORD-VAL PIC 9(4)V9(2).
05 CUSTOMER-PAY-VAL PIC S9(4)V9(2).
05 CUSTOMER-ORD-BAL PIC S9(4)V9(2).
03 CUSTOMER-C-BAL PIC S9(5)V9(2).
03 CUSTOMER-GROUP-002.
05 CUSTOMER-DEL-FLG PIC 9.
88 CUSTOMER-DEL-FLG-TRUE VALUE 1.
05 CUSTOMER-LOAD-FLG PIC 9.
88 CUSTOMER-LOAD-FLG-TRUE VALUE 1.
05 CUSTOMER-SAVE-FLG PIC 9.
88 CUSTOMER-SAVE-FLG-TRUE VALUE 1.
05 CUSTOMER-CLR-FLG PIC 9.
88 CUSTOMER-CLR-FLG-TRUE VALUE 1.
05 CUSTOMER-EXIT-FLG PIC 9.
88 CUSTOMER-EXIT-FLG-TRUE VALUE 1.
03 CUSTOMER-ERR-MSG PIC X(20).
*******************************************
* End of Data Block for Set CUSTOMER
*******************************************
******************************************* * Field Numbers for Set CUSTOMER ******************************************* 01 CUSTOMER-FIELD-NUMBERS. 03 CUSTOMER-FLD-NO-C-CODE PIC 9(4) COMP VALUE 1. 03 CUSTOMER-FLD-NO-C-NAME PIC 9(4) COMP VALUE 2. 03 CUSTOMER-FLD-NO-C-ADDR1 PIC 9(4) COMP VALUE 3. 03 CUSTOMER-FLD-NO-C-ADDR2 PIC 9(4) COMP VALUE 4. 03 CUSTOMER-FLD-NO-C-ADDR3 PIC 9(4) COMP VALUE 5. 03 CUSTOMER-FLD-NO-C-ADDR4 PIC 9(4) COMP VALUE 6. 03 CUSTOMER-FLD-NO-C-LIMIT PIC 9(4) COMP VALUE 7. 03 CUSTOMER-FLD-NO-C-AREA PIC 9(4) COMP VALUE 8. 03 CUSTOMER-FLD-NO-ORD-NO PIC 9(4) COMP VALUE 9. 03 CUSTOMER-FLD-NO-ORD-DATE PIC 9(4) COMP VALUE 10. 03 CUSTOMER-FLD-NO-ORD-VAL PIC 9(4) COMP VALUE 11. 03 CUSTOMER-FLD-NO-PAY-VAL PIC 9(4) COMP VALUE 12. 03 CUSTOMER-FLD-NO-ORD-BAL PIC 9(4) COMP VALUE 13. 03 CUSTOMER-FLD-NO-C-BAL PIC 9(4) COMP VALUE 14. 03 CUSTOMER-FLD-NO-DEL-FLG PIC 9(4) COMP VALUE 15. 03 CUSTOMER-FLD-NO-LOAD-FLG PIC 9(4) COMP VALUE 16. 03 CUSTOMER-FLD-NO-SAVE-FLG PIC 9(4) COMP VALUE 17. 03 CUSTOMER-FLD-NO-CLR-FLG PIC 9(4) COMP VALUE 18. 03 CUSTOMER-FLD-NO-EXIT-FLG PIC 9(4) COMP VALUE 19. 03 CUSTOMER-FLD-NO-ERR-MSG PIC 9(4) COMP VALUE 20. ******************************************* * End of Field Numbers for Set CUSTOMER ******************************************* 78 refresh-text-and-data-proc value 255. 78 dialog-system value "DSRUN". 01 array-ind pic 9(4) comp. 01 display-error-no pic 9(4).
procedure division.
*-----------------------------------------*
controlling section.
perform program-initialize
perform program-body
until CUSTOMER-EXIT-FLG-TRUE
perform program-terminate.
*-----------------------------------------*
program-initialize section.
initialize DS-CONTROL-BLOCK
initialize CUSTOMER-DATA-BLOCK
move CUSTOMER-DATA-BLOCK-VERSION-NO
to DS-DATA-BLOCK-VERSION-NO
move CUSTOMER-VERSION-NO to DS-VERSION-NO
open i-o customer-file
perform load-screenset.
*-----------------------------------------*
program-body section.
if DS-EXIT-FIELD-TRUE
perform derivations
perform set-up-for-refresh-screen
end-if
evaluate true
when CUSTOMER-DEL-FLG-TRUE
perform delete-record
when CUSTOMER-LOAD-FLG-TRUE
perform load-record
when CUSTOMER-SAVE-FLG-TRUE
perform save-record
when CUSTOMER-CLR-FLG-TRUE
perform clear-record
end-evaluate
perform clear-flags
perform call-dialog-system.
*-----------------------------------------*
program-terminate section.
close customer-file
stop run.
*-----------------------------------------*
delete-record section.
move CUSTOMER-C-CODE to file-c-code
delete customer-file
perform clear-record.
*-----------------------------------------*
load-record section.
initialize customer-record
move CUSTOMER-C-CODE to file-c-code
if file-c-code not = spaces
read customer-file
invalid key
initialize CUSTOMER-DATA-BLOCK
move file-c-code to CUSTOMER-C-CODE
not invalid key
perform fill-screen-from-record
perform derivations
end-read
else
initialize CUSTOMER-DATA-BLOCK
end-if
perform set-up-for-refresh-screen.
*-----------------------------------------*
save-record section.
perform fill-record-from-screen
rewrite customer-record
invalid key
write customer-record
end-write
end-rewrite.
*-----------------------------------------*
clear-flags section.
initialize CUSTOMER-GROUP-002.
*-----------------------------------------*
clear-record section.
initialize customer-record
initialize CUSTOMER-DATA-BLOCK
perform set-up-for-refresh-screen.
*-----------------------------------------*
fill-record-from-screen section.
move CUSTOMER-C-CODE to file-c-code
move CUSTOMER-C-NAME to file-c-name
move CUSTOMER-C-ADDR1 to file-c-addr1
move CUSTOMER-C-ADDR2 to file-c-addr2
move CUSTOMER-C-ADDR3 to file-c-addr3
move CUSTOMER-C-ADDR4 to file-c-addr4
move CUSTOMER-C-LIMIT to file-c-limit
move CUSTOMER-C-AREA to file-c-area
perform varying array-ind from 1 by 1
move CUSTOMER-ORD-NO(array-ind)
to file-ord-no(array-ind)
move CUSTOMER-ORD-DATE(array-ind)
to file-ord-date(array-ind)
move CUSTOMER-ORD-VAL(array-ind)
to file-ord-val(array-ind)
move CUSTOMER-PAY-VAL(array-ind)
to file-pay-val(array-ind)
end-perform.
*-----------------------------------------*
fill-screen-from-record section.
move file-c-code to CUSTOMER-C-CODE
move file-c-name to CUSTOMER-C-NAME
move file-c-addr1 to CUSTOMER-C-ADDR1
move file-c-addr2 to CUSTOMER-C-ADDR2
move file-c-addr3 to CUSTOMER-C-ADDR3
move file-c-addr4 to CUSTOMER-C-ADDR4
move file-c-limit to CUSTOMER-C-LIMIT
move file-c-area to CUSTOMER-C-AREA
perform varying array-ind from 1 by 1
until array-ind > no-of-orders
move file-ord-no(array-ind)
to CUSTOMER-ORD-NO(array-ind)
move file-ord-date(array-ind)
to CUSTOMER-ORD-DATE(array-ind)
move file-ord-val(array-ind)
to CUSTOMER-ORD-VAL(array-ind)
move file-pay-val(array-ind) to
to CUSTOMER-PAY-VAL(array-ind)
end-perform.
*-----------------------------------------*
set-up-for-refresh-screen section.
move refresh-text-and-data-proc
to DS-PROC-NO.
*-----------------------------------------*
derivations section.
move 0 to CUSTOMER-C-BAL
perform varying array-ind from 1 by 1
until array-ind > no-of-orders
compute CUSTOMER-ORD-BAL(array-ind) =
CUSTOMER-ORD-VAL(array-ind) -
CUSTOMER-PAY-VAL(array-ind)
add CUSTOMER-ORD-BAL(array-ind)
to CUSTOMER-C-BAL
end-perform.
*-----------------------------------------*
load-screenset section.
move DS-NEW-SET to DS-CONTROL
move "CUSTOMER" to DS-SET-NAME
perform call-dialog-system.
*-----------------------------------------*
call-dialog-system section.
call dialog-system using DS-CONTROL-BLOCK,
CUSTOMER-DATA-BLOCK
if not DS-NO-ERROR
move DS-SYSTEM-ERROR-NO
to display-error-no
display "DS ERROR NO: "
display-error-no
perform program-terminate
end-if.
************ END OF PROGRAM ***************
The CUSTOMER-DATA-BLOCK and CUSTOMER-FIELD-NUMBERS are generated by the Dialog System definition software in the file customer.cpb. The file ds-cntrl.mf is provided with Dialog System.
Figure 22-19: Customer Data Block; Part 2
This is exactly what they are. If you look at the PROGRAM-BODY SECTION in the program listing, you can see how the program acts on these flags.
Figure 22-20: Customer Data Block; Part 2 Program Body Section
You can see a SETF function (SET Flag) in the dialog. Its effect is to put the value 1 into the field defined in the parameter.
Apart from the SETF function, you can see the RETC function (RETurn to Calling program). If you look at the first line in the dialog you can see that the F2 key causes the LOAD-FLG to be set.
The customer.cpb program requires a screenset called customer.s, which is why you saved the screenset with that name.
You now need to compile your program to test it running. It is assumed that you are using Micro Focus NetExpress.
This is the end of Tutorial 12.
In this tutorial you will learn more about the behavior of a screenset and its relation to the calling program. You will also learn how to run a program through the trap.
The files you need for this tutorial are:
customer.s2
customer.cbl
ds-cntrl.mf
customer.cpb
customer.err
The program is the same program that you have just used, but the screenset customer.s2 is different. Before the program can use this new screenset, you must load it and save it as customer.s.
Look especially at the dialog in the panel "MENU-SCR". This panel contains a fixed text group that is used as a menu. The menu items can be selected either by typing a key letter or using the selection bar and pressing Enter.
It might be useful to run the program and the trap at the same time. You can do this using the following steps.
78 DIALOG-SYSTEM VALUE "DSRUN".
to:
78 DIALOG-SYSTEM VALUE "DS".
The program is now calling the trap. This enables you to have all the trap functions except for two; you cannot change the screenset name and you cannot change the control field. It is probably important here for you to consider how this facility will help you in developing your applications.
In this tutorial you will learn more about the behavior of a screenset and its relation with the calling program.
The files you need for this tutorial are:
customer.s3
customer.cbl
ds-cntrl.mf
customer.cpb
customer.err
The program is the same program that you have just used, but the screenset customer.s3 is different. Before the program can use this new screenset, you must load it and save it as customer.s.
You can see that you are now forced to enter upper case values into the customer code. This is because case sensitivity off was selected when the field was placed on the panel. Also you cannot access any customer records whose key contains lower case letters. This illustrates why you must decide in advance whether you wish to force upper case on keys.
This is the end of Tutorial 14.
In this tutorial you will learn more about the behavior of a screenset and its relation with the calling program.
The files you need for this tutorial are:
customer.s4
customer.s5
customer.cbl
ds-cntrl.mf
customer.cpb
customer.err
Just like the other examples, load the screensets and run them through the trap before you run the program. Save the screenset to use as customer.s so you can use it with the program customer.cbp.
In customer.s4, the screenset shows the menu permanently and switches between menu and input screen using the F10 key.
The screenset customer.s5 is included as an example of a user interface still using the same CUSTOMER program and created by the action bar and pulldown generation facility included with Dialog System.
This is the end of Tutorial 15.
In this tutorial you will see how a program is used to control the paging of data in and out of a file, and how this relates to the panel and Data Block paging in the screenset.
The files you need for this tutorial are:
dsdemo5.s
dsdemo5.cbl
ds-cntrl.mf
dsdemo5.cpb
dsdemo5.fle
Generate dsdemo5.cpb in Dialog System using the generate feature.
The application illustrated in this tutorial is typical of the sort that developers commonly wish to create.
There is a relative file containing many records and you wish to display a number of records in a panel. (This particular panel displays 18 records.) To minimize disk activity, you can create a Data Block that has more records than the panel. (This Data Block has 52 records, which allows for page down on 18 twice without accessing the disk.)
The COBOL program is:
$set ans85 comp noqual noalter align(1) noosvs
$set vsc2
identification division.
* This program handles the viewing of the contents of a relative
* file. The screen has a visible size of "visible-size". The
* size of the file array in the data block is "file-array-size".
* For this program to work correctly the file-array-size must be
* greater than the visible-size.
* You are provided with test file "dsdemo5.fle"which illustrates
* the use of this program. It may be of interest to note that
* the record size of this test file is exactly the same as the
* record size of any of the error message files you create. As a
* tutorial you may wish to use this program to look at one of
* your own error message files. (Beware however that the error
* message files have a dummy system record at the start, so that
* your error numbers are always one greater than the relative
* record key.
environment division.
input-output section.
file-control.
select test-file assign "dsdemo5.fle"
organization is relative
access mode is dynamic
relative key is rel-key
file status is file-status.
data division.
file section.
fd test-file.
01 test-file-record pic x(76).
working-storage section.
* local proc numbers
78 data-up-proc value 144.
78 data-down-proc value 145.
* run time and screenset name constants
78 dialog-system value "DSRUN".
78 screen-set-name value "DSDEMO5".
* visible-size is one less than the size of the visible portion
* of the array on the screen.This is to allow pageing of data to
* still leave one of the previous records visible on the screen
78 file-array-size value 52.
78 visible-size value 17.
* relative record variables
01 rel-key pic 9(4) comp.
01 rec-limit pic 9(4) comp.
01 actual-amount-read pic 9(4) comp.
* temporary indexes used in array manipulations
01 temp-ind-1 pic s9(4) comp.
01 temp-ind-2 pic s9(4) comp.
01 file-status pic x(2).
88 successful-io value "00".
88 end-of-file value "10" "46".
* buffer used to store extra records when paging
* beyond the current limits of the array.
01 paging-buffer.
03 paging-buffer-item occurs visible-size.
05 buffer-rnumber pic 9(3).
05 buffer-rcontents pic x(76).
copy "ds-cntrl.mf".
copy "dsdemo5.cpb".
*************************************
* procedure division *
*************************************
procedure division.
main-process section.
perform initialise-demo-handler
perform process-file-list
until dsdemo5-esc-flag-true
perform terminate-process.
*************************************
initialise-demo-handler section.
initialize dsdemo5-data-block
move dsdemo5-data-block-version-no
to ds-data-block-version-no
move dsdemo5-version-no to ds-version-no
open input test-file
perform load-array-from-file
if rec-limit < file-array-size
move rec-limit to dsdemo5-line-lim
else
move file-array-size to dsdemo5-line-lim
end-if
initialize ds-input-fields
move ds-new-set to ds-control
move screen-set-name to ds-set-name
perform call-dialog-system
move ds-continue to ds-control.
*************************************
process-file-list section.
if dsdemo5-up-flag-true
perform adjust-array-up
else
if dsdemo5-dn-flag-true
perform adjust-array-down
end-if
end-if
perform clear-flags
perform call-dialog-system.
*************************************
terminate-process section.
close test-file
stop run.
*************************************
adjust-array-up section.
move dsdemo5-rnumber(1) to rel-key
perform read-previous-page
if actual-amount-read > zero
perform shuffle-array-down
move actual-amount-read
to dsdemo5-adj-cnt
move data-down-proc to ds-proc-no
end-if.
*************************************
adjust-array-down section.
move dsdemo5-rnumber(file-array-size)
to rel-key
perform read-next-page
if actual-amount-read > zero
perform shuffle-array-up
move actual-amount-read
to dsdemo5-adj-cnt
move data-up-proc to ds-proc-no
end-if.
*************************************
read-previous-page section.
* this section attempts to read backwards through the file up to
* visible-size records
move zero to actual-amount-read
subtract 1 from rel-key
if rel-key not = 0
move visible-size to temp-ind-1
perform read-test-file
perform until rel-key = 0
or actual-amount-read = visible-size
if successful-io
add 1 to actual-amount-read
move rel-key
to buffer-rnumber(temp-ind-1)
move test-file-record
to buffer-rcontents(temp-ind-1)
subtract 1 from temp-ind-1
end-if
subtract 1 from rel-key
perform read-test-file
end-perform
end-if.
*************************************
read-next-page section.
* this section attempts to read forwards through
* the file up to visible-size records
move zero to actual-amount-read
perform read-test-file
perform read-next-record
perform until end-of-file
or actual-amount-read = visible-size
if successful-io
add 1 to actual-amount-read
move rel-key
to buffer-rnumber(actual-amount-read)
move test-file-record
to buffer-rcontents(actual-amount-read)
end-if
perform read-next-record
end-perform.
*************************************
load-array-from-file section.
* this section does the initial load of as much of
* the file as it can get into the array
move 1 to rec-limit
move 1 to rel-key
perform read-test-file
perform until not successful-io
or rec-limit > file-array-size
if successful-io
move rel-key
to dsdemo5-rnumber(rec-limit)
move test-file-record
to dsdemo5-rcontent(rec-limit)
add 1 to rec-limit
end-if
perform read-next-record
end-perform
subtract 1 from rec-limit.
*************************************
shuffle-array-up section.
move actual-amount-read to temp-ind-1
add 1 to temp-ind-1
move 1 to temp-ind-2
perform until temp-ind-1 > file-array-size
move dsdemo5-group-item-001(temp-ind-1)
to dsdemo5-group-item-001(temp-ind-2)
add 1 TO temp-ind-1
add 1 TO temp-ind-2
end-perform
move 1 to temp-ind-1
move file-array-size to temp-ind-2
subtract actual-amount-read from temp-ind-2
add 1 to temp-ind-2
perform until temp-ind-2 > file-array-size
move paging-buffer-item(temp-ind-1)
to dsdemo5-group-item-001(temp-ind-2)
add 1 TO temp-ind-1
add 1 TO temp-ind-2
end-perform.
*************************************
shuffle-array-down section.
move file-array-size to temp-ind-1
subtract actual-amount-read from temp-ind-1
move file-array-size to temp-ind-2
perform until temp-ind-2 = actual-amount-read
move dsdemo5-group-item-001(temp-ind-1)
to dsdemo5-group-item-001(temp-ind-2)
subtract 1 from temp-ind-1
subtract 1 from temp-ind-2
end-perform
move visible-size to temp-ind-1
move actual-amount-read to temp-ind-2
perform until temp-ind-2 < 1
move paging-buffer-item(temp-ind-1)
to dsdemo5-group-item-001(temp-ind-2)
subtract 1 from temp-ind-1
subtract 1 from temp-ind-2
end-perform.
*************************************
clear-flags section.
move 0 to dsdemo5-esc-flag
move 0 to dsdemo5-up-flag
move 0 to dsdemo5-dn-flag.
*************************************
read-test-file section.
read test-file.
*************************************
read-next-record section.
read test-file next.
*************************************
call-dialog-system section.
call dialog-system using ds-control-block
dsdemo5-data-block
if ds-system-error-no > zero
perform terminate-process
end-if.
*************************************
The best way to understand the combination of screenset, program and file is to animate the program while you run the screenset.
A number of new functions are used, which monitor the size of the panel array. For further information about these, see the chapters Function Code List and Dialog.
This is the end of Tutorial 16.
Windows:
In this tutorial, which is not available on UNIX, you will learn how a
Micro Focus Panels screenset can be manipulated. Full details of the use
of Micro Focus Panels can be found in your NetExpress documentation.
The files you need for this tutorial are:
dsdemo6.s
dsdemo6.cbl
ds-cntrl.mf
dsdemo6.cpb
panlink.cpy
Generate dsdemo6.cpb using the generate option in Dialog System.
This is a demonstration of the use of Micro Focus Panels based screensets. When you load the screenset, you can see that it is a Micro Focus Panels screenset by looking at the F2 key on the Alt+F5 menu from the main menu. The main additional function used here is the extraction of the panel-id (MPID). The program the uses this panel-id to call Micro Focus Panels directly. The Panels program provided with Dialog System is called Dspanels.
Animate the program to examine the behavior of the screenset and the program.
This is the end of Tutorial 17.
In this tutorial, you will see a menu that uses a virtual text group with multiple pulldown sub-menus for each main menu item. The pulldown menus are all examples of fixed text groups. Each pulldown option passes control to a panel.
The file you need for this tutorial is dsdemo7.s.
Load this screenset and examine the dialog in each of the panels. Run the screenset through the trap and look at its behavior with the trace facility.
This is the end of Tutorial 18.
In this tutorial, you will see examples of two pick and point menu types. Also, you will see an example of a data group with automatic scrolling backward and forward using both the Tab and cursor keys.
The file you need for this tutorial is dsdemo8.s.
Load this screenset and examine the dialog in each of the panels. Run the screenset through the trap and look at its behavior with the trace facility.
This is the end of Tutorial 19.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Error Messages | Dialog System Limits | |