Document revision date: 15 July 2002

Before you can create queues, you must create a queue database by entering a command in the following format:

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

where:

/NEW_VERSION	Specifies that new queue database files are to be created: Master file Queue file Journal file Specify the /NEW_VERSION qualifier only if you want to create new database files. If your queuing system is already functioning, creating new database files is not necessary.
/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.

You normally perform this task only once because when you enter the command, the system stores it, along with any qualifier or parameter you enter, in the queue database.

The job controller automatically starts the queue manager during reboot unless you enter a STOP/QUEUE/MANAGER/CLUSTER command. For this reason, including START/QUEUE/MANAGER in your startup command procedure is unnecessary.

How to Perform This Task

1. Make sure the values of the system address parameters SCSNODE and SCSSYSTEMID match the DECnet for OpenVMS node name and node ID. These values must be correctly defined for the queuing system to operate correctly:
   • The PARAMETERS SHOW command of the System Management utility (SYSMAN) determines the value of the system address parameters SCSNODE and SCSSYSTEMID.
   • The Network Control Program (NCP) SHOW EXECUTOR SUMMARY command shows the DECnet for OpenVMS node name and node ID.
   For more specific instructions, see the second example in Section 13.11.5.1.
2. To create queue database files in the default location, SYS$COMMON:[SYSEXE], go to step 3.
   To create queue database files in a location other than the default, follow the instructions in Section 13.3.1 or Section 13.3.2, or both.
3. To start the queue manager and create queue database files, enter a START/QUEUE/MANAGER command. This command starts the queue manager process and, optionally, creates queue and journal files.

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

Example

The following example specifies that:

• The master file is to located in the directory DUA4:[MASTER].
• The queue and journal files are to be located in the directory DUA2:[SYSQUE]. (The master file, however, will remain in DUA4:[MASTER].)

$ DEFINE/SYSTEM/EXECUTIVE_MODE QMAN$MASTER DUA4:[MASTER] $ MOUNT/SYSTEM/NOASSIST DUA4: $ ! $ ! Add the two previous commands to SYLOGICALS.COM $ ! $ START/QUEUE/MANAGER/NEW_VERSION DUA2:[SYSQUE]

For information about creating one or more additional queue managers, see Section 13.8.

13.6 Customizing Queue Manager Failover

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.

13.7 Stopping and Restarting the Queue Manager

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

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

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

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

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

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]

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

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:

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

   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

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

	privacy and legal statement
6017PRO_056.HTML