PreviousGenerating the Copyfile LinkingNext"

Chapter 12: Programming

The eighth step in developing your Dialog System application is to write a calling program. Dialog System has several advanced features that enable you to create more sophisticated programs. It is recommended that you do not try these advanced features until you are thoroughly familiar with the basic features of Dialog System.

This chapter explains:

12.1 Calling Dialog System

The screenset runs using a simple call interface between your program and the Dialog System Run-time System and uses the Data Block you created and a control block provided with the system. The call statement for this interface passes two parameters:

call "DSRUN" using DS-CONTROL-BLOCK,
                   screenset-DATA-BLOCK.

where:

screenset is the name of the screenset to run. The run-time system searches for the screenset either in the current directory, or in the directory specified by the P option (see the section Run time Path Name Support later in this chapter), then finally in the directories specified by the environment variable COBDIR, in order.

The contents and values of the control block and Data Block are described in the chapters Running the Screenset and Generating the Copyfile.

12.2 Using Multiple Screensets from One Program

Occasionally, you might wish one program to use two or more screensets. If these screensets occur successively in the program, each one can be called by setting the Ds-Control field in the control block to a value of "N" (start running new screenset). The previous screenset is canceled.

However, to start a new screenset and, on completion, return to the point from which you left the original screenset, you must use the facilities to POP and PUSH screensets. To do this, you set the following values in the Ds-Control field:

Q quit screenset (78 Ds-Quit-Set). This quits running the current screenset and pops to the last screenset pushed. If there is no screenset pushed, the current screenset simply unloads itself.
S push screenset (78 Ds-Push-Set). This pushes the current screenset onto a stack and starts the new one.
U use screenset (78 Ds-Use-Set). This causes the current screenset to be swapped with the named screenset on the push stack. Execution then continues as if 'C' had been issued. This feature is supported for Micro Focus Panels screensets only. If there is no named screenset on the stack, an error 4 (invalid screenset) is returned in DS-SYSTEM-ERROR-NO.
W what screenset (78 Ds-What-Set). This tells the application the name of the current screenset. This is returned in DS-SET-NAME.

To start a new screenset (screenset number two), and push the current screenset (screenset number one), you must place a value of "S" rather than "N" in the Ds-Control field for the new screenset.

To keep the current screen visible (screenset number one), you must also set the Ds-Control-Param field to a value of one to override the default. (The default setting clears the current screen before a new screenset is started.)

To terminate the second screenset, there must be a call to Dsrun placing a value of "Q" in the Ds-Control field. This call quits screenset number two and pops back to screenset number one.

When you use these facilities, remember the following points:

12.3 Using Error Files Directly from Your Program

There might be situations where you wish to use the Dialog System error file directly from your program (see the chapter Data Definition for details on setting up the error file). For example, if you have a complex validation that Dialog System cannot perform, the input must be validated by your program. Normally, your program must also deal with the use of any associated error messages. However, Dialog System enables you to hold these error messages in its own error message file.

Also, Dialog System enables you to access multiple error files from other sources via the calling program. You can access up to 15 files not defined in Dialog System without using the run-time system. Because this facility is used from the calling program, it does not affect the normal error message handling inside the Dialog System Run-time System, which continues to use the error message file created during dialog definition.

When you specify an error message file, the run-time system searches for the file in the current directory, then in any directory specified by the P option (see the section Run time Path Name Support later in this chapter), then finally in the directories specified by the environment variable COBDIR, in order.

12.3.1 The Dialog System Error File

To access this error file from the program, ensure that the error file is open, then read the required error message. You do not need a call to close this error file because the run-time system closes all files when the screenset is terminated.

The error file is often already open because of earlier errors in user input. However, to ensure that it is open, you can set the value in the Ds-Control field of the control block immediately following the call to start a new screenset ("N").

Use the following value:

E open error file (78 Ds-Err-File-Open). This opens the error file for use by the run-time system.

This "E" call does no harm if the file is already open.

If you have pushed a screenset (Ds-Control set to "S"), its associated error file is closed. When you pop the screenset (Ds-Control set to "Q"), make a new call to Dsrun with Ds-Control set to "E" to reopen the error file.

To read the error file, use the following COBOL call:

call "DSERRHAN" using ERROR-FILE-LINKAGE
                      ERROR-FILE-DATA

where ERROR-FILE-LINKAGE and ERROR-FILE-DATA are:

 01 ERROR-FILE-LINKAGE.
     03 SHORT-FILE-NAME          PIC X(8).
     03 FILE-ACCESS              PIC XX.
     03 FILLER                   PIC X(6).
     03 E-RETURN-CODE            PIC XX.

 01 ERROR-FILE-DATA.
     03 ERROR-RECORD-NUMBER      PIC 9(4) COMP.
     03 ERROR-RECORD-CONTENTS    PIC X(76).

For example, to find the contents of error message number 135 in an error file called customer.err,place the following values in ERROR-FILE-LINKAGE and ERROR-FILE-DATA.

SHORT-FILE-NAME "CUSTOMER"
FILE-ACCESS     "R"  {read}
ERROR-RECORD-NUMBER     "135"

If record 135 is not found, the return value is:

E-RETURN-CODE   "NF"

If record 135 is found, the return value is:

E-RETURN-CODE   "OK"

and the text of the error record is contained in:

ERROR-RECORD-CONTENTS

12.3.2 Alternative Error Files

To access other error files from your application program, you can make direct calls to the Dserrhan file provided with the Dialog System software. This facility enables you to open, read and close other files.

The following example shows how you can use the Dserrhan file to open an alternative error file.

For an error file called cust1.err, in a directory c:\files\errors, you must set up the following values:

SHORT-FILE-NAME "CUST1"
FILE-ACCESS     "NI"
ERROR-FILE-DATA "C:\FILES\ERRORS\CUST1.ERR"

The call to Dserrhan is:

call "DSERRHAN" using ERROR-FILE-LINKAGE
                 ERROR-FILE-DATA

To read alternative error files, use exactly the same COBOL call as you do for the Dialog System error file:

call "DSERRHAN" using ERROR-FILE-LINKAGE
                ERROR-FILE-DATA

However, unlike the Dialog System error file, you must close the alternative error file. To close the file, you must make a call to Dserrhan using the following values:

SHORT-FILE-NAME "CUST1"
FILE-ACCESS     "NC"

12.4 User Validation in Screensets

If you want to use user-validation on your screensets, you must write a module called DSUSRVAL. Micro Focus ships a skeleton source of this module, containing comments to help you add your own code.

The Dialog System Run-time System calls Dsusrval when you are about to exit a field.

The parameters passed to the routine are:

Dialog Control Block input Use this to determine the current screenset, panel and field. Any changes you make to this Control Block are ignored by Dialog System.
Screenset Data Block input/output You can access and change any fields for the current screenset in this Data Block.
DS-User-Val-Status output If you want to flag a field validation failure, set this flag to 1. If validation is OK, set this field to 0.
DS-User-Error-Number output This field is ignored unless DS-User-Val-Status is non-zero. When a field validation error has occurred, if this field is set to 0, the error message associated with this validation will be displayed. You can force a different error message to be displayed by placing its number in this field.

12.5 Control of User-defined Field Formats

Dialog System provides a number of screen field formats, which depend on the original definition of the field. For example, input to a numeric field can be zero suppressed or signed. The formats provided are sufficient for most applications. However, you can configure the field formats for any input or output fields. To do this, you must write your own program, and call it DSUSRFMT.

The Dialog System Run-time System calls Dsusrfmt after every keystroke in the field. The field Ds-User-Format-Number is set to the value (in the range 1 to 4) that you associate with the field in the Panel Field menu. You must provide the correct behavior for the field for any access; however, you do not always need to define the behavior completely because you can instruct Dialog System to format the field according to its underlying main format. Your Dsusrfmt program must never make any screen input or output.

The Dialog System software includes an example user format program called dsusrfmt.cbl, together with a screenset called dsusrfmt.s that uses it. To use this program, compile it and place it in the same directory as the screenset.

To call DSUSRFMT:

call 'DSUSRFMT' using Ds-User-Linkage
                      Ds-Field-Buffer.  

You must write Dsusrfmt with a Linkage Section containing the following items:

  1. A control block. See the section Control Block for dsusrfmt for a description of its contents.

  2. A field buffer containing the current contents of the field, with a decimal point if necessary. The size of the buffer, which varies depending on the size of the field, is specified in one of the control block fields (03 Ds-Buffer-Length). The buffer size can be larger than the size of the field on the panel; however, the user format routine must not access any data item larger than the current size of the field because if it does, undefined errors can occur. When you access this buffer, it is advisable to use reference modification.

  3. The Data Block generated for the screenset that Dsusrfmt uses.

12.5.1 Control Block for Dsusrfmt

The contents of the control block are:

 01 Ds-User-Linkage.
    03 Ds-Access-Flag                   pic x.
    03 Ds-Screenset-Name                pic x(8).
    03 Ds-Panel-Name                    pic x(8).
    03 Ds-Field-Name                    pic x(8).
    03 Ds-Field-Offset                  pic 9(4) comp-x.
    03 Ds-Field-Screen-Length           pic 9(4) comp-x.
    03 Ds-Master-Forma                  pic 9(2) comp-x.
    03 Ds-Screen-Forma                  pic 9(2) comp-x.
    03 Ds-Screen-Subforma               pic 9(2) comp-x.
    03 Ds-User-Format-Number            pic 9(2) comp-x.
    03 Ds-Length                        pic 9(4) comp-x.
    03 Ds-Decimal-Length                pic 9(2) comp-x.
    03 Ds-Sign                      pic 9(2) comp-x.
    03 Ds-Buffer-Length             pic 9(4) comp-x.
    03 Ds-Shift-State                   pic 9(2) comp.
    03 Ds-Lock-State                    pic 9(2) comp-x.
    03 Ds-Cursor-Position               pic 9(2) comp-x.
    03 Ds-Sign-Value                    pic 9(2) comp-x.
    03 Ds-Buffer-Screen-Offset          pic 9(4) comp-x.
    03 Ds-Flags.
        05 Ds-Display-Field-Flag        pic 9(2) comp-x.
        05 Ds-Display-Cursor-Flag       pic 9(2) comp-x.
        05 Ds-Autoskip-Left         pic 9(2) comp-x.
        05 Ds-Autoskip-Right            pic 9(2) comp-x.
        05 Ds-Do-Internal-Formatting    pic 9(2) comp-x.
    03 Ds-Input-Key.
        05 Ds-Key-Type              pic 9(2) comp-x.
        05 Ds-Key-Description           pic 9(2) comp-x.
        05 Ds-Key-Description-X redefines
             Ds-Key-Description     pic X.
        05 filler                       pic 9(2) comp-x.
    03 filler                           pic x(10).
    03 Ds-Field-Long-Name                pic x(30).

The field buffer is declared as follows:

01 Ds-Field-Buffer.
    03 Field-Buffer-Comp                pic 9(2) comp occurs 9999.

The Dialog System software also includes a copyfile, ds-user.cpy, which contains this control block. This copyfile contains the most recent format and naming of the Dsusrfmt control block, with appropriate descriptions. Another copyfile, ds-key.cpy, contains the constants that you require.

If the user presses a function key combination that generates a multi-byte scan code that Dialog System does not recognize, for example Ctrl+Del or Ctrl+Ins, an error code is returned. This is a general error code and is not specific to any key.

The control block is split into two parts; one contains fields that provide information to the user format module, and the other contains fields that provide information and control the subsequent behavior of the Dialog System Run-time System.

The following are the parameter values that Dialog System passes to the Dsusrfmt control block to provide information to the user format module:

Ds-Access-Flag A one-character flag that denotes the current stage of processing of a field so that Dsusrfmt can take the appropriate action. This flag is passed at four points during processing according to the following settings:
  L when the screenset is initialized (DS-LOAD-ACCESS).
  I when a field is set to its default state, for example, when the panel fields are refreshed during an RFTD or a POP function, or before the first keystroke is pressed when moving onto a field for input (DS-INITIALIZE-FIELD).
  C after each keystroke during input on the field (DS-NORMAL-ACCESS).
  T when the field is completed, for example, if a key with dialog has been pressed or the user format routine has requested a move to another field (DS-TERMINATE-FIELD).
Ds-Screenset-Name
  The name of the screenset currently in use.
Ds-Panel-Name The name of the currently active panel. This enables you to specify different input behavior for different panels.
Ds-Field-Name The field name if the name does not exceed eight characters. If the name exceeds eight characters, the field contains an indicator `@' in the first character position and binary data in the rest of the field. The field name is also contained in the field Ds-Field-Long-Name.
Ds-Field-Offset A number in the range 0 to 1999 specifying the offset on the panel on which the current field is positioned. This might be useful if the same field occurs more than once on the current panel and you wish the different versions to behave differently.
Ds-Field-Screen-Length
  The length of the field on the panel, not including the sign if present. This can be shorter than the buffer length.
Ds-Master-Format
  The underlying master field format for the current field. This can have the following values:
  1
2
3
4
19
20
35
51
52
67
68
alphanumeric
alphabetic
numeric
signed-numeric
COMP
signed COMP
COMP-X
COMP-3
signed COMP-3
COMP-5
signed COMP-5
Ds-Screen-Format
  The format of the current field on the panel.
This can have the following values:
  0
50
100
150
date
numeric
alphabetic
alphanumeric
Ds-Screen-Subformat
  Specifies any subformats applicable to some screen formats, such as date and numeric fields. For a date field, the following formats are valid:
  1
2
3
4
5
XX-XX-XX
XX-XXX-XX
XX-XXX
XX-XX
XX-XX-XXXX
  For a numeric field, the following formats are valid:
  0
2
not zero suppressed (the default)
zero suppressed
Ds-User-Format-Number
  A number in the range 1 to 4 specifying the user format number of the current field.
Ds-Length The length of alphabetic and alphanumeric fields or the length of the integer part of a numeric field.
Ds-Decimal-Length
  The length of the decimal part of a numeric field, not including the decimal point. For non-numeric fields, this is zero.
Ds-Sign Indicates whether or not there is a sign with this field on the panel, according to the following settings:
  1
2
sign present
no sign present
Ds-Buffer-Length
  The length of the formatted buffer passed from Dialog System to the user format routine.
Ds-Shift-State The state of the shift keys (Alt, Ctrl, Left Shift and Right Shift) after they have been enabled. The state is given by a byte according to the following bit settings:
  bit 0
bit 1
bit 2
bit 3
bits 4-7
Right Shift
Left Shift
Control
Alternate
Not used
Ds-Lock-State The state of the lock keys (Insert, Caps, Number (DOS only) and Scroll Locks) after they have been pressed. The state is given by a byte according to the following bit settings:
  bit 0
bit 1
bit 2
bit 3
bits 4-7
Scroll Lock
Num Lock (DOS only)
Caps lock
Insert lock
Not used
Ds-Input-Key Two fields that identify the key that has just been pressed. The Ds-Key-Type field identifies the type of key that has been pressed, and the Ds-Key-Description field identifies the exact key pressed, according to the values given in the following tables.

For data keys, the key description is the ASCII code of the key pressed, except for those codes given in the second table (type 51) and Ctrl+h, Ctrl+i, and Ctrl+m. These three keys return function codes for <right-arrow>|, Backspace, and Enter, respectively.

These key values, which are used by the run-time system, are in the file ds-key.cpy, provided with the Dialog System software. If your keyboard does not have the keys shown below, please consult your Release Notes to see which keys on the standard keyboard for your system provide the equivalent functions.




  Type 49 Function-Key
  1-9
0
91
92
F1–F9
F10
F11
F12
  61
62
13-19
20
93
94
Shift+F1
Shift+F2
Shift+F3–Shift+F9
Shift+F10
Shift+F11
Shift+F12
  21-29
30
95
96
Ctrl+F1–Ctrl+F9
Ctrl+F10
Ctrl+F11
Ctrl+F12
  31-39
40
97
98
Alt+F1–Alt+F9
Alt+F10
Alt+F11
Alt+F12
  41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
60
65
Enter
<left-arrow>
<right-arrow>
<up-arrow>
<down-arrow>
Home
<right-arrow>|
|<left-arrow>
Backspace
End
Page Up
Page Down
Ctrl+Home
Ctrl+End
Ctrl+Page Up
Ctrl+Page Down
Ctrl+ <left-arrow>
Ctrl+<right-arrow>
Delete
Escape
  Type 49 Function-Key
  71-79
80

81
82

101-102
Alt+1–Alt+9
Alt+0

Alt+Minus
Alt+Equals

Alt+a–Alt+z
  Type 51 Data Key
  1-7
10
11

12
14-26
Ctrl+a–Ctrl+g
Ctrl+j
Ctrl+k

Ctrl+l
Ctrl+n–Ctrl+z
  Type 53 Shift Key
  0
1
2
3
4
5
6
7
Alt Key On
Alt Key Off
Ctrl Key On
Ctrl Key Off
Left Shift Key On
Left Shift Key Off
Right Shift Key On
Right Shift Key Off
  Type 54 Lock Key
  16
17
18
19
32
33
34
35
Insert On
Caps Lock On
Num Lock On
Scroll Lock On
Ins Off
Caps Lock Off
Num Lock Off
Scroll Lock Off

The following are the parameter values that Dialog System passes to the Dsusrfmt control block to provide information, and control the subsequent behavior of the Dialog System Run-time System.

Ds-Cursor-Position The current position of the cursor in the field on the panel starting from position one. It should not exceed the value of Ds-Field-Screen-Length; otherwise, the cursor can appear outside the current field.
Ds-Sign-Value Indicates the current value of the sign of numeric fields, according to the following settings:
  0
1
negative
positive
Ds-Buffer-Screen-Offset
  The offset of the first character in the field buffer that is shown in position one of the current field on the panel. This offset starts from position one.
Ds-Display-Field-Flag
  A flag that determines whether the field is redisplayed on the panel. For example, key "A" is given as a value 51 in Ds-Key-Type and 65 in Ds-Key-Description, but it is not in the buffer. If the user presses key "A", it does not appear on the panel unless you place it in the appropriate place in Ds-Field-Buffer and set the Ds-Display-Field-Flag to true.
Ds-Display-Cursor-Flag
  A flag that determines whether the cursor is displayed when control returns to the run-time software. This is usually required if the user format routine has moved the cursor to a new position.
Ds-Autoskip-Left A flag that makes Dialog System return control to the previous input field. Only effective if DS-Do-Internal Formatting is set to 0. This parameter setting may be used when DS-Access-Flag is "I" or "C".
Ds-Autoskip-Right A flag that makes Dialog System move control to the next input field. Only effective if DS-Do-Internal Formatting is set to 0. This parameter setting may be used when DS-Access-Flag is "I" or "C".
Ds-Do-Internal-Formatting
  A flag that determines whether Dialog System performs its own formatting routines according to the screen format of the current field, according to the following settings. This enables the user format routine to slightly modify the input behavior of a field without providing all of the field handling code.
  0 do nothing
  1 perform the internal formatting. This is the default Dialog System sets after each keystroke.
Ds-Input-Key Two fields that identify the key that has just been pressed. The Ds-Key-Type field identifies the type of key that has been pressed, and the Ds-Key-Description field identifies the exact key pressed, according to the values given in the tables in the description of the Ds-Input-key in the section Control of User-defined Field Formats. This field can be changed to return to Dialog System a different key value than normally given by the key actually pressed.
Ds-Field-Long-Name
  A 30-character field name, containing the name of the current field.

12.5.2 Optionally Passing Data Block to DSUSRFMT

If the directive DATABLOCK-DSUSRFMT is present in the run-time configuration file dsdef.cfg then, whenever Dialog System calls the user-coded DSUSRFMT program, an additional parameter (the third parameter), which is the user data block, is passed across. The call to DSUSRFMT is thus:

call 'DSUSRFMT' using Ds-User-Linkage
                      Ds-Field-Buffer
                      User-Data-Block  

where User-Data-Block has the same format as the user-data-block passed from the application to DSRUN. See the section Calling Dialog System for more details.

You should ensure that your program does not access beyond the boundary of this parameter. The ability to access the data block enables the content of other fields in the data block to influence the behavior of your program.

For example, your program could control unlimited field protection. In this case, user data fields are used as flags to indicate whether associated fields should be treated as protected or not (in the same way as built-in field protection works). The user code in DSUSRFMT checks the corresponding flag on initial field entry, and if set to protect, then the autoskip flag is set to cause the field to be skipped. This method is not bound by the limits on the number of flags and fields per panel which are supported, as is the built-in protection mechanism.

12.6 User Control of Every Keystroke

Dialog System enables you to write a program that can intercept every keystroke and modify its value to any other key value you wish. If you write such a program, you must call it Dsusrtrn.

To use this program, you must set the F4=key-translation-off/on switch from the Screenset Switches menu in the Main Alt menu. When you set this switch on, the Dialog System Run-time System calls the Dsusrtrn program for every keystroke. You can then use this program to change values of keystrokes. Your Dsusrtrn program must never make any screen input or output. See the section Screenset Switches (F5) in the chapter Using Dialog System.

If you use both this program and the Dsusrfmt program described in the previous section, the order you call them is Dsusrtrn followed by Dsusrfmt.

You must write Dsusrtrn with the Linkage Section, ds-tran.cpy, given below. The ds-key.cpy file provided with the Dialog System software contains the constants that you require for this program. The Dialog System Run-time System sends certain values in the Linkage Section, while you can change certain others of these values to affect the keystroke.

The contents of the ds-tran.cpy file are:

**********************************************************
* Interface to called user-defined key translation module
**********************************************************

 01 ds-tran-linkage.
    03 t-access-flag          pic x.
      78 t-load-access          value "L".
      78 t-normal-access        value "C".
    03 t-input-key.
       05 t-key-type          pic 9(2) comp.
       05 t-key-description   pic 9(2) comp.
       05 filler              pic 9(2) comp.
    03 filler                 pic x(10).

The Dialog System Run-time System sends the following parameter values to Dsusrtrn:

T-Access-Flag A single-character flag that denotes the current stage of processing of a field so that the Dsusrtrn program can take the appropriate action. This flag has the following settings:
  L when the screenset is initialized. This flag is automatically set to "L" on the "N" call to Dsrun, so the first call to Dsusrtrn has a value "L" in this field.
  C while the screenset is running. Any calls after the screenset is initialized have a value "C" in this field.
T-Input-Key Two fields that identify the key that has just been pressed. The Ds-Key-Type field identifies the type of key that has been pressed, and the Ds-Key-Description field identifies the exact key pressed, according to the values given in the tables in the description of the Ds-Input-Key in the section Control of User-Defined Field Formats. You can alter these keys in your program to change the value of any key that is pressed.

12.7 Obtaining System Information from Dialog System

You can determine what was the last key pressed and where the cursor is currently positioned in the application program by specifying a third parameter on the call to Dsrun. The format of this parameter is:

 01 Ds-Third-Param.
    03 Last-Key-Pressed
       05 Key-Type-Hex     pic x.
       05 Key-Type-Decimal redefines Key-Type-Hex
                           pic 9(2) comp
       05 Actual-Key-Hex   pic x.
       05 Actual-Key-Decimal redefines Actual-Key-Hex
                           pic 9(2) comp.
    03 Cursor-Position.
       05 Cursor-Row       pic 9(2) comp.
       05 Cursor-Column    pic 9(2) comp.

The following parameter values are returned by this call:

Last-Key-Pressed The key code for the last key pressed (see the description of the Ds-Input-Key in the section Control of User-defined Field Formats for key code tables).
Cursor-Position The position of the cursor relative to the screen. This is only set if there is currently field input on the active panel.

12.8 Run-time Path Name Support

You can instruct the Dialog System Run-time System to look outside the current directory for screensets and error files by prepending the desired path to a filename. You specify this current path with a second parameter in the call to Dsrun:

 01 Current-Path PIC X(52).

You must then call Dsrun with the following value in the Ds-Control field of the control block:

P Indicate path name. This specifies the name of the path to be followed (78 Ds-Pathname). A pathname of spaces causes the search to reset to the current directory.

This call to set the current path to a named location instead of the current directory in the run-time software can be made at any time. If a screenset or error message file is not found in the current directory or the directory specified by the P option, Dialog System searches the directories specified by the environment variable $COBDIR, in order.

12.9 Compiling Dialog System Applications

When you are compiling a Dialog System application, there is a restriction:


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

PreviousGenerating the Copyfile LinkingNext"