Global Names that would normally be loaded into the lightweight namespace will be loaded into the DNS namespace. The Naming Agent Manager Utility, DMQ$NA_MGR.EXE, can be used to load names into the DNS namespace, and to browse this namespace. DMQ$NA_MGR supersedes the DMQ$DNS_LOAD.EXE program provided in previous releases of MessageQ.
The loader program will update 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().
If you want to use dynamic binding, you should to declare the names in
the group where the dynamic binding will occur. This operational step
will prevent another group's startup from reinitializing the names.
8.1.6 Using the Naming Agent Manager Utility to Manage the Global Namespace
The global namespace can be browsed, names created, and addresses set and cleared with the Naming Agent Manager utility program. Define a foreign command as follows:
$ dmq$na_mgr:==$DMQ$EXE:DMQ$NA_MGR.EXE
pass the group number of the group where the Naming Agent is running into DMQ$NA_MGR as the first argument. For example to manage the names served by the Naming Agent in group 4, use the following command:
$dmq$na_mgr 4
The following menu appears when the NA Manager utility starts without a command parameter.
-------------------------------------------------------------------
MessageQ Naming Agent Manager Utility
usage: dmqnamgr group [command name [argument]]
group: naming agent group to talk to (0 for current group)
command: PATH get naming agent default path
LIST get entries matching a pattern
GET get entry data
ZERO zeroes entry address
ADDRESS g.q set entry address to g.q
[the first letter of the command is sufficient]
name: name of the entry to work with
example: dmqnamgr 0 G QUEUE_NAME
-------------------------------------------------------------------
A sample session that lists the namespace, gets a name, and zeros its address is shown below.
-------------------------------------------------------------------
$! list names known by the local naming server
$! by entering group 0 as the first parameter
$
$ dmq$na_mgr 0 L
MessageQ Naming Agent Manager Utility
Enter entry name (return to go back) : *
Enter entry name (return to go back) : *
GLOBAL_TEST
GLOBAL_TEST_QUEUE5
GLOBAL_TEST_QUEUE6
GLOBAL_TEST_BIND
QUEUE_2
...
$
$ !get into the menu, look at the name GLOBAL_TEST
$ !clear its address and exit
$
$ dmq$na_mgr 0
MessageQ Naming Agent Manager Utility
Menu choices :
P[ath]
G[et]
L[ist]
A[ddress]
Z[ero]
H[ierarchy of directories]
Enter P,G,L,A,Z,H or return to exit : G
Enter entry name (return to go back) : GLOBAL_TEST
Name : /DMQ$DISK/DMQ$V40/DMQNS/GLOBAL_TEST
Address : 40.1
Time last modified : Thu Jan 8 12:31:11 1998
Menu choices:
P[ath]
G[et]
L[ist]
A[ddress]
Z[ero]
H[ierarchy of directories]
Enter P,G,L,A,Z,H or return to exit : Z
Enter entry name (return to go back) : GLOBAL_TEST
Menu choices :
P[ath]
G[et]
L[ist]
A[ddress]
Z[ero]
H[ierarchy of directories]
Enter P,G,L,A,Z,H or return to exit : G
Enter entry name (return to go back) : GLOBAL_TEST
Name : /DMQ$DISK/DMQ$V40/DMQNS/GLOBAL_TEST
Address : 0.0
Time last modified : Thu Jan 8 12:31:11 1998
-------------------------------------------------------------------
To reset the names to their original values, rerun the loader.
-------------------------------------------------------------------
$ !run the loader to see that GLOBAL_TEST is put back
$
$ RUN DMQ$EXE:DMQ$LOADER
DmQ I 40:33.4 Time Stamp - 8-JAN-1998 12:40:33.48
DmQ I 40:33.4 loader is running
DmQ I 40:33.5 Parsing PROFILE Section
DmQ I 40:33.5 Parsing GROUP Section
DmQ I 40:33.6 Parsing ROUTE Section
DmQ I 40:33.6 Parsing CLS Section
DmQ I 40:33.6 Parsing BUFFER Section
DmQ I 40:33.6 Parsing QCT Section
DmQ I 40:34.0 Parsing SBS Section
DmQ I 40:34.2 Parsing MRS Section
DmQ I 40:34.2 Parsing GNT Section
DmQ I 40:34.4 Parsing NAM Section
DmQ I 40:34.4 loader is exiting
$ ! Run NA Manager Utility to view the name
$
$ dmq$na_mgr 0
MessageQ Naming Agent Manager Utility
Menu choices :
P[ath]
G[et]
L[ist]
A[ddress]
Z[ero]
H[ierarchy of directories]
Enter P,G,L,A,Z,H or return to exit : G
Enter entry name (return to go back) : GLOBAL_TEST
Name : /DMQ$DISK/DMQ$V40/DMQNS/GLOBAL_TEST
Address : 40.1
Time last modified : Thu Jan 8 12:40:41 1998
-------------------------------------------------------------------
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 Example 8-3 .
Example 8-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:
MessageQ supports defining symbolic names for type and class codes within MessageQ application programs and the MessageQ script facility. These codes are carried in the DMQ header 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:
You can add codes to the DMQ$TYPCLS.TXT file when you run DMQ$CUSTOMIZE (from the MessageQ main menu) and enter YES in response to the following question:
Create language specific TYPE_CLASS include files [Y/N] (N)?
Example 8-4 is an excerpt from the DMQ$TYPCLS.TXT file that shows the PAMS class and type codes section of the file.
************************************************************** * * * 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 8-2 describes types of statements used in the
DMQ$TYPCLS.TXT file.
| Statement Type | Description | ||||||
|---|---|---|---|---|---|---|---|
| Comments | Begins with an asterisk (*) and can start anywhere on a line. | ||||||
| Blank lines | Transferred as is. | ||||||
| Symbol
declarations |
|
Note:
The only valid separators for this file are spaces and tabs.
This chapter describes how to configure and use the MessageQ Client Library Server on OpenVMS systems.
The following topics are covered in this chapter:
Note:
The information in this chapter supersedes the information in the BEA MessageQ Client for Windows User's Guide about the MessageQ Client Library Server for OpenVMS.
The role of the MessageQ Client Library Server (CLS) on OpenVMS systems is to provide applications access to message queuing capabilities without having MessageQ servers running on the same system. Typically, these applications run on PCs, but MessageQ also provides this economical access from any UNIX, OpenVMS, or Windows NT systems. Client applications can communicate with other distributed application components anywhere in the network using a single connection with CLS to the message queuing bus architecture provided by MessageQ .
The MessageQ Client Library Server is implemented for all server platforms supported by MessageQ . The CLS architecture is identical on all platforms. The CLS implementation is tailored for each operating system environment. See the BEA MessageQ Client for Windows User's Guide for more information on the Windows Client and Client Library Server architecture.
The MessageQ Client Library Server for OpenVMS runs as a non-privileged application program that uses MessageQ for OpenVMS. CLS uses asynchronous message queuing operations and network system service routines to support multiple Windows client connections by a single OpenVMS process. Support for multiple clients by a single process has the advantage of minimizing OpenVMS process resources compared to using one MessageQ CLS process for each Windows client.
All MessageQ functions available to Windows clients are supported
by CLS. The return status codes from MessageQ functions executed
by the Client Library Server on OpenVMS are converted to the equivalant
status values used by MessageQ for UNIX or Windows NT.
MessageQ Windows client applications do not receive OpenVMS return
status values.
9.3 Client Library Server Installation and Transport Support
The VMSINSTALL procedure for the MessageQ for OpenVMS media kit installs the files needed to run the Client Library Server. The files specific to the Client Library Server are the following:
The MessageQ CLS supports DECnet and one of the following TCP/IP transports:
During the MessageQ for OpenVMS installation, the LINKALL.COM command procedure calls DMQ$CLS.LNK to link one or more DMQ$CLS Server image files. The DMQ$CLS.LNK command procedure creates an executable image file in the DMQ$EXE directory for all network transports available on your system. The CLS image file names are:
| CLS Image File | Transport supported |
|---|---|
| DMQ$CLS_DECNET.EXE | DECnet |
| DMQ$CLS_UCX.EXE | DEC TCP/IP for OpenVMS |
| DMQ$CLS_TCP.EXE | TCPware for OpenVMS |
When CLS is using the TCP/IP transport, the value of the MessageQ logical name DMQ$TCPIP_LD determines which transport-specific CLS image file runs.
Note:
Refer to Chapter 4 for details on how define the DMQ$TCPIP_LD logical name.
If you install a new TCP/IP transport product after installing MessageQ , a new CLS image file must be linked to support the new TCP/IP transport. The MessageQ development media kit can be used to create a new transport-specific CLS image file using the following command:
@DMQ$EXE:DMQ$CLS.LNK
The command creates a new CLS image file that is available to use to
connect Windows clients using your transport product. Systems having
only a MessageQ run-time kit installed must reinstall
MessageQ to create the new CLS image.
9.4 Configuring the CLS section of DMQ$INIT.TXT File
Client Library Servers are started automatically by the MessageQ COM Server using the %CLS section of the DMQ$INIT.TXT configuration file. Edit the Client Library Server configuration table as required. Example 9-1 shows a sample CLS Configuration Table.
Example 9-1 Sample Client Library Server Configuration Table
--------------------------------------------------------
%CLS **** Client Lib Server Configuration Table ****
*
* Maximum # Security
* Endpoint Transport of Clients File Path
* -------- --------- ---------- ---------------
5000 TCPIP 25 dmq$user:cl_5000.sf
5001 TCPIP 25
6000 DECNET 32
--------------------------------------------------------
where:
| Parameter | Value | Description |
|---|---|---|
| Endpoint | 1024---65535 | CLS TCP/IP port |
| Endpoint | 1---99999 | CLS DECnet object |
| Transport | DECNET or TCPIP | Transport type (DECnet or
TCP/IP) |
| Maximum #
of Clients |
1---512 | Maximum number of clients allowed for each CLS Server, OpenVMS only |
| Security
File Path |
The full pathname of the CLS Security File. If no security file is specified then CLS will not restrict access by remote clients. |
Each entry in the table results in the creation of a multithreaded CLS process with the specified characteristics. For example, three Client Library Servers are started using the configuration table shown in Example 9-1 .
The first CLS process uses the TCP/IP transport and listens for connections on port 5000. The second CLS process also uses the TCP/IP transport, but listens for client connections using the port No. 5001. Both servers support up to 25 client connections. The third CLS process uses the DECnet transport and accepts connections on the DECnet object name, DMQCLS_6000.
Each Windows client application connecting to a Client Library Server
process uses MessageQ message queuing resources on the OpenVMS
system. Be sure to configure the MessageQ buffer pools to support
the messaging requirements of all MessageQ applications running
locally on the OpenVMS system as well as the Windows client
applications connected to the message queuing bus by CLS.
9.4.1 CLS Endpoints
The CLS endpoint identifies either the TCP/IP port number or the DECnet object name the server uses to listen for client connections. The same endpoint is used in the configuration of MessageQ Windows clients to locate the Client Library Server.
When the transport type is TCP/IP, the available port numbers are in the range from 1024 to 65535. Port numbers less than 1024 are reserved for privileged applications, such as TELNET and FTP. 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.
When the transport type is DECnet, the available endpoint values are in
the range from 1 to 99999. The endpoint value is concatenated with the
prefix DMQCLS_ to create a unique DECnet object name (for
example, DMQCLS_5000. If the value of the Maximum #
Clients parameter is equal to 1, then the endpoint range is
smaller, from 1 to 9999. This is used to support CLS subprocess object
names.
9.4.2 Setting Maximum Number of Clients for CLS
The Maximum # Clients parameter determines the number of active client connections supported by a single CLS process. When the maximum number of Windows clients are attached to CLS, further attach queue attempts fail with the the return status of PAMS__REJECTED. The maximum # clients parameter is ignored by non-OpenVMS groups.
The correct value for the maximum number of clients depends on the application. The maximum number of clients for each CLS is a function of variables unique to each application environment. Consider the following application characteristics when selecting a value:
Set the value of the Maximum # Clients parameter high enough to support a large number of Windows clients, then monitor the performance of the CLS process and the Windows client messaging response. Add additional CLS processes as needed to meet the application load and system environment. Very large networks of Windows clients can expect to use multiple Client Library Servers.
Special queue configuration issues arise using multithreaded Client
Library Servers. The configuration issues are described in the section
Section 9.5 .
9.4.3 Configuring One Client for Each CLS Server Option
When the value of the Maximum # Clients parameter is set to 1, CLS supports multiple clients using one OpenVMS subprocess for each client connection. This configuration is referred to as a Single-Client mode. When Maximum # Clients parameter is greater than 1, CLS runs multithreaded. When this parameter is equal to 1, CLS runs multiprocess.
Note:
When running the CLS in Single-Client mode, a separate CLS process is created for each client connection. Make sure the the sub-process quota ( PRCLM ) is large enough to accomodate the expected number of clients.
The Single-Client mode is used in previous versions of MessageQ for OpenVMS to support Windows client connections to permanent queues. MessageQ for OpenVMS Version 4.0A allows a multithreaded CLS process to provide client connections to permanent queues. The Single-Client mode is still available to support applications that have special configuration requirements that cannot be supported by a multithreaded CLS. The special configuration issues are described in Section 9.5 .
Note that the permanent queues used by a CLS Server in the Single-Client mode do not need to be configured differently. Each client connection is handled by a separate OpenVMS process that functions as any local MessageQ application process. The special queue configuration issues arise when using multithreaded CLS servers.
In the Single-Client mode, the CLS process listens on the endpoint as a well-known location for client requests to connect to. CLS behaves as a listener, waiting for connections.
When client connection requests arrive, the listener creates a separate OpenVMS Server subprocess to handle each client connection. This is similar to how the Client Library Server functions on UNIX systems. The OpenVMS process names for the CLS Server process begin with CLS_S_, followed by the listener endpoint number and a server sequence number. For example, the process name may be CLS_S_5000_1.
To reduce the delays for OpenVMS process creation, the CLS listener
creates an available server process before accepting the next client
connection request. When Windows clients connect to CLS, they first
connect to the listener which returns a dynamic port number for an
available server subprocess. They disconnect from the listener and
reconnect to the available server subprocess ready and waiting for
their connection. Windows clients complete a PAMS_ATTACH_Q
operation faster using a multithreaded CLS compared to using a
multiprocess CLS in the Single-Client mode.
9.4.4 Restricting Remote Access to CLS
The CLS security file is a text file containing a table of client entries. Each client entry contains a list of endpoints and queues which the clent may use. CLS uses the security file to restrict access by remote clients to those endpoints and queues. MessageQ groups can have their own separate security files, or can share one jointly.
A template security file is available at the following location:
DMQ$DISK:{DMQ$V40.USER.TEMPLATE]DMQCLSEC.TXT
Begin by making a copy of the template security file. Then edit the copy to remove the sample entries and add entries for the client systems in your environment. Copy the file to its target location and then associate the security file with the message queuing group.
When a CLS is started, it loads the security file specified in the %CLS section of the group initialization file. If no security file is specified, CLS will not restrict access by remote clients. Each CLS can have a separate security file, or a security file can be shared by multiple CLS processes.
For information about the CLS Security Utility, refer to the
BEA MessageQ Client for Windows User's Guide .
9.5 Special Queue Configuration Issues
Special queue configuration issues arise when using multithreaded CLS processes. Multithreaded CLS processes support client connections to both permanent and temporary queues. However, permanent queues used by Windows clients must be configured differently in order to be supported by a multithreaded CLS process.
Permanent queues are defined in the Queue Configuration Table of the DMQ$INIT.TXT file. (See Chapter 5 for more information on the Queue Configuration Table.)
Permanent queues used by clients must be configured as unowned secondary queues for a multithreaded CLS process to support multiple clients. Unowned secondary queues are permanent queues with a Q Type of "S", and a Q Owner of " . ". (Normally, secondary queues have a Q Owner that identifies a primary queue that the queue is tied to.)
Example 9-2 shows a sample of the Queue Configuration Table with permanent unowned secondary queues defined for use by CLS clients.
Example 9-2 Sample Client Queues for Queue Configuration Table
%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 *------------------- ---- ------- ---- ---- ---- ---- ---- ----- ---- ----- ---- * * Other permanent queues as needed. * * Client Queues * CLIENT_1 1 64000 100 All . S . II Y L N CLIENT_2 2 64000 100 All . S . EI Y L N CLIENT_3 3 64000 100 All . S . EO Y L N CLIENT_4 4 64000 100 Msg . S . II Y L N CLIENT_5 5 64000 100 Msg . S . EI Y L N CLIENT_6 6 64000 100 Msg . S . EO Y L N CLIENT_7 7 64000 100 Byte . S . II Y L N CLIENT_8 8 64000 100 Byte . S . EI Y L N CLIENT_9 9 64000 100 Byte . S . EO Y L N CLIENT_10 10 64000 100 . . S . . Y L N * * %EOS
The multithreaded CLS process handles all differences between using permanent primary queues and permanent secondary queues. Windows client applications do not have to be changed to use secondary queues.
The differences in queue type handled by CLS include the following: