JMS Postcard is a simple way to do the following:
To use JMS Postcard, make sure that the Java Messaging feature of WebSphere MQ for Windows (WebSphere MQ JMS) is installed. You also need a working Java Runtime Environment (JRE) at Java 1.3.1 level or later.
Before you can successfully run the JMS Postcard application, define the environment variables CLASSPATH, MQ_JAVA_DATA_PATH, MQ_JAVA_INSTALL_PATH, and MQ_JAVA_LIB_PATH. On Windows systems these variables are set as part of the install process. On other platforms you must set them yourself. For more information about these variables, see Environment variables.
Many operations that the Postcard application carries out on your behalf require the user to be a member of the WebSphere MQ administrators group (mqm). If you are not a member of mqm, get a member of the mqm group to set up the default configuration on your behalf. See JMS Postcard default configuration.
To start the JMS Postcard application, run the postcard script. This is supplied in the java/bin directory of the WebSphere MQ installation.
The first time that you run JMS Postcard, it asks you to complete the default configuration, which sets up a suitable queue manager to act as mailbox. See JMS Postcard default configuration.
Whenever you start a Postcard application, you must sign on and enter a nickname. (There are advanced options available on the sign-on dialog, see Sign-on advanced options for details).
The sign-on dialog has a check box labelled Advanced. Check this to see the extended dialog where you can choose which queue manager is used by the Postcard program.
To send a postcard successfully, you need two instances of the Postcard application with different nicknames. For example, suppose you start the Postcard application and use the nickname Will, and then start it again using the nickname Tim. Will can send postcards to Tim and Tim can send postcards to Will.
If Will and Tim are connected to the same queue manager, see Running JMS Postcard with one queue manager.
If Tim is on a different queue manager manager (on the same or a different computer from Will), see Running JMS Postcard with two queue managers.
When the postcard arrives successfully, you know that your WebSphere MQ installation and WebSphere MQ JMS are working correctly.
For an alternative way of verifying the installation of WebSphere MQ JMS, run the IVTRun application from the command line. See Running the point-to-point IVT for more information about this.
If you have already started the Postcard application with a nickname, for example, Will, and you want to send a postcard to a second nickname on this computer, follow these steps:
If you have already started JMS Postcard with a nickname, for example Will, and you want to send a postcard to a second nickname on a second queue manager on this, or another, computer, follow these steps:
either start from WebSphere MQ First Steps (to use the default configuration), or open the WebSphere MQ Explorer, right-click on the queue manager you want to use and click All Tasks->Start a Postcard...
Look in Tim's Postcard to see the message arrive, and double-click on it to see the postcard itself.
You can do this by selecting the message that arrived in Tim's list, and clicking Reply.
See also How JMS Postcard works.
The Postcard application needs a suitable queue manager to act as mailbox. See JMS Postcard default configuration for the easiest way to get one. You will be prompted to install this default configuration the first time you start the Postcard application (see Starting).
Instead of using the default configuration, you can also start the Postcard application using any other local queue manager.
If you want to send postcards to another computer, or to other queue managers, the default configuration must include the option of being joined in the same cluster. The other queue managers must either be in the same cluster or you must create a connection explicitly between them.
See also How JMS Postcard works.
Installing the default configuration creates a special queue manager (with queues and channels), and optionally joins it to a cluster, to enable you to use the JMS Postcard application to verify your installation and see messaging working.
On WebSphere MQ for Windows, the Default Configuration Wizard automatically opens when JMS Postcard is started and the wizard has not already been run on this computer.
On platforms other than Windows systems, you can also run the DefaultConfiguration script, provided that there are no existing queue managers on this computer. On Windows systems, run Default Configuration from First Steps.
This section tells you how the JMS Postcard works, including:
When JMS Postcard starts, it checks to see what queue managers exist on this computer, and initializes the sign-on dialog accordingly. If there are no queue managers at all, it prompts you to install the default configuration.
JMS Postcard uses the Java Message Service method queueConnectionFactory.createQueueConnection() to connect to the default queue manager.
All the time JMS Postcard is running, it polls a queue called postcard for incoming messages from other Postcard applications. If there is no queue called postcard, JMS Postcard creates one.
When JMS Postcard starts running, it creates a Java Message Service QueueReceiver object for the local postcard queue, providing as a parameter a selector string that filters the messages to be received from the queue by the Correlation Identifier (CorrelId field). The selector string defines that the postcard client should only receive messages where the CorrelId field matches the nickname of the user. The words from the message data are then presented in the JMS Postcard window.
If you did not enter a computer name in the On: field, JMS Postcard assumes that the recipient is on the same queue manager.
If you entered a name, JMS Postcard checks for the existence of a queue manager with this name, first using the exact name supplied, and then using a prefix in the same format as that created by the default configuration.
In both cases, it issues a session.createQueue('postcard'), and sets the base queue manager name to the string supplied.
Finally, it builds a JMS BytesMessage from your nickname and the words you typed in, and runs queueSender.send(theMessage) to put the message onto the queue.
When other instances of Postcard on this computer use the same queue manager and queue, the messages are being put and got from the one queue. This does, however, verify that the WebSphere MQ code installed on this computer is configured and working correctly.
JMS Postcard can only send to another queue manager if a connection to that queue manager exists. This connection exists because either both queue managers are members of the same cluster, or you have explicitly created a connection yourself. JMS Postcard can therefore assume that it can connect to the queue manager, and connects to it, opens the queue, and puts a message, as already described, leaving all the work of getting the message there to the WebSphere MQ cluster code. In other words, JMS Postcard uses only one piece of code for putting the message, and does not need to know whether the message is going to another computer.
In JMS Postcard, when session.createSender('postcard') is called, the cluster code checks the repository to find the other queue manager, and to check that the queue exists, and throws an exception if this was not possible for any reason.
When queueSender.send(theMessage) is called, the cluster code opens a channel to the other queue manager (creating it if necessary) and sends the message.
Discard the channel afterwards, if the cluster optimizing code does not need it. If the queue managers are on different computers, that is all handled by the cluster code.
If you sent a postcard message to John, but never ran a Postcard application with the nickname John, the message would sit on the queue for ever. To prevent this, JMS Postcard sets the Message Lifetime (Expiry) field in the Message Descriptor (MQMD) to 48 hours. After that time, the message is discarded, wherever it may be (possibly even still in transmission).
You can exchange messages between all the different types of Postcard application as follows:
Normally JMS Postcard uses standard Java Swing settings for font size and background color. But if it detects a postcard.ini file on startup, JMS Postcard uses settings specified in this file instead. You can also change the trace setting.
Edit the sample file postcard.ini in the bin directory of the WebSphere MQ classes for Java installation and set your preferred settings for font size, and screen foreground and background colors.
Background=000000 Foreground=FFFFFFThis example selects white text on a black background. The values represent intensity levels for red, green, and blue colors using a hexadecimal scale from 00 to FF. Other examples of colors are FF0000 (bright red), 00FF00 (bright green) and 0000FF (bright blue).
MinimumFont=20This example selects a minimum font size of 20 points. Any value smaller than 13 is ignored.
WebBrowser=nautilusThis setting is only applicable on non-Windows systems. The internal browser used for displaying online help information cannot be customized. This setting allows you to identify an alternative browser.
Trace=1Set this to start trace output. Note that the trace output is sent to the trc subdirectory of the directory defined by the MQ_JAVA_DATA_PATH system environment variable. If the application cannot write to this directory, trace output is directed to the system console.
You can also use the MQJMS_TRACE_LEVEL parameter on the java command line to start tracing. See Tracing programs for more about tracing applications.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
jmspc |