Figure 7-8 Sample Panel with One Data Field Picture

EMPL_NAME X(30) EMPL_STREET_ADDRESS X(30) EMPL_CITY X(20) EMPL_STATE X(2) EMPL_ZIP_CODE X(10)

Figure 7-9 shows the results of defining all the fields in the panel.

Figure 7-9 Sample Panel with Data Field Pictures

Panel editing finished.

DECforms redisplays the FDE Main Menu, shown in Figure 7-2.

You now edit the form IFDL source file to include other definitions and special instructions. Note that DECforms automatically added a number of statements to your IFDL file when you exited FDE. For example, the Form Data section and the field descriptions in that file are a result of the data fields that you created interactively with DECforms.

To edit the form IFDL source file, follow these steps:

1. Use a text editor to open your IFDL source file named EMPLOYEE_INFO_FORM.IFDL. When using the LSE editor, for example, enter the following command:

   $ LSEDIT EMPLOYEE_INFO_FORM.IFDL

2. Enter a form record description in the IFDL source file following the declaration of the form data items. Enter the following lines after the line "End Data":

   Form Record EMPLOYEE_INFO_RECORD Copy EMPLOYEE_INFO_RECORD From Dictionary End Copy End Record

   
   The fields in the form record description here must correspond to the form data items defined above the description in the file. In this tutorial, you create a one-to-one correspondence between the form data items and the fields in EMPLOYEE_INFO_RECORD, which you previously entered in CDD. The COPY...FROM DICTIONARY clause copies that record from CDD.
   This one-to-one correspondence of record fields and data items is not a requirement, however. In more complex applications, the fields in a form record description are usually a subset of the list of form data items.

3. Immediately following this definition, enter another form record definition to correspond to a workspace definition that you enter later in CDD (in Section 7.3.5):

   Form Record CONTROL_WORKSPACE ERROR_STATUS_FIELD Character(4) MESSAGEPANEL Character(80) End Record

   
   In the data entry task, you need to inform users if they enter an employee number that already exists. A COBOL procedure called from the task checks for this error condition. If the error occurs, the procedure moves the value DUPL into the field ERROR_STATUS_FIELD in the record CONTROL_WORKSPACE.
   In your task, you can test the field ERROR_STATUS_FIELD for the DUPL value. If this value is in the field, you can place an error message in the MESSAGEPANEL field of CONTROL_WORKSPACE. (The processing step in the task definition discusses this error handling in more detail; see Section 7.4.2.)
   A MESSAGEPANEL is a special field in a form record. When you specify a MESSAGEPANEL field in a form record, any data associated with this field is automatically displayed in a message panel, which appears on any panel you have created. If you do not create your own message panel (this tutorial does not), DECforms uses the default message panel, which is the last line (line 24) on a panel display.

4. Enter the following lines after the line "Size 24 Lines by 80 Columns":

   Function QUIT_KEY Is %PF4 End Function

   
   This declares a function named QUIT_KEY and binds that name to [PF4]. By declaring a function response for QUIT_KEY in the next step, you allow the user to stop the task by pressing [PF4].

5. A function response describes the action you want to occur when a user presses a function key. Enter the following lines after the line "End Function". (Note that there is a space before the F in FQUT.)

   Function Response QUIT_KEY Remove All Return " FQUT" End Response

   
   If a user presses [PF4] while entering employee information in the panel, the function response directs DECforms to remove all viewports from the screen and return the value " FQUT" to ACMS. Within ACMS, the task definition tests a control-key workspace and performs some action based on receiving that value. The space and the F in " FQUT" conform to a special DECforms format required to return a receive-control text string. The QUT in this 5-character string are arbitrary characters.

6. To describe other actions that you want to occur at certain times while the application is running, enter the following response lines in the IFDL source file after the line "End Response" of the QUIT_KEY function response:

   Disable Response Request Exit Response Remove All End Response End Response Receive Response EMPLOYEE_INFO_RECORD Reset All Display EMPLOYEE_INFO_PANEL Activate Panel EMPLOYEE_INFO_PANEL End Response Transceive Response EMPLOYEE_INFO_RECORD EMPLOYEE_INFO_RECORD Display EMPLOYEE_INFO_PANEL Activate Panel EMPLOYEE_INFO_PANEL Deactivate Field EMPL_NUMBER on EMPLOYEE_INFO_PANEL Position to Field EMPL_NAME on EMPLOYEE_INFO_PANEL End Response Send Response CONTROL_WORKSPACE Activate Wait Signal End Response

   
   The Disable Response removes the current screen display by removing all viewports when the form is disabled. This prevents old data from appearing on the screen during transitions from one form to another.
   The Receive Response prepares a DECforms panel for user input whenever the data entry task definition ( Section 7.4) executes its RECEIVE FORM RECORD EMPLOYEE_INFO_RECORD statement. The Receive Response resets all data fields to spaces (clearing any old data). It then displays the specified panel in its viewport and activates all the data fields on that panel (allowing user input to every field on the panel).
   The Transceive Response prepares a DECforms panel for user input whenever the Inquiry/Update Task definition ( Section 8.2) executes its TRANSCEIVE FORM RECORD EMPLOYEE_INFO_RECORD statement. The Transceive Response displays the specified panel and activates all the data fields on that panel. Because the employee number is the record's key field, it cannot be modified. The Deactivate statement prevents the user from modifying the EMPL_NUMBER field when that record is displayed. The Position statement places the cursor on the first field, EMPL_NAME, that the user is allowed to modify.
   The Send Response causes DECforms to wait for the user to press a function key whenever ACMS sends DECforms a message via the record CONTROL_WORKSPACE. For example, ACMS sends DECforms an error message if the user tries to add an employee number that already exists. DECforms displays the message, activates a wait, and produces an audible signal. The user can then press [PF4] to cancel the transaction, or [Ctrl/Z] to begin again.

7. Your EMPLOYEE_INFO_FORM.IFDL file is now complete. Save the edits made in the IFDL file, and exit from the text editor.

Whenever you edit your IFDL source file, you must translate that file into an updated binary form file to reflect the edits made in the IFDL file. DECforms stores a form internally in a binary form file (with file type .FORM).

You also need to create an object module and a shareable image of the form to use in your ACMS application.

To create a new binary form file, an object module, and a shareable image of your form, follow these steps:

1. Issue the following command to create a new binary form file:

   $ FORMS TRANSLATE EMPLOYEE_INFO_FORM.IFDL $

   
   When you issue this command, DECforms uses the most recent version of your IFDL file to create a new binary file.

2. Issue the EXTRACT OBJECT command as the first step in creating a shareable image of a form:

   $ FORMS EXTRACT OBJECT EMPLOYEE_INFO_FORM.FORM $

   
   This command creates a form object module, or .OBJ file.

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

   $ LINK/SHARE EMPLOYEE_INFO_FORM.OBJ $

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

You must now define the additional fields and records for a control workspace and a quit workspace. The following steps explain how to create the source files and how to enter these definitions in your CDD dictionary.

1. Using a text editor, create a source file called EMPLOYEE_CONTROL_FIELDS.CDO and enter the following lines. Then exit the file:

   DEFINE FIELD ERROR_STATUS_FIELD DATATYPE TEXT SIZE 4 INITIAL_VALUE IS " ". DEFINE FIELD MESSAGEPANEL DATATYPE TEXT SIZE 80.

2. Create a source file called EMPLOYEE_CONTROL_WKSP.CDO, enter the following lines, and exit the file:

   DEFINE RECORD CONTROL_WORKSPACE. ERROR_STATUS_FIELD. MESSAGEPANEL. END RECORD.

3. Create a source file called EMPLOYEE_QUIT_FIELD.CDO, enter the following lines, and exit the file:

   DEFINE FIELD QUIT_KEY DATATYPE TEXT SIZE 5 INITIAL_VALUE IS " ".

4. Create a source file called EMPLOYEE_QUIT_WKSP.CDO, enter the following lines, and exit the file:

   DEFINE RECORD QUIT_WORKSPACE. QUIT_KEY. END RECORD.

5. Execute these four source files by issuing the following commands at the CDO> prompt:

   $ CDO CDO> @EMPLOYEE_CONTROL_FIELDS CDO> @EMPLOYEE_CONTROL_WKSP CDO> @EMPLOYEE_QUIT_FIELD CDO> @EMPLOYEE_QUIT_WKSP CDO>

6. Exit from CDO.

The data entry task definition in this tutorial contains three kinds of steps:

• Exchange steps, during which information is exchanged between the terminal user and the ACMS application.
• A processing step that calls a COBOL procedure to handle the I/O interactions between the application and the database (in this case, an RMS master file). The procedures that you call from processing steps are subroutines that you write and link together with a main program module supplied by ACMS.
• A block step, which groups the exchange steps and processing steps into a unit.

The first exchange step displays a form where the user enters new data. The processing step adds a new record to the RMS file with the information the user supplied in the first exchange step. The second exchange step displays a message, if an error is encountered in the processing step.

To define a task, you use commands and clauses of the ACMS Application Definition Utility (ADU). The easiest way to use ADU is to create a source file of ADU commands with a text editor such as LSE. Then submit the file as a command file to ADU, which compiles the task definition.

7.4.1 Defining the First Exchange Step

You begin an exchange step by identifying it with the ADU keyword EXCHANGE. Following the keyword, you use a SEND, RECEIVE, or TRANSCEIVE call to DECforms, identifying the direction of exchange:

• SEND indicates that you want to send information from the ACMS application to the form.
• RECEIVE indicates that you want to receive information in the ACMS application from the form.
• TRANSCEIVE indicates that you want both to send information to the form and receive information from the form, in that order.

To define the first exchange step in the data entry task definition, follow these steps:

1. Using an editor such as LSE, create a source file for your task definition. Name the source file EMPLOYEE_INFO_ADD_TASK.TDF.

   $ LSEDIT EMPLOYEE_INFO_ADD_TASK.TDF

2. In this file, enter the following lines of this exchange step:

   GET_EMPL_INFO: EXCHANGE RECEIVE FORM RECORD EMPLOYEE_INFO_RECORD RECEIVING EMPLOYEE_INFO_WKSP WITH RECEIVE CONTROL QUIT_WORKSPACE;

   
   Use label names (such as GET_EMPL_INFO) to mark exchange and processing steps in a task. During debugging, you can then reference each step by its label name rather than by line number.
   The purpose of the first exchange step in the data entry task is to obtain user input---users enter data in response to prompts displayed on the terminal screen. In this case, the ACMS application needs to receive information from the form.
   A form record name or form record list name must appear after a SEND, RECEIVE, or TRANSCEIVE call to DECforms. That name must correspond to a form record defined in the form source IFDL. This tutorial application, for example, uses EMPLOYEE_INFO_RECORD here and in your form source file.
   You must also include one or more workspace names after the keyword RECEIVING. DECforms uses these workspaces to pass user-entered data to ACMS.
   The WITH RECEIVE CONTROL clause specifies the record containing the name of the function key defined in the form source file. In this tutorial, the function QUIT_KEY is a field in the record QUIT_WORKSPACE.

3. Next, enter a CONTROL FIELD statement:

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

   
   The CONTROL FIELD clause tests the contents of a workspace field. Here it tests the value of the QUIT_KEY field in the record QUIT_WORKSPACE. The clause lists a value that this field can have: FQUT. If the value is FQUT, the action taken is EXIT TASK, which is the ADU clause that ends the current task.

You begin a processing step by identifying it with the keyword PROCESSING. This processing step calls a procedure that adds information to an RMS file.

The processing step is located after the exchange step. Add the processing step as follows:

1. Add these clauses as the first part of your processing step:

   PROCESS_EMPL_INFO: PROCESSING CALL ADD_EMPL_INFO IN EMPL_SERVER USING EMPLOYEE_INFO_WKSP, CONTROL_WORKSPACE;

   
   As mentioned previously, when ACMS starts a processing step, it allocates a server process to handle the procedure in that step. A server process is a specialized OpenVMS process with a user name, privileges, and quotas, just like your own OpenVMS process. (This manual often refers to a server process simply as a server.)
   In the CALL clause, you specify the procedure name and the name of the server in which the procedure executes. The server process (named EMPL_SERVER here) can have any name you choose. The procedure (named ADD_EMPL_INFO here) must correspond to the PROGRAM-ID name that you specify in the COBOL procedure later in this chapter.
   The CALL clause also includes a USING phrase that names the two workspaces that this procedure uses: EMPLOYEE_INFO_WKSP, which stores the user input to be passed to the procedure for processing; and CONTROL_WORKSPACE, which holds status values and error messages.

2. Add these clauses to your processing step to handle duplicate employee number errors:

   IF (CONTROL_WORKSPACE.ERROR_STATUS_FIELD EQ "DUPL") THEN MOVE "Employee number already exists. Ctrl/Z to repeat, PF4 to quit." TO CONTROL_WORKSPACE.MESSAGEPANEL; ELSE EXIT TASK; END IF;

   
   In the data entry task, you need to include a method for reporting any errors that can occur when the processing step attempts to write the new information to the RMS file. When the ADD_EMPL_INFO procedure finishes executing, it returns a status value that indicates whether or not the procedure completed successfully.
   A common error in a data entry task occurs when the user tries to enter information for a primary key that already exists. For example, in this tutorial application, every employee is uniquely identified by an employee number (the EMPL_NUMBER field of EMPLOYEE_INFO_WKSP). If a user tries to write a new record to the RMS file with an employee number that already exists, the user receives an error message on the terminal screen.
   The ADD_EMPL_INFO procedure tests the return status value of the write operation. If the status value corresponds to the COBOL code for the duplicate primary key error, the procedure stores the value DUPL in a workspace field.
   The processing step in this task tests the field ERROR_STATUS_FIELD, using an IF clause. If that field contains DUPL, the processing step directs ACMS to move an error message to the field MESSAGEPANEL, and the task continues to a second exchange step to display the message. Otherwise, if the DUPL value is not in the workspace field, control passes to the ELSE statement, and the task ends successfully.

The purpose of the second exchange step is to display an error message if the user tries to enter an employee number that already exists in the RMS file (DUPL error). Add the second exchange step as follows:

1. The SEND statement specifies the name of the form record (CONTROL_WORKSPACE):

   DISPLAY_ERROR_MESSAGE: EXCHANGE SEND FORM RECORD CONTROL_WORKSPACE

2. The SENDING statement specifies the name of the workspace that ACMS uses to pass the error message to the form. The RECEIVE CONTROL clause specifies the name of the record that contains the QUIT_KEY field:

   SENDING CONTROL_WORKSPACE WITH RECEIVE CONTROL QUIT_WORKSPACE;

   
   The record CONTROL_WORKSPACE contains the field MESSAGEPANEL, which stores the error message corresponding to the DUPL error. DECforms receives the message from ACMS, displays the message in its default message panel, and waits for the user to take some action.

3. Enter the following ACTION clause to complete the exchange step:

   ACTION IS IF (QUIT_WORKSPACE.QUIT_KEY EQ " FQUT") THEN EXIT TASK; ELSE REPEAT TASK; END IF;

   
   The IF clause tests the value of the field QUIT_KEY. If the value is FQUT (that is, if the user presses [PF4] ), the action is to exit the task. Otherwise, if the user executes the transmit function (presses [Ctrl/Z] ), the action is to repeat the task, sending control back to the first exchange step. In this way, the user can read the error message and choose one of two actions: to end the task or to repeat it.