Skip to main content

skip to main content

developerWorks  >  WebSphere  >

Using WebSphere MQ binding with a client channel definition table

developerWorks
Document options

Document options requiring JavaScript are not displayed


Rate this page

Help us improve this content


Level: Intermediate

Fenglian Xu (xufengli@uk.ibm.com), Software Developer, WebSphere Enterprise Service Bus Development team, IBM

04 Apr 2007

A client channel definition table (CCDT) is a means of enabling Service Component Architecture (SCA) applications on WebSphere Process Server or WebSphere Enterprise Service Bus (WebSphere ESB) to communicate with WebSphere MQ. This article describes the use and benefits of the CCDT support provided by WebSphere Application Server V6.0, WebSphere Process Server V6.0.2, and WebSphere ESB V6.0.2. To help you avoid time-consuming configuration problems, the article also uses examples to describe common configuration problems and their solutions.

Introducing WebSphere MQ client channel definition table

The client channel definition table (CCDT) contains details of all client-connection channels defined in an IBM® WebSphere® MQ session. The table is a binary file named AMQCLCHL.TAB, and it is automatically generated when a client connection channel is created in WebSphere MQ. Each client connection requires the details of the server host name, server channel name, and listening port on the server. The CCDT hides this configuration information from users, who need to specify only the URL where the CCDT resides. However, inappropriate use of the CCDT can cause run-time problems when using WebSphere Application Server V6.0, WebSphere Process Server V6.0.2, and WebSphere ESB V6.0.2 (hereafter, for the sake of brevity, these three products together will be referred to as "WebSphere Application Server/Process Server/ESB"). Many questions about configuring WebSphere Application Server with WebSphere MQ have been posted on IBM forums, and this article should help answer some of those questions. The article has three main topics: creating a CCDT from WebSphere MQ and configuring WebSphere Application Server/Process Server/ESB to use the CCDT, solving common configuration problems, and using the WebSphere MQ binding with a CCDT from an SCA module.

Example of CCDT configuration

This section describes how to create and use a CCDT. You can create a CCDT with either MQ Explorer user interface, or the command line. The following example shows how to create a CCDT with MQ Explorer V6:

Obtaining the CCDT from WebSphere MQ

Assume you are using a newly created queue manager with MQ Explorer V6. To create a CCDT file suitable for use by WebSphere Application Server/Process Server/ESB:

  1. Create a queue manager called QMGR
  2. Create a client channel with called SYSTEM.DEF.SVRCONN under the manager QMGR

Step 1 simply creates a queue manager named QMGR and leaves everything else as default. Step 2 creates a client channel to communicate with a server channel under the queue manager QMGR. The server connection channel SYSTEM.DEF.SVRCONN is the system channel and is automatically created by the system when the queue manager QMGR is created. The client channel name must be the same as the server channel to which the client will be connected. Normally, the server channel can have any name chosen by the system administrator, but in order to use the CCDT from WebSphere Application Server/Process Server/ESB, the server channel name must be SYSTEM.DEF.SVRCONN.

The connection name can be either localhost(1414) or hostname(1414), depending on how you distribute the CCDT file. The local host is used only for a local WebSphere MQ server, while the hostname can be used for either a local or remote WebSphere MQ server, and it can be specified as either a host name or an IP address. Port 1414 is the default port used by WebSphere MQ, but you can configure the listener on a different port. An example of the client channel properties is shown in Figure 1 below.

The configuration created by the above two steps is contained in a file called AMQCLCHL.TAB in the directory $WMQ_HOME/Qmgrs/QMGR/@ipcc. To make this file available to WebSphere Application Server/Process Server/ESB, you can copy this file to a directory on the host where WebSphere Application Server/Process Server/ESB are installed. This table contains a list of client channels for the Queue Manager. Configuration information of each client channel and its associated server channel, listener port, and the WebSphere MQ server host name, is stored in the table.


Figure 1. Client channel properties
Client channel properties

To use the CCDT, the WebSphere MQ client uses a URL, as described below. Two queues must be defined -- one for receiving request messages, and one for sending response messages. For example, the queues REQUESTQ and RESPONSEQ could be created within WebSphere MQ Explorer.

The client channel name must be SYSTEM.DEF.SVRCONN for WebSphere Application Server/Process Server/ESB, as required by WebSphere Application Server V6.0.

CCDT URL conventions

The CCDT URL specifies the file location and is required by an MQ binding when the connection mode is selected to use a CCDT. The format of the CCDT URL depends on the operating system where the CCDT is located and how WebSphere Application Server/Process Server/ESB is distributed. The following formats cover all use cases:

  • When the CCDT is local to a WebSphere Application Server/Process Server/ESB installation on Windows®:
    file:///C:/Drive/AMQCLCHL.TAB or file:/C:/Drive/AMQCLCHL.TAB.
  • When the CCDT is located in the same network file system (NFS) as WebSphere Application Server/Process Server/ESB on UNIX® or Linux®:
    file:///Drive/AMQCLCHL.TAB or file:/Drive/AMQCLCHL.TAB.
  • When accessing a CCDT via FTP when the CDDT is remote to WebSphere Application Server/Process Server/ESB. The host where the CCDT resides must have an FTP server and the host where WebSphere Application Server/Process Server/ESB is located must have an FTP client. The credentials are required for security reasons: ftp://userName:password@myServer/definitionPath/AMQCLCHL.TAB.

The file protocols can use either three slashes ("///") or one slash ("/"), which is different from the FTP format. If you use two slashes in a URL employing the file protocol, it will cause a run-time error, as described below. For examples of accessing CCDT files on both local and remote systems, see WebSphere MQ V6 Java and JMS clients and the client channel definition table.

Configuring WebSphere Process Server and WebSphere ESB to use the CCDT

CCDT is used when the application is using an MQ export binding and an MQ import binding. You can configure the export binding when creating the SCA application in WebSphere Integration Developer V6.0.2. For details on how to create an SCA application with an MQ export binding, see the WebSphere Integration Developer information center.


Figure 2. MQ export binding properties
MQ export binding properties

When applying an MQ binding to an export in WebSphere Integration Developer, the properties sheet shown in Figure 2 is displayed. There are three sections: End-point configuration, Data format, and Function Selector. You need to fill in only the first section, End-point configuration. Set the MQ manager name field to QMGR, and the receive and send destination queue fields to REQUESTQ and RESPONSEQ respectively. These queues are used for receiving and sending messages. When the CCDT is selected as the connection mode, the CCDT file must be provided and must conform to the format described above. The host name, server channel, and port are greyed-out as they are irrelevant when using CCDT.

All binding properties will be deployed during installation and then used at run time. Once the application has been created and exported to an EAR file, it can be installed and started in the WebSphere Application Server/Process Server/ESB administrative console. The application should then be ready to receive messages from WebSphere MQ without additional configuration. However, you can also customise the CCDT URL property in the WebSphere Application Server/Process Server/ESB administrative console, as shown in Figure 3, in order to use a CCDT located in a different place:


Figure 3. Custom properties in the WebSphere Application Server/Process Server/ESB admin console
Custom properties in the WebSphere Application Server/Process Server/ESB admin console

Common problems and solutions

The previous section shows how to configure the CCDT from WebSphere MQ and how the CCDT is used by WebSphere Application Server/Process Server/ESB. This section describes common problems you may encounter while using the CCDT with a WebSphere MQ binding in WebSphere Application Server/Process Server/ESB, and their solutions.

Problems often occur when starting up SCA applications with WebSphere Application Server/Process Server/ESB. The most common problem is failure to create a connection factory or an MQManager. Error messages are in the WebSphere Application Server/Process Server/ESB run-time log file SystemOut.log, in the directory $WAS_INSTALL_ROOT\profiles\AppSrv01\logs\server1. Here are some sample errors:


Problem 1 000000a SystemErr R com.ibm.ws.exception.RuntimeWarning:
com.ibm.ws.runtime.component.binder.ResourceBindingException:
		invalid configuration passed to resource binding logic.
REASON: Failed to create connection factory: Error raised constructing AdminObject,
		error code: XACF CCDTURL : XACF CCDTURL

Problem 1 is caused by using an invalid CCDT URL such as: file://C:/Drive/AMQCLCHL.TAB. The solution is to follow the CCDT URL conventions described above.


Problem 2: 0000004d JMSExceptionL E   WMSG0018E: Error on JMSConnection
		for MDB export.test_Export_Parameters_003MQ , JMSDestination
WMQBindingsExportModule/test_Export_Parameters_003_MQ_RECEIVE_D  : javax.jms.JMSException:
		MQJMS2005: failed to create MQQueueManager for 'QMGR'
	at com.ibm.mq.jms.services.ConfigEnvironment.newException(ConfigEnvironment.java:586
	at com.ibm.mq.jms.MQConnection.createQM(MQConnection.java:2082)
	at com.ibm.mq.jms.MQConnection.createQMNonXA(MQConnection.java:1496)
	at com.ibm.mq.jms.MQQueueAgentThread.setup(MQQueueAgentThread.java:306)
	at com.ibm.mq.jms.MQQueueAgentThread.run(MQQueueAgentThread.java:1672)
	at java.lang.Thread.run(Thread.java:570)
---- Begin backtrace for Nested Throwables
com.ibm.mq.MQException: MQJE001: Completion Code 2, Reason 2423
	at com.ibm.mq.MQQueueManager.sequentialConstruct(MQQueueManager.java:904)
	at com.ibm.mq.MQQueueManager.<init>(MQQueueManager.java:865)
	at com.ibm.mq.MQSPIQueueManager.<init>(MQSPIQueueManager.java:83)
	at com.ibm.mq.jms.MQConnection.createQM(MQConnection.java:2009)
	at com.ibm.mq.jms.MQConnection.createQMNonXA(MQConnection.java:1496)
	at com.ibm.mq.jms.MQQueueAgentThread.setup(MQQueueAgentThread.java:306)
	at com.ibm.mq.jms.MQQueueAgentThread.run(MQQueueAgentThread.java:1672)
	at java.lang.Thread.run(Thread.java:570)

Problem 2 is caused by picking up the wrong client channel definition from the CCDT, which often happens when using a client channel with a name other than SYSTEM.DEF.SVRCONN. The solution in this environment is to make sure that there is only one entry in the CCDT, and that it is named SYSTEM.DEF.SVRCONN.


Problem 3: 0000000a MDBListenerIm W WMSG0019E: 
				Unable to start MDB Listener export.Export1MQ,
		JMSDestination TestExport/Export1_MQ_RECEIVE_D : javax.jms.JMSException: MQJMS2005:
		failed to create MQQueueManager for 'localhost:QMGR'
	at com.ibm.mq.jms.services.ConfigEnvironment.newException(ConfigEnvironment.java:586)
	at com.ibm.mq.jms.MQConnection.createQM(MQConnection.java:2298)
...
---- Begin backtrace for Nested Throwables
com.ibm.mq.MQException: MQJE001: Completion Code 2, Reason 2278
	at com.ibm.mq.MQQueueManager.sequentialConstruct(MQQueueManager.java:946)

Problem 3 is caused by an incompatible MQ library mq.jar between WebSphere MQ V6.0 and WebSphere Application Server/Process Server/ESB V6.0.2, since the base WebSphere Application Server V6.0 uses the WebSphere MQ V5.0 mq.jar. The solution is to configure the WebSphere Application Server environment variable MQ_INSTALL_ROOT to point to the operating system environment variable WMQ_INSTALL_ROOT. Alternatively you can copy com.ibm.mq.jar and com.ibm.mqjms.jar from $WMQ_INSTALL_ROOT\java\lib to $WAS_INSTALL_ROOT\lib\WMQ\java\lib.

Conclusion

This article has described how to configure a CCDT from WebSphere MQ V6.0 for a JMS client to send and receive messages, and how to use a CCDT to bind to WebSphere MQ from WebSphere Application Server/Process Server/ESB. It also presented some common run-time problems and their solutions, which should save time and trouble if you are using SCA applications and the CCDT to bind to WebSphere MQ from WebSphere Application Server/Process Server/ESB V6.0.2.

Acknowledgements

The author would like to thank her colleagues and her manager in the WebSphere ESB development team at the IBM Hursley Software Lab in the UK. She also thanks Matthew White from the WebSphere MQ team at IBM Hursley, and extends a special thank-you to her colleagues Ian Parkinson, Ewan Withers, Tim Raff, and James Siddle for their kindly encouragement and for reviewing this paper.



Resources



About the author

Photo of Fenglian Xu

Dr. Fenglian Xu is a Software Developer on the WebSphere Enterprise Service Bus Development team at the IBM Hursley Software Lab in the UK. Her expertise includes WebSphere MQ JMS bindings, WebSphere Application Server, and WebSphere Enterprise Service Bus. She has worked in various IT companies on both middleware to applications, and with the UK eScience pilot project GEODISE, which involved workflow and SOA. She received a B.Sc. in Applied Math and Software Engineering from Xian Jiaotong University in China in 1989, and a Ph.D. in Computer Science from the University of Southampton in the UK in 1998. You can contact Fenglian at xufengli@uk.ibm.com.




Rate this page


Please take a moment to complete this form to help us better serve you.



YesNoDon't know
 


 


12345
Not
useful		Extremely
useful
 


Back to top