BEA MessageQ
Installation and Configuration Guide for OpenVMS

In general, client applications are not aware that permanent queues are configured as unowned secondary queues instead of primary queues. All message queuing operations, including Message Recovery Services, work the same way.

9.5.1 Attach Errors to Undefined Queues

Using a multithreaded CLS, client applications attempting to attach to permanent queues that are not defined in the Queue Configuration Table, receive the return status value of PAMS__NOTSECONDARYQ, (--270). Since the client specified a queue type parameter of PSYM_ATTACH_PQ, the error is inconsistent. This is due to the queue type mapping performed by multithreaded CLS. However, it indicates that the queue must be defined as an unowned secondary queue in the Queue Configuration Table.

9.6 Starting and Stopping CLS Manually

For convenience and ease of application management, CLS Servers are normally started from the CLS Configuration Table when a MessageQ group starts. CLS Servers also are stopped when the MessageQ group is shutdown. There are circumstances when new CLS Servers need to be started without impacting the entire MessageQ group.

9.6.1 Starting CLS from the Manager Utility

A CLS Server process can also be started from the Manager Utility, Remote Client Management menu, Start Service function (Example 9-4 ). The service must already be defined in the %CLS section of the group initialization file. If the service is not defined in the group initialization file, then modify the initialization file to add the new service and then run the loader again using the following command:

$RUN DMQ$EXE:DMQ$LOADER.EXE

Example 9-3 Manager Utility Remote Client Management Menu

 
 
Bus:99  Group:40  MessageQ Manager Utility  Thu Jan  8 15:28:37 1998 
 
           Remote ClientLib Controls  - Choose the function type 
 
           SS  - Start Service            KS  - Stop Service 
 
           EX  - Exit Remote ClientLib Controls 
 
 
 
           Enter option: 
   
 

Example 9-4 Starting CLS from Remote Client Management Menu

 
 
Bus:99  Group:40   MessageQ Manager Utility  Thu Jan  8 15:33:29 1998 
 
      Endpoint     Transport 
 
       5001       TCPIP 
       6000       DECNET 
 
 
   Enter end point number: 5001 
 
   Successfully started CLS Endpoint:5001, Transport:TCPIP 
<CR> to continue: 
 
 

The DCL command procedure, DMQ$CLS_START.COM, is available in DMQ$EXE as a way to start additional CLS Servers while a MessageQ is already running. Client Library Server processes can be stopped and started without impacting the MessageQ group. However, stopping a CLS process impacts all clients currently connected to that server.

To execute the DMQ$CLS_START.COM command procedure, enter

$ @DMQ$EXE:DMQ$CLS_START

This command procedure takes the following parameters:

 
$ @DMQ$EXE:DMQ$CLS_START <endpt> <transport> <max clients> 
 

where

• Endpt = endpoint
• Transport = TCPIP or DECNET
• Maximum clients = 1 sets the Single-Client mode

Examples of CLS_START parameters:

@DMQ$EXE:DMQ$CLS_START 5000 TCPIP 25 
@DMQ$EXE:DMQ$CLS_START 5000 DECNET 25 
@DMQ$EXE:DMQ$CLS_START 5000 TCPIP 1 

DMQ$CLS_START uses the DMQ$EXE:DMQ$START_SERVER.COM command procedure to create a detached CLS Server process.

9.6.3 Stopping CLS from the Manager Utility

A CLS Server process can be stopped via the Manager Utility, Remote Client Management menu, Stop Service function (Example 9-5 ), or by using the Manager Utility, Force Process service (Example 9-6 ).

Example 9-5 Stopping CLS from Remote Client Management Menu

 
 
Bus:99  Group:40   MessageQ Manager Utility   Thu Jan  8 15:33:29 1998 
 
      Endpoint     Transport 
 
       5001       TCPIP 
       6000       DECNET 
 
 
   Enter end point number: 5001 
  Successfully stopped CLS Endpoint:5001, Transport:TCPIP 
<CR> to continue: 
 
 

Example 9-6 Stopping CLS from Force Process Menu

 
 
Bus:99   Group:40    MessageQ Manager Utility   Thu Jan  8 15:48:58 1998 
                            FORCEX Process 
 
Index  Process Name    State     PQ Name               #Queues  #Pending 
  1   DMQ_N_009900040        NA_SERVER                      1        0 
  2   DMQ_M_009900040        MRS_SERVER                     1        0 
  3   DMQ_S_009900040        SBS_SERVER                     1        0 
  4   DMQ_C_009900040        COM_SERVER                     1        0 
  5   DMQ_T_009900040        TCPIP_LD                       1        0 
  6   DMQ_D_009900040        DECNET_LD                      1        0 
  7   DMQ_L_009900040        EVENT_LOGGER                   1        0 
  8   DMQ_J_009900040        JRN_SERVER                     1        0 
  9   DMQ_CLS_T_5001         +DMQ_CLS_T_5001_203            1        0 
 10   DMQ_CLS_D_6000         +DMQ_CLS_D_6000_204            1        0 
 11   _FTA30:                +_FTA30:_205                   1        0 
[End] 
      
Index of process to be stopped? [1 - 11]: 
 
      
 
 

The Client Library Server event logging is integrated with the MessageQ for OpenVMS Event Logger process. CLS Server initialization and client connect/disconnect events are logged to the Event Logger.

The Client Library Server also supports trace output utilized for more detailed information about client activity. The CLS trace output displays information about the MessageQ API calls executed by CLS on behalf of client applications.

The CLS event log and trace output can be directed to the common event log, to the console, or to separate files. See Chapter 11 for more information on using the MessageQ Event Log facility.

Part III contains the following information:

Chapter	Describes...
10	The MessageQ Main Menu, its major options and features.
11	The MessageQ system management and monitoring utilities.
12	How to tune MessageQ software to support your application.
13	Steps for troubleshooting MessageQ problems.
14	MessageQ security features.
15	How to perform failover for a message queuing group.

The 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 MessageQ Main Menu
• Starting and Shutting Down the COM Server
• Testing MessageQ Communications with DMQ$LOOP
• Testing MessageQ Services with DMQ$TEST
• Running the CUSTOMIZE Command Procedure
• Changing Bus and Group Numbers
• Shutting Down MessageQ

Note:

The DMQ$MGR_UTILITY and DMQ$MONITOR utilities are described in Chapter 11 .

The MessageQ main menu provides access to many MessageQ command procedures and utilities. Before you access the 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 MessageQ group, invoke the MessageQ main menu by entering the following commands:

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

MessageQ displays the main menu.

Table 10-1 describes each MessageQ main menu option and indicates where to find more information about each option.

.

Table 10-1 MessageQMain Menu Options

Option	Name	Use option to...
1	Run IVP	Execute the Installation Verification Procedure. See Section 10.3 and Chapter 2 .
2	Restart/Shutdown DMQ$COM_SERVER	Start up or shut down a group's MessageQ Servers. See Section 10.4 and Chapter 3 .
3	Run LLS_VERIFY	Display information about queues containing pending messages. See Section 10.5 .
4	Run LOOP	Perform a loopback of messages to test communication. See Section 10.6 .
5	Run MONITOR	Monitor and control MessageQ communications. See Chapter 11 .
6	Run TEST	Send and receive test messages. See Section 10.7 .
7	Run MGR_UTILITY	Display 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 Chapter 11 .
8	Run PSSVFY	Verify that a MessageQ script is syntactically correct. See the BEA MessageQ Programmer's Guide .
9	@CUSTOMIZE procedure	Change the system configuration by editing the DMQ$BOOT.COM, DMQ$INIT.TXT, or DMQ$TYPCLS.TXT file. See Section 10.8 .
10	Run LOADER	Add a new name string, a new group, or change the address associated with a named object. See Section 10.9
11	Change Bus and Group numbers	Change MessageQ bus and group number for your process. See Section 10.10 .

10.3 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 MessageQ software is functioning properly on your system.

10.4 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 MessageQ startup or shutdown, enter Y.

Note:

Refer to Section 10.11 for more information on the shutdown process.

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.

10.6 Testing 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 VMS groups. This utility is not supported for testing cross-group communications with groups on Unix or Windows NT systems.

When running this utility, you do the following:

Select DMQ$LOOP

Select Option 4 from the MessageQ main menu.

Execute Local Loopback Test

To perform the local loopback test, select L from the menu.
The system prompts you for the following data entry:

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

When you enter the data, a statistical data screen will be displayed.

Press Return to continue.

Execute Cross-Group Loopback Test

To perform the cross-group loopback tests, select X from the menu. The system prompts for the following data entry:

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

This type of data will produce an X-Group loop test statistics screen.

Select Data Verification

To suppress (or activate) the data verification, select V from the menu.

Usually, the the data verification is ON. When you select this option, the DATA VERIFICATION switch changes from ON to OFF. The next time, it will be toggled to ON again.

Note:

Use this option to control writing and checking of a data pattern within each message. Please note that with small messages, this overhead is insignificant. However, with the message size increase, the overhead may become a large percentage of the cost of sending a message.

The DMQ$TEST utility tests 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 MessageQ main menu. The system prompts you to enter configuration information to set up the test, after which you can perform the testing.

10.8 Running the CUSTOMIZE Command Procedure

Select Option 9 from the 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 MessageQ configuration.

10.8.1 Customization Options

The CUSTOMIZE options are:

• Edit the DMQ$BOOT.COM startup file [Y/N]
  Refer to Section 10.8.2 as well as Chapter 3 and Chapter 5 for more information on the use of 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 Chapter 13 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 Appendix A 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 Appendix B 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 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 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-1996 14:20:24 
   
     <CR> to continue: 
   
  

  10.8.2 About the DMQ$BOOT Command Procedure

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

  The logicals defined in DMQ$BOOT allow you 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 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 Chapter 3 for more information on the DMQ$BOOT.COM procedure.

  10.8.3 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 (%) and the name or an abbreviation for the name of the section. Refer to Chapter 3 on how to customize the group initialization file.

  10.8.4 About the DMQ$TYPCLS.TXT File

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

  See Chapter 8 for more information on how to edit this file.

  10.9 Running the DMQ$LOADER Utility

  You can dynamically reload the DMQ$INIT.TXT file at any time, without stopping MessageQ , by running the program DMQ$EXE:DMQ$LOADER.EXE. Refer to Section 3.4.3 for information on changing parameters in a running group.

  10.9.1 Starting the LOADER Utility

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

  10.9.2 Restrictions on DMQ$LOADER

  Be aware of 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 modifications take effect.

  10.10 Changing Bus and Group Numbers

  Select Option 11 to change 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]: 
  

  The "?" prompt allows you to display the list of existing LNM tables for the node.

  10.11 Shutting Down 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.

  When MessageQ shuts down MessageQ , 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 
    

  ---

  Note:

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

  ---

  ---

  Chapter 11
  Using MessageQ System Management Utilities

  11.1 Overview

  This chapter describes two MessageQ utility programs that can be used to perform system management tasks and to monitor MessageQ system status.

  • Using the Monitor Utility (DMQ$MONITOR)
  • Using the System Management Utility (DMQ$MGR_UTILITY)

  The DMQ$MGR_UTILITY and DMQ$MONITOR utilities require that the MessageQ environment variables be defined and accessible to the user. This can be accomplished with the DMQ$STARTUP.COM command procedure.

  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 MessageQ main menu.

  11.2 Major System Management Tasks

  Table 11-1 and Table 11-2 list major MessageQ system management tasks that you can perform using the DMQ$MONITOR and DMQ$MGR_UTILITY utilities. Refer to corresponding sections for detailed information in listed features.

  Table 11-1 lists DMQ$MONITOR features.

  Table 11-1 DMQ$MONITOR System Management Tasks

  Tasks
  Displaying Queue Information: ||
  	Display counts of messages-sent, messages-received and messages-pending for attached queues	Option D
  	Display the same information for all configured queues	Option D
  	Continuously monitor queue states and counters	Option D
  	Display information about message queue quotas	Option Q
  	Display queue-specific information	Option P
  	Reset dynamic counts of number of messages-received and messages-sent since the last reset operation	Option R
  Displaying Group and Network Connection Information: ||
  	Display cross-group network message routing information	Option RT
  	Reestablish lost cross-group connections	Option C
  	Display network transport communications links for a group	Option LS
  	Display detailed [inbound or outbound] link information	Option LD
  Displaying Group Information: ||
  	Display detailed group information	Option GD
  	Change to alternate group	Option A
  	Display system status and resource allocation statistics	Option T
  	Display failover availability for message groups	Option LT
  Shutting Down a Group: ||
  	Shut down the group	Option K

  Table 11-2 lists all major MessageQ system management tasks you can perform using DMQ$MGR_UTILITY.

  Table 11-2 DMQ$MGR_UTILITY System Management Tasks

  Tasks
  Controlling and Displaying Queues and Processes: ||
  	Display processes connected to a group, attached queues, and programs that run	Option 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	Option DQ
  	Cause a process attached to MessageQ to exit by invoking the SYS$FORCEX system service	Option FR
  	Flush all messages pending to an unattached queue	Option QC
  	Start or Stop Queues	Option QC
  	Display names in the group name space	Option DG
  	Start or Stop Client Library Services	Option CM
  Controlling Event and Error Logging and Tracing: ||
  	Enable or disable tracing for a process attached to MessageQ	Option 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	Option RO
  	Close the common event log file and open a new one	Option LC
  Controlling Message Recovery Journals: ||
  	Open and close DQF and SAF streams	Option JC
  	Close a DLJ or PCJ stream and open a new one	Option JC
  	Enable or disable all recovery streams (DQF, SQF, DLJ, and PCJ) in a given group	Option JC
  	Show what recovery streams have messages in them and what files are associated with the streams	Option JC
  	Obtain a formatted dump of the contents of an inactive (closed) recovery stream	Option JC
  	Redirect a recovery stream associated with one queue to another target queue, either replacing the target stream, or merging with it	Option JC
  Using Link Management Subsystem to Control Cross-Group Network Links: ||
  	Shut down a network link to another MessageQ group	Option LM
  	Start a network link to a MessageQ group	Option LM

  11.3 Using the Monitor Utility (DMQ$MONITOR)

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

  ---

  Previous | Next | Contents