Compaq ACMS for OpenVMS
ADU Reference Manual


Previous Contents Index


Chapter 4
Task Group Definition Clauses

A task group is a set of tasks that share resources and are built into a single database file. This chapter explains the ADU clauses you use to define task groups. You use these clauses with the CREATE, MODIFY, REPLACE, or EDIT commands.

4.1 Task Group Clauses

Use task group clauses to define:

Also use task group clauses to name the tasks belonging to the group and to define some tasks directly in the task group definition. You can define a task directly in a task group definition if that task:

If a task does not follow these rules, name it in the task group definition, but define it separately using the task and block clauses described in Chapter 3. Figure 4-1 shows the syntax you use to define a task group. Table 4-1 lists the task group clauses and gives a brief description of each.

Figure 4-1 Task Group Syntax


Table 4-1 Task Group Clauses
Clause Description
DEFAULT TASK GROUP FILE Names the default file specification of the task group database.
FORMS Names the DECforms forms used by the tasks in a task group.
MESSAGE FILES Names the message files used by the tasks in a task group.
REQUEST LIBRARIES Names the request libraries used by the tasks in a task group.
SERVERS Defines the servers used by the tasks in a task group.
TASKS Names the tasks in a task group.
WORKSPACES Names the workspaces available to tasks in a task group.

You can use two kinds of subclauses with task group clauses: processing subclauses and server subclauses. If a task consists of a single processing step, you can include the definition for the task directly in the task group definition. The task group clauses you use to define a task directly in a task group definition are called processing subclauses. Section 4.2 explains these subclauses.

When you define a server in a task group definition, you use subclauses to describe characteristics for that server. Section 4.3 explains these server subclauses.

The examples that follow and their explanations do not show how to define a task group. Their purpose is to help you understand how the clauses in this chapter fit together to form task group definitions.

Example 4-1 shows an example of a simple task group definition.

Example 4-1 Simple Task Group Definition

CREATE GROUP PERSONNEL_GROUP 
  SERVER IS 
    UTILITY_SERVER: DCL PROCESS; 
                    DYNAMIC USERNAME; 
  END SERVER; 
    TASK IS 
      DATR: DELAY; 
            PROCESSING IS DCL COMMAND "$MCR DTR32" 
              IN UTILITY_SERVER; 
    END TASK; 
END DEFINITION; 

The task group with the given name PERSONNEL_GROUP contains just one task, DATR. When a user selects the DATR task from a menu, ACMS processes the DCL command MCR DTR32. ACMS runs this task in the server UTILITY_SERVER. This server must be a DCL server to handle the processing of a DCL command.

You must use the keywords END SERVER to end the SERVER clause, END TASK to end the TASK clause, and END DEFINITION to end the task group definition.

Example 4-2 shows an example of another simple task group definition.

Example 4-2 Simple Task Group Definition for Multiple-Step Tasks

CREATE GROUP PERSONNEL_GROUP 
  DEFAULT TASK GROUP FILE IS "SYS$SAMPLE:PERSONNEL.TDB"; 
  MESSAGE FILE IS "SYS$SAMPLE:PERSMSG.EXE"; 
  FORM IS "SYS$SAMPLE:PERS_FORM" WITH NAME PERS_LABEL; 
  SERVER IS 
    PERSONNEL_SERVER: 
      PROCEDURE SERVER IMAGE IS "PERSGRP.EXE"; 
      INITIALIZATION PROCEDURE IS PERS_START; 
      TERMINATION PROCEDURE IS PERS_STOP; 
      PROCEDURE IS PERSADD; 
  END SERVER; 
  TASK IS 
    ADD_EMPLOYEE: TASK IS ADD_EMPLOYEE_TASK; 
  END TASK; 
END DEFINITION; 

This definition of the task group PERSONNEL_GROUP contains just one task, ADD_EMPLOYEE. ADD_EMPLOYEE_TASK is the given name of the task, and its definition is stored in the dictionary. In this example, ADD_EMPLOYEE is a multiple-step task, and the processing step in the task uses a call to a subroutine. The processing work for ADD_EMPLOYEE must be handled by a procedure server.

The PERSONNEL_GROUP task group definition specifies a task group database, a DECforms form, and a message file. The task group definition specifies that the file SYS$SAMPLE:PERSONNEL.TDB is the name of the default task group database; the file SYS$SAMPLE:PERS_FORM contains the DECforms form; and the file SYS$SAMPLE:PERSMSG.EXE contains the message library. The tasks in the task group refer to the form by the name PERS_LABEL. If you do not name the task group database when you build the task group, ACMS uses the one specified with the DEFAULT TASK GROUP FILE clause.

The PERSONNEL_GROUP task group uses one procedure server, named PERSONNEL_SERVER. When the task group is built, ACMS creates an object module for the server. Linking this object module with other modules associated with the server and with the object module of the procedure used in ADD_EMPLOYEE produces the procedure server image in the file PERSGRP.EXE.

Because ADD_EMPLOYEE has just one processing step that uses a step procedure, PERSONNEL_SERVER includes that procedure, PERSADD, in addition to the initialization and termination procedures, PERS_START and PERS_STOP.

Example 4-3 shows an example of a more complex task group definition.

Example 4-3 More Complex Task Group Definition

CREATE GROUP PERSONNEL_GROUP 
  DEFAULT TASK GROUP FILE IS "SYS$SAMPLE:PERSONNEL.TDB"; 
  MESSAGE FILE IS "SYS$SAMPLE:PERSMSG.EXE"; 
  FORM IS "SYS$SAMPLE:PERS_FORM" 
          WITH NAME PERS_LABEL; 
  WORKSPACES ARE 
    PERSONNEL_USER_WORKSPACE 
      WITH TYPE USER ACCESS UPDATE LOCK, 
    PERSONNEL_GROUP_WORKSPACE 
      WITH TYPE GROUP ACCESS RETRIEVAL; 
  SERVERS ARE 
    PERSONNEL_SERVER: 
      PROCEDURE IMAGE IS "PERSGRP.EXE"; 
      INITIALIZATION PROCEDURE IS PERS_START; 
      TERMINATION PROCEDURE IS PERS_STOP; 
      PROCEDURE IS PERSADD; 
      DEFAULT OBJECT FILE IS "PERSERV.OBJ"; 
      NO RUNDOWN ON CANCEL; 
      CANCEL PROCEDURE PERSCANCEL; 
    UTILITY_SERVER: 
      DCL PROCESS; 
      DYNAMIC USERNAME; 
  END SERVERS; 
  TASKS ARE 
    ADD_EMPLOYEE: TASK IS ADD_EMPLOYEE_TASK; 
    DATR        : DELAY; 
                  PROCESSING IS DCL COMMAND "MCR DTR32" 
                    IN UTILITY_SERVER; 
  END TASKS; 
END DEFINITION; 

The task group definition for PERSONNEL_GROUP specifies that SYS$SAMPLE:PERSONNEL.TDB is the name of the default task group database; the file SYS$SAMPLE:PERS_FORM contains the DECforms form; and the file SYS$SAMPLE:PERSMSG.EXE contains the message library. The tasks in the task group refer to the form by the name PERS_LABEL.

The task group definition makes two workspaces available to all the tasks in the group: PERSONNEL_USER_WORKSPACE and PERSONNEL_GROUP_WORKSPACE. Because PERSONNEL_USER_WORKSPACE is a user workspace, each user using tasks in the group gets a separate copy of that workspace. A user can use a copy of the workspace for many instances of the same or different tasks. In addition, each user can lock the workspace for update.

Because PERSONNEL_GROUP_WORKSPACE is a group workspace defined for RETRIEVAL ACCESS, all the tasks in the group can use the contents of the workspace, but none can update those contents.

The task group uses two servers to handle the processing work for the tasks in the group, PERSONNEL_SERVER and UTILITY_SERVER. When the task group is built, ACMS creates an object module for PERSONNEL_SERVER and stores it in the file PERSERV.OBJ. When the PERSONNEL_SERVER procedure server starts, ACMS runs the initialization procedure whose entry point in the procedure server image is PERS_START. When the server stops, ACMS runs the termination procedure whose entry point in the procedure server image is PERS_STOP. If a cancel occurs while a task is doing processing, ACMS runs the cancel procedure whose entry point in the procedure server image is PERSCANCEL. However, ACMS does not stop and then restart the server when a cancel occurs.

The UTILITY_SERVER server is a reusable DCL server. The user name of UTILITY_SERVER changes to match the user name of the terminal user every time the server process is used.

The two tasks in the PERSONNEL task group are ADD_EMPLOYEE and DATR. The ADD_EMPLOYEE task has a definition whose CDD path name is ADD_EMPLOYEE_TASK. However, the DATR task contains just a single processing step, and the definition for the task is included directly in the task group definition. The DATR task runs the DCL command MCR DTR32. Because two servers are named in the task group definition, you must define which server you want the task to run in.

You must use the END DEFINITION keywords at the end of a task group definition.

4.2 Processing Subclauses

You can include the definition for a task directly in the task group definition when the task:

To define a task in a task group, you use a processing subclause within the TASKS clause of the task group definition.

Table 4-2 lists the processing subclauses and gives a brief description of each.

Table 4-2 Processing Subclauses
Clause Description
CALL [PROCEDURE] Names a procedure that ACMS runs.
CALL TASK Names a task to be called.
DATATRIEVE COMMAND Names a DATATRIEVE command to do the processing work for the step.
DCL COMMAND Names a DCL command to do the processing work for the step.
IMAGE Names an OpenVMS image to do the processing work for the step.

Use only one processing subclause to describe the work the task does.

When you define a task within the TASKS clause in a task group definition, you can use the WAIT, DELAY, LOCAL, GLOBAL, or CANCELABLE keywords to define attributes for the task. These keywords must precede the processing subclause.

You must use the END TASKS keywords to signal the end of the tasks you are defining within a TASKS clause. Figure 4-2 shows the syntax of the processing subclauses in the TASKS clause.

Figure 4-2 Processing Subclauses Syntax


4.3 Server Subclauses

Use the SERVERS clause to name the servers in a task group and to define the following:

Use server subclauses in the SERVERS clause to define each server you name.

If you define a server to be a DCL server, the only additional subclauses you can use to describe that server are the USERNAME subclause, the REUSABLE subclause, and the DYNAMIC USERNAME or FIXED USERNAME subclause. However, if you define a server to be a procedure server, you can use any of the clauses listed in Table 4-3 except DCL PROCESS.

You must use the END SERVERS keywords to signal the end of the servers you are defining within a SERVERS clause. Table 4-3 lists the server subclauses and gives a brief description of each.

Table 4-3 Server Subclauses
Clause Description
Server Type Subclauses
DCL PROCESS 1 Identifies a server that does work for processing steps that use DCL commands, OpenVMS images, or DATATRIEVE commands.
PROCEDURE SERVER IMAGE 2 Specifies the file name of the procedure server image and identifies the server as a procedure server.
Server Implementation Subclauses
ALWAYS EXECUTE TERMINATION PROCEDURE 2 Instructs ACMS to always process the server's termination procedure when the server process is run down.
CANCEL PROCEDURE 2 Names a procedure ACMS runs in the server when a task using the server is canceled.
DCL AVAILABLE 2 Specifies the loading of DCL into a procedure server process.
DEFAULT OBJECT FILE 2 Specifies a file name for the object module produced for a procedure server by the BUILD GROUP command.
INITIALIZATION PROCEDURE 2 Names a procedure to run when a procedure server image is started.
PROCEDURES 2 Names the procedures that run in a procedure server.
REUSABLE 1,2 Identifies a server as being able to process more than one processing step for one or more tasks before being restarted.
RUNDOWN ON CANCEL 2 Specifies whether ACMS should stop a procedure server when a task cancel occurs.
TERMINATION PROCEDURE 2 Names a procedure to run when a procedure server image is stopped.
Server Default Control Attributes
DYNAMIC USERNAME 1 Specifies that the user name, UIC, and default directory of a server change to match that of the user each time the server process is used.
FIXED USERNAME 1 Specifies that the user name, UIC, and default directory of the server are those associated with the user name under which the server starts.
USERNAME 1,2 Assigns the user name of the terminal user to the server process.


1You can use this clause when defining DCL servers.
2You can use this clause when defining procedure servers.

Figure 4-3 shows the syntax for server subclauses in the SERVERS ARE clause.

Figure 4-3 Server Subclauses Syntax



ALWAYS EXECUTE TERMINATION PROCEDURE Subclause (Server)

Specifies that ACMS should always process the server's termination procedure when the server process is run down.

Format

ALWAYS EXECUTE TERMINATION PROCEDURE ON RUNDOWN;


Clause Default

The ALWAYS EXECUTE TERMINATION PROCEDURE subclause is optional. If you do not specify this subclause, ACMS does not process the server's termination procedure if the server process runs down because the task is canceled.

Notes

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

By default, ACMS processes a server's termination procedure when the server process is run down, unless the server process is being run down because the task was canceled. There might be times when you want to override this default by specifying the ALWAYS EXECUTE TERMINATION PROCEDURE subclause. For example, a server that uses global sections might need to clean up information in the global sections when the server process is run down.


Example


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

In this example, when DEPARTMENT_SERVER is run down, ACMS runs the DEPART_SHUTDOWN termination procedure, even if the server process is being run down because the task was canceled.


CALL Subclause (Processing)

Names a procedure in a procedure server to do the work for a processing step.

Format

CALL PROCEDURE entry-point-name [IN server-name] [USING workspace-name [,...]];


Parameters

entry-point-name

The entry point name of the procedure called in the procedure server image.

server-name

The name of the server in which ACMS runs the procedure named by the CALL subclause. When you use the CALL subclause, the server you name must be a procedure server and must be declared in the definition of the task group containing the task you are defining. If you do not name a server, ACMS uses the last server named in the immediately preceding SERVERS clause.

workspace-name

The name of the workspace used by the procedure. You can name only the ACMS system workspaces when using the CALL subclause to define a task in a task group definition.

Clause Default

If you do not use a CALL subclause, ACMS does not call a procedure in a procedure server.

The CALL subclause is optional. If you are defining a task in a task group definition, you must include a CALL, DATATRIEVE COMMAND, DCL COMMAND, or IMAGE processing subclause within the TASKS clause.

The PROCEDURE command keyword is required if "task" or "procedure" is the procedure entry point name.


Note

Any procedure you name with the CALL subclause must run in a procedure server.

Examples

#1

TASK IS 
  ADDEMP: PROCESSING CALL PERSADD IN PERSONNEL_SERVER; 
END TASK; 
      

The ADDEMP task uses the PERSADD procedure in the PERSONNEL_SERVER.

#2

CREATE GROUP PERSONNEL_GROUP 
  MESSAGE FILE IS "SYS$SAMPLE:PERSMSG.EXE"; 
    FORM IS "SYS$SAMPLE:PERS_FORM" WITH NAME PERS_LABEL; 
        SERVER IS 
    PERSONNEL_SERVER: 
      PROCEDURE SERVER IMAGE IS "PERSGRP.EXE"; 
      INITIALIZATION PROCEDURE IS PERS_START; 
      TERMINATION PROCEDURE IS PERS_STOP; 
      PROCEDURE IS PERSADD; 
  END SERVER; 
  TASK IS 
    ADD_EMPLOYEE: PROCESSING CALL PERSADD; 
  END TASK; 
END DEFINITION; 
      

This task group definition names one task, ADD_EMPLOYEE. The definition for the task contains a single processing step that calls the PERSADD procedure. The CALL subclause does not name the server in which the procedure runs. By default, ACMS uses the last server defined in the task group, PERSONNEL_SERVER.


CANCEL PROCEDURE Subclause (Server)

Names a procedure that runs when a task instance is canceled while that task is executing a step procedure in the server or is maintaining server context in the server.

Format

CANCEL PROCEDURE IS cancel-entry-name ;


Parameter

cancel-entry-name

The entry point of the cancel procedure in the procedure server image. Do not enclose this name in quotation marks.

Clause Default

The CANCEL PROCEDURE subclause is optional. If you do not name a cancel procedure for a procedure server, ACMS does not run a cancel procedure for that server.

Notes

Use server cancel procedures to perform server process cleanup work to avoid having to run down a server process when a task is canceled while it retains context in the server. This cleanup work might include aborting a distributed transaction started by a step procedure; closing temporary files opened for a specific task instance; and closing terminal channels opened by a step procedure.

ACMS does not pass workspaces to server cancel procedures. Therefore, if you need information from workspaces to perform task cleanup work after a cancel, use the CANCEL ACTION phrase to call a step procedure.

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

When a task instance is canceled while that task is executing a step procedure in a server or is maintaining context in a server, ACMS runs the cancel procedure named in the CANCEL PROCEDURE subclause of the server definition for any servers assigned to that task instance. ACMS then either frees up the server to be used by another task instance or runs down the server process.

Because a distributed transaction can be aborted at any time, a server cancel procedure can be called before or after a distributed transaction has been aborted. Therefore, server cancel procedures should not rely on the state of a distributed transaction.

If a server has a cancel procedure, ACMS uses the status returned by the cancel procedure to determine whether or not to run down the server process. Table 4-4 shows the actions ACMS takes for each return status.

Table 4-4 Server Process Rundown Actions
Return Status Action taken by ACMS
  • ACMS$_RNDWN
Always run down server process.
  • ACMS$_RNDWNIFINT
Run down server process only if ACMS interrupts execution of a step procedure to cancel the task.
  • ACMS$_NRNDWN
  • Other
Do not run down server process unless absolutely necessary. For example, if a step procedure leaves channels open to a terminal, or if a fatal exception, such as an access violation, occurs, ACMS runs down the server process.

The cancel procedure must be linked into the procedure server image with all other procedures required by the server.

Name the cancel procedure for a server in the CANCEL PROCEDURE subclause. If you use the cancel procedure as a step procedure, you must also specify the name of the procedure in the PROCEDURES subclause.


Example


SERVERS ARE 
  PERSONNEL_SERVER: PROCEDURE IMAGE IS "PERSGRP.EXE"; 
                    PROCEDURE IS PERSADD; 
                    CANCEL PROCEDURE PERSCANCEL; 
  UTILITY_SERVER: DCL PROCESS; 
                  DYNAMIC USERNAME; 
END SERVERS; 
      

PERSCANCEL is the name of the entry point of the cancel procedure in the PERSONNEL_SERVER procedure server image.


Previous Next Contents Index