| Previous | Contents | Index |
Once you create one or more task definitions, you can take the two final steps to prepare the definitions for debugging:
This chapter explains these steps.
10.1 Defining a Task Group
Often you have a set of tasks that have common characteristics or require the same resources. You group these tasks in task groups. Task groups let you set up resources needed by a number of tasks, such as the servers those tasks use.
Just as the task part of a task definition sets up characteristics for the steps in the task, a task group definition sets up characteristics for the tasks in that group.
There are several characteristics you can define for a task group:
Of these characteristics, you must always define the first two: the
tasks that belong to the group and the server or servers that do work
for those tasks. The third characteristic is required only if you use
requests or the GET ERROR MESSAGE clause in any of the tasks in the
task group. Declaring workspaces used by tasks in the task is optional;
the task database file name is optional.
10.2 Identifying Which Tasks Belong to the Task Group
In a task group definition you must identify the tasks belonging to that group. For example, in Figure 10-1, the Department task group includes three tasks.
Figure 10-1 A Task Group and Its Tasks
You name the tasks in the definition for the Department task group as follows:
TASKS ARE REVIEW_HISTORY : TASK IS REVIEW_HISTORY_TASK; REVIEW_SCHEDULE : TASK IS REVIEW_SCHEDULE_TASK; REVIEW_UPDATE : TASK IS REVIEW_UPDATE_TASK; END TASKS |
When you name a task in a task group definition:
Use a colon (:) to separate the task name and the path name. Unless you set your CDD default to the correct directory when you build the definition, you must use the full CDD path name of each task you define. If you have set your CDD default, you can use just the given name of each task, as in the previous example, or a partial CDD path name.
You can also include single-step task definitions directly in a task group definition rather than creating a separate definition for this task and referencing it by a CDD path name in the task group definition:
TASKS ARE
EDITOR : DELAY;
PROCESSING IS
DCL COMMAND IS "$EDIT/EDT 'P1'" IN PRIVATE_UTILITY_SERVER;
|
See Chapter 13 for an explanation of single-step tasks.
10.3 Identifying Which Servers Are Required in the Group
When you write a definition for a multiple-step task, you name the server or servers required to handle the processing work for that task. Many tasks can use the same server. DCL servers handle DCL commands or procedures, DATATRIEVE commands or procedures, and OpenVMS images. Procedure servers handle calls to procedures or subroutines.
There are two characteristics you must define for each server you name in a task group:
The server type can be either DCL PROCESS or PROCEDURE SERVER. The procedures you name for a procedure server are the procedures named in the processing steps of tasks using that server.
The Department task group uses a single procedure server.
SERVER IS
DEPARTMENT_SERVER:
PROCEDURE SERVER IMAGE IS "ACMS$EXAMPLES:DEPRMSCOB.EXE";
.
.
.
END SERVER;
|
When you use the PROCEDURE SERVER clause to identify the server type, you must also name the file specification of the image for the server you are describing. The procedure server image is the runnable collection of all the procedures handled by a server. It is the result of linking:
For example, the file DEPRMSCOB.EXE is the result of linking:
If you define the server type to be PROCEDURE SERVER, you must name the step procedures handled by a server. For example:
SERVER IS
DEPARTMENT_SERVER:
PROCEDURE SERVER IMAGE IS "ACMS$EXAMPLES:DEPRMSCOB.EXE";
PROCEDURES ARE
REVIEW_HISTORY_GET, REVIEW_SCHEDULE_GET,
REVIEW_UPDATE_GET, REVIEW_UPDATE_PUT;
.
.
.
END SERVER;
|
These are the procedure names the Review History, Review Schedule, and Review Update task definitions use in their processing steps. The names are the entry points for these procedures in the procedure server image. In the PROCEDURES clause, you can also name initialization, termination, and cancel procedures; however, only the names of step procedures are required.
There are additional characteristics you can describe for a procedure server:
Tasks using the same procedure server usually require one or more of the same files. For example, the Review History, Review Schedule, and Review Update tasks all use the Personnel and History files. Rather than opening and closing files for each task, you can name, for a server, procedures that open and close files when that server starts and stops. These procedures are called initialization and termination procedures. You name each procedure as part of the server definition:
INITIALIZATION PROCEDURE IS DEPART_STARTUP; TERMINATION PROCEDURE IS DEPART_SHUTDOWN; |
You identify an initialization or termination procedure by its entry point in the procedure server image. DEPART_STARTUP is the entry point of the initialization procedure in the image for the PERSONNEL procedure server. If you are using a procedure written in COBOL, it begins with an IDENTIFICATION DIVISION, which defines the entry point as the PROGRAM-ID:
IDENTIFICATION DIVISION. PROGRAM-ID. DEPART_STARTUP. |
If you use BASIC, the entry point is the function name of the initialization or termination procedure. You do not enclose the procedure name within quotation marks.
A server definition can also name a cancel procedure. This procedure usually releases record locks and performs other cleanup work for the server. If a task is canceled either during a processing step or while ACMS is retaining process context in a task, ACMS runs the cancel procedure named for the server being used by the task when the cancel occurs.
CANCEL PROCEDURE IS DEPART_CANCEL; |
As with initialization and termination procedures, the name of the cancel procedure is its entry point in the procedure server image. Do not enclose the procedure name within quotation marks.
When you build a task group, ACMS creates an object file, called the procedure server transfer module, for each procedure server named in the definition for that group. You can use the DEFAULT OBJECT FILE clause to define, for a server, the file specification you want ACMS to use for the object file it creates. For example:
DEFAULT OBJECT FILE IS "ACMS$EXAMPLES:DEPRMSCOB.OBJ"; |
You can also use logical names to name the location of the default object file. Enclose the file specification within quotation marks. If you do not name an object file, ACMS derives the name of the file from the the full given name you assign to the server in the task group definition, including dollar signs and underscores.
Here is the SERVER IS clause for the Department task group:
SERVER IS
DEPARTMENT_SERVER:
PROCEDURE SERVER IMAGE IS "ACMS$EXAMPLES:DEPRMSCOB.EXE";
PROCEDURES ARE
REVIEW_HISTORY_GET, REVIEW_SCHEDULE_GET,
REVIEW_UPDATE_GET, REVIEW_UPDATE_PUT;
INITIALIZATION PROCEDURE IS DEPART_STARTUP;
TERMINATION PROCEDURE IS DEPART_SHUTDOWN;
CANCEL PROCEDURE IS DEPART_CANCEL;
DEFAULT OBJECT FILE IS "ACMS$EXAMPLES:DEPRMSCOB.OBJ";
END SERVER;
|
In addition to naming the procedures, procedure server image, and default object file, you can use the server definition to specify attributes that affect the modularity and, possibly, the performance of your application. This section describes two such attributes, the RUNDOWN ON CANCEL IF INTERRUPTED and ALWAYS EXECUTE TERMINATION PROCEDURE server subclauses.
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 ALWAYS EXECUTE TERMINATION PROCEDURE. 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. The ALWAYS EXECUTE TERMINATION PROCEDURE subclause instructs ACMS to process the server's termination procedure whenever the server process is run down.
By default, ACMS runs down a server process when the task is canceled while the task is keeping context in that server. When the server exits, ACMS releases server context. Preventing unnecessary process deletions and creations can improve the performance of your application. You can use the RUNDOWN ON CANCEL IF INTERRUPTED server subclause to instruct ACMS to run down the server process only if ACMS interrupts the execution of a step procedure due to an exception. ACMS does not run down the server process if, for example, the task is simply retaining context when you specify RUNDOWN ON CANCEL IF INTERRUPTED.
Example 10-1 shows a server definition that specifies ALWAYS EXECUTE TERMINATION PROCEDURE and RUNDOWN ON CANCEL IF INTERRUPTED.
| Example 10-1 Definition of VR_READ_SERVER |
|---|
SERVERS ARE
VR_READ_SERVER:
PROCEDURE SERVER IMAGE IS "AVERTZ_DEFAULT:VR_READ_SERVER.EXE";
INITIALIZATION PROCEDURE IS VR_READ_INIT;
TERMINATION PROCEDURE IS VR_TERM;
ALWAYS EXECUTE TERMINATION PROCEDURE ON RUNDOWN;
RUNDOWN ON CANCEL IF INTERRUPTED;
PROCEDURES ARE
VR_COMPUTE_BILL_PROC,
VR_FIND_CU_PROC,
VR_FIND_SI_PROC,
VR_FIND_VE_VRH_PROC,
VR_FIND_RES_PROC,
VR_RES_DETAILS_PROC;
DEFAULT OBJECT FILE IS "AVERTZ_DEFAULT:VR_READ_SERVER.OBJ";
|
Once you have defined the tasks in a task group and the servers used by
those tasks, you can consider other characteristics of the task group,
such as the request libraries, message files, and workspaces used by
the tasks in the group.
10.4 Naming Request Libraries
When you define tasks, you can name TDMS requests in the exchange steps. For ACMS to process a request, it must know in which request library to find it. This library stores the definitions for all the requests that you use for tasks in the group. For example, all the requests you use in the exchange steps of tasks in the Department task group are in the same request library.
For each task group definition, you name all the request libraries used by tasks in the task group:
REQUEST LIBRARY IS "ACMS$EXAMPLES_DEPRMSRLB"; |
In this example, ACMS$EXAMPLES_DEPRMSRLB is the name of the request library. This name is a logical name pointing to the location of the request library file. The default file type is .RLB. If you do not name a directory, ACMS uses the directory named by the DEFAULT DIRECTORY clause in the application definition. You must enclose the file name of the request library within quotation marks if there are characters in that name that are invalid for an identifier (such as periods, colons, or semicolons), or if the name is longer than 31 characters.
If you name just one request library, ACMS uses that request library for all the tasks in the group. If different tasks in the group use different libraries, or if different steps in a single task use different libraries, you must name all these request libraries in the task group definition. In this case, you must also assign a name to each request library you name. For example:
REQUEST LIBRARY IS "ACMS$EXAMPLES_DEPRMSRLB" WITH NAME DEPARTREQ; |
The name you assign to a request library is an identifier containing 1 to 31 characters. When writing a task definition, you use this name in the DEFAULT REQUEST LIBRARY clause or with the IN keyword of the REQUEST clause to identify the request library used by the task or exchange step. For example:
EXCHANGE
REQUEST IS REVIEW_HISTORY_INPUT_REQUEST
IN DEPARTREQ USING REVIEW_HISTORY_WORKSPACE;
|
If you do not name the request library with the IN keyword of the REQUEST clause of an exchange step, and you do not use the DEFAULT REQUEST LIBRARY clause in the definition of the task containing that step, ACMS uses the first request library named in the task group containing the task.
When defining a task group whose tasks call only user request procedures (URPs) , you can use the REQUEST LIBRARY IS clause to name the shareable image containing URP procedures. The shareable image must have a .EXE extension. You may specify a complete file specification or a logical name in the REQUEST LIBRARY IS clause. If you use a logical name (the recommended method), be sure to define the logical name to translate to a full file specification with a .EXE extension. If the logical name does not contain the .EXE extension, the EXC uses the .RLB default when it tries to open all the files declared in the REQUEST LIBRARY IS clauses. This action causes the ACMS/START APPLICATION to fail, unless ACMS finds a TDMS (.RLB) file of the same name.
For information on building request libraries, see VAX TDMS Request and Programming Manual.
10.5 Identifying Which Message Files Are Used in the Group
Just as you declare the request libraries containing requests used by tasks in a task group, you must name the message files used by the tasks in a group. You use the MESSAGE FILES clause as follows:
MESSAGE FILE IS "ACMS$EXAMPLES:DEPARTMSG.EXE"; |
When you use the MESSAGE FILES clause, you use the name of the image (.EXE) version of the message file. In this example, the message file used by the Department task group is the file ADMINMSG.EXE in the directory with the logical name ACMS$EXAMPLES. If you do not name a directory, ACMS uses the directory named by the DEFAULT DIRECTORY clause of the application definition.
For information on creating message files, see Compaq ACMS for OpenVMS Writing Server Procedures.
10.6 Naming Workspaces in a Task Group Definition
Often workspaces are used by more than one task in a task group. You can name these workspaces in the task group definition. You use the USE WORKSPACES clause in a task definition that uses workspaces named in the task group. For example, suppose that you declare DEPT_WORKSPACE in the definition for the Department task group:
WORKSPACE IS DEPT_WORKSPACE WITH TYPE USER; |
The Review History task uses the USE WORKSPACE clause to refer to the DEPT_WORKSPACE named in the task group definition:
USE WORKSPACE DEPT_WORKSPACE; |
When you use the USE WORKSPACE clause, you can change the access
restrictions that are defined for the workspace in the task group
definition. You cannot change the workspace type.
10.7 Naming the Task Database for a Task Group
When you build a task group, ACMS creates a task database for that task group. ACMS uses the database at run time to get information about processing tasks selected by a user. You can use the DEFAULT TASK GROUP FILE clause to assign the file specification you want ACMS to use when creating the task database. For example:
DEFAULT TASK GROUP FILE IS "ACMS$EXAMPLES:DEPRMSCOB.TDB"; |
If you do not use a file specification with the BUILD command, ACMS uses the file specification, if any, you named in the DEFAULT TASK GROUP FILE clause. If you do not use the DEFAULT TASK GROUP FILE clause, ACMS derives the file specification from the full given name of the task group, including dollar signs and underscores.
Example 10-2 shows the complete definition for the Department task group.
| Example 10-2 Definition of Department Task Group |
|---|
REPLACE GROUP DEPART_TASK_GROUP/LIST=DEPGRP.LIS
REQUEST LIBRARY IS "ACMS$EXAMPLES_DEPRMSRLB";
MESSAGE FILE IS "ACMS$EXAMPLES:DEPARTMSG.EXE";
DEFAULT TASK GROUP FILE IS "ACMS$EXAMPLES:DEPRMSCOB.TDB";
TASKS ARE
REVIEW_HISTORY : TASK IS REVIEW_HISTORY_TASK;
REVIEW_SCHEDULE: TASK IS REVIEW_SCHEDULE_TASK;
REVIEW_UPDATE : TASK IS REVIEW_UPDATE_TASK;
END TASKS;
SERVER IS
DEPARTMENT_SERVER:
PROCEDURE SERVER IMAGE IS "ACMS$EXAMPLES:DEPRMSCOB.EXE";
PROCEDURES ARE
REVIEW_HISTORY_GET, REVIEW_SCHEDULE_GET,
REVIEW_UPDATE_GET, REVIEW_UPDATE_PUT;
INITIALIZATION PROCEDURE IS DEPART_STARTUP;
TERMINATION PROCEDURE IS DEPART_SHUTDOWN;
CANCEL PROCEDURE IS DEPART_CANCEL;
DEFAULT OBJECT FILE IS "ACMS$EXAMPLES:DEPRMSCOB.OBJ";
END SERVER;
END DEFINITION;
|
This definition does not include all the clauses you can use to define a task group. An additional characteristic you can define for a task group is a list of the workspaces used by tasks in that group. For a complete list and explanation of all the task group clauses, see the Compaq ACMS for OpenVMS ADU Reference Manual.
Once you have written a task group definition, you can store it in the CDD. If you include the CREATE or REPLACE command in the definition source file, you submit the file to the ADU as a command file:
ADU> @DEPARTGRP.COM |
If you did not include the REPLACE command in the source definition file, you use the REPLACE command in response to the ADU> prompt. For example:
ADU> REPLACE GROUP DEPART_TASK_GROUP DEPART.GDF |
This command stores the definition in the DEPART.GDF file in the CDD, using the name DEPART_TASK_GROUP. Common errors you might receive when you use the CREATE command are:
The CREATE command does not check whether the task group definition is valid or correct, such as whether the tasks named in the definition exist or whether file specifications are correct; it checks only for correct syntax. ACMS checks file specifications only at run time. However, references to CDD definitions are checked when you build the task group.
Once you have defined a task group and stored the definition in the CDD, you can go on to build the task group.
| Previous | Next | Contents | Index |