Compaq ACMS for OpenVMS
Getting Started
Previous Contents Index

Chapter 9
Building the Task Group

This chapter describes how to combine the data entry task and the inquiry/update task into a task group. It also describes how to write startup and cleanup procedures, how to link the object modules into a server image, and how to test the tasks using the ACMS Task Debugger.

9.1 Defining Startup and Cleanup Procedures

Because ACMS can use one server process to handle several procedures, any startup and cleanup operations can be done just once during the lifetime of the process rather than at every processing step. The following sections have you define the initialization, termination, and cancellation procedures that perform startup and cleanup for the tasks.

9.1.1 Defining the Initialization Procedure

The initialization procedure in this tutorial performs any work that must be done before the data entry, retrieval, and update procedures in the server process can execute. For example, this initialization procedure opens an RMS file and leaves it open until the process stops. This is more efficient than opening and closing the file every time a task calls one of the three processing procedures.

Therefore, the processing procedures in this tutorial do not open and close the RMS file; instead, the file is opened in the initialization procedure and closed in the termination procedure. The initialization procedure tests the status of the open operation and stops the server process if the file was not opened successfully.

In this tutorial application, the RMS file is created the first time you use the application. Because the file being opened does not exist yet, the SELECT OPTIONAL statement in COBOL creates it.

Create the COBOL initialization procedure as follows:

  1. Example 9-1 contains the COBOL initialization procedure. Create a source file named EMPLOYEE_INFO_INIT.COB and type in the procedure as shown in this example.
  2. Save the file and exit the editor.

Example 9-1 COBOL Initialization Procedure 

******************************************************************* 
IDENTIFICATION DIVISION. 
PROGRAM-ID.  INIT_EMPL_INFO. 
 
******************************************************************* 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER.        VAX-11. 
OBJECT-COMPUTER.        VAX-11. 
 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT  OPTIONAL EMPLOYEE-FILE 
        ORGANIZATION INDEXED 
        ACCESS RANDOM 
        FILE STATUS IS FILE-STAT 
        ASSIGN TO "xxx_FILES:EMPLOYEE.DAT". 
I-O-CONTROL. 
        APPLY LOCK-HOLDING ON EMPLOYEE-FILE. 
 
******************************************************************* 
DATA DIVISION. 
FILE SECTION. 
FD  EMPLOYEE-FILE EXTERNAL 
    DATA RECORD IS EMPLOYEE_INFO_WKSP 
    RECORD KEY EMPL_NUMBER OF EMPLOYEE_INFO_WKSP. 
 
COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY. 
 
WORKING-STORAGE SECTION. 
01  STATUS-RESULT                       PIC S9(9) COMP. 
01  FILE-STAT                           PIC XX IS EXTERNAL. 
 
******************************************************************* 
PROCEDURE DIVISION GIVING STATUS-RESULT. 
DECLARATIVES. 
PERS-USE SECTION. 
    USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE. 
PERS-CHECKING. 
    MOVE RMS-STS OF EMPLOYEE-FILE TO STATUS-RESULT. 
END DECLARATIVES. 
 
MAIN SECTION. 
000-SET-STATUS. 
    SET STATUS-RESULT TO SUCCESS. 
 
010-OPEN-FILES. 
    OPEN I-O EMPLOYEE-FILE ALLOWING ALL. 
 
100-EXIT-PROGRAM. 
    EXIT PROGRAM.

Use the COBOL command to compile this procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

Compile the source file EMPLOYEE_INFO_INIT.COB as follows: 


$ COBOL/DEBUG/LIST EMPLOYEE_INFO_INIT
$

If the source file contains syntax errors, continue to edit the source file and recompile it until the program compiles successfully.

9.1.2 Defining the Termination Procedure

The termination procedure performs any work that must be done when the server process stops. (ACMS stops a server process when you stop an application that uses the server.) For example, closing an RMS file in a termination procedure is more efficient than opening and closing the file every time the task calls one of the three processing procedures.

Note
If the server runs down because a cancel occurs, ACMS does not execute the termination procedure unless you include the statement ALWAYS EXECUTE TERMINATION PROCEDURE in the server clause of the task group definition (see Section 9.2.3).

Create the COBOL termination procedure as follows:

  1. Example 9-2 contains the COBOL termination procedure. Create a source file named EMPLOYEE_INFO_TERM.COB and type in the procedure as shown in this example.
  2. Save the file and exit the editor.

Example 9-2 COBOL Termination Procedure 

******************************************************************* 
IDENTIFICATION DIVISION. 
PROGRAM-ID.  TERM_EMPL_INFO. 
 
******************************************************************* 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER.        VAX-11. 
OBJECT-COMPUTER.        VAX-11. 
 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT  EMPLOYEE-FILE 
        ORGANIZATION INDEXED 
        ACCESS RANDOM 
        FILE STATUS IS FILE-STAT 
        ASSIGN TO "xxx_FILES:EMPLOYEE.DAT". 
I-O-CONTROL. 
        APPLY LOCK-HOLDING ON EMPLOYEE-FILE. 
 
******************************************************************* 
DATA DIVISION. 
FILE SECTION. 
FD  EMPLOYEE-FILE EXTERNAL 
    DATA RECORD IS EMPLOYEE_INFO_WKSP 
    RECORD KEY EMPL_NUMBER OF EMPLOYEE_INFO_WKSP. 
 
COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY. 
 
WORKING-STORAGE SECTION. 
01  STATUS-RESULT                       PIC S9(9) COMP. 
01  FILE-STAT                           PIC XX IS EXTERNAL. 
 
******************************************************************* 
PROCEDURE DIVISION GIVING STATUS-RESULT. 
DECLARATIVES. 
PERS-USE SECTION. 
    USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE. 
PERS-CHECKING. 
    MOVE RMS-STS OF EMPLOYEE-FILE TO STATUS-RESULT. 
END DECLARATIVES. 
 
MAIN SECTION. 
000-SET-STATUS. 
    SET STATUS-RESULT TO SUCCESS. 
 
010-CLOSE-FILES. 
    CLOSE EMPLOYEE-FILE. 
 
100-EXIT-PROGRAM. 
    EXIT PROGRAM.

Use the COBOL command to compile this procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

Compile the source file EMPLOYEE_INFO_TERM.COB as follows: 


$ COBOL/DEBUG/LIST EMPLOYEE_INFO_TERM
$

If the source file contains syntax errors, continue to edit the source file and recompile it until the program compiles successfully.

9.1.3 Defining the Cancellation Procedure

The cancellation procedure performs any work that must be done if a cancel occurs while the server process is active. For example, the processing procedures lock a record to process it. If a cancel occurs (for example, if the user presses [Ctrl/C]) while the record is locked, the record remains locked until the server process stops unless you unlock it in a cancellation procedure. By unlocking the record quickly with a cancellation procedure, you avoid delays to other users trying to access the record.

Note
Often a cancellation procedure is not recommended in more complex applications, either for design reasons, or because you can accomplish any necessary server cleanup activity in your termination procedure.

Create the COBOL cancellation procedure as follows:

  1. Example 9-3 contains the COBOL cancellation procedure. Create a source file named EMPLOYEE_INFO_CANCEL.COB and type in the procedure as shown in this example.
  2. Save the file and exit the editor.

Example 9-3 COBOL Cancellation Procedure 

******************************************************************* 
IDENTIFICATION DIVISION. 
PROGRAM-ID.  CANCEL_EMPL_INFO. 
 
******************************************************************* 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER.        VAX-11. 
OBJECT-COMPUTER.        VAX-11. 
 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
SELECT  EMPLOYEE-FILE 
        ORGANIZATION INDEXED 
        ACCESS RANDOM 
        FILE STATUS IS FILE-STAT 
        ASSIGN TO "xxx_FILES:EMPLOYEE.DAT". 
I-O-CONTROL. 
        APPLY LOCK-HOLDING ON EMPLOYEE-FILE. 
 
******************************************************************* 
DATA DIVISION. 
FILE SECTION. 
FD  EMPLOYEE-FILE EXTERNAL 
    DATA RECORD IS EMPLOYEE-INFO_WKSP 
    RECORD KEY EMPL_NUMBER OF EMPLOYEE_INFO_WKSP. 
 
COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY. 
 
WORKING-STORAGE SECTION. 
01  STATUS-RESULT                       PIC S9(9) COMP. 
01  FILE-STAT                           PIC XX IS EXTERNAL. 
 
******************************************************************* 
PROCEDURE DIVISION GIVING STATUS-RESULT. 
DECLARATIVES. 
PERS-USE SECTION. 
    USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE. 
PERS-CHECKING. 
    MOVE RMS-STS OF EMPLOYEE-FILE TO STATUS-RESULT. 
END DECLARATIVES. 
 
MAIN SECTION. 
000-SET-STATUS. 
    SET STATUS-RESULT TO SUCCESS. 
 
010-UNLOCK-FILES. 
    UNLOCK EMPLOYEE-FILE. 
 
100-EXIT-PROGRAM. 
    EXIT PROGRAM.

Use the COBOL command to compile this procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

Compile the source file EMPLOYEE_INFO_CANCEL.COB as follows: 


$ COBOL/DEBUG/LIST EMPLOYEE_INFO_CANCEL
$

If the source file contains syntax errors, continue to edit the source file and recompile it until the program compiles successfully.

9.2 Defining and Building the Task Group

To define the task group in this tutorial, you specify the tasks that belong to the group, the server in which the tasks run, and the workspaces that the tasks use. Because the application uses DECforms to get information from the terminal user, you must also specify the form file name, form file specification, and form file label of the forms used in the task group definition.

You define a task group with commands and clauses of the Application Definition Utility (ADU) in the same manner that you created the two task definitions earlier.

9.2.1 Naming Forms

To begin defining the task group definition, follow these steps:

  1. Use a text editor to create a source file for the task group definition. Name the source file EMPLOYEE_INFO_TASK_GROUP.GDF.
  2. Begin your file by entering the following lines: 


     
REPLACE GROUP EMPLOYEE_INFO_TASK_GROUP 
FORM IS EMPLOYEE_INFO_FORM IN "xxx_FILES:EMPLOYEE_INFO_FORM" 
  WITH NAME EMPLOYEE_INFO_LABEL;  
FORM IS EMPLOYEE_INFO_PROMPT_FORM 
  IN "xxx_FILES:EMPLOYEE_INFO_PROMPT_FORM" 
  WITH NAME EMPLOYEE_INFO_PROMPT_LABEL;

    The task group definition lists the OpenVMS file specifications of DECforms form files used in the task group. These are EMPLOYEE_INFO_FORM and EMPLOYEE_INFO_PROMPT_FORM, created in Chapter 7 and Chapter 8, and stored in the directory specified by your logical xxx_FILES.
    The WITH NAME phrase specifies the form label name for each form. These names were used earlier within the ACMS task definitions to refer to the form.

9.2.2 Naming the Tasks in the Task Group

You can now add the following TASKS ARE clause to the source file: 


 
TASKS ARE 
  EMPLOYEE_INFO_ADD_TASK : TASK IS EMPLOYEE_INFO_ADD_TASK; 
  EMPLOYEE_INFO_UPDATE_TASK : TASK IS EMPLOYEE_INFO_UPDATE_TASK; 
END TASKS;

The task name on the right hand side of the colon is as you defined it in CDD. The task name on the left hand side of the colon can be any unique name you create to identify the task and does not need to match the task name on the right hand side, but using different names is more often confusing than useful. You use the task names on the left hand side later in the application definition to assign different characteristics to individual tasks.

9.2.3 Naming the Procedure Server and Workspaces

All the COBOL procedures run in the same procedure server, which you define by adding a SERVER IS clause to your source file.

  1. Add the following lines to your file: 


     
SERVER IS 
  EMPL_SERVER: 
    DEFAULT OBJECT FILE IS EMPL_SERVER; 
    PROCEDURE SERVER IMAGE IS "xxx_FILES:EMPL_SERVER"; 
    INITIALIZATION PROCEDURE IS INIT_EMPL_INFO; 
    TERMINATION PROCEDURE IS TERM_EMPL_INFO; 
    CANCEL PROCEDURE IS CANCEL_EMPL_INFO; 
    PROCEDURES ARE 
      ADD_EMPL_INFO, 
      GET_EMPL_INFO, 
      PUT_EMPL_INFO; 
END SERVER; 
 
WORKSPACES ARE 
 EMPLOYEE_INFO_WKSP, 
 EMPLOYEE_INFO_WKSP WITH NAME EMPLOYEE_INFO_COMPARE_WKSP, 
 QUIT_WORKSPACE, 
 CONTROL_WORKSPACE; 
 
END DEFINITION;

    The SERVER IS clause identifies the procedure server for the task group and lists all procedures that run in the server. You list each procedure by its PROGRAM-ID (for example, ADD_EMPLOYEE_INFO), including any initialization, termination, and cancellation procedures you have written.
    The DEFAULT OBJECT FILE statement names the procedure server object module (.OBJ), while the PROCEDURE SERVER IMAGE statement names the executable image (.EXE). In this tutorial, the server object module and the executable image are both called EMPL_SERVER. The system logical xxx_FILES specifies the directory in which to place the procedure server image.
    The WORKSPACES clause defines the workspaces used in the tasks. In the inquiry/update task, both EMPLOYEE_INFO_WKSP and EMPLOYEE_INFO_COMPARE_WKSP need to use the EMPLOYEE_INFO_WKSP definition. However, ACMS requires that workspace names be unique; therefore, you use the WITH NAME keywords in the WORKSPACES clause to rename one of the EMPLOYEE_INFO_WKSP definitions.

  2. Your definition for the task group definition, EMPLOYEE_INFO_TASK_GROUP.GDF, is now complete. Save your file and exit the editor.

9.2.4 Compiling the Task Group Definition

Compiling the task group definition allows ADU to check for syntax errors in the source file EMPLOYEE_INFO_TASK_GROUP.GDF. If there are no errors, ADU inserts your task group definition into CDD. To do this, perform the following steps:

  1. Invoke ADU: 


    $ ADU

  2. When you use the SET LOG and SET VERIFY commands, ADU simultaneously writes its output to the terminal screen and to the ADULOG.LOG file. Enter the SET LOG and SET VERIFY commands: 


    ADU> SET LOG
ADU> SET VERIFY

  3. Submit the task group definition file to ADU: 


    ADU> @EMPLOYEE_INFO_TASK_GROUP.GDF

    If ADU detects syntax errors in your task definition, exit ADU and edit the source file to correct the errors; then reenter ADU and resubmit the file. Repeat editing the source file and resubmitting it to ADU until the file processes without errors. If you get error messages, make sure that you typed the definition exactly as shown. In particular, check that you used the appropriate punctuation.

  4. Exit from ADU.

Your default CDD directory now contains the task group definition, the task definitions created for the data entry and inquiry/update tasks, and the record definitions for these tasks. You can use the CDO DIRECTORY command to verify that these definitions exist (a partial directory listing is as follows). 


$ CDO
CDO> DIRECTORY
   CONTROL_WORKSPACE;1                            RECORD
   EMPLOYEE_INFO_ADD_TASK;1                       ACMS$TASK
   EMPLOYEE_INFO_TASK_GROUP;1                     ACMS$TASK_GROUP
   EMPLOYEE_INFO_UPDATE_TASK;1                    ACMS$TASK
   EMPLOYEE_INFO_WKSP;1                           RECORD
   . 
   . 
   . 
CDO>

The DIRECTORY command displays the names of items in CDD and indicates the type of each item: CDD record or field, ACMS task or task group.

9.2.5 Building the Task Group

You can now build the task group with the ADU BUILD command. This command produces two new files: a task group database file and a procedure server object module. The task group database is an RMS file that contains binary versions of the tasks and information about how to process them. At run time, ACMS executes the tasks in their binary form rather than as ADU source commands. The procedure server object module controls the procedures that run in the same server.

To build the task group, use the BUILD command with the GROUP keyword. Include the /DEBUG qualifier to test the task group in the ACMS Task Debugger (described at the end of this chapter). Build the task group as follows: 


$ ADU
ADU> BUILD GROUP EMPLOYEE_INFO_TASK_GROUP/DEBUG 
ADU>

If the BUILD command succeeds, ADU displays a "Writing TDB...object module created" sequence of messages. When ADU processes this command, it creates the task group database file EMPLOYEE_INFO_TASK_GROUP.TDB. It also creates a procedure server transfer module called EMPL_SERVER.OBJ. In the following section, you link this object module with all the procedure object modules to produce the procedure server image.

If the BUILD command fails, ADU issues error messages and redisplays the ADU> prompt. Correct the errors and resubmit the task group definition to ADU, repeating this sequence until the definition processes without errors.

Exit from ADU.

9.3 Linking the Server Image

You can now link the procedure server object module with the object modules of all the procedures in the task group. Use the DCL LINK command. Include the /DEBUG qualifier to test the task group in the ACMS Task Debugger (described at the end of this chapter): 


$ LINK/DEBUG EMPL_SERVER, EMPLOYEE_INFO_ADD, EMPLOYEE_INFO_INIT, -
_$ EMPLOYEE_INFO_TERM, EMPLOYEE_INFO_CANCEL, EMPLOYEE_INFO_UPDATE_GET, -
_$ EMPLOYEE_INFO_UPDATE_PUT
$

If your LINK command succeeds, DCL returns the $ prompt without any error messages.

The VAX Linker automatically uses the first object module listed after the LINK command as the name of the server image. The tutorial lists the EMPL_SERVER object module first, so that the server image has the same name as the procedure server. This produces a server image named EMPL_SERVER.EXE.

(Notice that you use the DCL file names for the COBOL procedures in the LINK command.)

9.4 Testing a Task in the ACMS Task Debugger

With the ACMS Task Debugger you can simulate how a task runs as part of an application, even though you have not yet defined the application and its menus. You run one task at a time and, in this way, test how an individual task works. The ACMS Task Debugger uses the task group database (.TDB) file and the server image (.EXE) file to run the tasks in a task group.

Note
The ACMS Task Debugger works within your OpenVMS process. To accommodate the Task Debugger, your OpenVMS account needs a minimum BYTLM quota of 50,000. Otherwise, you receive an EXBYTLM error in step 2.

If you want to create a DECforms trace file that records form processing whenever an ACMS task calls a DECforms request, turn on tracing here before entering the Task Debugger (see Section A.4).

To use the ACMS Task Debugger, follow these steps:

  1. To start the Task Debugger, issue the ACMS/DEBUG command followed by the name of the task group. To examine the contents of workspaces while stepping through a task, include the /WORKSPACE qualifier: 


    $ ACMS/DEBUG EMPLOYEE_INFO_TASK_GROUP /WORKSPACE
ACMSDBG>

  2. Issue the START command to start EMPL_SERVER. The Task Debugger returns several messages and the DBG> prompt: 


    ACMSDBG> START EMPL_SERVER
Terminal is in SERVER EMPL_SERVER 
 
          VAX DEBUG Version ...   
 
%DEBUG-I-INITIAL, language is COBOL, module set to EMPL_SERVER 
DBG>

  3. Issue the GO command to run the initialization procedure, EMPLOYEE_INFO_INIT.COB: 


    DBG> GO
Server EMPL_SERVER has been started 
ACMSDBG>

    To verify that EMPL_SERVER is active as you are testing, you can enter the SHOW SERVERS command: 


    ACMSDBG> SHOW SERVERS
EMPL_SERVER 
ACMSDBG>

  4. (Optional) Set breakpoints for EMPLOYEE_INFO_ADD_TASK at the GET_EMPL_INFO and PROCESS_EMPL_INFO lines in the task, using the $ACTION symbol. Breakpoints stop a task at a specified line so that you can examine the contents of a field in one of the workspaces: 


    ACMSDBG> SET BREAK EMPLOYEE_INFO_ADD_TASK\GET_EMPL_INFO\$ACTION
ACMSDBG> SET BREAK EMPLOYEE_INFO_ADD_TASK\PROCESS_EMPL_INFO\$ACTION
ACMSDBG>

  5. (Optional) Issue the SHOW BREAK command to check the breakpoints you have set: 


    ACMSDBG> SHOW BREAK



    task breakpoint at EMPLOYEE_INFO_ADD_TASK\GET_EMPL_INFO\$ACTION 
task breakpoint at EMPLOYEE_INFO_ADD_TASK\PROCESS_EMPL_INFO\$ACTION 



    ACMSDBG>

  6. Enter the SELECT command with the name of the task that you want to start: 


    ACMSDBG> SELECT EMPLOYEE_INFO_ADD_TASK
Task is in the task debugger

    This command begins the task. The EMPLOYEE_INFO_FORM appears on your screen.

  7. Enter data in all the fields on the form. (Make note of the employee number that you enter here to test the inquiry/update task next.) Then press [Ctrl/Z]. If you set breakpoints, the system returns this message: 


    Task breakpoint at EMPLOYEE_INFO_ADD_TASK\GET_EMPL_INFO\$ACTION

    (If you did not set breakpoints, the message is "Task ended," and you can proceed to step 11.)

  8. Issue the EXAMINE command to check that the information you entered on the form was transmitted to the workspace EMPLOYEE_INFO_WKSP: 


    ACMSDBG> EXAMINE EMPLOYEE_INFO_WKSP

    The Task Debugger displays the employee data as it appears in the workspace.

  9. Enter GO to continue to your second breakpoint: 


    ACMSDBG> GO



    Task is in SERVER EMPL_SERVER 
Task is in the task debugger 
Task breakpoint at EMPLOYEE_INFO_ADD_TASK\PROCESS_EMPL_INFO\$ACTION 



    ACMSDBG>

    The Task Debugger now stops at the second breakpoint (PROCESS_EMPL_INFO) in your task.

  10. Enter GO to complete the task: 


    ACMSDBG> GO
Task ended

  11. If you wish to test EMPLOYEE_INFO_UPDATE_TASK, you can use the employee number that you just entered during the data entry test above. (If you wish to set breakpoints for this task, do so before selecting the task.) Enter the SELECT command with the name of the task: 


    ACMSDBG> SELECT EMPLOYEE_INFO_UPDATE_TASK
Task is in the task debugger

    This command begins the task. The EMPLOYEE_INFO_PROMPT_FORM appears on your screen. Type in the employee number and press [Ctrl/Z]. The employee data that you entered in the data entry test should appear on your screen. You can now modify that data and save it by pressing [Ctrl/Z].

  12. When you are finished testing your tasks ("Task ended"), issue the STOP command to stop EMPL_SERVER: 


    ACMSDBG> STOP /ALL
Terminal is in SERVER EMPL_SERVER 
Server EMPL_SERVER stopped 
ACMSDBG>

  13. Exit from the ACMS Task Debugger: 


    ACMSDBG> EXIT
$

Previous Next Contents Index