Names a procedure that runs when a procedure server image is stopped.

Format

Parameter

terminal-procedure-entry-name

The entry point of the termination procedure in the procedure server image.

Clause Default

The TERMINATION PROCEDURE subclause is optional. If you do not name a termination procedure, ACMS does not run any procedures when the procedure server is stopped.

Notes

Use the TERMINATION PROCEDURE subclause only when defining a procedure server.

A termination procedure you name for a server runs only when the server is stopped; it does not run when each task using the server stops or when a processing step using the server stops. However, servers can be stopped at any time while the application is running, depending on the processing load of the application.

When you name a termination procedure for a procedure server, you normally also name an initialization procedure for that server.

You can name only one termination procedure for each server you define.

A termination procedure performs such activities as closing files used by the tasks handled by a server.

You can name a termination procedure for a server in the PROCEDURES subclause for that server. However, you must also name the procedure in the TERMINATION PROCEDURE subclause.

By default, if a procedure server process runs down because of a task cancel, ACMS does not process the termination procedure. To override this default, use the ALWAYS EXECUTE TERMINATION PROCEDURE server subclause.

Example

SERVER IS 
  DEPARTMENT_SERVER: 
    PROCEDURE IMAGE IS "ACMS$EXAMPLES:DEPARTGRP.EXE"; 
    INITIALIZATION PROCEDURE IS DEPART_STARTUP; 
    TERMINATION PROCEDURE IS DEPART_SHUTDOWN; 
    PROCEDURES ARE 
      REVIEW_HISTORY_GET,REVIEW_SCHEDULE_GET,REVIEW_UPDATE_GET; 
END SERVER; 
      

When DEPARTMENT_SERVER is stopped, ACMS runs a termination procedure. The entry point of this procedure in the procedure server image is DEPART_SHUTDOWN.

Indicates that the server process runs under the OpenVMS user name of the terminal user, using the UIC and default directory of that user.

Format

USERNAME IS USERNAME OF TERMINAL USER ;

Clause Default

ACMS assigns to the server process the user name you give to the execution controller in the application definition.

Notes

The USERNAME subclause is overridden by any user name specified for the server in the application definition.

If you define a server to have the user name of the terminal user, that server cannot be reusable and cannot have a dynamic user name.

The REUSABLE server subclause in the task group definition is the default for both DCL and procedure servers. However, using the clause USERNAME OF TERMINAL USER in application or task group definitions overrides this default and creates servers that are not reusable. Every time a terminal user selects a task running a server defined with the USERNAME OF TERMINAL USER clause, a separate server process is created for that user. For best performance, your application should run as few servers as needed to perform the application.

Example

SERVER IS 
  PRIVATE_UTILITY_SERVER: DCL PROCESS; 
                          USERNAME OF USER; 
                          NOT REUSABLE; 
END SERVER; 
      

The user name of PRIVATE_UTILITY_SERVER is the same as the user name of the terminal user.

Declares one or more workspaces used by the tasks in a task group.

Format

Parameters

record-path-name

The CDD path name of the record description for the workspace. You must use the full CDD record path name unless you have set your CDD default to the directory where the record definition is stored. In that case, you can use only the given name of the workspace.

If you name more than one workspace, separate the record path names with commas.

unique-name

A unique name for a workspace. The name of each workspace must be unique within the workspace declarations for the task group. If two or more given names of record path names are identical, you use the unique name parameter to define a different name for the workspace. If you do not use the unique-name parameter, the default name of the workspace is the given name of the workspace.

Keywords

ACCESS

Identifies the access characteristics of a workspace. The types of access you can define are RETRIEVAL and UPDATE. Because TASK workspaces always have update access, define access characteristics only for GROUP and USER type workspaces. The default access type is RETRIEVAL.

GROUP

Identifies the workspace as a GROUP workspace. The contents of a GROUP workspace can be used by many instances of the same or different tasks. ACMS maintains these contents from application startup to application shutdown.

LOCK

Indicates that a task instance can lock the workspace from use by other tasks when the task starts, and unlock it when the task stops or is canceled. If you do not use the LOCK keyword, the workspace is not locked. The keyword applies only to GROUP and USER workspaces defined for UPDATE access.

RETRIEVAL

Indicates that a task can use and make changes to the contents of the workspace. However, when the task finishes, ACMS does not copy changes into the master copy of the workspace. RETRIEVAL is the default access type for GROUP and USER workspaces.

TASK

Identifies the workspace as a TASK workspace. The contents of a TASK workspace are kept for just one instance of a task. TASK is the default type of workspace.

TYPE

Identifies the type of workspace being used by the task. The workspace types you can define are: GROUP, TASK, and USER.

UPDATE

Indicates that the task can make changes to the contents of the workspace. When the task finishes, ACMS copies these changes to the master copy of the workspace. Unless you use the LOCK keyword, ACMS does not lock the workspace against updates from other tasks or users.

USER

Indicates the workspace is a USER workspace. The contents of a USER workspace can be used by a single user for many instances of the same or different tasks. A user's copy of a USER workspace exists from the time the user first requires the workspace until that user logs out of ACMS.

Clause Default

The WORKSPACES clause is optional. If you do not name workspaces in a task group definition, tasks in that group can use only workspaces declared in task definitions.

In addition, ACMS provides a set of system workspaces that are available by default. The system workspaces are:

• ACMS$PROCESSING_STATUS
  Contains processing status handling information
• ACMS$SELECTION_STRING
  Contains a string submitted at task selection time
• ACMS$TASK_INFORMATION
  Contains task information

You cannot name the system workspaces in the WORKSPACES clause. System workspaces are always used by the tasks in a task group and are always implicitly declared. For a discussion of the system workspaces, see Appendix B.

Notes

Use the USE WORKSPACES task clause to have a task access a workspace defined in the task group definition. When you use the USE WORKSPACES clause in a task definition, you can override access restrictions defined for a workspace in the task group.

Because TASK is the default workspace type and the ACCESS keyword is valid only for GROUP and USER workspaces, you must include the TYPE keyword if you use the ACCESS keyword.

When you want to specify the version of a workspace that has the highest version number, use a semicolon after the workspace name, followed by a zero. Using a semicolon alone causes an error.

ADU lets you use the LOCK keyword when defining a TASK workspace. However, this keyword has no effect at run time.

Do not name the ACMS system workspaces in the WORKSPACES clause.

You can use the WORKSPACES clause more than once in a task group definition.

The unique name of a workspace can be different from the name of the record description for that workspace. For example, suppose you assign a unique name to SAMPLE_WORKSPACE:

WORKSPACE IS SAMPLE_WORKSPACE WITH NAME EXAMPLE1;

The record description for SAMPLE_WORKSPACE can be as follows:

DEFINE RECORD SAMPLE_WORKSPACE. SAMPLE STRUCTURE. A. B. END SAMPLE STRUCTURE. END SAMPLE_WORKSPACE RECORD.

The name of the record description SAMPLE_WORKSPACE indicates the location of the record in the dictionary. The unique name of the workspace, EXAMPLE1, does not have to be the same as the name of the record description or the structure, and is used only within the task group definition.

In a task definition, to refer to the A field in the EXAMPLE1 workspace, you can use: EXAMPLE1.SAMPLE.A, SAMPLE.A, A, or EXAMPLE1.A.

If you add another field A to the workspace, the record definition looks like this:

DEFINE RECORD SAMPLE_WORKSPACE. SAMPLE STRUCTURE. A. B. X STRUCTURE. A. END X STRUCTURE. END SAMPLE STRUCTURE. END SAMPLE_WORKSPACE.

You encounter an ambiguous field reference when using the following field names in a definition: A or EXAMPLE1.A. The reference EXAMPLE1.SAMPLE.A is still valid.

The ADU does not support CDD objects containing branch information. When the ADU attempts to access a CDD object (for example, an ACMS task) containing branch information, the ADU generates errors similar to the following and aborts:

%ADU-E-ESTFETNEXT, Unexpected CDD Error %CDD-W-ILLBRANCH, TSK1(1:V1:1) contains branch information

Examples

WORKSPACE IS 
  DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.DEPT_WORKSPACE; 
      

This example declares a workspace that can be used by the tasks in the DEPARTMENT task group. The given name of the workspace is DEPT_WORKSPACE. The default workspace type is TASK.

WORKSPACE IS DEPT_WORKSPACE WITH TYPE GROUP ACCESS UPDATE LOCK; 
      

This example also declares a workspace that can be used by the tasks in the DEPARTMENT task group. However, in this example, CDD$DEFAULT is set to DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS. Therefore, you use only the given name of the workspace in the WORKSPACES clause.

Because DEPT_WORKSPACE is a group workspace, all the tasks in the group can use the contents of the workspace and can lock the workspace from use by other tasks. In addition, each task can update the contents of the workspace.

An application definition consists of a set of clauses that define control attributes for tasks, servers, and the application execution controller that manages the server processes in which tasks run.

Two application definition clauses are required. The TASK GROUPS clause names the task group or groups that define the tasks of an application. The APPLICATION USERNAME clause defines the user name with which the execution controller runs. The other clauses in the application definition are optional.

Four application definition clauses use two sets of keywords, one set beginning the clause and the other set ending it. These four clauses are: SERVER ATTRIBUTES, SERVER DEFAULTS, TASK ATTRIBUTES, and TASK DEFAULTS. Between the keywords, you put subclauses that define the control characteristics of servers or tasks:

SERVER ATTRIBUTES ARE <server-subclauses> END SERVER ATTRIBUTES;

When ADU begins processing an application definition, it assigns default values to all characteristics of tasks and servers. You can change these default values by assigning different task characteristics to the tasks of an application with the TASK ATTRIBUTES or TASK DEFAULTS clause, and by assigning different server characteristics to the servers of an application with the SERVER ATTRIBUTES or SERVER DEFAULTS clause. Figure 5-1 shows the full syntax of the application definition.

Figure 5-1 Application Definition Syntax

Example 5-1 shows an example of a complete application definition.

Example 5-1 Application Definition

USERNAME IS PERSONNEL; SERVER DEFAULTS ARE DEFAULT DIRECTORY IS SYS$SAMPLE; MAXIMUM SERVER PROCESSES IS 10; MINIMUM SERVER PROCESSES IS 1; END SERVER DEFAULTS; TASK DEFAULTS ARE ACCESS CONTROL IS (ID=ACCOUNTING, ACCESS=NONE); END TASK DEFAULTS; TASK GROUP IS PERSONNEL_GROUP : TASK GROUP FILE IS "SYS$SAMPLE:PERSONNEL.TDB"; END TASK GROUP; TASK ATTRIBUTES ARE ADD_EMPLOYEE : TASK ADD_EMPLOYEE IN PERSONNEL_GROUP; ACCESS IS (ID=PERSONNEL, ACCESS=EXECUTE); DATR : TASK DATR IN PERSONNEL_GROUP; ACCESS IS (ID=PERSONNEL, ACCESS=EXECUTE); END TASK ATTRIBUTES; SERVER DEFAULTS ARE MINIMUM SERVER PROCESSES IS 2; END SERVER DEFAULTS; SERVER ATTRIBUTES ARE PERSONNEL_SERVER : SERVER PERSONNEL_SERVER IN PERSONNEL_GROUP; USERNAME IS PERSONNEL; DYNAMIC USERNAME; UTILITY_SERVER : SERVER UTILITY_SERVER IN PERSONNEL_GROUP; DYNAMIC USERNAME; USERNAME IS DEPART; END SERVER ATTRIBUTES; END DEFINITION;

5.1 Application Definition Clauses

Table 5-1 describes the application clauses you use to write application definitions.

Table 5-1 Application Definition Clauses

Clause	Meaning
APPLICATION DEFAULT DIRECTORY	Assigns a default device and directory that the application execution controller uses.
APPLICATION NAME TABLES	Specifies which logical name tables the application execution controller can use.
APPLICATION LOGICALS	Defines one or more process logical names for the process in which an application execution controller runs.
APPLICATION USERNAME	Assigns an OpenVMS user name under which the application execution controller runs.
AUDIT	Keeps a record of application level events.
DEFAULT APPLICATION FILE	Defines the default application database file (.ADB) ADU uses when you do not include a file specification with the BUILD APPLICATION command.
MAXIMUM SERVER PROCESSES	Sets the upper limit on the number of server processes that the application can have active at one time.
MAXIMUM TASK INSTANCES	Assigns the largest number of task instances that can be active at one time for an application.
SERVER ATTRIBUTES	Assigns values for one or more control attributes to one or more servers.
SERVER DEFAULTS	Sets the current default value for one or more control attributes of a set of servers.
SERVER MONITORING INTERVAL	Controls how often queues are checked to determine whether to create or delete new server processes.
TASK ATTRIBUTES	Assigns values for one or more task control attributes of one or more tasks defined in a task group definition.
TASK DEFAULTS	Sets the current default value for one or more task control attributes.
TASK GROUPS	Names the task group or groups in the application.

5.2 Server Subclauses

The SERVER ATTRIBUTES and SERVER DEFAULTS clauses use the same subordinate clauses to define one or more application servers. The SERVER ATTRIBUTES clause defines the processing characteristics of a single server, while SERVER DEFAULTS can affect a group of servers. Table 5-2 contains a brief description of these subclauses.

Table 5-2 Server Subclauses

Clause	Meaning
AUDIT	Determines whether or not ACMS keeps a record of server events.
CREATION DELAY	Controls how long ACMS waits before beginning to create new server processes when tasks are waiting for a server process.
CREATION INTERVAL	Controls the intervals at which ACMS creates new server processes.
DEFAULT DIRECTORY	Assigns the default disk and directory for the server processes.
DELETION DELAY	Controls how long ACMS waits before deleting inactive server processes.
DELETION INTERVAL	Controls the intervals at which ACMS deletes inactive server processes.
DYNAMIC USERNAME	Specifies that the user name, UIC, and default directory of a server process change to match those of the terminal user each time the server process is allocated to a task.
FIXED USERNAME	Sets the user name, UIC, and default directory of the server process to the user name under which the server process starts.
LOGICALS	Defines a set of process logical names for the server. Every server process associated with this server has these logicals set when the process starts.
MAXIMUM PROCESSES	Sets the largest number of server processes that the server can use at one time.
MINIMUM PROCESSES	Sets the number of server processes to the smallest number that you want ACMS to start when it starts the application.
NAME TABLES	Specifies which logical name tables the server process can use.
PROTECTED WORKSPACES	Enables a workspace mapping option that maps the entire task instance workspace pool during the first procedure call to a task server.
SERVER PROCESS DUMP	Specifies whether or not an OpenVMS process dump is generated for a server process if the process terminates abnormally.
USERNAME	Assigns a user name to the server.

Figure 5-2 shows the syntax for the SERVER ATTRIBUTES clause.

Figure 5-2 SERVER ATTRIBUTES Clause Syntax

Figure 5-3 shows the syntax for the SERVER DEFAULTS clause.

Figure 5-3 SERVER DEFAULTS Clause Syntax

Example 5-2 shows an example of how to use the SERVER ATTRIBUTES and SERVER DEFAULTS clauses.

Example 5-2 Example of SERVER ATTRIBUTES and SERVER DEFAULTS Clauses

USERNAME IS DEPART; SERVER DEFAULTS ARE DEFAULT DIRECTORY IS SYS$SAMPLE; MAXIMUM SERVER PROCESSES IS 10; MINIMUM SERVER PROCESSES IS 1; END SERVER DEFAULTS; TASK GROUP IS PERSONNEL_GROUP : TASK GROUP FILE IS "SYS$SAMPLE:PERSONNEL.TDB"; END TASK GROUP; SERVER ATTRIBUTES ARE PERSONNEL_SERVER : SERVER PERSONNEL_SERVER; USERNAME IS PERSONNEL; UTILITY_SERVER : SERVER UTILITY_SERVER; DYNAMIC USERNAME; END SERVER ATTRIBUTES; END DEFINITION;