BEA Logo BEA MessageQ Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

   MessageQ Doc Home   |   Installation and Configuration Guide for Windows NT   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Configuring MessageQ

 

This chapter contains the following topics that describe how to configure MessageQ message queuing buses using the Configuration Editor and message queuing groups by editing the group initialization file:

Overview of MessageQ System Configuration

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

Figure 2-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 several server processes, such as MRS/JRN, SBS, and CLS.

Figure 2-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.

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. A Group Control Process automatically creates the resources required for a group using the values and settings in the group initialization file. All MessageQ processes are started by way of the Group Control Process.

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 unique queue number, which is part of the queue address. Message queues can be temporary or permanent.

If an application needs to use a queue for a short period of time, the queue should be configured as a temporary queue. However, if an application needs to use a queue for an extended period of time (for example, a financial application that tracks the buying and selling of particular stocks), then the queue should be configured as a permanent queue.

A message queue is configured by the application developer and is managed by MessageQ. MessageQ supports three types of message queues: primary, secondary, and multireader. Table 2-1 describes these message queues.

Table 2-1 Types of Message Queues

Queue Type

Description

Primary

Serves as the main mailbox for a MessageQ application. An application is limited to one primary queue, although it may be associated with multiple secondary or multireader queues. When an application reads a message from a primary queue, the message is removed from the queue. Messages are read in first-in/first-out (FIFO) order, unless another order is specified.

Secondary

Serves as an alternate mailbox for an application to receive messages

Multireader

Serves as a central mailbox for multiple applications. This lets more than one application simultaneously attach to and read messages from the same queue.

Primary and secondary queues can be permanent or always writable. A queue that is always writable can store messages when there are no receiver programs attached. A permanent queue cannot store messages unless a receiver program is attached to it. Multireader queues are always writable, and temporary queues are only active when a receiver program is attached.

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 address have been defined, the sender application must know the queue address to direct messages containing temperature readings. The receiver application 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.

Using 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 translation is provided in the Global Name Table (%GNT) section (see Defining Name-to-Queue Translations in the Group Name Section for more information) of the MessageQ configuration file for the group. Dynamic definition means that an application has created a name-to-queue 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 naming capability is called the Naming Agent. The Naming Agent is responsible for creating entries in the name space that were created by static or dynamic definitions. In addition, the Naming Agent provides the look up capability for name-to-queue translations that are made dynamically at runtime.

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 "Defining the Naming Agent Process in the Name Section" 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 Windows NT 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 Enabling Network Connections in the Cross-Group Section and Defining the Message Routing Database in the Route Section for instructions on how to configure direct and indirect cross-group connections.

You can also specify timeout intervals for testing cross-group connections. For more information, see the "Defining Timeout Intervals for Link Drivers" topic.

Server Processes

MessageQ for Windows NT 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 2-2 shows the server processes and other components of a MessageQ message queuing group.

Figure 2-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 2-2 describes the server processes that are available to MessageQ for Windows NT.

Table 2-2 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. This server also controls journal management functions such as the handling, opening, closing, and dumping of all journal files.

Client Library Server (CLS)

Provides full message queuing support for applications running in a MessageQ Client environment

Configuring a Message Queuing Group

MessageQ for Windows NT Version 5.0 requires users to configure groups by editing a group initialization file using a text editor. This approach is now used by all MessageQ server implementations and makes group configuration data portable among all MessageQ server platforms.

Note: The Configuration Editor utility that previously shipped with the MessageQ for Windows NT product is now obsolete. In Version 5.0 configuration data is no longer stored in the NT Registry. Instead it is maintained in a group initialization file for each message queuing group. If you have existing configuration data that was created using the Configuration Editor utility, you need to convert the data to a MessageQ Version 5.0 group initialization file. Refer to the last section of Chapter 1 entitled Performing Postinstallation Tasks for information on how to use the MessageQ conversion utility.

To create a group initialization file for each group that you need to configure, make a copy of the template file called group.init and copy it to the working directory for the group. The working directory is the directory in which your application or applications are designed to execute. You can use the standard settings in the template file as the configuration data for your group, or you can change them as described in this section. You may want to add comments on your specific configuration. Use the exclamation, pound sign, semicolon, or asterisk characters (!, #, ;, or *) to as comment characters.

When you run the dmqstartup procedure, MessageQ uses the settings contained in the group initialization file to set the characteristics of the group it creates. The group.init template can be found in the following location:

Program Files\BEA Systems\BEA MessageQ\TEMPLATES\group.init

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

Table 2-3 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 Defining the Message Routing Database in the Route Section topic for more information.

%CLS

Client Library Server

Enables the support of multiple MessageQ Client connections to a single NT process using the TCP/IP transport.

See the Configuring the 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 MessageQ for UNIX and Windows NT, 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

The MessageQ group initialization file is a ASCII text file that can be created and modified using any text editor. You define parameters in the group initialization file by providing numeric values within a specified range or enabling settings to be YES or NO. To create a group initialization file for each message queuing group, make a copy of the template file, copy it to the group working directory and edit the copy. Do not edit the sample template file that is distributed with the MessageQ kit.

MessageQ also lets you modify a subset of parameters in the group initialization file at runtime. You can use the MessageQ Loader utility to dynamically reload the group initialization file without having to stop and restart MessageQ. Refer to the section Changing Group Characteristics at Runtime in Chapter 3 for a list of the parameters that you can change for a running group. Several of the modifiable parameters can only be changed if certain conditions exist. These conditions are noted in the parameter description.

Note that Windows NT services cannot access mapped drives when using the default System Account. To allow access to mapped drives, modify the service entry using the Control Panel Services applet to specify "This Account" and a "Password". The account and password must have privileges on the mapped drive.

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 that identifies the group initialization file version. (Note that this is the initialization file version, and is not equivalent to the product version number.) MessageQ for NT systems accepts group initialization files with version number 4.0 only. MessageQ uses the version number to be able to correctly parse configuration information for the message queuing group at startup.

Listing 2-1 shows a sample %VERSION section.

Listing 2-1 Sample %VERSION Section


%VERSION 4.0


Setting Group Characteristics in the Profile Section

The %PROFILE section configures 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:

Listing 2-2 shows a sample %PROFILE section:

Listing 2-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 2-4 describes the parameters of the %PROFILE section.

Table 2-4 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 up, 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-
3950

200

Selects the starting number of the pool of 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-
Unlimited

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 unlimited, you should not specify a value that is more than 30% of the virtual memory configured for the system.

GROUP_MAX_USER_QUEUE

101-3999

999

Sets the highest user queue number

GROUP_MAX_MESSAGE_SIZE

1-4194304

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 units 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.

If ENABLE_JRN is set to YES, messages are written to the PCJ as a function of the force_j argument value in the pams_confirm_msg call.

If ENABLE_JRN is set to NO, messages are not written to the PCJ regardless of the force_j argument value in the pams_confirm_msg call.

The default journaling action is to not write messages to the PCJ.

ENABLE_SBS

YES
NO

YES

Enables Selective Broadcast Services and AVAIL/UNAVAIL services

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 NT systems, message recovery is provided by the dmqjourn journal process.

The MessageQ startup procedure starts up the MRS Server only if the ENABLE_MRS parameter is set to YES in the Profile section. In addition, setting the ENABLE_JRN parameter in the Profile section to YES enables message recovery services to log messages to the auxiliary journals called the postconfirmation journal and the dead letter journal. For a complete description of MRS, refer to the Programmer's Guide.

MessageQ 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 re-sent 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 re-sent 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 to not 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 re-sent under user or application control.

When configuring the path for journal files on Windows NT systems, note that Windows NT services cannot access mapped drives when using the default System Account. Modify the service entry using the Control Panel Services applet to specify "This Account" and a "Password". The account and password must have privileges on the mapped drive.

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

Listing 2-3 Sample %MRS Section


%MRS

CACHE_PERCENTAGE         90                ! %rcv msg quota for MRS msgs

MRS_JOURNAL_PATH             C:\my\rj_path   ! recovery journal path

MRS_POST_CONFIRMATION_PATH   C:\my\pcj_path  ! post confirmation journal path

MRS_DEAD_LETTER_PATH         C:\my\dlj_path  ! dead-letter journal path

MAX_CACHE_BYTES              4194304       ! maximum number of unwritten bytes

%EOS


Configuring the 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 Windows NT User's Guide.

Listing 2-4 shows a sample %CLS section.

Listing 2-4 Sample %CLS Section


%CLS

!

!                             Max      Security
! Endpoint Transport Clients File

! 12345 TCPIP 25 C:\my\dmqclsec.txt
! 64365 TCPIP 50

%EOS


Table 2-6 describes the parameters of the %CLS section:

Table 2-6 %CLS Parameters

Parameter

Range

Default

Description

ENDPOINT

TCP/IP:
1024 - 65535

-

Identifies the TCP/IP port number that the server uses to accept incoming connections. 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. For MessageQ for NT systems, this value is TCPIP.

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, security is not enabled. The MessageQ kit provides a template file called dmqclsec.txt. To configure security, copy this file to your group working directory and modify it as appropriate for your environment. For more information about the CLS security file, see the Restricting Remote Access to CLS topic in Chapter 3.

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.

Table 2-7 describes the parameters of the %XGROUP section.

Table 2-7 %XGROUP Parameters

Parameter

Range

Default

Description

GROUP NAME

-

-

Name by which the remote MessageQ group is known to the local group

GROUP NUMBER

1-32000

-

MessageQ Group Number of the remote group

NODE/HOST

-

-

Name by which the remote node is known to the local node

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 setting is ignored on MessageQ for UNIX and Windows NT systems. It 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.

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 - 32767

-

Address (port number) of the remote link listener process. 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 an arbitrary number of 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 2-6 shows a sample %ROUTE section.

Listing 2-6 Sample %ROUTE Section


%ROUTE

!Target    Routethrough

!Group     Group

7 1
10 2

%EOS


Table 2-8 describes the parameters of the %ROUTE section.

Table 2-8 %ROUTE Parameters

Parameter

Range

Default

Description

TARGET_GROUP

1-
32,000

-

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 2-7, the %XGROUP and %ROUTE sections are correctly defined. Group2 and Group7 are not defined as target groups in the %ROUTE section, and they are correctly defined as route-through groups.

Listing 2-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 2-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 2-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, the MessageQ link drivers automatically load 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 provides an example of how route discovery allows a group to acquire routing information about other groups.

Figure 2-3 Route Discovery

In the example, Group 2 is connected to Groups 1 and 3, and the %ROUTE for Group 1 section was loaded at startup. When Group 1 sends a message to Group 3, the link driver loads the return address of the message into the %ROUTE section for Group 3. 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. As a message is written to the link sender, 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:

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 2-4. Each server can route messages to other groups without requiring clients to be directly connected to the target group of the message.

Figure 2-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 NT systems, queues numbered 90 to 100 are reserved exclusively for MessageQ.

Listing 2-9 shows a sample %QCT section.

Listing 2-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 2-9describes the parameters of the %QCT section.

Table 2-9 %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

1-3950

-

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 value 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 value 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 setting is ignored on MessageQ for UNIX and Windows NT systems.

QUEUE TYPE

P
S
M

P

Designates the queue type as follows:

P: Primary queue

P: 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

EO: 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 service 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. Create the queue security file in the following subdirectory of the MessageQ instalation directory:
\udataobj\dmq\b_BBBB\g_GGGGG\acl

where BBBB is a 4 digit bus ID and GGGGG is a 5 digit group ID

MRS_FLUSH_TIMER

-1 - Unlimited

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 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 2-10).

MRS_FLUSH_DEPTH

-1 - Unlimited

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 unlimited, 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 2-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 2-10 shows the addition of these parameters:

Listing 2-10 Sample %QCT 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 2-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 2-11 Sample %GNT Section


%GNT

!
!Name Group.Queue Scope

INVENTORY_IN    9.10            G

ACCOUNTS_PAY    0.0             G

%EOS


Table 2-10 describes the parameters in the %GNT section.

Table 2-10 %GNT Parameters

Parameter

Range

Default

Description

NAME

-

-

Equivalence name. Queue reference used by applications to refer to the queue by name.

Note: MessageQ for NT systems is case-sensitive, while MessageQ for VMS is not. Use both upper and lower case for developers porting applications from Open VMS 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 connections to the groups in which the Naming Agent runs.

Listing 2-12 shows a sample %NAM section.

Listing 2-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. The default value is 0, meaning that a naming agent should be started in the local group.

Configure the Namespace

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

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 (directory structure) 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:

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 detailed instructions on how to set an environment variable, refer to your system documentation.

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.

In addition to specifying the DMQNS_DEVICE environment variable, MessageQ also provides another environment variable called DMQNS_DEFAULT_PATH that provides path information for the name space. Using this environment variable to specify path information can be used to add a layer of path information to that specified in the group initialization file DEFAULT_NAMESPACE_PATH parameter or by the application.

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 specify 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 example illustrates how to set the default namespace path to refer to global names in a namespace created in a 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:

The following example shows static and dynamic global name definitions in the GNT section of the initialization file.

Listing 2-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 "c:" and the DEFAULT_NAMESPACE_PATH is set to "/inventory", the Naming Agent would search for the name "widgets" in:

c:/inventory/widgets

partially qualified name-The applications 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 "c:" and the DEFAULT_NAMESPACE_PATH were set to "/inventory", the Naming Agent would search for the name "test/widgets" in:

c:/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 "c:" and the DEFAULT_NAMESPACE_PATH is set to "/inventory", the Naming Agent would search for the name "/production/test/widgets" in:

c:/production/test/widgets

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

Listing 2-14 Sample Global Names and Their Resolution


Name Used in API  DEFAULT_NAMESPACE_PATH  Name Searched

toto			bus1		C:/dmq/dmqns/bus1/toto

mypath/toto			bus1		C:/dmq/dmqns/bus1/mypath/toto

/anotherpath/toto			bus1		C:/anotherpath/toto

toto/bus1C:			/bus1		/toto

/mypath/toto/bus1C:			/bus1		/mypath/toto

/anotherpath/toto			/bus		C:/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 applications developers to send and receive messages between applications to:

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. To invoke the Test utility, double click on the Test utility icon.

Figure 2-5 illustrates the use of the Test utility to send a message on a Windows NT system.

Figure 2-5 MessageQ Test Utility