The Queued Task Initiator (QTI) is an ACMS run-time component which processes ACMS task queues by dequeuing queued task elements and initiating the associated task. The QTI user name must be authorized as an agent using the UDU. Before you can start ACMS task queues, you must start the QTI. Start the QTI either when you bring up the ACMS system or after ACMS is started. See Compaq ACMS for OpenVMS Concepts and Design Guidelines for detailed information about the QTI and the ACMS queuing facility.

8.6.1 Starting the QTI

To start the QTI after the ACMS system is started, use the ACMS/START QTI command. For example:

$ ACMS/START QTI

Once the ACMS QTI is started, you can then start task queues by specifying the ACMS/START QUEUE command. See Section 8.7.1 for information about starting task queues.

8.6.2 Stopping the QTI

To stop the QTI, specify the ACMS/STOP QTI command. The ACMS/STOP QTI command also stops all task queues. For example:

$ ACMS/STOP QTI

Unless you specify the /CANCEL qualifier with the ACMS/STOP QTI command, ACMS waits for all active tasks to complete before stopping the QTI. There is no timeout period. The following command stops the QTI, all task queues, and any active tasks:

$ ACMS/STOP QTI/CANCEL

8.6.3 Displaying QTI Information

Get information about the QTI by specifying the ACMS/SHOW QTI command. The ACMS/SHOW QTI command displays the run-time characteristics of the QTI. Example 8-3 shows the output from an ACMS/SHOW QTI command.

Example 8-3 ACMS/SHOW QTI Command

$ ACMS/SHOW QTI ACMS V4.0 ACMS QTI - QUEUED TASK INITIATOR Time: 1-MAY-1994 16:16:05.52 (1) State: STARTED (2) User Name: ROLEX (3) PID: 11000211 (4) Process Name: ACMS01QTI00400 (5) Queues: 2 (6) Submitter count: 6

The following is a description of the numbered items in Example 8-3:

1. State
   Whether the QTI is started or stopped.
2. User Name
   The OpenVMS user name for the QTI. This is defined by the ACMSGEN parameter QTI_USERNAME.
3. PID
   Process ID of the QTI process.
4. Process Name
   Process name of the QTI process.
5. Queues
   Number of currently active task queues.
6. Submitter count
   Number of submitters currently signed in by the QTI.

Once you create task queues with ACMSQUEMGR and start the QTI, you can start and stop ACMS task queues. See Chapter 5 for information about how to create task queues.

8.7.1 Starting Task Queues

Once you start the QTI, you can start task queues with the ACMS/START QUEUE command. The following command starts the queue MY_QUE:

$ ACMS/START QUEUE MY_QUE

Once you start a task queue, the QTI begins dequeuing and initiating tasks in the queue.

You must specify at least one queue name with the ACMS/START QUEUE command. You can start more than one queue by separating the queue names with commas.

You can specify the /ERROR_QUEUE and /TASK_THREADS qualifiers with the ACMS/START QUEUE command. The /ERROR_QUEUE qualifier allows you to specify the name of an error queue for a task queue. Tasks that do not complete successfully are placed in the error queue (unless they are to be retried), and ACMS records any errors in the Audit Trail Log. The /TASK_THREADS qualifier allows you to determine the maximum number of concurrent outstanding task elements that the QTI processes for the specified queue.

The error queue you specify with the /ERROR_QUEUE qualifier must exist. You can create an error queue with the ACMS Queue Manager (ACMSQUEMGR) Utility. See Chapter 5 for information about how to create an error queue.

The following command starts the task queues MY_QUE and NEW_QUE and specifies that if a task does not complete sucessfully in either queue, the task should be placed in the error queue ERR_QUE (unless it is to be retried). Any errors are recorded in the Audit Trail Log.

$ ACMS/START QUEUE/ERROR_QUEUE=ERR_QUE MY_QUE,NEW_QUE

You can specify a value from 1 through 256 with the /TASK_THREADS qualifier. The default is /TASK_THREADS=1. The following command starts the queue YOUR_QUE and specifies that the maximum number of concurrent tasks that can execute on YOUR_QUE is 12:

$ ACMS/START QUEUE YOUR_QUE/TASK_THREADS=12

8.7.2 Stopping Task Queues

You can stop a task queue with the ACMS/STOP QUEUE command. The queue you specify must exist and be currently started. You must specify at least one queue name. The following command stops the queue MOD_QUE:

$ ACMS/STOP QUEUE MOD_QUE

You can stop more than one queue by separating the queue names with commas.

Unless you specify the /CANCEL qualifier, the ACMS/STOP QUEUE command does not complete until all outstanding tasks in the queues have stopped. The following command stops all outstanding tasks in queue MY_QUE and stops queue MY_QUE:

$ ACMS/STOP QUEUE/CANCEL MY_QUE

Queued task elements that have been canceled remain in the queue repository file.

8.7.3 Displaying Task Queue Information

You can display information about ACMS task queues by specifying the ACMS/SHOW QUEUE command. The ACMS/SHOW QUEUE command displays information about queues currently being processed by the QTI. Because no queue name is specified, the ACMS/SHOW QUEUE command in Example 8-4 displays queue information for all active queues.

Example 8-4 ACMS/SHOW QUEUE Command

$ ACMS/SHOW QUEUE ACMS V4.0 QUEUED TASK QUEUES Time: 1-MAY-1994 16:16:05.52 (1) Task Queue: MECCAQUEUE (2) Threads: 4 (3) Successful tasks invocations:783 (4) Active Tasks: 2 (5) Failed tasks invocations: 4 (6) Error Queue: MECCAERROR_QUEUE Task Queue: MY_QUE Threads: 6 Successful tasks invocations: 620 Active Tasks: 4 Failed tasks invocations: 2 Error Queue: MYERROR_QUEUE

The following is a description of the numbered items in Example 8-4:

1. Task Queue
   Name of the queue.
2. Threads
   Maximum number of concurrent tasks that can be processed by the queue.
3. Successful task invocations
   Number of tasks that completed successfully.
4. Active tasks
   Number of currently active tasks.
5. Failed task invocations
   Number of tasks that failed.
6. Error Queue
   Name of the error queue associated with the task queue.

ACMS lets you cancel users manually with the ACMS/CANCEL USER command or automatically by using the SYS$MANAGER:ACMSCANCEL.COM command procedure. The ACMS/CANCEL USER command allows you to sign out an active ACMS user. The command procedure can be used only to sign out inactive users.

8.8.1 Canceling Users with the ACMS/CANCEL USER Command

Use the ACMS/CANCEL USER command to cancel users before bringing down the ACMS system. When you use the ACMS/CANCEL USER command, you not only sign out the users you specify, you also cancel any tasks they have selected from a menu, plus any tasks that have been called by those tasks.

Use qualifiers to cancel users by user name, device name, or submitter ID. Use the ACMS/SHOW USER command to display user information.

If you do not use qualifiers or specify user names, the ACMS/CANCEL USER command cancels all active users and prompts you to confirm each cancellation.

When you name a user with the ACMS/CANCEL command, you cancel all users with the name you specify. In this example, only one user has the user name ADAMS:

$ ACMS/CANCEL USER ADAMS User Name: ADAMS Submitter ID: MONEY::00010030 Agent PID: 204002D Device: RTA6: Submitter ID: MONEY::00010030 (Y/[N]):Y

By default, the ACMS/CANCEL USER command asks that you confirm the cancellation by typing Y, for yes. ACMS cancels users without prompting you if you use the /NOCONFIRM qualifier, but it is safer to confirm each cancellation. In either case, you can include the /LOG qualifier with the ACMS/CANCEL USER command. The /LOG qualifier displays a message that confirms each successful cancellation.

On a distributed ACMS system, ACMS/CANCEL USER cannot cancel remote users (submitters).

8.8.2 Canceling Users with ACMSCANCEL.COM

You can use the command procedure ACMSCANCEL.COM to cancel inactive ACMS users. ACMSCANCEL.COM is located in the directory SYS$MANAGER. By default, ACMS writes cancellation information to the file ACMS$CANCEL.LOG in the SYS$MANAGER directory.

If you do not want cancellation information written to the SYS$MANAGER directory, define the logical ACMS$CANCEL_DIR to point to a directory where you want user cancellation information placed. For example:

$ DEFINE/SYSTEM ACMS$CANCEL_DIR $DISK1:[MYDIR]

If you do not define ACMS$CANCEL_DIR, you must have write access to the SYS$MANAGER directory before using ACMSCANCEL.COM.

After you define ACMS$CANCEL_DIR, or if you have write access to SYS$MANAGER, run the command procedure by submitting it to a batch queue:

$ SUBMIT SYS$MANAGER:ACMSCANCEL.COM

By defining the logical name ACMS$CANCEL_USER_WAIT as a group or system logical, you can choose the length of time that ACMSCANCEL.COM waits before canceling inactive users. By default, ACMSCANCEL.COM cancels all users who have been inactive for one hour. The following command tells ACMSCANCEL.COM to wait 1 hour and 45 minutes before canceling any inactive users:

$ DEFINE/SYSTEM ACMS$CANCEL_USER_WAIT 01:45

8.8.3 Displaying User Information

The ACMS/SHOW USER command displays information about ACMS users. Include one or more user names as parameters. If you include more than one user name, separate the names with a comma. If you do not include a user name, ACMS displays information about all users signed in to ACMS.

Use the /DEVICE qualifier to display information about a user at a specific terminal. The following command displays information about the user JONES signed in at terminal TTHO:.

$ ACMS/SHOW USER JONES/DEVICE=TTH0:

By default, ACMS does not display task information when you use the ACMS/SHOW USER command. For information about the tasks that users are running, specify the /FULL qualifier with the ACMS/SHOW USER command. However, the ACMS/SHOW USER /FULL command only displays the task selected by a user from the ACMS menu. It does not display any tasks called by a task. To display all task instances in a sequence of task calls, use the ACMS/SHOW TASKS command. Example 8-5 contains sample output from the ACMS/SHOW USER/FULL command.

Example 8-5 ACMS/SHOW USER/FULL Command

$ ACMS/SHOW USER/FULL ACMS V4.0 CURRENT USERS Time: 1-MAY-1994 20:11:04.21 (1) User Name: JONES (2) Submitter ID: KARAT::00010027 (3) Agent PID: 22E000A4 (4) Device: VTA5: (5) Task Name: DELETE (6) Task ID: KARAT::00010029-0000000F (7) Appl Name: TEST1 (8) Appl Node: ALLDAY::

This command displays task information for each local submitter, including their remote task selections. This command does not display information about remote submitters. The following is a description of the numbered items in Example 8-5:

1. User Name
   OpenVMS user name for a user signed in to ACMS.
2. Submitter ID
   ACMS task submitter identification code assigned to the user at sign-in. Refer to Chapter 12 for information about submitter identification codes.
3. Agent PID
   OpenVMS process ID (PID) for a submitter's agent process. For those submitters signed in to the TSC, this is the process ID of the submitter's Command Process.
4. Device
   ACMS login device of the submitter.
5. Task Name
   Name of the task that the user is running. The task name is the name defined for the task in the task group definition.
6. Task ID
   ACMS task identification code for the task the user is running. Refer to Chapter 12 for information on task identification codes.
7. Appl Name
   Name of the application in which the task is running.
8. Appl Node
   Name of the node on which the application is running.

Example 8-5 shows that JONES is running a task named DELETE on node ALLDAY at terminal VTA5. If more than one user is signed in under the user name JONES, the command displays information about all users named JONES.

8.9 Summary of Operator Commands and Qualifiers

Table 8-1 lists the ACMS operator commands and their qualifiers and provides a brief description of each command. For detailed information about the operator commands and qualifiers, see Chapter 21.

Table 8-1 Summary of Operator Commands

Commands and Qualifiers	Description
ACMS/CANCEL TASK /APPLICATION=application-name /[NO]CONFIRM /DEVICE=device-name /IDENTIFIER=task-id /[NO]LOG /SUBMITTER=submitter-id /USER=user-name	Stops task instances.
ACMS/CANCEL USER /[NO]CONFIRM /DEVICE=device-name /[NO]LOG /SUBMITTER=submitter-id	Stops all tasks for the user and logs the user out of ACMS.
ACMS/DEBUG /AGENT_HANDLE /PID /SERVER /TWS_POOLSIZE[=n] /TWSC_POOLSIZE[=n] /WORKSPACE	Starts the ACMS Task Debugger.
ACMS/ENTER /[NO]RETURN	Signs users in to ACMS. This command does not require OPERATOR privilege.
ACMS/INSTALL /[NO]REMOVE	Installs an application database (.ADB) file in ACMS$DIRECTORY.
ACMS/MODIFY APPLICATION /APPLICATION_ATTRIBUTES /[NO]CONFIRM /[NO]LOG /SERVER_ATTRIBUTES /TASK_ATTRIBUTES	Modifies the attributes of an active application.
ACMS/REPLACE SERVER /APPLICATION=application-name /[NO]CONFIRM /[NO]LOG	Replaces a server image with a new version of that image.
ACMS/REPROCESS APPLICATION_SPEC /[NO]CONFIRM /[NO]LOG	Causes ACMS to retranslate the file specification of an application.
ACMS/RESET AUDIT	Creates a new version of the Audit Trail Log file when ACMS is active.
ACMS/RESET TERMINALS	Makes recently assigned sign-in characteristics in DDU definitions available to ACMS.
ACMS/SET QUEUE /TASK_THREADS=n	Sets the processing characteristics of a started queue.
ACMS/SET SYSTEM /[NO]AUDIT /[NO]OPERATOR /PROCESS /TERMINAL=device-name	Depending on the qualifiers used, enables or disables the Audit Trail Log or ACMS operators' terminals.
ACMS/SHOW APPLICATION /CONNECTIONS /DETACHED_TASKS /POOL /SERVER_ATTRIBUTES /TASK_ATTRIBUTES	Displays information about one or more active ACMS applications in static mode.
ACMS/SHOW APPLICATION/CONTINUOUS /[NO]BEGINNING_TIME=time /[NO]ENDING_TIME=time /[NO]INTERVAL[=seconds] /[NO]OUTPUT[=file-spec]	Displays information about one or more active ACMS applications in continuous refresh mode.
ACMS/SHOW QTI	Displays the run-time characteristics of the QTI.
ACMS/SHOW QUEUE	Displays active queue information.
ACMS/SHOW SERVER /APPLICATION=application-name	Displays information about one or more servers.
ACMS/SHOW SYSTEM /POOL /ALL	Displays information about the ACMS run-time system.
ACMS/SHOW TASK /APPLICATION=application-name /DEVICE=device-name /IDENTIFIER=task-id /SUBMITTER=submitter-id /USER=user-name	Displays information about one or more active ACMS tasks executing on the local node.
ACMS/SHOW USER /ALL /APPLICATION /DEVICE=device-name /[NO]FULL /LOCAL /REMOTE /SUBMITTER	Displays information about ACMS users on the node where you specify the ACMS/SHOW USER command.
ACMS/START APPLICATION	Starts one or more ACMS applications.
ACMS/START QTI	Starts the QTI.
ACMS/START QUEUE /ERROR_QUEUE=error-queue-name /TASK_THREADS=n	Starts a queue and any tasks in the queue.
ACMS/START SYSTEM /[NO]AUDIT /[NO]QTI /[NO]TERMINALS	Starts the ACMS system.
ACMS/START TASK /[NO]LOG /[NO]RETRY_LIMIT[=n] /SELECTION_STRING=selection_string /USERNAME=username /WAIT_TIMER=n	Starts a detached task in the specified application.
ACMS/START TERMINALS	Starts the TSC.
ACMS/STOP APPLICATION /[NO]CANCEL	Stops one or more ACMS applications.
ACMS/STOP QTI /[NO]CANCEL	Stops the QTI and all task queues.
ACMS/STOP QUEUE /[NO]CANCEL	Stops the specified queue.
ACMS/STOP SYSTEM /[NO]CANCEL	Stops ACMS applications, the TSC, and ACMS.
ACMS/STOP TERMINALS	Stops the TSC.