HP OpenVMS Systems Documentation
Compaq ACMS for OpenVMS
You cannot retain server context when calling a task from another task.
If a task that is retaining context in a server process attempts to call another task, ACMS unconditionally cancels the calling task.
TDMS does not support multiple sessions to the same device and limits
form context to a request using the same form as the previous request.
Therefore, called tasks using TDMS I/O always share form context with
the parent task.
5.1.8 Using the NOT CANCELABLE BY TASK SUBMITTER Clause
Depending on the type of task, you might sometimes want to prevent a task from being canceled by the terminal user. To accomplish this, ACMS lets you specify the NOT CANCELABLE BY TASK SUBMITTER clause in your task definition. The NOT CANCELABLE BY TASK SUBMITTER clause tells ACMS to ignore a submitter cancel request generated in situations such as when a terminal user presses [Ctrl/Y]. This clause affects a task only when it is currently executing.
In Example 5-8, if the user presses [Ctrl/Y] while the MAIN_MENU task is running, ACMS ignores the request to cancel the task. However, when the MAIN_MENU task calls the ENTER_ORDER task, [Ctrl/Y] cancels the called task.
|Example 5-8 MAIN_MENU Task|
WORKSPACE IS TASK_CTL_WSP; NOT CANCELABLE BY TASK SUBMITTER; BLOCK WORK EXCHANGE RECEIVE FORM RECORD GET_SELECTION_FORM_REC_LIS RECEIVING TASK_CTL_WSP, TASK_CTL_WSP; ACTION IS CONTROL FIELD TASK_CTL_WSP.TASK_CTL_FIELD "QUIT" : EXIT TASK; END CONTROL FIELD; PROCESSING SELECT FIRST TRUE ( TASK_NUMBER = 1 ): CALL TASK ADD_CUSTOMER; ( TASK_NUMBER = 2 ): CALL TASK MODIFY_CUSTOMER; ( TASK_NUMBER = 3 ): CALL TASK ENTER_ORDER; ( TASK_NUMBER = 4 ): CALL TASK MODIFY_ORDER; ( TASK_NUMBER = 5 ): CALL TASK DISPATCH_ORDERS; END SELECT; ACTION IS CONTROL FIELD IS ACMS$T_STATUS_TYPE "T": GOTO PREVIOUS EXCHANGE; NOMATCH: GET ERROR MESSAGE; GOTO PREVIOUS EXCHANGE; END CONTROL FIELD; END BLOCK WORK;
The MAIN_MENU task:
If a called task returns a success status, the menu task prompts for
another task selection. If a called task returns a failure status, the
MAIN_MENU task uses the GET MESSAGE phrase to retrieve the error text
associated with the returned status value, so that the task selection
form can display the message for the user. The NOT CANCELABLE BY TASK
SUBMITTER clause prevents the user from canceling the menu task itself
by typing [Ctrl/Y].
5.1.9 Auditing and Operation
This section describes how to audit and operate task-calling
188.8.131.52 Task Auditing and Security
ACMS always checks the task access control list (ACL) to determine whether you can execute a task, even when the task is called from another task.
To audit instances of tasks called by other tasks, ACMS appends the
call sequence number to the Task ID field. The ACMS$TASK_INFORMATION
system workspace describes the call sequence number.
184.108.40.206 Using ACMS Operator SHOW and CANCEL Commands
The ACMS operator command ACMS/SHOW USER/FULL displays the following types of task selections:
The ACMS/SHOW USER/FULL command does not display any tasks called by another task. For example:
$ ACMS/SHOW USER TESTU1/FULL ACMS V4.0 CURRENT USERS Time: 24-MAR-1994 10:17:53.80 User Name: TESTU1 Submitter ID: GROW::00010025 Agent PID: 21C0043F Device: RTA3: Task Name: VR_CHECKIN_TASK Task ID: GROW::00010025-00000005 Appl Name: VR_APPL Appl Node: GROW::
To display all the task instances in a sequence of task calls, use the ACMS operator command ACMS/SHOW TASKS. For example:
$ ACMS/SHOW TASKS ACMS V4.0 CURRENT TASKS Time: 24-MAR-1994 10:21:20.12 Task Name: VR_CHECKIN_TASK State: Active; Executing PROCESSING step WORK Step Label: GET_RESV Task ID: GROW::00010025-00000005 Application: VR_APPL User Name: TESTU1 Submitter ID: GROW::00010025 Device: RTA3: Called Task: VR_GETRESV_TASK State: Active; Executing EXCHANGE step WORK Step Label: CHANGE_INFO Task ID: GROW::00010025-00000005-00000001
ACMS indents called tasks under the header of the parent task. This example illustrates that task VR_CHECKIN_TASK has called task VR_GETRESV_TASK. The report appends the task call sequence number for the called tasks to the end of the task ID.
The ACMS operator command ACMS/CANCEL USER cancels:
The ACMS operator command ACMS/CANCEL TASK accepts an optional third hexadecimal number that indicates the task call sequence number of the task instance to be canceled. If the operator omits the third number, ACMS cancels all the task instances in the task call sequence. For example, the following command cancels both of the tasks displayed in the previous example:
$ ACMS/CANCEL TASK/IDENTIFIER=GROW::00010025-00000005
The following command cancels VR_GETRESV_TASK. You can omit leading zeros from each number in the task ID.
$ ACMS/CANCEL TASK/IDENTIFIER=GROW::10025-5-1
This chapter describes how to use detached tasks in ACMS applications.
For information about ACMS operator commands, refer to Compaq ACMS for OpenVMS Managing Applications.
6.1 Overview of Detached Tasks
This section provides an overview of detached tasks, describes an
application that effectively implements the interactive and deferred
processing modes of task execution, and lists the characteristics of
6.1.1 Detached Tasks
ACMS typically does interactive processing of the tasks in your
applications, but certain tasks capture data that does not require
immediate processing. Detached tasks provide ACMS applications with a
mechanism to start a task with an ACMS operator command, while allowing
the task to execute in an unattended, noninteractive manner once it has
6.1.2 Designing Your Application to Use Detached Tasks
ACMS supports two basic modes of task execution:
In the interactive work flow mode, ACMS tasks collect requests from a user and process the requests while the user waits for a response. Users interact with the executing task through a terminal or device. A typical task has an exchange step to accept data from a user, followed by a processing step to process the data. The next exchange step returns control to the terminal to complete the task, or to continue to request input from the terminal.
The detached processing mode is similar to batch-style processing, where no user interaction occurs through a terminal or device, from a task executing within the Application Execution Controller (EXC). A task that executes in this mode is called a detached task.
To illustrate the two modes of task execution, consider the following example involving a manufacturing and distribution company. The company has its headquarters and manufacturing facility based in one location, and multiple distribution centers located remotely. At its headquarters, the company maintains a master database, using Rdb, that holds information about its entire operation. In addition, smaller Rdb databases, located at each distribution center, hold information specific to that segment of the business.
During the day, changes are made to the distribution center databases. These changes necessitate updates to the master database. As the changes are made to the distribution center database, records are queued to a queue database on the distribution center's system. The records are then forwarded to the central system. To update the distribution center databases, an employee executes a task through a terminal device. This is an example of the interactive work flow mode.
Subsequently, a task running continuously in the background without any
human interaction is executed to update the master database at the
central system. This task is a detached task, and shows how an
application uses the detached processing mode.
6.1.3 Characteristics of Detached Tasks
Detached tasks have the following characteristics:
The following sections describe:
To start a detached task, use the ACMS/START TASK command. When starting a detached task, specify the task name and the application name where the task executes. You can also specify a retry limit, retry wait timer, user name, and a selection string to pass workspace data.
$ ACMS/START TASK task-name application-name
Example 6-1 shows an audit message for starting a detached task.
|Example 6-1 Audit Message for Starting a Detached Task|
Type : TASK Time : 16-APR-1994 10:57:41.79 Appl : DIST_APPL Task : DEQUEUE_TASK User : SMITH ID : MYNODE::00020013-00000001-B985D5E0-009576B2 Sub : MYNODE::00020013-00000000-B985D5E0-009576B2 Text : Detached task started
See Compaq ACMS for OpenVMS Managing Applications for more information about the ACMS/START TASK
6.2.2 Setting the Retry Limit
The retry limit is the maximum number of times ACMS retries the detached task after a failure. The following command starts a detached task and specifies that the task can be retried a maximum of 10 times after a task failure:
$ ACMS/START TASK timer_task dist_appl/RETRY_LIMIT=10
If the detached task retry limit is exceeded, then an audit message of type ERROR is written to the audit log. Example 6-2 shows an audit message that results when the task exceeds the retry limit.
|Example 6-2 Audit Message for Exceeding the Retry Limit|
Type : ERROR Time : 19-APR-1994 12:07:48.22 Appl : DIST_APPL Text : Detached Task DEQUEUE_TASK terminated due to retry limit being exceeded
The retry wait timer indicates the number of seconds ACMS waits before
retrying the detached task after a task failure. The default value is 5
seconds. The minimum value is 1 second, and the maximum is 65,535
seconds. If the detached task is started with a retry limit of 0, or if
the task completes successfully, the retry wait timer is not used.
6.2.4 Showing the Status of Detached Tasks
The following sections describe two operator commands that allow you to
determine if a detached task is active, and whether the task has
started and has not completed.
220.127.116.11 Using the ACMS/SHOW TASK Command
$ ACMS/SHOW TASK task-name
If a detached task is active, then ACMS displays a message similar to Example 6-3.
|Example 6-3 ACMS/SHOW TASK Message for Detached Tasks|
ACMS V4.0 CURRENT TASKS Time: 16-APR-1994 09:58:19.15 Task Name: DEQUEUE_TASK ***Detached Task*** State: Active; Executing PROCESSING step WORK Step Label: $STEP_3 Task ID: MYNODE::00020016-00000001 Application: DIST_APPL User Name: JONES Submitter ID: MYNODE::00020016 Device: NL:
While the ACMS/SHOW TASK command shows only detached tasks that are active, the ACMS/SHOW APPLICATION/DETACHED_TASKS command shows all detached tasks that have started and have not completed.
Use the following command to display the status of all detached tasks:
$ ACMS/SHOW APPLICATION/DETACHED_TASKS
ACMS displays the message shown in Example 6-4.
|Example 6-4 ACMS/SHOW APPLICATION/DETACHED_TASKS Message|
ACMS V4.0 CURRENT APPLICATIONS Time: 16-APR-1994 09:58:20.65 Application Name: DIST_APPL State: STARTED Task Name: DEQUEUE_TASK Task State: Active Submitter ID: MYNODE::00020016 Username: JONES Retry Limit: 10 Retry Count: 2 Retry Wait Timer: 60 Task Name: UPDATE_CENTRAL_TASK Task State: Waiting to Retry Submitter ID: MYNODE::00020017 Username: SMITH Retry Limit: 10 Retry Count: 0 Retry Wait Timer: 60
See Compaq ACMS for OpenVMS Managing Applications for more information about the ACMS/SHOW
APPLICATION/DETACHED_TASKS operator command.
6.2.5 Stopping a Detached Task
Use the ACMS/CANCEL TASK or ACMS/CANCEL USER operator commands to stop a detached task when you need to cancel and not retry the detached task. Both operator commands cancel a detached task and the associated submitter.
ACMS treats task failures generated as a result of ACMS/CANCEL TASK and ACMS/CANCEL USER operator commands as special cases and does not retry the task. For example, you can use the ACMS/CANCEL USER operator command to stop a task accessing a queue file, so the queue file can be backed up. Once the queue file is backed up, you can start the detached task again. This is particularly important for continuous operations.
In addition, a detached task is stopped whenever the application or the ACMS system is stopped with the /CANCEL qualifier.
Example 6-5 shows an audit message for a canceled detached task.
|Example 6-5 Audit Messages for a Detached Task Canceled by a System Operator|
Type : TASK Time : 18-APR-1994 18:02:21.09 Appl : DIST_APPL Task : DEQUEUE_TASK User : SMITH ID : MYNODE::00020013-00000001-B985D5E0-009576B2 Sub : MYNODE::00020013-00000001-B985D5E0-009576B2 Text : Detached task end Task completion status: Task canceled by system operator ************************************************************ Type : OTHER Time : 18-APR-1994 18:02:22.16 Text : Detached task terminated in application DIST_APPL Detached task DEQUEUE_TASK canceled by system operator
To force a detached task to not retry, a task can return the value ACMS$_DETTASK_NORETRY as the completion status. The ACMS$_DETTASK_NORETRY status directs the detached task to not retry even if the retry limit has not been exceeded. Use the following task definition syntax to return the completion status ACMS$_DETTASK_NORETRY:
CANCEL TASK RETURNING ACMS$_DETTASK_NORETRY;
Table 6-1 lists some of the failures that cause ACMS not to retry a detached task.
|ACMS$_DETTASK_NORETRY||Task explicitly specified as NO RETRY.|
|ACMS$_SECURITY_CHECK_FAILED||Submitter not authorized.|
|ACMS$_APPL_NOT_STARTED||Application is stopping.|
|ACMS$_OPR_CANCELED||Operator canceled task.|
|ACMS$_SUB_CANCELED||Operator canceled submitter.|
|ACMS$_INTERNAL||Internal ACMS error.|
|ACMS$_TASKNOTCOMP||Child task is not composable.|
|ACMS$_NEED_IOID||Child task is defined with I/O.|
|ACMS$_NEED_DEVORRR||Child task requires device name or RR server.|
|ACMS$_NEED_DEVICE||Child task requires device name.|
Example 6-6 shows an audit message for a task failure that is not retried.
|Example 6-6 Audit Message for a Task Failure that Is Not Retried|
Type: : ERROR Time : 03-MAY-1994 17:53:55.23 Text: Error in application DIST_APPL Detached task DEQUEUE_TASK terminated due to a task failure that cannot be retried. Task is not composable
ACMS operator terminals can receive notification when a detached task terminates under the following conditions:
ACMS operator terminals receive notification when a detached task is waiting to retry, and also the reason why the task is retrying.
To enable an ACMS operator terminal to receive these broadcasts, use one of the following commands:
$ ACMS/SET SYSTEM/PROCESS/OPERATOR
The ACMS/SET SYSTEM/PROCESS/OPERATOR command enables your terminal as an ACMS operator terminal for the duration of your process or until ACMS stops.
$ ACMS/SET SYSTEM/TERMINAL=TTE2/OPERATOR
The ACMS/SET SYSTEM/TERMINAL/OPERATOR command enables terminal TTE2 as an ACMS operator terminal for as long as ACMS is active.
Example 6-7 shows a detached task broadcast message for a detached task that exceeded the retry limit.
|Example 6-7 Broadcast Message for a Detached Task that Exceeded the Retry Limit|
%ACMS, 19-APR-1994 12:07:51.00, Detached task DEQUEUE_TASK terminated due to retry limit being exceeded
To effectively use group workspaces, a detached task that executes for long periods of time must call a task that executes for a short period of time (short-lived) to update the contents of a group workspace. The detached task must also call a short-lived task to read the contents of a group workspace when the contents are needed.