|
|
|
|
|
|
Configuring the BEA MessageQ Client Library Server
This chapter describes how to configure and use the BEA MessageQ Client Library Server (CLS) on OpenVMS systems.
The following topics are covered in this chapter:
BEA MessageQ Client Library Server Overview
The role of the BEA MessageQ Client Library Server (CLS) on OpenVMS systems is to provide applications access to message queuing capabilities without having BEA MessageQ servers running on the same system. Typically, these applications run on PCs, but BEA MessageQ also provides this economical access from any UNIX, OpenVMS, or Windows NT system. 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 BEA MessageQ.
The BEA MessageQ Client Library Server is implemented for all server platforms supported by BEA MessageQ. The CLS architecture is identical on all platforms. The CLS implementation is tailored for each operating system environment. See the BEA MessageQ Client User's Guide for your operating system for platform-specific information.
The BEA MessageQ Client Library Server for OpenVMS runs as a nonprivileged application program that uses BEA MessageQ for OpenVMS. CLS uses asynchronous message queuing operations and network system service routines to support multiple client connections using a single OpenVMS process. Support for multiple clients using a single process has the advantage of minimizing OpenVMS process resources compared to using one BEA MessageQ CLS process for each client.
All BEA MessageQ functions available to clients are supported by CLS. The return status codes from BEA MessageQ functions executed by the Client Library Server on OpenVMS are converted to the equivalant status values used by BEA MessageQ for UNIX or Windows NT. BEA MessageQ client applications on UNIX or Windows NT do not receive OpenVMS return status values.
Client Library Server Installation and Transport Support
The VMSINSTAL procedure for the BEA 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 BEA MessageQ CLS supports DECnet and the following TCP/IP transports:
During the BEA 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 Services for OpenVMS |
|
DMQ$CLS_TCP.EXE |
PSC TCPware for OpenVMS |
|
DMQ$CLS_TGV.EXE |
PSC MultiNet TCP/IP for OpenVMS |
When CLS is using the TCP/IP transport, the value of the BEA MessageQ logical name DMQ$TCPIP_LD determines which transport-specific CLS image file runs.
Note: Refer to Configuring Cross-group Connections, for details on how define the DMQ$TCPIP_LD logical name.
If you install a new TCP/IP transport product after installing BEA MessageQ , a new CLS image file must be linked to support the new TCP/IP transport. The BEA 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 to connect clients using your transport product.
Configuring the CLS section of DMQ$INIT.TXT File
Client Library Servers are started automatically by the BEA MessageQ COM Server using the %CLS section of the DMQ$INIT.TXT configuration file. Edit the Client Library Server configuration table as required. Listing 8-1 shows a sample CLS Configuration Table.
Listing 8-1 Sample Client Library Server Configuration Table
%CLS **** Client Library 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
Table 8-1 describes the parameter definitions for the CLS Configuration Table.
Table 8-1 CLS Configuration Table Parameter Definitions
|
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 # |
1-512 |
Maximum number of clients allowed for each CLS Server, OpenVMS only |
|
Security |
pathname |
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 Listing 8-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 port 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 client application that connects to a CLS process uses BEA MessageQ message queuing resources on the OpenVMS system. Be sure to configure the BEA MessageQ buffer pools to support the messaging requirements of all BEA MessageQ applications running locally on the OpenVMS system, as well as the client applications connected to the message queuing bus by CLS.
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 BEA MessageQ 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 BEA 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 Maximum # Clients is equal to 1, then the endpoint range is reduced to values between 1 and 9999. This is used to support CLS subprocess object names.
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 clients are attached to CLS, additional attach queue attempts fail with the the return status of PAMS__REJECTED. The maximum number of clients parameter is ignored by non-OpenVMS groups.
The optimum 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:
Faster machines with more memory allow individual CLS processes to handle a larger number of simultaneous client connections, depending on system load.
CLS can support a higher number of client connections if each client sends and receives messages with low frequency.
Multithreaded Client Library Servers use AST routines to support multiple client connections that perform blocking dequeue functions. As the number of clients waiting for messages increases, the CLS process incurs a gradually higher processing cost to receive each message.
Each CLS process supports many network connections, each connection uses additional system and network resources.
Client applications share process and system resources of the CLS process. Different applications or users in different organizations may prefer to use separate CLS processes for easier application management.
Set the value of the Maximum # Clients parameter to a value that supports a large number of clients, then monitor the performance of the CLS process and the client messaging response. Add additional CLS processes as needed to meet the application load and system environment. Very large client networks can expect to use multiple Client Library Servers.
Special queue configuration issues arise using multithreaded Client Library Servers. The configuration issues are described in Special Queue Configuration Issues.
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 in multithreaded mode. When this parameter is equal to 1, CLS runs in multiprocess mode.
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 for remote BEA MessageQ client applications requiring unrestricted connection to any available queue, just like a local application. The BEA MessageQ for OpenVMS multithreaded CLS process provides client applications attachment to temporary queues and to permanent queues that are specifically defined as unowned secondary. See Special Queue Configuration Issues for more information.
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 like any local BEA MessageQ application process. The special queue configuration issues arise when using multithreaded CLS servers.
In Single-Client mode, the CLS process listens on the endpoint as a well-known location for client requests to connect. 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_05000_001.
To reduce the delays for OpenVMS process creation, the CLS listener creates an available server process before it accepts the next client connection request. When clients connect to CLS, they first connect to the listener, which returns a dynamic port number for an available server subprocess. Clients disconnect from the listener and reconnect to the available server subprocess ready and waiting for their connection. BEA MessageQ client applications complete a pams_attach_q operation faster using a multithreaded CLS, compared to using a multiprocess CLS in the Single-Client mode.
Restricting Remote Access to CLS
The CLS security file is a text file that contains 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. BEA 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$V50.USER.TEMPLATE]DMQCLSEC.TXT When you create a group, a copy of the template security file is automatically placed in the group's directory. Edit the file to remove the sample entries and add entries for the client systems in your environment. Then associate the security file with the message queuing group by specifying the Security File Path in the %CLS section of the group initialization file.
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.
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 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 Configuring Message Queues and Global Memory, 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 specified by a period (.). (Normally, secondary queues have a Q Owner that identifies a primary queue that the queue is tied to.)
Listing 8-2 shows a sample of the Queue Configuration Table with permanent unowned secondary queues defined for use by CLS clients.
Listing 8-2 Sample Client Queues for Queue Configuration Table
%QCT ***** Queue Configuration Table ******
*
* ---Pool Quota--- UCB Q Q Confrm Perm Name Chk
* 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. Client applications do not have to be changed to use secondary queues.
The differences in queue types handled by CLS include the following:
In general, client applications are not aware that permanent queues are configured as unowned secondary queues instead of primary queues. All message queuing operations, including Message Recovery Services, functions in the same way.
Errors Attaching to Undefined Queues
Using a multithreaded CLS, client applications attempting to attach to permanent queues that are not defined in the Queue Configuration Table receive a return status value of PAMS__NOTSECONDARYQ, (-270). Because the client specified a queue type parameter of PSYM_ATTACH_PQ, the error is inconsistent. This is due to the queue type mapping performed by multithreaded CLS. However, it indicates that the queue must be defined as an unowned secondary queue in the Queue Configuration Table.
Starting and Stopping CLS Manually
For convenience and ease of application management, CLS Servers are generally started from the CLS Configuration Table when a BEA MessageQ group starts. CLS Servers also are stopped when the BEA MessageQ group is shut down. There are circumstances when new CLS Servers need to be started without affecting the entire BEA MessageQ group.
Starting CLS from the Manager Utility
A CLS Server process can be started from the Manager Utility, using the Start Service command on the Remote Client Management menu (Listing 8-3 and Listing 8-4). The service must already be defined in the %CLS section of the group initialization file. If the service is not defined in the group initialization file, then modify the initialization file to add the new service and then run the loader again using the following command:
$RUN DMQ$EXE:DMQ$LOADER.EXE
Listing 8-3 Manager Utility Remote Client Management Menu
Bus:99 Group:40 MessageQ Manager Utility Thu Jan 8 15:28:37 1998
Remote ClientLib Controls - Choose the function type
SS - Start Service KS - Stop Service
EX - Exit Remote ClientLib Controls
Enter option:
Listing 8-4 Starting CLS from Remote Client Management Menu
Bus:99 Group:40 MessageQ Manager Utility Thu Jan 8 15:33:29 1998
Endpoint Transport
5001 TCPIP
6000 DECNET
Enter end point number: 5001
Successfully started CLS Endpoint:5001, Transport:TCPIP
<CR> to continue:
Starting CLS from DCL
Additional CLS Server processes can be started using the DCL command procedure DMQ$CLS_START.COM, while BEA MessageQ is already running. This procedure is available in DMQ$EXE. Although CLS processes can be stopped and started without impacting the BEA MessageQ group, stopping a CLS process impacts all clients that are currently connected to that server.
To execute the DMQ$CLS_START.COM command procedure, enter
$ @DMQ$EXE:DMQ$CLS_START
This command procedure takes the following parameters:
$ @DMQ$EXE:DMQ$CLS_START endpt transport max clients
where
Examples of CLS_START parameters:
@DMQ$EXE:DMQ$CLS_START 5000 TCPIP 25
@DMQ$EXE:DMQ$CLS_START 5000 DECNET 25
@DMQ$EXE:DMQ$CLS_START 5000 TCPIP 1
DMQ$CLS_START uses the DMQ$EXE:DMQ$START_SERVER.COM command procedure to create a detached CLS Server process.
Stopping CLS from the Manager Utility
A CLS Server process can be stopped from the Manager Utility, using the Stop Service command from the Remote Client Management menu (Listing 8-5), or by using the Force Process service (Listing 8-6).
Listing 8-5 Stopping CLS from Remote Client Management Menu
Bus:99 Group:40 MessageQ Manager Utility Thu Jan 8 15:33:29 1998
Endpoint Transport
5001 TCPIP
6000 DECNET
Enter end point number: 5001
Successfully stopped CLS Endpoint:5001, Transport:TCPIP
<CR> to continue:
Listing 8-6 Stopping CLS from Force Process Menu
Bus:99 Group:40 MessageQ Manager Utility Thu Jan 8 15:48:58 1998
FORCEX Process
Index Process Name State PQ Name #Queues #Pending
1 DMQ_N_009900040 NA_SERVER 1 0
2 DMQ_M_009900040 MRS_SERVER 1 0
3 DMQ_S_009900040 SBS_SERVER 1 0
4 DMQ_C_009900040 COM_SERVER 1 0
5 DMQ_T_009900040 TCPIP_LD 1 0
6 DMQ_D_009900040 DECNET_LD 1 0
7 DMQ_L_009900040 EVENT_LOGGER 1 0
8 DMQ_J_009900040 JRN_SERVER 1 0
9 DMQ_CLS_T_5001 +DMQ_CLS_T_5001_203 1 0
10 DMQ_CLS_D_6000 +DMQ_CLS_D_6000_204 1 0
11 _FTA30: +_FTA30:_205 1 0
[End]
Index of process to be stopped? [1 - 11]:
CLS Event Logging and Tracing
The Client Library Server event logging is integrated with the BEA MessageQ for OpenVMS Event Logger process. CLS Server initialization and client connect/disconnect events are logged to the Event Logger.
The Client Library Server also supports trace output that provides more detailed information about client activity. The CLS trace output displays information about the BEA MessageQ API calls executed by CLS on behalf of client applications.
The CLS event log and trace output can be directed to the common event log, to the console, or to separate files. See Using BEA MessageQ System Management Utilities, for more information on using the BEA MessageQ Event Log facility.
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|