Compaq ACMS for OpenVMS
Managing Applications
Previous Contents Index

Chapter 20
ACMSQUEMGR Commands

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.

CREATE QUEUE Command (ACMSQUEMGR>)

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:

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

/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

#1 

ACMSQUEMGR> CREATE QUEUE BIG_NUMBERS_QUE

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

#2 

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.

#3 

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.

DELETE ELEMENT Command (ACMSQUEMGR>)

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:

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:

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

Notes

None

Examples

#1 

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.

#2 

ACMSQUEMGR>  DELETE ELEMENT * YOUR_QUE

This command deletes all queued task elements in queue YOUR_QUE.

#3 

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.

#4 

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.

#5 

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.

#6 

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.

DELETE QUEUE Command (ACMSQUEMGR>)

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

#1 

ACMSQUEMGR> DELETE QUEUE GROUP_QUE

This command deletes queue GROUP_QUE.

#2 

ACMSQUEMGR> DELETE QUEUE BOSS_QUE /PURGE

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

EXIT Command (ACMSQUEMGR>)

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.

HELP Command (ACMSQUEMGR>)

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.

MODIFY QUEUE Command (ACMSQUEMGR>)

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

#1 

ACMSQUEMGR> MODIFY QUEUE DEVO_QUE /FILE_SPECIFICATION=DEVO.DAT

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

#2 

ACMSQUEMGR> MODIFY QUEUE DOCO_QUE /MAX_WORKSPACES_SIZE=500

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

Previous Next Contents Index