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

- Tasks selected by a user from an ACMS menu
- Tasks selected by a user with the SELECT command
- Tasks invoked by a user agent

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 user's session
- Any task that the user selected from a menu
- Any tasks that the task called

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:

- Interactive work flow
- Detached processing

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:

- When you write a detached task, the task cannot perform any exchange I/O and you must define the task with the NO I/O phrase.
- Before starting a detached task, you must start the application within which the detached task executes. The name of the detached task must exist in the specified application database file.
- For every detached task started, the ACMS$SIGN_IN service signs in a task submitter. By default, ACMS uses the user name of the application (EXC) as the task submitter.
- A detached task can have a string passed to it through the ACMS$SELECTION_STRING system workspace. When a detached task is started, the selection string can optionally be specified.
- A detached task can be retried automatically after a task failure. When a detached task is started, both a retry limit and retry wait timer can be specified. The retry limit parameter specifies the number of times ACMS retries the detached task after a failure. The retry wait timer defines how long ACMS waits before retrying the detached task after a task failure.

# 6.2 Managing Detached Tasks

The following sections describe:

- Starting a detached task
- Setting the retry limit
- Setting the retry wait timer
- Showing the status for detached tasks
- Stopping a detached task
- Forcing a detached task not to retry
- Enabling broadcast of detached task notification messages

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

- The retry limit is exceeded.
- A task failure occurs that ACMS cannot retry.
- The detached task is canceled by an operator command.
- An unexpected internal failure occurs.

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:

- If the detached task accesses a group workspace for modify access, then the detached task prevents other tasks from updating the workspace until the detached task is completed.
- If the detached task accesses a group workspace for read access, then the detached task gets the contents of the workspace at the time the detached task starts, and uses the contents until the detached task is completed.

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