# Compaq ACMS for OpenVMS
Managing Applications

Previous | Contents | Index

# Chapter 5
Creating and Managing Queues

This chapter describes how to create and manage ACMS queues and how to manage queued task elements using the ACMSQUEMGR Utility. This chapter assumes a general knowledge of the ACMS Queued Task Facility. Please read the description of the ACMS Queued Task Facility in Compaq ACMS for OpenVMS Concepts and Design Guidelines before reading this chapter. See Section 5.6 for a summary of ACMSQUEMGR commands and qualifiers. For reference information on the commands described in this chapter, refer to Chapter 20.

# 5.1 How ACMSQUEMGR Works

Use ACMS Queue Manager (ACMSQUEMGR) Utility commands to create and manage task queues and to manage the elements in the task queues. In addition to using the ACMSQUEMGR, system managers and application managers who are responsible for the ACMS Queued Task facility may need to:

- Control the Queued Task Initiator (QTI) to process task queues. The QTI must be started before you can start task queues. See Chapter 8 for information on the operator commands you can use to control the QTI and start task queues.
- Set up an OpenVMS user name for the QTI process. See Chapter 11 for information about defining a user name for the QTI.
- Monitor the QTI process by reading the QTI audit reports generated by the Audit Trail Logger. See Chapter 12 for information about monitoring the QTI process.

Use the ACMSQUEMGR commands to perform operations directly on task queues or queued task elements while you use queuing operator commands to control the QTI's processing of task queues.

Note ACMS task queues are totally independent from OpenVMS task queues.

Use ACMSQUEMGR commands to create and delete task queues and display information about the task queues as well as to modify static and dynamic characteristics of task queues. When you create a task queue, ACMSQUEMGR creates a queue definition file to keep information about each of the queues on a system or cluster. The queue definition file contains the following information about a queue:

- Name of the task queue
- Whether or not tasks can be queued (the enqueue state)
- Whether or not queued task elements in the queue can be read and processed by the QTI (the dequeue state)
- Maximum workspace size for a task executing in the task queue
- File specification of the task queue repository file

You can also use ACMSQUEMGR commands to manage any queued task elements in the task queues. When you queue a task, the ACMS$QUEUE_TASK service creates a record of information for that task called a queued task element. Queued task elements for a queue are stored in a queue repository file. A queued task element contains the following information about a task:

- Task name
- Application name
- Workspace values
- Element priority
- Queue name
- Enqueuer user name
- Enqueue time
- Enqueue state
- Element ID
- Error count

The information in a queued task element is specified by using parameters to the ACMS$QUEUE_TASK service. See Compaq ACMS for OpenVMS Writing Applications for more information about the ACMS Queued Task Services.

An element ID is assigned to the queued task element when it is created with the ACMS$QUEUE_TASK service. Use the element ID with ACMSQUEMGR commands to set the processing characteristics of a queued task element, delete a queued task element, or display information about queued task elements.

# 5.2 How to Run ACMSQUEMGR

Use either of the following commands to start the ACMSQUEMGR Utility:

    $ RUN SYS$SYSTEM:ACMSQUEMGR
    ACMSQUEMGR>

or

    $ MCR ACMSQUEMGR
    ACMSQUEMGR>

When you see the ACMSQUEMGR prompt (ACMSQUEMGR>), you can begin entering ACMSQUEMGR commands, including the HELP command, to get online help information.

Instead of typing in individual ACMSQUEMGR commands, you can enter ACMSQUEMGR commands by pressing keypad keys. Press the `[PF1]` and `[PF2]` keypad keys for access to the ACMSQUEMGR command keypad. Press `[Ctrl/B]` to recall each of the last 20 ACMSQUEMGR commands you entered. To exit from the ACMSQUEMGR, press `[Ctrl/Z]` or use the EXIT command.

ACMSQUEMGR also supports DCL foreign commands. From DCL level, define the DCL symbol ACMSQUEMGR as a foreign command in your LOGIN.COM file. For example:

    $ ACMSQUEMGR:==$SYS$SYSTEM:ACMSQUEMGR

Once you define ACMSQUEMGR as a DCL foreign command, you can issue ACMSQUEMGR commands from DCL level. For example:

    $ ACMSQUEMGR SHOW ELEMENT * PAYROLL_QUEUE
    $ ACMSQUEMGR DELETE ELEMENT PAYRLL::2F600041 PAYROLL_QUEUE
    $ ACMSQUEMGR SET QUEUE PAYROLL_QUEUE /ENQUEUES=SUSPENDED

See OpenVMS DCL Dictionary for more information on foreign commands.

To run the ACMSQUEMGR, you need:

- Read/write access to the ACMS queue definition file (ACMSQDF.DAT)
- Access to the queue file or files with which you are going to work

When you run ACMSQUEMGR for the first time, it searches for an existing queue definition file and, if it does not find one, asks you if you want to create a new file. For example:

    %ACMQUEMGR-I-ERROPNFIL, Unable to open the ACMS Queue Definition File
                          SYS$SYSROOT:[SYSEXE]ACMSQDF.DAT
    -RMS-F-FNF, file not found
    Do you want to create a new file?

If you answer YES to this question, the ACMSQUEMGR creates a new queue definition file. Otherwise, the ACMSQUEMGR exits.

By default, the queue definition file is named SYS$SYSTEM:ACMSQDF.DAT, but you can define the logical name ACMSQDF to point to a different file specification or location:

    $ DEFINE /SYSTEM /EXEC ACMSQDF $DISK1:[MYDIR]ACMSQDF.DAT

When you are using the ACMSQUEMGR Utility, you can use any access mode for the ACMSQDF logical. However, at run time, ACMS Queued Task Services require that ACMSQDF be an executive-mode logical name. If you expect a queue definition file to exist when you run ACMSQUEMGR, check that the logical name ACMSQDF is pointing to the correct file specification.

# 5.3 Managing Task Queues

Use the following ACMSQUEMGR commands to create and manage ACMS task queues:

- CREATE QUEUE
- SET QUEUE
- MODIFY QUEUE
- DELETE QUEUE
- SHOW QUEUE

These commands are described in the following sections.

## 5.3.1 Creating Task Queues

You use the CREATE QUEUE command to create a task queue. Once you have created a queue, it can be reached through the ACMS$QUEUE_TASK service to enqueue elements to the queue, and also by the QTI to process the elements in the queue. The following command creates a queue called PERS_QUEUE. Because this command does not include a full file specification for the queue, the ACMSQUEMGR Utility creates the queue SYS$SYSTEM:PERS_QUEUE.DAT.

    ACMSQUEMGR> CREATE QUEUE PERS_QUEUE

When you use the CREATE QUEUE command to create a queue, the ACMSQUEMGR Utility sets the owner of the queue file to [1,4] and sets the protection of the file to S:RWED,O:RWED,G,W. Therefore, to access the queue file, a user must have a system UIC or must have the SYSPRV privilege.

## 5.3.2 Setting the Characteristics of Task Queues

You can dynamically control the availability of task queues by using the SET QUEUE command. For example, the SET QUEUE command can be used to prevent queued task elements from being queued to a task queue. Likewise, the SET QUEUE command can prevent queued task elements from being dequeued from a task queue.

When you use the SET QUEUE command, you must use either the /DEQUEUE or /ENQUEUE qualifier.

The /ENQUEUE qualifier allows or disallows queued task elements to be queued. The following example disables the queuing of queued task elements to queue HISTORY_QUE:

    ACMSQUEMGR> SET QUEUE /ENQUEUE=SUSPENDED HISTORY_QUE

When the enqueue state of a task queue is set to SUSPENDED, the ACMS$QUEUE_TASK service returns an error when elements are queued to the task queue. Use /ENQUEUE=RESUMED to enable queuing of elements.

Allow or disallow the QTI to dequeue all queued task elements in a queue by using the /DEQUEUE qualifier. Dequeuing is the process whereby the QTI reads and then deletes a queued task element to make a task available for processing. The /DEQUEUE qualifier in the following command specifies that no queued task elements can be dequeued from MY_QUE. No queued task elements are processed until you set the dequeue state to RESUMED.

    ACMSQUEMGR> SET QUEUE /DEQUEUE=SUSPENDED MY_QUE

By using the /DEQUEUE=SUSPENDED qualifier, you can allow tasks to be queued to a queue, but suspend their processing. When dequeues are suspended, the ACMS$DEQUEUE_TASK service returns an error. When you want tasks to be processed by the QTI, specify the /DEQUEUE=RESUMED qualifier.

## 5.3.3 Modifying Task Queues

You can modify the static characteristics of a task queue by using the MODIFY QUEUE command. This can include changing the disk where a queue repository file is located, or increasing the maximum workspace size for a task queue to allow for the size requirements of a new task in your application. In any case, you do not need to modify the characteristics of a task queue on a frequent basis.

The MODIFY QUEUE command requires exclusive access to the task queue. Make sure that no processes have access to the queue by setting the enqueue and dequeue state of the task queue to suspended. To do this, use the SET QUEUE command and then stop the queue with the ACMS/STOP QUEUE command.

The following command modifies the maximum workspace size allowed for a queued task element in task queue PAY_QUE:

    ACMSQUEMGR> MODIFY QUEUE PAY_QUE/MAX_WORK=450

Use the /FILE_SPECIFICATION qualifier with the MODIFY QUEUE command to specify the name of a new queue repository file. The queue repository file contains the queued task elements for a queue and is created when you create the queue with the CREATE QUEUE command. The following command changes the location of the queue repository file for queue MY_QUE:

    ACMSQUEMGR> MODIFY QUEUE MY_QUE/FILE_SPEC=DISK2:MY_QUE.DAT

## 5.3.4 Deleting Task Queues

Use the ACMSQUEMGR DELETE QUEUE command to delete a task queue. To delete a task queue, you need to delete access to the queue repository file, and the task queue must be stopped. The following command deletes task queue PAY_QUE:

    ACMSQUEMGR> DELETE QUEUE PAY_QUE

The /PURGE qualifier deletes all queued task elements in the queue when you delete the queue. For example:

    ACMSQUEMGR> DELETE QUEUE/PURGE PAY_QUE

If you do not specify the /PURGE qualifier and there are queued task elements in the task queue, ACMSQUEMGR is unable to delete the task queue and displays an error message.

## 5.3.5 Displaying Task Queue Information

The SHOW QUEUE command displays information about task queues currently defined in the queue definition file. The SHOW QUEUE command in Example 5-1 displays information about the queue PAYROLL_QUE. You can display information about all queues by using the wildcard character (*).

Example 5-1 ACMSQUEMGR SHOW QUEUE Command

    ACMSQUEMGR> SHOW QUEUE PAYROLL_QUE

    (1) Queue Name: PAYROLL_QUE
    (2)
     Enqueues State:  RESUMED  (3)
     Dequeues State:  RESUMED   (4)
     Max Wsp Size:  256
    (5) File Specification:  SYS$SYSTEM:PAYROLL_QUE.DAT

The following is a description of the numbered items in Example 5-1:

1. Queue Name
   The name of the task queue.
2. Enqueues State
   Whether or not new tasks can be queued. If the enqueues state is enabled, new tasks can be queued. If it is disabled, they cannot be queued.
3. Dequeues State
   If the dequeues state is enabled, queued tasks can be removed from the queue. If it is disabled, they cannot be removed.
4. Max Wsp Size
   The maximum total size (in bytes) of workspaces allowed in a queued task element.
5. File Specification
   The file specification of the queue repository file. The queue repository file stores the queued task elements. By default, the queue repository file has the file specification SYS$SYSTEM:queue-name.DAT; however, you can specify another file specification by using the /FILE_SPECIFICATION qualifier with the CREATE QUEUE command.

See Chapter 20 for more information about the SHOW QUEUE command.

# 5.4 Managing Queued Task Elements

Use ACMSQUEMGR commands to:

- Alter the processing priority or state of a queued task element
- Delete a queued task element
- Display information about a queued task element

The commands you can use to perform these operations are described in the following sections.

Associated with each queued task element is an element ID. The element ID is returned by the ACMS$QUEUE_TASK programming service. ACMSQUEMGR commands that perform operations on queued task elements require that you specify the element ID of the queued task element. This implies that your application program, which called the ACMS$QUEUE_TASK programming service, made available to you the element ID. Another way to obtain an element ID is to display all queued task elements (or a subset thereof) using the ACMSQUEMGR command SHOW ELEMENT (see Section 5.4.3). Then, once you locate the element you are interested in, note its element ID.

If you specify a partial element ID, the omitted fields are wildcarded. For example, an element ID of ABCD:: matches all element IDs beginning with ABCD::; that is, all elements enqueued from node ABCD. See Chapter 20 for more information about specifying an element ID.

Although you can perform operations on specific queued task elements by specifying element IDs, you can use the wildcard character (*) instead of an element ID, and then use the /SELECT, /EXCLUDE, and /CONFIRM qualifiers to limit the scope of the command to the specified elements. This approach is best if you do not know the element ID or you want to perform operations on several elements at once.

For example, the following command deletes all queued task elements in queue INVENTORY_QUE for tasks UPDATE_PART1 and UPDATE_PART2 that were queued today but are not priority 1 or 2:

    ACMSQUEMGR> DELETE ELEMENT * INVENTORY_QUE -
    _ACMSQUEMGR> /SELECT=(TASK=(UPDATE_PART1,UPDATE_PART2), -
    _ACMSQUEMGR> SINCE=TODAY) -
    _ACMSQUEMGR> /EXCLUDE=PRIORITY=(1,2)

## 5.4.1 Setting the Characteristics of Queued Task Elements

Set the state or priority of a queued task element with the ACMSQUEMGR SET ELEMENT command. Setting the attributes of a queued task element allows you to control how it is dequeued.

Setting the priority of an element allows you to control when the element is dequeued relative to other elements in the queue. You can specify a priority of 0 through 255. The QTI and the ACMS$DEQUEUE_TASK service dequeue highest priority elements first, and, within priority, dequeue elements on a first-in/first-out (FIFO) basis. For example, if all queued task elements in a queue are set at priority 10, then normally they would be processed in FIFO order. To cause a particular queued task element to be processed first, you issue the following command:

    ACMSQUEMGR> ELEMENT NODE1:22D00082-0000000E PARTS_QUE /PRIORITY=11

To control whether or not the QTI and the ACMS$DEQUEUE_TASK service dequeue a queued task element, use the /STATE qualifier with the SET ELEMENT command. For instance, if you set the state of a queued task element to HOLD, then the element is not dequeued from the queue. For example:

    ACMSQUEMGR> SET ELEMENT NODE1:22D00082-0000000E PARTS_QUE -
    _ACMSQUEMGR> /STATE=HOLD

Setting an element to HOLD is useful when you want to start a queue, but do not want certain elements to be processed by the QTI. To allow a queued task element to be dequeued, specify /STATE=NOHOLD.

You can specify a wildcard character (*) instead of an element ID, and use the /SELECT or /EXCLUDE qualifiers to limit the scope of the command.

For example, if you want the QTI to process queued task elements for the task UPDATE_INVENTORY only between the hours of 6:00 and 10:00 at night, then set the state of the queued task elements to HOLD and submit a batch job to run at 6:00 that issues the following command:

    ACMSQUEMGR> SET ELEMENT * INVENTORY_QUE /STATE=NOHOLD -
    _ACMSQUEMGR> /SELECT=TASK=UPDATE_INVENTORY

Assuming that INVENTORY_QUE is started, then these elements are now available for dequeuing and processing by the QTI. If you want processing to stop at 10:00 P.M. that evening, run a batch job at that time containing the following command:

    ACMSQUEMGR> SET ELEMENT * INVENTORY_QUE /STATE=HOLD  -
    _ACMSQUEMGR> /SELECT=TASK=UPDATE_INVENTORY

## 5.4.2 Deleting Queued Task Elements

Use the DELETE ELEMENT command to delete one or more queued task elements in a task queue. Identify a particular element to delete by specifying part or all of an element ID, or use the wildcard character (*) to delete all queued task elements in a queue. This command deletes all queued task elements submitted from node AVERTZ in queue MY_QUE:

    ACMSQUEMGR> DELETE ELEMENT AVERTZ:: MY_QUE

Use the /SELECT or /EXCLUDE qualifiers to select a category of queued task elements to delete, or exclude a category from being deleted. The following command deletes all queued task elements submitted before today on queue PAY_QUE:

    ACMSQUEMGR> DELETE ELEMENT * PAY_QUE /SELECT=BEFORE=TODAY

## 5.4.3 Displaying Queued Task Elements

The SHOW ELEMENT command displays one or more queued task elements in a queue. Unless you specify the /FULL qualifier, brief information is provided by default. The brief display contains the following information:

- Task name
- Element state
- Application name
- Element priority

When you use the /FULL qualifier, the following additional information is displayed. See Example 5-2 for an example of a full display.

- Enqueuer user name
- Time the task element was created
- Queue name
- Element ID
- Error count (if any) for the queue element
- Task error (if any)

Example 5-2 ACMSQUEMGR SHOW ELEMENT/FULL

    ACMSQUEMGR> SHOW ELEMENT * INVENTORY_QUE/FULL

            ACMS Queued Tasks                     Current Date/Time: 2-FEB-1994 13:21:31.13

    (1)    Task:  PARTS_AVAIL            (2)  State:     NOHOLD
    (3)    Appl:  SITE_INVENT            (4)  Priority:  20
    (5)    Username:   NORTH             (6)  Enq Time:  2-FEB-1994 10:13:17.71
    (7)    Queue Name: PAYROLL_QUEUE
    (8)    Element Id: MYNODE::28C00082-0000000F-FDE272E0-0090AB3F
    (9)    Error Cnt:  1
    (10)   Last Error:  %ACMS-E-NOSUCH_PKG, There is no such package defined
    (11)   Error Time:  2-FEB-1994 11:38:39.24

        Task:  PARTS_REQ                       State:     NOHOLD
        Appl:  SITE_INVENT                       Priority:  20
        Username:   JONES                        Enq Time:  15-JAN-1994 10:13:16.85
        Queue Name: PAYROLL_QUEUE
        Element Id: MYNODE::28C00082-0000000E-FD5F3920-0090AB3F
        Error Cnt:  0
        Queued Task total for this display: 2

The following is a description of the numbered items in Example 5-2:

Previous | Next | Contents | Index