Creating a connection definition

In order to create a connection definition an administration message must be created and put to the administration queue. A reply must be received to indicate successful creation of a connection definition before any attempt is made to use the connection, indeterminate behavior may result if an attempt is made to use a connection before such as reply has been received.

In order to show how one might create a connection definition we shall use the examples.config.CreateConnectionDefinition example. A connection definition administration message has a number of methods to help create the message correctly. First of all we need to create an MQeConnectionAdminMsg:

MQeConnectionAdminMsg connectionMessage = new MQeConnectionAdminMsg();

Once we have created the connection administration message we need to set the name of the resource we wish to work on:

connectionMessage.setName("RemoteQM");

We now need to set the information in the administration message that will set the action to create and will provide the information for the route to our remote queue manager:

connectionMessage.create("com.ibm.mqe.adapters.MQeTcpipHistoryAdapter:
                         127.0.0.1:8082",
                         null,
                         null,
                         "Default Channel",
                         "Example connection");

There are a number of things to note about the information passed to the create method.

The first parameter is a colon delimited string and has a profound affect on what type of connection definition will be created. The string used in the above example will create a connection to a queue manager called RemoteQM using the communications adapter MQeTcpipHistoryAdapter running on the local machine listening at port 8082. If we had merely specified a queue manager name, for instance "ServerQM" then a via connection definition would have been created and we would have to either already have a connection definition for ServerQM or create one before we attempted to use the via connection definition.

The second parameter is really only useful for HTTP adapters that may run a servlet on the server. This is where you would define your servlet name which would then be passed within the HTTP header.

The third parameter allows the persistent option to be set or unset, although in reality this should be done with great care as the default values for persistence are set within the communications adapters so they are consistent with the protocol being used. For instance the MQeTcpipLengthAdapter and MQeTcpipHistoryAdapter both use persistence, that is the socket is kept open, the MQeTcpipHttpAdapter on the other hand uses a new socket for each conversation.

The fourth parameter defines the channel, this should always be set to "Default Channel".

The fifth parameter provides descriptive text for the connection definition.

We now need to add information to the administration message that will determine which queue manager receives the administration message.

connectionMessage.setTargetQMgr("LocalQM");

Specify that you want to receive a reply, if using the Msg_Style_Datagram, indicate that no reply was required. The reply indicates success or failure of the administrative action.

connectionMessage.putInt(MQe.Msg_Style, MQe.Msg_Style_Request);

The queue and queue manager that will receive the reply, this may not necessarily be the queue manager that created and sent the administration message. Using the default administration reply queue allows you to use the definition of the String provided in the MQe class. Also, the reply must arrive on the local queue.

connectionMessage.putAscii(MQe.Msg_ReplyToQ, MQe.Admin_Reply_Queue_Name);
connectionMessage.putAscii(MQe.MSG_ReplyToQMgr, "LocalQM");

A unique identifier must be added to the message before putting it onto the administration queue. This allows you to identify the appropriate reply message. Use the system time in order to do this.

String match = "Msg" + System.currentTimeMillis();
connectionMessage.putArrayOfByte(MQe.Msg_CorrelID, match.getByte());

You can now put our administration message to the default administration queue, the fourth parameter allows for an MQeAttribute to be specified with the fifth parameter allowing for an identifier that allows you to undo the put. As neither is required, specify null and zero respectively.

queueManager.putMessage("LocalQM",
                        MQe.Admin_Queue_Name, 
                        connectionMessage, null, 0);

Before we can safely use the connection definition we need to ensure it has been correctly created and must therefore wait for a reply. We specified the reply should be sent to the queue manager LocalQM on the default administration reply queue. We create a filter using the correlation id so we get the correct reply:

MQeFields filter = new MQeFields();
filter.putArrayOfByte(MQe.Msg_CorrelID, match.getBytes());

Now using the filter we have created we wait for a reply message on the default administration reply queue. The return from the waitForMessage method gives an MQeMsgObject, so we cast that to an MQeAdminMsg. The fourth parameter which we have set to null may be used for an MQeAttribute, this is set to null as we have not used security during this example, the zero passed in parameter five is for a confirm ID that may be used in an undo operation, again we have not used this. The last parameter defines how long to wait in milliseconds, we are waiting for three seconds.

// all on one line
MQeAdminMsg response = (MQeAdminMsg) 
                       queueManager.waitForMessage(queueManagerName,
                       MQe.Admin_Reply_Queue_Name,
                       filter,
                       null, 0, 3000);

Once we have received the reply we check to make sure we have a successful return code, there is additional checking done within the example, for the purposes of this manual we just look at the successful return. As can be seen there is a useful method on the administration message which will return a return code to us for easy checking.

switch (response.getRC()) {
   case MQeAdminMsg.RC_Success :
      System.out.println("connection created");
      break;

We have now successfully created a connection definition to a remote queue manager.


Terms of use | WebSphere software

(c) Copyright IBM Corporation 2004, 2005. All rights reserved.