Document revision date: 19 July 1999

By default, all nodes in an OpenVMS Cluster environment are able to run the queue manager, in no specified order of preference. The /ON qualifier of the START/QUEUE/MANAGER command lets you specify a list of OpenVMS Cluster member nodes in the order that they should claim the queue manager process. Compaq recommends that you specify an asterisk (*) at the end of the node list to make sure that at least one node is always available to run the queue manager.

12.7 Stopping and Restarting the Queue Manager

To stop and restart the queue manager, you need to enter DCL commands.

12.7.1 Stopping the Queue Manager

To shut down the queue manager on a standalone node or an OpenVMS Cluster node, enter the following command:

$ STOP/QUEUE/MANAGER/CLUSTER

The queue manager performs the following tasks:

• Aborts all current jobs that cannot be restarted and requeues all current restartable jobs
• Stops all execution queues
• Disables autostart on all nodes
• Closes all queue database files associated with that queue manager

Once you enter STOP/QUEUE/MANAGER/CLUSTER, the queue manager process remains stopped; requests to that queue manager are denied until you restart the queue manager by entering START/QUEUE/MANAGER. (Note that the queue system remains running as long as one or more queue managers are running.)

OpenVMS Cluster transitions do not change the state of the queue manager. Newly available nodes do not attempt to start the queue manager (unless you enter START/QUEUE/MANAGER).

Use the /CLUSTER qualifier to stop a clusterwide queue manager. If you enter the obsolete command STOP/QUEUE/MANAGER (without the /CLUSTER qualifier), the command performs the same function as STOP/QUEUES/ON_NODE. (Use STOP/QUEUES/ON_NODE to stop all queues on a single node without stopping the queue manager.)

12.7.2 Restarting the Queue Manager

The queue manager restarts automatically whenever you reboot the system. However, you might need to enter START/QUEUE/MANAGER for one of the following reasons:

• If STOP/QUEUE/MANAGER/CLUSTER has been executed, enter START/QUEUE/MANAGER to restart the queue manager.
• In an OpenVMS Cluster environment, enter START/QUEUE/MANAGER with the /ON qualifier to modify the list of preferred nodes on which the queue manager can run. For more information, see Section 12.6.
• In an OpenVMS Cluster environment, enter START/QUEUE/MANAGER to ensure that the queue manager process executes on the most preferred, available node. If it does not, the queue manager will be moved to the most preferred, available node without interruption of service. If you are using the default node list (*), the queue manager will not be moved.

How to Perform This Task

To restart the queue manager, use a command in the following format:

START/QUEUE/MANAGER[/ON=(node,...)] [dirspec]

Specify the /ON=(node,...) qualifier and dirspec parameter only if you want to change the value you are currently using for the qualifier or parameter. The command you enter to start the queue manager is stored in the queue database, with any qualifier or parameter you specify. If you do not specify a qualifier or parameter, the queue manager is started using the node list and location (if any) stored in the queue database.

If the queue manager does not start, see Section 12.11.1 for a troubleshooting checklist.

12.8 Using Multiple Queue Managers

You can use multiple queue managers to distribute the batch and print work load among nodes and disk volumes. You need to understand what multiple queue managers are and how to create additional queue managers.

12.8.1 Understanding Multiple Queue Managers

Explanations of items related to the operation of multiple queue managers follow.

Restrictions on Using Multiple Queue Managers

Multiple queue managers have the following restrictions:

• Queues running on one queue manager cannot reference queues running on a different queue manager. For example, a generic queue running on queue manager A cannot direct jobs to an execution queue running on queue manager B.
• You cannot move a job from a queue on one queue manager to a queue on a different queue manager.
• The operating system allows a maximum of five queue managers in an OpenVMS Cluster environment.

Names of Multiple Queue Managers

The process name for a queue manager is the first twelve characters of the queue manager name. The default queue manager name is SYS$QUEUE_MANAGER; the default queue manager process name is QUEUE_MANAGE. If you create an additional queue manager named PRINT_MANAGER, the process name is PRINT_MANAGE.

Know the process names of all your queue managers so that you can troubleshoot queue manager problems, as explained in Section 12.11.

Multiple Queue Managers' Use of Queue Database Files

Multiple queue managers share a single master file. However, a queue database with multiple queue managers contains a queue file and a journal file for each queue manager, as explained in Section 12.2.

Commands for Managing Multiple Queue Managers

By default, the following commands affect the default queue manager SYS$QUEUE_MANAGER or the queues running on the default queue manager:

• START/QUEUE/MANAGER
• ENABLE AUTOSTART/QUEUES and DISABLE AUTOSTART/QUEUES
• STOP/QUEUES/ON_NODE
• STOP/QUEUE/MANAGER/CLUSTER
• DELETE/QUEUE/MANAGER

The /NAME_OF_MANAGER qualifier allows you to specify a different queue manager for these commands.

12.8.2 Creating Additional Queue Managers

1. Follow steps 1 and 2 in Section 12.5.
2. To create an additional queue manager, enter a command in the following format:

   START/QUEUE/MANAGER/ADD/NAME_OF_MANAGER=name[/ON=(node,...)] [dirspec]

   
   where:

   /ADD	Creates an additional queue manager in the existing master file and creates new queue and journal files
   /NAME_OF_MANAGER= name	Creates a non-default queue manager with a name up to 31 characters long. You can create a maximum of five queue managers.
   /ON= (node,...)	Allows you to customize failover of the queue manager. For more information, see Section 12.6.
   dirspec	Specifies the location of the queue and journal files, as explained in Section 12.3.2. Use this parameter if you are creating the queue and journal files in a location other than the default.

Example

The command in the following example creates and starts a new queue manager named BATCH_MANAGER.

$ START/QUEUE/MANAGER/ADD/NAME_OF_MANAGER=BATCH_MANAGER/ON=(A,B,*) DUA2:[QUEUES]

12.8.2.1 Creating and Moving Queues with Multiple Queue Managers

When you create a queue with the INITIALIZE/QUEUE command, specify the name of the queue manager on which it is to run by including the /NAME_OF_MANAGER qualifier. If you do not specify the /NAME_OF_MANAGER qualifier, the queue is created to run on the default queue manager, SYS$QUEUE_MANAGER.

To move an existing queue from its original queue manager to a different queue manager, delete the queue with the DELETE/QUEUE command and re-create the queue with the INITIALIZE/QUEUE command.

12.8.2.2 Maintaining Queue Managers

When entering DCL commands to maintain the queue manager, be sure to specify the /NAME_OF_MANAGER qualifier to specify the queue manager to which the command is to apply. If you do not specify the /NAME_OF_MANAGER qualifier, the command is executed on the default queue manager, SYS$QUEUE_MANAGER.

Example

In the following example:

• The first command creates and starts the queue manager PRINT_MANAGER and creates master, queue, and journal files.
• The second command creates and starts an additional queue manager, BATCH_MANAGER; queue and journal files are created for it automatically.
• The default queue manager SYS$QUEUE_MANAGER is not defined.
• The SHOW QUEUE/MANAGERS command displays information about the queue managers running on your system, as explained in Section 12.4.

$ START/QUEUE/MANAGER/NEW_VERSION/NAME_OF_MANAGER=PRINT_MANAGER - _$ /ON=(JADE,RUBY,*) $ START/QUEUE/MANAGER/ADD/NAME_OF_MANAGER=BATCH_MANAGER - _$ /ON=(OPAL,PEARL,*) $ SHOW QUEUE/MANAGERS/FULL Master file: SYS$COMMON:[SYSEXE]QMAN$MASTER.DAT; Queue manager PRINT_MANAGER, running, on JADE:: /ON=(JADE,RUBY,*) Database location: SYS$COMMON:[SYSEXE] Queue manager BATCH_MANAGER, running, on OPAL:: /ON=(OPAL,PEARL,*) Database location: SYS$COMMON:[SYSEXE]

12.9 Saving and Restoring the Queue Database

Each time you want to preserve changes to your queue configuration, save a copy of your queue database files. In this way, if your queue database files are not accessible, you can restore the queue database you have saved; you thus avoid having to redefine forms and characteristics and reinitialize each queue.

12.9.1 Saving Queue Database Files

To save a record-by-record copy of your queue database files while the queuing system is functioning, perform the following steps. This procedure saves definitions of queues, forms, and characteristics. No job information is preserved. (Compaq recommends not saving the journal file because timed and pending jobs might be reexecuted after the journal file is restored.)

How to Perform This Task

1. To save the master file, enter an OpenVMS Convert utility (CONVERT) command in the following format:

   CONVERT/SHARE QMAN$MASTER.DAT master-filename

   
   where master-filename is the name of the file to which QMAN$MASTER.DAT is to be copied.
   For more information about CONVERT, refer to the OpenVMS Record Management Utilities Reference Manual.

2. Enter a CONVERT command in the following format to save the queue file:

   CONVERT/SHARE SYS$QUEUE_MANAGER.QMAN$QUEUES queue-filename

   
   where queue-filename is the name of the file to which SYS$QUEUE_MANAGER.QMAN$QUEUES is to be copied.

3. Use the Backup utility (BACKUP) to save the files created with CONVERT. Use a command in the following format:

   BACKUP/LOG masterfile-name, queue-filename device:saveset-name/LABEL=label

   
   For more information about the Backup utility, refer to the OpenVMS System Management Utilities Reference Manual.

Example

The following example is a simple procedure showing how to save the queue database.

$ SET DEFAULT SYS$COMMON:[SYSEXE] $ CONVERT/SHARE QMAN$MASTER.DAT MASTERFILE_9SEP.KEEP; $ CONVERT/SHARE SYS$QUEUE_MANAGER.QMAN$QUEUES QFILE_9SEP.KEEP; $ INITIALIZE MUA0: QDB $ MOUNT/FOREIGN MUA0: %MOUNT-I-MOUNTED, QDB mounted on _LILITH$MUA0: $ BACKUP/LOG MASTERFILE_9SEP.KEEP,QFILE_9SEP.KEEP MUA0:QDB_9SEP.SAV/LABEL=QDB %BACKUP-S-COPIED, copied SYS$COMMON:[SYSEXE]MASTERFILE_9SEP.KEEP; %BACKUP-S-COPIED, copied SYS$COMMON:[SYSEXE]QFILE_9SEP.KEEP; $ DISMOUNT MUA0:

12.9.2 Restoring Queue Database Files

When you restore queue database files, all queue, form, characteristic, and queue manager information is restored. However, information about jobs in the queues is not restored.

How to Perform This Task

1. If the queue manager is running, stop it by entering the STOP/QUEUE/MANAGER/CLUSTER command.
2. Delete all three queue database files. (You must delete all three files, even if only one or two of them are lost.)
3. Use the MOUNT command to mount the disk or tape containing the queue database backup.
4. Use the Backup utility (BACKUP) to restore the queue file and master file from the save set you created in step 3 of Section 12.9. If the master file or queue file is stored in a location other than the default, make sure you restore it to the correct location or that you specify the new location when you start the queue manager.

   Note When you restore your queue database, you must always restore both the master and queue files, even if you lost only one of those files.

5. Start the queue manager with the START/QUEUE/MANAGER command. Do not enter the /NEW_VERSION qualifier: a new, empty journal file will be created automatically.

Example

The following example is a simple procedure showing how to restore the queue database from tape.

$ STOP/QUEUE/MANAGER/CLUSTER $ SET DEFAULT SYS$COMMON:[SYSEXE] $ DELETE SYS$QUEUE_MANAGER.QMAN$JOURNAL;,SYS$QUEUE_MANAGER.QMAN$QUEUES;, - _$ QMAN$MASTER.DAT; $ MOUNT/FOREIGN MUA0: %MOUNT-I-MOUNTED, QDB mounted on _LILITH$MUA0: $ BACKUP/LOG MUA0:QDB_9SEP.SAV/SELECT=[SYSEXE]MASTERFILE_9SEP.KEEP; - _$ QMAN$MASTER.DAT; %BACKUP-S-CREATED, created SYS$COMMON:[SYSEXE]QMAN$MASTER.DAT;1 $ SET MAGTAPE/REWIND MUA0: $ BACKUP/LOG MUA0:QDB_9SEP.SAV/SELECT=[SYSEXE]QFILE_9SEP.KEEP; - _$ SYS$QUEUE_MANAGER.QMAN$QUEUES %BACKUP-S-CREATED, created SYS$COMMON:[SYSEXE]SYS$QUEUE_MANAGER.QMAN$QUEUES;1 $ DISMOUNT MUA0: $ START/QUEUE/MANAGER

12.10 Maximizing Queuing System Performance

The following resources have the most effect on queuing system performance:

• CPUs --- CPU speed and availability are important on the nodes on which the queue managers are running. The more time the queue manager has and the faster the CPU, the faster the queue manager can process information.
• Disks --- Disk speed as well as nonqueuing activity (such as paging and heavy access to the database) on the database disk can affect performance.

Use the following methods to maximize your queuing system's performance:

• Maintain queue manager processes on the fastest and most available nodes in a cluster. (See Section 12.1.)
• Create an additional queue manager to run on another node to distribute the CPU load on heavily used queuing systems. (See Section 12.8.)
• Move queue and journal files to disks with less activity or higher speeds. (See Section 12.5.)
  Note that moving the master file provides little difference in performance.

Use the following sections to help solve queue manager problems:

Topic	For More Information
Avoiding common problems: a troubleshooting checklist	Section 12.11.1
If the queue manager does not start	Section 12.11.2
If the queuing system stops or the queue manager does not run on specific nodes	Section 12.11.3
If the queue manager becomes unavailable	Section 12.11.4
If the queuing system does not work on a specific OpenVMS Cluster node	Section 12.11.5
If you see inconsistent queuing behavior on different OpenVMS Cluster nodes	Section 12.11.6
Reporting a queuing system problem to Compaq support representatives	Section 12.12

12.11.1 Avoiding Common Problems: A Troubleshooting Checklist

To avoid the most common queuing system problems, make sure you have met the following requirements:

Requirement	For More Information
QMAN$MASTER is identically defined on all nodes in the cluster.	Section 12.3
The queue database is in the specified location.	Section 12.3
The queue database disk is mounted and available.	Section 12.3
The node list specified with the /ON qualifier contains a sufficient number of nodes. If you specify a node list, Compaq recommends that you include an asterisk (*) at the end of the node list.	Section 12.11.4
The system address parameters SCSNODE and SCSSYSTEMID match the DECnet for OpenVMS node name and node ID.	Section 12.11.5

12.11.2 If the Queue Manager Does Not Start

If the queue manager does not start when you enter the START/QUEUE/MANAGER command, the system displays the following message:

%JBC-E-QMANNOTSTARTED, queue manager could not be started

12.11.2.1 Investigating the Problem

Search the operator log file SYS$MANAGER:OPERATOR.LOG (or look on the operator console) for messages from the queue manager and job controller for information about the problem, as follows:

$ SEARCH SYS$MANAGER:OPERATOR.LOG/WINDOW=5 QUEUE_MANAGE, JOB_CONTROL,BATCH_MANAGE

Use the information provided with these messages to further investigate the problem, making sure you have met the requirements listed in Section 12.11.1.

12.11.2.2 Cause

The cause of the problem is the system's inability to find the queue master file. Often the logical is not defined correctly, or the disk is not available. For example, the following message indicates that the master queue file does not exist in the expected location:

%%%%%%%%%%% OPCOM 13-MAR-1998 15:53:52.84 %%%%%%%%%%% Message from user JOB_CONTROL on ABDCEF %JBC-E-OPENERR, error opening SYS$COMMON:[SYSEXE]QMAN$MASTER.DAT %%%%%%%%%%% OPCOM 13-MAR-1998 15:53:53.04 %%%%%%%%%%% Message from user JOB_CONTROL on ABDCEF -SYSTEM-W-NOSUCHFILE, no such file

12.11.2.3 Correcting the Problem

On systems with multiple queue managers, search for messages displayed by additional queue managers by including their process names in the search string. To display information about queue managers running on your system, use the SHOW QUEUE/MANAGERS command as explained in Section 12.4. Correct any problem indicated in the displayed information.

Example

$ START/QUEUE/MANAGER DUA55:[SYSQUE](1) %JBC-E-QMANNOTSTARTED, queue manager could not be started(2) $ SEARCH SYS$MANAGER:OPERATOR.LOG /WINDOW=5 QUEUE_MANAGE,JOB_CONTROL(3) %%%%%%%%%%% OPCOM 14-APR-1998 18:55:18.23 %%%%%%%%%%% Message from user QUEUE_MANAGE on CATNIP %QMAN-E-OPENERR, error opening DUA55:[SYSQUE]SYS$QUEUE_MANAGER.QMAN$QUEUES; %%%%%%%%%%% OPCOM 14-APR-1998 18:55:18.29 %%%%%%%%%%% Message from user QUEUE_MANAGE on CATNIP -RMS-F-DEV, error in device name or inappropriate device type for operation %%%%%%%%%%% OPCOM 14-APR-1998 18:55:18.31 %%%%%%%%%%% Message from user QUEUE_MANAGE on CATNIP -SYSTEM-W-NOSUCHDEV, no such device available(4) $ START/QUEUE/MANAGER DUA5:[SYSQUE](5)

	privacy and legal statement
6017PRO_054.HTML