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:
- 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.
| 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:
- Server type
- Implementation characteristics of the server
- Default control characteristics of the server
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.
| 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 |