HP OpenVMS Systems Documentation

If you change the number of TASK ARGUMENT workspaces defined for a task or if you change the ACCESS method of a TASK ARGUMENT workspace, you must rebuild the application database (.ADB) after you rebuild the task group database (.TDB). If you forget to rebuild the .ADB and attempt to select a task that has been changed in this manner, ACMS cancels the task and writes the following message to the audit trail log:

************************************************************
Type   : TASK      Time   : 16-FEB-1988 15:24:48.45
Appl   : CTAPPL
Task   : PWT
User   : USER1
ID     : SAILNG::00010014-00000001-8A8853C0-0090E729
Sub    : SAILNG::00010014-00000000-8A8853C0-0090E729
Text   : Task start failed during initialization
Application must be rebuilt due to TASK ARGUMENT workspace changes
************************************************************
Type   : TASK      Time   : 16-FEB-1988 15:24:48.45
Appl   : CTAPPL
Task   : PWT
User   : USER1
ID     : SAILNG::00010014-00000001-8A8853C0-0090E729
Sub    : SAILNG::00010014-00000000-8A8853C0-0090E729
Text   : Task end
Task completion status: Unexpected error during task initialization. See
audit/error logs for details
************************************************************

Once the tasks and task groups of an application are implemented, you create application and menu definitions to control the application and to present tasks to users. Chapter 11 begins by walking you through the creation of a simple, complete application. The rest of the chapter explains how to define control characteristics for tasks, servers, and the application as a whole. Chapter 12 explains how to create menu definitions to access the application.

11.1 Defining a Simple Application

Suppose that your personnel department needs a way to monitor performance reviews for all company employees. The department also needs to use the DATATRIEVE procedure DUE, which displays reviews that are due, and the DCL command EDIT.

First, you develop the four tasks and the two task groups you need. The Department task group contains two tasks described in Chapter 2:

• Review History displays the performance history of one employee.
• Review Schedule displays the performance review schedules of an entire department.

The Administration task group contains two single-step tasks:

• DATATRIEVE procedure, DUE
• DCL command, EDIT

(Chapter 13 explains how to define the Administration task group. See Example 13-1 for a listing of the task group definition.)

The following sections explain how to create an application definition that contains and controls the tasks in these two task groups.

11.2 Describing the Application Environment

In the application definition, you describe the application environment by defining control characteristics for the application. Application definitions must:

• Name the task groups that contain the tasks of the application
• Assign a user name to the Application Execution Controller (EXC), the ACMS system process that controls the application

Access to tasks is always controlled from the application definition. You use application clauses to describe these and other application characteristics, as described in the following sections.

11.2.1 Naming Task Groups

You begin writing an application definition by naming the task groups of the application. You use the TASK GROUPS clause to name the task groups. The clause begins with the keywords TASK GROUPS ARE and ends with END TASK GROUPS. Between these keywords, you include:

• Name for each of the task groups in the application
• Name of the task group database file created by building each task group definition

The TASK GROUPS clause for the Personnel application is:

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;

Task groups in the application are DEPARTMENT_COBOL_TASK_GROUP and ADMINISTRATION_COBOL_TASK_GROUP. These names are not CDD path names for the task group; they are names that you assign in the application to identify the task groups. DEPRMSCOB.TDB and ADMRMSCOB.TDB are the task group database files that are created when you build the two task group definitions by using the ADU BUILD command.

You can name all the task groups in an application in a single TASK GROUPS clause, or you can group them in multiple TASK GROUPS clauses. For example, you could put the two task groups DEPARTMENT_COBOL_TASK_GROUP and ADMINISTRATION_COBOL_TASK_GROUP in separate TASK GROUPS clauses:

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

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

ACMS uses a process called the Application Execution Controller (EXC) to manage the servers that handle processing work for tasks. The EXC process requires special quotas and privileges to perform this work. Therefore, the application definition must include an OpenVMS user name for the EXC process that has the necessary quotas and privileges. Include the APPLICATION USERNAME clause in your source file.

APPLICATION USERNAME IS ACMSAMPLE;
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;

In this example, the user name is ACMSAMPLE. End the APPLICATION USERNAME clause with a semicolon (;).

11.2.3 Assigning Characteristics to Tasks and Servers

For applications more complex than the Personnel application, you can assign task and server control characteristics that affect how ACMS handles tasks and servers at run time. You assign these characteristics by using subclauses within the DEFAULTS and ATTRIBUTES clauses of the application definition. There are two characteristics, however, that are very important for even the simplest application:

• Who can select a task
• The user names under which you want servers to run

One important purpose of an application definition is to control who can run which tasks in that application. You use the ACCESS subclause to control access to tasks.

For example, suppose that you want to let everyone in the Personnel department run all the tasks in the Personnel application and you want to prevent anyone outside the department from running any of the tasks in the application. If all the users in the Personnel department have user identification codes (UICs) with a group number of 300, such as [300,1], [300,2], and so on, you can set up this access control list (ACL) for the tasks in the application:

TASK DEFAULT IS
  ACCESS CONTROL LIST
    IDENTIFIER [300,*] ACCESS EXECUTE;
END TASK DEFAULT;

Any user with a UIC group number of 300 can run the tasks in the application. ACMS does not allow any other users to run the tasks. This ACCESS subclause overrides the default ACMS ACL, which allows all users to run all tasks.

For characteristics assigned with the TASK DEFAULTS clause to take effect, the TASK DEFAULTS clause must be placed before the TASK GROUPS clause and the TASK ATTRIBUTES clause in the application definition.

In addition to defining control characteristics such as access control to tasks, you can define control characteristics for servers.

It is important to assign user names to servers in an application because when a server runs, it takes on the privileges, priority, and quotas associated with its user name. The default value for server user names is the user name of the application. Because the application requires more privileges and quotas, and a higher priority than servers, it is a good idea to assign servers a user name different from the application user name.

For example, you can assign a server user name to all the servers in the Personnel application with the USERNAME subclause in the SERVER DEFAULTS clause:

SERVER DEFAULT IS
  USERNAME IS PERSONSVR;
END SERVER DEFAULT;

This subclause assigns the user name PERSONSVR to all the servers in the Personnel application. For characteristics assigned with the SERVER DEFAULTS clause to take effect, the SERVER DEFAULTS clause must be placed before the TASK GROUPS clause and the SERVER ATTRIBUTES clause in the application definition.

Example 11-1 shows the application definition for the Personnel application.

APPLICATION USERNAME IS ACMSAMPLE;

TASK DEFAULT IS
  ACCESS CONTROL LIST
    IDENTIFIER [300,*] ACCESS EXECUTE;
END TASK DEFAULT;

SERVER DEFAULT IS
  USERNAME IS PERSONSVR;
END SERVER DEFAULT;
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;

You can give any number of users or groups of users access to tasks by using the ACCESS subclause. You can also use the same subclause to prevent certain users or groups of users from running tasks with the same subclause.

11.3 Controlling Tasks

You control tasks in an application by assigning task control characteristics in an application definition. These characteristics determine:

• Who can run a task
• Whether or not information about a task is written to the ACMS audit trail log
• What happens at the end of a task
• Whether or not the task is available for execution

When ADU begins processing an application definition, it assigns default values to all characteristics of tasks. You can reset these default values by assigning different characteristics to the tasks of an application by using the TASK ATTRIBUTES or TASK DEFAULTS clauses. Within these clauses, you use subclauses to describe specific task control characteristics.

The examples in the following sections use the TASK ATTRIBUTES clause to explain how to describe control characteristics for tasks in an application. Section 11.3.4 describes the TASK ATTRIBUTES and TASK DEFAULTS clauses in more detail.

11.3.1 Controlling Access to Tasks

One of the important purposes of the application definition is to control who can run which tasks in an application. You use the ACCESS subclause to control access to tasks.

The Personnel application used in the examples in this book includes the DATR task. You can define an ACL to control which users have access to the DATR task. For example, you may want to let everyone in the Personnel department run this task, but to prevent anyone outside the department from running it. Because all the users in the Personnel department have UICs with a group number of 300, the ACL for the DATR task is [300,*] ACCESS EXECUTE. This ACL says that all users with a group number of 300 can run the task:

TASK ATTRIBUTE IS
  DATR : TASK DATR IN ADMINSTRATION_COBOL_TASK_GROUP;
             ACCESS CONTROL LIST
               IDENTIFIER [300,*] ACCESS EXECUTE;
END TASK ATTRIBUTE;

The default value for access control is to allow all users to run all tasks. This ACCESS subclause overrides this default ACL.

In some cases you may want to provide access to the same task by different groups of users. You can include access definitions for more than one group in the same ACCESS subclause. For example:

TASK ATTRIBUTE IS
  DATR : TASK DATR IN ADMINISTRATION_COBOL_TASK_GROUP;
             ACCESS CONTROL LIST
               IDENTIFIER [100,*] ACCESS EXECUTE,
               IDENTIFIER [300,*] ACCESS EXECUTE;
END TASK ATTRIBUTE;

This ACL allows all users with UIC group numbers of 100 or 300 to run the DATR task. If you include more than one access definition in an ACCESS subclause, separate them with commas. End the ACCESS subclause with a semicolon (;).

You can also use the NONE keyword to prevent a user or group of users from running a particular task. For example:

TASK ATTRIBUTE IS
  DATR : TASK DATR IN ADMINISTRATION_COBOL_TASK_GROUP;
             ACCESS CONTROL LIST
               IDENTIFIER [200,*] ACCESS NONE,
               IDENTIFIER [*,*] ACCESS EXECUTE;
END TASK ATTRIBUTE;

Because ACCESS NONE overrides the default value that allows all users to run all tasks, you must follow it with IDENTIFIER [*,*] ACCESS EXECUTE, so that users who are not in group 200 can run the DATR task.

When ACMS looks at an ACL to find out whether a user can run a task, it starts at the top of the list and reads only until it finds an entry matching that user. If the definition for [*,*] is first in the ACL, then ACMS stops before finding the entry for [200,*], allowing users with group number 200 to run the DATR task.

In most cases, you group all access definitions for a single task in a single ACCESS subclause, but you can include more than one ACCESS subclause for each task, as well as more than one access definition in each ACCESS subclause. If you include more than one ACCESS subclause in one TASK ATTRIBUTES or TASK DEFAULTS clause, ACMS uses the lists as though they were one list; the values set in the TASK ATTRIBUTES clause override the values set in the TASK DEFAULTS clause.

11.3.2 Auditing Task Events

ACMS provides an auditing facility to record task events such as unexpected canceling of tasks. The Audit Trail Report Utility writes reports on task events from the audit trail log file.

You use the AUDIT subclause to control whether or not events such as task selections and completions are recorded in the audit trail log:

TASK ATTRIBUTE IS
 DATR : TASK DATR IN ADMINISTRATION_COBOL_TASK_GROUP;
        AUDIT;
END TASK ATTRIBUTE;

In this example, the audit trail log records task events for the DATR task whenever that task 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 subclause, ACMS records all failure statuses.

11.3.3 Controlling What Happens When a Task Ends

From the application definition you can control what happens when an ACMS task ends. ACMS provides three options:

• Display the menu immediately
• Display the menu after a 3-second delay
• Display the menu after the user presses [Return]

The default value for this attribute is to display a menu immediately when a task ends. To delay the display of a menu for three seconds after a task ends, use the DELAY subclause:

TASK ATTRIBUTE IS
  DATR : TASK DATR IN ADMINISTRATION_COBOL_TASK_GROUP;
         DELAY;
END TASK ATTRIBUTE;

When a user finishes using the DATR task, ACMS waits for three seconds before displaying the next menu.

To delay the display of a menu until the user presses [Return] after a task ends, use the WAIT subclause. For example:

TASK ATTRIBUTE IS
  DATR  : TASK DATR IN ADMINISTRATION_COBOL_TASK_GROUP;
          WAIT;
END TASK ATTRIBUTE;

Now when a user finishes using the DATR task, ACMS waits until the user presses [Return] before displaying the menu.

You can also define the wait and DELAY subclauses in the task group definition. A WAIT or DELAY characteristic that you assign in a TASK ATTRIBUTES clause in an application definition overrides a WAIT or DELAY assignment in the task group definition.

Although all the examples so far have defined task control attributes within a TASK ATTRIBUTES clause, you can use these subclauses in a TASK DEFAULTS clause. The next section discusses the TASK ATTRIBUTES and TASK DEFAULTS clauses, the differences between the two, and the circumstances in which to use each.

11.3.4 TASK ATTRIBUTES and TASK DEFAULTS Clauses

When ADU begins processing an application definition, it assigns default values to all characteristics of tasks. Characteristics assigned with the TASK DEFAULTS or TASK ATTRIBUTES clauses reset the values of ACMS-supplied defaults. A characteristic assigned with the TASK DEFAULTS clause can become the value of the characteristic, or you can override it with a value supplied in the task group definition or a value supplied in a TASK ATTRIBUTES clause.

ACMS uses the following order of default to find values for task control characteristics:

1. TASK ATTRIBUTES clause in the application definition
   If you specifically define an attribute for a task in a TASK ATTRIBUTES clause, ADU uses that value for the attribute for that task.
2. TASKS clause in the task definition or the TASK subclause in the task group definition
   If you do not define a task attribute for a task in a TASK ATTRIBUTES clause, and if the attribute is one that you can assign in a task group definition, ADU looks in the task group database that defines implementation attributes for that task to see whether the attribute is defined there. The control attributes that you can define in a task group definition are DELAY, WAIT, CANCELABLE, LOCAL, and GLOBAL.
3. TASK DEFAULTS clause in the application definition
   ADU looks at the TASK DEFAULTS clauses in the application definition for any attribute that you do not define in the TASK ATTRIBUTES clause of the application or task group definition. The TASK DEFAULTS clause changes the ACMS-supplied default values for task attributes. An application definition can include more than one TASK DEFAULTS clause. The position of the TASK DEFAULTS clauses, TASK ATTRIBUTES clauses, and TASK GROUPS clauses in the application definition determines which task defaults apply to which tasks.
4. ACMS-supplied defaults
   ADU uses the default value it supplies only if you do not assign a value for the attribute in the TASK ATTRIBUTES or TASK DEFAULTS clause of the application definition, or in the task group database.

You can include more than one task in a TASK ATTRIBUTES clause, and you can include more than one TASK ATTRIBUTES clause in an application definition.

In a TASK ATTRIBUTES clause, you must always name the task or tasks to which you want a subclause to apply. The task name must be unique in the application and must conform to the rules for ACMS identifiers. For example:

TASK ATTRIBUTE IS
  DATR : TASK DATR IN ADMINISTRATION_COBOL_TASK_GROUP;
         AUDIT;
END TASK ATTRIBUTE;

This TASK ATTRIBUTES clause assigns the name DATR to the DATR task in the ADMINSTRATION_COBOL_TASK_GROUP task group. A colon (:) separates the name from the TASK and AUDIT subclauses. The name you assign to the left of the colon, DATR, must be unique within the application definition. However, the actual task name to the right of the colon needs to be unique within the task group only, not within the application. End each subclause with a semicolon (;).

The TASK keyword points to a task in a task group. In this example, the TASK keyword points to the DATR task in the Administration task group. The task group name must be the same as the name you used in the TASK GROUPS clause in the application definition.

11.3.4.2 Using the TASK DEFAULTS Clause

You can use TASK DEFAULTS clauses with TASK ATTRIBUTES clauses to simplify your application definition.

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

Several tasks can 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 TASK DEFAULTS clause.

The TASK DEFAULTS clause allows you to define an attribute that several tasks have in common in a single subclause. If you use the TASK ATTRIBUTES clause, you must name each task and the identical attribute for each task. If you use the TASK DEFAULTS clause, you can give users with the group UIC 100 access to both the DATR and EDIT tasks in a single subclause:

TASK DEFAULT IS
  ACCESS CONTROL LIST IDENTIFIER [100,*] ACCESS EXECUTE;
END TASK DEFAULT;

TASK ATTRIBUTES ARE
  DATR : ADMINISTRATION_COBOL_TASK_GROUP;
  EDIT : ADMINISTRATION_COBOL_TASK_GROUP;
END TASK ATTRIBUTES;

When you build an application database, ADU takes the ACL for the DATR and EDIT tasks from the TASK DEFAULTS clause. ACMS uses the defaults it supplies for all other task control attributes for those tasks.

The TASK DEFAULTS clause must precede the TASK GROUPS or TASK ATTRIBUTES clause to which you want it to apply.

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

REPLACE APPLICATION PERSONNEL_APPLICATION
USERNAME IS PERSONNEL;
TASK DEFAULTS ARE
  ACCESS CONTROL LIST IDENTIFIER [200,*] ACCESS EXECUTE;
  AUDIT;
END TASK DEFAULTS;

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

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