![]() |
![]() |
|
|
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:
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:
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:
/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. 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:
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:
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:
It also contains definitions of:
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.
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|