| Previous | Contents | Index |
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:
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.
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:
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:
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:
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:
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 |
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:
See Chapter 20 for more information about the SHOW QUEUE command.
5.4 Managing Queued Task Elements
Use ACMSQUEMGR commands to:
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) |
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 |
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 |
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:
When you use the /FULL qualifier, the following additional information is displayed. See Example 5-2 for an example of a full display.
| 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 |