Configuring MessageQ

 

This chapter contains the following topics that describe how to configure MessageQ message queuing buses and groups:

• Overview of MessageQ Configuration

• Configuring a Message Queuing Group

• Defining Parameters in the Group Initialization File

• Using the Test Utility to Test Your Group Configuration

If you have not already adjusted your system resources to support MessageQ software, use the information in Chapter 2 to configure your system resources, then rebuild and reboot the kernel.

Overview of MessageQ Configuration

Before applications can exchange information, you must configure the MessageQ environment by defining the default values and parameter settings for the following components:

• Message queuing bus

• Message queuing groups

• Message queues

• Naming

• Cross-group connections

• Server Processes

Figure 3-1 shows a sample MessageQ configuration. The configuration shows a message queuing bus that contains two message queuing groups, one on a Digital UNIX system and the other on a Windows NT system. Both groups are able to exchange messages using a cross-group connection. Each application is associated with at least one primary message queue and utilizes the services of several MessageQ Servers such as the recoverable messaging (MRS) and journalling (JRN) server, message broadcasting (SBS), and Client Library support (CLS).

Figure 3-1 Sample MessageQ Configuration

The following topics describe the standard components of a MessageQ configuration.

Message Queuing Bus

The MessageQ message queuing bus is the backbone of MessageQ because it forms the interprocess communication highway that applications use to send and receive messages. The message queuing bus is made up of one or more message queuing groups that are configured to communicate with each other.

Note: Aside from assigning a bus ID when you configure each message queuing group, there are no configuration steps you need to perform to configure the message queuing bus. MessageQ for UNIX automatically creates the bus when you enter the dmqstartup command to start a message queuing group (see the Starting a Message Queuing Group topic in Chapter 4 for more information).

Message Queuing Groups

A MessageQ message queuing group is a collection of related processes that share system resources. A single group must reside on a single system; however, a single system can support multiple groups. Applications that manage common resources or have frequent or high-volume communications with each other should be placed in the same group.

A group connects related applications or components of the same application. Communication between groups on the same system and between applications running in different message queuing groups on different systems requires that a computer network be configured (see the Configuring the Network topic in Chapter 1 for more information).

Groups are labeled with a four-digit bus ID and a five-digit group ID. Groups with the same bus ID form a message queuing bus; only groups that share a bus ID can communicate. The MessageQ startup procedure (dmqstartup) automatically creates the resources required for a group using the values and settings in the group initialization file. Message queuing groups are started by the startup procedure.

Message Queues

A message queue provides an area for an application to store and retrieve messages. Message queues can be thought of as attachment points on the message queuing bus. Each message queue is identified by a queue address. The group ID and a unique queue number form the queue address for each message queuing group.

MessageQ offers two types of queues: temporary and permanent:

• Temporary queues are created by MessageQ at runtime when they are requested using the pams_attach_q function. Applications use temporary queues when the need for the queue is short-lived.

• Permanent queues must be defined in the group initialization file. Permanent queues can become active when the group starts or when an application attaches. Applications use permanent queues when there is an ongoing need for the queue to service the application and when applications need to refer to the queue by name or number.

After you have selected the type of queue to use, you must set the following attributes of the queue:

• Primary or secondary

• Single reader or multireader

• Active on attach or permanently active

Each process that attaches to the MessageQ message queuing bus must have a primary queue assigned to it. This queue functions as the "main mailbox" for receiving messages from other processes using MessageQ. In addition, MessageQ applications can use secondary queues as a means of exchanging information among application components without interrupting the flow of messages taking place in the primary queue. In this way, secondary queues are used by application processes as alternate "mailboxes" for selected application messages.

Applications can be designed to read messages from one or more queues. Queues defined to be read by a single program are called single reader queues. When a process attaches to a single reader queue, it owns the queue and is the only process that can read from the queue. Queues that are designed to be read by multiple applications are called multireader queues (MRQs). MRQs are used to store messages that can be read by many simultaneous readers, creating a central "mailbox" for several applications or application components to receive messages. Only permanent queues can be defined as MRQs. In addition, MRQs must have the attribute permanently active.

When defining permanent queues in the group initialization file, you have the choice of determining whether the queue becomes active when a process attaches to the queue or if the queue is active when the group starts up regardless of whether any process is attached. If the queue is configured as permanently active, processes can insert messages into the queue even if it is not currently attached by a client process.

Applications must be associated with at least one message queue to receive MessageQ messages. For example, a system designer may designate queue 3 in group number 1 to receive temperature readings from a semiconductor furnace. After the bus, group, and queue have been configured and the group is started, the sender program must know the queue address to direct messages containing temperature readings. The receiver program must know the queue address from which to read messages about temperature changes in the furnace.

Applications also can send and receive messages from message queues in one or more message queuing groups. The application designer decides how to distribute messaging based on the requirements of the application.

Naming

Naming is a MessageQ capability that enables applications to refer to queues by name instead of using their physical address in the MessageQ configuration. Using names separates applications from the specifics of the network environment and enables system managers to make configuration changes without requiring developers to change the applications. Developers use the pams_locate_q function to locate the queue address for a queue name at runtime. Currently, the MessageQ naming capability applies only to queue names. There is no ability to assign a name to other MessageQ entities such as groups or buses.

Names can be defined to have a local or global scope. Local names are visible only to applications running in a particular group. Global names are available for use by any application attached to the message queuing bus.

Also, names can be defined using a static or dynamic approach. Static definition means that the definition of the name-to-queue address translation is provided in the Global Name Table (%GNT) section (see the Defining Name to Queue Translations in the Group Name Section topic for more information) of the MessageQ configuration file for the group. Dynamic definition means that an application has created a name-to-queue address translation using the pams_bind_q function and that MessageQ must look up the definition that has been created.

The MessageQ process that supports the global naming capability is called the Naming Agent. The Naming Agent stores the global name-to-queue address translations that were created using a static or dynamic approach. In addition, the Naming Agent provides the run-time lookup capability for global name-to-queue address translations requested using the pams_locate_q function.

When you configure a group, you must decide the message queuing group in which the naming agent will run. You can also define a backup naming agent group in the event that the first group becomes unavailable. This definition is set in the %NAM section (see the Configuring Global Naming topic for more information) of the group initialization file. The group that is assigned to run the naming agent starts the naming agent process at group startup.

Cross-Group Connections

Communication between groups requires the use of a network protocol. MessageQ for UNIX supports TCP/IP as a network protocol.

There are two types of cross-group connections: direct and indirect. Groups that share a physical network connection can be configured directly in the %XGROUP section of the group initialization file. Groups that do not share a physical network connection can be configured indirectly in the %ROUTE section of the group initialization file.

See the Enabling Network Connections in the Cross-Group Section topic and the Defining the Message Routing Database in the Route Section topic for instructions on how to configure direct and indirect cross-group connections.

You can also specify timeout intervals for testing cross-group connections. See the Defining Timeout Intervals for Link Drivers topic in Chapter 4 for more information.

Server Processes

MessageQ for UNIX provides several server processes that provide key features of MessageQ such as recoverable messaging, message broadcasting, cross-group communication, and message queuing support for MessageQ Clients. Figure 3-2 shows the server processes and other components of a MessageQ message queuing group.

Figure 3-2 Components of a MessageQ Message Queuing Group

The server processes can be enabled by setting values in the %PROFILE section of the group initialization file. Table 3-1 describes the server processes that are available to MessageQ for UNIX.

Table 3-1 MessageQ Server Processes

Server Process	Description
Selective Broadcasting Services (SBS) Server	Controls the broadcasting of data between an application and multiple receiving applications. In addition, the SBS server provides AVAIL/UNAVAIL message-based services.
Message Recovery Services (MRS)/Journal (JRN) Server	Manages the disk storage required to handle recoverable message traffic. The MessageQ message recovery system guarantees message delivery if the system, network, or application fails. Messages designated as recoverable are directed to an MRS server for storage and removed from storage when delivery is confirmed by a user or another MRS server.
Naming Agent	Maintains the namespace for name-to-queue address translations and performs the runtime queue lookup when an application refers to a queue by name
Client Library Server (CLS)	Provides full message queuing support for MessageQ Clients.

For a complete description of MessageQ concepts and components, refer to the Introduction to Message Queuing documentation.

Configuring a Message Queuing Group

When configuring a message queuing group, you have two options:

• Let the dmqsetup utility configure the group for you by creating a standard group.

  For new MessageQ users or users who are configuring a new installation, the dmqsetup utility will help you quickly create a minimum message queuing group configuration to get MessageQ software up and running on your system in the shortest amount of time. For more information about the dmqsetup utility, see the Creating a Standard Group Configuration topic.

• Configure the group yourself.

  For users who want to create a custom configuration and understand the individual components of the group initialization file, see the Creating a Custom Group Configuration topic.

Creating a Standard Group Configuration

The dmqsetup utility lets you configure a standard group configuration and begin running MessageQ software on your system in the shortest time possible. The dmqsetup utility creates a standard, minimum configuration that uses default values and recommended parameter settings. This utility is ideal for users who have never performed a MessageQ group configuration, or for users who are considerably expanding an existing group configuration. The dmqsetup utility is installed with the product and can be found at the following location: /install_dir/util.

The dmqsetup utility is a write-only utility. That is, after you exit from the utility and write the group initialization file, you cannot later use dmqsetup to make changes to that file. However, you can make changes to the group configuration file using a text editor.

The main menu of the dmqsetup utility contains the following options:

1.   Profile
2.   Links
3.   Routes
4.   Queues
5.   Names
6.   Create standard group initialization
7.   Save
8.   Help
9.   Exit

To create a standard group configuration, follow these steps:

1. Invoke the dmqsetup utility:
   
   # dmqsetup
   MessageQ for UNIX: Setup
   1. Profile
   2. Links
   3. Routes
   4. Queues
   5. Names
   6. Create standard group initialization
   7. Save
   8. Help
   9. Exit

2. Create a standard group initialization file by entering option 6.
   
   * Enter selection (1-9) [6]

3. Enter the name of the group, the group ID, and the node name.
   
   * Enter group name [GROUP1] ?
   * Enter group id (1-32000) [1] ?
   * Enter the node name [chopin] ?
   Standard group initialization has been created.

4. The standard group configuration has been created.
   Save by selecting 7.
   
   MessageQ for UNIX: Setup
   1. Profile
   2. Links
   3. Routes
   4. Queues
   5. Names
   6. Create standard group initialization
   7. Save
   8. Help
   9. Exit
   * Enter selection (1-9) [6] ? 7

5. Enter the name you want to give the group initialization file you just created, and confirm that you want to save the file.
   
   * Enter group initialization file name [mygroup.init] ?
   * Save group initialization in file mygroup.init [Y] ?
   Group initialization saved in file mygroup.init.

6. After you finish creating standard groups, exit from the dmqsetup utility.
   
   MessageQ for UNIX: Setup
   1. Profile
   2. Links
   3. Routes
   4. Queues
   5. Names
   6. Create standard group initialization
   7. Save
   8. Help
   9. Exit
   * Enter selection (1-9) [7] ? 9
   Bye.

A standard group has the following attributes:

• One template queue (Queue0) used as a template when temporary queues are created.

• 15 permanent queues.

• Five example queues used by the example programs provided in the MessageQ Example Programs installation subset.

• A DEAD_LETTER_QUEUE (Queue 96).

• A TCP/IP cross-group connection definition for the group. A standard group uses cross-group communications to exchange messages directly with other groups on nodes that share a network link. Note, however, that incoming TCP/IP connections will not be validated. See the XGROUP_VERIFY parameter in Table 3-3 for more information.

A standard group will not have Message Recovery Services (MRS) enabled, nor will it exchange messages with groups on nodes that do not share a network link. However, Selective Broadcast Services (SBS) will be enabled.

Creating a Custom Group Configuration

To enable you to configure groups to meet your specific messaging needs, MessageQ for UNIX systems provides a group initialization file template for each supported UNIX system. The system-specific templates can be found at the following location:

/install_dir/templates/group.init

Table 3-2 gives an overview of the sections of the group initialization file.

Table 3-2 Sections of the Group Initialization File

Section Header	Name	Description
%VERSION	Version	Identifies the group initialization file version. See the Default Values for Parameters topic for more information.
%PROFILE	Profile	Defines the basic parameters of a group. See the Defining Parameters in the Group Initialization File topic for more information.
%XGROUP	Cross-Group Communications	Enables groups on nodes that share a network link to directly exchange messages. This section should have an entry for the node on which the group is running. See the Enabling Network Connections in the Cross-Group Section topic for more information.
%ROUTE	Message Routing	Enables groups on nodes that do not share a network link to indirectly exchange messages. See the Enabling Network Connections in the Cross-Group Section topic for more information.
%CLS	Client Library Server	Enables the support of multiple MessageQ Client connections to a single UNIX process using TCP/IP transports. See the Configuring Client Library Server in the CLS Section topic for more information.
%BUFFER	Buffer Pool Configuration Table	Applies to OpenVMS systems only.
%QCT	Queue Configuration Table	Defines the permanent queues. See the Defining Queues in the Queue Configuration Section topic for more information.
%SBS	Selective Broadcast Services (SBS)	On OpenVMS systems, this section of the initialization file controls the operation of the local SBS server. On UNIX and Windows NT systems, the local SBS server is enabled by setting the parameter value to YES in the %PROFILE section. The SBS section is empty. See the Setting Group Characteristics in the Profile Section topic for more information.
%MRS	Message Recovery System (MRS)	Controls the operation of the local MRS server. See the Setting Message Recovery System Parameters in the MRS Section topic for more information.
%GNT	Group Name Table	Provides generic queue names (that do not necessarily appear in the %QCT) and their addresses. See the Defining Name to Queue Translations in the Group Name Section topic for more information.
%NAM	Naming Agent	Defines the group in which the naming agent process is running. You can define two naming agents for the environment. The naming agent provides the lookup capability for global (bus-wide) names. See the Configuring Global Naming topic for more information.

Defining Parameters in the Group Initialization File

You define parameters in the group initialization file by providing numeric values within a specified range or enabling settings to be YES or NO. The group initialization file is a typical ASCII text file that can be created and modified using any text editor. To create a custom group initialization file, make a copy of the template file and edit the copy. Do not edit the actual template file. You may want to add comments on your specific configuration. Use the exclamation, pound sign, semicolon, or asterisk characters (!, #, ;, or *) to as comment characters.

MessageQ also lets you modify a subset of parameters in the group initialization file at runtime. You can then use the Loader utility to dynamically reload the group initialization file without having to stop and restart MessageQ. See the Changing Group Characteristics at Runtime topic in Chapter 4 for instructions on how to run the Loader utility.

Several of the modifiable parameters can only be changed if certain conditions exist. These conditions are noted in the parameter description. The following topics describe the parameters, values, and settings in the group initialization file.

Default Values for Parameters

The group.init file template file contains most of the common parameters that you will need to configure. The following sections of this guide describe all available parameters that you can set using this file. The default values for all parameters are set at group startup, regardless of whether the parameter appears in the group initialization file. If a parameter is not specified, or is specified as a "." or -1, then the paramater takes on the default value.

Some sections of the sample group.init file are commented out because they are not used by default. To use these sections, you must uncomment these lines and set the values as appropriate for your environment.

Identifying the Group Initialization File Version

The %VERSION (file version) section consists of a single line identifying the group initialization file version. (Note that this is the initialization file version, and is not equivalent to the product version number.) MessageQ for UNIX systems accepts group initialization files with version numbers of 4.0 only. MessageQ uses the version number to be able to correctly parse configuration information for the message queuing group at startup.

Listing 3-1 shows a sample %VERSION section.

Listing 3-1 Sample %VERSION Section

---

%VERSION 4.0

Setting Group Characteristics in the Profile Section

The %PROFILE section is used to configure the primary characteristics (default values and parameter settings) of a group. This section is also enables MessageQ Server processes such as MRS, JRN, and SBS. Each server process is dedicated to a specific task or set of tasks.

You can start the following server processes by indicating "YES" for each server entry in the %PROFILE section:

• MRS Server-Enables recoverable messaging.

• JRN Server-Enables journaling services for postconfirmation and dead letter journals.

• SBS Server-Enables message broadcasting and AVAIL/UNAVAIL notification.

Listing 3-2 shows a sample %PROFILE section:

Listing 3-2 Sample %PROFILE Section

---

%PROFILE

!

ACCEPT_KILL_COMMAND       YES     ! accept kill commands from DMQ Monitor

ENABLE_XGROUP             NO      ! allow cross-group communications

XGROUP_VERIFY             NO      ! do not verify cross group links

FIRST_TEMP_QUEUE          200     ! minimum is 101, maximum is 850

XGROUP_TABLE_SIZE         20      ! size of the group link table

GROUP_BYTE_QUOTA          8388608 ! maximum number of bytes on all queues

GROUP_MAX_MESSAGE_SIZE    32000   ! largest message size permitted in

                                  ! this group

ATTACH_TMO                600     ! timeout in seconds for locates

ENABLE_MRS                NO      ! start recoverable messaging servers

ENABLE_JRN                YES     ! enable PCJ journaling when MRS is

                                  ! enabled

ENABLE_SBS                YES     ! start selective broadcast and AVAIL/UNAVAIL

DEFAULT_NAMESPACE_PATH   /u/mydir ! default namespace path for naming

                                  ! agent

%EOS

Table 3-3 describes the parameters of the %PROFILE section.

Table 3-3 %Profile Parameters

Parameter	Range	Default	Description
ACCEPT_KILL_COMMAND	YES NO	YES	Controls group control process termination requests from the MessageQ Monitor utility. A NO setting means that any message requests to shut down group control processes are ignored. Note: This parameter can be modified at runtime.
ENABLE_XGROUP	YES NO	NO	Enables MessageQ TCP/IP network access. A YES setting causes the appropriate link drivers to start to perform cross-group communications.
XGROUP_VERIFY	YES NO	NO	Verifies incoming TCP/IP connections. A YES setting causes all connections to be validated against the cross-group connection table, much like an Access Control List (ACL).
FIRST_TEMP_QUEUE	101- 3999	200	Selects the starting size of the temporary queue pool. This defines the size of the permanent and temporary queue pools for a group.
XGROUP_TABLE_SIZE	1- 32,000	20	Selects maximum number of group entries. This parameter defines the maximum number of group entries that MessageQ tracks, and does not affect the maximum group address.
GROUP_BYTE_QUOTA	1,048,576- 2,147,483,647	8,388,608	Sets the maximum number of message bytes on queues in memory. This includes user queues and all internal queues (such as recoverable messages that have not been written to a journal yet). The primary purpose of this parameter is to prevent the group server from becoming excessively large. Note: Although the range for this parameter is 2,147,483,647, you should not specify a value that is more than 30% of the virtual memory configured for the system.
GROUP_MAX_MESSAGE_SIZE	8192- 4,194,304	32,000	Specifies the largest message size permitted in this group.
ATTACH_TMO	>0	600	Selects the maximum elapsed time that an attach queue operation can take before a status of PAMS_TIMEOUT is returned to the caller. This number is in tenths of seconds. Note: This parameter can be modified at runtime.
ENABLE_MRS	YES NO	NO	Enables Message Recovery Services.
ENABLE_JRN	YES NO	YES	Enables PCJ journaling when MRS is enabled. The default journaling action is not to write messages to the PCJ.
ENABLE_SBS	YES NO	YES	Enables Selective Broadcast Services and AVAIL/UNAVAIL services. The %SBS section in the group initialization file is not used by MessageQ for UNIX
DEFAULT_NAMESPACE_PATH	--	--	Default namespace pathname for naming agent. Refer to the section entitled Configuring Global Naming for more information. Note: This parameter can be modified at runtime.

If the group you have defined will use resources such as message recovery services, CLS, group connections, permanent queues, or name-to-queue translations, you must define them next.

Setting Message Recovery System Parameters in the MRS Section

The %MRS section lets you enable MessageQ Message Recovery Services (MRS), which provide a mechanism for guaranteed message delivery by storing messages on disk and automatically attempting redelivery until the message is received by the target system. On MessageQ for UNIX systems, message recovery is provided by the dmqjourn journal process.

The server process that handles recoverable messaging is the MRS Server. In MessageQ, the MessageQ startup procedure starts up the MRS Server only if the ENABLE_MRS parameter is set to YES in the Profile section; then dmqjourn is started. When choosing a common directory where the journal files will be written, you should consider other files used by your programs (such as databases and logs) and the amount of available disk space. For a complete description of MRS, refer to the Programmer's Guide.

MessageQ for UNIX provides the following types of recovery journals:

Journal Type	Description
Store and Forward (SAF)	Used to store recoverable messages targeted at a remote group on the local system. Messages are automatically resent after communication with the target group is restored.
Destination Queue File (DQF)	Used to store recoverable messages targeted at the local group on the local system. Messages are automatically resent when the queue becomes active.
Postconfirmation Journal (PCJ)	Used to store successfully confirmed recoverable messages. The PCJ forms an audit trial of message exchange that can be read or printed. The default journaling action is not to write messages to the PCJ.
Dead Letter Journal (DLJ)	Used to store messages that could not be stored for automatic recovery by MRS. Undelivered DLJ messages can be resent under user or application control.

Listing 3-3 shows a sample %MRS section and Table 3-4 describes the parameters of the %MRS section.

Listing 3-3 Sample %MRS Section

---

%MRS

CACHE_PERCENTAGE         90                ! %rcv msg quota for MRS msgs

MRS_JOURNAL_PATH             /my/rj_path   ! recovery journal path

MRS_POST_CONFIRMATION_PATH   /my/pcj_path  ! post confirmation journal path

MRS_DEAD_LETTER_PATH         /my/dlj_path  ! dead-letter journal path

MAX_CACHE_BYTES              4194304       ! maximum number of unwritten bytes

%EOS

Table 3-4 %MRS Parameters

Parameter	Range	Default	Description
MRS_JOURNAL_PATH	-	-	If a recoverable message cannot be delivered to the target application, the journal process writes it to the recoverable journal file. Journal files are dynamically created and deleted as needed by the journal process. The size of a journal file is fixed. The journal process creates a new journal file each time the current file fills up and attempts to empty journal files by periodically attempting to reach the corresponding remote queue.
CACHE_PERCENTAGE	1 - 100	50	Specifies the receive quota to determine the number of messages that MRS maintains queued in the message pool to a given target queue. Multiply the CACHE_PERCENTAGE value by the MSG_QUOTA value (see the %QCT section) to determine the maximum number of recoverable messages that can reside in the memory based queue at one time. We recommend that you always set this parameter to less than 100. This parameter operates as follows: When a message queue is attached, enough recoverable messages are delivered to match this limit. When the limit is reached, no more recoverable messages are delivered until enough recoverable messages are dequeued by the target to drop below the set limit. While recoverable message delivery is stopped due to the limit, new recoverable messages are written to the DQF file to be delivered in order of receipt. Non-recoverable messages are delivered as usual.
MRS_POST_CONFIRMATION_PATH	-	-	Recoverable messages that successfully reach the delivery interest point can be written to the postconfirmation journal of the target group.
MRS_DEAD_LETTER_PATH	-	-	Recoverable messages that cannot be stored by the message recovery system are written to the dead letter journal of the sender program's group. The DLJ file provides a backup mechanism for recovering messages that could not be stored for automatic recovery.
MAX_CACHE_BYTES	1,048,576- 2,147,483,647	4,194,304	Sets the maximum number of bytes that have not yet been written to disk. A large value improves the performance of recoverable messaging, particularly for PCJ and SAF journals. There is no maximum value for this parameter. Note: Although the range for this parameter is 2,147,483,647, you should not specify a value that is more than 30% of the virtual memory configured for the system.

Configuring Client Library Server in the CLS Section

The %CLS section lets you configure the MessageQ Client Library Server. The CLS provides MessageQ applications running on a supported MessageQ client system with access to message queuing. Applications can communicate with other distributed applications anywhere in the MessageQ network using a single connection to a CLS process connected to the bus. For detailed information about the CLS, refer to the MessageQ Client for UNIX User's Guide.

Listing 3-4 shows a sample %CLS section.

Listing 3-4 Sample %CLS Section

---

%CLS

!

!                             Max      Security
!   Endpoint     Transport    Clients  File

    12345        TCPIP        25       /my/dmqclsec.txt
     64354         TCPIP         50

%EOS

Table 3-5 describes the parameters of the %CLS section:

Table 3-5 %CLS Parameters

Parameter	Range	Default	Description
ENDPOINT	TCP/IP: 1024-65535	-	Identifies either the TCP/IP port number that the server uses to accept incoming connections. Using endpoint numbers under 5000 is recommended. The same endpoint is used in the configuration of MessageQ Clients to locate the CLS. For TCP/IP transport, port numbers less than 1024 are reserved. There is no restriction on the use of port numbers within the available range by CLS. However, you should select port numbers that do not conflict with port numbers used by MessageQ TCP/IP Link Drivers or other TCP/IP-based applications on your system.
TRANSPORT	TCPIP	-	The name of the network protocol stack to be used for the server.
MAX CLIENTS	1 - 512	32	The maximum number of clients the server will serve at any given time. This parameter applies to OpenVMS systems only. Note: This parameter can be modified at runtime, but the CLS must be stopped.
SECURITY FILE	-	-	The full pathname of the security file. If no security file is specified, MessageQ provides a default file name. For more information about the CLS security file, see the Restricting Remote Access to CLS topic in Chapter 4. Note: This parameter can be modified at runtime, but no process can be attached to the queue.

Enabling Network Connections in the Cross-Group Section

To enable message queuing between different systems in a network, you must create MessageQ message queuing groups on each system and establish cross-group connections between them. Messages can be exchanged between groups using two methods:

To Exchange Messages...	Between...	Use...
Directly	Groups that share a physical network link	Cross-group connections (%XGROUP section)
Indirectly	Groups that do not share a physical network link	Message routing (%ROUTE section)

Your configuration will probably use both methods, so it is important to understand that if a group is defined in the %XGROUP section, it cannot be designated as a target group in the %ROUTE section (as described in the "Defining the Message Routing Database in the Route Section" topic). It can, however, be designated as a route-through group.

The %XGROUP section lets you define cross-group communication connections among groups that share a physical network link. Each line in the %XGROUP section defines a single cross-group connection, which creates two new link drivers for each unique group number. The %XGROUP section provides the link drivers with the information needed to connect to other MessageQ message queuing groups through TCP/IP networks.

• All parameters for a given connection must appear on the same line.

• You must provide an entry for the local (current) group.

• Changing the node/host name in the group.init file then running the Loader utility results in an additional entry at the front of the %XGROUP table rather than a replacement entry. In this case, there is link configuration information in the running group that does not match the group.init file and that is also not accessible from any monitor display.

  Listing 3-5 Sample %XGROUP Section

  ---

  %XGROUP

  !

  !Group Group  Node/ Init Thresh- Buffer Recon-    Window      Trans-  End- 
  !Name  Number Host       old     Pool   nect   Delay  Size    port    point
  

  GROUP1  1    delius  Y  2000000   .     30     10     25000   TCPIP   10001
  GROUP2  2    bizet   N  4000000   .     30     10     25000   TCPIP   10002
  GROUP3  3    bartok  N  8000000   .     30     10     25000   TCPIP   10003
  GROUP4  4    boehm   N  4000000   .     30     10       250   TCPIP   10004
  GROUP4  4    rameau  N  4000000   .     30     10       250   TCPIP   10004
  

  %EOS
  

Table 3-6 describes the parameters of the %XGROUP section.

Table 3-6 %XGROUP Parameters

Parameter	Range	Default	Description
GROUP NAME	--	--	Name by which the remote MessageQ group is known to the local group.
GROUP NUMBER	-	-	MessageQ Group Number of the remote group.
HOST	-	-	Name by which the remote host is known to the local host.
INITIATE	Y N D (Disable)	-	Logical value indicating whether connections to this node should be initiated or disabled. Y - The Group Control Process initiates a connection to the node. N - The Group Link Table and Group Link Vector Table entries are built for the node; however, a connection is not initiated. D - All connections to the node are disabled.
THRESHOLD	1,048,576	1,048,576	This value is ignored and has been superseded by the GROUP_BYTE_QUOTA parameter in the %PROFILE section.
BUFFER POOL	--	--	This value is ignored on MessageQ for UNIX and Windows NT systems. Note: This parameter can be modified at runtime, but the link must be disabled.
RECONNECT	>=1	60	Interval, in seconds, between reconnect attempts when this cross-group link is not connected.
WINDOW DELAY	>=0	10	Delay, in seconds, that a sender must wait before using a new window when the receiver is congested.
WINDOW SIZE	>0	250	Maximum number of messages a group can send to another group before requesting permission to send more. Note: This parameter can be modified at runtime.
TRANSPORT	TCPIP		Network protocol stack used. For MessageQ V5.0 this is TCPIP.
ENDPOINT	TCP/IP: 1024-3276	--	Protocol-stack-dependent address (port number) of the remote link listener process. Using endpoint numbers under 5000 is recommended. For TCP/IP transport, this address is an Internet port number ranging from 1024 to 32767 inclusive.

Defining the Message Routing Database in the Route Section

MessageQ uses routing entries to allow messaging between groups that are not directly attached to the local group by way of a physical network link. MessageQ software allows up to 15 intermediate MessageQ groups between the message source and the target queue. The intermediate groups are specified in the %ROUTE section of the group initialization file. The %ROUTE section specifies the next hop (next group to route through) for a message to reach the target destination queue. Groups defined in the %XGROUP section do not need to be defined in the %ROUTE section, and vice versa.

The %ROUTE section lets you define the MessageQ static routing database. The routing database determines where to send messages that are addressed to non-adjacent nodes; that is, nodes that do not appear in the %XGROUP section. All parameters for a given routing entry must appear on the same line.

Listing 3-6 shows a sample %ROUTE section.

Listing 3-6 Sample %ROUTE Section

---

%ROUTE

!Target    Routethrough

!Group     Group

  7        1
  10       2

%EOS

Table 3-7 describes the parameters of the %ROUTE section.

Table 3-7 %ROUTE Parameters

Parameter	Range	Default	Description
TARGET_GROUP	--	--	Group for which traffic is being routed.
ROUTE_THROUGH_GROUP	1- 32,000	--	Group to which traffic for the target group will be routed.

Note: If a group is defined in the %XGROUP section, it cannot be designated as a target group in the %ROUTE section. It can, however, be designated as a route-through group.

In Listing 3-7, the %XGROUP and %ROUTE sections are correctly defined. Group1 and Group2 are not defined as target groups in the %ROUTE section, and they are correctly defined as route-through groups.

Listing 3-7 Correctly Defined %XGROUP and %ROUTE Sections

---

%XGROUP
!

!Group Group  Node/ Init Thresh- Buffer Recon- Window Window  Trans-  End- 
!Name  Number Host       old     Pool   nect   Delay  Size    port    point

GROUP2  2     node2  Y    5       75     10    10     250     TCPIP   10002
GROUP7  7     node7  N    5       75     10    10     250     TCPIP   10007

%EOS

!
!Target    Routethrough

!Group     Group

   10        7
   1         2

%EOS

In Listing 3-8, the %ROUTE section is incorrectly defined. GROUP1 cannot be designated as a target group in the %ROUTE section because it was previously defined as an adjacent group in the %XGROUP section. However, GROUP2 is correctly designated as a route-through group.

Listing 3-8 Incorrectly Defined %XGROUP and %ROUTE Sections

---

%XGROUP

!Group Group  Node/ Init Thresh- Buffer Recon- Window Window  Trans-  End- 
!Name  Number Host       old     Pool   nect   Delay  Size    port    point

GROUP1  001   node1  Y    5      75     10     10     250     TCPIP   10001
GROUP2  002   node   N    5      75     10     10     250     TCPIP   10002
%EOS
%ROUTE
!
!Target    Routethrough

!Group     Group

   1         2
   7         2

%EOS

Route Discovery

The user-specified %ROUTE section is automatically updated by the process of route discovery. As a message hops along the message route, MessageQ automatically loads the return address into the routing table so that a message can be returned. Route discovery has the advantage of allowing groups to acquire information about other groups with which they might communicate.

Figure 3-3 provides an example of how route discovery allows a group to acquire routing information about other groups.

Figure 3-3 Route Discovery

In the example, Group 2 is connected to Groups 1 and 3, and Group 1's %ROUTE section was loaded at startup. When Group 1 sends a message to Group 3, MessageQ loads the return address of the message into Group 3's %ROUTE section. Through route discovery, Group 3 is now able to send a message to Group 1.

Visit Counts

Messages with circular routing paths could be endlessly passed from system to system. To prevent this, full message routing uses a visit count, which is a system-determined limit on the number of groups through which a message can hop. The visit count is placed into the message header when the message is created. When a message is sent between groups, the visit count is decremented. When the visit count reaches zero, the message can no longer be forwarded to another system and the Undeliverable Message Action (UMA) for the message is taken.

Full message routing rules followed by the MessageQ server are as follows:

• The initial visit count is 16.

• If the visit count has been exceeded, the UMA is taken.

• If there is a direct connection to the group, the MessageQ server ignores the routing table and uses the direct connection.

• If the group has a known route-through group, the MessageQ server uses it.

• If there is no known route to the target group, the UMA is taken.

Client/Server Message Routing

Full message routing is based on the model of a server group ring surrounded by a client ring, as shown in Figure 3-4. Each server can route messages to other groups without requiring clients to be directly connected to the target group of the message.

Figure 3-4 Client and Server Full Message Routing

In full message routing, a client group has cross-group entries for itself and the adjacent server group. A client group can attach to different server groups, one at a time. The server groups subsequently update the routing table by using route discovery.

A server group has entries in the %XGROUP section of the initialization file for itself and all other server groups. A server group does not have entries for clients; instead, it uses route discovery to learn the return route from server back to client.

Defining Queues in the Queue Configuration Section

The %QCT section lets you define the permanent queues. Each line in the %QCT section defines a single queue. All parameters for a given queue must appear on the same line. Parameters that do not apply must be given a placeholder value.

Note: On VMS systems, queues numbered 90 to 100 and 150 to 199 are reserved exclusively for MessageQ. On UNIX systems, queues numbered 90 to 100 are reserved exclusively for MessageQ.

Listing 3-9 shows a sample %QCT section.

Listing 3-9 Sample %QCT Section

---

%QCT
!

!Queue     Queue  Byte  Msg   Quota UCB  Queue Owner Conf  Perm   Name Security
!Name       Number Quota  Quota  Enbl  Send  Type   Queue Style Active  Scope

TEMPLATE    0    262144      NONE   .      P    0    II    N      L     N
QUEUE1      1    .           NONE   .      P    0    II    N      L     N
QUEUE2      2    .           NONE   .      P    0    II    N      L     N
QUEUE3      3    .           NONE   .      P    0    II    N      L     N
QUEUE4      4    .           ALL    .      M    0    II    Y      L     N
QUEUE5      5    .           .      .      S    3    II    Y      L     N
QUEUE6      6    .           .      .      S    3    II    Y      L     N
QUEUE7      7    .           .      .      S    0    II    N      L     N

! queues that specify ACL security files exist and should be
! checked each time a process attaches one of these queues
QUEUE10    10    .           .      .      P    0    II    N      L     Y
QUEUE11    11    .           MSG    .      S    10   II    N      L     Y
QUEUE12    12    .           BYTE   .      S    10   II    N      L     Y

! queues with differing quotas. Quotas also can be turned on using
! the monitor programs (dmqmonc and dmqmonm)
QUEUE13    13     8192   32  ALL    .      P    0    II    N      L     N
QUEUE14    14   131072   64  MSG    .      P    0    II    N      L     N
QUEUE15    15    32768   .   BYTE   .      .    0    II    N      L     N

! queues that require explicit confirmation and allow out of 
! order confirmation
QUEUE16    16            .   None    .     P    0    EI    N      L     N
QUEUE17     17              .   .        .     P     0    EO     N       L     N

! the example_q_n queues are used by the example programs 
! provided in the MessageQ Example Programs subset
example q_1 193            .   .        .      P    0      .     N      L     N
example q_2 194            .   .        .      P    0      .     N      L     N
example q_3 195            .   .        .      P    0      .     N      L     N
example q_4 196            .   .        .      P    0      .     N      L     N
example q_5 197            .   .       .       P    0      .     N      L     N

! The DEAD_LETTER_QUEUE is the target for UMA modes.of
! xx_DLQ A user process may attach this queue to collect un-
! deliverable messages for application-specific processing
DEAD_LETTER_QUEUE 96 64000 500 None    .      P     0      II    Y      L     N

%EOS

Table 3-8 describes the parameters of the %QCT section.

Table 3-8 %QCT Parameters

Parameter	Range	Default	Description
QUEUE NAME	1- 255 characters	--	MessageQ internal name for each permanent queue. You can create a TEMPLATE QUEUE (queue 0) allowing you to create a set of customized default values for your environment. Specifying a -1 or "." as the value when configuring additional queues enables them to automatically use the TEMPLATE QUEUE settings.
QUEUE NUMBER	--	--	Number of this queue. Queue numbers must be less than the value for the FIRST_TEMP_QUEUE in the %PROFILE section. A queue number can appear only once in the %QCT section. Queues 90-95 and 97-100 are reserved and cannot appear in this section.
BYTE QUOTA	>1	65,536	Maximum number of uncollected bytes that can reside in this queue when quotas are enabled. If the value is -1 or ".", the value in the TEMPLATE QUEUE is used. If no template queue is specified, the default value of 65,536 is used. Note: This parameter can be modified at runtime.
MSG_QUOTA	>1	128	Maximum number of uncollected messages that can reside in this queue when quotas are enabled. If the value is -1 or ".", the value in the TEMPLATE QUEUE is used. If no template queue is specified, the default value of 128 is used. Note: This parameter can be modified at runtime.
QUOTA ENABLED	All None Byte Msg "."	--	Controls the enabling and disabling of queue quotas. Values for this attribute are as follows: All: All queue quotas are ON. None: All queue quotas are OFF. Byte: Only the byte quota is enabled; msg quota is disabled. Msg: Only the msg quota is enabled; the byte quota is disabled. ".": Default value, which is "All" for all queues. Note: This parameter can be modified at runtime.
UCB SEND	--	--	This field is not used. It exists only for compatibility with the MessageQ for OpenVMS software.
QUEUE TYPE	P S M	P	Designates the queue type as follows: P: Primary queue S: Secondary queue M: Multi-reader queue Note: This parameter can be modified at runtime under the following conditions: The queue must be empty and have no processes attached. When changing a primary queue to a secondary queue, the primary queue cannot have any secondary queues defined.
OWNER	Any non-secondary queue	0	If QUEUE TYPE=S, specifies the number of the controlling queue. If QUEUE TYPE=P or M, use zero. Note: This parameter can be modified at runtime under the condition that the queue must be empty and have no processes attached.
CONF STYLE	II EI EO "."	EO	Determines how recoverable messages are confirmed by the receiver program. Possible values are as follows: II: Implicit, in-order confirmations EI: Explicit, in-order confirmations EO: Explicit, out-of-order confirmations ".": Accepts default, which is "EO". Note: This parameter can be modified at runtime.
PERM ACTIVE	Y N	N	Permanently active queue. Setting this value to Y allows processes to insert messages into this queue even if it is not currently attached by a client process. Note: This parameter can be modified at runtime.
NAME SCOPE	L (Local) G (Global)	--	Indicates the scope of the queue name. Valid settings are: L: The name is loaded into the Group Name Table, but not into the distributed naming service. The name can be translated by the pams_locate_q function and by other processes in this group. G: The name is loaded into the distributed naming service. The name can be translated by the pams_locate_q function by other processes in this network.
SECURITY	Y N	N	Controls security, as follows: N: No security authorization checking for attach. Y: Activates security authorization checking. An Access Control List (ACL) file must be present and able to be opened for read or write in order to attach the queue. Note: This parameter can be modified at runtime. See the Setting Security for Queues topic in Chapter 4 for more information.
MRS_FLUSH_TIMER	-1 - 2,147,483,647	100	Maximum number of milliseconds to wait before flushing the non-journaled message cache. If the value is -1 or absent, the default value is used. If the value is 0, no scheduled flushing occurs. However, flushing can occur as a result of limits set by other parameters. When the chosen value is anything other than 0, messages will get flushed sooner than the limit only if the group server is idle. This parameter must be manually added to the file (see Listing 3-10).
MRS_FLUSH_DEPTH	-1 - 2,147,483,647	0	Maximum number of messages that can be cached. If the value is -1 or absent, the default value is used. If the value is 0, the number of messages cached can be 2,147,483,647, but may be limited by other parameters such as MAX_CACHE_BYTES. >0 means to flush when that number of messages are cached. For example, a value of 1 means flush each message immediately; a value of 2 means flush after 2 messages are cached. This parameter must be manually added to the file (see Listing 3-10).

The Flush Timer and Flush Depth parameters must be manually added to the file as the last two columns in the QCT group. Listing 3-10 shows the addition of these parameters:

Listing 3-10 Sample %GNT Section

---

%QCT
!

!Queue      Queue    Byte	...    Name   Security   Flush      Flush 
!Name       Number   Quota	...    Scope             Timer      Depth

TEMPLATE    0     262144	...    L       N      1000       10
QUEUE1      1       .  	...     L       N      1000       10
QUEUE2      2       .  	...     L       N      1000       10

Defining Name to Queue Translations in the Group Name Section

The %GNT section lets you define the generic queue names and their address for queues that do not necessarily appear in the %QCT section. Each line in the %GNT section defines a single name-to-queue translation.

Listing 3-11 shows a sample %GNT section where INVENTORY_IN is statically defined in the bus-wide namespace, while ACCOUNTS_PAY allows dynamic binding using pams_bind_q.

Listing 3-11 Sample %GNT Section

---

%GNT

!
!Name           Group.Queue     Scope

INVENTORY_IN    9.10            G

ACCOUNTS_PAY    0.0             G

%EOS

Table 3-9 describes the parameters in the %GNT section.

Table 3-9 %GNT Parameters

Parameter	Range	Default	Description
NAME	--	--	Equivalence name. Queue reference used by applications to refer to the queue by name. Names can be up to 255 characters. Note: MessageQ for UNIX systems is case-sensitive, while MessageQ for OpenVMS is not. Use both upper and lower case for developers porting applications from OpenVMS systems.
GROUP.QUEUE	-	-	Group and queue number to be returned to the calling process when this name is translated by the pams_locate_q function. Contains a group identifier, a period (.) and a queue number. Specifying zero for the group identifier implies the local group number. Specifying a zero for both the group and queue number means that this name can be dynamically assigned a queue address at runtime using the pams_bind_q function.
SCOPE	L (Local) G (Global)	-	Scope of name, as follows: L: Queue name is loaded into the group-wide namespace. Other processes in this group can issue the pams_locate_q function to translate the queue name. G: Queue name is loaded into the group-wide namespace and the bus-wide namespace. Any application on the message bus can issue the pams_locate_q function to translate the queue name.

Configuring Global Naming

To use local (group-wide) naming, configure queue names in the Queue Configuration Table (%QCT) or the Group Name Table (%GNT) section of the group initialization file. When the group starts up, MessageQ automatically creates the group namespace. It creates the process name space when an application attaches to the message queuing bus.

To enable your applications to use global (bus-wide) naming, you must perform additional configuration steps. First, you must decide the group or groups in which the naming agent will run. MessageQ allows you to specify a main group and an alternate group to run the Naming Agent. To configure a group to run the Naming Agent follow the steps outlined in the topic "Configure Groups to Run or Use the Naming Agent."

Configure Groups to Run or Use the Naming Agent

The MessageQ Naming Agent is the MessageQ Server that maintains the namespace for name-to-queue address translations and performs the runtime queue lookup when an application refers to a queue by name. The %NAM section of the group initialization file enables you define the group or groups in which the Naming Agent process will run. MessageQ allows the definition of two naming agents for each message queuing bus.

When MessageQ starts each group, it looks in this section of the initialization file to decide whether to start a naming agent for the group. For groups that do not run a Naming Agent, MessageQ uses the information in the %NAM section to direct requests to the Naming Agent. Groups must have a cross-group connection to the group in which the Naming Agent runs.

Listing 3-12 shows a sample %NAM section.

Listing 3-12 Sample %NAM Section

---

%NAM

NA_GROUP   10

NA_GROUP   28

%EOS

%END

---

Valid ranges for the NA_GROUP parameter are 0 to 32,000. If the parameter is set to 0, a naming agent is started in the local group.

Configure the Namespace

MessageQ for UNIX supports only the creation of a "lightweight" name space that is included with MessageQ. It does not support any add-on naming products such as CDS or DECdns. To create the global name space, MessageQ for UNIX users use a flat file system by creating the directory in which the MessageQ Naming Agent will maintain the name space.

To use global naming, you must create a namespace on the nodes on which the Naming Agents will run. MessageQ enables users to configure two Naming Agents to support global messaging for the environment. In order to allow the second Naming Agent to form a backup for the first, both Naming Agents must be configured to use the same name space. Therefore, when you configure your name space for use by two Naming Agents that run on different systems, it must use a shared file system that is accessible to both Naming Agents.

After you create the name space, you must set the DMQNS_DEVICE environment variable to specify a device name for the name space because access to the MessageQ lightweight name space for global naming is system dependent. Therefore, when a naming agent is configured, it must be told what device name to use when it accesses this name space. This is done by setting the environment variable DMQNS_DEVICE as follows:

• For Windows NT, it should be set to a drive letter followed by a colon (for example, c:> or a full qualified sharename (e.g. \\machine\share)

• For VMS, it should be set to a disk device name or a logical name that translates to such a device (dua1 or disk$user1)

• For UNIX, it should be set to a file system specification (for example, / or /usr or /mnt/dmqns)

Note that this environment variable need only be set for the group or groups in which the Naming Agent is running. Only the Naming Agent process is designed to use this environment variable setting to resolve the location of the name space.

For environments which use two naming agents, it is critically important to ensure that the device name set using the DMQNS_DEVICE environment variable on both systems points to the same device that stores the shared file system containing the MessageQ namespace.

Configure a Default Namespace Path for Each Group

To use a global name, at least some portion of the path name must be specified. Path information can be supplied by the application, or you can use the DEFAULT_NAMESPACE_PATH parameter in the %PROFILE section of the group initialization file in order to create and maintain path information for global names. For global naming to function properly, this parameter must be set to the same value for all groups in which applications are designed to access the same name space. The following syntax shows how to set the default namespace to be created and maintained in the directory called /u/mydir.

DEFAULT_NAMESPACE_PATH /u/mydir

For example, for testing purposes, you might set this parameter to look at a copy of the production name space that you store in your own development directory. However, when the application is deployed into production, the application will reference the common name space shared by all production systems.

Define the Queue Names in the Group Initialization File

Use the Queue Configuration Table (%QCT) or the Group Name Table (%GNT) of the group initialization file to create static or dynamic definitions for global names as follows:

Define global static names in the %QCT or %GNT by providing the name, the queue address, and setting the name scope identifier to "G" for global names.

Define global dynamic names by supplying the name, "0.0" as the address, and the "G" identifier for global names. Names defined with a 0.0 address can be dynamically bound to a queue address at runtime using the pams_bind_q function.

Listing 3-13 shows static and dynamic global name definitions in the GNT section of the initialization file.

Listing 3-13 Sample Group Name Table for Global Naming

---

%GNT
!Name           Group.Queue     Scope

widgets         9.10            G

red_widgets     0.0             G

%EOS

---

When an application refers to a queue by name using the pams_locate_q or the pams_bind_q functions, it can specify the name as one of the following:

unqualified name-The application uses only the queue name such as "widgets" and does not specify the path. The Naming Agent automatically prefixes the name with the value of the environment variable DMQNS_DEVICE. Further, it prepends the value of the environment variable DMQNS_DEFAULT_PATH unless the path name specified by the DEFAULT_NAMESPACE_PATH begins with a "/". For example, if the DMQNS_DEVICE environment variable is set to "dev" and the DEFAULT_NAMESPACE_PATH is set to "/inventory", the Naming Agent would search for the name "widgets" in:

/dev/inventory/widgets

partially qualified name - The application specifies the queue name and a portion of the path name. The Naming Agent automatically prefixes the pathname and queue name with the device specified as the DMQNS_DEVICE environment variable and the setting of the DEFAULT_NAMESPACE_PATH parameter or the DMQNS_DEFAULT_PATH environment variable. For example, if the DMQNS_DEVICE environment variable were set to "dev" and the DEFAULT_NAMESPACE_PATH were set to "/inventory", the Naming Agent would search for the name "test/widgets" in:

/dev/inventory/test/widgets

fully qualified name-The application specifies that the name is a fully qualified name using "/" as the first character of the name. When the first character of a name begins with "/", the Naming Agent does not prepend any information to the name other than the device name specified by the DMQNS_DEVICE environment variable. This means that a fully qualified name includes the full path name and queue name. For example, if the DMQNS_DEVICE environment variable is set to "dev" and the DEFAULT_NAMESPACE_PATH is set to "/inventory", the Naming Agent would search for the name "/production/test/widgets" in:

dev/production/test/widgets

The use of unqualified, partially qualified, and fully qualified names gives application developers significant flexibility in using global name references. provides several more examples of how global names are resolved. In Listing 3-14, the DMQNS_DEVICE environment variable is set to "dev" and the DMQNS_DEFAULT_PATH is set to "/dmq/dmqns".

Listing 3-14 Sample Global Names and Their Resolution

---

Name Used in API  DEFAULT_NAMESPACE_PATH  Name Searched

toto			bus1		/dev/dmq/dmqns/bus1/toto

mypath/toto			bus1		/dev/dmq/dmqns/bus1/mypath/toto

/anotherpath/toto			bus1		/dev/anotherpath/toto

toto			/bus1		/dev/bus1/toto

/mypath/toto			/bus		/dev/bus1/mypath/toto

/anotherpath/toto			/bus		/dev/anotherpath/toto

---

Refer to the MessageQ Programmer's Guide for more information on designing applications to use the MessageQ global naming feature.

Using the Test Utility to Test Your Group Configuration

The Test utility allows application developers to send and receive messages between applications to:

• Build interactive tests of application modules.

• Simulate send and receive messages to any target from any source.

• Exercise the queues in the MessageQ system.

The MessageQ Test utility enables application developers to interactively attach to a permanent or temporary queue, read messages from a script file or available interprocess messages, and pass messages to a defined target queue. The Test utility can be invoked by way of the Motif user interface or a character-cell user interface on UNIX systems.

To invoke the Test utility using the Motif user interface, set the environment variables for the bus and group ID and enter the following command:

dmqtestm

To invoke the Test utility using the character-cell interface, set the environment variables for the bus and group ID and enter the following command:

dmqtestc 

Listing 3-15 shows the character-cell Test Utility main menu options.

Listing 3-15 Test Utility Main Menu

---

Main Menu

1 Parameters
2 Actions
3 Exit

Enter Menu Selection >> 1

---

Refer to Table 3-10 for the Test Utility Parameters and Actions menu Options.

Table 3-10 Test Utility Parameters and Actions Menu Options

Parameters Menu Option	Actions Menu Options
Attach Parameters	Attach Queue
Bind Parameters	Bind Queue
Detach Parameters	Detach Queue
Locate Parameters	Locate Queue
Put Parameters	Put Message
Get Parameters	Get Message
Set Timer Parameters	Set Timer
Cancel Timer Parameters	Cancel Timer
View Current Parameters	View Current Parameters
Subscribe MOT Parameters	Subscribe MOT
Previous Menu	Previous Menu

The examples in the following section show how to use the Test Utility to perform various tasks such as:

• Setting the Attach parameters to specify a temporary primary queue

• Setting the Put parameters for the message

• Attaching to queues

• Putting the message to queue

• Detaching from the temporary queue

• Exiting from the Test Utility

Specifying a Temporary Queue

Listing 3-16 shows how to specify a temporary queue.

Listing 3-16 Specify a Temporary Queue

---

Main Menu

1 Parameters
2 Actions
3 Exit

Enter Menu Selection >> 1

Parameters Menu

 1 Attach Parameters
 2 Bind Parameters
 3 Detach Parameters
 4 Locate Parameters
 5 Put Parameters
 6 Get Parameters
 7 Set Timer Parameters
 8 Cancel Timer Parameters
 9 View Current Parameters
10 Subscribe MOT Parameters
11 Previous Menu

Enter Menu Selection >> 1

SELECT ATTACH TYPE
	1) Attach Primary
	2) Attach Secondary
Select attach type [1] ? 

SELECT ATTACH_MODE
	1) Attach by name
	2) Attach by number
	3) Attach temporary
Select attach mode [3] ? 

Setting the PAMS_PUT_MESSAGE Parameters

Listing 3-17 shows how to set the pams_put_message parameters.

Listing 3-17 Set the Put Parameters

---

Parameters Menu

 1 Attach Parameters
 2 Bind Parameters
 3 Detach Parameters
 4 Locate Parameters
 5 Put Parameters
 6 Get Parameters
 7 Set Timer Parameters
 8 Cancel Timer Parameters
 9 View Current Parameters
10 Subscribe MOT Parameters
11 Previous Menu

Enter Menu Selection >> 5

SELECT PRIORITY
	1) Standard Priority
	2) High Priority
Select priority [1] ? 

SELECT DELIVERY MODE
	1) PDEL_MODE_AK_xxx
	2) PDEL_MODE_NN_xxx
	3) PDEL_MODE_WF_xxx
Select deliver mode [2] ? 3

SELECT DELIVERY MODE
	1) PDEL_MODE_xx_ACK
	2) PDEL_MODE_xx_CONF
	3) PDEL_MODE_xx_DEQ
	4) PDEL_MODE_xx_DQF
	5) PDEL_MODE_xx_MEM
	6) PDEL_MODE_xx_SAF
Select delivery mode [5] ? 5

SELECT UMA
	1) PDEL_UMA_DISC
	2) PDEL_UMA_RTS
	3) PDEL_UMA_SAF
	4) PDEL_UMA_DLQ
	5) PDEL_UMA_DLJ

Select UMA [1] ? 1

Enter target group [9] ? 9
Enter target queue [205] ? 
Enter response queue [0] ? 
Enter timeout in seconds [30] ? 
Enter message class [1] ? 12
Enter message type [-100] ? 34
Enter message text ? This is a test message.

---

Attaching to a Queue

Listing 3-18 shows how to attach to a queue.

Listing 3-18 Attach to Queue 206 in Group 9

---

Main Menu

1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 2

Actions Menu

 1 Attach Queue
 2 Bind Queue
 3 Detach Queue
 4 Locate Queue
 5 Put Message
 6 Get Message
 7 Set Timer
 8 Cancel Timer
 9 View Current Parameters
10 Subscribe MOT
11 Previous Menu

Enter Menu Selection >> 1
attached to queue 9.206

---

If your MessageQ message queing group is properly configured, the Test utility returns a success message indicating that the attach operation was successful. However, if your MessageQ message queing group is not properly configured, an error message is displayed indicating the source of the problem as shown in Listing 3-19.

Listing 3-19 Common Errors

---

Actions Menu

 1 Attach Queue
 2 Bind Queue
 3 Detach Queue
 4 Locate Queue
 5 Put Message
 6 Get Message
 7 Set Timer
 8 Cancel Timer
 9 View Current Parameters
10 Subscribe MOT
11 Previous Menu

Enter Menu Selection >> 1
PAMS_RESRCFAIL, Failed to allocate resources.

---

Refer to the Troubleshooting chapter for additional information.

Sending a Message

Listing 3-20 shows how to send a message.

Listing 3-20 Put the Message to Queue 205 in Group 9

---

Actions Menu

 1 Attach Queue
 2 Bind Queue
 3 Detach Queue
 4 Locate Queue
 5 Put Message
 6 Get Message
 7 Set Timer
 8 Cancel Timer
 9 View Current Parameters
10 Subscribe MOT
11 Previous Menu

Enter Menu Selection >> 5
put message to queue 9.205

---

Detaching from a Temporary Queue

Listing 3-21 shows how to detach from the temporary queue.

Listing 3-21 Detach from Temporary Queue 205

---

Main Menu

1 Parameters
2 Actions
3 Exit

Enter Menu Selection >> 2

Actions Menu

 1 Attach Queue
 2 Bind Queue
 3 Detach Queue
 4 Locate Queue
 5 Put Message
 6 Get Message
 7 Set Timer
 8 Cancel Timer
 9 View Current Parameters
10 Subscribe MOT
11 Previous Menu

Enter Menu Selection >> 3
detached from queue 9.205

---

Setting the PAMS_GET_MSG Parameters

Listing 3-22 shows how to set the pams_get_msg parameters.

Listing 3-22 Set the PAMS_GET_MSG Parameters

---

Main Menu

1 Parameters
2 Actions
3 Exit

Enter Menu Selection >> 1

Parameters Menu

 1 Attach Parameters
 2 Bind Parameters
 3 Detach Parameters
 4 Locate Parameters
 5 Put Parameters
 6 Get Parameters
 7 Set Timer Parameters
 8 Cancel Timer Parameters
 9 View Current Parameters
10 Subscribe MOT Parameters
11 Previous Menu

Enter Menu Selection >> 

SELECT INPUT QUEUE
	1) FIFO : default queue
	2) FIFO : alternate queue ? 
Select input queue [1] ? 

SELECT PRIORITY
	1) Standard Priority
	2) High Priority 
Select priority [1] ? 

SELECT WAIT OPTION
	1) PAMS_GET_MSG
	2) PAMS_GET_MSGW 
Select wait option [1] ? 

---

Receiving a Message

Listing 3-23 shows how to receive a message.

Listing 3-23 Receiving a Message

---

Main Menu

1 Parameters
2 Actions
3 Exit

Enter Menu Selection >> 2

Actions Menu

 1 Attach Queue
 2 Bind Queue
 3 Detach Queue
 4 Locate Queue
 5 Put Message
 6 Get Message
 7 Set Timer
 8 Cancel Timer
 9 View Current Parameters
10 Subscribe MOT
11 Previous Menu

Enter Menu Selection >> 6
received message from 9.205, class:12, type:34, : This is a test message from dmq

---

Setting Detach Parameters

Listing 3-24 shows how to set the detach parameters.

Listing 3-24 Setting Detach Parameters

---

Main Menu

1 Parameters
2 Actions
3 Exit

Enter Menu Selection >> 1

Parameters Menu

 1 Attach Parameters
 2 Bind Parameters
 3 Detach Parameters
 4 Locate Parameters
 5 Put Parameters
 6 Get Parameters
 7 Set Timer Parameters
 8 Cancel Timer Parameters
 9 View Current Parameters
10 Subscribe MOT Parameters
11 Previous Menu

Enter Menu Selection >> 3

Detach all [0] ? 

Flush on detach [1] ? 

Enter queue number [205] ?

---

Exiting from the Test Utility

Listing 3-25 shows how to exit from the Test Utility.

Listing 3-25 Exit from the Test Utility

---

Main Menu

1 Parameters
2 Actions
3 Exit

Enter Menu Selection >> 3

---