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.

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 $

For more information on testing and debugging tasks, see Compaq ACMS for OpenVMS Writing Server Procedures. For information on using the OpenVMS Debugger, consult the OpenVMS Debugger Manual.

In this chapter, you learn how to write the application definition. You then build this definition into an application database that ACMS uses at run time.

10.1 Defining the Application

An ACMS application controls one or more task groups, each of which contains related tasks that may share servers. In the application definition, you describe characteristics that control the tasks, the servers, and the application. ACMS provides defaults for most of the control characteristics that an application requires.

You create the application definition as a source file of ADU commands in the same manner that you created the task and task group definitions earlier.

10.1.1 Application Characteristics

To begin writing the application definition, follow these steps:

1. Use a text editor to create a source file for the application definition. Name the file EMPLOYEE_INFO_APPL_xxx.ADF, filling in your initials or other unique characters for the xxx part of the name. Creating a unique application name avoids conflicts with the applications of others who may be entering this tutorial on your system. (If you copy the file EMPLOYEE_INFO_APPL_xxx.ADF from the online source files, rename it to substitute your initials for xxx. Also, edit this file to make the same name change in the first line of the file.)
2. Begin your file by entering the following lines:

   REPLACE APPLICATION EMPLOYEE_INFO_APPL_xxx AUDIT; APPLICATION USERNAME IS EMPLOYEE_EXC;

   
   The AUDIT clause directs ACMS to collect audit trail information for the application. This information is useful for determining how an ACMS system and its tasks and applications are being used. The ACMS Audit Trail Logger gathers statistics about an active ACMS system and records them in the audit trail log file. This file, which is named SYS$ERRORLOG:ACMSAUDIT.LOG by default, records such information as task selections, task cancellations, user logins and logouts, and application starts and stops.
   At run time, ACMS uses an OpenVMS process called an Application Execution Controller (EXC) for each application. The EXC executes the task and performs task flow control. The APPLICATION USERNAME clause specifies the user name EMPLOYEE_EXC for the Application Execution Controller. Chapter 12 describes how your system manager creates the account EMPLOYEE_EXC.

Every server in an application has an OpenVMS user name. By default, a server uses the application user name as its OpenVMS user name. For most applications, however, use a different OpenVMS account for the server, because the server usually requires fewer privileges and lower quotas than an application. The application definition specifies the name EMPL_SERVER. Chapter 12 describes how your system manager creates the account EMPL_SERVER.

Add the following lines to your source file:

SERVER DEFAULTS ARE AUDIT; USERNAME IS EMPL_SERVER; MINIMUM SERVER PROCESSES IS 1; MAXIMUM SERVER PROCESSES IS 1; END SERVER DEFAULTS;

The AUDIT clause generates audit trail information for the server. The USERNAME clause names EMPL_SERVER as the account in which the server runs.

ACMS lets you control both the minimum and maximum number of server processes used for your application. Servers are serially reusable, so they can be created once and used several times by the application. The MINIMUM SERVER PROCESSES and MAXIMUM SERVER PROCESSES clauses specify that only one server process be created for the application. Specifying the same number for the minimum and the maximum can greatly improve the performance of your application, provided that the number of processes is adequate for the number of users.

10.1.3 Task Characteristics

The only required task characteristic is the name of every task group in the application. Optional task characteristics specify which users can run which tasks and whether audit trail information is recorded for the tasks. This tutorial application is simple enough that all users can be allowed access to all tasks.

1. Add these lines to your source file:

   TASK DEFAULTS ARE AUDIT; END TASK DEFAULTS; TASK GROUPS ARE EMPLOYEE_INFO_TASK_GROUP: TASK GROUP FILE IS "xxx_FILES:EMPLOYEE_INFO_TASK_GROUP.TDB"; END TASK GROUPS; END DEFINITION;

2. Your definition for the application definition, EMPLOYEE_INFO_APPL_xxx.ADF, is now complete. Save your file and exit the editor.

Compile your source file after exiting the editor. Invoke ADU and submit the file EMPLOYEE_INFO_APPL_xxx.ADF as follows:

$ ADU ADU> SET LOG ADU> SET VERIFY ADU> @EMPLOYEE_INFO_APPL_xxx.ADF

If ADU detects syntax errors in your application definition, you must exit ADU and edit the source file to correct the errors. Then reenter ADU and resubmit the file. Repeat this sequence 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.

10.3 Building the Application

Next, build the application with the ADU BUILD command and the APPLICATION keyword:

ADU> BUILD APPLICATION EMPLOYEE_INFO_APPL_xxx

This command produces an application database file in your default OpenVMS directory. This file is sometimes called the ADB file because .ADB is the default file type (in this case, your EMPLOYEE_INFO_APPL_xxx.ADB file).

If the BUILD command succeeds, ADU displays a "Writing ADB" message.

If the BUILD command fails, ADU issues error messages and redisplays the ADU> prompt. Continue to correct the errors and resubmit the application to ADU until the application processes without errors.

Exit from ADU.

This chapter describes how to write the menu definition. You then build this definition into a menu database that ACMS uses at run time.

11.1 Defining the Menu

In the menu definition, you describe the contents of the top-level menu displayed to users. You now define the ACMS menu from which terminal users can select either the data entry task or the inquiry/update task. ACMS provides a standard menu format.

To define a menu, specify a name for each entry and the name of the task (and application) to which the entry corresponds. A menu entry can also be the name of another menu, which allows you to create a hierarchy of menus for an application. However, this tutorial uses only one menu.

Create the menu definition as a source file of ADU commands in the same manner that you created previous ACMS definitions.

To begin writing the menu definition, follow these steps:

1. Use a text editor to create a source file for the menu definition. Name the source file EMPLOYEE_INFO_MENU.MDF.

   Note If you copied this file from the online source files, edit the file to change two occurrences of EMPLOYEE_INFO_APPL_xxx to your unique application name.

2. Begin your file by entering the following lines:

   REPLACE MENU EMPLOYEE_INFO_MENU HEADER IS " Personnel Administration System";

   
   In the HEADER clause, you specify a one- or two-line title, enclosed in quotation marks, for the top of the menu. When ACMS displays the menu, the title, Personnel Administration System, preceded by the given number of spaces, appears at the top. Note that you must use spaces to center a menu title; you cannot use tabs.

3. Add the following lines to your source file:

   ENTRIES ARE "ADD" : TASK IS EMPLOYEE_INFO_ADD_TASK IN EMPLOYEE_INFO_APPL_xxx; TEXT IS "Add new employee record"; "UPDATE" : TASK IS EMPLOYEE_INFO_UPDATE_TASK IN EMPLOYEE_INFO_APPL_xxx; TEXT IS "Display or update employee record"; END ENTRIES;

   
   You use the ENTRIES clause to specify the entries on the menu, the type of entry, and any explanatory text. Each entry you specify is either a task or another menu. If it is a task, ACMS runs the specified task from the specified application when the user selects that entry. In the ENTRIES clause here, you give each entry a name such as ADD, specifying each entry's type (TASK), its name in the application database, and the name of the application (the menu definition can point to tasks from different applications).

4. To end the menu definition, enter the following line at the end of the file:

   END DEFINITION;

5. Your source file for the menu definition, EMPLOYEE_INFO_MENU.MDF, is now complete. Save your file and exit the editor.

Compile your source file after exiting the editor. Invoke ADU and submit the file EMPLOYEE_INFO_MENU.MDF as follows:

$ ADU ADU> SET LOG ADU> SET VERIFY ADU> @EMPLOYEE_INFO_MENU.MDF

If ADU detects syntax errors in your menu definition, you must edit the source file to correct the errors and resubmit it. Repeat this sequence until the file processes without errors. If you receive error messages, make sure that you typed the definition exactly as shown. In particular, check that you used the appropriate punctuation.

Exit from ADU.

At this point, your default CDD directory contains the definitions for the application, the menu, the task group, the data entry task, and the inquiry/update task. Use the CDO DIRECTORY command to verify that these definitions exist:

$ CDO CDO> DIRECTORY CONTROL_WORKSPACE;1 RECORD EMPLOYEE_INFO_ADD_TASK;1 ACMS$TASK EMPLOYEE_INFO_APPL_xxx;1 ACMS$APPLICATION EMPLOYEE_INFO_MENU;1 CDD$MENU EMPLOYEE_INFO_RECORD;1 RECORD EMPLOYEE_INFO_TASK_GROUP;1 ACMS$TASK_GROUP EMPLOYEE_INFO_UPDATE_TASK;1 ACMS$TASK EMPLOYEE_INFO_WKSP;1 RECORD EMPL_CITY;1 FIELD EMPL_NAME;1 FIELD EMPL_NUMBER;1 FIELD EMPL_STATE;1 FIELD EMPL_STREET_ADDRESS;1 FIELD EMPL_ZIP_CODE;1 FIELD ERROR_STATUS_FIELD; FIELD MESSAGEPANEL; FIELD QUIT_KEY;1 FIELD QUIT_WORKSPACE;1 RECORD CDO>

To look at the contents of a field or a record, you can use the SHOW FIELD or SHOW RECORD command, followed by the name of the record or field.

11.3 Building the Menu

Build the menu with the ADU BUILD command and the MENU keyword:

$ ADU ADU> BUILD MENU EMPLOYEE_INFO_MENU

This command produces a menu database file in your default OpenVMS directory. The file is named EMPLOYEE_INFO_MENU.MDB.

If the BUILD command succeeds, ADU displays a "Writing MDB" message.

If the BUILD command fails, ADU issues error messages and redisplays the ADU> prompt. You must correct the errors and resubmit the menu to ADU, repeating this sequence until the menu processes without errors.

Exit from ADU.