PreviousTutorial - Creating a Sample Screenset Tutorial - Adding and Customizing a Status BarNext

Chapter 19: Tutorial - Using the Sample Screenset

The chapter Tutorial - Creating a Sample Screenset explained how to create the Entries screenset containing the user interface for a sample application. This chapter explains how to write an application program to use the Entries screenset, and guides you through the following steps:

  1. Generating the COBOL copyfile from the screenset.

  2. Writing the COBOL application program with the necessary calls to the Dialog System run-time.

  3. Debugging and animating the COBOL program.

  4. Packaging your application.

19.1 Generating the Data Block Copyfile

The Data Block copyfile contains the definition of the Data Block passed from the calling program to Dialog System at run time. You must include the copyfile in your calling program. The copyfile also contains version checking information.

Dialog System enables you to generate a copyfile from your screenset, and set options determining how that copyfile is generated.

To create the copyfile for your sample screenset, first set the screenset configuration options, then generate the copyfile:

  1. Select Configuration on the Options menu.

  2. Select Screenset on the popup menu.

  3. Enter the name Entry in Screenset identifier.

  4. Check that Fields prefixed by screenset ID check box is on.

    This specifies that all the data names from the data block are prefixed by the string "entry". The sample program uses these prefixed data names.

  5. Select Enter or OK to accept the other defaults from this dialog box.

  6. Select Generate on the File menu.

  7. Select Data block COPY-File from the drop down menu that appears.

  8. Enter the name of the file to be used for the copyfile – entries.cpb.

  9. Select Enter.

    Dialog System generates the copyfile for the sample screenset using the copyfile options you have just set.

19.1.1 Selecting Options and Generating the Copyfile

You have already generated the sample copyfile.

19.2 Writing the COBOL Application Program

A COBOL program that uses the sample screenset you created in the previous chapter is shown below. This program is provided with your Dialog System software as a demonstration program. It is called entries.cbl.

Your requirements and programming style may result in a different program structure.

 1 $set ans85
 2  identification division.

 3  program-id. race-entries.

 4  environment division.

 5  input-output section.
 6  file-control.
 7      select entry-file assign "entries.dat"
 8      access is sequential.

 9  data division.
 
10  file section.
11  fd  entry-file.
12  01  entry-record.
13      03  file-name              pic x(15).
14      03  file-male              pic 9.
15      03  file-address           pic x(100).
16      03  file-club              pic x(30).
17      03  file-code              pic x(3).

18  working-storage section.
19      copy "ds-cntrl.v1".
20      copy "entries.cpb".

21  78  refresh-text-and-data-proc value 255
22  77  display-error-no           pic 9(4).
  
23  procedure division.

24  main-process section.
25      perform program-initialize
26      perform program-body until entry-exit-flg-true
27      perform program-terminate.

28  program-initialize section.
29      initialize entry-data-block
30      initialize ds-control-block
31      move entry-data-block-version-no
32                            to ds-data-block-version-no
33      move entry-version-no to ds-version-no
34      open output entry-file
35     perform load-screenset.

36  program-body section.
37 * Process the returned user action (in the flags); clear those
38 * flags and call Dialog System again.

39      evaluate true
40        when entry-save-flg-true
41          perform save-record
42        when entry-clr-flg-true
43          perform clear-record
44      end-evaluate
45      perform clear-flags
46      perform call-dialog-system.

47  program-terminate section.
48      close entry-file
49      stop run.

50  save-record section.
51 * Save the current details in the file if all the text fields
52 * contain values.

53      if (entry-name    < > spaces) and
54         (entry-address < > spaces) and
55         (entry-club    < > spaces) and
56         (entry-code    < > spaces)
57             move entry-name    to file-name
58             move entry-male    to file-male
59             move entry-address to file-address
60             move entry-club    to file-club
61             move entry-code    to file-code
62             write entry-record
63      end-if.

64  clear-record section.
65 * Clear the current details by initializing the data block.

66      initialize entry-record
67      initialize entry-data-block
68      perform set-up-for-refresh-screen.

69  clear-flags section.
70      initialize entry-flag-group.

71  set-up-for-refresh-screen section.
72 * Force Dialog System to execute the procedure P225 (in global
73 * dialog) the next time it is called. This procedure simply
74 * refreshes the main window with the values from the data 
75 * block.

76      move "refresh-data" to ds-procedure.

77  load-screenset section.
78 * Specify the screenset to be used and call Dialog System.

79      move ds-new-set to ds-control
80      move "entries"  to ds-set-name
81      perform call-dialog-system.

82  call-dialog-system section.
83      call "dsgrun" using ds-control-block,
84                         entry-data-block.
85      if not ds-no-error
86          move ds-error-code to display-error-no
87          display "ds error no:   " display-error-no
88         perform program-terminate
89      end-if.
Lines 1 to 22:
1  $set ans85
2  identification division.

3  program-id. race-entries.

4  environment division.

5  input-output section.
6  file-control.
7      select entry-file assign "entries.dat"
8      access is sequential.

9  data division.

10 file section.
11 fd  entry-file.
12 01  entry-record.
13     03  file-name              pic x(15).
14     03  file-male              pic 9.
15     03  file-address           pic x(100).
16     03  file-club              pic x(30).
17     03  file-code              pic x(3).

18 working-storage section.
19     copy "ds-cntrl.v1".
20     copy "entries.cpb".

21 78  refresh-text-and-data-proc value 255
22 77  display-error-no              pic 9(4).

These lines set up the records for storage of the entries input by the user.

Lines 23 to 27:
23  procedure division.

24  main-process section.
25      perform program-initialize
26      perform program-body until entry-exit-flg-true
27      perform program-terminate.

These lines structure the whole program, making sure that it ends when the user presses Esc or uses the System menu to close the window. These actions set the Exit flag in the screenset. The flag setting is passed to the program for action.

Lines 28 to 35:
28  program-initialize section.
29      initialize entry-data-block
30      initialize ds-control-block
31      move entry-data-block-version-no
32                            to ds-data-block-version-no
33      move entry-version-no to ds-version-no
34      open output entry-file
35      perform load-screenset.

The Data Block copyfile contains not only the user data but some version numbers that Dialog System checks against the screenset when it is called. To do this, the calling program must copy them into data items in the Control Block before it calls the Dialog System run-time.

When you write your calling program, you must copy the copyfile into the program Working-Storage Section using the statement: copy "ds-cntrl.mf". If you are using ANSI-85 conformant COBOL then you should use the copyfile ds-cntrl.ans.

You also need to make sure that the Control Block contains the name of the screenset and other information that controls Dialog System behavior.

Lines 36 to 46:
36  program-body section.
37 * Process the returned user action (in the flags); clear those
38 * flags and call Dialog System again.

39      evaluate true
40        when entry-save-flg-true
41          perform save-record
42        when entry-clr-flg-true
43          perform clear-record
44      end-evaluate
45      perform clear-flags
46      perform call-dialog-system.

Dialog System enables the user to decide which functions the program is to perform rather than the program dictating the user's actions. The flags set in the Data Block returned from Dialog System contain values resulting from the user's action. These values tell the program what to do next.

The program can respond in a variety of ways including:

Lines 47 to 49:
47  program-terminate section.
48      close entry-file
49      stop run.

These lines end the program when an error occurs or when the user presses Esc or uses the System menu to close the window.

Lines 50 to 63:
50  save-record section.
51 * Save the current details in the file if all the text fields
52 * contain values.

53      if (entry-name    < > spaces) and
54         (entry-address < > spaces) and
55         (entry-club    < > spaces) and
56         (entry-code    < > spaces)
57             move entry-name    to file-name
58             move entry-male    to file-male
59             move entry-address to file-address
60             move entry-club    to file-club
61             move entry-code    to file-code
62             write entry-record
63      end-if.

These lines save the user's input if the user has pressed Save. Pressing this button sets the Save flag which the program tests in the program-body section. The input is not saved if the record is empty.

Lines 64 to 68:
64  clear-record section.
65 * Clear the current details by initializing the data block.

66      initialize entry-record
67      initialize entry-data-block
68      perform set-up-for-refresh-screen.

These lines clear the current inputs from the screen and from the Data Block when the user presses Clear. Pressing this button sets the Clear flag which the program tests in the program-body section.

Lines 69 to 76:
69  clear-flags section.
70      initialize entry-flag-group.
71  set-up-for-refresh-screen section.

72 * Force Dialog System to execute the procedure P225 (in global
73 * dialog) the next time it is called. This procedure simply
74 * refreshes the main window with the values from the data 
75 * block.

76      move "refresh-data" to ds-procedure.

These lines clear the flags and tell Dialog System to refresh the screen ready for the next user inputs.

Lines 77 to 89:
77  load-screenset section.
78 * Specify the screenset to be used and call Dialog System.

79      move ds-new-set to ds-control
80      move "entries"  to ds-set-name
81      perform call-dialog-system.

82  call-dialog-system section.
83      call "dsgrun" using ds-control-block,
84                         entry-data-block.
85      if not ds-no-error
86          move ds-error-code to display-error-no
87          display "ds error no:   " display-error-no
88          perform program-terminate
89      end-if.

These lines load the correct screenset and call Dialog System. The second section also checks for calling errors and ends the program if an error occurs.

19.3 Debugging and Animating the COBOL Program

Your COBOL system provides an editing, debugging and animating environment.

When you are debugging an application, the source code of each program is displayed in a separate window. When you animate the code, each line of the source is highlighted in turn as each statement is executed, showing the effect of each statement. You can control the pace at which the program executes and can interrupt execution to examine and change data items. See the topic Debugging in the Help for more information.

19.4 Packaging Your Application

To create the finished application you must complete various subtasks.

You use the Project facility from within Net Express to build your Dialog System application. See the topic Building Applications in your Help for further details.

The topic Compiling in your Help explains what you must do next to prepare your application for production.

When testing is completed, you are ready to assemble the finished product. A finished product can be copied onto diskettes, sent to a customer, and loaded onto another machine to run as an application.

Depending on the size of the application, the finished product consists of one or more of the following:


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

PreviousTutorial - Creating a Sample Screenset Tutorial - Adding and Customizing a Status BarNext