|
|
|
|
|
|
Using BEA MessageQ System Management Utilities
This chapter describes two BEA MessageQ utility programs that can be used to perform system management tasks and to monitor BEA MessageQ system status.
The DMQ$MGR_UTILITY and DMQ$MONITOR utilities require that the BEA MessageQ environment variables be defined and accessible to the user. Use the DMQ$STARTUP.COM command procedure to define these variables.
The DMQ$MONITOR utility must be attached to a running group, while only some options of the DMQ$MGR_UTILITY utility require a connection to a running group. You can run these utilities independently or access them from the BEA MessageQ main menu.
Major System Management Tasks
Table 10-1 and Table 10-2 list major BEA MessageQ system management tasks and options that you can select using the DMQ$MONITOR and DMQ$MGR_UTILITY utilities. Refer to corresponding sections for detailed information on listed features.
Table 10-1 lists DMQ$MONITOR options.
Table 10-1 DMQ$MONITOR System Management
|
Tasks |
Option to Use |
|---|---|
|
To display queue information: |
|
|
Display counts of messages sent, messages received and messages pending for attached queues |
D |
|
Display the same information for all configured queues |
D |
|
Continuously monitor queue states and counters |
D |
|
Display information about message queue quotas |
Q |
|
Display queue-specific information |
P |
|
Reset dynamic counts of number of messages received and messages sent since the last reset operation |
R |
|
To display group and network connection information: |
|
|
Display cross-group network message routing information. |
RT |
|
Re-establish lost cross-group connections |
C |
|
Display network transport communications links for a group |
LS |
|
Display detailed [inbound or outbound] link information |
LD |
|
To display group information: |
|
|
Display detailed group information |
GD |
|
Change to alternate group |
A |
|
Display system status and resource allocation statistics |
T |
|
Display failover availability for message groups |
LT |
|
To shut down a group: |
|
|
Shut down the group |
K |
Table 10-2 lists all major BEA MessageQ system management tasks you can perform using DMQ$MGR_UTILITY.
Table 10-2 DMQ$MGR_UTILITY System Management Tasks
|
Tasks |
Option to Use |
|---|---|
|
To control and display queues and processes: |
|
|
Display processes connected to a group, attached queues, and programs that run |
DS |
|
Display quotas and counters of an attached queue, along with PID, process name, and program image name of the process attached to the queue |
DQ |
|
Cause a process attached to BEA MessageQ to exit by invoking the SYS$FORCEX system service |
FR |
|
Flush all messages pending to an unattached queue |
QC |
|
Start or stop queues |
QC |
|
Display names in the group name space |
DG |
|
Start or stop Client Library Services |
CM |
|
To control event and error logging and tracing: |
|
|
Enable or disable tracing for a process attached to BEA MessageQ |
RO |
|
Redirect event, error logging, and/or trace output from a specific process to any of several targets, including a common event log, and the system console device |
RO |
|
Close the common event log file and open a new one |
LC |
|
To control message recovery journals: |
|
|
Open and close DQF and SAF streams |
JC |
|
Close a DLJ or PCJ stream and open a new one |
JC |
|
Enable or disable all recovery streams (DQF, SQF, DLJ, and PCJ) in a given group |
JC |
|
Show what recovery streams have messages in them and what files are associated with the streams |
JC |
|
Obtain a formatted dump of the contents of an inactive (closed) recovery stream |
JC |
|
Redirect a recovery stream associated with one queue to another target queue, either replacing the target stream, or merging with it |
JC |
|
To use the Link Management Subsystem to control cross-group network links: |
|
|
Shut down a network link to another BEA MessageQ group |
LM |
|
Start a network link to a BEA MessageQ group |
LM |
|
To use the Naming Agent Subsystem to manage names and namespaces |
|
|
Display information about names and namespaces |
NA |
|
Manage the association of names and addresses |
NA |
|
Remove names from the namespace |
NA |
Using the Monitor Utility (DMQ$MONITOR)
To run the Monitor utility, select Option 5 from the BEA MessageQ main menu.
The Monitor utility is used to monitor and control the BEA 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.
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 utility menu to display the current number of messages that are sent, received, or pending in a message queue.
The system prompts you to choose:
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). |
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 you to choose:
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). |
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 utility menu options.
The COM Server Specific Information screen displays the following information:
Displaying Queue-Specific Status
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):
Resetting COM Server Counters
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.
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.
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. SeeDefining Access Control on Queues in BEA MessageQ Security, 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 BEA MessageQ Main Menu and Utilities, on other ways to stop the COM Server.
Displaying Link Summary Information
Select Option LS from the Monitor utility menu to display link summary information. The system prompts you for the group number from which to start. This screen displays the status of DECnet and TCP/IP network communications links for each group.
Displaying Link Detail Information
Select Option LD from the Monitor utility menu to display detailed link information. The system asks you to choose:
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
Displaying Link Connect Table
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.
Displaying Group Detail Information
Select Option GD from the Monitor utility menu to display group detail information.
Resetting Cross-Group Connections
Select Option C from the Monitor utility menu to re-establish cross-group connections.
Use this option if network communications links between the groups were lost and you want to re-establish all cross-group connections.
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 is valid only for message server systems; it is not available for client implementations.
Using the System Management Utility (DMQ$MGR_UTILITY)
The DMQ$MGR_UTILITY program provides a collection of menu-driven services that manage and control several BEA MessageQ subsystems.
To run this utility, select Option 7 from the BEA MessageQ main menu.
Displaying Queue Summary Information
Select Option DS from the Manager utility menu to display summary level information about queues.
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.
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.
Stopping Queues
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. After 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 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. After 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.
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.
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.
Redirecting Status and Trace Output
Error and status logging in BEA MessageQ for OpenVMS can be enabled or disabled by using:
Enabling Tracing Prior to Starting a Program
To enable tracing prior to starting a user or sender program, set either one or both of the following logicals:
Turns on the BEA MessageQ call tracing.
Turns on the service-specific tracing for a BEA 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 valid:
|
Target |
Description |
|
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 |
|
MEM_LOG |
In-memory ring buffer |
|
NONE |
No trace output sent |
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 BEA MessageQ Servers by modifiying the DCL command procedure DMQ$USER:DMQ$SET_SERVER_LOGICALS.COM. See Listing 10-1.
Listing 10-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 = ""
Enabling Tracing When a Program is Running
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 Managing a BEA MessageQ Environment, for more information on separating error logging streams to isolate system problems.
Event Logging
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, USER_LOG, MEM_LOG, or NONE. These streams are assigned by logical names, with defaults provided by BEA MessageQ. They can be dynamically redirected from the Redirect Status/Trace Switch option.
Directing Error and Status Messages Prior to Starting a Program
Two separate classes of events can be logged by a process connected to BEA 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 targets that DMQ$TRACE_OUTPUT can be set to: EVL_LOG, CONSOLE, SYSOUT, SYSERR, USER_LOG, MEM_LOG, or NONE. 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.
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 Redirecting Status and Trace Output for more information. Note that the RO option prompts you to set values for the DMQ$PROCESS_OUTPUT and DMQ$GROUP_OUTPUT logical names.
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 BEA MessageQ events. All entries are time-stamped.
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 BEA MessageQ problems that are time-related.
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 Managing a BEA MessageQ Environment, for more information on system troubleshooting.
Displaying Group Name Table
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.
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.
BEA MessageQ provides the following journal files:
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 Configuring Message Recovery, for detailed information on the BEA MessageQ message recovery system and journal files.
Managing DQF and SAF Journals
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 Managing Failover, for more information on Merge and Redirect options.
|
[Open] |
Opens the DQF or SAF journal for a group and queue. |
|
[Close] |
Closes the DQF or SAF journal. Note: When a DQF or SAF journal is closed, inbound traffic for the journal is rejected and the UMA forced. The journal must be reopened to accept the traffic. |
|
[Delete] |
Deletes the DQF or SAF journal associated with the queue. |
|
[Merge] |
Transfers and merges the contents of a DQF or SAF journal to another DQF or SAF journal. Used during a failover. |
|
[Dump] |
Performs a formatted dump of a DQF or SAF journal file. |
|
[Directory] |
Displays a directory of DQF or SAF journal files. |
|
[Redirect] |
Redirects recoverable data stream and opens a DQF or SAF journal at another group. Used during a failover. |
Managing DLJ and PCJ Journals
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. |
Managing the Naming Agent and the Namespace
Naming provides the ability to separate application processing from configuration details by allowing applications to refer to queues by name. The Naming Agent accesses and manages the BEA MessageQ bus-wide namespace. A namespace is the repository where names and their associated queue addresses are stored.
Select Option NA from the Manager utility menu to display the Naming Agent menu, as shown in Listing 10-2. This menu allows you to control all Naming Agent functions. Each option first asks for a group number associated with the Naming Agent server. Enter 0 for the local group (the default value), or enter a number from 1 to 32000 that corresponds to a message queuing group. The message queuing group that runs the Naming Agent must be identified in the %NAM section of the group initialization file.
Listing 10-2 Naming Agent Menu
Bus:1 Group:1 MessageQ Manager Utility Mon Nov 22 17:21:25 1999
Naming Agent Management - Choose a function type
LA - List All Entries PA - Show Path
SA - Set Address ZA - Zero Address
GE - Get Entry DE - Delete Entry
EX - Exit Naming Agent Management
Enter function :
The following sections describe the individual naming agent management functions. For the purposes of these examples, the %GNT section of the DMQ$INIT.TXT file is specified as shown in Listing 10-3.
Listing 10-3 Group Name Table Section of DMQ$INIT.TXT File
%GNT ********* Group Name Table Section *********************
*
* Queue Name Group.Queue Scope
*------------------------------ ---------- -----
GLOBAL_QUEUE1 1.234 G
*
%EOS
Displaying Information About Names and the Namespace
Select Option LA from the Naming Agent Management menu to list all the name entries in the name space that match the search criteria. The system prompts for a group number assocated with the Naming Agent. The system prompts you for search criteria. The default is an asterisk (*), which is a wildcard character and results in a list of all entries in the namespace. You can also enter a specific name or portion of a name, including a wildcard. Listing 10-4 shows the List All Entries function.
Listing 10-4 List All Entries Function
Bus:44 Group:42 MessageQ Manager Utility Tue Dec 14 15:30:56 1999
Naming Agent Management - Choose a function type
LA - List All Entries PA - Show Path
SA - Set Address ZA - Zero Address
GE - Get Entry DE - Delete Entry
EX - Exit Naming Agent Management
Enter function : LA
Enter NA Group (def=0, local):
Enter List Search (def=*) :
GLOBAL_QUEUE1
<CR> to continue:
Select Option GE from the Naming Agent Management menu to display information about a specific name. The system prompts you for an entry name. Listing 10-5 shows the Get Entry function.
Listing 10-5 Get Entry Function
Bus:44 Group:42 MessageQ Manager Utility Tue Dec 14 15:30:56 1999
Naming Agent Management - Choose a function type
LA - List All Entries PA - Show Path
SA - Set Address ZA - Zero Address
GE - Get Entry DE - Delete Entry
EX - Exit Naming Agent Management
Enter function : GE
Enter NA Group (def=0, local):
Enter Entry name (def=back) : GLOBAL_QUEUE1
Name : /DMQ$DISK/DMQ$V50/DMQNS/GLOBAL_QUEUE1
Address : 1.234
Time last modified : Tue Dec 14 15:27:55 1999
<CR> to continue:
Select Option PA from the Naming Agent Management menu to display the namespace path. Listing 10-6 shows the Show Path function.
Listing 10-6 Show Path Function
Bus:44 Group:42 MessageQ Manager Utility Tue Dec 14 15:30:56 1999
Naming Agent Management - Choose a function type
LA - List All Entries PA - Show Path
SA - Set Address ZA - Zero Address
GE - Get Entry DE - Delete Entry
EX - Exit Naming Agent Management
Enter function : PA
Path is : /DMQNS/
<CR> to continue:
Managing Address and Name Associations
Select Option ZA from the Naming Agent Management menu to clear an address associated with a name. The system prompts you for an entry name for which the address is to be cleared. Listing 10-7 shows the Zero Address function.
Listing 10-7 Zero Address Function
Bus:44 Group:42 MessageQ Manager Utility Tue Dec 14 15:30:56 1999
Naming Agent Management - Choose a function type
LA - List All Entries PA - Show Path
SA - Set Address ZA - Zero Address
GE - Get Entry DE - Delete Entry
EX - Exit Naming Agent Management
Enter function : ZA
Enter NA Group (def=0, local):
Enter Entry name (def=back) : GLOBAL_QUEUE1
<CR> to continue:
Select Option SA from the Naming Agent Management menu to associate an address (group.queue) with a name. The system prompts you for an entry name and an address to be associated with the name. Listing 10-8 shows the Set Address function.
Listing 10-8 Set Address Function
Bus:44 Group:42 MessageQ Manager Utility Tue Dec 14 15:30:56 1999
Naming Agent Management - Choose a function type
LA - List All Entries PA - Show Path
SA - Set Address ZA - Zero Address
GE - Get Entry DE - Delete Entry
EX - Exit Naming Agent Management
Enter function : SA
Enter NA Group (def=0, local):
Enter Entry name (def=back) : GLOBAL_QUEUE1
Enter Address (group.queue) : 543.210
<CR> to continue:
Removing Names from the Namespace
Select Option DE from the Naming Agent Management menu to delete a specified name from the namespace. The system prompts for the name to be deleted from the namespace.
Listing 10-9 Delete Entry Function
Bus:44 Group:42 MessageQ Manager Utility Tue Dec 14 15:30:56 1999
Naming Agent Management - Choose a function type
LA - List All Entries PA - Show Path
SA - Set Address ZA - Zero Address
GE - Get Entry DE - Delete Entry
EX - Exit Naming Agent Management
Enter function : DE
Enter NA Group (def=0, local):
Enter Entry name (def=back) : GLOBAL_QUEUE1
<CR> to continue:
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|