HP OpenVMS Systems Documentation

This chapter contains reference information and examples for the ACMS Queue Manager (ACMSQUEMGR) Utility commands. ACMSQUEMGR commands allow you to create and manage ACMS task queues and the queued task elements in the queues. See Chapter 5 for general information about the ACMSQUEMGR Utility.

Creates a queue for queued task elements.

Format

CREATE QUEUE queue-name

Command Qualifiers	Defaults
/DEQUEUE=keyword	/DEQUEUE=RESUMED
/ENQUEUE=keyword	/ENQUEUE=RESUMED
/FILE_SPECIFICATION=file-spec	SYS$SYSTEM:queue-name.DAT
/MAX_WORKSPACES_SIZE=n	/MAX_WORKSPACES_SIZE=256

Privileges Required

OpenVMS SYSPRV privilege or write access to SYS$SYSTEM

Parameters

queue-name

The name of the queue you want to create. A queue name can be any valid RMS file name containing 1 through 39 alphanumeric characters.

Qualifiers

/DEQUEUE=keyword

Allows or disallows the dequeuing of all queued task elements in the created queue. Specify one of the following keywords with the /DEQUEUE qualifier:

• SUSPENDED
  The /DEQUEUE=SUSPENDED qualifier prohibits the Queued Task Initiator (QTI) and ACMS$DEQUEUE_TASK service from processing queued task elements in the queue. This qualifier allows tasks to be queued to the created queue, but suspends them from being dequeued until you specify the /DEQUEUE=RESUMED qualifier. The default is /DEQUEUE=RESUMED.
• RESUMED
  The /DEQUEUE=RESUMED qualifier allows the QTI and ACMS$DEQUEUE_TASK service to dequeue queued task elements in the queue. Use this qualifier after you specify /DEQUEUE=SUSPENDED to resume dequeuing. The default is /DEQUEUE=RESUMED.

/ENQUEUE=keyword

Enables or disables the queuing of queued task elements to the queue you create. You can specify one of the following keywords with the /ENQUEUE qualifier:

• SUSPENDED
  The /ENQUEUE=SUSPENDED qualifier prohibits the ACMS$QUEUE_TASK service from queuing queued task elements to the queue you create until the queue state is resumed. The default is /ENQUEUE=RESUMED.
• RESUMED
  The /ENQUEUE=RESUMED qualifier allows ACMS$QUEUE_TASK service to queue queued task elements to the queue you create. The default is /ENQUEUE=RESUMED.

/FILE_SPECIFICATION=file-spec

Specifies the file specification of the queue repository that stores the queued task elements. The file specification can be any valid RMS file specification or logical name. If you do not specify the /FILE_SPECIFICATION qualifier, the queue repository is SYS$SYSTEM: queue-name.DAT, where queue-name is the name of the created queue. If you do not specify a full file specification, the missing components are taken from the default file specification.

/MAX_WORKSPACES_SIZE=n

Specifies the maximum total size (in bytes) of workspaces allowed in a single queued task element for the queue you create. If you do not use the /MAX_WORKSPACES_SIZE qualifier, the default is /MAX_WORKSPACES_SIZE=256. You can specify a value of 0 through 31,720. If a queued task element's workspace size on a call to the ACMS$QUEUE_TASK service exceeds the value specified with the /MAX_WORKSPACES_SIZE qualifier, you receive an error when you queue the task.

Specify the largest workspace size needed for a single queued task element that is queued to the queue. Use the following formula to determine the workspace size for a single queued task element:

2 * (n+1) + size (in bytes) of workspace 1 + size (in bytes) of workspace 2 . . . + size (in bytes) of workspace n (where n is the total number of workspaces)

The number of workspaces and size of the workspaces that can be passed to a task are displayed when you use the Application Definition Utility (ADU) command DUMP GROUP.

For the most efficient performance of the queue services and the QTI, specify the smallest possible value with the /MAX_WORKSPACES_SIZE qualifier.

Notes

You must create a queue before the queue can be accessed by the ACMS queued task services or by the QTI run-time component.

The queue repository file is created with the owner UIC [1,4] and the protection (S:RWED,O:RWED,G,W).

ACMS stores queue information in the file SYS$SYSTEM:ACMSQDF.DAT.

Examples

ACMSQUEMGR> CREATE QUEUE BIG_NUMBERS_QUE
      

This command creates the queue BIG_NUMBERS_QUEUE. The defaults are used for all qualifiers.

ACMSQUEMGR> CREATE QUEUE EMPLOYEE_QUEUE /MAX_WORKSPACES_SIZE=500
      

This command creates queue EMPLOYEE_QUEUE, setting the maximum workspace size allowed for queued task elements at 500.

ACMSQUEMGR> CREATE QUEUE INVENTORY_QUE -
_ACMSQUEMGR> /FILE_SPECIFICATION=MYDISK$:QUEUE.DAT -
_ACMSQUEMGR> /ENQUEUE=SUSPENDED
      

This command creates the queue INVENTORY_QUE. It names the queue repository file MYDISK$:QUEUE.DAT, and disallows queuing of queued task elements by the ACMS$QUEUE_TASK service.

Removes one or more queued task elements from the specified queue.

Format

DELETE ELEMENT element-id queue-name

Command Qualifiers	Defaults
/[NO]CONFIRM	/NOCONFIRM
/EXCLUDE=(keyword[,...])	None
/SELECT=(keyword[,...])	None

Privileges Required

Write access to the queue repository file. If the queue repository file has the default protection from the CREATE QUEUE command, you need the OpenVMS SYSPRV privilege or the UIC [1,4] to delete the queued task element.

Parameters

element-id

The element identification of the queued task element you want to remove. Either specify the element ID of the task element or use the wildcard character (*). The element ID is returned by the ACMS$QUEUE_TASK service. Specify all or part of the element ID. If you specify only part of an element ID, all queued task elements whose IDs contain the specified characters are removed. For example, if MY_NODE is specified as the element ID, all elements queued from MY_NODE are removed from the queue. Display the element ID of a queued task element by using the SHOW ELEMENT command with the /FULL qualifier. The SHOW ELEMENT command is described in SHOW ELEMENT Command (ACMSQUEMGR„).

If you use the wildcard character (*) in place of an element ID, all queued task elements are removed from the specified queue. When using the wildcard character, you can also use the /SELECT qualifier or /EXCLUDE qualifier to choose a group of queued task elements to remove.

queue-name

The name of the queue containing the queued task element. A queue name can be any valid RMS file name containing 1 through 39 alphanumeric characters.

Qualifiers

/[NO]CONFIRM

/CONFIRM displays each queued task element selected for removal and prompts you to confirm that you want the queued task element removed. Answer the prompt by entering one of the following:

• Y or y---For yes
• N or n---For no
• Q or q---For quit (exits the command without removing the queued task element).
• A or a---For always (removes all remaining queued task elements without displaying the confirmation prompt).
• RETURN---For the default

The default is /NOCONFIRM.

/EXCLUDE=(keyword[,...])

Allows you to exclude a queued task element or group of queued task elements from being removed. Specify exclusion criteria with keywords to the /EXCLUDE qualifier. You can specify more than one keyword by separating the keywords with a comma and enclosing them in parentheses. You must use at least one keyword with the /EXCLUDE qualifier. You can use the /EXCLUDE qualifier to limit the scope of the DELETE ELEMENT command when you use a wildcard character (*) instead of an element ID.

The /EXCLUDE qualifier takes precedence over the /SELECT qualifier. Therefore, if a queued task element matches the selection criteria but is excluded by the exclusion criteria, that queued task element is not removed from the queue.

Specify one or more of the following keywords:

• APPLICATION=(application-spec[,...])
  Excludes queued task elements containing the specified application. Specify more than one application specification by separating the specifications with a comma and enclosing them in parentheses.
• BEFORE=time
  Excludes queued task elements queued before the specified time. You can specify absolute time, combination time, or the keyword argument TODAY or YESTERDAY. See OpenVMS User's Manual for more information about absolute and combination time.
• PRIORITY=(n[,...])
  Excludes queued task elements having the specified priority. Valid priority values are 0 through 255. Specify more than one priority value by separating the values with a comma and enclosing them in parentheses.
• SINCE=time
  Excludes queued task elements queued since the specified time. You can specify absolute time, combination time, or the keyword argument TODAY or YESTERDAY. See OpenVMS User's Manual for more information about absolute and combination time.
• STATE=[NO]HOLD
  If you specify /EXCLUDE=STATE=HOLD, the ACMSQUEMGR excludes all queued task elements currently on hold. Queued task elements on hold cannot be removed from the queue. If you specify /EXCLUDE=STATE=NOHOLD, the ACMSQUEMGR excludes all queued task elements not on hold. Queued task elements that are not on hold can be dequeued.
• TASK=(task-name[,...])
  Excludes all queued task elements having the specified task name. Specify more than one task name by separating the task names with a comma and enclosing them in parentheses.

• USERNAME=(enqueuer-user-name[,...])
  Excludes all queued task elements that have the specified enqueuer user name. The enqueuer user name is the user name explicitly or implicitly specified with the ACMS$QUEUE_TASK service. See Compaq ACMS for OpenVMS Writing Applications for information about the ACMS$QUEUE_TASK service.

/SELECT=(keyword[,...])

Limits the DELETE ELEMENT command to queued task elements that match the selection criteria. Specify the selection criteria with keywords to the /SELECT qualifier. Specify more than one keyword by separating the keywords with a comma and enclosing them in parentheses. You must use at least one keyword with the /SELECT qualifier. You can use the /SELECT qualifier to limit the scope of the DELETE ELEMENT command when you use a wildcard character (*) instead of an element ID.

Specify one or more of the following keywords:

• APPLICATION=(application-spec[,...])
  Removes only queued task elements containing the specified application. You can specify more than one application specification by separating the specifications with a comma and enclosing them in parentheses.
• BEFORE=time
  Removes all queued task elements queued before the specified time. You can specify absolute time, combination time, or the keyword argument TODAY or YESTERDAY. See OpenVMS User's Manual for more information about absolute and combination time.
• PRIORITY=(n[,...])
  Removes all queued task elements having the specified priority. Valid priority values are 0 through 255. Specify more than one priority value by separating the values with a comma and enclosing them in parentheses.
• SINCE=time
  Removes all queued task elements queued since the specified time. You can specify absolute time, combination time, or the keyword argument TODAY or YESTERDAY. See OpenVMS User's Manual for more information about absolute and combination time.
• STATE=[NO]HOLD
  If you specify /SELECT=STATE=HOLD, the ACMSQUEMGR removes all queued task elements currently on hold. If you specify /SELECT=STATE=NOHOLD, the ACMSQUEMGR removes all queued task elements not on hold.
• TASK=(task-name[,...])
  Removes all queued task elements having the specified task name. Specify more than one task name by separating the task names with a comma and enclosing them in parentheses.

• USERNAME=(enqueuer-user-name[,...])
  Removes all queued task elements that have the specified enqueuer user name. The enqueuer user name is the user name explicitly or implicitly specified with the ACMS$QUEUE_TASK service. See Compaq ACMS for OpenVMS Writing Applications for information about the ACMS$QUEUE_TASK service.

Notes

None

Examples

ACMSQUEMGR> DELETE ELEMENT MY_NODE::28C0082-0000000A MY_QUE
      

This command deletes the queued task element identified by the element ID MY_NODE::28C0082-0000000A in queue MY_QUE.

ACMSQUEMGR>  DELETE ELEMENT * YOUR_QUE
      

This command deletes all queued task elements in queue YOUR_QUE.

ACMSQUEMGR> DELETE ELEMENT * RACE_QUEUE /CONFIRM
      

This command causes ACMSQUEMGR to prompt you for confirmation before deleting each queued task element in queue RACE_QUEUE.

ACMSQUEMGR> DELETE ELEMENT * RESERVE_QUE -
_ACMSQUEMGR> /EXCLUDE=TASK=(BIGTSK,BIGGERTSK)

      

This command deletes all queued task elements in queue RESERVE_QUE except for the queued task elements having the names BIGTSK and BIGGERTSK.

ACMSQUEMGR> DELETE ELEMENT MY_NODE:: BOOK_QUE /SELECT=STATE=HOLD
      

This command deletes all queued task elements queued from node MY_NODE to queue BOOK_QUE that are currently on hold.

ACMSQUEMGR> DELETE ELEMENT * BOSCO_QUEUE -
_ACMSQUEMGR> /SELECT=(APPLICATION=STATS,SINCE=TODAY)
      

This command deletes all queued task elements on queue BOSCO_QUEUE that were queued today and contain the application STATS.

Deletes the queue you specify.

Format

DELETE QUEUE queue-name

Command Qualifier	Default
/[NO]PURGE	/NOPURGE

Privileges Required

Delete access to the queue repository file. If the queue repository file has default protection from the CREATE QUEUE command, you need OpenVMS SYSPRV privilege or the UIC [1,4] to delete the queue.

Parameters

queue-name

The name of the queue you want to delete. A queue name can be any valid RMS file name containing 1 through 39 alphanumeric characters.

Qualifiers

/[NO]PURGE

If you use the /PURGE qualifier, all queued task elements currently in the queue are deleted along with the queue. If you use the /NOPURGE qualifier, and queued task elements are in the queue, ACMSQUEMGR cannot delete the queue. ACMS displays an error message indicating that the queue is not empty. The default is /NOPURGE.

Notes

The DELETE QUEUE command requires exclusive access to the queue repository file. If the queue is currently being processed by the QTI, the queue must be stopped with the ACMS/STOP QUEUE command. If the queue has been accessed by an image using the ACMS queue task services, the image must be exited.

Examples

ACMSQUEMGR> DELETE QUEUE GROUP_QUE

      

This command deletes queue GROUP_QUE.

ACMSQUEMGR> DELETE QUEUE BOSS_QUE /PURGE
      

This command deletes queue BOSS_QUE and removes any queued task elements in the queue.

Ends the ACMSQUEMGR session and returns you to DCL level.

Format

EXIT

Privileges Required

None

Notes

You can also end a session by pressing [Ctrl/Z]. [Ctrl/Z] signals the end of the file for data entered from the terminal. [Ctrl/Z] is displayed as EXIT.

Example

ACMSQUEMGR> EXIT
$
      

This command causes you to exit from ACMSQUEMGR and returns you to DCL level.

Displays information about ACMSQUEMGR commands and qualifiers.

Format

HELP [ topic [...]]

Command Qualifier	Default
/[NO]PROMPT	/PROMPT

Privileges Required

None

Parameters

topic

The ACMSQUEMGR command or topic you want to know about. If you do not specify a topic, HELP provides a list of topics to choose from. Use the wildcard character (*) as a prefix or suffix to display information on a sequence of topics with common characters.

Qualifiers

/[NO]PROMPT

Controls whether or not you receive prompts for the topic and subtopic. If you use the /NOPROMPT qualifier, no prompts are displayed. If you use the /PROMPT qualifier, prompts are displayed along with the help information. The default is /PROMPT.

Notes

None

Example

ACMSQUEMGR> HELP SET ELEMENT
SET
  ELEMENT
    Sets the state or priority of one or more queued task elements.
    You must specify at least one qualifier or this command has
    no effect.
      Format:
         SET ELEMENT element-id queue-name /qualifier
      You can specify all or part of an element ID. Use the
      wildcard character (*) to set characteristics of all the
      queued task elements in a queue.  Use SHOW ELEMENT to display
      element IDs.
      For example:
         ACMSQUEMGR> SET ELEMENT * EILEEN_QUE /PRIORITY=200 -
         _ACMSQUEMGR> /SELECT=(TASK=URGENT)
    Additional information available:
    /CONFIRM   /EXCLUDE   /PRIORITY  /SELECT    /STATE
SET ELEMENT Subtopic?

      

This command displays help information about the SET ELEMENT command.

With a qualifier, modifies the static characteristics of a task queue.

Format

MODIFY QUEUE queue-name

Command Qualifiers	Defaults
/FILE_SPECIFICATION=file-spec	Existing queue repository file
/MAX_WORKSPACES_SIZE=n	Specified in the existing definition

Privileges Required

Write access to the queue repository file. If the queue repository file has the default protection from the CREATE QUEUE command, you need OpenVMS SYSPRV privilege or the UIC [1,4] to modify the queue.

Parameters

queue-name

The name of the queue whose characteristics you want to modify. A queue name can be any valid RMS file name containing 1 through 39 alphanumeric characters.

Qualifiers

/FILE_SPECIFICATION=file-spec

Specifies the file specification of a new queue repository file. The file specification can be any valid RMS file specification or logical name. If you do not use the /FILE_SPECIFICATION qualifier, the existing queue repository file is used. If you do not specify a full file specification, the missing components are taken from the default file specification, SYS$SYSTEM:queue-name.DAT, where queue-name is the name of the queue.

/MAX_WORKSPACES_SIZE=n

Specifies the maximum total size (in bytes) of workspaces allowed in a single queued task element for the queue you modify. If you do not use the /MAX_WORKSPACES_SIZE qualifier, the default is /MAX_WORKSPACES_SIZE=256. You can specify a value of 0 through 31,720. If a queued task element's workspace size on a call to the ACMS$QUEUE_TASK service exceeds the value specified with the /MAX_WORKSPACES_SIZE qualifier, you receive an error when you queue the task.

Specify the largest workspace size needed for a single queued task element that will be queued to the queue. Use the following formula to determine the workspace size for a single queued task element:

2 * (n+1) + size (in bytes) of workspace 1 + size (in bytes) of workspace 2 . . . + size (in bytes) of workspace n (where n is the total number of workspaces)

The number of workspaces and size of the workspaces that can be passed to a task are displayed when you use the Application Definition Utility (ADU) command DUMP GROUP.

For the most efficient performance of the queue services and the QTI, specify the smallest possible value with the /MAX_WORKSPACES_SIZE qualifier.

Notes

You must use either the /FILE_SPECIFICATION or /MAX_WORKSPACES_SIZE qualifier with the MODIFY QUEUE command.

The MODIFY QUEUE command requires exclusive access to the queue repository file. If the queue is currently being processed by the QTI, the queue must be stopped with the ACMS/STOP QUEUE command before you issue this command. If the queue has been accessed by an image using the ACMS queue task services, the image must be exited.

A queue is not available for any queue operations while it is being modified.

Examples

ACMSQUEMGR> MODIFY QUEUE DEVO_QUE /FILE_SPECIFICATION=DEVO.DAT
      

This command modifies queue DEVO_QUE, naming DEVO.DAT as the queue repository file.

ACMSQUEMGR> MODIFY QUEUE DOCO_QUE /MAX_WORKSPACES_SIZE=500
      

This command modifies queue DOCO_QUE, setting the maximum workspace size of tasks to 500.