|
HP OpenVMS Systems Documentation |
|
Compaq ACMS for OpenVMS
|
| Previous | Contents | Index |
Names the request libraries the task group uses.
request-library-file-spec
An identifier or quoted string pointing to the location of a TDMS request library or Request Interface user request procedure shared image file. The default device and directory are those defined with the application-level DEFAULT DIRECTORY clause in the definition of the application containing the task group. The default file type is .RLB for a TDMS request library and .EXE for a Request Interface user request procedure shared image file.library-name
A 1- to 31-character identifier you assign to the request library with the WITH NAME keywords. Tasks in the task group refer to a request library by its library name. If you name more than one request library in a task group definition, you must assign a library name to each library. However, if you name only one request library, you do not have to assign a library name to that library. In this case, the default name of the request library is the request library file specification.If you do not name a request library in a task definition, the request library defaults to the first request library named in the task group definition containing that task.
The REQUEST LIBRARIES clause is required if any of the tasks in the task group use TDMS requests called by exchange steps. If you do not name any request libraries, ACMS does not make any request libraries available to the task group.
You can use the REQUEST LIBRARIES clause more than once in a single task group definition.The request libraries you name with the REQUEST LIBRARIES clause must be available at run time. If the task group contains tasks that are accessed remotely, the UIC-based file protection on the request library files you name with the REQUEST LIBRARIES clause must grant world read access.
The request-library-file-spec parameter cannot be a search list.
| #1 |
|---|
REQUEST LIBRARY IS "ACMS$EXAMPLES:DEPART.RLB";
|
In this example, the file name of the request library is DEPART.RLB. The file is in the directory associated with the logical name ACMS$EXAMPLES.
| #2 |
|---|
REQUEST LIBRARIES ARE
"ACMS$EXAMPLES:DEPART.RLB" WITH NAME DEPARTREQ,
"ACMS$EXAMPLES:PERSREQ.RLB" WITH NAME PERSREQ;
|
When you name more than one request library for a task group, you must use the WITH NAME keywords to assign names to each library. Each task in the task group uses a library name to refer to the request library it uses. In this example, the unique names of the request libraries are DEPARTREQ and PERSREQ.
Identifies a server process as able to process more than one processing step for more than one task without being restarted. Server processes that are not reusable must be started each time they are needed.
[ NOT ] REUSABLE ;
The REUSABLE subclause is optional. DCL servers and procedure servers are reusable by default.
When a server is reusable, ACMS can delete the server process only when server context is released or at the end of a task instance. Except for servers with USERNAME OF TERMINAL USER, ACMS keeps the server process active for multiple processing steps. When a server is not reusable, ACMS deletes the server process at the end of each processing step.Only servers that are reusable can retain server context between processing steps of a task.
If a server has the USERNAME OF TERMINAL USER subclause, that server cannot be used by more than one task instance, whether it is reusable or not. ACMS runs down the server when server context is released.
Nonreusable procedure servers are designed for use where a step procedure opens channels to the task submitter's terminal, but does not close the channels before completing.
You can use a nonreusable procedure server to avoid ACMS canceling the task when a step procedure does not close all open channels to a task submitter's terminal. For optimal performance, nonreusable procedure servers should include only step procedures that do not close all open channels to a task submitter's terminal.
Nonreusable procedure servers cannot participate in distributed transactions. ADU does not build the task group, if a task that starts or participates in a distributed transaction contains a procedure call to a procedure server defined with the NOT REUSABLE clause.
SERVER IS
PERSONNEL_SERVER: DCL PROCESS;
REUSABLE;
DYNAMIC USERNAME;
END SERVER;
|
PERSONNEL_SERVER is a reusable DCL server with a dynamic user name.
Causes a procedure server to exit when a task cancel occurs while the task is keeping context in that server. When the server exits, ACMS releases server context.
The RUNDOWN ON CANCEL subclause is optional. The default characteristic is RUNDOWN ON CANCEL.
If you use the RUNDOWN ON CANCEL subclause and a task instance has active server context when the task is canceled, ACMS releases that context and stops that server process.If you specify the RUNDOWN ON CANCEL IF INTERRUPTED subclause, ACMS runs down the server process only if ACMS interrupts the execution of a step procedure due to an exception. For example, ACMS does not run down the server process if the task was simply retaining server context. Use the RUNDOWN ON CANCEL IF INTERRUPTED subclause to avoid unnecessary process deletions and creations.
When you use the NO RUNDOWN ON CANCEL subclause, ACMS does not release context or exit the server image. This can provide you with performance gains.
If you use the NO RUNDOWN ON CANCEL subclause, you must make sure that active recovery units are ended and all locks are released when the task is canceled. You can use a cancel procedure to release locks.
Use the NO RUNDOWN ON CANCEL subclause only when defining a procedure server.
SERVER IS
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;
PROCEDURE ARE
VR_COMPUTE_BILL_PROC,
VR_FIND_CU_PROC,
VR_FIND_SI_PROC;
END SERVER;
|
In this example, ACMS runs down the VR_READ_SERVER process only if an exception occurs which forces ACMS to interrupt the execution of one of the step procedures.
Defines the servers that handle the processing work for the tasks in a task group.
server-name
A 1- to 31-character unique name. Use this name to refer to the server from other clauses in the task group definition and from the application definition.server-subclause
Defines the characteristics of a server. Section 4.3 explains each of these subclauses.
The SERVERS clause is required. You must name at least one server for each task group you define.
You can use the SERVERS ARE clause more than once in a single task group definition.You can define two types of servers: DCL servers and procedure servers. When you define a procedure server, you create an executable image file that contains subroutines you call from task processing steps.
Use the SERVER subclauses to define DCL and procedure server attributes.
| #1 |
|---|
SERVER IS
PERSONNEL: DCL PROCESS;
FIXED USERNAME;
END SERVER;
|
The PERSONNEL server is a DCL server; it does the processing work for DCL commands or procedures, DATATRIEVE commands or procedures, or OpenVMS images. The user name assigned to the server is the user name under which the server starts.
| #2 |
|---|
SERVER IS
DEPARTMENT_SERVER:
PROCEDURE IMAGE IS "ACMS$EXAMPLES:DEPARTGRP.EXE";
INITIALIZATION PROCEDURE IS DEPART_STARTUP;
TERMINATION PROCEDURE IS DEPART_SHUTDOWN;
PROCEDURES ARE REVIEW_HISTORY_GET,
REVIEW_SCHEDULE_GET, REVIEW_UPDATE_GET;
END SERVER;
|
DEPARTMENT_SERVER is a procedure server: it handles the work of processing steps that include calls to subroutines. The procedure server image is in the file DEPARTGRP.EXE, which is in the directory associated with the logical name ACMS$EXAMPLES. The entry points in this image of the procedures that run when the image is started and stopped are DEPART_STARTUP and DEPART_SHUTDOWN. In addition, the entry points in the procedure server image of the procedures handled by the DEPARTMENT_SERVER are:
- REVIEW_HISTORY_GET
- REVIEW_SCHEDULE_GET
- REVIEW_UPDATE_GET
Identifies the tasks belonging to the task group you are defining.
task-name
A unique name you create to identify a task. You can use as many as 31 characters to define a task name. You must assign a unique task name to each task you define in the task group.processing-subclause
A subclause you use to define a task directly in a task group definition. You can define a task directly in a task group definition if that task:
- Consists of a single unconditional processing step
- Specifies no step actions
- Specifies no default server or default request library
- Uses no workspaces other than the ACMS system workspaces
If a task definition does not follow these rules, name the task in the task group definition, but define it separately and refer to it by its CDD task path.
A processing subclause describes the processing work for a task. The four processing subclauses are: CALL, CALL TASK, DATATRIEVE COMMAND, DCL COMMAND, and IMAGE. Section 4.2 explains these subclauses.
task-path
The CDD path name of a task definition. Use the task-path parameter to specify the location in the dictionary of task definitions not included in the task group definition. You must use the full CDD path name of each task unless you set your CDD default to the appropriate directory.
[ NO ] DELAY
Allows three seconds before ACMS clears the last screen of a task when that task ends. If you use the DELAY keyword, you cannot use the WAIT keyword in the same task definition. When you use the DELAY keyword, ACMS supplies it as a default value for the control definition of the task in the application. If you use the DELAY keyword, it must precede the processing subclause for the task.[ NO ] WAIT
When a task ends, the WAIT keyword causes the terminal to display a message requesting the user to press [Return] when finished looking at the information on the screen. If you do not use the WAIT keyword, ACMS returns the user to the menu when a task ends. When you use the WAIT keyword, you cannot use the DELAY keyword in the same task definition. If you use the WAIT keyword, it must precede the processing subclause for the task.GLOBAL
Specifies that a task can be selected from a menu, can be called by an agent, or can be called by another task. GLOBAL is the default task attribute.LOCAL
Specifies that a task can be called only by another task.CANCELABLE
Specifies whether or not a task can be canceled by a task submitter.
The TASKS clause is required. You must name at least one task for each task group you define.
Every task must have a unique name.You can use the TASKS clause more than once in a single task group definition.
If a task contains a block step, you cannot include the definition for that task in the task group definition.
You can, in a single task group definition, name tasks whose definitions are included in the task group definition, as well as tasks that are defined separately and referenced by the task group definition.
If you do not use the IN SERVER keywords with a processing subclause, ACMS uses the last server named in the immediately preceding SERVERS clause.
If you use neither the DELAY nor the WAIT keywords, ACMS returns the user to the menu when the task ends, unless the application definition specifies WAIT or DELAY for the task.
| #1 |
|---|
TASKS ARE
EDITOR: DELAY;
PROCESSING IS DCL COMMAND IS "$EDIT/TPU 'P1'"
IN PRIVATE_UTILITY_SERVER;
MAIL : PROCESSING IS
DCL COMMAND IS "$MAIL"
IN PRIVATE_UTILITY_SERVER;
END TASKS;
|
The two tasks named by this TASKS clause are: EDITOR and MAIL. The EDITOR task executes the DCL command EDIT/TPU, using a parameter the user supplies as a selection string. The server PRIVATE_UTILITY_SERVER handles this processing work. Because the task definition includes a DELAY clause, ACMS waits three seconds before clearing the last screen of the task and returning the user to a menu.
The MAIL task executes the DCL command MAIL within the DCL server PRIVATE_UTILITY_SERVER.
| #2 |
|---|
TASKS ARE
NEW_EMPLOYEE: TASK DEFINITION IS NEW_EMPLOYEE_TASK;
CHANGE_PROFILE: TASK DEFINITION IS CHANGE_PROFILE_TASK;
END TASKS;
|
In this example, the TASKS clause names the tasks NEW_EMPLOYEE and CHANGE_PROFILE associated with a task group. Both these tasks have task definitions stored in the dictionary. In this example, the default directory is DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES. Therefore, you need use only the given names of the task definitions, rather than their full CDD path names.
Names a procedure that runs when a procedure server image is stopped.
terminal-procedure-entry-name
The entry point of the termination procedure in the procedure server image.
The TERMINATION PROCEDURE subclause is optional. If you do not name a termination procedure, ACMS does not run any procedures when the procedure server is stopped.
Use the TERMINATION PROCEDURE subclause only when defining a procedure server.A termination procedure you name for a server runs only when the server is stopped; it does not run when each task using the server stops or when a processing step using the server stops. However, servers can be stopped at any time while the application is running, depending on the processing load of the application.
When you name a termination procedure for a procedure server, you normally also name an initialization procedure for that server.
You can name only one termination procedure for each server you define.
A termination procedure performs such activities as closing files used by the tasks handled by a server.
You can name a termination procedure for a server in the PROCEDURES subclause for that server. However, you must also name the procedure in the TERMINATION PROCEDURE subclause.
By default, if a procedure server process runs down because of a task cancel, ACMS does not process the termination procedure. To override this default, use the ALWAYS EXECUTE TERMINATION PROCEDURE server subclause.
SERVER IS
DEPARTMENT_SERVER:
PROCEDURE IMAGE IS "ACMS$EXAMPLES:DEPARTGRP.EXE";
INITIALIZATION PROCEDURE IS DEPART_STARTUP;
TERMINATION PROCEDURE IS DEPART_SHUTDOWN;
PROCEDURES ARE
REVIEW_HISTORY_GET,REVIEW_SCHEDULE_GET,REVIEW_UPDATE_GET;
END SERVER;
|
When DEPARTMENT_SERVER is stopped, ACMS runs a termination procedure. The entry point of this procedure in the procedure server image is DEPART_SHUTDOWN.
Indicates that the server process runs under the OpenVMS user name of the terminal user, using the UIC and default directory of that user.
USERNAME IS USERNAME OF TERMINAL USER ;
ACMS assigns to the server process the user name you give to the execution controller in the application definition.
The USERNAME subclause is overridden by any user name specified for the server in the application definition.If you define a server to have the user name of the terminal user, that server cannot be reusable and cannot have a dynamic user name.
The REUSABLE server subclause in the task group definition is the default for both DCL and procedure servers. However, using the clause USERNAME OF TERMINAL USER in application or task group definitions overrides this default and creates servers that are not reusable. Every time a terminal user selects a task running a server defined with the USERNAME OF TERMINAL USER clause, a separate server process is created for that user. For best performance, your application should run as few servers as needed to perform the application.
SERVER IS
PRIVATE_UTILITY_SERVER: DCL PROCESS;
USERNAME OF USER;
NOT REUSABLE;
END SERVER;
|
The user name of PRIVATE_UTILITY_SERVER is the same as the user name of the terminal user.
Declares one or more workspaces used by the tasks in a task group.
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 only the given name of the workspace.If you name more than one workspace, separate the record path names with commas.
unique-name
A unique name for a workspace. The name of each workspace must be unique within the workspace declarations for the task group. If two or more given names of record path names are identical, you use the unique name parameter to define a different name for the workspace. If you do not use the unique-name parameter, the default name of the workspace is the given name of the workspace.
ACCESS
Identifies the access characteristics of a workspace. The types of access you can define are RETRIEVAL and UPDATE. Because TASK workspaces always have update access, define access characteristics only for GROUP and USER type workspaces. The default access type is RETRIEVAL.GROUP
Identifies the workspace as a GROUP workspace. The contents of a GROUP workspace can be used by many instances of the same or different tasks. 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 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 type 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: GROUP, TASK, and USER.UPDATE
Indicates that the task can make changes to the contents of the workspace. When the task finishes, 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.
The WORKSPACES clause is optional. If you do not name workspaces in a task group definition, tasks in that group can use only workspaces declared in task definitions.In addition, ACMS provides a set of system workspaces that are available by default. The system workspaces are:
- ACMS$PROCESSING_STATUS
Contains processing status handling information- ACMS$SELECTION_STRING
Contains a string submitted at task selection time- ACMS$TASK_INFORMATION
Contains task informationYou cannot name the system workspaces in the WORKSPACES clause. System workspaces are always used by the tasks in a task group and are always implicitly declared. For a discussion of the system workspaces, see Appendix B.
Use the USE WORKSPACES task clause to have a task access a workspace defined in the task group definition. When you use the USE WORKSPACES clause in a task definition, you can override access restrictions defined for a workspace in the task group.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.
When you want to specify the version of a workspace that has the highest version number, use a semicolon after the workspace name, followed by a zero. Using a semicolon alone causes an error.
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 use the WORKSPACES clause more than once in a task group definition.
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 SAMPLE_WORKSPACE:
WORKSPACE IS SAMPLE_WORKSPACE WITH NAME EXAMPLE1;The record description for SAMPLE_WORKSPACE can be as follows:
DEFINE RECORD SAMPLE_WORKSPACE. SAMPLE STRUCTURE. A. B. END SAMPLE STRUCTURE. END SAMPLE_WORKSPACE RECORD.The name of the record description SAMPLE_WORKSPACE 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 used only within the task group 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.
If you add another field A to the workspace, the record definition looks like this:
DEFINE RECORD SAMPLE_WORKSPACE. SAMPLE STRUCTURE. A. B. X STRUCTURE. A. END X STRUCTURE. END SAMPLE STRUCTURE. END SAMPLE_WORKSPACE.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.
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
| #1 |
|---|
WORKSPACE IS
DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.DEPT_WORKSPACE;
|
Previous Next Contents Index