Although a task executes successfully under the ACMS Task Debugger, it can sometimes encounter problems when it is running in the ACMS run-time environment. You can request a server process dump in the event that a server abnormally terminates processing. Using the server process dump, you can trace the location of a software error that occurs while the server is executing in a production environment.

To enable server process dumps, use the SERVER PROCESS DUMP clause in the application definition:

SERVER ATTRIBUTES ARE SMITHSRV: SERVER SMITHSRV IN ACMSTEST_GROUP; SERVER PROCESS DUMP; END SERVER ATTRIBUTES;

If the server process terminates abnormally and you have enabled server dumps, ACMS saves the context of the process at the point where the error occurs and writes it to a dump file.

To analyze the output from a server process dump file, use the command ANALYZE/PROCESS_DUMP. For information on using this command, consult OpenVMS Debugger Manual.

For more information on requesting server process dumps, see Compaq ACMS for OpenVMS Writing Server Procedures.

11.5 Controlling Applications

In addition to controlling an application by assigning server and task attributes, you can assign control characteristics to the application itself. These characteristics determine processing for the application including:

• User name for the EXC
• Whether or not application events are audited
• Default directory for the EXC
• Logical names and name tables for the EXC
• Default file name for the application database
• Maximum number of server processes the application can have active at one time
• Maximum number of task instances the application can have active at one time

ACMS assigns default values to all user names except the EXC user name. Every EXC has a user name that you assign in the application definition with the APPLICATION USERNAME clause. The execution controller user name determines:

• How the work done by the execution controller process is logged by the OpenVMS ACCOUNTING facility
• The privileges, priority, and quotas assigned to the execution controller

The following application definition assigns the user name PERSONNEL to the execution controller:

APPLICATION USERNAME IS PERSONNEL; TASK GROUP IS ADMINISTRATION_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:ADMRMSCOB.TDB"; END TASK GROUP;

The user name that you assign to the Application Execution Controller must be a valid OpenVMS user name consisting of 1 to 12 alphanumeric characters, including underscores. The user whose user name you assign to the Application Execution Controller must be an authorized OpenVMS user.

11.5.2 Auditing Applications

ACMS provides the audit trail log to record application events such as application starts and stops, and to write out reports on application events. You use the AUDIT clause to control whether events are recorded in the audit trail log. For example:

AUDIT; APPLICATION USERNAME IS PERSONNEL; TASK GROUPS ARE DEPARTMENT_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:DEPRMSCOB.TDB"; ADMINISTRATION_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:ADMRMSCOB.TDB"; END TASK GROUPS; END DEFINITION;

In this example, the audit trail log records application events for the Personnel application whenever that application is run. The default value for the AUDIT subclause is NOAUDIT. For a list of the events written to the audit trail log, see Compaq ACMS for OpenVMS Managing Applications. Even if you do not specify the AUDIT clause, ACMS records all failure statuses.

11.5.3 Assigning Application Default Directories

ACMS assigns a default directory to every Application Execution Controller process directory. The default value comes from the directory that you assign to the user name of an application.

You can assign a default directory for an execution controller if you want to override the default directory assignment because the execution controller needs a different default directory from the one assigned to the application user name in the SYSUAF file. By default, ACMS assigns USERNAME DEFAULT DIRECTORY for the DEFAULT DIRECTORY clause. When the default is in effect, ACMS assigns the execution controller the default directory that is in the SYSUAF entry for the application user name.

If you do not supply full file specifications for task group databases, request libraries, or message files in the application and task group definition, ACMS uses the default directory assigned to the application user name in the SYSUAF file to find them.

You can name a default device and directory with the DEFAULT DIRECTORY subclause. For example:

DEFAULT DIRECTORY IS SYS$SAMPLE; USERNAME IS PERSONNEL; TASK GROUP IS ADMINISTRATION_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:ADMRMSCOB.TDB"; END TASK GROUP;

This definition assigns the device and directory pointed to by the logical name SYS$SAMPLE as the default directory for the execution controller in the Personnel application. You can name a directory specification and device name rather than a logical name, but using logical names lets you change directory locations without redefining and rebuilding the application. You can also use the LOGICAL NAMES subclause to define the name.

11.5.4 Assigning Application Logical Names

It is important to define logical names for an EXC process if that process needs to find task group databases, request libraries, or message files by logical name. Logical name translations must be available to the EXC. There are several ways to make the names available:

• Define the logical names as system logicals.
• Define the logical names as group logicals. Make sure the logical names are available to the group UIC for the EXC process.
• Use the APPLICATION LOGICAL NAMES subclause to define process logical names for the execution controller process.
• Use logical name tables.

Logicals assigned with the LOGICAL NAMES subclause are available only to the execution controller. List each logical name and its equivalent name. For example:

APPLICATION LOGICAL NAME IS EMPLOYEE_MESSAGES = "ACMS$SAMPLE:EMPMSG.EXE"; APPLICATION USERNAME IS PERSONNEL; TASK GROUP IS ADMINISTRATION_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:ADMRMSCOB.TDB"; END TASK GROUP; END DEFINITION;

In this example, the LOGICAL NAMES clause defines the logical name EMPLOYEE_MESSAGES for the file ACMS$SAMPLE:EMPMSG.EXE. If a logical name or equivalent name does not conform to the rules for identifiers, enclose it in quotation marks.

ACMS assigns the logical names SYS$LOGIN, SYS$DISK, and SYS$SCRATCH by default.

For information on using logical name tables, see Section 11.4.5.

11.5.5 Assigning Application Database Files

When you build an application definition, you can include the name of the application database file with the BUILD command. The BUILD command translates the CDD version of the definition into the application database file. For example:

ADU> BUILD APPLICATION PERSONNEL_APPL1 SYS$SAMPLE:PERSONNEL ADU>

In this example, PERSONNEL_APPL1 is the CDD application object. The application database file is SYS$SAMPLE:PERSONNEL.ADB.

To simplify the BUILD command, you can include the default database file name in the application definition instead of putting it on the command line. You name the file in the application definition with the DEFAULT APPLICATION FILE clause. For example:

DEFAULT APPLICATION FILE IS PERSONNEL; USERNAME IS PERSONNEL; TASK GROUP IS ADMINISTRATION_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:ADMRMSCOB.TDB"; END TASK GROUP; END DEFINITION;

The application database file you are naming for the default is PERSONNEL. The default file type is .ADB. If you do not include a device or directory, ADU uses your default device and directory when you build the application. The default device and directory are those of the process at work when the application is built, rather than those in effect when the application definition is created.

If ADU does not find an application database file on the BUILD command line, it looks for the name in the application definition. If you have not used the DEFAULT APPLICATION FILE clause, ADU derives the file name from the full CDD given name of the application, including underscores (_) and dollar signs ($), and a default file type of .ADB, to create the application database file name.

The DEFAULT APPLICATION FILE clause accepts a full file specification so that ADU can control the placement of the application database file. Once you build the application, you must move the application database file to ACMS$DIRECTORY or use the INSTALL command to copy the application database into ACMS$DIRECTORY before you can start the application.

11.5.6 Controlling the Number of Server Processes

It is important to control the number of server processes active in your application in order to make the best use of your system resources. Because every application requires a slightly different allocation of system resources, experiment with the number of server processes that is best for your application. For more information on determining the best number of server processes for your application, see Compaq ACMS for OpenVMS Managing Applications.

You can control the number of server processes allowed in an ACMS application from two places in the application definition:

• MAXIMUM SERVER PROCESSES subclause in the SERVER DEFAULTS or SERVER ATTRIBUTES clauses
• MAXIMUM SERVER PROCESSES clause at the application level

For example:

DEFAULT APPLICATION FILE IS "ADRMSCAPP.ADB"; MAXIMUM SERVER PROCESSES IS 2; APPLICATION USERNAME IS PERSONNEL; SERVER DEFAULTS ARE AUDIT; MAXIMUM SERVER PROCESSES IS 2; MINIMUM SERVER PROCESSES IS 0; END SERVER DEFAULTS; TASK GROUP IS ADMINISTRATION_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:ADMRMSCOB.TDB"; END TASK GROUP; END DEFINITION;

In the SERVER DEFAULTS clause, the MAXIMUM SERVER PROCESSES is set to 2. In the MAXIMUM SERVER PROCESSES clause at the application level, the number of server processes is also set to 2.

When an application is started, ACMS checks three values to determine the actual maximum number of server processes:

• Value your system manager sets for the maximum number of OpenVMS processes OpenVMS can create (MAXPROCESSCNT)
• Value of the MAXIMUM SERVER PROCESSES clause at the application level
• Sum of the values of all the MAXIMUM SERVER PROCESSES subclauses for all the servers in the application

ACMS first compares the value of all the MAXIMUM SERVER PROCESSES subclauses with the value of the MAXIMUM SERVER PROCESSES clause at the application level. ACMS takes the smaller value of the two and compares it to the maximum number of OpenVMS processes available. The smaller of these two values is the number assigned for the overall maximum number of server processes in the application.

The number you assign with the MAXIMUM SERVER PROCESSES clause for the application must be greater than the sum of the MINIMUM SERVER PROCESSES subclauses for all the servers in the application.

When you start an application, the EXC determines the smallest value for the maximum server processes. Then it creates a table for each server. The tables can become large enough to affect the size of the EXC, and the size of the EXC affects your system.

You can make sure that ACMS does not use up all of the process slots on your operating system table by setting a MAXIMUM SERVER PROCESSES value in the application that is less than the maximum number of OpenVMS processes allowed on your system.

If the execution controller cannot start a server process because no more OpenVMS processes are available on the system, the execution controller cancels tasks. If there are no available server processes in the ACMS system, the execution controller holds a task until a server process becomes available.

You can experiment with the number of server processes to get an idea of how many server processes are best for your application and system. The default value for MAXIMUM SERVER PROCESSES is unlimited. Try the default value and then decrease the number of server processes. Too many server processes can degrade the performance of your system. Too few may decrease throughput. Set a limit that does not degrade system performance but still lets users complete their work as quickly as possible.

11.5.7 Controlling the Number of Task Instances

The value you define with the MAXIMUM INSTANCES clause controls the number of task instances that can be active at one time. The number of task instances allowed on your system affects the system's performance. For example:

DEFAULT APPLICATION FILE IS "ADRMSCAPP.ADB"; MAXIMUM SERVER PROCESSES IS 2; MAXIMUM TASK INSTANCES IS 25; TASK GROUPS ARE DEPARTMENT_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:DEPRMSCOB.TDB"; ADMINISTRATION_COBOL_TASK_GROUP : TASK GROUP FILE IS "ACMS$EXAMPLES:ADMRMSCOB.TDB"; END TASK GROUPS;

By default, ACMS allows as many task instances as there are task selections. In most cases, you can use the default value, but there are two reasons to define a lower value for MAXIMUM TASK INSTANCES:

• To prevent the EXC from using up its OpenVMS quotas
• To improve performance if a large number of active tasks are causing poor performance

The execution controller assigns quotas to each task from the pool of quotas that it has available. If the number of task instances is greater than the value of MAXIMUM TASK INSTANCES, ACMS cancels additional task selections. To avoid overloading your system and thereby reducing performance, set a reasonable task limit with the MAXIMUM TASK INSTANCES clause. Because the needs of different applications vary, you must experiment with this value to find the best setting for the applications you have.

After you write an application definition, you must store the definition in the CDD and then process the definition, using ADU, to create an application database that ACMS can use at run time.

11.6 Modifying an Active Application

ACMS allows you to modify certain environmental attributes for the following components of an active ACMS application:

• Application attributes
• Server attributes
• Task attributes

Using the ACMS/MODIFY APPLICATION command, you can perform the following functions:

• Enable or disable application, server, and task auditing
• Enable or disable tasks
• Adjust the minimum and maximum number of server processes for a particular server
• Adjust server creation and deletion intervals
• Adjust server creation and deletion delays
• Adjust the maximum number of task instances and server processes for an application
• Adjust server monitoring intervals
• Adjust transaction timeout limits

Changes you make with the ACMS/MODIFY APPLICATION command affect only the current application and do not permanently affect the ADB. Parameters changed with the ACMS/MODIFY APPLICATION command are reset when you restart an application. To change attributes permanently, you must modify and rebuild the application definition.

For more information on modifying active applications, consult Compaq ACMS for OpenVMS Managing Applications.

11.7 Controlling Application Failover

ACMS is capable of keeping applications available in the event of a system failure. The ACMS/REPROCESS APPLICATION_SPEC command redirects all subsequent task selections to the application pointed to by the applications specification.

For example, suppose that:

• The application specification payroll points to an application in which tasks are being selected
• You have defined PAYROLL as a logical name for A::PAYROLL

To force subsequent task selections for PAYROLL to go to node B, you must:

1. Redefine PAYROLL as B::PAYROLL
2. Issue the command to redirect future task selections:

   $ ACMS/REPROCESS APPLICATION_SPEC PAYROLL

By using search lists for application specifications, you can provide for automatic change to one or more backup applications in the event of a system failure. When the original system becomes available, you can use the ACMS/REPROCESS APPLICATION_SPEC command to change back to the original application.

For more information on application failover, see Compaq ACMS for OpenVMS Managing Applications.

After you define the tasks, task groups, and application as described in the previous chapters, you need to write menu definitions to describe how your application looks to users.

You can define two types of entries to display on a menu: tasks and menus. Tasks do the work of an application; menus display tasks and other menus for selection by users. Because a user can select one menu from another menu, you can create a menu hierarchy or tree. There are three parts to creating a menu hierarchy for your application:

• Planning the menu structure of your application
• Deciding whether to use DECforms or TDMS to display each menu in your menu structure
• Writing definitions for menus in the application

You can create and use a menu tree before any applications exist. This feature is useful for early tests of how your menus and menu tree will look to users. Before you write menu definitions, plan the menu structure that best represents the work users need to do with your application.

For each menu in a menu tree, you need to decide whether you want to use DECforms or TDMS to display your menu. You can use a combination of DECforms and TDMS to display the menus in one menu tree.

12.1 Planning the Menu Structure

The ACMS menu structure provides a great deal of flexibility for presenting your application to users. ACMS menus are organized in a hierarchical structure, much like the OpenVMS directory structure. A top menu points to menus and tasks. Users can select either a menu or a task to run from the top menu.

You can display the tasks of an application on a single menu or on more than one menu. This choice depends on how you want to present the tasks to users.

One menu or menu tree can point to tasks in several applications. Several menus or menu trees can point to tasks in a single application. Finally, you can create any combination of these two cases.

Figure 12-1 shows the hierarchical ACMS menu structure.

Figure 12-1 The ACMS Menu Structure

Using a fictional personnel application as an example, suppose you had two kinds of tasks in the application:

• REVIEW_HISTORY and REVIEW_SCHEDULE tasks, which are restricted tasks that deal with employee performance reviews
• Utility tasks, such as an LSEDIT task to run the LSE editor and a DATR task to run the DATATRIEVE procedure DUE

You can create a menu hierarchy that includes three menus: one to display the REVIEW_HISTORY and REVIEW_SCHEDULE tasks, one to display the utility tasks, and one from which the other two menus can be selected. Example 12-1 shows the menu definition for the last of these menus.

Example 12-1 Menu Definition for the Personnel Menu

HEADER IS " PERSONNEL MENU"; ENTRIES ARE REVIEW : MENU IS EXAMPLES_DEFINITIONS.REVIEW_MENU; TEXT IS "Review Menu"; UTILITY : MENU IS EXAMPLES_DEFINITIONS.UTILITY_MENU; TEXT IS "Utility Menu"; END ENTRIES; END DEFINITION;

Figure 12-2 shows the menu that is displayed by the top menu definition after it is processed. The letter M indicates that the menu selection is another menu; if the letter T appears it indicates that the menu selection is a task.

Figure 12-2 Personnel Menu

Once you plan a menu structure for your application, you can write menu definitions to describe what the user sees on the menus. In the menu definition you:

• Assign a title, or header, to a menu
• Name tasks and menus to be listed on the menu
• Include descriptive text for each task and menu
• Assign default application files for tasks on the menu
• Assign default menu database files for the build process
• Assign WAIT/DELAY characteristics for tasks
• Reference DECforms control text responses or TDMS requests for customized menus

ACMS provides both a DECforms form and a TDMS request for ACMS to use when displaying menus. ACMS takes the specific information that you enter about a menu (heading, titles of menus and tasks listed, and so on) from your menu database (.MDB) and displays that information in the format of either the DECforms or TDMS request. (See Section 12.2.9 for details on how to determine which forms product ACMS uses.)

Both the DECforms and TDMS menu formats allow you to create menus that serve the needs of your users. By specifying menu elements in your menu definition, you can create a menu to suit almost any application. After you define a menu, you use ADU to create a menu database (.MDB) to use in your application. (See Section 12.3 for an explanation of how to build a menu database.)

If you need to use a menu format different from the one provided with either DECforms or TDMS requests, you can modify the standard menu format. See Appendix A and Appendix B for information on modifying menus displayed by DECforms and TDMS requests.