PreviousUsing the Client/Server Binding Questions and AnswersNext

Chapter 15: Advanced Topics

This chapter introduces some of the more advanced system features available with Dialog System.

Topics include:

15.1 Implementing Applications to Run on Multiple Resolutions

When writing applications for production use on more than one desktop resolution size, it is possible to implement COBOL program and screenset changes which fully enable window, control and font mapping support based on the current resolution. This section covers the three areas that need to be implemented:

15.1.1 Enabling the screenset for multiple resolutions

This feature is enabled by a CALLOUT to "dsrtcfg" with a flag of 9 and an identifier that tells Dialog System what resolution the screenset was DEFINED under.

The Dialog System run-time uses Panels V2 generic coordinates, which provides a basis for cross-resolution support and compatibility with differing graphics adapters. This results in differing coordinate values for what otherwise appears to be the same resolution setting.

To check the identifier you need to supply for your definition platform, a verification program is supplied with Dialog System: this displays a message box detailing the resolution identifier you need to use to implement the changes. This is executed as follows:

runw dsreschk

This program displays:

Code the following dialog in your SCREENSET-INITIALIZED or other dialog table which will be executed before the windows creation:

CLEAR-CALLOUT-PARAMETERS $NULL

    CALLOUT-PARAMETER 1 CONFIG-FLAG $NULL
    CALLOUT-PARAMETER 2 CONFIG-VALUE $NULL
    MOVE 9 CONFIG-FLAG
    MOVE resolution id CONFIG-VALUE
    CALLOUT "dsrtcfg" 3 $PARMLIST

CONFIG-FLAG and CONFIG-VALUE should be C5 4 byte data fields.

Once implemented, all windows, dialog boxes and their child controls will be resized in proportion to the current resolution. See the topic Multiple Resolution and Dynamic Window Sizing in the Help.

15.1.2 Enabling font mapping

In addition to enabling multiple resolution support in each of your screensets, the objects you create need to be allocated a font style so that their font used at run time may be adjusted depending upon the resolution on which your production application runs.

When you specify a font using Fonts on the Edit menu, you can specify both a typeface and a style name for that font. The style name is a user-defined name that represents the specified typeface, pointsize and attributes. This style name enables your fonts to be increased or decreased in size appropriate to resolutions used at run time.

Select the font typeface, pointsize and attributes required, and enter your required style name in the Selection box provided. For example, My-Style.

Click Apply to apply the selected font style to the current object (or group of objects).

When you specify a binary font side file (with a .dfb extension) using Resource Files on the Options menu, Dialog System looks up the style name in the binary font side file at run time and uses the details of that font for the resolution platform in use. If the style is not found in the side file, the default font is used.

Assume that you want to use a style created under 1024*768 resolution and transfer that to the 640*480 resolution. You have specified a binary font side file (with a .dfb extension) and saved the screenset. When you save the screenset, a textual version of the font side file (.dft file) is created (or appended to) and contains:

[NT]

FONT-RECORD
    STYLENAME My-Style
    ATTRIBUTES BITMAPPED, PROPORTIONAL
    POINTSIZE 12
    TYPEFACE "Roman"
END-RECORD

In order to transfer the screenset and binary font side file to the production environment, you need to edit the .dft side file to incorporate a new definition for running under each possible resolution. The file now contains:

[RESOLUTION1]
FONT-RECORD
    STYLENAME My-Style
    ATTRIBUTES BITMAPPED, PROPORTIONAL
    POINTSIZE 12
    TYPEFACE "Roman"
END-RECORD

[RESOLUTION2]
FONT-RECORD
    STYLENAME My-Style
    ATTRIBUTES BITMAPPED, PROPORTIONAL
    POINTSIZE 8
    TYPEFACE "Roman"
END-RECORD

Notes:


Having added the new section marker and attributes, you need to convert the side file to binary format:

run dsfntgen /t appstyle.dft /b appstyle.dfb /c

This creates the binary side file. Now you need to set the environment variable:

set DSFNTENV=RESOLUTION2

Dialog System automatically selects the new font attributes for that font style definition. DSFNTENV is set to RESOLUTION2 under 640*480 resolutions where smaller fonts are required as there is less available display space.

If DSFNTENV is not set, then no mapping is performed and the default values, stored in the screenset, are used. Provided your screensets are consistent in use of style names you can use just one font side file for applications consisting of many screensets.

15.1.3 Setting the DSFNTENV Environment Variable Using COBOL

You can place the setting of the required DSFNTENV environment variable under control of your COBOL program. This section explains how this is achieved, but you first need to determine the resolution that the application is currently running in.

Do this by using the following code:

* Determine resolution & set DSFNTENV accordingly
           MOVE LOW-VALUES               TO P2I-Initialization-Record
           MOVE P2I-Current-Environment  TO P2I-Environment
           MOVE 0                        TO P2I-Name-Length
           MOVE Pf-Initialize            TO P2-Function
           CALL "PANELS2" USING P2-Parameter-block
                                P2I-Initialization-Record
           END-CALL
           IF  P2-Status NOT = 0
               DISPLAY "Warning: Unable to start PANELS2. Error No = "
                   P2-STATUS
               STOP RUN
           END-IF.

You should include the copyfiles pan2link.cpy, and pan2err.cpy in your program's Working-Storage section to obtain the required variables and Panels V2 interface record.

You can then test the values returned in P2I-Screen-Width and P2I-Screen-Height, and using the following code and COBOL reserved words, set the environment variable to point to the font side file section marker required.

IF P2I-Screen-width = 640
            AND P2I-Screen-Height = 480
                DISPLAY "DSFNTENV" UPON ENVIRONMENT-NAME
                DISPLAY "RESOLUTION2" UPON ENVIRONMENT-VALUE
           END-IF
           IF P2I-Screen-width = 1024
            AND P2I-Screen-Height = 768
                DISPLAY "DSFNTENV" UPON ENVIRONMENT-NAME
                DISPLAY "RESOLUTION1" UPON ENVIRONMENT-VALUE
           END-IF

This environment variable should be established before your first call to Dialog System and will remain in existence until termination of the COBOL run unit.

It is possible to refine targeted production platform resolutions further (for example, 800*600 - Large fonts) by adding the following code BEFORE the call to Panels V2:

ADD P2I-Generic-Coordinates TO P2I-Environment

This will alter the returned coordinates to be in line with the values returned by the DSRESCHK program. You then need to adjust your subsequent IF statements to reflect the supported production resolutions.

You have now implemented multiple resolution support in your screenset, enabled all screenset object fonts to be remapped at run time, and established the correct environment variable according to the current production resolution platform.

Provided the layout of your windows has been well designed, your screenset should now be fully portable across different resolutions.

15.2 Using the Dialog System Error Message File Handler

Your calling program can display error messages using the Dialog System error message file handler and its display capabilities. You might want to do this if you need to perform some complex validation that Dialog System is not designed to perform.

The error message is stored in an error message file as normal. The simplest method is to use the error message file that the screenset is using. Alternatively, you can use one or more other error message files, but you must explicitly open and close them.

To use the Dialog System error message file handler at run time, your program needs to:

This fragment of code illustrates the procedures:

 1 working-storage section.
 2 ...
 3 01  error-file-linkage.
 4     03 short-file-name       pic x(8).
 5     03 file-access           pic xx.
 6     03 filler                pic x(6).
 7     03 errhan-code           pic xx.
 8 
 9 01 error-file-data.
10     03 error-record-number   pic 9(4) comp.
11     03 error-record-contents pic x(76).
12 ...
13 procedure division.
14     ...
15     initialize ds-control-block
16     initialize data-block
17     move "N" to ds-control
18     move data-block-version-no to ds-data-block-version-no
19     move version-no to ds-version-no
20     move "custom" to ds-set-name
21     call "dsgrun" using ds-control-block
22                        data-block
23     ...
24     move "E" to ds-control
25     call "dsgrun" using ds-control-block
26                        data-block
27     ...
28     move "CUSTERR" to short-file-name
29     move "R" to file-access
30     move 101 to error-record-number
31     call "dserrhan" using error-file-linkage
32                           error-file-data
33     ...
Lines 3-11:
 01  error-file-linkage.
     03 short-file-name       pic x(8).
     03 file-access           pic xx.
     03 filler                pic x(6).
     03 errhan-code           pic xx.

 01 error-file-data.
     03 error-record-number   pic 9(4) comp.
     03 error-record-contents pic x(76).

You need to define these records in the Working-Storage Section.

Lines 15-22:
     initialize ds-control-block
     initialize data-block
     move "N" to ds-control
     move data-block-version-no to ds-data-block-version-no
     move version-no to ds-version-no
     move "custom" to ds-set-name
     call "dsgrun" using ds-control-block
                        data-block

Initial call to Dialog System.

Lines 24-26:
     move "E" to ds-control
     call "dsgrun" using ds-control-block
                        data-block

If you intend to use the error message file the screenset uses, you must make sure that it is open by calling Dialog System in the normal way, but with the parameter "E" in ds-control. Dialog System immediately returns control to the program having opened the file and replaces the parameter "C" (ds-continue) in ds-control.

ds-err-file-open is a pre-defined value for ds-control. It is defined in the Control Block as:

         05 ds-err-file-open            pic x value "E".

Thus, an alternative to line 24 is:

     move ds-err-file-open to ds-control
Line 28:
     move "custerr" to short-file-name

Moves the name of the error file (not including the extension .err) to the data item short-file-name.

Line 29:
     move "R" to file-access

"R" is for Read.

Line 30:
     move 101 to error-record-number

Moves the number of the error message you want to display.

Lines 31-32:
     call"dserrhan" using error-file-linkage
                          error-file-data

This call reads the error message file. If the call is successful, it returns with errhan-code equal to "OK" and the error message in error-record-contents. If the file is not found, the value "NF" (Not Found) is placed in errhan-code. If the file is in use or if you tried to open more than 16 files, the value "FU" (File in Use) is placed in errhan-code. You do not need to close the error file because Dialog System does this automatically.

You now need to put the error message in a data item in the Data Block so Dialog System can display it. One way to do this is to set up a procedure that displays a message box, using the data item as its argument, then call Dialog System requesting that procedure.

For example, if you have a message box named ERR-DISPLAY-MB, define a procedure with the following dialog:

  DISPLAY-ERR-MSG
    INVOKE-MESSAGE-BOX ERR-DISPLAY-MB ERR-MSG-EF $REGISTER

Then in your program, request this procedure when you return to Dialog System with a statement such as:

move "display-err-msg" to ds-procedure

where display-err-msg is the name of the procedure and ds-procedure is a data item in the Control Block. On entry to Dialog System, this procedure is executed.

15.2.1 Using an Alternative Error Message File

To use an error message file other than the one specified by your screenset, at run time your program needs to:

The only difference between using an alternative message file and the Dialog System error message file is that you must explicitly open and close the alternative file.

The following fragment of code illustrates the procedures:

 1 working-storage section.
 2 ...
 3 01  error-file-linkage.
 4     03 short-file-name       pic x(8).
 5     03 file-access           pic xx.
 6     03 filler                pic x(6).
 7     03 errhan-code           pic xx.
 8 
 9 01 error-file-data.
10     03 error-record-number   pic 9(4) comp.
11     03 error-record-contents pic x(76).
12 ...
13 procedure division.
14     ...
15     move "ALTERR" to short-file-name
16     move "NI" to file-access
17     move "C:\CUST\ALTERR.ERR" to error-file-data
18     call "dserrhan" using error-file-linkage
19                           error-file-data
20     ...
21     move "ALTERR" to short-file-name
22     move "R" to file-access
23     move 101 to error-record-number
24     call "dserrhan" using error-file-linkage
25                           error-file-data
26     ...
27     move "ALTERR" to short-file-name
28     move "NC to file-access
29     call "dserrhan" using error-file-linkage
30                           error-file-data
31     ...
Lines 3-11:
01  error-file-linkage.
     03 short-file-name       pic x(8).
     03 file-access           pic xx.
     03 filler                pic x(6).
     03 errhan-code           pic xx.

 01 error-file-data.
     03 error-record-number   pic 9(4) comp.
     03 error-record-contents pic x(76).

Again, you need to define these records in the Working-Storage Section.

Line 15:
     move "ALTERR" to short-file-name

Identifies the alternative file.

Line 16:
     move "NI" to file-access

"NI" is the file access code to open a new file .

Line 17:
     move "C:\CUST\ALTERR.ERR" to error-file-data

Specifies the path and name of the error file to be opened.

Lines 18-19:
     call "dserrhan" using error-file-linkage
                           error-file-data

Reads the error file with the call statement. If the call is successful, it returns with errhan-code equal to "OK" and the error message in error-record-contents. If the call is unsuccessful, errhan-code is "NF" for Not Found. If the file is already open or you try to open more than 16 files, errhan-code is "FU" for "File in Use".

Line 27:
     move "ALTERR" to short-file-name

Specifies the file to close.

Line 28:
     move "NC to file-access

"NC" is the close file code.

Lines 29-30:
     call "dserrhan" using error-file-linkage
                           error-file-data 

This call closes the file. errhan closes the file and returns to the program.

You now need to display the error message. Refer to the section Using the Dialog System Error Message File Handlerabove for a method to do this.

15.3 Building an Interface to a File Selection Facility

When the user needs to enter the name of a file, it is useful to provide a prompt that displays the files currently available on the system. The user can then browse around the drives and directories on his system and select an existing filename or enter the name of a new one.

For example, Dialog System uses this file selection facility when you generate a copybook for a screenset and specify the filename to use.

This section describes how to provide this facility from your Dialog System applications using the Dsdir Dialog System extension. Dialog System Extensions (DSX) is the term given to dialog functions implemented by using the CALLOUT dialog function. Dialog System extensions are supplied to enable you to perform many regular programming tasks, such as calling on-line help or providing a file selection facility. For more information about Dialog System extensions, see the topic Dialog System Extensions in the Help.

15.3.1 The Dirdemo Sample Screenset

A sample application, Dirdemo, illustrates how you can use the Dsdir Dialog System extension in your applications. You can run the application to see the facilities that are available with the Dsdir Dialog System extension.

You can run the Dirdemo sample directly from the Dialog System definition software. There is no COBOL program with this sample. Load the screenset dirdemo.gs and run it through the Screenset Animator. For information on running a screenset, see the chapter Using the Screenset. Alternatively, you can run the Dirdemo sample using Dsrunner. See the chapter Multiple Screensets for more information on Dsrunner.

The program displays two prompts:

To use the file selection facility window select one of the options on the pulldown menu:

Open Select a file to be opened. The user can select only a file that already exists.
Save Select a file to be saved. The user can select any file that already exists (or supply the name of a new file).
Check Check whether or not the file entered in the filename field actually exists. When this function is selected, wildcard characters are not accepted in the filename field.
Exit Exit.

None of the options in this menu actually opens a file. Once the user has selected a file, you can decide which function to use.

15.3.2 The Dirdemo Data Block

To call the Dsdir Dialog System extension, you must define the following in the screenset's Data Block, in addition to any other data that the screenset uses:

DSDIR-PARAMS                        1
    DSDIR-FUNCTION                 X    4.0
    DSDIR-RETURN-CODE              C    2.0
    DSDIR-FILENAME                 X  256.0

To set your own title for the file selector window, you also need to add the following to the screenset's Data Block:

DSDIR-PARAMS2
    DSDIR-TITLE                    X  256.0

These fields are described in the section about the Dsdir Dialog System extension in the topic Dialog System Extensions in the Help.

15.3.3 The Dirdemo Dialog

The Dirdemo sample calls the Dsdir Dialog System extension whenever a file is required to be selected.

The dialog (attached to the main window) to do this is:

1     DO-DSDIR-CALL
2       CLEAR-CALLOUT-PARAMETERS $NULL
3       CALLOUT-PARAMETER 1 DSDIR-PARAMS $NULL
4       CALLOUT-PARAMETER 2 DSDIR-PARAMS2 $NULL
5       CALLOUT "Dsdir" 0 $PARMLIST
6 ...
17    @OPEN-PD
18      MOVE "open" DSDIR-FUNCTION(1)
19      EXECUTE-PROCEDURE DO-DSDIR-CALL
20    @SAVE-PD
21      MOVE "save" DSDIR-FUNCTION(1)
22      EXECUTE-PROCEDURE DO-DSDIR-CALL
23    @CHECK-PD
24      MOVE "chek" DSDIR-FUNCTION(1)
25      EXECUTE-PROCEDURE DO-DSDIR-CALL
Line 1:
    DO-DSDIR-CALL

This procedure makes the call to the Dsdir Dialog System extension.

Lines 2-4:
      CLEAR-CALLOUT-PARAMETERS $NULL
      CALLOUT-PARAMETER 1 DSDIR-PARAMS $NULL
      CALLOUT-PARAMETER 2 DSDIR-PARAMS2 $NULL

Defines the parameters required for the CALLOUT. Because more than one parameter is required when the file selector window title is specified, all the parameters must be defined before you make the CALLOUT. The CLEAR-CALLOUT-PARAMETERS function is used to ensure that any previously defined parameters are removed before the new parameters are defined.

Line 5:
     CALLOUT "Dsdir" 0 $PARMLIST

This line calls the Dialog System extension using the previously defined parameters. The file selector window is displayed, and the user can select a file. When the user has selected a file, or cancelled the file selection, control is returned to your screenset.

Line 17:
    @OPEN-PD

The user selected the Open option on the pulldown menu.

Line 18:
      MOVE "open" DSDIR-FUNCTION(1)

This line sets up the parameter that tells the Dialog System extension to allow the user to select a file to open. In this mode, the user can only select files that already exist.

Line 19:
      EXECUTE-PROCEDURE DO-DSDIR-CALL

Carries out the procedure that calls the Dialog System extension.

Lines 20-22:
    @SAVE-PD
      MOVE "save" DSDIR-FUNCTION(1)
      EXECUTE-PROCEDURE DO-DSDIR-CALL

The user selected the Save option on the pulldown menu. In save mode, the user can select any file, or specify the name of a new file.

Lines 23-25:
    @CHECK-PD
      MOVE "chek" DSDIR-FUNCTION(1)
      EXECUTE-PROCEDURE DO-DSDIR-CALL

The user selected the Check option on the pulldown menu. The chek function requests the Dialog System extension to check for the existence of the supplied filename. The file selector window is not displayed.

15.4 Modifying Menu Items at Run Time

As well as defining menu items at definition time, you can define dialog to add, delete, or change menu items at run time. For example, you can add a list of recently opened files to your menu, or a list of open windows in a Multiple Document Interface (MDI) application.

All the options for defining a menu bar at definition time can also be used at run time, except that you can only add new items to an existing menu bar, and you cannot add menu choices to context menus.

You add menu choices to a menu bar using the ADD-MENU-CHOICE dialog function. One of the parameters for this function is a text string that specifies all the options for the menu item. The following example shows all the options specified in their correct places, although in practice, you should never define a menu item like this:

GET-MENU-CHOICE-REFERENCE MAINWIN EDITMENU PARENT-REF
ADD-MENU-CHOICE PARENT-REF "~item>" $EVENT-DATA
GET-MENU-CHOICE-REFERENCE MAINWIN $EVENT-DATA PARENT-REF
ADD-MENU-CHOICE PARENT-REF "*~choice@item&ctrl+c" $EVENT-DATA

Where:

PARENT-REF This parameter specifies which menu (or sub-menu) this new item will be added to. The value of this parameter must be obtained using the GET-MENU-CHOICE-REFERENCE function. The value can never be zero.
* The asterisk causes the menu item to be created with the checkmark type set to off (the default is none). The asterisk must appear as the first character of the text parameter, otherwise it will be assumed to be part of the menu text. If you intend the asterisk to be part of the menu text, add a space before it.
~ The tilde causes the next character to be defined as the mnemonic character for the menu choice. You are not warned if you define menu choices with duplicate mnemonic characters (unlike when defining a menu choice at definition time). The tilde character can appear anywhere in the choice text.
> The greater than symbol, if it appears as the last character of the text parameter, signifies that when the menu item is selected, a submenu of choices is to be displayed. If you specify that a menu choice is to display a submenu, the checkmark state and shortcut key settings are ignored.
choice The text up to the @ (at) defines the text that is displayed in the menu bar (the choice text).
@item The '@' signifies that the next text (up to the next @, space, & or >) is the name of the menu item. Normal Dialog System object naming rules apply to the menu item name. If there is a procedure defined in the screenset with the same name as the menu item, selecting the menu item causes the procedure with that name to be executed. The menu item name is optional.
&ctrl+c The ampersand signifies that the next text (up to the next @, space, & or >) is the shortcut key for the menu item. You can specify the shortcut key either in the format you use when you define a menu choice in menu bar definition (such as CTC), or in the format that the shortcut key will be displayed on screen (for example, Ctrl+C).

When you create a menu bar item using this function, the ID of the created menu bar item is returned. You can then use this ID with functions such as DISABLE-MENU-CHOICE to manipulate the menu item further.

You can delete menu items using the DELETE-MENU-CHOICE function. The items that you delete can be menu items defined in menu bar definition, or menu items added using the ADD-MENU-CHOICE function.

Also, you can update the text of menu items by using the UPDATE-MENU-TEXT function.

See the relevant functions in the Help for more details, including examples of using the functions.

15.5 Using the Call Interface

The Dialog System call interface can be used by your calling program to provide more sophisticated ways of using Dialog System. For example:

Using these features, you can divide your user interface into logical components that are used as required, use multiple copies of the same screenset, and group all your error messages into a single file. See the chapter Using the Screenset for details.

15.6 Adding Help

This section discusses the Helpdemo screenset in detail. The Helpdemo screenset:

You might want to run the screenset while you read this section.

15.6.1 Running the Helpdemo Sample

You can run the Helpdemo sample directly from the Dialog System definition software. There is no COBOL program with this sample.

Load the screenset helpdemo.gs and run it through the Screenset Animator.

For information on running a screenset, see the section Testing the Screenset in the chapter Using the Screenset.

Alternatively, you can run the Helpdemo sample using Dsrunner. See the chapter Multiple Screensets for more information on Dsrunner.

15.6.2 The Helpdemo Data Block

To call the Dsonline Dialog System extension, you must define the following in the screenset's Data Block, in addition to any other data that the screenset uses:

DSONLINE-PARAMETER-BLOCK            1
    DSONLINE-FUNCTION             X    18.0
    DSONLINE-RETURN               C    2.0
    DSONLINE-HELP-FLAGS           C    2.0
    DSONLINE-HELP-CONTEXT         9    18.0
    DSONLINE-HELP-TOPIC           X   32.0
    DSONLINE-HELP-FILE            X  256.0

The meaning of each of these fields is given in the description of the Dsonline Dialog System extension in the topic Dialog System Extensions in the Help.

15.6.3 The Helpdemo Dialog

The Helpdemo sample calls the Dsonline Dialog System extension whenever help information is required. Help might be required for a particular field, or when the user selects an option on the Help menu.

The dialog (attached to the main window) to do this is:

1  F1
2      MOVE 1 DSONLINE-HELP-CONTEXT(1)
3      BRANCH-TO-PROCEDURE CONTEXT-HELP
4    @HELP-CONTENTS
5      MOVE "cont" DSONLINE-FUNCTION(1)
6      BRANCH-TO-PROCEDURE CALL-ON-LINE
7    @HELP-INDEX
8      MOVE "indx" DSONLINE-FUNCTION(1)
9      BRANCH-TO-PROCEDURE CALL-ON-LINE
10    @EXIT-F3
11      SET-EXIT-FLAG
12      RETC
13    CONTEXT-HELP
14      MOVE "ctxt" DSONLINE-FUNCTION(1)
15      BRANCH-TO-PROCEDURE CALL-ON-LINE
16    CALL-ON-LINE
17      MOVE "helpdemo.hlp" DSONLINE-HELP-FILE(1)
18      MOVE 0 DSONLINE-HELP-FLAGS(1)
19      CALLOUT "dsonline" 0 DSONLINE-PARAMETER-BLOCK
Line 1:
F1

The user pressed the F1 key. Every entry field in this example has individual control dialog for the event caused by the F1 key, so if this dialog processes the event, it means that the focus is not on one of the entry fields. When this event is processed, general help is provided.

Line 2:
    MOVE 1 DSONLINE-HELP-CONTEXT(1)

Set the context number to be displayed. The context numbers are defined in the On-line help file. If you do not specify context numbers, the On-line help file builder (ohbld) provides them for you. In this example, 1 is the context number for general help.

Line 3:
    BRANCH-TO-PROCEDURE CONTEXT-HELP

Branches to the procedure that displays the help. Because all context help is displayed in the same way, a procedure is used, to avoid repeating dialog.

Line 4:
  @HELP-CONTENTS

The user selected Contents on the Help menu.

Line 5:
    MOVE "cont" DSONLINE-FUNCTION(1)

The Dsonline Dialog System extension can do several different things. To tell it what to do, you must provide it with a function name (a four character string). The cont function requests that the contents of the On-line help file are displayed.

Line 6:
    BRANCH-TO-PROCEDURE CALL-ON-LINE

Branches to the procedure that calls the Dialog System extension.

Lines 7-9:
  @HELP-INDEX
    MOVE "indx" DSONLINE-FUNCTION(1)
    BRANCH-TO-PROCEDURE CALL-ON-LINE

The user selected Index on the Help menu. The indx function requests that the index for the On-line help file be displayed.

Line 10:
  @EXIT-F3

The user selected Exit on the File menu, or pressed the F3 key.

Line 11:
    SET-EXIT-FLAG

The exit flag is a flag that Dsgrun returns to the calling program when a RETC is executed. The exit flag tells Dsrunner that the screenset has finished processing.

Line 12:
    RETC

Return to the calling program (in this example, either Dialog System or Dsrunner).

Lines 13-15:
  CONTEXT-HELP
    MOVE "ctxt" DSONLINE-FUNCTION(1)
    BRANCH-TO-PROCEDURE CALL-ON-LINE

This procedure is used to display context help. The ctxt function requests that context-sensitive help be displayed. The CALL-ON-LINE procedure is used to call the Dialog System extension.

Lines 16-19:
  CALL-ON-LINE
    MOVE "helpdemo.hlp" DSONLINE-HELP-FILE(1)
    MOVE 0 DSONLINE-HELP-FLAGS(1)
    CALLOUT "dsonline" 0 DSONLINE-PARAMETER-BLOCK

This procedure calls the Dsonline Dialog System extension. It sets up the name of the help file in the parameter block, and turns off all the flag settings for the On-line Help system (see the Dsonline Dialog System extension in the topic Dialog System Extensions in the Help for information about the flags).

15.6.4 Entry Field Dialog

As well as the dialog on the main window, each entry field in the window has dialog. Each entry field sets a different context number, but otherwise, the dialog is the same.

For the Product Code entry field, the dialog is:

1  F1
2      MOVE 2 DSONLINE-HELP-CONTEXT(1)
3      BRANCH-TO-PROCEDURE CONTEXT-HELP

This dialog is similar to that for the F1 key on the main window, but uses a different context number, where 2 is the context number for help about this entry field.

15.7 Further Information

See the chapters Using the Screenset and Multiple Screensets for further information about controlling the use of screensets and using multiple screensets and multiple instances of screensets.

The chapter Multiple Screensets also contains a detailed description of the call interface. The topic The Call Interface in the Help also provides information on the Control Block, including the Event Block, the Data Block, use of the Screenset Animator, version checking, and the values the calling program returns to Dialog System.


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

PreviousUsing the Client/Server Binding Questions and AnswersNext