Creating Global Names

 

The BEA MessageQ application programming interface uses a numeric queue address to refer to a specific message queue within a message queuing group. The BEA MessageQ naming feature enables a name to be associated with a numeric queue address to separate the application from the underlying network configuration. Local names are shared only by applications that run in the same message queuing group; global names can be used by any application on the message queuing bus. BEA 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, BEA MessageQ automatically creates the group namespace. It creates the process namespace when an application attaches to the message queuing bus.

To enable your application to use global (bus-wide) naming, you must perform additional configuration steps. This chapter explains how to configure the BEA MessageQ built-in global naming capability and how to use Distributed Name Services (DNS).

Configuring BEA MessageQ Global Naming

The first step in configuring global naming it to decide the group or groups in which the Naming Agent will run. BEA 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 Configure Groups to Run or Use the Naming Agent.

Configure Groups to Run or Use the Naming Agent

The BEA MessageQ Naming Agent is the BEA MessageQ Server that maintains the namespace for name-to-queue address translations and performs the run-time 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. BEA MessageQ allow the definition of up to two Naming Agents for each message queuing bus.

When BEA 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, BEA 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 7-1 shows a sample %NAM section.

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

Configure a Lightweight Namespace

BEA MessageQ for OpenVMS supports the creation of both a lightweight namespace, which is included with BEA MessageQ, and a DNS namespace. To create the lightweight namespace, BEA MessageQ uses a flat file system by creating the directory in which the BEA MessageQ Naming Agent will maintain the namespace. On BEA MessageQ for OpenVMS the following default lightweight namespace directory is created during installation:

DMQ$DISK:[DMQ$V50.DMQNS] 

To use global naming, you must create a namespace on the nodes on which the Naming Agents will run. BEA 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 BEA 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:

• For Windows NT, set the variable to a drive letter followed by a colon (for example. C:) or a fully qualified pathname (for example, \\machine\share).

• For OpenVMS, DMQNS_DEVICE is a logical (defined in DMQ$BOOT.COM), it should be set to the root device and/or directory for the namespace path. The default is DMQ$DISK:[DMQ$V50].

• For UNIX, set the variable 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 namespace.

For environments that 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 BEA MessageQ namespace.

Default Namespace Path Definition

BEA MessageQ uses the DMQNS_DEFAULTPATH logical name to define path information for the namespace. This logical name is defined in DMQ$BOOT.COM. Using the DMQNS_DEFAULTPATH logical name allows you to remove the DEFAULT_NAMESPACE_PATH definition from the DMQ$INIT.TXT file, yet still define the path information needed by the Naming Agent Server.

The Naming Agent Server only uses the DMQNS_DEFAULTPATH logical if DEFAULT_NAMESPACE_PATH is not defined in the DMQ$INIT.TXT file. ( The DEFAULT_NAMESPACE_PATH parameter is commented out in the DMQ$INIT.TXT file provided in the [DMQ$V50.USER.TEMPLATE] subdirectory.) If the DEFAULT_NAMESPACE_PATH is defined, then the DMQNS_DEFAULTPATH logical is ignored.

Configure a Default Namespace Path for Each Group

To use a global name, specify at least some portion of the path name. Path information can be supplied by the application, either use the DMQNS_DEFAULTPATH logical name, or use the DEFAULT_NAMESPACE_PATH parameter in the %PROFILE section of the group initialization file 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.

To define a default namespace path as a directory called /DMQNS/mydir using the DMQNS_DEFAULTPATH logical name, enter the following command:

$ define DMQNS_DEFAULTPATH /DMQNS/mydir

The following syntax shows how to use the DEFAULT_NAMESPACE_PATH parameter in the %PROFILE section of the group initialization file 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 

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.

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.

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 run-time using the pams_bind_q function.

Listing 7-2 shows static and dynamic global name definitions in the %GNT section of the initialization file.

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

• unqualified name-The application uses only the queue name such as widgets and does not specify the path. The Naming Agent automatically assigns a prefix to the name with the value of the environment variable DMQNS_DEVICE. For example, if the DMQNS_DEVICE logical is set to DUA0: and the DEFAULT_NAMESPACE_PATH is set to /inventory, the Naming Agent would search for the name widgets in:

  /DUA0/inventory/inventory.dnf 

  or

  DUA0:[inventory]inventory.dnf 

• partially qualified name-The applications specifies the queue name and a portion of the path name. The Naming Agent automatically assigns a prefix to the pathname and queue name with the device specified as the DMQNS_DEVICE environment variable and the setting of the DEFAULT_NAMESPACE_PATH parameter. For example, if the DMQNS_DEVICE logical is set to DUA0: and the DEFAULT_NAMESPACE_PATH is set to /inventory, the Naming Agent would search for the name test/widgets in:

  /DUA0/inventory/test/test.dnf 

  or

  DUA0:[inventory.test]test.dnf 

• fully qualified name-The application specifies that the name is a fully qualified name using a forward slash (/) as the first character of the name. When the first character of a name begins with a forward slash (/), the Naming Agent does not assign a prefix to 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 pathname and queue name. For example, if the DMQNS_DEVICE logical is set to DUA0: and the DEFAULT_NAMESPACE_PATH is set to /inventory, the Naming Agent would search for the name /production/test/widgets in:

  /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. Table 7-1 provides several more examples of how global names are resolved. In this example, the DMQNS_DEVICE environment variable is set to DUA0:[DMQ.DMQNS].

  Table 7-1 Sample Global Names and Their Resolution

  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
  /otherpath/toto	bus1	/DUA0/DMQ/DMQNS/otherpath/toto

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

Using DNS with Global Naming

To use Distributed Name Service (DNS) naming with BEA MessageQ you must:

• Verify the presence of a DNS server on your network.

• Set your DEFAULT_NAMESPACE_PATH in the group initialization file to point to the DNS root directory. For example, if the node name is NODE1, the clearinghouse is NODE1_CH, the namespace is NODE1_NS, and the directory is DMQ, then the DEFAULT_NAMESPACE_PATH would be NODE1_NS:.DMQ.

Global Names that would generally be loaded into the lightweight namespace are loaded into the DNS namespace. The Manager Utility, DMQ$MGR_UTILITY, can be used to load names into the DNS namespace, and to browse this namespace. DMQ$MGR_UTILITY supersedes the DMQ$NA_MGR.EXE program provided in previous releases of BEA MessageQ.

The Manager utility updates the address of any name that has the G attribute in the %GNT section or %QCT section of the DMQ$INIT.TXT file, unless is dynamically bound to a particular queue in the group. Dynamically bound names are initialized to group 0 queue 0 and are modified by a call to pams_bind_q. To use dynamic binding, declare the names in the group where the dynamic binding will occur. This operational step prevents another group's startup from reinitializing the names.

Managing the Global Namespace

You can browse the global namespace, created names, and set and cleared addresses with the BEA MessageQ Manager utility program, DMQ$MGR_UTILITY. (The capabilities of the Naming Agent Manager utility have been incorporated into the Manager utility.) For information on using the Manager utility, see Using BEA MessageQ System Management Utilities.

Viewing a Group's Cache

The DG command (Display GROUP name table) in the main menu of the Manager utility (DMQ$MGR_UTILITY.EXE) allows the user to view all local and cached global names. See Listing 7-3 for a sample group name table.

Listing 7-3 DMQ$MGR_UTILITY Display Group Name Table

---

Bus:99   Group:40      MessageQ Manager Utility     Thu Jan  8 12:47:48 1998 
                            Group Name Table 
 
 Entry  Scope     ID        Name 
    1     G    40.00001    /DMQNS/GLOBAL_TEST 
    2     G    40.00005    /DMQNS/GLOBAL_TEST_QUEUE5 
    3     G    40.00006    /DMQNS/GLOBAL_TEST_QUEUE6 
    4     G    40.00002    /DMQNS/QUEUE_2 
    5     L    40.00091    ALL_UCBS 
    6     L    40.00099    AVAIL_SERVER 
    7     L    40.00100    COM_SERVER 
    8     L    40.00100    CONNECT_SERVER 
    9     L    40.00151    DCL_BY_Q_NAME 
   10     L    40.00096    DEAD_LETTER_QUEUE 
   11     L    40.00100    DECLARE_SERVER 
   12     L    40.00153    DECNET_LD 
   13     L    40.00191    DMQ_FULLTEST_PQ 
   14     L    40.00192    DMQ_FULLTEST_SQ 
   15     L    40.00150    DMQ_LOADER 
[More] 
 <CR> to continue: 

---

Global Name Examples

This section provides some examples of global name caching on BEA MessageQ for OpenVMS. These examples use pams_locate_q with the following information defined in the group initialization file (DMQ$INIT.TXT):

%PROFILE
DEFAULT_NAMESPACE_PATH  /DMQNS/
%EOS

%GNT
myglobalqueue   115.1    G
%EOS

%NAM
NA_GROUP 0
%EOS

Attempting to locate myglobalqueue without specifying PSEL_TBL_BUS in the namespace list results in a PAMS__NOOBJECT failure:

locate "myglobalqueue" with PSEL_TBL_GRP returns PAMS__NOOBJECT

However, attempting to locate myglobalqueue using PSEL_TBL_BUS in the namespace list results in success:

locate "myglobalqueue" with PSEL_TBL_BUS returns 115.1

Global names have the value in DEFAULT_NAMESPACE_PATH added as a prefix when they are cached. Therefore, the name will not be found in the local cache unless PSEL_TBL_BUS is either included in the namespace list or the fully prefixed name is specified:

locate "myglobalqueue" with PSEL_TBL_BUS returns 115.1
locate "myglobalqueue" with PSEL_TBL_GRP returns PAMS__NOOBJECT
locate "/DMQNS/myglobalqueue" with PSEL_TBL_GRP returns 115.1
locate "/DMQNS/myglobalqueue" with PSEL_TBL_PROC returns 115.1
locate "myglobalqueue" with PSEL_TBL_GRP,PSEL_TBL_BUS returns 115.1

Combining PSEL_TBL_BUS with PSEL_TBL_GRP results in the DEFAULT_NAMESPACE_PATH being automatically added as a prefix to the queue name before any table lookups begin.

If any of the following table names are included in the namespace list, then the DEFAULT_NAMESPACE_PATH is automatically added as a prefix to the queue name:

• PSEL_TBL_DNS_CACHE

• PSEL_TBL_DNS_LOW

• PSEL_TBL_DNS_MED

• PSEL_TBL_DNS_HIGH

• PSEL_TBL_BUS

• PSEL_TBL_BUS_LOW

• PSEL_TBL_BUS_MED

• PSEL_TBL_BUS_HIGH

If an application contains one of the above table names, but does not have a Naming Agent defined, then you must comment out DEFAULT_NAMESPACE_PATH in the %PROFILE section of the DMQ$INIT.TXT file to prevent the DEFAULT_NAMESPACE_PATH from being added as a prefix to the queue name.

If the DMQ$INIT.TXT file contains global queue name definitions, but does not have a Naming Agent defined, then those queue names are not resolved because global name lookups have been moved out of the process's context and into the Naming Agent. (This is different behavior than in BEA MessageQ for OpenVMS version 3.2B.)

The DMQNS_DEFAULTPATH logical name is supported and is defined in DMQ$BOOT.COM. Using the DMQNS_DEFAULTPATH logical name allows you to remove the DEFAULT_NAMESPACE_PATH definition from the DMQ$INIT.TXT file, yet still define the path information needed by the Naming Agent Server. The rules for defining this logical are the same rules documented for defining the DEFAULT_NAMESPACE_PATH in the DMQ$INIT.TXT file. The Naming Agent Server only uses this logical if a DEFAULT_NAMESPACE_PATH is not defined in the DMQ$INIT.TXT file. If the DEFAULT_NAMESPACE_PATH is defined, then the DMQNS_DEFAULTPATH logical is ignored.

Defining DMQNS_DEFAULTPATH allows name lookups for both local and global names to use the same pams_locate_q API call with a namespace list of PSEL_TBL_PROC, PSEL_TBL_GROUP, and PSEL_TBL_BUS. Assuming that the DEFAULT_NAMESPACE_PATH in DMQ$INIT.TXT is not defined, no path name is added as a prefix to the queue name at the API level. This provides flexiblity for applications that require backwards compatibility with BEA MessageQ version 3.2B applications.

Below are some examples of global name caching using pams_locate_q with the following information defined in the group initialization file (DMQ$INIT.TXT) and the group boot file (DMQ$BOOT.COM).

DMQ$INIT.TXT
.
.
.
%PROFILE
*DEFAULT_NAMESPACE_PATH  /DMQNS/   ! COMMENTED OUT
%EOS
.
.
.
%GNT
myglobalqueue           115.1    G
mylocalqueue              1.5    L
%EOS
.
.
.
%NAM
NA_GROUP 0
%EOS


DMQ$BOOT.COM
.
.
.
    $!    -- Namespace root directory 
    $!
    $       dmq_lnm DMQNS_DEVICE        dmq$disk:['root']
    $!
    $!    -- Namespace default path (based off of DMQNS_DEVICE)
    $!
    $       dmq_lnm DMQNS_DEFAULTPATH   "/DMQNS/"
.
.
.

Attempting to locate myglobalqueue without specifying PSEL_TBL_BUS in the namespace list will result in a PAMS__NOOBJECT failure:

locate "myglobalqueue" with PSEL_TBL_GRP returns PAMS__NOOBJECT

However, attempting to locate myglobalqueue with PSEL_TBL_BUS in the namespace list will result in a success:

locate "myglobalqueue" with PSEL_TBL_BUS returns 115.1

Global names are prefixed with the DEFAULT_NAMESPACE_PATH when they are cached. However, in this example the DEFAULT_NAMESPACE_PATH is not defined (or NULL). Therefore, the name will be cached without a namespace path prefix.

locate "myglobalqueue" with PSEL_TBL_BUS returns 115.1
locate "myglobalqueue" with PSEL_TBL_GRP returns 115.1
locate "/DMQNS/myglobalqueue" with PSEL_TBL_GRP returns PAMS__NOOBJECT
locate "/DMQNS/myglobalqueue" with PSEL_TBL_PROC returns PAMS__NOOBJECT
locate "myglobalqueue" with PSEL_TBL_GRP,PSEL_TBL_BUS returns 115.1

Attempting to locate mylocalqueue without specifying PSEL_TBL_GRP in the namespace list will result in a PAMS__NOOBJECT failure:

locate "mylocalqueue" with PSEL_TBL_BUS returns PAMS__NOOBJECT

However, attempting to locate mylocalqueue with PSEL_TBL_GRP in the namespace list will result in a success:

locate "myglobalqueue" with PSEL_TBL_GRP returns 1.5

Because the DEFAULT_NAMESPACE_PATH in this example is not defined (or NULL), there is no namespace path prefix appended on the queue name during lookup even though PSEL_TBL_BUS is in the namespace list.

locate "mylocalqueue" with PSEL_TBL_BUS returns PAMS__NOOBJECT
locate "mylocalqueue" with PSEL_TBL_GRP returns 1.5
locate "mylocalqueue" with PSEL_TBL_PROC returns 1.5
locate "mylocalqueue" with PSEL_TBL_GRP,PSEL_TBL_BUS returns 1.5

Defining Type and Class Codes

BEA MessageQ supports defining symbolic names for type and class codes within BEA MessageQ application programs and the BEA MessageQ Script facility. These codes are carried in the DMQ header file and are accessed using parameters of the API services.

The DMQ$USER:DMQ$TYPCLS.TXT file contains definitions of the following reserved type and class codes:

• MRS

• PAMS

• SBS_SERVER

• AVAIL_SERVER

• ETHERNET

It also contains definitions of:

• Generic UCB types and classes

• DEMO type codes for DEMO_IO_SERVER

• LU62 type codes for LU6.2 UCB

• Message types for LU6.2 services

• Message types for generic port server

You can add codes to the DMQ$TYPCLS.TXT file when you run DMQ$CUSTOMIZE (from the BEA MessageQ main menu) and enter YES in response to the following question:

Create language specific TYPE_CLASS include files [Y/N] (N)? 

Listing 7-4 is an excerpt from the DMQ$TYPCLS.TXT file that shows the PAMS class and type codes section of the file.

Listing 7-4 Excerpt from DMQ$TYPCLS.TXT

---

************************************************************** 
*                                                            * 
*        PAMS   Class and Type codes (900-999)               * 
*                                                            * 
************************************************************** 
#MSG_CLAS_PAMS 29           * define PAMS class * 
 
* define PAMS type codes * 
msg_type_timer_expired           -900 
msg_type_list_all_q_req          -960 
msg_type_list_all_q_resp         -961 
msg_type_enable_q_notify_req     -962 
msg_type_enable_q_notify_resp    -963 
msg_type_disable_q_notify_req    -964 
msg_type_disable_q_notify_resp   -965 
msg_type_q_update                -966 
msg_type_locate_q_rep            -972 
msg_type_linkmgt_req             -975 
msg_type_linkmgt_resp            -976 
msg_type_declare_sq              -980 
msg_type_undeclare_sq            -981 
msg_type_allocated_sq            -982 
msg_type_msg_status              -983 
msg_type_dmq_server_nak          -989 
msg_type_enable_notify           -990 
msg_type_disable_notify          -991 
msg_type_process_dcl             -992 
msg_type_process_exit            -993 
msg_type_list_dcls               -994 
msg_type_list_all_entrys         -995 
msg_type_list_all_connections    -996 
msg_type_list_all_groups         -997 
msg_type_link_lost               -998 
msg_type_link_complete           -999  

---

Table 7-2 describes types of statements used in the DMQ$TYPCLS.TXT file.

Table 7-2 DMQ$TYPCLS.TXT Statements

Statement Type	Description
Comments	Begin with an asterisk (*) and can start anywhere on a line
Blank lines	Transferred as is
Symbol declarations	Type of Symbol	Prefix
	Message class	msg_clas_30000 through _32767
	Message type	msg_type_

Note: The only valid separators for this file are spaces and tabs.