| Tutorial - Creating a Sample Screenset | Tutorial - Adding and Customizing a Status Bar | |
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:
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:
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.
Dialog System generates the copyfile for the sample screenset using the copyfile options you have just set.
You have already generated the sample copyfile.
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.
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.
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.
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.
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:
Done in the save-record section.
Not done in this application.
Done in the call-dialog-system section, if an error occurs
when the program calls Dialog System.
In this simple application, help is handled entirely by a message box in Dialog System. An alternative way of handling help would be to write a section of code in the program to provide help whenever a Help flag was set.
A minimal level of validation is done in the save-record
section to ensure that empty records are not saved. Obviously, more complex
validation can be done both by the program and by Dialog System itself at
the input stage.
By returning to Dialog System after saving or clearing the record.
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.
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.
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.
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.
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.
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.
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.
| Tutorial - Creating a Sample Screenset | Tutorial - Adding and Customizing a Status Bar | |