Compaq ACMS for OpenVMS
Writing Applications


Previous Contents Index

5.1.7 Form and Server Context in Task Calling

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:

  1. Prompts the user for a task selection
  2. Calls a task based on that selection

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 applications.

5.1.9.1 Task Auditing and Security

ACMS writes an audit record to the audit trail log whenever a task calls another task defined with the AUDIT attribute.

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.

5.1.9.2 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


Chapter 6
Using the Detached Task Feature

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 detached tasks.

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 started.

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:

6.2 Managing Detached Tasks

The following sections describe:

6.2.1 Starting a Detached Task

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.

Before starting a detached task, start the application within which the detached task executes. Use the following command to start a detached task:


$ 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 operator command.

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 

6.2.3 Setting the Retry Wait Timer

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.

6.2.4.1 Using the ACMS/SHOW TASK Command

The ACMS/SHOW TASK command displays whether an active task is a detached task. Use the following command to display the status of an active detached task:


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

6.2.4.2 Using the ACMS/SHOW APPLICATION/DETACHED_TASKS Command

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 

6.2.6 Forcing a Detached Task to Not Retry

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; 

6.2.6.1 Task Failures that Cause ACMS Not to Retry a Task

Table 6-1 lists some of the failures that cause ACMS not to retry a detached task.

Table 6-1 Task Failures
Name Description
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 

6.2.7 Broadcasting Detached Task Messages

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 

6.3 Using Group Workspaces in a Detached Task

Workspaces that are declared as group workspaces and are used by detached tasks that execute for long periods of time (for example, several days) have the following limitations:

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.


Previous Next Contents Index