|
|
|
|
|
|
Configuring the MessageQ Client
This chapter describes how to configure the MessageQ Client for UNIX. Refer to Table 3-1 for the configuration options for the MessageQ Client for UNIX.
|
Option |
Description |
Required? |
|---|---|---|
|
Server |
Default Server Network transport, server host name, and endpoint definition |
Yes |
|
Failover |
Automatic Failover Server Network transport, server host name, and endpoint definition for the failover server |
No |
|
MRS |
Settings for enabling the local store-and-forward (SAF) message journal and configuring the local journal files |
No |
|
Tracing |
Settings to enable runtime trace information about the API calls and Client library activity |
No |
To configure the MessageQ Client for UNIX, use the Client for UNIX Configuration Utility, dmqclconf. The configuration utility is started from the command line using the following command line format:
dmqclconf [-f file] [-l] [-v] [-h]
Refer to Table 3-2 for the command-line parameters.
|
Option |
Description |
|---|---|
|
-f file |
Specifies the dmq.ini file path. The default file is ./dmq.ini. If this option is not used, dmqclconf searches the directories specified by the PATH environment variable, and opens the first dmq.ini file that it finds. |
|
-l |
Lists the current configuration settings (if used with the -f file options), or the default configuration settings |
|
-v |
Displays the MessageQ Client for UNIX Configuration Utility version number |
|
-h |
Displays a brief help message that describes the options for this command |
See Listing 3-1 for the MessageQ Client for UNIX Configuration Utility Main Menu.
Listing 3-1 MessageQ Client for UNIX Configuration Utility Main Menu
Main Menu (file: /usr/jones/messageq/dmq.ini)
1 Open
2 Configure
3 List
4 Save
5 Exit
Enter Selection:
Refer to Table 3-3 for a description of the Main Menu options.
|
Option |
Description |
|---|---|
|
Open |
Opens a specific dmq.ini file |
|
Configure |
Configure the MessageQ Client for UNIX |
|
List |
Lists the current (or the default) settings |
|
Save |
Saves the configuration changes or updates to the dmq.ini file |
|
Exit |
Exits the MessageQ Client for UNIX Configuration Utility |
The Configuration Utility updates an initialization file, dmq.ini, that is used at run time by the MessageQ Client for UNIX library. The dmq.ini file can be shared by multiple MessageQ-enabled applications using the same general configuration. Individual copies of dmq.ini can be used to tailor the configuration for individual applications. The dmq.ini file can be stored in any of the following directories:
The location of the dmq.ini file determines whether the same configuration is shared by multiple applications. When the application attempts to attach to the MessageQ message queuing bus, the client library searches the directories in the order listed for a copy of the dmq.ini file. The dmq.ini file can be modified using any text editor; however, we recommend using the MessageQ Client for UNIX Configuration Utility.
To begin configuring the MessageQ Client for UNIX, select item 2, Configure, from the Main Menu. See Listing 3-2 for the MessageQ Client for UNIX Configure Menu.
Listing 3-2 MessageQ Client for UNIX Configure Menu Options
Configure Menu (file: /usr/jones/messageq/dmq.ini)
1 Server
2 Failover
3 Logging
4 MRS
5 Tracing
6 Previous Menu
Enter Selection:
Configuring the Server Connection
Configuring the connection to the MessageQ Client Library Server (CLS) consists of the following two items:
The default server is used for all connections to the message queuing bus. If automatic reconnection is enabled, 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.
If the primary default server is not available, the MessageQ Client for UNIX provides the option of connecting to a failover server to ensure robust client connections. However, if automatic reconnect to the default server is enabled, the automatic failover server cannot be used.
The default server identifies the MessageQ server system for all connections to the message queuing bus. If automatic reconnection is enabled, applications that are attempting to connect 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 for UNIX 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 SAF journal are sent to the CLS before new operations can be performed. For example, when a pams_get_msg triggers the reconnect threshold and a successful automatic reconnect and attach operation completes, the SAF journal is completely drained before the pams_get_msg function call returns. See Listing 3-3 for the default server configuration options.
Listing 3-3 Default Server Options
Server Configuration
Network Transport Type (TCP/IP) [TCP/IP]:
Server Hostname [arches]: dmqsrv
Server Endpoint [5000]:
Reconnect Interval (# of messages) [0]:
Refer to Table 3-4 for the default server configuration options.
|
Option |
Description |
|---|---|
|
Network Transport Type |
The network-level transport used to send messages to the MessageQ CLS. MessageQ supports TCP/IP as a network transport. |
|
Server Hostname |
The name of the host running the MessageQ CLS. The hostname must have a corresponding entry in the local hosts file. Refer to your network documentation for additional information on the location of these files. |
|
Server Endpoint |
The endpoint used by the MessageQ CLS. For more information about specifying the endpoint, see the CLS section of the Installation and Configuration Guide for your server platform. |
|
Reconnect Interval |
The number of message operations that occur before the server attempts to reconnect. If set to 0, automatic reconnect is not enabled. If set to greater than 0, automatic reconnect is enabled. The MessageQ Client for UNIX attempts to reconnect to the server using the Reconnect Interval option as the threshold for making a new connection attempt. Any messaging operation call increments the count used to determine when to attempt another reconnect. When the number of operations attempted reaches the Reconnect Interval threshold, a reconnect attempt is made. Applications can choose to use a higher reconnect value to store messages in the local journal for forwarding at a later time. |
Automatic Failover Server
If the primary (default) server is not available and automatic failover is enabled, the MessageQ Client for UNIX provides the option of connecting to a failover CLS. The failover options are ignored if automatic reconnect to the default server is enabled.
By enabling automatic failover, a MessageQ Client for UNIX 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 made only during a call to pams_attach_q.
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 for UNIX 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 for UNIX 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 MessageQ Clients for UNIXs attach to a temporary queue and use 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 for UNIX 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.
Automatic failover is not appropriate for all applications. 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 for UNIX.
On the other hand, the previous scenario could use failover by making the MessageQ server group (and all disk-based queuing resources) also fail over to another system so that messages previously sent to the MessageQ Client for UNIX are received after a failover transition. See Listing 3-4 for the automatic failover server configuration options.
Listing 3-4 Automatic Failover Server Options
Failover Configuration
Enable Automatic Failover (yes/no) [no]: y
Network Transport Type (TCP/IP) [TCP/IP]:
Server Hostname [oquirh]: dmqbck
Server Endpoint [5000]:
Refer to Table 3-5 for a description of the automatic failover server configuration options.
|
Option |
Description |
|---|---|
|
Enable Automatic Failover |
If checked, automatic failover is enabled. The failover server is used when the default server is not available and automatic failover is enabled. The Reconnect Message Interval option (see Table 3-3) must be greater than 0. |
|
Network Transport Type |
The network-level transport used to send messages to the failover server. MessageQ supports TCP/IP as a network transport. |
|
Server Hostname |
The name of the host running the MessageQ CLS. The hostname must have a corresponding entry in the local hosts file. |
|
Server Endpoint |
The endpoint used by the MessageQ CLS. For more information, see the startup information for the CLS in the MessageQ Installation and Configuration Guide for your server platform. |
Configuring Logging
The MessageQ Client for UNIX allows you to log error events and messages a log file, as well as to trace messages and write the output to a trace file. All log 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 a file is an effective way to monitor the run time behavior of the application. See Listing 3-5 for the logging configuration options.
Listing 3-5 Logging Options
Logging Configuration
Log Error Events (yes/no) [yes]: y
Log Messages Sent to Trace File (yes/no) [no]:
Log Messages Received to Trace File (yes/no) [no]:
Refer to Table 3-6 for the message logging and message tracing configuration options. Note that you must perform a pams_attach_q operation for any of the "Log Messages" options to take effect.
|
Option |
Description |
|---|---|
|
Log Error Events |
If set to yes, logs error events to the file dmqerror.log. The default behavior is to log error events. When error event logging is enabled, connection errors to the CLS also log the full file path of the configuration file used at the time of the connection attempt. This can help identify problems due to multiple copies of the configuration file. |
|
Log Messages Sent |
If set to yes, sends a copy of MessageQ messages sent by the application to the dmqtrace.log message log file |
|
Log Messages Received |
If set to yes, sends a copy of MessageQ messages received by the application to the dmqtrace.log message log file |
Configuring Message Recovery Services
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 re-established, 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. See Listing 3-6 for the MRS configuration options.
Listing 3-6 MRS Configuration Options
MRS Configuration
MRS Enabled (yes/no) [yes]:
Journal File Path [./]:
Journal File Size (bytes) [48000]:
Cycle Journal File Blocks (yes/no) [yes]: n
Fixed Size Journal File (yes/no) [yes]:
Preallocate Journal File (yes/no) [yes]:
Refer to Table 3-7 for the MRS configuration options.
|
Option |
Description |
|---|---|
|
MRS Enabled |
When checked, MRS is enabled |
|
Journal File Path |
Specifies the path where the MessageQ journal file, dmqsaf.jrn, is located. The default location is the current working directory. |
|
Journal File Size |
Initial size, in bytes, of the journal file |
|
Cycle Journal Blocks |
If set to yes, the journal cycles (reuses) disk blocks when full and overwrites previous messages. The Cycle Journal Blocks file automatically sets the Fixed Size allocation option. When Cycle Journal Blocks is enabled, all read/write operations to the journal use fixed size journal message blocks. |
|
Fixed Size Journal File |
Determines if the journal size is fixed or allowed to grow. If Cycle Journal Blocks is set to yes, Fixed Size is also enabled. Note: Journals that do not cycle and are not fixed can grow until the disk is full. |
|
Preallocate Journal |
If set to yes, the journal file disk blocks are preallocated when the journal is initially opened |
|
Journal Message Block Size |
Defines the file I/O block size, in bytes. Used for journal read/write operations only when Cycle Journal Blocks is enabled. When calculating this value, add 80 bytes to the largest user message (because an 80-byte MRS message header is written to the journal for each user message). |
Configuring Tracing
Tracing can be a useful debugging tool, because it allows you to enable and disable MessageQ Client for UNIX processing activity trace output. The trace output may create large output files on your system, and should be used only to monitor specific application behavior. The trace output log files are located in the default working directory for the application. See Listing 3-7 for the tracing configuration options.
Listing 3-7 Tracing Configuration Options
Tracing Configuration
Trace PAMS API Calls (yes/no) [no]: y
Trace Client Library Activity (yes/no) [yes]: y
Refer to Table 3-8 for the tracing configuration options.
|
Option |
Description |
|---|---|
|
Trace PAMS API calls |
If set to yes, logs API call activity to the file dmqcldll.log. The default is no tracing. |
|
Trace Client library activity |
If set to yes, traces the internal client library activity to the file dmqcldll.log. The default is no tracing. |
Testing the Configuration Using the Test Utility
To test your newly configured MessageQ Client for UNIX, run the MessageQ Test Utility dmqcltest. The Test Utility is started from the command line using the following command-line format:
dmqcltest
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.
To use the Test Utility, you first set the parameters associated with an action, then you perform the action. For example, to attach to a queue, you set the desired attach parameters, then execute the attach action.
See Listing 3-8 for the Test Utility main menu options.
Listing 3-8 Test Utility Main Menu
Wed > dmqcltest
Main Menu
1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 1
Refer to Table 3-9 for the Test Utility Parameters and Actions menu Options.
|
Parameters Menu Options |
Actions Menu Options |
|---|---|
|
Attach Parameters |
Attach Queue |
|
Detach Parameters |
Detach Queue |
|
Locate Parameters |
Locate Queue |
|
Put Parameters |
Put Message |
|
Get Parameters |
Get Message |
|
Set Timer Parameters |
Set Timer |
|
Cancel Timer Parameters |
Cancel Timer |
|
View Current Parameters |
View Current Parameters |
|
Previous Menu |
Previous Menu |
The examples in the following figures show how to use the Test Utility to attach to a temporary queue and send a message to another queue. The steps shown by the examples are as follows:
Set the Attach parameters to specify a temporary primary queue (Listing 3-9)
Set the Put parameters for the message (Listing 3-10)
Attach to queue 206 in group 9 (Listing 3-11)
Put the message to queue 1 in group 9 (Listing 3-13)
Detach from the temporary queue (Listing 3-14)
Exit from the Test Utility (Listing 3-15)
Listing 3-9 Specify a Temporary Queue
Wed > dmqcltest
Main Menu
1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 1
Parameters Menu
1 Attach Parameters
2 Bind Parameters
3 Detach Parameters
4 Locate Parameters
5 Put Parameters
6 Get Parameters
7 Set Timer Parameters
8 Cancel Timer Parameters
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 1
SELECT ATTACH TYPE
1) Attach Primary
2) Attach Secondary
Select attach type [1] ?
SELECT ATTACH_MODE
1) Attach by name
2) Attach by number
3) Attach temporary
Select attach mode [3] ?
Listing 3-10 Set the Put Parameters
Parameters Menu
1 Attach Parameters
2 Bind Parameters
3 Detach Parameters
4 Locate Parameters
5 Put Parameters
6 Get Parameters
7 Set Timer Parameters
8 Cancel Timer Parameters
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 5
SELECT PRIORITY
1) Standard Priority
2) High Priority
Select priority [1] ?
SELECT DELIVERY MODE
1) PDEL_MODE_AK_xxx
2) PDEL_MODE_NN_xxx
3) PDEL_MODE_WF_xxx
Select deliver mode [2] ? 3
SELECT DELIVERY MODE
1) PDEL_MODE_xx_ACK
2) PDEL_MODE_xx_CONF
3) PDEL_MODE_xx_DEQ
4) PDEL_MODE_xx_DQF
5) PDEL_MODE_xx_MEM
6) PDEL_MODE_xx_SAF
Select delivery mode [5] ? 5
SELECT UMA
1) PDEL_UMA_DISC
2) PDEL_UMA_RTS
3) PDEL_UMA_SAF
4) PDEL_UMA_DLQ
5) PDEL_UMA_DLJ
Select UMA [1] ? 1
Enter target group [9] ? 9
Enter target queue [205] ?
Enter response queue [0] ?
Enter timeout in seconds [30] ?
Enter message class [1] ? 12
Enter message type [-100] ? 34
Enter message text ? This is a test message.
Listing 3-11 Attach to Queue 206 in Group 9
Parameters Menu
1 Attach Parameters
2 Bind Parameters
3 Detach Parameters
4 Locate Parameters
5 Put Parameters
6 Get Parameters
7 Set Timer Parameters
8 Cancel Timer Parameters
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 10
Main Menu
1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 2
Actions Menu
1 Attach Queue
2 Bind Queue
3 Detach Queue
4 Locate Queue
5 Put Message
6 Get Message
7 Set Timer
8 Cancel Timer
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 1
attached to queue 9.206
If the MessageQ Client is properly configured to communicate with the Client Library Server running on a MessageQ Server, the Test utility returns a success message indicating that the attached operation was successful. However, if a problem occurs when the MessageQ Client attempts to attach to the message queuing bus, an error message is displayed indicating the source of the problem as shown in Listing 3-12.
The PAMS_NETNOLINK return value is a common error condition that occurs when network communication between the MessageQ Client and the CLS has not been established.
Listing 3-12 PAMS_NETNOLINK Error
Actions Menu
1 Attach Queue
2 Bind Queue
3 Detach Queue
4 Locate Queue
5 Put Message
6 Get Message
7 Set Timer
8 Cancel Timer
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 1
PAMS_NETNOLINK, Communications link could not be established.
The PAMS_NETNOLINK error can be caused by a variety of conditions. Table 3-10 describes the potential causes of this problem and their resolution.
|
Condition |
Resolution |
|---|---|
|
The client configuration is incorrect. |
Check the server configuration information in the dmq.ini file to make sure that:
|
|
The Client cannot determine the network address for the CLS. |
Check the local hosts file or name server to make sure that the network address specified for the host system running the CLS is correct. |
|
The CLS may not be running. |
Check the MessageQ Server system that is running the CLS to be sure that:
|
The PAMS_NETNOLINK error is only one of the error conditions that can arise when using the Test utility to test your MessageQ Client configuration. Refer to Chapter 5, "Troubleshooting" for more troubleshooting information.
Listing 3-13 Put the Message to Queue 1 in Group 9
Actions Menu
1 Attach Queue
2 Bind Queue
3 Detach Queue
4 Locate Queue
5 Put Message
6 Get Message
7 Set Timer
8 Cancel Timer
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 5
put message to queue 9.205
Actions Menu
1 Attach Queue
2 Bind Queue
3 Detach Queue
4 Locate Queue
5 Put Message
6 Get Message
7 Set Timer
8 Cancel Timer
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 10
Listing 3-14 Detach from the Temporary Queue
Main Menu
1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 2
Actions Menu
1 Attach Queue
2 Bind Queue
3 Detach Queue
4 Locate Queue
5 Put Message
6 Get Message
7 Set Timer
8 Cancel Timer
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 3
detached from queue 9.205
Listing 3-15 Exit from the Test Utility
Actions Menu
1 Attach Queue
2 Bind Queue
3 Detach Queue
4 Locate Queue
5 Put Message
6 Get Message
7 Set Timer
8 Cancel Timer
9 View Current Parameters
10 Previous Menu
Enter Menu Selection >> 10
Main Menu
1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 3
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|