This chapter describes how to configure the MessageQ Client. Refer to Table 3-1 for the configuration options for the MessageQ Client.
Note: Before using the MessageQ Client utility programs you should execute the following command to define the appropriate symbols:
@DMQ$EXE:DMQ$CL_SET_LNM_TABLE
To configure the MessageQ Client, use the MessageQ Client Configuration:, 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.
See Listing 3-1 for the MessageQ Client Configuration Utility Main Menu.
Listing 3-1 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 MessageQ Client Main Menu Options.
The Configuration Utility updates an initialization file, dmq.ini, that is used at run time by the MessageQ Client. 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 locations:
The location of the To begin configuring the MessageQ Client, select item 2, Configure, from the Main Menu. See Listing 3-2 for the MessageQ Client Configure Menu.
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 Configuration Utility.
Listing 3-2
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 connection to the 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.
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 Listing 3-3 are described in Table 3-4.
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.
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]:
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 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 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.
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.
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. 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.
The MessageQ Client allows you to log error messages to a file (dmqerror.log) It also allows run time message activity to be monitored by using the Event Watcher utility, or 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. 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. 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 Event Watcher (yes/no) [no]: y
Log Messages Sent to Trace File (yes/no) [no]:
Log Messages Received to Event Watcher (yes/no) [no]:y
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.
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 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.
To test your newly configured MessageQ Client, 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.
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 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 ParametersParameters Menu
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 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 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 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 Previous Menu
Enter Menu Selection >> 9
Listing 3-13 Detach from the Temporary QueueMain Menu
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 >> 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 Previous Menu
Enter Menu Selection >> 9
Main Menu
1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 3