PreviousSetting Up the Configuration File Key Code ListNext

Chapter 17: Common Questions and Answers

This chapter provides answers to some questions that people unfamiliar with Dialog System typically ask. Each answer includes a detailed description with step-by-step instructions for solving the problem.

Also, your Dialog System software includes some screensets with sample solutions to each question. The names of these screensets are question-number.s, for example, q1.s, q2.s, and q3.s.

The subjects covered by the questions are:

  1. Displaying a validation message

  2. Defining a validation message panel

  3. Defining scrolling data groups

  4. Inserting and deleting fields in an array

  5. Checking the size of an array

  6. Creating a menu entry table

  7. Creating a highlighted menu entry line

  8. Extracting virtual text

  9. Chaining panels

17.1 Displaying a Validation Message

Q1.:
How do I define how validation messages are displayed when an error is found and removed when the error is corrected?

A.:
The display and removal of validation messages is completely automatic once you make the relevant definitions. Use the following steps:

  1. Define the data fields that you require for your screenset (see the chapter Data Definition for details).

  2. Define an additional data field called ERR-MSG as alphanumeric and length 40.

  3. Define this field to be the error message field (see the chapter Data Definition for details of error message field definition).

  4. Define the error messages that you are going to use.

  5. Define validations for the required fields (see the chapter Data Definition for details of validation definition).

  6. Associate an error message with each of these validations (see the chapter Data Definition for validation error message definition).

  7. Define a suitable panel (see the chapter Panels for details).

  8. Place the data fields for which you have defined validations on this panel and ensure that their usage is set to INPUT (see the chapter Panel Painting for details on positioning data fields on panels).

  9. Place the ERR-MSG field on this panel and ensure that its usage is set to OUTPUT.

  10. Define the following global dialog: the <right-arrow>| key causes a skip to next field; and the |<left-arrow> key causes a skip to the previous field (see the chapter Dialog for details). You might find this dialog table helpful: 
    Key     Function   Parameters

    TAB     SKNF        0001
    BTAB    SKPF        0001

This screenset is now ready to run (see the chapter Running the Screenset for details on running screensets). You can compare your screenset with the sample provided in q1.s.

17.2 Defining a Validation Message Panel

Q2.:
How do I define just one panel in which all of my error messages can appear?

A.:
This is a common requirement. The previous example explained how to place the error message field on the relevant panel, which you could do for every panel. However, it is also quite straightforward to create a separate panel. This example continues on from the example in Question One. Use the following steps:

  1. Define a separate panel to display error messages, and place the ERR-MSG output field, created in the last example, on it.

  2. Define the following local dialog for this error message panel: Any keystroke pops the panel; the keystroke is repeated on the panel popped to; but the Escape key is not repeated after the POP (otherwise it causes a return to the calling program). See the chapter Dialog for details on defining dialog. You might find the following dialog table helpful: 
    Key     Function        Parameters

ESC     POP
ANYO    RPKY
        POP
  3. Define the following local dialog for the panel containing the data fields for which you have defined validations: a validation error pushes the current panel; the cursor is turned on (remember, the cursor is automatically turned off in panels that contain no input fields); and control goes to the error panel. The dialog table for this "error procedure" looks like this: 
    Key     Function        Parameters

ERR     PUSH            $NULL
        CON
        GOP             ERROR

This screenset is now ready to run (see the chapter Running the Screenset for details of running screensets). You can compare your screenset with the sample in q2.s.

17.3 Defining Scrolling Data Groups

Q3.:
How do I define scrolling for an array of data fields?

A.:
This is also a common requirement. Dialog System can have up to 30 separate scrolling groups on each panel. For simplicity, the example shows how to define just one.

  1. Define five data fields as follows (see the chapter Data Definition for details on defining data):

    Name FIELD1, Format X, Size 20
    Name FIELD2, Format X, Size 10
    Name FIELD3, Format X, Size 3
    Name FIELD4, Format 9, Size 4.2
    Name FIELD5, Format 9, Size 4.2

  2. Define FIELD1 as a data group with 50 repeats (see the chapter Data Definition for details on defining data groups).

  3. Include the remaining four fields in the group to create a group of data items that repeat 50 times in the Data Block. Now you must define how this group is used on the panel.

  4. Define a panel wide enough to contain all the fields side by side, that is, a panel of approximately 60 characters (see the chapter Panels for details).

  5. Position the fields side by side along one row of the panel (see the chapter Panel Fields for details).

    The fields are now on the panel, but there is only one occurrence of each. If you run the screenset at this stage, you can enter data only on the first of each of the 50 occurrences in each field.

  6. Define your row of fields as a panel group and call it "DATA-GRP" (see the chapter Panel Groups for details).

  7. Extend the size of the group to the number of occurrences you wish to be visible on the screen at one time. Remember that the final array will scroll, so you do not need to have all 50 occurrences visible at once.

  8. Select the group-accept-exit-bar option from the Data Group menu. This forces the cursor to move off the group after the last field in the last occurrence of the group, rather than after the last field in the current occurrence. It also automatically moves the selection bar.

  9. Define a selection bar on this group (see the chapter Panel Groups for details on defining selection bars).

  10. Define the following local dialog for this panel: <up-arrow> moves the selection bar up by one line; <down-arrow> moves the selection bar down by one line; <right-arrow>| causes a skip to next field; and |<left-arrow> causes a skip to the previous field (see the chapter Dialog for details of defining dialog). You might find this dialog table helpful: 
     Key     Function        Parameters

 CURU    PBUP            DATA-GRP
                         0001
 CURD    PBDN            DATA-GRP
                         0001
 TAB     SKNF            0001
 BTAB    SKPF            0001

This screenset is now ready to run (see the chapter Running the Screenset for details on running screensets). Scrolling at the top and bottom of the list is completely automatic. You can compare your screenset with the sample in q3.s.

17.4 Inserting and Deleting Fields in an Array

Q4.:
How do I define inserting and deleting in an array of data fields?

A.:
You can so this easily using the following steps, which continue on from the previous example.

  1. Follow the steps in Question three.

  2. Define the following additional local dialog for your panel group named DATA-GRP: F3 enables a line to be inserted at the current bar position; and F4 enables a line to be deleted at the current bar position (see the chapter Dialog for details on defining dialog). Your new dialog table looks like this: 
     Key     Function        Parameters

 F3      IBP             DATA-GRP
 F4      DBP             DATA-GRP
 CURU    PBUP            DATA-GRP
                         0001
 CURD    PBDN            DATA-GRP
                         0001
 TAB     SKNF            0001
 BTAB    SKPF            0001

This screenset is ready to run (see the chapter Running the Screenset for details on running screensets). You can compare your screenset with the sample in q4.s.

17.5 Checking the Size of an Array

Q5.:
How can I keep track of how many items there are in an array after inserting and deleting?

A.:
You can both control and monitor this array size. Once you have set the array size, the Dialog System Run-time System prevents you from moving above the first occurrence or below the final occurrence. For example, the previous example uses an underlying array size of 50. Every use of the DBP function reduces the internal array size by one, down to a limit of one. Every use of the IBP function increases the array size by one, up to a limit of 50. However, if you set the array size to five, the IBP function applies only up to a limit of five.

The following steps explain how you can monitor the array size, using the previous example screenset as a starting point.

  1. Define a new data field called ARR-SIZE, which is format 9 and size 2 (see the chapter Data Definition for details on defining data fields). This field will contain the current array limit.

  2. Place the array size field on the panel on which you have placed your panel group, as an OUTPUT field, so that you can see what is happening to it (see the chapter Panel Fields for details).

  3. Define the following additional global dialog for your panel group named DATA-GRP: initialize the screenset, placing a value of two in the data item ARR-SIZE (to ensure that there are only two entries accessible in the panel group at the start). The dialog table looks like this: 
        Key     Function        Parameters

    P000    MOVE            0002
                            ARR-SIZE
  4. Define the following additional local dialog for this panel: set the internal array size to the value in the ARR-SIZE field; move the current internal array size of DATA-GRP to the ARR-SIZE field when an item is inserted; refresh the panel so that the revised value of ARR-SIZE can be viewed; move the current internal array size of DATA-GRP to the ARR-SIZE field when an item is deleted; reset the value of ARR-SIZE to two if its value becomes less than two; and refresh the panel. The amended dialog table looks like this: 
    Key     Function        Parameters

F3      IBP             DATA-GRP
        MAS             DATA-GRP
                        ARR-SIZE
        RFTD
F4      DBP             DATA-GRP
        MAS             DATA-GRP
                        ARR-SIZE
        IF              ARR-SIZE
                        0002
                        P001
        RFTD
CURU    PBUP            DATA-GRP
                        0001
CURD    PBDN            DATA-GRP
                        0001
TAB     SKNF            0001
BTAB    SKPF            0001
P000    SAS             DATA-GRP
                        ARR-SIZE
P001    MOVE            0002
                        ARR-SIZE
        XP              P000

This screenset is ready to run (see the chapter Running the Screenset for details on running screensets). Watch the behavior of the group and the value in ARR-SIZE as it runs. You can compare your screenset with the sample in q5.s.

17.6 Creating a Menu Entry Table

Q6.:
How do I define a list of menu options in the middle of the screen, from which I can select an option either by moving up and down the list and pressing Enter or by typing a key letter?

A.:
This is a common requirement that makes your application much more useful. Use the following steps:

  1. Define a data field called "OPT-NO" with format 9 and size one (see the chapter Data Definition for details on defining data fields).

  2. Define a panel and place five menu text items, such as Load, Save, Clear, Delete and Exit, in the middle of it (see the chapter Panel Fields for details). These are your menu entries, which can be selected either by using the selection bar or typing in the appropriate key letter such as L, S, C, D, X.

  3. Define four additional panels to go to when a menu entry is selected. Name them LOAD, SAVE, CLEAR, and DELETE, respectively (you do not need a separate panel for Exit, because you will use that to terminate the current screenset rather than to go to another panel). Don't place anything in these panels at the moment.

  4. Define the following local dialog for each of these panels: any keystroke pops the panel (see the chapter Dialog for details on defining dialog). The dialog table looks like this: 
    Key     Function        Parameters

ANYO    POP
  5. Define your five menu entries as a fixed text group named MENU (see the chapter Panel Groups for details).

  6. Define a suitable selection bar on this group (see the chapter Panel Groups for details on defining selection bars).

  7. Define the following local dialog for this panel: Enter branches to the procedure to load a menu panel; <up-arrow> and <down-arrow> move the selection bar one line up and down, respectively, and set it on one of the menu options; "C" sets the selection bar on menu option three and goes to the CLEAR menu panel; "D" sets the selection bar on menu option four and goes to the DELETE menu panel; "L" sets the selection bar on menu option one and goes to the LOAD menu panel; "S" sets the selection bar on menu option two and goes to the SAVE menu panel; and "X" sets the selection bar on menu option five and returns to the calling program.

    The dialog table looks like this: 

    Key     Function        Parameters

CR      BPD             MENU
                        P011
CURU    PBUP            MENU
                        0001
CURD    PBDN            MENU
                        0001
C       MOVE            0003
                        OPT-NO
        XP              P001
        XP              P013
D       MOVE            0004
                        OPT-NO
        XP              P001
        XP              P014
L       MOVE            0001
                        OPT-NO
        XP              P001
        XP              P011
S       MOVE            0002
                        OPT-NO
        XP              P001
        XP              P012
X       MOVE            0005
                        OPT-NO
        XP              P001
        XP              P015
P000    MOVE            0000
                        OPT-NO
P001    SB              MENU
                        OPT-NO
P011    PUSH            $NULL
        GOP             LOAD
P012    PUSH            $NULL
        GOP             SAVE
P013    PUSH            $NULL
        GOP             CLEAR
P014    PUSH            $NULL
        GOP             DELETE
P015    RETC

    You have defined the characters C, D, L, S and X in upper case but not in lower case. This is because by default Dialog System recognizes these as the same character. However, if you require case sensitivity, you can turn it on. See the section Dialog Definition Menu in the chapter Dialog for details.

    The procedures defined for the lines in a text group must occur in the same order as the lines in the group.

This screenset is ready to run (see the chapter Running the Screenset for details on running screensets). You can compare your screenset with the sample in q6.s.

17.7 Creating a Highlighted Menu Entry Line

Q7.:
How do I define a menu line at the top of the screen from which I can select an option either by moving along the list and pressing, or by typing a key letter?

A.:
This uses the same principles as the previous question. The differences are that instead of using a fixed text group for the menu and moving a selection bar up and down it, you use a one-line virtual attribute group and press the <left-arrow> and <right-arrow> keys to position the virtual attribute data up and down. Use the following steps:

  1. Define a data field called "OPT-NO" with format 9 and size one, the same as in the previous example (see the chapter Data Definition for details on defining data fields).

  2. Define a one-line panel and place the five menu text items, Load, Save, Clear, Delete and Exit, across it (see the chapter Panel Fields for details).

  3. Define the LOAD, SAVE, CLEAR and DELETE panels to pass control to when the relevant menu entry is selected. Do not place anything in these panels at the moment.

  4. Define the following local dialog for each of these panels: any keystroke POPs the panel (see the chapter Dialog for details on defining dialog). The dialog table looks like this: 
    Key     Function        Parameters

ANYO    POP
  5. Define your five menu entries as a virtual attribute group named MENU and define the set of attributes that will move over the text items on your panel (see the chapter Panel Groups for details).

  6. Define the following local dialog for this panel: Enter branches to the procedure to load a menu panel; <left-arrow> and <right-arrow> position the data one menu item up and down, respectively; "C" sets the data on menu option three and goes to the CLEAR menu panel; "D" sets the data on menu option four and goes to the DELETE menu panel; "L" sets the data on menu option one and goes to the LOAD menu panel; "S" sets the data on menu option two and goes to the SAVE menu panel; and "X" sets the data on menu option five and returns to the calling program.

    The dialog table for this menu panel looks like this: 

    Key     Function        Parameters

CR      BPD             MENU
                        P011
CURL    PDUP            MENU
                        0001
CURR    PDDN            MENU
                        0001
C       MOVE            0003
                        OPT-NO
        XP              P001
        XP              P013
D       MOVE            0004
                        OPT-NO
        XP              P001
        XP              P014
L       MOVE            0001
                        OPT-NO
        XP              P001
        XP              P011
S       MOVE            0002
                        OPT-NO
        XP              P001
        XP              P012
X       MOVE            0005
                        OPT-NO
        XP              P001
        XP              P015
P000    MOVE            0001
                        OPT-NO
P001    SD              MENU
                        OPT-NO
P011    PUSH            $NULL
        GOP             LOAD
P012    PUSH            $NULL
        GOP             SAVE
P013    PUSH            $NULL
        GOP             CLEAR
P014    PUSH            $NULL
        GOP             DELETE
P015    RETC

This screenset is ready to run (see the chapter Running the Screenset for details on running screensets). You can compare your screenset with the sample in q7.s.

17.8 Extracting Virtual Text

Q8.:
Can I extract the contents of a virtual text item into a data field?

A.:
Yes. Use the following steps:

  1. Define two data fields:

    Name POSITION, Format 9, Size 2
    Name TEXT, Format X, Size 30

    The field "TEXT" is the field to move the required virtual text to, and the field "POSITION" is the field to use to monitor this move on the current screen.

  2. Define a panel that contains these two fields as output fields.

  3. Define a virtual text group called "TEXT-GRP" and define about two to three times as much virtual text as can fit on the visible group area.

  4. Define a selection bar on this virtual text.

  5. Define the following local dialog for this panel: carriage return moves the position of the selection bar on the TEXT-GRP group to the POSITION field, transfers the virtual text to the TEXT field at the offset defined by POSITION, then refreshes the information on the panel; <up-arrow> and <down-arrow> position the selection bar one line up and down, respectively, on the virtual text. The dialog table looks like this: 
     Key     Function        Parameters

 CR      MBD             TEXT-GRP
                         POSITION
         MOVEVTXT        TEXT-GRP
                         POSITION
                         TEXT
         RFTD
 CURU    PBUP            TEXT-GRP
                         0001
 CURD    PBDN            TEXT-GRP
                         0001

This screenset is ready to run (see the chapter Running the Screenset for details on running screensets). You can compare your screenset with the sample in q8.s.

17.9 Chaining Panels

Q9.:
How can I "chain" many panels so that <right-arrow>| in the last field in a panel moves to next panel and |<left-arrow> in the first field in a panel moves to the previous panel?

A.:
This is another common requirement. The solution uses the ability to detect an exception condition when a SKNF function attempts to execute but there are no more fields on the panel, and the similar but opposite situation for SKPF. Use the following steps:

  1. Define a number of data fields.

  2. Paint a number of panels, for instance AAAAAAAA, BBBBBBBB, CCCCCCCC, DDDDDDDD and EEEEEEEE.

  3. Place the data fields you defined onto these panels.

  4. Define the following local dialog for the first panel, AAAAAAAA: when SKNF causes an exception, it performs a PUSH and Goes to Panel BBBBBBBB. The dialog table looks like this: 
    Key     Function        Parameters

TAB     BPE             P001
        SKNF            0001
BTAB    SKPF            0001
P001    PUSH            $NULL
        GOP             BBBBBBBB
  5. Define the following local dialog for the second panel, BBBBBBBB: when SKNF causes an exception, it performs a PUSH and Goes to Panel CCCCCCCC, and when SKPF causes an exception, it performs a POP. The dialog table looks like this: 
        Key     Function        Parameters

    TAB     BPE             P001
            SKNF            0001
    BTAB    BPE             P002
            SKPF            0001
    P001    PUSH            $NULL
            GOP             CCCCCCCC
    P002    POP
  6. Define the local dialog for the remaining three panels in the same way, with the additional dialog for the final panel to skip to the first panel on exception. Thus, the dialog table for the last panel looks like this: 
    Key     Function        Parameters

TAB     SKNF            0001
BTAB    BPE             P002
        SKPF            0001
P002    POP

You can chain a number of panels in this way. However, the maximum number of panels you can PUSH is 16.

This screenset is ready to run (see the chapter Running the Screenset for details on running screensets). You can compare your screenset with the sample in q9.s.

Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousSetting Up the Configuration File Key Code ListNext