Compaq ACMS for OpenVMS
Getting Started


Previous Contents Index


Chapter 8
Developing the Inquiry/Update Task

This chapter describes in step-by-step detail how to write the inquiry/update task using ACMS, DECforms, and CDD definitions.

8.1 Defining a DECforms Form for Inquiry/Update

In the inquiry portion of the task, the user needs to see a panel that prompts for the employee number. In the update portion of the task, the user sees the same panel developed for the data entry task. (In the update task, the fields are already filled in with employee data when the panel appears.)

Use the same steps as in Section 7.3 to create a form and panel for the inquiry portion of this task. This panel prompts the user to enter an employee number. Abbreviated versions of these steps are as follows:

  1. Enter FDE and type the name of your new form:


    $ FDE 
    _Input_File: EMPLOYEE_INFO_PROMPT_FORM
    

    Note

    If you copied the online IFDL source files to your default directory before starting this tutorial, DECforms translates the existing IFDL file here and loads the resulting FORM file. It displays the Main Menu instead of Figure 7-1. In this case, use the arrow keys to choose the Exit option and press [Select] . Proceed to step 10.
  2. Select Yes to accept the default layout; select the panel option Choose, Create; select the option Create Panel; enter the name of your panel as show below; select Yes-Remove; and then select OK.


    Panel Name: EMPLOYEE_PROMPT_PANEL
    

  3. Select the Panel Editor menu choice. Format your panel as shown in Figure 8-1 (remembering to use the arrow keys to position the cursor).

    Figure 8-1 Employee Number Panel


  4. Position the cursor after "Employee Number of Record to Update:" on the panel. Press [Do] and issue the CREATE FIELD command to create a field there:


    Command> CREATE FIELD
    

  5. Enter the field name on the Create Field Menu and press [Return].


    Field Name    : EMPL_NUMBER
    

    As before, press [Select] at the Data Type prompt, select the Character data type, and enter a size of 10. Select OK. Enter X(10) for the field picture and then select OK to leave the Create Field Menu.

  6. Press [Ctrl/Z] to exit from the Panel Editor, test this panel through the Test option on the FDE Main Menu, press [Ctrl/Z] to exit the test, and then exit from FDE by selecting Exit.
  7. Use a text editor to edit the IFDL source file created by DECforms. This file is named EMPLOYEE_INFO_PROMPT_FORM.IFDL.
    Enter a form record description. Add the following lines after the line, "End Data":


    Form Record EMPLOYEE_INFO_RECORD 
        Copy 
            EMPLOYEE_INFO_RECORD From Dictionary 
        End Copy 
    End Record 
    

    Enter a function key declaration, a function response, and, to perform cleanup activities, a disable response. Add the following lines after the line, "Size 24 Lines by 80 Columns":


    Function QUIT_KEY 
        Is %PF4 
    End Function 
     
    Function Response QUIT_KEY 
        Remove All 
        Return 
            " FQUT" 
    End Response 
     
    Disable Response 
        Request Exit Response 
            Remove All 
        End Response 
    End Response 
    

    Add the following lines under "Field EMPL_NUMBER" after the line specifying "Column ...":


    Entry Response 
        Reset EMPL_NUMBER 
    End Response 
    

    The Reset clause deletes old data that may be in the EMPL_NUMBER field.

  8. Your EMPLOYEE_INFO_PROMPT_FORM.IFDL is now complete. Save the edits made in the IFDL file and exit from the text editor.
  9. Create a new binary form file to match your IFDL source file by issuing the following command:


    $ FORMS TRANSLATE EMPLOYEE_INFO_PROMPT_FORM.IFDL
    $
    

  10. Enter the DECforms EXTRACT OBJECT command to create a form object module, or .OBJ file:


    $ FORMS EXTRACT OBJECT EMPLOYEE_INFO_PROMPT_FORM.FORM
    $
    

  11. Enter the LINK/SHARE command to link the form object module into a shareable image:


    $ LINK/SHARE EMPLOYEE_INFO_PROMPT_FORM.OBJ
    $
    

    The result of the LINK/SHARE command is an image (.EXE) of the form that can be shared by multiple users.

8.2 Defining the Inquiry/Update Task

The inquiry/update task allows a user to display an employee record from the RMS master file EMPLOYEE.DAT. The user can then modify the contents of that record (for example, changing the employee's address) and write the revised record back to the RMS master file. This task first displays a panel to prompt the user for the employee number, then displays the employee record for that number, and then writes the modified record to the RMS file.

The inquiry/update task contains three exchange steps and two processing steps:

The inquiry/update task does not cover all possible error conditions. For illustration purposes, this task contains error handling for a condition in which two users are modifying the same record at approximately the same time. The task informs one of the users that another user has changed that record and gives the notified user a chance to repeat the task with the most recent version of the record.

8.2.1 Defining the First Exchange Step

The first exchange step directs DECforms to display a panel that prompts the user for the employee number of the record to be updated. This employee number is passed to the first processing step, which retrieves the specified record from the RMS file and displays it to the user.

To define the first exchange step:

  1. Use a text editor to create a source file for the inquiry/update task definition. Name the source file EMPLOYEE_INFO_UPDATE_TASK.TDF.
  2. Enter the first exchange step in your task definition file:


    GET_EMPL_NUMBER: 
    EXCHANGE 
      RECEIVE FORM RECORD EMPLOYEE_INFO_RECORD 
      IN EMPLOYEE_INFO_PROMPT_LABEL 
      RECEIVING EMPLOYEE_INFO_WKSP 
      WITH RECEIVE CONTROL QUIT_WORKSPACE; 
     
    

    Unlike the data entry task, this exchange step explicitly states the name of the form (EMPLOYEE_INFO_PROMPT_LABEL) used to enter the employee number. Otherwise, ACMS displays the data entry form, which you specify as the default form later in the task group definition. Specifying a form here overrides the default form.
    As in the data entry task, the RECEIVE CONTROL statement names the ACMS workspace (QUIT_WORKSPACE) to which DECforms returns the value FQUT when the user presses [PF4].

  3. Add the following lines to your task definition:


    CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY 
       " FQUT"  :  EXIT TASK; 
    END CONTROL FIELD; 
    

    The CONTROL FIELD statement associates the value FQUT with the ACMS command EXIT TASK. Because you have already defined the field QUIT_KEY and the record QUIT_WORKSPACE in CDD for the data entry task, you do not need to define them again for the inquiry/update task.

8.2.2 Defining the First Processing Step

The first processing step calls a COBOL procedure that retrieves an employee record from the RMS master file. The retrieved record corresponds to the employee number that the user entered. The user then has an opportunity to modify employee information on the panel that displays this record.

Add the following processing step next as the second step in your task definition file. To simplify referencing this step in the task, begin the step with the label RETRIEVE_UPDATE_INFO:


RETRIEVE_UPDATE_INFO: 
PROCESSING 
  CALL GET_EMPL_INFO IN EMPL_SERVER 
    USING EMPLOYEE_INFO_WKSP, EMPLOYEE_INFO_COMPARE_WKSP, 
    CONTROL_WORKSPACE; 

GET_EMPL_INFO is the name of the COBOL procedure that retrieves a record from the RMS file. It runs in the server EMPL_SERVER and uses three workspaces. The procedure and these workspaces are discussed later in the chapter.

8.2.3 Defining the Second Exchange Step

The second exchange step directs DECforms to display the retrieved employee record on a panel. The user can then modify that information. When the user finishes modifying employee information, this exchange step then directs DECforms to return the updated information to ACMS.

Next, add the second exchange step to your task definition file. To simplify referencing this step in the task, begin the step with the label GET_UPDATE_INFO_FROM_USER:


GET_UPDATE_INFO_FROM_USER: 
EXCHANGE 
  TRANSCEIVE FORM RECORD EMPLOYEE_INFO_RECORD, EMPLOYEE_INFO_RECORD 
    IN EMPLOYEE_INFO_LABEL 
  SENDING EMPLOYEE_INFO_WKSP 
  RECEIVING EMPLOYEE_INFO_WKSP 
  WITH RECEIVE CONTROL QUIT_WORKSPACE; 
 
  CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY 
       " FQUT"     :  EXIT TASK; 
  END CONTROL FIELD;    

The second exchange step begins with a TRANSCEIVE FORM RECORD call to DECforms naming the SEND record and the RECEIVE record involved in the TRANSCEIVE operation (in both cases here, EMPLOYEE_INFO_RECORD). The name EMPLOYEE_INFO_LABEL specifies which form to use.

The SENDING clause names the workspace sent to the form: EMPLOYEE_INFO_WKSP. The RECEIVING clause names the workspace received from the form: also EMPLOYEE_INFO_WKSP. The latter workspace contains any modifications that a user makes to the data items displayed on the form.

As you did for the first exchange step, include a CONTROL FIELD clause in your task definition so that the user can press a key to exit from the task without saving any entries.

8.2.4 Defining the Second Processing Step

The second processing step calls a COBOL procedure that processes the update information and places it in the RMS file.

Next, add the second processing step to your task definition file. To simplify referencing this step in the task, begin the step with the label PROCESS_UPDATE_INFO:


 
PROCESS_UPDATE_INFO: 
PROCESSING 
  CALL PUT_EMPL_INFO IN EMPL_SERVER 
     USING EMPLOYEE_INFO_WKSP, EMPLOYEE_INFO_COMPARE_WKSP, 
        CONTROL_WORKSPACE; 
  IF (CONTROL_WORKSPACE.ERROR_STATUS_FIELD EQ "CHNG") 
    THEN 
      MOVE "Changed by another user.  Ctrl/Z to repeat, PF4 to quit." TO 
          CONTROL_WORKSPACE.MESSAGEPANEL; 
    ELSE 
      EXIT TASK;            
  END IF; 

PUT_EMPL_INFO is the name of the COBOL procedure that writes a changed record to the RMS file. It runs in EMPL_SERVER and uses the same workspaces as the retrieval procedure. The procedure and these workspaces are discussed later in the chapter.

The procedure PUT_EMPL_INFO reads this record from the RMS file and locks it. The procedure then compares this record to a copy of the original record stored in a workspace.

If the two records do not match, the record in the RMS file has been changed since the user first saw it. In that case, the user is attempting to modify an outdated version of the record. The user is notified (by means of the "changed" message) and given the opportunity to repeat (with the current version of the record) or quit (cancel the task).

If the records do match, the procedure writes the modified record to the RMS file.

The IF THEN ELSE clause tests for the CHNG value in the field ERROR_STATUS_FIELD. If the value is present, a message is stored in the MESSAGEPANEL field, and the task moves on to the third exchange step to display the message. Otherwise, if the CHNG value is not in the workspace field, control passes to the ELSE statement and ends the task successfully.

8.2.5 Defining the Third Exchange Step

The third exchange step is nearly the same as the second exchange step in the data entry task discussed in Chapter 7. The purpose of this step is to display an error message, if the user tries to modify a record that another user just changed.

Add the following lines to your source file. To simplify referencing this step in the task, begin with the label DISPLAY_ERROR_MESSAGE:


DISPLAY_ERROR_MESSAGE: 
 EXCHANGE 
   SEND FORM RECORD CONTROL_WORKSPACE IN EMPLOYEE_INFO_LABEL 
   SENDING CONTROL_WORKSPACE 
   WITH RECEIVE CONTROL QUIT_WORKSPACE; 
 ACTION IS 
   IF (QUIT_WORKSPACE.QUIT_KEY EQ " FQUT") 
   THEN EXIT TASK; 
   ELSE REPEAT TASK; 
   END IF; 

8.2.6 Completing the Task Definition

To complete the inquiry/update task definition, you need to add some lines at the beginning of your file and at the end of your file. These lines define the block step and the remaining elements of the definition. As described in Section 7.4.4, the block step consists of the exchange and processing steps, which constitute the block work.

  1. Add these lines at the beginning of your file:


     
    REPLACE TASK EMPLOYEE_INFO_UPDATE_TASK 
    USE WORKSPACES 
     EMPLOYEE_INFO_WKSP, 
     EMPLOYEE_INFO_COMPARE_WKSP, 
     QUIT_WORKSPACE, 
     CONTROL_WORKSPACE; 
     
    BLOCK WORK WITH FORM I/O 
     
    

    REPLACE is an ADU command that stores a new task definition in CDD (creating a new definition or replacing an old one). Placing this command inside the task definition allows you to run this task definition (EMPLOYEE_INFO_UPDATE_TASK) as a command file in ADU (see Section 8.3).
    The WORKSPACES clause names the workspaces used in the task. In the processing steps, you use EMPLOYEE_INFO_COMPARE_WKSP as the workspace that stores a copy of the displayed record.
    The BLOCK WORK clause marks the beginning of the work that takes place within the block step.

  2. Add these lines at the end of your file:


     
    END BLOCK WORK; 
     
    END DEFINITION; 
    

    The END BLOCK WORK clause ends the work done within the block step.

  3. Your definition for the inquiry/update task, EMPLOYEE_INFO_UPDATE_TASK.TDF, is now complete. Save your file and exit the editor.

8.3 Compiling the Task Definition

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


    $ ADU
    

  2. When you issue 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 definition file to ADU:


    ADU> @EMPLOYEE_INFO_UPDATE_TASK.TDF
    

    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 you typed the definition exactly as shown. In particular, check that you used the appropriate punctuation.

  4. Exit from ADU.

8.4 Defining COBOL Procedures

The procedures used in the inquiry/update task are similar in many respects to the COBOL procedure EMPLOYEE_INFO_ADD.COB, which is called from the data entry task discussed in Chapter 7. Consequently, this section does not discuss the basic details again. This section concentrates instead on the processing and error handling in the Procedure Division of each program.

The first processing step in the inquiry/update task calls a COBOL procedure that retrieves a record from an RMS file. (You must retrieve the record before calling DECforms to display it.) This COBOL procedure is called EMPLOYEE_INFO_UPDATE_GET.COB.

The second processing step calls a COBOL procedure that writes the updated record to the RMS file. This COBOL procedure is called EMPLOYEE_INFO_UPDATE_PUT.COB. The following sections explain these two procedures.

8.4.1 Defining the Retrieval Procedure

The Identification Division, the Environment Division, and the File Section of the Data Division for the retrieval procedure are almost identical to those for the data entry procedure (see Example 7-1). The only difference is the PROGRAM-ID, which for the retrieval procedure is GET_EMPL_INFO. Because the data entry and retrieval procedures use the same RMS file, they must define the file identically in the SELECT and FD statements.

Create the COBOL retrieval procedure as follows:

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

Example 8-1 COBOL Retrieval Procedure

 
***************************************************************** 
IDENTIFICATION DIVISION. 
PROGRAM-ID. GET_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 INTO EMPLOYEE_INFO_LINKAGE_WKSP 
      ALLOWING NO OTHERS.  
    MOVE EMPLOYEE_INFO_WKSP TO EMPLOYEE_INFO_COMPARE_WKSP. 
 
100-EXIT-PROGRAM. 
    UNLOCK EMPLOYEE-FILE. 
    EXIT PROGRAM.                               

Recall that the Linkage Section lists the workspaces that ACMS passes to the procedure. The linkage workspace and the file workspace must have different names; therefore, the COPY statement includes the REPLACING clause to assign a different name to the EMPLOYEE_INFO_WKSP workspace. Like the data entry procedure, the retrieval procedure also uses CONTROL_WORKSPACE for error handling and reporting.

In the retrieval procedure, you make a copy of the record displayed to the user and store it in another workspace. The copied record is called EMPLOYEE_INFO_COMPARE_WKSP, and ACMS passes it to the update procedure to be compared with the corresponding record in the RMS file. If the the record in the RMS file has changed since this task began, ACMS notifies the user that the displayed record is no longer current.

In the Main Section of the Procedure Division, the retrieval procedure performs the following actions:

8.4.2 Compiling the Retrieval Procedure

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


$ COBOL/DEBUG/LIST EMPLOYEE_INFO_UPDATE_GET
$

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


Previous Next Contents Index