This chapter describes how to configure the MessageQ Client. Table 3-1 lists and describes the configuration options for the MessageQ Client.
Run the Client Configuration program to specify the MessageQ Client configuration settings. Configuration settings are stored in the dmq.ini file if it is found in the PATH, and in the Registry. The following methods allow users to determine whether they use dmq.ini or the Registry for their configuration settings:
Applications may dynamically configure Configuring the connection to the MessageQ Client Library Server (CLS) consists of the following two items:
dmq.ini at runtime using the Windows WritePrivateProfileString function.
Configuring the Server Connection
The default CLS is used for all connections to the message queuing bus. Applications that are attempting to connect to a server (or lose a connection to the CLS) attempt to reconnect when the network connection to the server is available. If you do not enable automatic reconnect for the default server, you may want to consider configuring the automatic failover server.
The default server identifies the MessageQ server system for all connections to the message queuing bus. If automatic reconnection is enabled, applications that lose a connection to a server (or lose a connection to the CLS) try to reconnect when the network connection to the server is available. Client applications also reconnect in the event that the CLS or host server system is stopped and restarted. During an automatic reconnect event, the MessageQ Client attempts to connect only to the default server. Automatic reconnect does not attempt to use the failover server.
After a successful reconnect, the application is automatically attached to the message queuing bus and messaging operations can continue without interruption. All pending messages in the store-and-forward (SAF) journal are sent to the CLS before new operations can be performed. For example, when a The server configuration options shown in Figure 3-1 are described in Table 3-2.
If the primary (default) server is not available and automatic failover is enabled, the MessageQ Client provides the option of connecting to a failover CLS. By enabling automatic failover, a MessageQ Client will transparently try to attach to the failover server when the CLS on the primary server group is not available. Attempts to connect to the failover server are only made during a call to Using the failover capability requires additional planning and work in order for messages to be sent and received correctly. The message queues used by MessageQ Client applications are implemented by the MessageQ server group. The message queues, and any recoverable message journals, are located on the server system.
When connecting to the failover group, the queue address used by the MessageQ Client is likely to change (unless the MessageQ group started on the failover system has the same group ID as the primary server group). Recoverable messages sent to the client using the queue address of the primary server group are not delivered to the client when it reattaches to the failover server in a different MessageQ server group.
The simplest use of automatic failover is when the MessageQ Client attaches to a temporary queue and uses a request/response style of messaging. The client sends requests to one or more servers that send responses back to the queue address that sent the request. If failover occurs, the MessageQ Client is automatically reattached to a new temporary queue and request messages are sent and responses delivered to the new queue address. The application is unaware that a failover event occurred, except that any pending response is not received.
When clients attach to a specific permanent queue and receive recoverable messages sent to that queue address, they depend on the message queuing resources of that MessageQ group. Recoverable messages sent to the queue address while the client is not attached are saved on that system. If the client reconnects to the same queue name or number, but on a different (failover) MessageQ group, the recoverable messages on the MessageQ group where the default CLS is located are not delivered to the new queue address used by the MessageQ Client.
Automatic failover is not appropriate for all applications. The MessageQ server group and all disk-based queuing resources must also fail over to another system so that messages sent to the MessageQ Client are received after a failover transition. For example, the MessageQ server group can recover by restarting the MessageQ group on another node in an OpenVMS cluster.
Figure 3-2 shows the automatic failover server configuration options.
Table 3-3 lists and describes the automatic failover server configuration options. Default Server
pams_get_msg function call triggers the reconnect threshold and a successful automatic reconnect and attach operation completes, the SAF file is completely drained before the pams_get_msg function call returns.
Figure 3-1 Default Server Configuration Options
Automatic Failover Server
pams_attach_q. Failover is not used if automatic reconnect to the default server is enabled.
Figure 3-2 Automatic Failover Server Configuration Options
Message Recovery Services (MRS) are the MessageQ services that manage the automatic redelivery of critical messages. Messages that are sent using a recoverable delivery mode are written to the local store-and-forward (SAF) journal when the connection to the server system is not available.
The MessageQ Client ensures delivery of recoverable messages to the CLS on the MessageQ Server by providing a store-and-forward (SAF) journal (dmqsaf.jrn) to store recoverable messages when the connection to a CLS is not available. Local SAF journal processing is available when Message Recovery Services (MRS) are enabled in the MessageQ Client configuration. The location of the journal file can be set when configuring MRS.
If MRS is enabled, the message recovery journal is turned on when the client application first initiates an attach operation. If the CLS is not available at the time of an attach, the journal file is opened and the attach operation completes with return a status of PAMS__JOURNAL_ON.
When the journal is on, messages sent using the following reliable delivery modes are saved to the journal:
When the connection to the CLS is reestablished, all messages in the SAF journal are sent before new messages are processed. The SAF messages are transmitted in first-in/first-out (FIFO) order. When the connection to CLS is reestablished, a return status of PAMS__LINK_UP is used to indicate that journal processing is no longer active.
Messages are sent from the SAF when one of the following events occurs:
The MessageQ Client MRS configuration options allow the SAF journal to be configured as follows:
These options allow you to determine how disk resources are used for message journals. Journal files that grow indefinitely periodically allocate an extent of disk blocks as needed to store messages. When all messages are sent from the SAF and the journal is empty, the disk blocks used by the journal are freed and the journal file returns to its original size.
This section is optional if recoverable messaging is not used.
Figure 3-3 shows the MRS configuration options.
Table 3-4 describes the MRS configuration options.Figure 3-3 MRS Configuration Options
The Protocol options determine how the MessageQ Client DLL communicates with the CLS.
Figure 3-4 shows the Protocol configuration options.
Figure 3-4 Protocol Configuration Options
Table 3-5 describes the Protocol configuration options.
There are significant differences between the standard request/response and Minimum network packets. Table 3-6 lists those differences to help you choose the protocol option that works best for your client implementation.
No additional configuration is required to support the standard request/response protocol.
You can configure the Minimum Packet Protocol (MPP) to customize the way the Client DLL and CLS exchange messages. Adjust the MPP parameters to suit your application and the network environment in which your application will run.
Table 3-7 describes the Minimum Packet Protocol configuration options.
Note: MPP does not function under the Netmanage Chameleon TCP/IP product.
Note: TCP/IP keepalive messages can be turned off when using the Minimum Packet Protocol.
The MessageQ Client allows you to log error events and messages to the Event Watcher, as well as trace messages and write the output to a trace file. All files are located in the current working directory for the application.
Message logging allows you to obtain a complete history of the messaging activity of your application. Tracing messages to the Event Watcher is an effective way to monitor the run-time behavior of the application. For more information about the MessageQ Event Watcher, see the Event Watcher Utility topic in Chapter 4.
Figure 3-5 shows the Message Logging configuration options.
Figure 3-5 Message Logging Configuration Options
Table 3-8 describes the message logging and message tracing configuration options. Note that you must stop and restart your application and perform a pams_attach_q operation for any of the logging options to take effect.
Tracing can be a useful debugging tool, because it allows you to observe MessageQ Client processing activity. The trace output may create large output files on your system, and should only be used to monitor specific application behavior. The trace output log files are located in the default working directory for the application.
Figure 3-6 shows the tracing configuration options.
Figure 3-6 Tracing Options
Table 3-9 describes the Tracing configuration options.
To determine the version of the MessageQ Client DLL, open the configuration utility. The window shown in Figure 3-7 is displayed. Click on the tab marked Version.
Figure 3-7 Client DLL Version Number
It is also possible to obtain DLL version information by displaying the file properties using Windows Explorer or File Manager.
In addition to the Configuration Editor, the MessageQ Client provides the utilities listed in Table 3-10 to assist in the configuration process.
The MessageQ CLS Security Utility, dmqsecu.exe, allows a MessageQ administrator to define a list of MessageQ client systems that can attach to CLS. The utility provides a convenient user interface to review, modify, and update the security table used by CLS on a remote server system.
A CLS security template file, dmqclsec.txt, is installed on the MessageQ server system. This file must be manually edited to specify the client systems that can update the security file with the CLS Security Utility. For more information about the CLS Security template file, see the Client Library Server topics in the MessageQ Installation and Configuration Guide.
Run the CLS Security Utility to update or modify the CLS security file. Figure 3-8 shows the main window of the MessageQ CLS Security Utility.
The CLS Security Utility uses the MessageQ Client configuration settings to connect to a CLS. The security file is automatically retrieved when the CLS Security Utility is started. You can change the Default Server configuration to use the CLS Security Utility with multiple CLS servers in different MessageQ groups. The current CLS hostname, endpoint, and group ID are displayed in the status bar. If the CLS is not using a security file, the CLS Security Utility will display an "Error getting security file" message.
The CLS security table consists of a list of client nodes that are allowed to connect to CLS and attach to the MessageQ message queuing bus. The security table format allows a MessageQ administrator to restrict access by client nodes to specific CLS endpoints and message queues. The Client Node List is similar to the cross-group connection table in the MessageQ group configuration. Only client nodes with entries in the list are allowed to connect to CLS. All other connection requests are rejected.
The list of client nodes defined in the security table is displayed in a scrollable list on the main form. You can modify individual entries in the list by selecting (highlighting) an entry with one mouse click and selecting the Edit... command button, or by double-clicking on the entry. Table 3-11 shows the minimum server versions required for security file support.
| MessageQ | Minimum Version |
|---|---|
|
MessageQ for UNIX |
V3.1 |
|
MessageQ for Windows NT |
V3.1 |
|
MessageQ for OpenVMS |
V4.0 |
Figure 3-8 shows a typical CLS Security Utility Main Window.
Figure 3-8 CLS Security Utility Main Window
Table 3-12 lists the CLS Security Utility command buttons for the Client Operations.
Table 3-13 lists the CLS Security Utility command buttons for the Table Operations:
Only client nodes that are granted CLS_SECURITY_FILE access in the CLS security table are allowed to modify the contents of the CLS security file using the CLS Security Utility. CLS security file updates are not password-protected. The CLS security table cannot be saved to a local file. However, you can print the contents of the security table by using the File menu Print option. Changes to the security table that have not been saved with the Replace command are not printed.
For more information about the CLS Security File, see the Installation and Configuration Guide for your MessageQ server platform.
The Security Table Client Entry dialog displays information about the resources the client node can access. Figure 3-9 shows the options for editing and creating client entries.
Figure 3-9 Security Table Client Entry Options
Table 3-14 describes the configuration options for security table client entries.
The client entry is added to the Client Node List on the main form when the OK button is selected. Changes to the security table do not become permanent until after the table is replaced. Changes to the security table do not become active until after a CLS load request, or the CLS server is restarted.
Modification history is a useful way to keep track of updates to the CLS security table. You can maintain the modification history for the CLS security table by using the Security Table Modification History dialog, as shown in Figure 3-10.
Figure 3-10 Security Table Modification History
To test your newly configured MessageQ Client, run the MessageQ Client Test Utility for Windows (Figure 3-11).
The Test Utility allows you to interactively select the parameter options for individual calls to MessageQ. The program also allows you to test various MessageQ message delivery options and send messages to any process connected to the MessageQ bus. Use the Test Utility for unit-testing applications under development.
Figure 3-11 MessageQ Test Utility
