The following topics are covered in this chapter:
The MessageQ SBS Server must be running for applications to use either the Selective Broadcast or AVAIL/UNAVAIL services. To start the SBS Server for a message queuing group, edit the Profile section of the DMQ$INIT.TXT file and set the symbol ENABLE_SBS set to YES, and then start the message queuing group. The ENABLE_SBS parameter is set to YES by default in the group initialization file template supplied with MessageQ for OpenVMS. Example 7-1 shows the ENABLE_SBS parameter in the Profile section of the group initialization file.
Example 7-1 SBS Enable Parameter
%PROFILE ***** Profile Parameters ***** * ... ENABLE_MRS YES ! Enable MessageQ Message Recovery Services ENABLE_JRN YES ! Enable Dead letter / Post Confirmation journal ENABLE_SBS YES ! Enable MessageQ Selective Broadcast Services ... * %EOS
Use the SBS Server initialization section of DMQ$INIT.TXT to configure the broadcasting operation of the local SBS Server. This section of DMQ$INIT.TXT begins with %SBS.
This section covers the following information:
A Multipoint Outbound Target (MOT_xxxx) is a queue address that is associated with a list of targets specified in the first four fields of the SBS Server Initialization Section of the DMQ$INIT.TXT file. MOT addresses are divided into two ranges, PRIVATE and UNIVERSAL, which control the scope of broadcast messages to distribution by the local SBS server or to all SBS servers in the MessageQ network.
The PRIVATE range includes addresses from MOT_LOW to MOT_MID -1. MessageQ broadcasts messages within the PRIVATE range using a list maintained by the local SBS Server.
The UNIVERSAL range includes addresses from MOT_MID to MOT_HIGH. MessageQ broadcasts messages within the UNIVERSAL range to all SBS servers on the message queuing bus and then each SBS server broadcasts them locally to all interested target queues.
Note:
Prior to this version of MessageQ for OpenVMS, the values for MOT_LOW and MOT_HIGH were adjustable, and MOT_MID was fixed at 5000. For this release of SBS, MOT_LOW and MOT_HIGH are now fixed as shown below:
| Parameter | Description |
|---|---|
| MOT_LOW | 4000 - Private MOT address are in the range between, and including 4000-4900. Messages broadcast to these address will remain local to the queuing group. |
| MOT_MID | 5000 - Note: MOT address settings 4901 to 5099 are reserved for MessageQ . |
| MOT_HIGH | 6000 - Universal MOT address are in the range between, and including 5100-5999. Messages broadcast to these address will be transmitted outside the queuing group. |
Note:
MOT ranges 4901 to 4999 and 5000 to 5099 are reserved for MessageQ .
7.3.2 Configuring Optimized Ethernet Mode
The optimized Ethernet mode on the SBS server utilizes the hardware
multicasting available with Ethernet controllers. Therefore, instead of
simulating broadcasting by sending a message to each adjacent SBS
server over the standard MessageQ links, it broadcasts one message to
all listening systems on the bus. This mode has an advantage of
scalability whereby any number of receiver systems can receive the same
MessageQ messages.
Example 7-2 shows the SBS Server initialization section of the group initialization file template.
Example 7-2 %SBS Initialization File Section
%SBS ******* SBS Server Initialization Section ************ * * NOTE: Heartbeat interval is in units of 1 millisecond * HEARTBEAT 1000 ! default is 1 second * * ---- Service ---- * ID Prot/Xport COMM_SERVICE 10 DG/DMQ ! default emulated broadcast path GROUPS * ! all known server groups REGISTER * ! all universal MOTs END_COMM_SERVICE * * ---- Service ---- * ID Prot/Xport COMM_SERVICE 0 DG_OLD/ETH ! datagram messaging over optimized Ethernet DEVICE_1 ESA0: ! VMS device name of the Ethernet board (rail A) DEVICE_2 EZA0: ! VMS device name of the Ethernet board (rail B) DRIVER_BUFFERS 16 ! # of VMS Ethernet driver buffers to preallocate[10-255] * * < <<<<<<<<<<<<<<<<< Warning >>>>>>>>>>>>>>>>>>> * The protocol and Ethernet addresses show below are not registered * and are not guaranteed to be conflict free. Use them with discretion. * |------ MCA ----| |Prot #| CNTRL_CHAN AB-AA-34-56-78-90 81F0 74 DATA_CHAN AB-12-34-56-78-91 81F1 75 * * NOTE: MAB = Message Assembly Buffer. Each MAB requires area for * a large message buffer, plus overhead of 150 bytes. * * Default Default Heartbeat * Transmit SILO Receive SILO Maximum Poll Dead Poll * MOT (in MABs) (in MABs) Heartbeat Interval Interval REGISTER 5101 1 5 4 10 10 REGISTER 5102 1 5 4 10 10 REGISTER 5156 1 5 6 10 10 * END_COMM_SERVICE * * ---- Service ---- * ID Prot/Xport COMM_SERVICE 0 RP/ETH ! retransmission protocol over optimized Ethernet DEVICE_1 ESA0: ! VMS device name of the Ethernet board (rail A) DEVICE_2 EZA0: ! VMS device name of the Ethernet board (rail B) DRIVER_BUFFERS 16 ! # of VMS Ethernet driver buffers to preallocate[10-255] * * < <<<<<<<<<<<<<<<<< Warning >>>>>>>>>>>>>>>>>>> * The protocol and Ethernet addresses show below are not registered * and are not guaranteed to be conflict free. Use them with discretion. * |------ MCA ----| |Prot #| |UCB #| CNTRL_CHAN AB-AA-34-56-78-90 81F0 74 DATA_CHAN AB-12-34-56-78-90 81F2 76 * * NOTE: MAB = Message Assembly Buffer. Each MAB requires area for * a large message buffer, plus overhead of 150 bytes. * * Default Default Heartbeat * Transmit SILO Receive SILO Maximum Poll Dead Poll * MOT (in MABs) (in MABs) Heartbeat Interval Interval REGISTER 5104 30 15 4 10 10 REGISTER 5105 10 6 4 10 10 * END_COMM_SERVICE * %EOS
Note:
There is a convert utility which will assist the migration of older, existing DMQ$INIT files into the new MessageQ for OpenVMS Version 4.0A COMM_SERVICE format See Section 2.5 .
| Parameter | Description |
|---|---|
| HEARTBEAT | A numeric field which specifies granularity of the heartbeat timer used to detect sequence gaps and lost packets. The timer is measured in units of one millisecond. The default is 1000 or one second. This value is used by the recovery protocol in conjunction with the poll and dead poll interval described below |
| COMM_SERVICE | A 2-field record. The first field is a unique integer between 0 and 10 to indicate which communication service is being defined. In version 4.0, the only services available are 0-10. The COMM_SERVICE number is intended to be used to control the priority of one path over another when multiple paths to a group are detected. The lower the number the higher the priority. Services 1-9 are optional and correspond to the old DMQ$INIT Ethernet SET command numbers. Service 10 is reserved for the default unoptimized MessageQ broadcasting, must be set to the DMQ transport at this time. The second field indicates the method of server-to-server communications that this service is to use. The first part is the protocol type and the second is the transport type. The two parts must be separated with a "/" (slash) character. |
| Protocols: |
DG ---Datagram protocol.
Messages are sent "best try" with failures detected by sequence gaps. DG_OLD---Datagram protocol. Same as DG but uses the older protocol used in MessageQ for OpenVMS V3.2 and earlier releases. Only valid in conjunction with the "ETH" transport. RP ---Retransmit Protocol. Messages are sent "best try" with failures recovered via retransmit request protocol up to a depth of messages that can be set by the user. |
| Transports: |
DMQ ---MessageQ messaging.
Messages are sent using MessageQ as the transport medium. ETH ---Direct Ethernet. Messages are sent using the hardware multicast capabilities of the Ethernet controller. |
| GROUPS | This is a numeric field containing a single MessageQ group number per line. This is used to indicate which groups should be broadcasted to. In V4.0 the required setting is an "*" (asterisk), used to indicate all known groups. This keyword is only useful when MessageQ is used as a transport. The default is "*". |
| DEVICE_1
DEVICE_2 |
This is a text field which specifies the name of the Ethernet controller to use for each rail. Single-rail configurations only use the "DEVICE_1" keyword whereas dual-rail configurations use both. This keyword is useful only in conjunction with the Ethernet transport. In a given init file, only one setting may be entered for DEVICE_1/DEVICE_2. If multiple settings are entered, only the last will be used. |
| DRIVER_BUFFERS | This is a numeric field containing the number of buffers that the system Ethernet controller should use to buffer incoming packets. On VMS, this directly affects the amount of non-paged pool allocated to each channel by the Ethernet controller. The default is 16. In a given init file, only one setting may be entered. If multiple settings are entered, only the last will be used. |
| CNTRL_CHAN | A 3-field record used to specify the Ethernet protocol/address pair for control information. The first field identifies the Ethernet hexadecimal multicast address (the low-order bit of the first byte must be set) that the SBS Server uses in the Ethernet transport mode. The second hexadecimal field is a unique protocol number used by the SBS Servers. The address/protocol pair for the SBS control channel must be consistent in all cooperating SBS Servers and must be distinguishable from other address/protocol pairs (for example, LAT, DECnet, local area VMSclusters, and so on). |
| DATA_CHAN | A 2-field record used to specify the data channel for optimized communications. The address/protocol pair for the SBS data channel must be consistent in all cooperating SBS Servers and must be distinguishable from other address/protocol pairs (for example, LAT, DECnet, local area VMSclusters, and so on). The first field is the hexadecimal Ethernet multicast address in the form of XX-XX-XX-XX-XX-XX. The second field is the hexadecimal Ethernet protocol number. |
| REGISTER | A 1-field or 6-field record used to add a subscription ID (MOT) to the communication service. The number of fields depends on the type of service being specified. For DG/DMQ it is a 1-field record; all others are 6-field. |
| MOT | The subscription ID that identifies the unique broadcast stream. For Datagram protocols using the DMQ transport, a wildcard "*" (asterisk) can be used to indicate all possible subscription IDs. Care should be taken as to number of MABs a given Subscription ID has since it has direct effect on the total amount of virtual memory that the SBS Server uses. |
| Transmit Silo | The number of Message Assembly Buffers (MABs) used to manage retransmission requests. For Datagram protocols this will always be forced to one. Valid ranges 0 to 100. |
| Receive Silo | The number of MABs to use for simultaneous multi-packet receptions. Valid ranges 0 to 100. For DG_OLD protocols this will always be forced to 5. |
| Maximum Heartbeat | The number of unacknowledged Polls before a sender is considered dead. Valid ranges 0 to 100. |
| Poll Interval | The number of MOT heartbeat intervals without an intervening message before a poll request is generated. Valid ranges 0 to 100. |
| Dead Poll Interval | Used as a multiplier to the Poll Interval to reduce the number of Polls sent to an unresponsive or inactive group. Valid ranges 0 to 100. |
| END_COMM_SERVICE | This keyword is used to close a communication service description block. |
Example 7-3 Ethernet Broadcasting Parameters in%QCT Initialization File Section
%QCT ***** Queue Configuration Table ****** * * ---Pool Quota--- UCB Q Q Confrm Perm Name Check * Queue Name Num Bytes Msgs Ctrl Send Type Own Style Act Scope ACL *------------------- ---- ------- ---- ---- ---- ---- ---- ----- ---- ----- ---- ... * * SBS Server uses the following UCB numbers for Optimized Delivery * SBS_ETH_CONTROL 74 0 0 . E . . . . L N SBS_ETH_CHAN1 75 0 0 . E . . . . L N SBS_ETH_CHAN2 76 0 0 . E . . . . L N * ... %EOS
| Parameter | Description |
|---|---|
| %QCT | There must be entries in the queue configuration table (QCT) section of the DMQ$INIT.TXT file for the CNTRL_CHAN and each of the DATA_CHAN entires. These entries must correspond to the correct queue address, have zero quota, and have the E flag set in the UCB Send Field. |
A registry of reserved protocols and multicast addresses is maintained by the Xerox Corporation. Choose protocols and multicast addresses so that they do not conflict with other users of the local area network (LAN). See Chapter 9 of the OpenVMS I/O User's Reference Manual.
The following are some requirements and restrictions imposed on SBS:
The MessageQ application programming interface uses a numeric queue address to refer to a specific message queue within a message queuing group. The MessageQ naming feature enables a name to be associated with a numeric queue address to separate the application from the underlying network configuration. Names are defined as local when they are only shared by applications running in the same message queuing group. Global names can be used by any application on the message queuing bus. MessageQ includes the ability to define both local and global names.
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 names space. It creates the process namespace 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. Read this chapter to learn how
to configure the MessageQ built-in global naming capability and how to
use Distributed Name Services (DNS).
8.1 Configuring MessageQ Global Naming
The first step in configuring global naming it to 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
Section 8.1.1 .
8.1.1 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 allows the user to define a primary and an alternate Naming Agent group. MessageQ allow the definition of up to 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. Example 8-1 shows a sample %NAM section.
Example 8-1 Sample%NAM Section
%NAM **************** Naming Agent Section ******************** * This section consists of a maximum of 2 entries consisting of * a keyword, "NA_GROUP", followed by the group number of a group where * a naming agent is running * %NAM NA_GROUP 10 NA_GROUP 28 %EOS
Valid ranges for the NA_GROUP parameter are 0 to 32,000. A value of 0
indicates that a Naming Agent should be started in the local group.
Note that any Naming agent startup failures will be logged in
DMQ$LOG:DMQ$NA_SERVER_bbbb_gggg.LOG, not the group's
Event Log.
8.1.2 Configure a Lightweight Namespace
MessageQ for OpenVMS supports the creation of both a lightweight namespace that is included with MessageQ and a DNS namespace. To create the lightweight namespace, MessageQ uses a flat file system by creating the directory in which the MessageQ Naming Agent will maintain the namespace. On MessageQ for OpenVMS the following default lightweight namespace directory is created during installation:
DMQ$DISK:[DMQ$V40.DMQNS]
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 namespace. Therefore, when you configure your namespace for use by two Naming Agents that run on different systems, it must use a shared file system such that is accessible to both Naming Agents.
After you create the namespace, you must set the DMQNS_DEVICE environment variable to specify a device name for the namespace because access to the MessageQ lightweight namespace 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 namespace. 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 namespace.
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 for Unix and MessageQ for Windows NT also provide another
environment variable called DMQNS_DEFAULTPATH that provides path
information for the namespace. Using this environment variable to
specify path information adds a layer of path information to that
specified in the group initialization file DEFAULT_NAMESPACE_PATH
parameter or by the application. However, the DMQNS_DEFAULTPATH
environment variable is not supported on OpenVMS.
8.1.3 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 namespace. The following syntax shows how to set the default namespace to be created and maintained in the directory called /DMQNS/mydir.
%PROFILE ***** Profile Parameters ***** * ... DEFAULT_NAMESPACE_PATH /DMQNS/mydir/ * %eos
For example, for testing purposes, you might set this parameter to look at a copy of the production namespace that you store in your own development directory. However, when the application is deployed into production, the application will reference the common namespace shared by all production systems.
Note:
The DEFAULT_NAMESPACE_PATH is case-sensitive. This is important to note for VMS groups that are referencing a namespace located on a Unix system.
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:
Example 8-2 shows static and dynamic global name definitions in the GNT section of the initialization file.
Example 8-2 Sample Group Name Table for Global Naming
%GNT ********* Group Name Table Section ********************* * * Queue 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:
/DUA0/inventory/inventory.dnf or DUA0:[inventory]inventory.dnf
/DUA0/inventory/test/test.dnf or DUA0:[inventory.test]test.dnf
/DUA0/production/test/test.dnf or DUA0:[production.test]test.dnf
The use of unqualified, partially qualified, and fully qualified names gives application developers significant flexibility in using global name references. Example 8-2 provides several more examples of how global names are resolved. In this example, the DMQNS_DEVICE environment variable is set to "DUA0:[DMQ.DMQNS]".
| Name Used in API | DEFAULT_NAMESPACE_PATH | Name Searched |
| toto | bus1 | /DUA0/DMQ/DMQNS/bus1/toto |
| mypath/toto | bus1 | /DUA0/DMQ/DMQNS/bus1/mypath/toto |
| /anotherpath/toto | bus1 | /DUA0/DMQ/DMQNS/anotherpath/toto |
Refer to the BEA MessageQ Programmer's Guide for more information on designing
applications to use the MessageQ global naming feature.
8.1.5 Using DNS with Global Naming
To use Distributed Name Service (DNS) naming with MessageQ you must do the following: