PreviousError Messages Dialog System LimitsNext

Chapter 22: Tutorials

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.

22.1 Tutorial 1 – Cutting and Pasting Experiment

You can cut and paste across multiple lines containing mixtures of text and data.

Experiment with cutting and pasting using the following steps:

  1. Start the definition process and load Test1.

  2. Press F3=panels followed by F3=panel-list.

    A list of panels appears (at present you only have one).

  3. Select the panel STOCK by pressing Enter.

  4. Try a variety of ways to cut and paste text and data.

    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.

  5. Try selecting F3=copy-from-block.

    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.

  6. After you mark and cut or copy a block, select F4=stack-block.

    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.

  7. Try stacking several blocks, then try restoring them.

    The only block function you have not yet used is the F8=copy-to-block function on the panel menu.

  8. Try marking an area, then selecting F8=copy-to-block.

    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.

  9. Make yourself familiar with all these block functions because you will use them a lot.

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.

22.2 Tutorial 2 – Groups and Scrolling

In this tutorial you will perform the following actions:

  1. Start the definition process again and load in your saved screenset Test1.

  2. Save this screenset immediately as Test2. Press Alt+F4, change test1.s to test2.s, then press Enter.

    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.

  3. Select F2=data-definition from the main menu, then F2=data-fields. Enter two new data items:

    S-PRICE, numeric (9), 3 Digits + 2 decimal places (3.2);
    S-DESC, alphanumeric (X), 20 characters (20).

  4. Move the selection bar to S-PRICE and press F6=define group.

  5. Enter the number of repeats as 50 and press <down-arrow>.

  6. Watch what happens to the number of repeats in S-DESC and the brackets to the left of the two data names.

  7. Press Enter to finish the definition of the group (see Figure 22-1).



    Figure 22-1: Defining the Group

  8. Press Escape to exit data fields and Escape again to get back to the main menu.

  9. Select F3=panels and F3=panel-list.

  10. Select F3=show-panel.

  11. Press Escape to get back to the panels menu again.

    You should now have the cursor in the top left hand corner of the screen and the STOCK panel visible on the screen.

  12. Create a new panel with top left hand corner at row 8, col 11 and bottom right hand corner at row 14, col 69.

  13. Name this panel SELLING.

  14. Paint this panel with a suitable background color.

  15. Inside this panel, move the cursor to row 2, col 15 and type Selling Price.

  16. Type Description at row 2, col 32.

  17. Select F3=field and place the S-PRICE field at row 3, col 17 and the S-DESC field at row 3, col 32.

  18. Escape from field definition.

    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.

  19. Place the cursor on the first character of the first of these fields and select F2=mark.

  20. Move the cursor to the last character of the second field and press F4=group.

    This defines the marked area, including the fields, as a group. You are prompted for a name for the group.

  21. Call this group S-DETS.

    The menu now enables you to add occurrences to the group by pressing the down cursor.

  22. Press <down-arrow> three times so that you have four occurrences visible on the panel, as shown in Figure 22-2.



    Figure 22-2: Four Occurrences on the Panel

  23. Press Enter to exit the group menu.

    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.

  24. Return to the panels menu and select the panel painting menu for the original panel (STOCK) by selecting F3=panel-list and pressing Enter.

    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.

  25. Type the text F10=selling details at the foot of the panel STOCK, just above the border.


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 is the end of Tutorial 2.

22.3 Tutorial 3 – Defining Validations

In this tutorial you will perform the following actions:

  1. Start the definition process again and load in your saved screenset Test2.

  2. Save this screenset immediately as Test3 so that we can modify Test3.

    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
  3. Enter data definition and place the selection bar on P-CODE and select F8=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

  4. Select range/table validation by pressing F3.

    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.

  5. Enter the valid values for P-CODE as defined above.

    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.

  6. Escape from validation, escape from data definition and select the panel STOCK.

  7. Position the cursor on the field P-CODE and select F3=field.

  8. Select F5=amend-field and select UPPER in the properties entry.

    This forces upper case to be entered at run time.

  9. Press Enter to complete the field definition.

  10. Press Escape to go back to the top menu. Go back into data definition and select validation for the field P-CODE.

  11. Select F6=null and select the F2=disallow-null toggle.

  12. Escape from validations and enter validations for P-NAME.

  13. Select the required validations, then do the same for P-COST and P-QUANT.

    When you return to the data definition menu, you will see that each of these fields have now got a V beside them.

  14. Save the screenset and run it. Try entering values in the validated fields.

    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.

  15. Go back into definition and select the STOCK panel.

  16. Select Alt+F3=attribute-palette and select F8=run-time-list.

    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.

  17. Change the error attribute to one that you want, by moving along the attribute list and pressing F6 on the required attribute.

    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:

  18. Go back to the main menu and select F2=data-definition and F3=error-messages. This invokes a menu where you can select F2=select-error-message-file-name.

  19. Press F2 and enter the name test.err as the name of the file. Press Enter.

    You have defined the name of the file.

  20. Select F3=define-error-messages, then define:

    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

  21. Press Escape twice.

    We must now allocate each message to the particular validation(s) to which it refers.

  22. Enter data fields again and go into validation for each of the validated fields.

    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.

  23. Select data definition and define a field at the end of the data fields. Call this field P-ERROR and make it alphanumeric of length 45.

  24. Define this field as the error field by pressing F9=err-msg-fld-def/undef.

    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.

  25. Select the stock panel and select F3=field.

  26. Place the field P-ERROR at an appropriate point on the panel and make sure its usage is OUTPUT.

    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.

  27. Run the screenset.

    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.

22.4 Tutorial 4 – Documenting the Screenset Definition

In this tutorial you will produce a text listing of the screenset.

  1. Load the Test3 screenset.

  2. From the main menu select F7=print.

    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.

  3. Press Enter=print-screen-set.

    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.

  4. Load in the previous two screensets Test1 and Test2 and produce listings of them.

  5. Print off the listings on your printer and review them.

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.

22.5 Tutorial 5 – Using the Trace and Trap

In this tutorial you will learn how to trace the dialog using the trap.

  1. Load your latest screenset (Test3), select F6=run and stop at the trap screen.

    There is a menu entry F2=trace on/off.

  2. Select trace on, then press Enter.

  3. Type "AAAAAA" into the first field, type "xxx" , into the second field, and press BackTab.

    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.

  4. Press S=Step, then F10 and observe the dialog being traced.

  5. Experiment with using trace.

  6. Try using trace on your earlier screensets.

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.

22.6 Tutorial 6 – Virtual Text

In this tutorial you will perform the following action:

  1. Start the definition process again and load in your saved screenset Test3.

  2. Save this screenset immediately as Test4.

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

  3. From panel definition, start by marking an area on the screen with top left corner at row 1, col 57 and bottom right corner at row 13, col 80.

  4. Define this area as a panel called HELP.

  5. Choose a suitable set of colors for this panel.

  6. Place a double line border around this panel by selecting F10=panel-maint then F4=double border, and pressing Escape.

  7. From the panel main menu, type the letters HELP in the middle of the second line of the help panel.

  8. Move the cursor to row 3, col 2 of the panel and mark an area down to row 12, col 23 (that is, everything inside the panel except the borders and heading.

  9. Press F4=group and name the group HELP-TXT.

    The following menu appears (see Figure 22-6):



    Figure 22-6: Fixed Text Group Menu

  10. Press F2=define-virtual-text.

    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.


This is the end of tutorial 6.

22.7 Tutorial 7 – Virtual Attributes

In this tutorial you will perform the following actions:

  1. Start the definition process again and load in your saved screenset Test4.

  2. Save this screenset immediately as Test5.

    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.

  3. Select data definition and define the new data items shown in Figure 22-8:



    Figure 22-8: Define New Data Items

  4. Paint two new panels called CUSTOMER and SALESMAN. Place the appropriate fields on these panels as input fields.

  5. Define the dialog on both these new panels so that Escape pops the panel (POP function).

  6. Alter the dialog on the STOCK panel so that Escape pops the panel (POP function).

    Now we will produce a menu so that we can select from one of the three panels STOCK, CUSTOMER and SALESMAN.

  7. Create a new panel called MENU that is just one line deep and at the top of the screen from column 1 to column 80.

    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.

  8. Type the text shown in Figure 22-9 into this panel.



    Figure 22-9: Column Headings

  9. Move the cursor to the first character of the word Stock and mark an area up to the last character of the words Exit.

  10. Select F4=group.

    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

  11. Select F2=attribute-group, then name the group MENU.

    The menu changes to the Virtual Attribute Group menu (see Figure 22-11).



    Figure 22-11: Virtual Attribute Group Menu

  12. Select F2=define-virtual-attributes.

    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"

  13. Experiment with the virtual attribute features until you have just four virtual attribute entries which highlight the four pieces of text as you require.

    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.

  14. Press Escape twice to get back to the panel menu.

  15. Enter the following dialog for the menu panel:
    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.

  16. Escape back to the panels menu and select F3=panel-list.

  17. Move the selection bar to highlight the "MENU" panel name.

  18. Press F5=select-first-panel.

    This selects the MENU panel as the first panel. You can reorder this list, if you wish, using the F9=relocate-panel function.

  19. Save the screenset and run it, tracing if necessary.

    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.

  20. Go back into definition and dialog entry for the MENU panel.

  21. Define two more procedures.
    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.

  22. Try the above and see if you can work out what is necessary for the CURL key.

  23. Save the screenset and run it. Tracing will help to clarify what is happening.

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.

22.8 Tutorial 8 – Changing Fields in Groups

In this tutorial you will perform the following actions:

The file you need for this tutorial is dsdemo1.s

  1. Go into definition mode and load the screenset Dsdemo1.

  2. Look at the Data Block (see Figure 22-13).



    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.

  3. Look at the panel in this screenset (see Figure 22-14). You can see that there is just one panel.



    Figure 22-14: Dsdemo1: Local Dialog

  4. Look at the local dialog for this panel (see Figure 22-15), and the parameters for each function (see Figure 22-16).



    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.

  5. Run this screenset and observe its behavior, using trace if necessary.

This is the end of Tutorial 8.

22.9 Tutorial 9 – Input Attributes and Procedures

In this tutorial you will perform the following actions:

The files you need for this tutorial are dsdemo2.s and dsdemo.err.

  1. Go into definition mode and load the screenset Dsdemo2 (see Figure 22-17).



    Figure 22-17: Dsdemo2: definition mode

  2. Look at the Data Block.

    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.

  3. Look at the panels in this screenset. There are a number of panels in use.

  4. Look at the dialogs associated with each of these panels. You will see a new function:

    XP execute procedure – forces a procedure to execute.

  5. Press F8 from the attribute palette menu to look at the attribute run-time list for one of the panels.

    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.

  6. Look at one of the screen groups. The group-accept-exit flag is set to "end" rather than "bar".

    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.

  7. Run this screenset and observe its behavior, using the trace if necessary.

This is the end of Tutorial 9.

22.10 Tutorial 10 – Using Different Group Types

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.

22.11 Tutorial 11 – Example of Data Validation

In this tutorial you will see some examples of data validation.

The files you need for this tutorial are dsdemo4.s and dsdemo.err.

  1. Go into definition mode and load the screenset Dsdemo4.

  2. Look at the panel in this screenset (see Figure 22-18). This example is used purely to illustrate various validated fields.



    Figure 22-18: Customer Data Block; Part 1

  3. Go into data validation and study the validations.

    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.

  4. Observe the effect of this by running the screenset through the trap.

This is the end of Tutorial 11.

22.12 Tutorial 12 – The Application Program Interface

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

  1. Generate the file customer.cpb. Go into the definition software and load the screenset customer.s1.

  2. Select F5=generate, then press Enter.

  3. Press F2 to generate the data descriptions.

    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.

  4. The following listing is the listing for customer.cbp, shown so you can study it:
    $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.

  5. Look at the Data Block in the screenset, shown in two parts in the Figures 22-19 and 22-20). You can see that, apart from the obvious fields, there are some fields which appear to be used as flags.



    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.

  6. Save this screenset as customer.s and run the screenset through the trap. Observe its behavior.

    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.

  7. Go into NetExpress and "Check" customer.cbl.

  8. Animate this program and spend some time observing its behavior until you are fully familiar with all the features of the program.

This is the end of Tutorial 12.

22.13 Tutorial 13 – Running the Program with the Trap

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.

  1. Look at the local dialog in each of the panels.

    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.

  2. Run this screenset with trace until you fully understand its behavior, and then run the program.

    It might be useful to run the program and the trap at the same time. You can do this using the following steps.

  3. Edit the program customer.cbl to change the line:
        78  DIALOG-SYSTEM     VALUE "DSRUN".

    to:

        78  DIALOG-SYSTEM     VALUE "DS".
  4. You need to ensure that there is a copy of the file ds.lbr in your current directory in addition to the dsrun.lbr which is currently there.

  5. Go into NetExpress and "check" customer.cbl.

  6. Run the program customer.cbl.

    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.

  7. Edit the program customer.cbl to change the line back to its original form.

  8. Go into NetExpress and "check" customer.cbl again, ready for tutorial 14.

22.14 Tutorial 14 – Case Sensitivity in Screensets

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.

  1. Look at the local dialog in each of the panels.

  2. Run this screenset with trace until you fully understand its behavior, and then run the program.

    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.

22.15 Tutorial 15 – Using Different Screensets

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.

22.16 Tutorial 16 – Paging a Large File

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.

22.17 Tutorial 17 – Using Micro Focus Panels

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.

22.18 Tutorial 18 – Menu Selection – Example 1

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.

22.19 Tutorial 19 – Menu Selection – Example 2

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.

PreviousError Messages Dialog System LimitsNext