# Compaq ACMS for OpenVMS
Writing Applications

Previous | Contents | Index

## 11.4.5 Creating Logical Name Tables for Application Servers

Using name tables can give you the following advantages over using logical names:

- Modify logicals used by an application or server without rebuilding application definitions
- Share common logicals among servers and applications without duplicating definitions
- Reduce server process initialization time by reducing the number of server process logicals

You can specify a list of logical name tables in the application definition for reference by applications and servers. For example:

    APPLICATION NAME TABLE IS LNM$PROCESS,
                              LNM$JOB,
                              OUR_APPL_LOGICALS,
                              LNM$GROUP,
                              LNM$SYSTEM;

If you specify the APPLICATION NAME TABLE IS clause and you want the Application Execution Controller to use any of the default tables, you must name these default tables in the clause.

ACMS uses the list of logical name tables specified in the application definition to define the logical LNM$FILE_DEV in the process directory table for the appropriate server or application process. The system uses process directory tables when translating logical names for the application or server process. For example, LNM$FILE_DEV must translate to a search list of one or more logical name table names which specify the tables and the search order of the tables for translating file specifications.

If you do not specify APPLICATION NAME TABLE IS, ACMS uses the default definition of LNM$FILE_DEV in the system logical name directory table, which normally holds the process, job, group, or system logical name tables.

For more information on logical name tables, see the OpenVMS documentation set.

## 11.4.6 Controlling the Number of Server Processes

One of the important factors in improving the performance of your ACMS application is the number of active server processes allowed for that application. There must be enough server processes available for users to do their work and as few idle processes as possible. To control the number of server processes available for each server, you use the MAXIMUM SERVER PROCESSES and MINIMUM SERVER PROCESSES subclauses. For example:

    SERVER DEFAULTS ARE
      MAXIMUM SERVER PROCESSES IS 5;
      MINIMUM SERVER PROCESSES IS 1;
    END SERVER DEFAULTS;

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

For each server in the Administration task group, ACMS starts a single server process when it starts the application. As more server processes are necessary, ACMS starts them. When the number of processes for the server reaches five, ACMS does not start any more processes. Any further tasks that needs a server process must wait until a process is free. As tasks finish using the server processes, ACMS gradually decreases the number of processes for each server, until the number reaches the minimum of one.

If you define a server with USERNAME OF TERMINAL USER, MINIMUM SERVER PROCESSES must be zero for that server because when the application starts, there is no terminal user for the server. Zero is the default value for MINIMUM SERVER PROCESSES.

The best way to judge how many server processes are necessary for your application is to use the ACMS/SHOW APPLICATION command to determine how your application is using server processes. You can also check with terminal users about system response time. See Compaq ACMS for OpenVMS Managing Applications for information on the ACMS/SHOW APPLICATION command and on how to interpret the information it supplies to determine appropriate values for the MAXIMUM and MINIMUM SERVER PROCESSES subclauses. See Section 11.5.6 for information on the application-level MAXIMUM SERVER PROCESSES clause and on how ACMS determines a value for MAXIMUM SERVER PROCESSES.

## 11.4.7 Creating and Deleting Server Processes

Business environments can differ widely in the pattern of the work day. For example, a stock broker's office is busiest when the New York Stock Exchange is in session. A dairy farm depends on the cows' schedule. Your work environment may be mildly busy in the morning, slack over the lunch hour, and very busy in the afternoon. The demand for ACMS server processes may vary, too. It could be stable through the day, with only minor variations, or it could suddenly and sharply increase and just as suddenly decrease.

ACMS creates and deletes new server processes as necessary, within the parameters of maximum and minimum server processes. The queue of tasks waiting for server processes is polled at 5-second intervals, as are inactive server processes. Before beginning to create new server processes, ACMS delays 10 seconds (default) to be sure that the requirement cannot be filled when another user completes a task and releases a server process. If no server process becomes available in this way, ACMS creates new server processes at intervals of 10 seconds (default) until the maximum is reached or no tasks are waiting. Similarly, when a server process becomes inactive, ACMS delays 30 seconds (default) to be sure no other task requires it. ACMS then deletes server processes at intervals of 15 seconds (default) until the minimum is reached or there are no more inactive server processes.

ACMS provides the ability to adjust these delays and intervals according to the pattern of demand for your application. Four server control subclauses are available for this purpose:

- CREATION DELAY
- CREATION INTERVAL
- DELETION DELAY
- DELETION INTERVAL

For example, a stock broker's office runs an ACMS application, recording transactions with the New York Stock Exchange as well as customer transactions. Both tasks use the same server. Customer transactions are steady throughout the day. Stock exchange transactions, however, begin at 10 a.m. and end at 4 p.m. The application definition uses these server control subclauses:

    SERVER ATTRIBUTES ARE
      BROKER_SERVER:  CREATION DELAY IS 5;
                      CREATION INTERVAL IS 2;
                      DELETION DELAY IS 15;
                      DELETION INTERVAL IS 5;
                      MAXIMUM SERVER PROCESSES IS 10;
                      MINIMUM SERVER PROCESSES IS 0;
    END SERVER ATTRIBUTES;

The application runs the NYSE task and the CUSTOMER task in the BROKER_SERVER. The CREATION DELAY of 5 seconds means that ACMS waits 5 seconds before starting to create new processes of BROKER_SERVER, to see if old processes become available. Before 10 a.m., the requirement for server processes is usually filled in this way.

After the New York Stock Exchange opens, demand for server processes increases sharply, and tasks are kept waiting for longer than 5 seconds. ACMS then begins to create new server processes at a CREATION INTERVAL of 2 seconds (up to the maximum of 10), quickly filling the need. Demand continues steadily until 4 p.m. when instances of the NYSE task are no longer required. ACMS then waits 15 seconds, the DELETION DELAY specified, before beginning to delete inactive server processes at a DELETION INTERVAL of 5 seconds, until there are no inactive BROKER_SERVER processes (minimum number).

ACMS does not monitor the queue of waiting tasks continuously; there is a monitoring interval which can be set with the SERVER MONITORING INTERVAL application clause. The actual delay at run time includes a waiting period of up to the monitoring interval. For example, if the definition specifies a CREATION DELAY of 10 seconds and if the monitoring interval is 5 seconds, the actual delay can be anywhere from 10 to 15 seconds. Use the SERVER MONITORING INTERVAL clause with caution, however. Setting the monitoring interval too low can affect performance, causing ACMS to use its resources monitoring its own requirements.

The use of the clauses controlling minimum and maximum server processes and the associated delays and intervals enables ACMS to adapt the supply of server processes to the demands of your business environment. In using these server control subclauses, you need to strike a balance between having inactive server processes and keeping your users waiting. In most environments, the default settings provided with ACMS strike this balance. You can handle unusual situations with the server control subclauses.

## 11.4.8 Replacing an Active Server

Once an application is running, you may want to make code changes to a server. ACMS gives an application manager the capability to dynamically replace a server within an active application without affecting task execution or availability of the application.

To dynamically replace a server in an active application, follow these steps:

1. Make the necessary changes to the new server's source file.
2. Compile and relink the new server image.
3. Fully test the new image.
4. Copy the server image to the location specified by the SERVER IMAGE IS statement in the application's task definition.
5. Issue the ACMS/REPLACE SERVER command.

For example, an application manager might be integrating some code changes to an existing server called DEPRMSCOB.EXE, whose server image definition is:

    SERVER IS
      DEPARTMENT_SERVER:
        PROCEDURE SERVER IMAGE IS "ACMS$EXAMPLES:DEPRMSCOB.EXE"
               .
               .
               .
    END SERVER;

The logical name ACMS$EXAMPLES points to the directory in which ACMS expects to find the server image.

After compiling, relinking, and testing the server image, the application manager must copy the server image to the correct directory:

    $ COPY DEPRMSCOB.EXE ACMS$EXAMPLES:DEPRMSCOB.EXE

Finally, the application manager uses the ACMS/REPLACE SERVER command to activate the new server using the server name defined in the application.

    $ ACMS/REPLACE SERVER DEPARTMENT_SERVER/APPLICATION=PERSONNEL

When the application controller receives the ACMS/REPLACE SERVER command, it runs down all free server processes for the specified server and requests all active servers to run down when they are free. A server retaining context does not run down until it releases context. ACMS creates new server processes to meet the MIN and MAX requirements of the application.

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

## 11.4.9 SERVER ATTRIBUTES and SERVER DEFAULTS Clauses

When ADU begins processing an application definition, ACMS assigns default values to all characteristics of servers. You can change these default values by assigning different characteristics to the servers of an application with the SERVER ATTRIBUTES or SERVER DEFAULTS clauses.

A characteristic assigned with the SERVER DEFAULTS clause can become the value of the characteristic or it can be overridden by a value supplied in the task group definition or a value supplied in a SERVER ATTRIBUTES clause.

ADU uses the following order of defaulting to find values for server attributes:

1. SERVER ATTRIBUTES clause in the application definition
   If a characteristic is defined for a server in a SERVER ATTRIBUTES clause, ADU uses that value for the characteristic for that server.
2. SERVERS clause in the task group definition
   If a server characteristic is not defined for a server in a SERVER ATTRIBUTES clause, and if the characteristic is one that can be assigned in a task group definition, ADU looks in the task group database that defines implementation for that server. The two control characteristics that can be defined in a task group definition are USERNAME OF TERMINAL USER and FIXED/DYNAMIC USERNAME.
3. SERVER DEFAULTS clause in the application definition
   ADU looks at the SERVER DEFAULTS clauses in the application definition for any characteristic not defined in the application or task group definition. The SERVER DEFAULTS clause sets up default values for server characteristics. An application definition can include more than one of these clauses. The position of the SERVER DEFAULTS, SERVER ATTRIBUTES, and TASK GROUP clauses in the application definition determines which server defaults apply to which servers.
4. ACMS-supplied defaults
   ADU uses the default value it derives only if no value is assigned for the characteristic in the SERVER ATTRIBUTES or SERVER DEFAULTS clause of the application definition, or the task group database.

You can include more than one server in a SERVER ATTRIBUTES clause and you can also include more than one SERVER ATTRIBUTES clause in an application definition.

In a SERVER ATTRIBUTES clause, you must always name the server to which you want a subclause to apply. This name must be unique for each server in the application and it must conform to the rules for identifiers. For example:

    SERVER ATTRIBUTE IS
      UTILITY_SERVER : SERVER UTILITY_SERVER IN DEPARTMENT_COBOL_TASK_GROUP;
                       USERNAME IS DEPARTMENT;
    END SERVER ATTRIBUTE;

This SERVER ATTRIBUTES clause assigns the name UTILITY_SERVER to the UTILITY_SERVER. A colon separates the server name from the SERVER keyword and the USERNAME subclause. You must end the subclause with a semicolon (;).

The SERVER keyword points to a server in a task group. In the example, the SERVER keyword points to the UTILITY_SERVER. The task group name must be the same as the name used in the TASK GROUPS clause in the application definition. You can use SERVER DEFAULTS clauses with SERVER ATTRIBUTES clauses to simplify your application definition.

The SERVER DEFAULTS clause resets the ACMS defaults for server control characteristics. These new defaults apply until the end of the definition, or until they are changed again with another SERVER DEFAULTS clause. You can override the defaults by assigning a value assigned in a task group definition or a SERVER ATTRIBUTES clause.

Several servers may have one or more control attributes in common that are different from the ACMS-supplied defaults. In this case, one way to simplify your application definition is to use a SERVER DEFAULTS clause.

The SERVER DEFAULTS clause allows you to define, in a single subclause, an attribute that several servers have in common. Using the SERVER ATTRIBUTES clause, you have to name each server and the identical attribute for each. For example, using the SERVER DEFAULTS clause, you can assign all the servers in the DEPARTMENT task group the user name DEPARTMENT in a single subclause:

    SERVER DEFAULT IS
      USERNAME IS DEPARTMENT;
    END SERVER DEFAULT;

    TASK GROUP IS
      DEPARTMENT_COBOL_TASK_GROUP : TASK GROUP FILE IS
          "ACMS$EXAMPLES:DEPRMSCOB.TDB";
    END TASK GROUPS;

When you build the application database, ADU assigns the user name Department to every server in the Department task group. ADU uses the defaults it derives for all other server control characteristics for those servers.

Remember that control characteristics assigned either in SERVER ATTRIBUTES clauses or in the task group definition override values assigned with the SERVER DEFAULTS clause. Also, the SERVER DEFAULTS clause must precede the TASK GROUPS clause to which you want it to apply.

Example 11-7 shows an application definition that uses a SERVER DEFAULTS clause to define control attributes for all the servers in the application. The application includes only one task group.

Example 11-7 Application Definition Using Server Defaults

    USERNAME IS PERSONNEL;
    SERVER DEFAULTS ARE
      AUDIT;
      USERNAME IS DEPARTMENT;
      MAXIMUM SERVER PROCESSES IS 5;
      MINIMUM SERVER PROCESSES IS 1;
    END SERVER DEFAULTS;

    TASK GROUP IS
       DEPARTMENT_TASK_GROUP: TASK GROUP FILE IS
                              "ACMS$EXAMPLES:DEPART.TDB";
    END TASK GROUP;

If an application contains only one task group and if all servers in the application use the same control attributes, the application definition can be as simple as this, even if the application includes many tasks.

## 11.4.10 Defaulting Server and Task Group Names

Depending on the position of SERVER ATTRIBUTES clauses in the application definition, you do not need to name explicitly the server or task group to which you want a control characteristic to apply. ACMS provides some defaulting of server and task group names in the application definition.

The following SERVER ATTRIBUTE clause includes both the server and the task group name of the server to which the user name DEPARTMENT applies:

    SERVER ATTRIBUTE IS
      UTILITY_SERVER : SERVER UTILITY_SERVER IN DEPARTMENT_COBOL_TASK_GROUP;
                       USERNAME IS DEPARTMENT;
    END SERVER ATTRIBUTE;

In the SERVER ATTRIBUTES clause, there are two phrases: the server name and the task group name. In some cases, one of these phrases can be omitted. If the server has the same name in that application as it has in the task group, you do not have to use the server name phrase. For example:

    SERVER ATTRIBUTE IS
      UTILITY_SERVER : IN DEPARTMENT_COBOL_TASK_GROUP;
                       USERNAME IS DEPARTMENT;
    END SERVER ATTRIBUTE;

If the task group containing the server immediately precedes the SERVER ATTRIBUTES clause, you do not have to use the task group phrase. For example:

    TASK GROUP IS
      DEPARTMENT_COBOL_TASK_GROUP : TASK GROUP FILE IS
          "ACMS$EXAMPLES:DEPRMSCOB.TDB";
    END TASK GROUPS;

    SERVER ATTRIBUTE IS
      UTILITY_SERVER : SERVER UTILITY_SERVER;
                       USERNAME IS DEPARTMENT;
    END SERVER ATTRIBUTE;

If you do not specify a task group name in a SERVER ATTRIBUTES clause, the task group name is defaulted from the last task group name in the immediately preceding TASK GROUPS clause. If you name the task group in the SERVER ATTRIBUTES clause, then you do not have to place the SERVER ATTRIBUTES clause after the TASK GROUPS clause to which it applies.

## 11.4.11 Positioning SERVER ATTRIBUTES and SERVER DEFAULTS Clauses

The way you place SERVER ATTRIBUTES and SERVER DEFAULTS clauses in an application definition affects how ACMS assigns control characteristics to the servers in the application.

Example 11-8 shows an application definition that uses multiple SERVER DEFAULTS clauses to define different server control attributes for the servers in two task groups.

Example 11-8 Application Using Multiple Server Defaults Clauses

    USERNAME IS PERSONNEL;
    SERVER DEFAULTS ARE
      AUDIT;
      USERNAME IS DEPARTMENT;
      LOGICAL NAME
         PERS_FILE  = "ACMS$EXAMPLES:PERSFILE.DAT";
      MAXIMUM SERVER PROCESSES IS 5;
      MINIMUM SERVER PROCESSES IS 1;
    END SERVER DEFAULTS;

    TASK GROUP IS
       DEPARTMENT_TASK_GROUP: TASK GROUP FILE IS
                              "ACMS$EXAMPLES:DEPART.TDB";
    END TASK GROUP;

    SERVER DEFAULTS ARE
      USERNAME IS PERSONNEL;
     END SERVER DEFAULTS;

    TASK GROUP IS
      PERSONNEL_TASK_GROUP:  TASK GROUP FILE IS
                             "ACMS$EXAMPLES:PERSONNEL.TDB";
    END TASK GROUP;

    SERVER ATTRIBUTES
      UTILITY_SERVER : DYNAMIC USERNAME;
    END SERVER ATTRIBUTES;
    END DEFINITION;

Because none of the servers in the Department task group is named in a SERVER ATTRIBUTES clause, the defaults defined by the first SERVER DEFAULTS clause apply to all the servers in that task group. Most of those default values also apply to all the servers in the Personnel task group, except that:

- The second SERVER DEFAULTS clause sets up a different default user name for the Personnel servers.
- The SERVER ATTRIBUTES clause defines the Utility server in the Personnel task group as the only one with a dynamic user name.

Any defaults set in a SERVER DEFAULTS clause remain in effect unless changed by a later SERVER DEFAULTS clause. Any control attributes not named in a SERVER DEFAULTS clause retain their ACMS-supplied defaults. You can also override any default value by explicitly assigning an attribute in a SERVER ATTRIBUTES clause.

When you write an application definition, use the order of SERVER DEFAULTS, SERVER ATTRIBUTES, and TASK GROUP clauses that lets you take the best advantage of defaulting. Your goal is always to make the application definition as simple and as clear as possible.

## 11.4.12 Auditing Servers

ACMS provides an auditing facility to record events occurring when a task is running in a server process. Use the AUDIT subclause to control whether events such as the unexpected stopping of a server process are recorded in the audit trail log. For example:

    SERVER DEFAULT IS
      AUDIT;
    END SERVER DEFAULT;

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

In this example, the audit trail log records server events for the Administration task group whenever a task in that group is run and at other times. The default value for the AUDIT subclause is NOAUDIT. If you want a record of task events, be sure to include the AUDIT subclause in the SERVER ATTRIBUTES or SERVER DEFAULTS clause. 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 subclause, ACMS records all failure statuses.

Previous | Next | Contents | Index