Generating the Copyfile

Linking

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:

• How to call Dialog System from your application program

• How to use multiple screensets from one program

• How to use one or more error files directly from the program

• How to control user-defined field formats

• How to control every keystroke

• How to obtain system information from Dialog System

• How to obtain files from other directories

• Restrictions on compiling Dialog System applications

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:

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:

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:

• The trap does not support the screenset PUSH and POP facilities, so you cannot fully test the way the screensets are pushed and popped using the trap.

• If you push and pop screensets that are a mixture of Micro Focus Panels screensets and non-Panels screensets, there can be unpredictable results.

• Screensets that have been pushed are stored in memory, which is automatically paged to disk if memory usage is high. This could be a problem on diskless workstations in Windows environments.

• When you push screensets, their associated error files are closed. Ensure that you open the error file again when you pop the screenset, as described in the next section.

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 (or COBPATH under UNIX), 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 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:

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:

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.

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:

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.

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:

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:

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:

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 (or $COBPATH under UNIX), in order.

12.9 Compiling Dialog System Applications

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

• Do not compile the application with the directive MS"2".

Generating the Copyfile

Linking