Except for the PROGRAM-ID, the update procedure is identical to the retrieval procedure until the Main Section of the Procedure Division.

Create the update procedure as follows:

1. Example 8-2 contains the update procedure. Create a source file named EMPLOYEE_INFO_UPDATE_PUT.COB and type in the procedure as shown in this example.
2. Save the file and exit the editor.

Example 8-2 COBOL Update Procedure

IDENTIFICATION DIVISION. PROGRAM-ID. PUT_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 FILE-STAT PIC XX IS EXTERNAL. 88 OK VALUE "00". 88 REC-LOCK VALUE "92". LINKAGE SECTION. COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY REPLACING ==EMPLOYEE_INFO_WKSP. == BY ==EMPLOYEE_INFO_LINKAGE_WKSP. ==. COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY REPLACING ==EMPLOYEE_INFO_WKSP. == BY ==EMPLOYEE_INFO_COMPARE_WKSP. ==. COPY "CONTROL_WORKSPACE" FROM DICTIONARY. PROCEDURE DIVISION USING EMPLOYEE_INFO_LINKAGE_WKSP, EMPLOYEE_INFO_COMPARE_WKSP, CONTROL_WORKSPACE. DECLARATIVES. EMPLOYEE-USE SECTION. USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE. EMPLOYEE-CHECKING. EVALUATE TRUE WHEN REC-LOCK MOVE "LOCK" TO ERROR_STATUS_FIELD END-EVALUATE. END DECLARATIVES. MAIN SECTION. 000-SET-STATUS. MOVE SPACES TO ERROR_STATUS_FIELD. 010-GET-RECORD. MOVE EMPL_NUMBER OF EMPLOYEE_INFO_LINKAGE_WKSP TO EMPL_NUMBER OF EMPLOYEE_INFO_WKSP. READ EMPLOYEE-FILE ALLOWING NO OTHERS. IF ERROR-STATUS_FIELD EQUAL "LOCK" THEN GO TO 100-EXIT-PROGRAM. 020-CHECK-FOR-CHANGES. PERFORM 070-CHECK-RECORD. IF ERROR-STATUS_FIELD EQUAL "CHNG" THEN MOVE EMPLOYEE_INFO_WKSP TO EMPLOYEE_INFO_LINKAGE_WKSP MOVE EMPLOYEE_INFO_WKSP TO EMPLOYEE_INFO_COMPARE_WKSP GO TO 100-EXIT-PROGRAM. 030-REWRITE-RECORD. REWRITE EMPLOYEE_INFO_WKSP FROM EMPLOYEE_INFO_LINKAGE_WKSP ALLOWING NO OTHERS. GO TO 100-EXIT-PROGRAM. 070-CHECK-RECORD. EVALUATE EMPLOYEE_INFO_WKSP EQUAL EMPLOYEE_INFO_COMPARE_WKSP WHEN FALSE MOVE "CHNG" TO ERROR_STATUS_FIELD END-EVALUATE. 100-EXIT-PROGRAM. UNLOCK EMPLOYEE-FILE. EXIT PROGRAM.

In the Procedure Division, the update procedure performs the following actions:

• Initializes ERROR_STATUS_FIELD with spaces.
• Retrieves and locks the modified record. If the record is already locked, the procedure stores an error value in ERROR_STATUS_FIELD and exits from the program.
• Checks the contents of the record in the RMS file against the record displayed to the user, a copy of which was stored in EMPLOYEE_INFO_COMPARE_WKSP by the retrieval procedure. If the two records do not match, the procedure stores an error value in ERROR_STATUS_FIELD and exits from the program.
• Writes the modified record back to the RMS file.
• Unlocks the record before exiting the program.

Use the COBOL command to compile the update 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_UPDATE_PUT.COB as follows:

$ COBOL/DEBUG/LIST EMPLOYEE_INFO_UPDATE_PUT $

If the source file contains syntax errors, continue to edit the source file and recompile it until the COBOL compiler completes successfully.

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.

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.

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.

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.

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.