BEA MessageQ Main Menu and Utilities

 

The BEA MessageQ main menu enables you to run various management and configuration functions as well as restart and shut down the COM Server.

The following topics are covered in this chapter:

• Using the BEA MessageQ Main Menu

• Running the IVP

• Starting and Shutting Down the COM Server

• Verifying Buffer Pool Configuration (DMQ$LLS_VERIFY)

• Testing BEA MessageQ Communications with DMQ$LOOP

• Testing BEA MessageQ Services with DMQ$TEST

• Running the CUSTOMIZE Command Procedure

• Running the DMQ$LOADER Utility

• Changing Bus and Group Numbers

• Shutting Down BEA MessageQ

  Note: The DMQ$MGR_UTILITY and DMQ$MONITOR utilities are described in Using BEA MessageQ System Management Utilities.

Using the BEA MessageQ Main Menu

The BEA MessageQ main menu provides access to many BEA MessageQ command procedures and utilities. Before you access the BEA MessageQ main menu, make sure that you run the DMQ$SET_LNM_TABLE command procedure to connect to the group's environment.

After you start a BEA MessageQ group, invoke the BEA MessageQ main menu by entering the following commands:

$ DMQ:==@DMQ$EXE:DMQ$MENU 
$ DMQ 

BEA MessageQ displays the main menu. Table 9-1 describes each BEA MessageQ main menu option and indicates where to find more information about each option.

Table 9-1 BEA MessageQMain Menu Options

Option	Name	Description
1	Run IVP	Executes the Installation Verification Procedure. See Running the IVP and the BEA MessageQ Installation Guide for OpenVMS.
2	Restart/Shutdown DMQ$COM_SERVER	Starts up or shuts down a group's BEA MessageQ Servers. See Starting and Shutting Down the COM Server and Defining the Message Queuing Environment.
3	Run LLS_VERIFY	Displays information about queues containing pending messages. See Verifying Buffer Pool Configuration (DMQ$LLS_VERIFY).
4	Run LOOP	Performs a loopback of messages to test communication. See Testing BEA MessageQ Communications with DMQ$LOOP.
5	Run MONITOR	Monitors and controls BEA MessageQ communications. See Using BEA MessageQ System Management Utilities.
6	Run TEST	Sends and receives test messages. See Testing BEA MessageQ Services with DMQ$TEST.
7	Run MGR_UTILITY	Displays queue information, flush a queue, force a process to exit, and display the group name table, as well as recovery journal management, logging and tracing control. See Using BEA MessageQ System Management Utilities.
8	Run PSSVFY	Verifies that a BEA MessageQ script is syntactically correct. See the BEA MessageQ Programmer's Guide.
9	@CUSTOMIZE procedure	Changes the system configuration by editing the DMQ$BOOT.COM, DMQ$INIT.TXT, or DMQ$TYPCLS.TXT file. See Running the CUSTOMIZE Command Procedure.
10	Run LOADER	Adds a new name string, a new group, or changes the address associated with a named object. See Running the DMQ$LOADER Utility.
11	Change Bus and Group numbers	Changes BEA MessageQ bus and group number for your process. See Changing Bus and Group Numbers.

Running the IVP

Select Option 1 on the main menu to perform the Installation Verification Procedure (IVP). You may run IVP to verify whether the BEA MessageQ software is functioning properly on your system.

Starting and Shutting Down the COM Server

Select Option 2 on the main menu to restart or shut down the DMQ$COM_SERVER process. The system displays the following prompts:

Startup  DMQ_C_001500001 [Y/N] (N): 
Shutdown DMQ_C_001500001 [Y/N] (N): 
The default is NO. To perform either a BEA MessageQ startup or shutdown, enter Y. 

Note: Refer to Shutting Down BEA MessageQ for more information on the shutdown process.

Verifying Buffer Pool Configuration (DMQ$LLS_VERIFY)

The DMQ$LLS_VERIFY utility maps a message queuing group's buffer pool configuration and verifies the consistency of data structures for the global section. It validates the configuration specified in the Buffer Pool Configuration Table of the DMQ$INIT.TXT file.

To use this utility, select Option 3 on the main menu.

Testing BEA MessageQ Communications with DMQ$LOOP

The DMQ$LOOP utility tests message queuing bus communications by performing a loopback of messages, for both local and cross-group communications. This is a quick test to see if, and at what rate, messages of a specified size can be exchanged.

Note: The DMQ$LOOP utility can only be used with other local and cross-group OpenVMS groups. This utility is not supported for testing cross-group communications with groups on UNIX or Windows NT systems.

Note: When running DMQ$LOOP, large messages can fail if the screen queue quota on the OpenVMS system is too small.

Running DMQ$LOOP

When running this utility, you perform the following steps:

1. Select Option 4 from the BEA MessageQ main menu to run DMQ$LOOP.

2. Select L from the menu to perform the local loopback test. The system prompts you for the following data entry:

   Message length (range 8:128000)? 
   Number of messages? 

   When you enter the data, a statistical data screen is displayed. Press Return to continue.

3. Select X from the menu to perform the cross-group loopback tests. The system prompts for the following data entry:

   Enter Target Group:  1 
   Enter RCVW timeout [D:100]:  
   Message length (range 8:128000)?  
   Number of messages? 

   When you enter the data, an X-Group loop test statistics screen is displayed.

4. Select V from the menu to suppress (or activate) data verification. Data verification is generally ON. When you first select this option, the Data Verification switch changes from ON to OFF. The next time, it will be toggled to ON again.

   Note: Use the data verification option to control writing and checking of a data pattern within each message. With small messages, this overhead is insignificant, however, if the message size increases, the overhead may become a large percentage of the cost of sending a message.

Testing BEA MessageQ Services with DMQ$TEST

The DMQ$TEST utility tests BEA MessageQ API routines. It allows you to define, send, and receive messages interactively while being attached to a permanent or temporary queue. It also supports generating messages from a script.

To use this utility, choose Option 6 from the BEA MessageQ main menu. At the prompt, enter configuration information to set up the test.

Running the CUSTOMIZE Command Procedure

Select Option 9 from the BEA MessageQ main menu to access the @CUSTOMIZE command procedure. The @CUSTOMIZE option allows you to access and edit the DMQ$BOOT.COM and DMQ$INIT.TXT files to customize your BEA MessageQ configuration. The previous versions of the files should not be purged until the new configuration files have been tested. Note that the default action is to purge the files.

Customization Options

The CUSTOMIZE options are:

• Edit the DMQ$BOOT.COM startup file [Y/N]

  Refer to About the DMQ$BOOT Command Procedure as well as Defining the Message Queuing Environment,and Configuring Message Queues and Global Memory, for more information on using the DMQ$BOOT.COM file.

• Edit the DMQ$SET_SERVER_LOGICALS.COM file [Y/N]

  Enter Y and press Return to change information in the server logical command procedure. Refer to Managing a BEA MessageQ Environment, for more information.

• Edit the DMQ$SET_SERVER_QUOTA .COM file [Y/N]

  Enter Y and press Return to change information in the server quota command procedure.

• Edit the DMQ$INIT.TXT file [Y/N]

  Refer to Sample DMQ$INIT.TXT File, for a sample of a complete DMQ$INIT.TXT file.

• Create language-specific PROCESS, GROUP include files [Y/N]

  Enter Y to create new include files for DMQ$INIT.TXT. The following messages are displayed:

  ... Translating DMQ$INIT.TXT to language include files.
   
  Translating for ADA
  Translating for BASIC
  Translating for BLISS
  Translating for C
  Translating for COBOL
  Translating for FORTRAN
  Translating for MACRO
  Translating for PASCAL
  Translating for PLI
  Inserting files into library

• Edit DMQ$TYPCLS.TXT for TYPE and CLASS [Y/N]

  Enter Y to add new classes and types. Refer to Sample DMQ$TYPCLS.TXT File, for the listing of all message types and class codes.

• Create language-specific TYPE_CLASS include files [Y/N]

  Enter Y if you have edited the DMQ$TYPCLS.TXT file. The system displays the following message:

  Translating DMQ$TYPCLS.TXT message class and type file into 
  ADA, BASIC, BLISS, C, COBOL, FORTRAN, MACRO, PASCAL and 
  PL/I.... 
   
  Inserting files into library... 
  Rebuild PAMScript symbols [Y/N] 
  Enter Y to customize the BEA MessageQ Script Facility to your present configuration. 
  The system displays the following message: 
  *This step takes from 1-30 minutes depending on system load, * 
  *processor type, and number of symbols in the files.         * 
   
  Submit to batch [S], Run at terminal [T]... [S,T] (T): 

• Execute the customization procedure SYCUSTOMIZE.COM [Y/N] (N):

  Enter Y to complete BEA MessageQ customization. Then press Return to return to the main menu.

  SYCUSTOMIZE.COM can be modified to archive these 
  changed modules: 
                DMQ$BOOT.COM 
                DMQ$INIT.TXT 
                DMQ$TYPCLS.TXT 
   
     9-OCT-1999 14:20:24 
   
     <CR> to continue:  

About the DMQ$BOOT Command Procedure

For each BEA MessageQ message queuing group, you can modify the DMQ$BOOT command procedure either by using option 10 (@CUSTOMIZE) or editing the DMQ$STARTUP procedure.

Use the logicals defined in DMQ$BOOT to do the following:

• Configure a group to share configuration files with another group.

• Redirect the location of MRS files by defining the logical DMQ$MRS to point to a different directory.

• Redirect output of BEA MessageQ console messages to a specific destination.

• Define the TCP/IP product that is used by the Link drivers and the Client Library Server.

Refer to Defining the Message Queuing Environment, for more information on the DMQ$BOOT.COM procedure.

About the DMQ$INIT.TXT File

The DMQ$INIT.TXT file contains nine sections that you must customize for each group. Each section begins with a percent sign (%) following the name or an abbreviation for the name of the section. Refer to Defining the Message Queuing Environment, for instructions on how to customize the group initialization file.

About the DMQ$TYPCLS.TXT File

BEA MessageQ software customization includes defining the symbolic names for type and class codes within BEA MessageQ application programs and the BEA MessageQ script facility. The DMQ$TYPCLS.TXT file contains symbolic definitions of type and class codes.

See Creating Global Names, for more information on how to edit this file.

Running the DMQ$LOADER Utility

You can dynamically reload the DMQ$INIT.TXT file at any time, without stopping BEA MessageQ, by running the program DMQ$EXE:DMQ$LOADER.EXE. Refer to Changing Parameters in the Running Group in Defining the Message Queuing Environment, for information on changing parameters in a running group.

Starting the LOADER Utility

Select Option 10 on the main menu to start the LOADER utility.

Restrictions on DMQ$LOADER

Note the following restrictions when using DMQ$LOADER:

• DMQ$LOADER supports only add and modify operations, but not deletes. DMQ$LOADER has no delete capability, but allows a symbol to be set to a null value (0).

• Changes to the %BUFFER, %MRS, or %SBS Server initialization sections require that the group be restarted before changes take effect.

Changing Bus and Group Numbers

Select Option 11 to change BEA MessageQ buses and groups on your process.

The following is an example of the prompt the system may display (for Bus 15):

Enter Bus ID to change to [0015] [? for list]: 
 
Enter Group ID to change to [? for list]: 

Enter a question mark (?) to display the list of existing LNM tables for the node.

Shutting Down BEA MessageQ

Use Option 2 to select the COM Server shutdown command. The system displays:

Startup  DMQ_C_001500001 [Y/N] (N): 
Shutdown DMQ_C_001500001 [Y/N] (N): 

At the Shutdown DMQ_ prompt, enter Y.

Do not use the DCL command STOP to stop the COM Server.

When BEA MessageQ shuts down, it performs the following tasks:

• The exit handler forces all attached processes to exit.

• The exit handler ensures that global sections are deleted.

• On exiting, the COM Server sets a bit to cause other processes to exit when the global sections are accessed.

• The SYS$OUTPUT device for the attached process displays this message:

  %PAMS-F-PAMSDOWN, This MessageQ
   group is down - 
             COM Server has exited