|
|
Configuring the BEA MessageQ Client
This section describes how to configure the BEA MessageQ Client and covers the following topics:
Configuration Options, Parameters, and Menus
Configuring the BEA MessageQ Client is done by editing an initialization file, dmq.ini. This file is used at run time by the BEA MessageQ Client. The dmq.ini file can be shared by multiple BEA 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 locations:
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 BEA 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 BEA MessageQ Client Configuration Utility.
Refer to Table 3-1 for the configuration options for the BEA MessageQ Client.
Note: Before using the BEA MessageQ Client utility programs you should execute the following command to define the appropriate symbols:
@DMQ$EXE:DMQ$CL_SET_LNM_TABLE
Table 3-1 BEA MessageQ Client Configuration Options
Option
Description
Required?
Default Server
Network transport, server host name, and endpoint definition
Yes
Failover
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
Logging
Settings for logging error events and tracing messages to a log file
No
Tracing
Settings to enable run-time trace information about the API calls and Client library activity
No
To configure the BEA MessageQ Client, use the BEA MessageQ Client 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 attempts to locate dmq.ini by first looking in the current default directory, then using the DMQCL_INI_FILE logical name. |
-l |
Lists the current configuration settings (if used with the -f file option), or the default configuration settings |
-v |
Displays the BEA MessageQ Client Configuration Utility version number |
-h |
Displays a brief help message that describes the options for this command |
See Listing 3-1 for the BEA MessageQ Client Configuration Utility Main Menu.
Listing 3-1 BEA MessageQ Client Configuration Utility Main Menu
Main Menu (file: []dmq.ini)
1 Open
2 Configure
3 List
4 Save
5 Exit
Enter Selection:
Refer to Table 3-3 for a description of the BEA MessageQ Client Main Menu Options.
Option |
Description |
---|---|
Open |
Opens a specific dmq.ini file |
Configure |
Configure the BEA MessageQ Client |
List |
Lists the current (or the default) settings |
Save |
Saves the configuration changes or updates to the dmq.ini file |
Exit |
Exits the BEA MessageQ Client Configuration Utility |
To begin configuring the BEA MessageQ Client, select item 2, Configure, from the Main Menu. See Listing 3-2 for the BEA MessageQ Client Configure Menu.
Listing 3-2 BEA MessageQ Client Configure Menu Options
Configure Menu (file: []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 BEA MessageQ Client Library Server (CLS) consists of the following two items:
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.
If the primary default server is not available, the BEA MessageQ Client 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 BEA 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 BEA 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 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.
The server configuration options shown in Listing 3-3 are described in Table 3-4.
Listing 3-3 Default Server Options
Server Configuration
Network Transport Type (DECnet or TCP/IP) [TCP/IP]:
Server Hostname [arches]: dmqsrv
Server Endpoint [5000]:
Reconnect Interval (# of messages) [0]:
Automatic Failover Server
If the primary (default) server is not available and automatic failover is enabled, the BEA MessageQ Client provides the option of connecting to a failover CLS. By enabling automatic failover, a BEA 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 pams_attach_q. Failover is not used if automatic reconnect to the default server is enabled.
Using the failover capability requires additional planning and work in order for messages to be sent and received correctly. The message queues used by BEA MessageQ Client applications are implemented by the BEA 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 BEA MessageQ Client is likely to change (unless the BEA 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 BEA MessageQ server group.
The simplest use of automatic failover is when the BEA 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 BEA 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 BEA 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) BEA MessageQ group, the recoverable messages on the BEA MessageQ group where the default CLS is located are not delivered to the new queue address used by the BEA MessageQ Client.
Automatic failover is not appropriate for all applications. The BEA MessageQ server group and all disk-based queuing resources must also fail over to another system so that messages sent to the BEA MessageQ Client are received after a failover transition. For example, the BEA MessageQ server group can recover by restarting the BEA MessageQ group on another node in an OpenVMS cluster.
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 (DECnet or 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 set to yes, automatic failover is enabled. The failover server is used when the default server is not available and automatic failover is enabled. The use message interval option (see Table 3-4) must be greater than 0. |
Network Transport Type |
The network-level transport used to send messages to the BEA MessageQ CLS. Choices are either TCP/IP or DECnet. |
Host name |
The name of the host running the BEA MessageQ CLS. The host name must have a corresponding entry in the local hosts file or DECnet database. |
Endpoint |
The endpoint used by the BEA MessageQ Client and the BEA MessageQ CLS. The endpoint identifies either the DECnet object name or the TCP/IP port number the BEA MessageQ Client used to locate the CLS. The CLS uses the same endpoint to listen for client connections. For DECnet transport, the endpoint can range from 1 to 65535 inclusive. The endpoint value is concatenated with the prefix DMQCLS_ to create a unique DECnet object name (for example, DMQCLS_05000). For TCP/IP transport, the endpoint ranges from 1024 to 65535 inclusive. Port numbers less than 1024 are reserved. |
Configuring Message Recovery Services
Message Recovery Services (MRS) are the BEA 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 BEA MessageQ Client ensures delivery of recoverable messages to the CLS on the BEA 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 BEA 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 BEA 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 portion of the configuration process is optional if recoverable messaging is not used. See Listing 3-5 for the MRS configuration options.
Listing 3-5 MRS Configuration Options
MRS Configuration
MRS Enabled (yes/no) [yes]:
Journal File Directory []:
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-6 for the MRS configuration options.
Option |
Description |
---|---|
MRS Enabled |
If set to yes, MRS is enabled |
Journal File Directory |
Specifies the directory where the BEA 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. 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 Logging
The BEA MessageQ Client allows you to log error messages to a file (dmqerror.log) It also allows run time message activity to be monitored by writing the messages to a file (dmqtrace.log). 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. See Listing 3-6 for the logging configuration options.
Listing 3-6 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-7 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. If 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 To Trace File |
If set to yes, sends a copy of BEA MessageQ messages sent by the application to the dmqtrace.log message log file. |
Log Messages Received To Trace File |
If set to yes, sends a copy of BEA MessageQ messages received by the application to the dmqtrace.log message log file. |
Configuring Tracing
Tracing can be a useful debugging tool, because it allows you to observe BEA MessageQ Client processing activity. 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 file, dmqcldll.log, is 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 the API calls to the file dmqcldll.log. The default is no tracing. |
Trace Client library activity |
If set to yes, traces the internal Client activity to the file dmqcldll.log. The default is no tracing. |
Testing the Configuration Using the Test Utility
To test your newly configured BEA MessageQ Client, run the BEA 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 BEA MessageQ. The program also allows you to test various BEA MessageQ message delivery options and send messages to any process connected to the BEA 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
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 |
Bind Parameters |
Bind Queue |
Cancel Timer Parameters |
Cancel Timer |
Detach Parameters |
Detach Queue |
Locate Parameters |
Locate Queue |
Get Parameters |
Get Message |
Previous Menu |
Previous Menu |
Put Parameters |
Put Message |
Set Timer Parameters |
Set Timer |
Subscribe MOT Parameters |
Subscribe MOT |
View Current Parameters |
View Current Parameters |
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:
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 Subscribe MOT Parameters
11 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 Subscribe MOT Parameters
11 Previous Menu
Enter Menu Selection >> 4
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 [0] ? 9
Enter target queue [0] ? 1
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 from dmqcltest.
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 Subscribe MOT Parameters
11 Previous Menu
Enter Menu Selection >> 9
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 Subscribe MOT
11 Previous Menu
Enter Menu Selection >> 1
attached to queue 9.206
Listing 3-12 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 Subscribe MOT
11 Previous Menu
Enter Menu Selection >> 4
put message to queue 9.1
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 Subscribe MOT
11 Previous Menu
Enter Menu Selection >> 9
Listing 3-13 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 Subscribe MOT
11 Previous Menu
Enter Menu Selection >> 2
detached from queue 9.206
Listing 3-14 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 Subscribe MOT
11 Previous Menu
Enter Menu Selection >> 9
Main Menu
1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 3
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|