HP OpenVMS Systems Documentation

ACMS tests the value of the STATUS_FIELD in the EMP_CNTRL_WKSP workspace. As long as the value of that field is "INVAL", ACMS performs the TRANSCEIVE operation associated with the DO keyword. However, if the value of STATUS_FIELD does not equal "INVAL", ACMS passes control to the action part of the step and exits the task.

Processing Clause Example

PROCESSING
    WHILE (AGE_ENTERED >= 21)
    DO
       CALL STANDARD_PROCESSING USING WAGE_HOUR_DATA;

    END WHILE;
    ACTION IS
      GO TO STEP FIVE;
      

This WHILE DO clause tests the AGE_ENTERED workspace; and, if the Boolean expression evaluates to true, ACMS performs the processing work associated with the DO keyword. Otherwise, ACMS passes control to the action part of the step and goes to STEP FIVE.

Names one or more workspaces used by steps in a task. When you use the WORKSPACES clause in a task definition, the workspaces you name are available only to instances of that task.

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 just the given name of the workspace.

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

unique-name

The unique name of a workspace. The given name of each workspace must be unique within the workspace declarations for the task group. If two or more given names are identical, you use the unique-name parameter to define a different name to 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. You can only define access characteristics for GROUP and USER type workspaces. The default type of access is RETRIEVAL.

GROUP

Identifies the workspace as a GROUP type workspace. The contents of a GROUP workspace can be used by many instances of the same task. 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 can 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 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: TASK, GROUP, and USER.

UPDATE

Indicates that the task can make changes to the contents of the workspace. When the task instance finishes with an EXIT TASK, GOTO TASK, or REPEAT TASK clause, 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. The default workspaces available to the task are the ACMS system workspaces ACMS$PROCESSING_STATUS (contains processing status information), ACMS$SELECTION_STRING (contains a string submitted at task selection time), and ACMS$TASK_INFORMATION (contains task information). You cannot name the system workspaces in the WORKSPACES clause. System workspaces are always used by a task and are always implicitly declared.

For a discussion of system workspaces, see Appendix B.

Notes

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 WORK_RECORD:

WORKSPACE IS WORK_RECORD WITH NAME EXAMPLE1;

The record description for WORK_RECORD can be as follows:

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

The name of the record description, WORK_RECORD, simply 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 only used within the task 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.

Suppose you now add another field A to the workspace. Now the record definition looks like this:

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

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.

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.

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 include more than one WORKSPACES clause in a task definition.

If you declare a workspace with ACCESS UPDATE (either LOCK or NOLOCK), any other task can use the workspace with ACCESS RETRIEVAL. However, if you declare a workspace with ACCESS UPDATE (either LOCK or NOLOCK), ACMS cancels, at the beginning of the task instance, any other task or instance of the same task that attempts to use the same workspace with ACCESS UPDATE (either LOCK or NOLOCK).

The sum of the sizes of workspaces referenced in a task definition must not exceed 65,535 bytes.

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

WORKSPACES ARE DEPT_WORKSPACE, HIST_RECORD, PERS_RECORD;
      

This example assumes that CDD$DEFAULT has been set to the correct directory. The given names of the workspaces being used by the task are DEPT_WORKSPACE, HIST_RECORD, and PERS_RECORD.

WORKSPACES ARE
  ADD_WORKSPACE,LABOR_REPORT_WORKSPACE TYPE GROUP RETRIEVAL;
      

The given names of these workspaces are ADD_WORKSPACE and LABOR_REPORT_WORKSPACE. ADD_WORKSPACE is a TASK workspace with default UPDATE access. LABOR_REPORT_WORKSPACE is a group workspace, and the task definition using this workspace clause has retrieval access.

If the block step uses STREAM I/O, the WRITE clause writes the contents of a workspace field to a stream. If the block step uses REQUEST I/O, the WRITE clause passes a literal string or the contents of a workspace to the exception line (line 24) on the terminal screen.

Format

Parameters

workspace-name

The given name of the workspace that contains the text to be displayed on the exception line of the terminal screen (for block steps using REQUEST I/O) or to be written to a stream (for block steps using STREAM I/O). The workspace name must correspond to a workspace declared by the WORKSPACES or USE WORKSPACES clause in the task definition, or must be a system workspace.

literal-string

The text you want to display on the exception line of the terminal screen (for the block steps using REQUEST I/O) or to pass to a stream (for the block steps using STREAM I/O). You must enclose the string in quotation marks. The length of the literal string must be less than the width of the terminal screen. There is no length restriction when you use STREAM I/O.

Clause Default

The WRITE clause is optional. If you do not use the WRITE clause, ACMS does not pass a literal string or the contents of a workspace to the exception line on the terminal screen or to a stream.

Notes

When using REQUEST I/O, the maximum size of the information you pass is the length of a single line on the terminal screen, either 80 or 132 characters. There is no length restriction when you use STREAM I/O.

The sum of the sizes of all workspaces referenced in a task definition must not exceed 65,535 bytes.

Examples

WRITE PERS_MESSAGE;
      

ACMS writes the contents of the PERS_MESSAGE workspace to the exception line on the terminal screen.

WRITE "Processing done";
      

ACMS writes the literal string, "Processing done", on the exception line of the terminal screen.

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:

• Characteristics applying to all the tasks in the group
• Servers that handle the processing for the tasks in the group

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:

• Consists of a single unconditional processing step
• Defines no step actions or exception handler actions
• Defines no default server or default request library
• Uses no workspaces other than the ACMS system workspaces

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

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.

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.

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.

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:

• Consists of a single unconditional processing step
• Has no step actions or exception handler actions
• Uses no workspaces other than the ACMS system workspaces
• Does not name a default server or default request library

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.

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