HP OpenVMS Systems Documentation

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 13.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:

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 13.11.1 for a troubleshooting checklist.

13.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.

13.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 13.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 13.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.

13.8.2 Creating Additional Queue Managers

1. Follow steps 1 and 2 in Section 13.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 13.6.
   dirspec	Specifies the location of the queue and journal files, as explained in Section 13.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]

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.

13.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 13.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]

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.

13.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:

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.)

   Caution When starting a queue manager on OpenVMS, the queue manager process always opens version number one of the queue journal file (SYS$QUEUE_MANAGER.QMAN$JOURNAL;1). For this reason, when you restore the queue system files with the Backup utility, you must ensure that the latest version of the queue journal file is version number one.

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 13.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.

   Caution When starting a queue manager on OpenVMS, the queue manager process always opens version number one of the queue journal file (SYS$QUEUE_MANAGER.QMAN$JOURNAL;1). For this reason, when you restore the queue system files with the Backup utility, you must ensure that the latest version of the queue journal file is version number one.

   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

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 13.1.)
• Create an additional queue manager to run on another node to distribute the CPU load on heavily used queuing systems. (See Section 13.8.)
• Move queue and journal files to disks with less activity or higher speeds. (See Section 13.5.)
  Note that moving the master file provides little difference in performance.

Use the following sections to help solve queue manager problems:

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

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

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 13.11.1.

13.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-2000 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-2000 15:53:53.04  %%%%%%%%%%%
Message from user JOB_CONTROL on ABDCEF
-SYSTEM-W-NOSUCHFILE, no such file

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 13.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-2000 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-2000 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-2000 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)

1. This command attempts to start the queue manager, specifying DUA55:[SYSQUE] as the location of the queue and journal files.
2. The error message indicates that the queue manager did not start.
3. This command searches the operator log file for relevant messages. The SEARCH command does not include a second queue manager name, such as BATCH_MANAGE.
4. This message indicates that the queue file could not be opened because device DUA55: does not exist.
5. This command, which correctly specifies DUA5:[SYSQUE] as the location for the queue and journal files, successfully starts the queue manager.

For more information about multiple queue managers and their process names, see Section 13.8.1.

13.11.3 If the Queuing System Stops or the Queue Manager Does Not Run on Specific Nodes

Use this section if the queue manager does not run on a specific node in the cluster, or if the queuing system stops, especially after one of the following actions:

• The node on which the queue manager was running leaves the cluster.
• A new node boots into the cluster.
• You change the node list specified with the /ON qualifier of the START/QUEUE/MANAGER command.
• You start the queue manager after moving the queue database.