Generating the Copyfile | Linking |
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:
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.
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:
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.
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 be 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
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"
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"
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. |
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.
You must write Dsusrfmt with a Linkage Section containing the following items:
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 (Windows 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 (Windows 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 |
F1F9 F10 F11 F12 |
|
61 62 13-19 20 93 94 |
Shift+F1 Shift+F2 Shift+F3Shift+F9 Shift+F10 Shift+F11 Shift+F12 |
|
21-29 30 95 96 |
Ctrl+F1Ctrl+F9 Ctrl+F10 Ctrl+F11 Ctrl+F12 |
|
31-39 40 97 98 |
Alt+F1Alt+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+1Alt+9 Alt+0 Alt+Minus Alt+Equals Alt+aAlt+z |
|
Type 51 | Data Key | |
1-7 10 11 12 14-26 |
Ctrl+aCtrl+g Ctrl+j Ctrl+k Ctrl+l Ctrl+nCtrl+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. |
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. |
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. |
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.
When you are compiling a Dialog System application, there is a restriction:
Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Generating the Copyfile | Linking |