BEA MessageQ
Installation and Configuration Guide for OpenVMS

The Monitor utility is used to monitor and control the MessageQ communications system. Because this utility uses messages to request information from the COM Server, you can use it to monitor more than one message queuing group. The Monitor utility screens display the current system status and configuration information.

11.3.1 Displaying Queue Counters

This option provides the display of permanent queue names (from DMQ$INIT.TXT) and temporary queue names.

Select Option D from the Monitor menu to display the current number of messages that are sent, received, or pending in a message queue.

The system prompts for: Display all, declared or MRQ [A,D,M] [A]:

where:

[All]	Use to select all queues.
[Declared]	Use to select attached queues.
[MRQ]	Use to select multireader queues (that share Read access).

11.3.2 Displaying Queue Quotas

Use this option when monitoring memory usage to determine whether an application is reading its messages as fast as they are being sent. You can assign greater system resources to applications that are falling behind in their message reading.

Select Option Q from the Monitor utility menu to display queue quotas. The system prompts for:

Display all, declared or MRQ [A,D,M] [A]:

where:

[All]	Use to select all queues.
[Declared]	Use to select attached queues.
[MRQ]	Use to select multireader queues (that share Read access).

11.3.3 Displaying COM Server Status

Select Option T from the Monitor utility menu to display statistics of the COM Server process

The COM Server Specific Information screen displays messages sent to and received by the COM Server process, errors logged to the COM Server, the amount of memory available in the buffer pool, and the number of queue slots remaining. Use this option to review system status and resource allocation to avoid such problems as buffer pool exhaustion and queue failures.

Press Return to return to the Monitor menu options.

Legend:

• MCS created on shows the date and time when the group was created.
• Counters reset on shows the last time the queues and group counters were reset by either a Monitor Reset command or an automatic reset when the counters exceeded a counter-full threshold.
• DMQ ID shows the platform type, DMQ version, and external cross-group protocol it uses.
• COM Server Msgs shows standard queue counts for the COM Server's queue. It also shows the number of times the COM Server became active to scan the buffer pool.
• Error Section shows:
  • Number of entries in the error log
  • Number of queuing failures encountered which typically exhaust the buffer pool
  • Number of process cleanups that the COM Server needed to perform on behalf of a failed process to assure that global queuing resources were released
• Buffer Pool shows the current status of the MessageQ buffer pool.
  It shows the total number of buffers, number of unallocated buffers, and the threshold of available count. The Low Buffer and user program access protection warnings are displayed including an asterisk "*" in the warning level column if the buffer pool is Low.
• Queue Slots shows the current number of allocated temporary queues and the total of remaining slots.
• DmQ cross group communication shows if communications between MessageQ groups has been enabled. If DISABLED is displayed, no message exchange can occur between MessageQ groups.

Use this option to display the queue number, the process ID, and the number of messages sent, received, and pending for the selected queue.

Select Option P from the MONITOR utility menu to display the status of a particular queue The system prompts:

Enter queue # for request (default = COM Servers queue number): 

Select Option R from the Monitor utility menu to reset the COM Server counters. By resetting the counters to zero, you can create a starting point from which to begin monitoring COM Server statistics.

11.3.6 Displaying the Routing Table

Select Option RT from the Monitor utility menu to display routing table information.

The routing table is part of the DMQ$INIT.TXT file and is used to configure cross-group communications between groups that do not have a direct network connection.

11.3.7 Shutting Down COM Server Process

Select Option K from the MONITOR utility menu to shut down the COM Server process. Use this option to provide an orderly shutdown of cross-group communications. To use this option, you must have the ACCEPT_KILL_CMD set to YES in the group initialization file and have either VMS OPER privilege or the Manager utility rights identifier DMQ$OPERATOR. See Section 14.3 for more information on the DMQ$OPERATOR rights identifier.

CAUTION:

Do not use the DCL STOP command to shut down the COM server. Refer to Chapter 10 on other ways to stop the COM Server.

Select Option LS from the MONITOR utility menu to display link summary information. This screen displays the status of DECnet and TCP/IP network communications links for each group.

11.3.9 Displaying Link Detail Information

Select Option LD from the Monitor utility menu to display detailed link information. The system asks:

Inbound or Outbound? (I/O) [I] 

Make your selection; the default is Inbound (I).

If the network link uses a TCP/IP transport, the fields in the lower right corner of the screen display would show:

Transport type = TCP/IP 
Host name      = rabbit 
INET address   = 
Port number    = 4573 

If the network link has a transport type unknown to the Monitor utility, the fields in the lower right corner of the screen display would show:

Transport type  = *Unknown* (n) 
Host name       = rabbit 
Host address    = 
Connect address = 4573 

Select Option LT from the Monitor utility menu to display the link connect table. This screen displays the failover search list for groups as defined in the DMQ$INIT.TXT file.

11.3.11 Displaying Group Detail Information

Select Option GD from the Monitor utility menu to display group detail information.

11.3.12 Resetting Cross-Group Connections

Select Option C from the Monitor utility menu to reestablish cross-group connections.

Use this option if network communications links between the groups were lost and you want to reestablish all cross-group connections.

11.3.13 Displaying Remote Groups

Select Option A from the Monitor utility menu to monitor the status of a remote group

After you set the alternate group by using this option, all options will display the information for the selected group. To display information for the local group, select this option and enter the local group number.

Note:

This option works only for message server systems; it does not work for client implementations.

The DMQ$MGR_UTILITY program provides a collection of menu-driven services that manage and control several MessageQ subsystems.

To run this utility, select Option 7 from the MessageQ main menu.

11.4.1 Displaying Queue Summary Information

Select Option DS from the Manager Utility menu to display summary level information about queues

11.4.2 Displaying Queue Detail Information

Select Option DQ from the Manager Utility menu to display detailed information about a particular queue. The utility prompts for the queue number.

11.4.3 Flushing Queues

Select Option QC from the Manager Utility menu, then select Option FQ from the Queue Controls Menu to remove any pending queue message entries from a message queue.

Use this option to selectively clear queues of pending messages, which can remain after an abnormal program termination. By removing unwanted messages from the unattached queues, you clear space in the buffer pool for other messages.

When you select this option, the system prompts for the queue number to flush.

Note:

The queue to be flushed can not be attached when you initiate the flush request.

Select Option QC from the Manager Utility menu, then select Option SPQ from the Queue Controls Menu to stop all message traffic to the specified message queue. Once a Stop Queue request has been executed, no more messages are allowed to be enqueued into the stopped queue until the queue is restarted.

When you select this option, the system prompts for the queue number to be stopped and inquires whether or not to stop the queue fast (immediately) or gracefully.

 Enter queue number to stop: 
 Stop fast? (Y/N) [N]: 

When a queue is stopped gracefully, the queue will no longer accept new messages; however, any pending messages that are in the queue are allowed to be read until the queue is empty. Once the queue is empty it is placed in a stopped state.

When a queue is stopped fast, the queue will not accept any new messages and will not allow pending messages to be read from the queue.

11.4.5 Starting Queues

Select Option QC from the Manager Utility menu, then select Option STQ from the Queue Controls Menu to start stopped message traffic to the specified message queue. When you select this option, the system prompts for the queue number to be started.

11.4.6 Forcing a Process to Exit

Select Option FR from the Manager Utility menu to force a process to exit.

Use this utility instead of the DCL command STOP to allow process exit handlers to control a clean process shutdown.

11.4.7 Redirecting Status and Trace Output

Error and status logging in MessageQ for OpenVMS can be enabled or disabled by

• using logical names that are read when a process calls the pams_attach_q service
• dynamically by using the RO option from the Manger Utility.

To enable tracing prior to starting a user or sender program, set either one or both of the following logicals:

• DMQ$DEBUG = ALL
  This setting turns on the MessageQ call tracing.
• DMQ$SERVER_TRACE = YES
  This setting turns on the service-specific tracing for a MessageQ Server process.

In either case, trace output is sent to the targets which are specified in the logical name DMQ$TRACE_OUTPUT. The following targets are possible:

EVL_LOG	Common event log for the group
CONSOLE	Console TTY device, either OPA0: or DMQ$ERROUT:
SYSOUT	SYS$OUTPUT: for the process
SYSERR	SYS$ERROR: for the process
USER_LOG	A file in SYS$LOGIN: or the file specified by DMQ$USER_LOG_NAME

The default setting for DMQ$TRACE_OUTPUT is SYS$OUTPUT.

You can override the default settings by changing the process logical name values prior to running a program. This is done for MessageQ Servers by modifiying the DCL command procedure DMQ$USER:DMQ$SET_SERVER_LOGICALS.COM. See Example 11-1 .

Example 11-1 Default MRS section in DMQ$USER:DMQ$SET_SERVER_LOGICALS.COM

 
$ MRS: 
$       trace_output    = "SYSOUT" 
$       group_output    = "EVL_LOG,CONSOLE" 
$       process_output  = "SYSOUT" 
$       debug           = "" 
$       headers         = "" 
$       server_trace    = "" 
$       user_log        = "" 
$ 
 

Use the RO option of the DMQ$MGR_UTILITY to dynamically enable the tracing feature and redirect tracing information without stopping and restarting the application.

Enter the primary queue number of the process you want to modify.

Using this screen, you can also select debug switch settings (DMQ$DEBUG) which allow you to set output streams for the selected debugging information, as follows:

ERROR	Display errors only.
TRACE	Display call tracing.
ALL	Display complete (error and call tracing) data.
NONE	Disable tracing.

Note:

This option is also used for event logging using DMQ$PROCESS_OUTPUT and DMQ$GROUP_OUTPUT settings. Refer to Chapter 13 for more information on separating error logging streams to isolate system problems.

The central error logging facility manages the Event Logger process (EVL_LOG). This facility directs error and debugging trace information to output streams: EVL_LOG, CONSOLE, SYSOUT, SYSERR, or USER_LOG. These streams are assigned by logical names, with defaults provided by MessageQ . They can be dynamically redirected from the Redirect Status/Trace Switch option.

11.4.8.1 Directing Error and Status Messages Prior to Starting a Program

Two separate classes of events can be logged by a process connected to MessageQ ; a process event and a group event. Process events apply only to a particular process while group events are the events that impact the entire message queuing group.

Process events are logged to the targets which are specified in the logical name DMQ$PROCESS_OUTPUT. This logical can be set to any or all of the same five targets that DMQ$TRACE_OUTPUT can be set to: EVL_LOG, CONSOLE, SYSOUT, SYSERR, or
USER_LOG. The default for DMQ$PROCESS_OUTPUT is SYS$OUTPUT.

Group events are logged to the targets which are specified in DMQ$GROUP_OUTPUT. Any, or all of the five targets may be chosen. The default for DMQ$GROUP_OUTPUT is EVL_LOG,CONSOLE.

11.4.8.2 Redirecting Error and Status Logging When a Program is Running

Event logging can be dynamically redirected with the RO option of DMQ$MGR_UTILITY. Refer to Section 11.4.7 for more information. Note that the RO option prompts you to set values for the DMQ$PROCESS_OUTPUT and DMQ$GROUP_OUTPUT logical names.

11.4.9 Using Event Log Control

The event log file is a common log managed by the Event Logger. It serves as a single repository for logging all MessageQ events. All entries are time-stamped.

11.4.9.1 Storing Event Data

Any trace data or events which are directed to the EVL_LOG target are sent by the mailbox to the DMQ$EVENT_LOGGER process. This server is designed to service the mailbox as quickly as possible, while efficiently handling logging to the DMQ$LOG:DMQ$EVL_bbbb_ggggg.LOG file. This mechanism means that high logging event rates can be handled with less impact on the timing of events than if the events were logged synchronously in the process context. This feature therefore can be useful in tracing the application or MessageQ problems that are time-related.

11.4.9.2 Switching Event Log Files

Select Option LC from the Manager Utility menu to run the Event Log Control. Use this option to close and move the EVL_LOG file, as well as to start a new log

The LC event log control option is used to switch logging from one version of the log to the next version.

Closing a log file and opening a new log file allows the previous version to be copied to tape or disk, and then be deleted. This option can be used by sites with 24x7 operations that can not afford to shut down a running group to manage large event log files. A large event log can be generated in unusual situations where large number of network or queuing errors are repeated due to some system failure.

Note:

Refer to Chapter 13 for more information on system troubleshooting.

Select Option DG from the Manager Utility menu to display all entries contained in the group name table for the current message queuing group.

The Time column shows the last time each entry was updated. The updates take effect when the DMQ$LOADER utility runs.

11.4.11 Journal Controls

Select Option JC from the Manager Utility menu to select the Journal Controls menu. This menu allows you to control all journal management functions.

MessageQ provides the following journal files:

• Destination Queue File (DQF)
• Store and Forward File (SAF)
• Dead Letter Journal (DLJ)
• Post Confirmation Journal (PCJ)

Journal Control selections allow you to open and close the message recovery journals and provide formatted dumps of their contents. All journal files (DQF, SAF, PCJ, and DLJ) can be manipulated with the DMQ$MGR_UTILITY program. These recoverable and auxiliary journal files have the same disk format; each journal is a sequence of files, not a single file).

Note:

Refer to Chapter 6 for detailed information on the MessageQ message recovery system and journal files.

When you select either the DQF or SAF option, the system displays a menu allowing you to open, close, delete, merge, dump, redirect, and obtain a directory of SAF or DQF files.

SAF or DQF files are dynamically created and deleted as needed by the recovery system; they are not preallocated fixed-size files. Both DQF and SAF files may be closed and the stream of messages in the file redirected to other targets. This can be in response to a message to the MRS Server from a suitably privileged user program, or from the entry in the Journal Control menu.

The DQF and SAF controls include the following options:

Note:

Refer to Chapter 15 for more information on Merge and Redirect options.

When you select either the DLJ or PCJ option, the system displays a menu that allows you to dump, delete, redirect, or display a directory of auxiliary journals.

The DLJ and PCJ journals are served by a separate server process, the JRN Server. This process maintains a history of all PCJ and DLJ filename changes in a disk file. This history is displayed by the DI (directory) and DU (dump) commands of DMQ$MGR_UTILITY to make it easy to find an old journal.

The PCJ and DLJ controls include the following options:

[Directory]	Displays a directory of DQF or SAF journal files.
[Dump]	Performs a formatted dump of a DQF or SAF journal file.
[Exit]	Exits a journal.
[Delete]	Deletes the DQF or SAF journal associated with the queue. Deleting an earlier journal removes its entry from the journal history file. Deleting all the existing journals clears the history file.
[Switch to]	Closes an old journal and opens a new one.

MessageQ software utilizes the capabilities of the underlying operating system and networking software to perform message queuing. For this reason, you may need to change the system configuration to run MessageQ and MessageQ applications efficiently. You may also need to tune your system on a regular basis to accommodate the growth and changes in your MessageQ environment.

The primary MessageQ resource to configure is memory---both global and local virtual memory. Other system resources, such as disk files, network links, and system parameters may need to be adjusted for large queuing networks to function properly. This chapter describes how to set OpenVMS and MessageQ configuration parameters and quotas for proper MessageQ operation.

12.2 Sizing and Tuning Processes

This section describes how to configure:

• Virtual Memory
• Global Memory
• I/O Channels
• Files
• Network Resources
• Other System Resources and Quotas
• Modifying DMQ$SET_SERVER_QUOTAS.COM

Virtual memory is allocated in OpenVMS by setting the page file quota alloted to a OpenVMS process. This quota must be less than the size of the system PAGEFILE and the system parameter VIRTUALPAGECNT.

The VIRTUALPAGECNT parameter limits the total number of pages that a single process can map to itself. The amount of virtual memory that is resident at any time is determined by the working set size, which is usually set much smaller than the page file quota.

The page file quota is passed as a parameter to the RUN command used to detach a MessageQ Server process. The quota for each server is specified in the DMQ$USER:DMQ$SET_SERVER_QUOTAS.COM command procedure. Methods for determining the amount of memory needed for specific servers is described in Section 12.3.3 .

12.2.2 Global Memory

MessageQ for OpenVMS uses four global sections to store messages. The MCS global section stores message headers. The other three global sections, called the LLS for small, medium, and large sections, store messages.

The amount of global memory alloted to store messages is a fixed resource. Available global memory is determined by the number and size of the buffer pool specified in the %BUFFER section of the DMQ$INIT.TXT file.

MessageQ also uses global sections for storing group information. These global sections are sized based on entries in the DMQ$INIT.TXT file. MessageQ run-time libraries also require global memory.

Adding a new MessageQ message queuing group may require changes to OpenVMS system parameters to allow the addition of global sections. The OpenVMS system parameters affected by this type of change are GBLPAGES, GBLPAGFIL and GBLSECTIONS.

MessageQ has quotas to limit the amount of global memory used by a particular queue. Queue quotas limit the number of messages queued and the total number of bytes that can be queued.

12.2.3 I/O Channels

The OpenVMS CHANNELCNT parameter limits the number of I/O channels alloted to a single process. Channels are used by MessageQ for network links and for message recovery journal files.

The COM Server allocates two channels for each cross-group link it manages. The TCP/IP and DECnet Link Driver processes allocate four channels per link. The MRS Server requires a channel for each open area file, which is a fixed size file used to store recoverable messages.

12.2.4 Files

The MessageQ message recovery system dynamically creates and deletes files as needed. The number of files that MRS can use is limited by the FILLM quota which is passed to the RUN command that starts the MRS Server. The total number of files used by the MRS Server is also limited by the OpenVMS CHANNELCNT parameter.

12.2.5 Network Resources

The primary system resource needed for cross-group messaging is buffer space associated with each cross group link. Buffers are stored in the local memory of the COM Server or Link Driver processes. Refer to Section 12.3 for more information.