Export (0) Print
Expand All

Microsoft BizTalk Adapter for MQSeries White Paper

 

July 2002

Summary

Learn how the Microsoft BizTalk Adapter for MQSeries will allow you to incorporate BizTalk Server into a system that is using IBM's MQSeries enterprise integration messaging standard. (41 pages)

Contents

The BizTalk Adapter for MQSeries Connectivity Solution
Solution Scenario
Architecture
Appendix
Troubleshooting
MQSeries Overview
Additional Information

The BizTalk Adapter for MQSeries Connectivity Solution

Ee265631.bts_accmqseries_01(en-US,BTS.10).gif

Overview

The Microsoft® BizTalk® Adapter for MQSeries is a connectivity solution that allows the BizTalk Server family of integration servers to be plugged into an enterprise that has chosen MQSeries as the messaging standard. The development of this solution was motivated, in part, by the following issues:

  • Accommodating customer requests for simple installation and configuration, and an MQSeries connectivity solution
  • Leveraging BizTalk Server in enterprises where MQSeries is the chosen messaging standard
  • Supporting message sizes up to 100MB
  • Providing MQSeries Support
  • Providing a Plug-and-Play MQSeries messages to BizTalk Server
  • Defines a bridge between yesterday's messaging protocol and today's integration server

These factors were strong stimulus in the very rapid design, implementation, and release of this connectivity solution. BizTalk Adapter for MQSeries is a key addition to the BizTalk Server suite of receive services that provide a set of listeners for various communication protocol standards. The listeners attach a protocol, for example HTTP, FTP, and/or MQSeries, to an enterprise application integration (EAI), business-to-business (B2B), or application-to-application integration (A2A) trading relationship.

BizTalk Adapter for MQSeries Benefits and Values

Asynchronous computing models are inherently scalable based on their ability to fully utilize the computing resources in a manner that parallels the state of affairs in the computing world today. The BizTalk Adapter for MQSeries functions very well in this computing environment by achieving the following:

  • Allowing organizations using MQSeries as their messaging standard to utilize BizTalk Server as the integration server
  • Simplifying installation, configuration, and deployment of BizTalk Server and MQSeries interoperability solutions
  • Easing the development of BizTalk Server and MQSeries solutions
  • Providing send and receive services between MQSeries and BizTalk Server
  • Including bi-directional Distributed Transaction Support (DTS) between MQSeries environments and BizTalk Server (on the Windows platform only).
  • Allowing MQSeries to bridge the need for once and only once delivery of messages cross-platform

BizTalk Server provides enterprise application integration (EAI), business-to-business (B2B) integration, business process automation, and a Plug-and-Play connectivity solution for MQSeries environments. Other solutions from Microsoft and additional vendors already exist, but the solutions did not support the MQSeries messaging protocol in a direct manner; they were not optimized for transporting messages to destinations or submission of documents to the BizTalk Server Messaging Engine.

The BizTalk Adapter for MQSeries removes barriers to easy adoption and use of BizTalk Server. This connectivity solution provides a zero code solution to enterprise customers. Enterprises can build solutions using BizTalk Server as the integration server standard without requiring any coding on the part of developers. The combination of BizTalk Server and the BizTalk Adapter for MQSeries provides a Plug-and-Play, loosely coupled integration architecture for MQSeries and BizTalk Server. The use of a very straightforward graphical user interface for configuration simplifies the administrative tasks required to quickly implement various solution scenarios.

How the BizTalk Adapter for MQSeries Works

To aid in explaining how the Microsoft BizTalk Adapter for MQSeries works, the technical concepts and goals are introduced by reviewing the following block diagram. This review is followed by a discussion of the illustration from both an outbound perspective and an inbound perspective. The BizTalk Adapter for MQSeries includes the following components:

  • Application Integration Component
  • Receive Service
  • MQHelper
  • Microsoft Management Console (MMC) Snap-In

The specific components of the BizTalk Adapter for MQSeries are discussed in greater detail in the "Architecture" section of this document.

The following diagram illustrates a source application delivering a document to BizTalk Server. The Messaging Engine within BizTalk Server (BTS in Figure 2) supports the use of multiple protocols. The source application could reside on the Internet and utilize the HTTP protocol to deliver the message to a Web server that stores the documents in an MQSeries queue or it could reside within an enterprise and deliver the message via MSMQ, File, SMTP, or FTP.

The following diagram illustrates a solution that leverages the HTTP protocol.

Ee265631.bts_accmqseries_02(en-US,BTS.10).gif

Figure 2: Source Application Delivering to BizTalk Server

Outbound

In an outbound direction, where an MQSeries enabled server is the destination, the BizTalk Server Messaging Engine locates and invokes a document processing channel. This is followed by delivery of the document through a messaging port. The messaging port determines how the message is processed inside the BizTalk Server Messaging Engine and which communication protocol is used to deliver the document to the destination. The Messaging Engine creates a transactional context that is joined by the MQSeries application integration component (AIC) during its invocation. The AIC acts as the configured end point of a messaging port. The AIC will establish contact with an instance of the MQHelper component that is deployed as a simple DLL on a Microsoft® Windows® 2000 Server (W2KServer2 in the diagram). The document is passed to the MQHelper DLL, which implements the MQSeries run time support required to insert the document into the target MQSeries queue on the second server. In this diagram the process ends when the Queue Manager delivers the message to the remote server in New York.

Inbound

Reversing the flow of the diagram for an inbound message processing scenario, New York City is the source and the Source Application is the destination. Note that many of the services and components are contained within the objects shown in the high-level overview, and therefore not called out specifically in the diagram. The MQSeries receive service polls one or more remote transmission queues located on the Windows 2000 server (See W2Kserver in Figure 2) looking for messages. Upon finding messages in the target queue, a transaction is started between the receive service and an MQHelper instance on the second server. The MQHelper contains the implementation of the MQSeries run time that provides the capability of extracting messages in batches. The messages are extracted from the remote queue. Conversions between ANSI and Unicode are performed on the messages. Next, the messages are transferred to a BizTalk Server instance using Distributed Component Object Model (DCOM) and submitted into the Work Queue for asynchronous processing. The documents are processed according to the tasks requested during definition of the messaging channel. The document is processed and routed to the appropriate destination via a messaging port transport component.

BizTalk Messaging

Microsoft® BizTalk® Server provides an environment for developers and/or administrators to configure the various elemental components of a solution by using visual tools. This drastically reduces the amount of programmatically developed business logic required to create a solution. The general high-level process is summarized as follows:

  • Messages are submitted to BizTalk Server through a COM+ application using the IInterchange interface or one of the File, MSMQ, or HTTP
  • Messages are matched against ports and channels. The matching is based either upon the submission parameters included with the documents presented to BizTalk Server, or upon the contents of marked elements in the BizTalk Server internal XML document format (using the XML based query language XPATH). The source identifier, destination identifier, and message type are three key pieces of a SQL query. The query is executed to determine one or more channels to process the documents
  • The information describing ports and channel definitions and all other configuration data is stored in the BizTalk Server repository
  • Asynchronous messages are held in a queue until execution time. If failures in transport or processing occur, messages are moved to the Retry Queue or the Suspended Queue. The Scheduled Queue holds messages that are processed at a specifically scheduled time.
  • The Work Queue is polled by one or more BizTalk Server Messaging services. The Messaging services are generally located on separate computers that have been clustered as a group of BizTalk Servers.
  • As messages are being processed and assigned to one or more channels for processing, each message passes through a sequence of processing stages. The processing stages can include validation, transformation, enveloping, encoding, signing, encryption, and/or serialization. The messages are then transported to a location specified in the messaging port data.
  • Messages are tracked in a tracking database after having been processed and prior to being forwarding to their destination.
  • In BizTalk Server, the trading relationship includes the channel and port. The messaging channel represents the entity that processes a message by performing tasks such as encryption and decryption, documenting signing, document filtering and tracking, and other processing steps inside a "pipeline".
  • The messaging port is first defined to be either an internal or external relationship. This definition maps to an enterprise application integration (EAI) or a business-to-business (B2B) data trading relationship. The port is the object defined first in the setup of a trading relationship. After the port is defined, there is an option of associating one or more channels to that particular port

Summary

The BizTalk Adapter for MQSeries connectivity solution allows customers to combine BizTalk Server with their MQSeries messaging protocol infrastructure. The connectivity solution extends the reach of BizTalk Server to the thirty-five platforms that are supported by the MQSeries product line. Enterprise customers can select BizTalk Server as their integration server of choice without having to discard and replace any of their existing MQSeries infrastructure components.

BizTalk Server plugs into the infrastructure as an integration server. This lets an enterprise break the hardwired direct connections between heterogeneous application systems by allowing conversion of messages from one protocol and/or data format to another. The BizTalk Server and BizTalk Adapter for MQSeries solution also simplifies administration of complex messaging solutions, and expands the reach and depth of enterprise integration strategies. This connectivity solution links the leading messaging-oriented products. The BizTalk Server and BizTalk for MQSeries combination connects yesterday's leading messaging today's fastest growing integration server.

Solution Scenario

Many enterprise customers want to leverage BizTalk Server within an MQSeries messaging environment. The question most enterprise decision makers ask with regard to implementing solutions combining these technologies is "How much effort is required to construct a robust solution without requiring coding on the part of my developers?" To answer this question, we will walk through the steps required to construct a solution.

Seeking Ease of Integration

Ease of integration is one of the most important factors considered by key decision makers. The common approach for quickly integrating BizTalk Server and MQSeries is defining a remote queue on an MQSeries Server and binding that queue to BizTalk Server as mentioned later in this document. The creation of the solution is deceptively simple considering that two totally distinct technologies can be combined to form complex integrated solutions in a Plug-and-Play manner.

Morgan Trust and Securities Bank Scenario

This scenario walks through a process of implementing functionality that matches key tasks. The scenario is one in which Morgan Trust and Securities Bank wants to leverage the abilities of its existing MQSeries messaging infrastructure. The CIO of the bank has recently decided to utilize the existing messaging infrastructure based on MQSeries, and an integration server to create better-quality solutions. To that end, the CIO has decided that Microsoft BizTalk Server is the right choice for the integration server based on its ease of use and price per value rating.

The CIO wants to design a solution that will guarantee the delivery of various payloads coming into the main bank and responses being routed back to each branch. The key feature he wants to see implemented is the dynamic routing of payloads via the content-based routing and encryption and decryption capabilities of BizTalk Server. The CIO wants to use BizTalk Server because he knows that Microsoft offers a zero code integration solution between the existing messaging infrastructure and BizTalk Server. The following figure illustrates the bank's headquarters-to-branch architecture.

Ee265631.bts_accmqseries_03(en-US,BTS.10).gif

Figure 3: Morgan State Corp-To-Branch Architecture

The CIO contracted with a consultant to guide his development team members during the design and implementation of this solution. The development team members chose to keep the solution simple to minimize the amount of custom code required to build the solution components. In this scenario the corporate office to Los Angeles branch integration is configured first. The steps that are necessary to construct the solutions are as follows:

  • Create a port and channel within BizTalk Server.
  • Configure the BizTalk Server MQSeries receive function.
  • Export the MQSeries Remote Queue definitions.
  • Import the MQSeries definitions via the MQSeries Explorer.
  • Define mapping between the BizTalk Server channel and the remote queues.
  • Start the BizTalk Adapter for MQSeries receive service.
  • Verify the receive function configuration.
  • Integrate the AICMQ.
  • Create BizTalk Server receive function.
  • Validate BizTalk Server receive function setup.

The following sections describe the process the development team used to develop a banking solution that links the corporate headquarters and various local and remote branch banks.

Port Definitions

Prior to the definition of a messaging port, the development team determined applications that would be targets for integration via BizTalk Server and the BizTalk Adapter for MQSeries. The Home organization was established and the channels to each of the remote sites were defined on the Queue Manager servers via the MQSeries Explorer. Those first steps being complete, the next action is to set up a port definition on the BizTalk Server instance. The port is defined by using the following steps:

To define a port

  1. Load the Messaging Manager.
  2. Click File, click New Messaging Port, and then click To an Application.

The following dialog box is displayed:

Ee265631.bts_accmqseries_04(en-US,BTS.10).gif

Figure 4: Configuring Los Angeles Messaging Port

  1. In the Name field, type Los Angeles as the port, and then click Next.

Ee265631.bts_accmqseries_05(en-US,BTS.10).gif

Figure 5: Selection of Application Name

The Messaging Port configuration wizard prompts for the creation or selection of a destination application or XLANG schedule. The developers and administration decide to use BizTalk Server Messaging by selecting a pre-existing or new application.

  • Click Browse.

Ee265631.bts_accmqseries_06(en-US,BTS.10).gif

Figure 6: Primary Transport - Application Integration Component

The Primary Transport dialog is displayed and the developers and administrator are given the opportunity to select from the currently supported protocols (Application Integration Component, File, HTTP, HTTPS, Loopback, Message Queuing, and SMTP). The developers choose Application Integration Component.

  • Next, click Browse.

Ee265631.bts_accmqseries_07(en-US,BTS.10).gif

Figure 7: Selection of AICMQ MQPipeline Component

After clicking Browse, the Select A Component dialog displays so that the developer or administrator can select an AIC. The team highlights AICMQ MQPipeline component.

  • Click OK.

Ee265631.bts_accmqseries_08(en-US,BTS.10).gif

Figure 8: AICMQ Binding to Messaging Port

Now, the primary transport has been set as Application Integration Component and the AICMQ MQPipeline pipeline component has been selected as the transport for this messaging port. The SMTP Return e-mail address field remains dimmed.

  • Click OK.

Ee265631.bts_accmqseries_09(en-US,BTS.10).gif

Figure 9: Messaging Port with AICMQ Selected

The team selects the destination application and defines the AICMQ MQPipeline component as the primary transport. The combination of the application and a transport constitute two key pieces of information in the definition and setup of an enterprise application integration (EAI) scenario in BizTalk Server. The team decides to not invoke use of a service window and so leaves this checkbox unselected. They also do not wish to provide a back up transport for the communication between the home office and the Los Angeles branch office during the initial setup of the solution scenario.

  • Click Next.

Ee265631.bts_accmqseries_10(en-US,BTS.10).gif

Figure 10: Envelope Selection

The team does not require a special envelop for their initial implementation so the Envelope information field is left at the default setting of None. The Organization identifier field defaults to the Home Organization selection. The high level steps are as follows:

  • Execute the primary setup.cmd command file
  • Obtain and install digital certificates
  • Create a secure port and the following channel
  • Create any receive functions

Detailed descriptions of the tasks necessary to complete this process are available in the online documentation.

  • Click Next.

Ee265631.bts_accmqseries_11(en-US,BTS.10).gif

Figure 11: Security Information

The Security Information dialog displays as shown above. To configure the server correctly, the team opens the BizTalk Server 2002 Help facility and searches for the Encryption and Decryption Sample topic. They follow this topic to allow the documents flowing between the home office and the Los Angeles branch to leverage the security capabilities built into BizTalk Server. The team opts to leave the Create a channel for this messaging port checkbox selected.

  • Click Finish.

The previous step concludes the Messaging Port definition and launches the New Channel wizard. The specifics of this portion of the solution configuration lead the team into the next section.

Channel Definitions

The team members were informed of the need to define a messaging channel, during their sessions with the consultant. They define a very straightforward channel to meet their needs to provide the appropriate amount of processing. They agree to name the channel "Los Angeles" to facilitate a natural link between the port and channel. They start the configuration process by completing the dialog that is displayed below in the following figure.

Ee265631.bts_accmqseries_12(en-US,BTS.10).gif

Figure 12: Channel Definition

The team chooses not to implement this channel as a receipt channel, so they leave the This is a receipt channel checkbox unselected.

  1. Type Los Angeles into the Name field.
  2. Add any necessary comments to the Comments field.
    Important   Leave the This is a receipt channel checkbox unselected.
  3. Click Next.

Ee265631.bts_accmqseries_13(en-US,BTS.10).gif

Figure 13: Organization Name

The team associates the channel with the default organization name of "Morgan State" which resides in the city of Los Angeles. They configure the channel to generate or expect a receipt by not selecting either of the corresponding checkboxes.

  • Click Next.

Ee265631.bts_accmqseries_14(en-US,BTS.10).gif

Figure 14: Inbound Document Definition

The solution requires that certain values be generated at execution time. The date is a value that must be calculated and passed to the target field in the format requested by the destination. The logical place for such conversion to occur is a BizTalk Server transformation map.

One of the developers on the team loads the source and destination specifications into the BizTalk Mapper and then connects all of the fields except the date field.

Click here to see larger image

Figure 15: Map Definition with Minimal Conversions

At this point, the team creates a transformation map that references their initial specification as the source and destination document specification. The outbound flow must have the date changed to the current date. Functoids are used to pass the current date information to the target date field and provide a flat discount rate to the purchase order total field in each of the detail records.

The BizTalk Server Mapper allows the development team to define, map, and then test the validity of the map. The Mapper relieves the development team of the need to understand low-level details of XML and Extensible Style Language Transformation (XSLT). The Mapper supports the following operations:

  • Copying Source content to Destination nodes
  • Various mathematical calculations
  • Logical operations
  • String conversion
  • Indexing and substring operations
  • Conversion of values during looping operation
  • Performing lookup and substitution of values at run time
  • Integration of VBScript and JScript snippets at design time to execute at run time
  • Conversion of the graphical element to their XSLT representations
  • Validation of the mapper via simulation instance passing though the map

Many of the items above describe the combination of the capabilities of the mapper and pre-built functoids. Further explanations about how the BizTalk Mapper can be utilized are found in the online Help document in the "BizTalk Mapper" section.

Returning to the scenario, the team goes back to the Messaging Manager to associate the map with the channel as shown in the next figure.

The development has defined the map associated with the document definition as shown in the Channel Properties dialog box.

Ee265631.bts_accmqseries_16(en-US,BTS.10).gif

Figure 16: Toggling on Transformation Using a Map

The Channel Properties dialog box (above) shows the map being associated with the Los Angeles messaging channel.

  • Click Browse.

Ee265631.bts_accmqseries_17(en-US,BTS.10).gif

Figure 17: Map Selection

The Select a Map from the WebDAV Repository dialog is displayed so that the developer or administrator may pick a specific map. The Los Angeles map is highlighted as the map of choice.

  • Click Open.

Ee265631.bts_accmqseries_18(en-US,BTS.10).gif

Figure 18: Map Selection -Los Angeles

The figure above shows the outbound document definition with the associated map that was just created in the previous section. The development team will return to this document at a later time to implement the document signing steps after the certificates have been acquired and are ready for deployment in the production environment.

If transformation operations were not required and a simple pass through operation was sufficient for the processing of the documents, there would be no need to specify a map. Neither would there be a need to leave the Map inbound document to outbound document checkbox unselected. A transformation map would be neither created nor selected.

This scenario does not include signing the document using a certificate. BizTalk Server online documentation and samples provide excellent examples of how to install the certificates and associate one to a document. The certificate allows trading partners to verify that the document came from the party that obtained a digital certificate, and shared appropriate information with each trading partner. The "Certificates Overview" topic is an excellent starting point in the online documentation. Other topics discussed are the "Understanding Certificates" and "Certificates Needed by BizTalk Server".

To continue the scenario and procedure:

  • Click Next.

The messaging port metadata is stored in the BizTalk Server repository and in the New Channel dialog box Document Logging is displayed as shown in the next figure.

Ee265631.bts_accmqseries_19(en-US,BTS.10).gif

Figure 19: Logging Specification

This dialog provides the development team an opportunity to determine how the inbound and outbound document data is logged for use in audit, reporting, and other tracking and verification operations. The dialog lets the developer or administrator turn on document tracking for both the native and XML format of inbound and outbound documents by selecting one of the checkboxes.

After selecting one or more of the check boxes, BizTalk Server makes the data associated with the logging process available in the repository in native format, or in BizTalk Server internal XML format.

  1. Click Next.
  2. Click Advanced.

The Override Messaging Port Defaults dialog box is displayed as shown in the next figure.

Ee265631.bts_accmqseries_20(en-US,BTS.10).gif

Figure 20: AICMQ MQPipeline Component Properties

The AICMQ MQPipeline component is shown as the Primary transport component selected as the definition of a messaging port earlier in the configuration of this scenario. The dialog box also includes tabs for defining Backup Transport, and Envelope.

  • Click Properties.

The next dialog box requires parameter entries associated with the remote Windows 2000 Server instance, and the MQSeries Queue Manager.

Ee265631.bts_accmqseries_21(en-US,BTS.10).gif

Figure 21: Remote Queue Manager and Queue Properties

The AICMQ MQPipeline Properties dialog box is utilized to configure components to setup a DCOM connection between the AICMQ MQPipeline and the MQHelper DLL. The AICMQ does not implement the functionality to handle payload submission into a transmission into an outbound queue. The MQHelper DLL residing on the Windows 2000 Server implements the various get and put operations. In the case of the AICMQ, the MQHelper executes an MQSeries API MQPut operation on the behalf of each AICMQ pipeline component.

  1. Type Los Angeles as the MQSeries Server.
  2. Type LAQMGR as the MQSeries Queue Manager Name.
  3. Type LosAngelesXmitq as the MQSeries Queue Name.

The next step is to define and export queue definitions.

Definition and Export of Transmission Queues at Headquarters

Next, the development team defines and exports various transmission queue locations. The BizTalk Adapter for MQSeries requires an MMC Snap-In as the configuration user interface. A job (object) must be created using the Snap-In. Jobs are created by doing the following:

  1. Click Start.
  2. Click Programs.
  3. Click Microsoft BizTalk Adapter for MQSeries.
  4. Click Microsoft BizTalk Adapter for MQSeries Configuration.

The configuration Snap-in is displayed as shown in the following figure.

Click here to see larger image

Figure 22: MQSeries Configuration Snap-in

The configuration Snap-in provides the user interface for defining a job, and associates mapping inbound documents to a receive service and a BizTalk Server channel.

  1. Expand the Microsoft BizTalk Adapter for MQSeries node.
  2. Right-click, point to New, and then click Job.

The job parameter for MQSeries Host Name (Los Angeles), Queue Manager Name (QM_LosAngeles), and the Transmission Queue Name (LAXmit) are chosen for the LA branch office. The job properties are typed into the following dialog box.

Ee265631.bts_accmqseries_23(en-US,BTS.10).gif

Figure 23: MQSeries Job Parameters

The MQSeries Host Name represents a remote Windows 2000 Server computer that has MQSeries software installed with a Queue Manager configured and waiting for messages. The Queue Manager Name should match the name of one of the Queue Managers setup on the remote computer via the MQSeries Explorer. The Transmission Queue Name is the name of a remote queue that will be polled by the MQSeries receive service for message batches via the MQHelper DLL using the DCOM protocol.

Accepting the default parameters provides the following Advanced Properties dialog box:

Ee265631.bts_accmqseries_24(en-US,BTS.10).gif

Figure 24: Job Advanced Parameters

  • Click OK to accept the values in the General and Advanced tabs of the Job Properties dialog box.

The team's next step is to define a Mapping between the MQSeries receive service and the remote MQSeries Messaging Server.

Linking BizTalk Server and Remote Transmit Queues

The implementation of the BizTalk Adapter for MQSeries does not utilize local queues. All queues are described as transmission queues in that they are all located on the Windows 2000 Server that hosts the MQSeries Queue Manager. This approach requires that a link be established between the BizTalk Server computer and the remote MQSeries Server. This provides the BizTalk Adapter for MQSeries with information needed to allow the receive service to poll the remote queue via the MQHelper DLL. Also note that MQSeries names are case sensitive.

Upon finding messages in the queue, the receive function collects one or more messages in a batch and delivers them to one or more BizTalk Server instances. The steps to create the mapping are as follows:

  1. Select the Job created previously
  2. Right-click, point to All Tasks, and then click Export MQS definitions.

Ee265631.bts_accmqseries_25(en-US,BTS.10).gif

Figure 25: Exporting MQSeries Transmit Queue Definitions

This launches the following dialog box that allows the queue definitions to be stored in the file system on the BizTalk Server computer.

Ee265631.bts_accmqseries_26(en-US,BTS.10).gif

Figure 26: Saving the Queue Definition

  • Type a job name, and then click Save.

Clicking Save causes the queue definitions to be written to the local file system. LosAngeles.mqs is used as the file name in the case of the Los Angeles branch office queue definition. The same naming convention is used for each of the queue definition files of the other branches. Clicking Save, the following message box is displayed confirming that the definitions were saved to the file LosAngeles.mqs.

Ee265631.bts_accmqseries_27(en-US,BTS.10).gif

Figure 27: Queue Definition files Success Message

The team duplicates the process of defining and exporting the MQSeries queue definitions for the Los Angeles office using the previous steps for each branch office. The next section discusses accomplishing this task for a single location. Each of the previous steps should be duplicated for each of the other branch offices.

Import of Queue Definitions at Remote Offices

Importing queue definitions at each of the branch offices is a straightforward process. The queue definitions are provided to each branch office and local resources complete the process of importing the definitions and any additional configurations that are required to complete the links between the BizTalk Server configuration at headquarters and each branch office.

MQSeries Explorer and a command line program (RUNMQSC) are used to import the queue definitions into the queue manager at each branch office. The RUNMQSC program is executed at a Windows DOS prompt. The command is:

runmqsc {queue manager} <export file name> {output file name}

The syntax shown above starts a command session. This allows the local or remote queue manager to define transmission queues. The MQSeries RUNMQSC program requires the name of export file, and optional output file names into which the responses are routed. Please recognize that RUNMQSC is a command program that will for whatever reason, capitalize the Queue Manager name, if you want to use a name that combines upper and lower case characters, the administrator or developer should execute the command manually through the UI or via the command-line. The Los Angeles branch executes the following:

runmqsc QM_LosAngeles <LosAngeles.mqs> LosAngelesOut.txt

This command generates an output file that holds the responses returned by the RUNMQSC program. The branch office reviews the file to ensure that the queue definitions completed successfully. The contents of the file are displayed in the following text:

Ee265631.bts_accmqseries_28(en-US,BTS.10).gif

Figure 28: MQSeries Queue Definition Import Responses

The response file shows that the queue definition task file has completed successfully by defining the LosAngelesXmit transmission queue. The last 4 lines show that the RUNMQSC program successfully executed 2 commands. This indicates that the queues were created on the remote server. The creation queues can be validated by loading the MQSeries Explorer on the Los Angeles server to see that the queue shows up in the queue listings as a local queue definition. The next figure confirms the queue was created on the correct server.

Click here to see larger image

Figure 29: MQSeries Explorer Displaying LOSANGELESXMIT Queue

With defining and importing the queues completed, the team defined a small test scenario that will be utilized to ensure that documents are successfully moved between the headquarters and the branch offices.

Each branch office can use a small test harness program to place a message in a transmit queue and a development team member at the headquarters office can confirm the arrival of the simple message. The headquarters team will leverage a test harness program to extract the message from BizTalk Server and process a portion of the message by making a change to a value and sending the message back to the correct branch office.

Additional load and stress test are conducted to ensure that the configuration of the solutions perform well under various scenarios designed to test the scalability, fault tolerance, and other areas of concern.

This MQSeries Explorer application is started by typing the program name at the prompt and then entering one or more commands during a session. Typing END at the prompt completes the session. The program can be run on Windows NT or Windows 2000 to create, alter, or delete queues and channels. The program can also be utilized to alter queue manager attributes.

Implementing encryption and signing of documents as required by banking standards can improve the solution. Each step in the process of building the infrastructure and deploying the prototype solution is documented. Progress of the solution will continue to be tracked and recorded as the various processes are completed.

Architecture

The BizTalk Adapter for MQSeries utilizes three components and a graphical user interface (GUI) to provide a simple but extremely effective architecture. The components are:

  • Microsoft Management Console (MMC) Snap-in
  • Application Integration Component (AIC)
  • Receive Function
  • MQSeries Run Time Services

The following figure shows the components as they are naturally distributed on the BizTalk Server and the MQSeries Servers, excluding the graphical user interface.

Ee265631.bts_accmqseries_30(en-US,BTS.10).gif

Figure 30: BizTalk Adapter for MQSeries Architecture

Microsoft BizTalk Adapter for MQSeries supports the following deployment models:

  • Receive Function – A single MQSeries Queue Manager is polled by a single BizTalk Server receive computer. Messages are gathered in batches as configured by the user in the MMC Snap-in. The necessary conversions from ANSI to Unicode are made prior to the payload being submitted to BizTalk Server for transformation and routing. After all messages contained in a batch are processed, the server is reinitialized and processing can proceed based on the next batch of messages arriving on the BizTalk Server instance.
  • Multiple MQSeries Queue Managers to one BizTalk Receive Server – In an enterprise that has chosen MQSeries as the messaging standard, BizTalk Server is often chosen as the hub. In this scenario, many MQSeries Queue Managers integrate with a single BizTalk Server instance that provides receive services.
  • Single MQSeries Queue Manager to Multiple BizTalk Receive Servers – Some enterprises scenarios require a very high level of inbound message reception and processing. In this solution scenario, multiple BizTalk Server receive computers are set up and configured to handle the inbound messages being routed to a single MQSeries transmission queue. The messages must be read from the queue in batches without applying exclusive locks to the server. Compensate for messages processed in an order that differs from the order in which they were inserted into the queue.

BizTalk Adapter for MQSeries Components

BizTalk Adapter for MQSeries includes design time and run time components. Design time is comprised of BizTalk Adapter for MQSeries Configuration Console, and BizTalk Server Configuration. BizTalk Server Configuration involves port binding and channel definitions. Run time contains the receive function component, MQSeries Helper run time library, and BizTalk Server application integration component.

Design Time

The design time portion of the BizTalk Adapter for MQSeries utilizes

  • BizTalk Server Messaging Manager
  • MQSeries MMC Snap-in
  • MQSeries Explorer

These three user interfaces allow the developer or administrator to link the required BizTalk Server components to the MQSeries environment. The next figure shows the MMC Snap-in developed for the BizTalk Adapter for MQSeries. The Snap-in provides the design palette for creating objects that are necessary to bind MQSeries and BizTalk Server Messaging together. A Job is created that acts as the container for the metadata describing a single relationship.

The Job object general properties are:

  • MQSeries Host Name
  • Queue Manager Name
  • Transmission Queue Name

The advanced properties are:

  • Maximum messages per transaction
  • Message wait interval
  • Maximum accumulated size
  • Polling interval

The linkage between an MQSeries queue and a BizTalk Server envelope, channel name, or document definition is defined in a mapping object that is associated with its parent Job object. The Mapping Properties dialog box supports all of the document submission parameters that are part of a BizTalk Server IInterchange.Submit call.

Ee265631.bts_accmqseries_31(en-US,BTS.10).gif

Figure 31: BizTalk Adapter for MQSeries MMC Snap-in

BizTalk Server Messaging Manager provides the graphical user interface required for the definition of a channel and port combination to implement a zero code integration solution between an MQSeries environment and the BizTalk Server.

Ee265631.bts_accmqseries_32(en-US,BTS.10).gif

Figure 32: BizTalk Messaging Manager

The BizTalk Server Messaging Manager is the default binding and configuration interface for the integration server. Adapter development companies are encouraged to leverage this interface as the mechanism for binding their adapter to a BizTalk Server messaging scenario. The MQSeries channel can be linked to an MQSeries queue via the BizTalk Adapter for MQSeries by defining a mapping. The configuration required in the BizTalk Adapter for MQSeries and Messaging Manager represent the values required providing the metadata needed to constitute the connectivity solution implementation.

BizTalk Adapter for MQSeries Configuration Console

The MMC Snap-in portion of the BizTalk Adapter for MQSeries has been implemented according to the Windows platform Microsoft Management Console (MMC Snap-in) standard. This graphical design pattern allows definition of graphical configuration displays at a higher level. The connectivity solution MMC Snap-in provides the ability to create a Job. This specifies the MQSeries Host Name (name of computer on which MQSeries is running), Queue Manager Name (Windows 2000 server computer on which MQSeries software has been installed and configured), and a Transmission Queue Name. These represent a transmission queue used to communicate with the MQSeries run time via the application integration component (AIC) and the MQHelper dynamic link library. The configuration console is shown in the following figure.

Ee265631.bts_accmqseries_33(en-US,BTS.10).gif

Figure 33: BizTalk Adapter for MQSeries MMC Snap-in

The figure shown above shows the MMC Snap-in used to create a unit of computation, or Job. The properties of the Job include the MQSeries Host Name, Queue Manger Name, and Transmission Queue. The properties are entered in the corresponding fields of the General tab of the Job Properties dialog box as shown in the next figure.

Ee265631.bts_accmqseries_34(en-US,BTS.10).gif

Figure 34: Job Property General

Ee265631.bts_accmqseries_35(en-US,BTS.10).gif

Figure 35: Job Property Advanced Tabs

The Advanced tab of the Job Properties dialog box includes the Max Messages per Transaction, Message Wait Interval, Max Accumulated Size, and Poll Interval.

BizTalk Server Configuration

Port Binding

The configuration of the BizTalk Server instance involves the creation of a port and channel combination. The port acts as the binding interface between BizTalk Server and the MQSeries run time. The developer or administrator selects Application Integration Component as the communication protocol in the BizTalk Server Messaging Manager as shown in the following figure.

Ee265631.bts_accmqseries_36(en-US,BTS.10).gif

Figure 36: AIC Selection as Protocol

  • Click Browse to display the Select a Component dialog box as shown in the next figure.

Ee265631.bts_accmqseries_37(en-US,BTS.10).gif

Figure 37: AICMQ MQPipeline Selection

Selecting AICMQ MQPipeline as shown above allows the developer or administrator to literally plug the BizTalk Adapter for MQSeries into the BizTalk Server Messaging Engine.

  • Click OK. The following dialog is displayed.

Ee265631.bts_accmqseries_38(en-US,BTS.10).gif

Figure 38: BizTalk Server and AICMQ Binding

The connectivity solution application integration component binds the BizTalk Adapter for MQSeries to BizTalk Server. The AIC is called AICMQ for short. AICMQ implements the algorithms necessary to handle outbound messages moving from BizTalk Server to a server that hosts the MQSeries Queue Manager software. The integration of the BizTalk Server capabilities can be linked to the MQSeries run time without the developer or administrator writing a single line of custom code. After the AICMQ has been bound to the appropriate messaging port, the BizTalk Server channel is used for processing data by providing transformation and other services.

Channel Definition

Creating and configuring a BizTalk Server port is a prerequisite to this task. After the port is configured for use in a scenario, the Queue Manager Server must provide information to BizTalk Server regarding processing steps on the inbound messages to a specific instance.

Note   A channel is created in the standard manner shown in the BizTalk Server online documentation.

The channel allows the definition of metadata by processing rules for converting the message from an MQSeries format to the format of the target application system. Inbound processing converts the message from Unicode to ANSI format. The configuration definition is illustrated in the next figure.

Ee265631.bts_accmqseries_39(en-US,BTS.10).gif

Figure 39: Channel Properties - Advanced Configuration

This dialog box provides access to the Advanced button. The developer or administrator can click the button and configure the properties as shown.

Ee265631.bts_accmqseries_40(en-US,BTS.10).gif

Figure 40: AICMQ MQPipeline Component Properties

Two Active Server Pages (ASPs) support this interface. The ASP pages define the parameter specification and storage interfaces. These are used to allow developers or administrators a facility for entering metadata at design time, which the adapter can use at run time. The pages are described as Edit and Post pages in the Microsoft BizTalk Server Adapter Development Guide. Each page is installed in the [install drive:]\ Program Files\MessagingManager\pipeline directory. The names of the ASP pages are AICMQ_MQPipeline_1.asp and AICMQ_MQPipeline_1_post.asp. The task of configuring the design time portion of the adapter configuration is complete once the developer or administrator clicks OK and the values are saved to the property bag or dictionary.

Run time

The run time components of this connectivity solution are a combination of BizTalk Server specific components and one component that requires the use of MQSeries SDK. The components provide the run time services required, allowing the BizTalk Server computer and a server running the MQSeries Queue Manager to communicate. These components provide the support necessary to allow inbound and outbound processing of MQSeries messages. The connectivity solution run time components are:

  • Receive Function
  • MQSeries Helper Run Time Library
  • BizTalk Server Application Integration Component

These three components combine to provide the non-visual adapter core. Each of these components will be discussed in this section.

Receive Service

This part of the connectivity solution is a Windows 2000 service, which implements the monitor design pattern. The pattern involves the use of a process initiated during the early stages of the operating system startup. In addition to Windows 2000 service functions, the service also implements an internal object called the Dispatcher. The Dispatcher configures thread level properties and associates each worker thread with a thread procedure or worker function. While the service is running, the worker function creates an MTBWorker object and sets the parameters and mappings for it. Each MTBWorker executes under the context of a new (DTC) transaction.

MTBWorker

Each MTBWorker reads batches of messages from the designated queue and transports them to BizTalk Server under a transactional context. This provides a guarantee that messages are either delivered to the BizTalk Server Work Queue (SQL Server internal table) or they are left in the source queue until they can successfully be delivered to a BizTalk Server instance. MQSeries messages are only deleted from the transmit queue upon completion of a DTC transaction. Both BizTalk Server and the MQSeries run time services must confirm the transaction as being completed successfully. The MQSeries run time services are implemented in a dynamic link library called MQHelper.dll (MQHelper).

MQHelper

This component provides the implementation of the MQSeries application program interface (API) methods necessary to provide send and receive services. This dynamic link library is necessary to provide DTC transaction contexts for each message traveling in an inbound or outbound direction.

In an outbound transactional scenario,

  1. BizTalk Server starts a transaction.
  2. The application integration component enlists in the transaction.
  3. The MQHelper component enlists in the transaction.
  4. The MQHelper performs the task of writing a message into an MQSeries message queue located on the remote Windows 2000 computer.
  5. The Windows 2000 service is deployed to host the MQSeries Server software.
  6. The connectivity solution uses Distributed COM (DCOM) to move the payload to the remote server.
  7. Any necessary conversion can then occur.
  8. The data is written the MQSeries queue on the server in an outbound direction or picked up and packaged as a message.
  9. This is sent to a BizTalk Server instance via DCOM in an inbound direction toward BizTalk Server.

The trip to the BizTalk Server instance requires installation and configuration of a receive service instance as discussed next.

Interaction with Receive Service

The receive service initiates an inbound transactional read operation, which causes this component to enlist in the transaction as part of the request for extracting message from a local or remote MQSeries queue. The component executes under the auspices of a surrogate process created by DLLHost.exe as a DCOM Server. This component must be installed on the server that hosts the MQSeries Queue Manager.

Application Integration Component

The BizTalk Adapter for MQSeries AIC (AICMQ) delivers messages from BizTalk Server to an MQSeries Queue Manager. In addition to message delivery, this component prevents message duplication, converts the messages from Unicode to ANSI, and performs diagnostic tracing.

BizTalk Server Application Integration Component Implementation Details

AICMQ implements the BizTalk Server IPipelineComponent COM interface, which allows the entry of metadata at design time. Meta data is represented as properties that are eventually stored as name and value pairs in a binary format in the property bag. The AICMQ component is installed as part of the connectivity solution installation. The component is registered with BizTalk Server by being installed as a Non-Configured COM+ Component followed by the appropriate category identifiers. The category identifiers register the component as an application integration component that should be displayed as a choice in the BizTalk Server Messaging Manager Select A Component dialog box when a developer or administrator chooses Application Integration Component as the messaging protocol. The following figure displays the selection of AICMQ MQPipeline as the component that implements the messaging protocol.

Ee265631.bts_accmqseries_41(en-US,BTS.10).gif

Figure 41: AIC Selection - AICMQ Pipeline Component

The figure above shows the selection of the AICMQ MQPipeline component as the transport mechanism for the associated BizTalk Server Messaging port. The BizTalk Server design time interfaces are aware of each component that has registered the appropriate category identifiers. This allows the BizTalk Server Messaging Manager to list the adapter as a choice in the list of available components.

Transaction Context

The AICMQ is always invoked under the context of a transaction that is driven by the BizTalk Server Messaging Engine using the DTC. Upon failure in AICMQ, the document will eventually be placed in the BizTalk Server suspended queue after the designated number of BizTalk Server Messaging Engine retries fail. The data passed to AICMQ is in Unicode (BSTR) format, so the component converts the message content to ANSI before transporting it to the MQSeries Queue Manager via communication with MQHelper. The conversion takes place in the MQHelper component.

Application Integration Component Execution Process

As an application integration component, AICMQ will run in the same process space as the BizTalk Server service and thus does not need to create and configure a COM+ package. At run time the BizTalk Server Messaging Engine invokes the AICMQ and passes in the property bag. AICMQ reads the necessary parameters and sets the parameters of the component to the supplied values prior to beginning its execution of the algorithms necessary to transport a BizTalk Server message to a remote server and queue.

MQSeries Queue Manager Software

The Queue Manager resides on a second Windows 2000 Server. Launching the MQSeries Explorer as shown in the next figure can configure the queue manager.

Ee265631.bts_accmqseries_42(en-US,BTS.10).gif

Figure 42: MQSeries Explorer

The Queue Manager Server provides the MQSeries Explorer as a MMC Snap-in. This supports

  • Definition of the Queue Manager
  • MQSeries channels
  • Client connections
  • Process definitions
  • Name lists
  • Cluster Queue Manager(s)
  • Transactional and non-transactional queues

Each of the components plays a key role in the acquisition and processing of messages. All of the components combined together form the foundation for building very simple to extremely complex messaging solutions. The BizTalk Adapter for MQSeries components combine to form a Plug-and-Play solution that integrates BizTalk Server into an MQSeries messaging environment.

Appendix

Single Machine Installation and Local Transmission Queues

A single machine configuration combines the BizTalk Server software, BizTalk Adapter for MQSeries, and the IBM MQSeries Series Software that is used to create a Queue Manager all loaded on the same machine. Let's assume that a server exists with the name "LAQueueServer". The configurations on this machine are very similar to the default multiple machine deployment scenario, but the MQSeries Host Name and Queue Manager Name are the same. The properties are set properties as follows:

  • MQSeries Host Name: LAMQueueServer
  • Queue Manager Name: LAQueueServer
  • Transmission Queue Name: XMIT

The Queue Definition is export as mentioned previously in this document. Once you have exported the queue definition, the remote Queue definition will show up in the MQSeries Explorer. The remote definition shows up with the same name as the Job name defined in MQSeries Adapter MMC SnapIn. The parameter for the LAMQueueServer machine would be as follows:

  • Queue Name: JOB
  • Type Remote: Definition
  • Description: "Some text here"
  • Put Message: Allowed
  • Default Priority: 0
  • Default Persistence: Not Persistent
  • Scope: Queue Manager
  • Remote Queue Definition: TestQueue
  • Remote Queue Manager Name: JOB
  • Transmission Queue Name: XMIT

The transmission queue has the following values as its properties:

  • Queue Name: XMIT
  • Type: Local
  • Description: "More Text"
  • Put Message: Allowed
  • Default Priority: 0
  • Default Persistence: Not Persistent
  • Scope: Queue Manager
  • Usage: Transmission

This configuration does not use DCOM but instead uses local RPC calls to move the data from BizTalk Server to a transport queue via AICMQ. The same observation applies for the message moving in an inbound to BizTalk Server direction. These messages are written to a transport queue located on the server and a Receive Services pulls the message of the queue and submits them to BizTalk Server.

MQSeries Trace Utility

This section provides information about the following MQSeries Trace Utility topics:

  • Background and Overview
  • Installation
  • Registry and Files
  • Running the Trace Utility
  • Trace Utility Details

Also included in the Appendix section are topics covering:

  • Troubleshooting
  • Other Considerations
  • Encoding Summary
  • MQSeries Overview
  • Things to Keep in Mind
  • References

Background and Overview

Beginning with Microsoft Windows 2000, the kernel provides tracing services for use by applications and device drivers. These services allow developers to leverage a highly scalable and extensible tracing architecture for capturing events either to a file or to a real-time trace listener. Complete documentation for Event Tracing is found in MSDN under Platform SDK Documentation\Base Services\Debugging and Error Handling\Event Tracing.

Software Tracing - Software Tracing is a library of code and tools that abstracts the developer experience for Event Tracing. Software Tracing uses a pre-processor to process and alter source code so that it will produce tracing information using Event Tracing. Software Tracing tools are available in the SDK and DDK from Microsoft. Software Tracing ships with several run time tools in addition to the compile time requirements of preprocessing source code.

Adapter Trace Utility (ATU) Interaction with Operating System (OS) Tracing - The ATU makes direct Event Trace application programming interface (API) calls to capture trace data into a logfile. Each logfile corresponds to an event trace session, which has parameters that include file destination, file size, and file-write behavior. The ATU makes direct use of the Event Tracing API to create and control a single Event Trace session.

Adapters – It is important that all adapters use the same trace utility. This was designed to simplify tracing for all adapters. All BizTalk 1.0 Adapters use this trace utility, and it will ship with all BizTalk 1.0 Adapters. If multiple adapters are installed on the same computer, for example, BizTalk Adapter for SAP and BizTalk Adapter for MQSeries, then the trace utility (implemented as an MMC Snap-in), will display both adapters. Enabling tracing for one component per adapter, multiple components per adapter or multiple adapters at the same time is possible. In this scenario, trace output for all enabled components/adapters will be directed to a single file.

Installation

If the BizTalk Adapter for MQSeries is installed using Autorun from the CD, the Microsoft MMC Adapter Trace Utility is automatically installed during setup. The default directory for installation of all trace files is %CommonProgramFiles%\Adapter Trace Utilities.

It can also be installed separately, by directly running the MSI package (BizTalkAdapterTraceUtility.msi)

To uninstall

  1. Double-click Add/Remove Programs.
  2. Select the program, and click Uninstall.

This will uninstall all created short cuts, directories and files.

To reinstall

  • Run the MSI package again. It will automatically switch to maintenance mode and Reinstall will update all the trace files.

Registry and Files

Adapter Trace Utility (ATU) – As part of the ATU package (BizTalkAdapterTraceUtility.msi), all registry keys used by the ATU are in a single location, which can be found at HKEY_LOCAL_MACHINE\Software\Microsoft\Adapter Trace Utility

This root key has values and sub-keys beneath it. Valid root key values are:

  • File (REG_SZ) is the path to the output trace file.
  • Size (REG_DWORD) is the size of the output trace file.
  • Flags (REG_DWORD) is the creation flags of the output trace file (circular, sequential).
  • Format Tool (REG_SZ) is the fully qualified path to tracefmt.exe.

BizTalk Adapter for MQSeries for tracing – As a part of the BizTalk Adapter for MQSeries package (BizTalkAdapterforMQS.msi), certain registry keys are created. Every sub-key of the root key identifies an adapter key. This key corresponds to the friendly name of an adapter, i.e., Microsoft BizTalk Adapter for MQSeries. Valid Adapter key values are:

  • TMF Path (REG_SZ) is the path to the adapter installed *.TMF and *.TMC files to be used by the tracefmt.exe utility to convert from binary trace files to human readable trace files. These files are installed with the BizTalk Adapter for MQSeries. By default, all *.tmf and *.tmc files are located at C:\Program Files\Microsoft BizTalk Adapter for MQSeries\Trace\Trace_Format\
  • An Adapter key has two sub-keys. The first sub-key is a Components key. The second Adapter sub-key is a Flags key.
  • *.CTL files are installed with the adapter at C:\Program Files\Microsoft BizTalk Adapter for MQSeries\Trace. These files contain the GUID for each component. When using the ATU, these files are not required since the GUID for each component is stored in the registry. This is required only for use with the command line utility. Tracelog.exe is not documented nor is it recommended for use.

Command Line tool (tracelog.exe) The command line utility is shipped as part of the BizTalkAdapterTraceUtility.msi package. Tracelog.exe is not recommended for usage; the GUI Utility is the preferred utility.

Run the Trace Utility

Click here to see larger image

Figure 43: Trace Utility
  1. On the Start menu, click Programs, click Microsoft BizTalk Adapter Trace Utility, and then click Trace Manager. The Trace Utility Manager will open.
  2. In the left pane, right-click Default Session, and then click Properties. In the Trace Settings dialog box, either fill in the following three properties or leave the default settings.
    • File Name: The default is %CommonProgramFiles%\Adapter Trace Utilities\traces\output.log.
    • File Size: Default is 20 MB.
    • Log Method: Leave the default of Create Circular. With a Circular log method, when the output log file reaches its maximum size, it will maintain that size by overwriting the same log from the beginning. This creates a sliding window of information, which can be useful.
      Note   Choosing Create Sequential, causes the output file, once it reaches its maximum size specified, to stop recording trace information.

You can trace any or all of the BizTalk Adapter for MQSeries four components: AICMQ, MQHelper, MTBSvc, or MTBWorker.

  1. To enable all components for tracing, in the left pane, right-click Microsoft BizTalk Adapter for MQSeries, and then click Enable All Components. To disable all components for tracing, in the left pane, right-click Microsoft BizTalk Adapter for MQSeries, and then click Disable All Components. 
  2. To enable or disable components individually, right-click the component, and then select Enable This Component or Disable This Component.
  3. Select an enabled component in the left pane. In the right pane, right-click the appropriate Flag Level for that component (Debug, Error, Information, or Warning), and then click Enable. This determines the level of tracing to perform.
  4. To enable or disable all components at once, right-click the component, and then click Enable All Flags or Disable All Flags.
  5. Repeat Step 3 for each component to be traced.
  6. Once each component is configured, right-click Default Session in the left pane, and then click Start to run the Trace Utility on the enabled components.
  7. To stop tracing, in the left pane, right-click Default Session, and then click Stop.
  8. At this point the output file might be sent to a Microsoft Product Support Specialist via e-mail. However, it is possible to view the file. In the left pane, right-click Default Session, and then click Format. This puts the output file into a readable format. Right-click Default Session again, and then click View. The file will open in the default viewer.
  9. To delete the output file, in the left pane, right-click Default Session, and then click Delete.

Tracing Utility Details

By default, trace output goes to a file called output.txt located at %CommonProgramFiles%\Adapter Trace Utilities\traces\output.log.

Output contains many fields, each delimited by comma (,). For example, a sample output trace statement might look like this:

0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::FinalConstruct,mqpipeline_cpp55,CMQPipeline::FinalConstruct - enter

The fields in the trace output are in the following order:

CPU, PROCESS ID, THREAD ID, TIMESTAMP (DATE/TIME), COMPONENT NAME, FLAG/LEVEL, FUNCTION NAME, NAME OF FILE/LINE NUMBER, OUTPUT STRING

Sample 1 – Send message from BizTalk to MQSeries – In this case, tracing is enabled only for AICMQ and MQHelper components. Also, all flags are enabled on for these 2 components.

Using the AIC for MQSeries (AICMQ), a message is sent from BizTalk Server to MQSeries Server (ANIL3), Queue Manager (MQS_QM), Queue (LocalTest1).

Output:

EventTrace
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::FinalConstruct,mqpipeline_cpp55,CMQPipeline::FinalConstruct - enter
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::FinalConstruct,mqpipeline_cpp72,CMQPipeline::FinalConstruct - exit
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::SetConfigData,mqpipeline_cpp551,SetConfigData is being called
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::SetConfigData,mqpipeline_cpp650,SetConfigData MQServer = <ANIL3>, Queue_Manager_Name = <MQS_QM>, Queue_Name = <LocalTest1>
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::Execute,mqpipeline_cpp140,Execute enter
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::Execute,mqpipeline_cpp220,Execute get working_data 0x0
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::Execute,mqpipeline_cpp248,Execute working_data length = 26
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceAICMQ_cpp32,The message length is 26
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceAICMQ_cpp56,The content is (not truncated):
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceAICMQ_cpp58,test message for brown bag
0,0000,076C,10/08/2001-15:43:58.907,aicmq,MYLOG_TRACE,CMQPipeline::Execute,mqpipeline_cpp259,Execute Create an MQHelper on ANIL3
0,0000,076C,10/08/2001-15:43:58.970,aicmq,MYLOG_TRACE,CMQPipeline::Execute,mqpipeline_cpp300,Execute Putting message to QMgr(MQS_QM), Q(LocalTest1)
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CRemoteMQ::WriteMessage,remotemq_cpp1204,WriteMessage: Enter
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CRemoteMQ::WriteMessage,remotemq_cpp1277,WriteMessage The original message
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceMQHelper_cpp32,The message length is 26
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceMQHelper_cpp56,The content is (not truncated):
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceMQHelper_cpp58,test message for brown bag
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CMQMessage::PrepareMQMessage,mqmessage_cpp59,CMQMessage::PrepareMQMessage Original IN message
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceMQHelper_cpp32,The message length is 26
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceMQHelper_cpp56,The content is (not truncated):
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageW,MsgTraceMQHelper_cpp58,test message for brown bag
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CMQMessage::PrepareMQMessage,mqmessage_cpp107,CMQMessage::PrepareMQMessage Number of bytes written is 26
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CMQMessage::PrepareMQMessage,mqmessage_cpp129,CMQMessage::PrepareMQMessage Buffer length = 27, Message data length = 26
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CMQMessage::PrepareMQMessage,mqmessage_cpp132,CMQMessage::PrepareMQMessage After necessary conversion
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageC,MsgTraceMQHelper_cpp74,The message length is 26
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageC,MsgTraceMQHelper_cpp97,The content is (not truncated):
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,KapolaTraceMessageC,MsgTraceMQHelper_cpp98,test message for brown bag
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CMQMessage::PrepareMQMessage,mqmessage_cpp176,CMQMessage::PrepareMQMessage Message length after conversion to CP_ACP: 26
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp499,InitMQ(MQS_QM, LocalTest1)
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp501,InitMQ m_fCanBePooled = 0
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp538,InitMQ CurrentQName = <RQD_QMTWO>, CurrentQMgrName = <QMONE>, CurrentOpenOptions = 16
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp553,InitMQ Diff_QMgr = <yes>, Diff_Q = <yes>, Diff_OO = <no>
0,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp587,InitMQ Queue is opened. Will close
1,0000,0A64,10/08/2001-15:43:58.970,mqhelper,MYLOG_TRACE,CRemoteMQ::Activate,remotemq_cpp1590,****** Activate *******
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp616,InitMQ Diff Q Mgr. Full Init required. fSameQ = FALSE
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp629,InitMQ Disconnect QMgr anyway
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp669,InitMQ Need to reset Q name.
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp697,InitMQ Set queue open options to 0x10
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp720,InitMQ fCanBePooled = 1. Return S_OK.
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,CRemoteMQ::WriteMessage,remotemq_cpp1362,WriteMessage Calling putMessage
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,KapolaTraceMessageC,MsgTraceMQHelper_cpp74,The message length is 26
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,KapolaTraceMessageC,MsgTraceMQHelper_cpp97,The content is (not truncated):
1,0000,0A64,10/08/2001-15:43:59.126,mqhelper,MYLOG_TRACE,KapolaTraceMessageC,MsgTraceMQHelper_cpp98,test message for brown bag
0,0000,076C,10/08/2001-15:44:02.548,aicmq,MYLOG_TRACE,CMQPipeline::Execute,mqpipeline_cpp439,Execute WriteMessage succeeded
0,0000,076C,10/08/2001-15:44:02.548,aicmq,MYLOG_TRACE,CMQPipeline::Execute,mqpipeline_cpp441,Execute returning S_OK
0,0000,076C,10/08/2001-15:44:02.548,aicmq,MYLOG_TRACE,CMQPipeline::FinalRelease,mqpipeline_cpp80,CMQPipeline::FinalRelease - enter
0,0000,076C,10/08/2001-15:44:02.548,aicmq,MYLOG_TRACE,CMQPipeline::FinalRelease,mqpipeline_cpp87,CMQPipeline::FinalRelease: This was the last object
1,0000,0A64,10/08/2001-15:44:02.548,mqhelper,MYLOG_TRACE,CRemoteMQ::WriteMessage,remotemq_cpp1386,WriteMessages(MQS_QM, LocalTest1): is successful
1,0000,0C00,10/08/2001-15:44:02.548,mqhelper,MYLOG_TRACE,CRemoteMQ::Deactivate,remotemq_cpp1622,***** Deactivate *****
1,0000,0C38,10/08/2001-15:44:03.391,mqhelper,MYLOG_TRACE,CRemoteMQ::CanBePooled,remotemq_cpp1612,***** CanBePooled ***** Object CanBePooled = 1

Sample 2 – Receive message in BizTalk from MQSeries - In this case, tracing is enabled for MTBSVC, MTBWorker and MQHelper components. Also, all flags are enabled on for these three components.
Message is sent from MQSeries Server to receive function on BizTalk Server.
Remote Definition Name (JOB), Remote Queue Manager (Job), Remote Queue Name (TestQueue01), Transmission Queue Name (XMITQ1), Machine Name (ANIL3). TestQueue01 is mapped to Channel1 on BizTalk Server.
Output:

EventTrace
0,0000,06F8,10/08/2001-15:58:51.896,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp285,ThreadProc: Creating a worker
0,0000,0710,10/08/2001-15:58:51.896,mtbworker_hash,MYLOG_TRACE,CWorker::FinalConstruct,worker_cpp32,CWorker::FinalConstruct - enter
0,0000,0710,10/08/2001-15:58:51.896,mtbworker_hash,MYLOG_TRACE,CWorker::FinalConstruct,worker_cpp52,CWorker::FinalConstruct - exit
1,0000,06F8,10/08/2001-15:58:51.911,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp338,ThreadProc, Set parameters
1,0000,0710,10/08/2001-15:58:51.911,mtbworker_hash,MYLOG_TRACE,CWorker::SetParameters,worker_cpp917,CWorker::SetParameters done
0,0000,0710,10/08/2001-15:58:51.927,mtbworker_hash,MYLOG_TRACE,CWorker::Work,worker_cpp144,CWorker::Work(ANIL3, MQS_QM, XMITQ1), m_fCanBePooled = 0
0,0000,0710,10/08/2001-15:58:51.927,mtbworker_hash,MYLOG_TRACE,CWorker::Work,worker_cpp245,CWorker::Work: Create an MQHelper on ANIL3
1,0000,06F8,10/08/2001-15:58:51.927,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp457,ThreadProc, Work(ANIL3, MQS_QM, XMITQ1)
0,0000,0710,10/08/2001-15:58:51.942,mtbworker_hash,MYLOG_TRACE,CWorker::Work,worker_cpp293,CWorker::Work: Read messages
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::Activate,remotemq_cpp1590,****** Activate *******
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::SetParameters,remotemq_cpp1580,CRemoteMQ::SetParametersGetMsgWaitInterval = 512 MaxNumMsgsPerTxn = 10 MaxAccumulatedSize = 30720
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp499,InitMQ(MQS_QM, XMITQ1)
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp501,InitMQ m_fCanBePooled = 0
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp538,InitMQ CurrentQName = <XMITQ1>, CurrentQMgrName = <MQS_QM>, CurrentOpenOptions = 34
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp553,InitMQ Diff_QMgr = <no>, Diff_Q = <no>, Diff_OO = <no>
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp569,InitMQ Same QMgr, Same Q, Same OO. CRemoteMQ object is to be reused directly.Set fCanBePooled flag to TRUE. Returning S_OK
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp852,ReadFromMQ()
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp886,ReadFromMQ fKeepReading = 1
1,0000,0654,10/08/2001-15:58:51.942,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp902,ReadFromMQ get next message from MQ
0,0000,0654,10/08/2001-15:58:52.458,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp991,ReadFromMQ: No more message in queue
0,0000,0654,10/08/2001-15:58:52.458,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp1012,ReadFromMQ: returning S_OK
0,0000,0654,10/08/2001-15:58:52.458,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadMessages,remotemq_cpp288,ReadMessages No message read. S_FALSE. Num messages left is set to 0
0,0000,0710,10/08/2001-15:58:52.458,mtbworker_hash,MYLOG_TRACE,CWorker::FinalRelease,worker_cpp61,CWorker::FinalRelease - enter
0,0000,0710,10/08/2001-15:58:52.458,mtbworker_hash,MYLOG_TRACE,CWorker::FinalRelease,worker_cpp71,CWorker::FinalRelease: This was the last object
0,0000,0710,10/08/2001-15:58:52.458,mqhelper,MYLOG_TRACE,CRemoteMQ::CanBePooled,remotemq_cpp1612,***** CanBePooled ***** Object CanBePooled = 1
0,0000,06F8,10/08/2001-15:58:52.458,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp504,ThreadProc Work(ANIL3, MQS_QM, XMITQ1) found 0 messages in the queue
1,0000,0710,10/08/2001-15:58:52.458,mtbworker_hash,MYLOG_TRACE,CWorker::Work,worker_cpp314,Work(ANIL3, MQS_QM, XMITQ1): MQ queue is empty
1,0000,0710,10/08/2001-15:58:52.458,mtbworker_hash,MYLOG_TRACE,CTransactionHelper::~CTransactionHelper,MTBWTxnHelper_cpp64,DTC SetAbort succeeded
1,0000,0654,10/08/2001-15:58:52.458,mqhelper,MYLOG_TRACE,CRemoteMQ::Deactivate,remotemq_cpp1622,***** Deactivate *****
0,0000,0D78,10/08/2001-15:58:53.458,mtbworker_hash,MYLOG_TRACE,CWorker::FinalConstruct,worker_cpp32,CWorker::FinalConstruct - enter
0,0000,0D78,10/08/2001-15:58:53.458,mtbworker_hash,MYLOG_TRACE,CWorker::FinalConstruct,worker_cpp52,CWorker::FinalConstruct - exit
0,0000,06F8,10/08/2001-15:58:53.458,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp457,ThreadProc, Work(ANIL3, MQS_QM, XMITQ1)
0,0000,0D78,10/08/2001-15:58:53.458,mtbworker_hash,MYLOG_TRACE,CWorker::Work,worker_cpp144,CWorker::Work(ANIL3, MQS_QM, XMITQ1), m_fCanBePooled = 0
1,0000,06F8,10/08/2001-15:58:53.458,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp285,ThreadProc: Creating a worker
1,0000,06F8,10/08/2001-15:58:53.458,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp338,ThreadProc, Set parameters
1,0000,0D78,10/08/2001-15:58:53.458,mtbworker_hash,MYLOG_TRACE,CWorker::SetParameters,worker_cpp917,CWorker::SetParameters done
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::Activate,remotemq_cpp1590,****** Activate *******
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::SetParameters,remotemq_cpp1580,CRemoteMQ::SetParametersGetMsgWaitInterval = 512 MaxNumMsgsPerTxn = 10 MaxAccumulatedSize = 30720
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp499,InitMQ(MQS_QM, XMITQ1)
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp501,InitMQ m_fCanBePooled = 0
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp538,InitMQ CurrentQName = <XMITQ1>, CurrentQMgrName = <MQS_QM>, CurrentOpenOptions = 34
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp553,InitMQ Diff_QMgr = <no>, Diff_Q = <no>, Diff_OO = <no>
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::InitMQ,remotemq_cpp569,InitMQ Same QMgr, Same Q, Same OO. CRemoteMQ object is to be reused directly.Set fCanBePooled flag to TRUE. Returning S_OK
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp852,ReadFromMQ()
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp886,ReadFromMQ fKeepReading = 1
0,0000,0654,10/08/2001-15:58:53.474,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp902,ReadFromMQ get next message from MQ
1,0000,0D78,10/08/2001-15:58:53.474,mtbworker_hash,MYLOG_TRACE,CWorker::Work,worker_cpp245,CWorker::Work: Create an MQHelper on ANIL3
1,0000,0D78,10/08/2001-15:58:53.474,mtbworker_hash,MYLOG_TRACE,CWorker::Work,worker_cpp293,CWorker::Work: Read messages
0,0000,0D78,10/08/2001-15:58:53.989,mtbworker_hash,MYLOG_TRACE,CWorker::Work,worker_cpp314,Work(ANIL3, MQS_QM, XMITQ1): MQ queue is empty
0,0000,0D78,10/08/2001-15:58:53.989,mtbworker_hash,MYLOG_TRACE,CTransactionHelper::~CTransactionHelper,MTBWTxnHelper_cpp64,DTC SetAbort succeeded
0,0000,0654,10/08/2001-15:58:53.989,mqhelper,MYLOG_TRACE,CRemoteMQ::Deactivate,remotemq_cpp1622,***** Deactivate *****
1,0000,0654,10/08/2001-15:58:53.989,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp991,ReadFromMQ: No more message in queue
1,0000,0654,10/08/2001-15:58:53.989,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadFromMQ,remotemq_cpp1012,ReadFromMQ: returning S_OK
1,0000,0654,10/08/2001-15:58:53.989,mqhelper,MYLOG_TRACE,CRemoteMQ::ReadMessages,remotemq_cpp288,ReadMessages No message read. S_FALSE. Num messages left is set to 0
1,0000,0D78,10/08/2001-15:58:53.989,mtbworker_hash,MYLOG_TRACE,CWorker::FinalRelease,worker_cpp61,CWorker::FinalRelease - enter
1,0000,0D78,10/08/2001-15:58:53.989,mtbworker_hash,MYLOG_TRACE,CWorker::FinalRelease,worker_cpp71,CWorker::FinalRelease: This was the last object
1,0000,0D78,10/08/2001-15:58:53.989,mqhelper,MYLOG_TRACE,CRemoteMQ::CanBePooled,remotemq_cpp1612,***** CanBePooled ***** Object CanBePooled = 1
1,0000,06F8,10/08/2001-15:58:53.989,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp504,ThreadProc Work(ANIL3, MQS_QM, XMITQ1) found 0 messages in the queue
0,0000,06F8,10/08/2001-15:58:54.989,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp285,ThreadProc: Creating a worker
0,0000,06F8,10/08/2001-15:58:54.989,mtbsvc,MYLOG_TRACE,CThread::ThreadProc,Thread_cpp338,ThreadProc, Set parameters
0,0000,0E64,10/08/2001-15:58:54.989,mtbworker_hash,MYLOG_TRACE,CWorker::SetParameters,worker_cpp917,CWorker::SetParameters done
1,0000,0E64,10/08/2001-15:58:54.989,mtbworker_hash,MYLOG_TRACE,CWorker::FinalConstruct,worker_cpp32,CWorker::FinalConstruct - enter
1,0000,0E64,10/08/2001-15:58:54.989,mtbworker_hash,MYLOG_TRACE,CWorker::FinalConstruct,worker_cpp52,CWorker::FinalConstruct - exit

Troubleshooting MQSeries - FAQs

Q. Which version of MQSeries should I use?

As of this writing, MQSeries 5.2.1 is the latest version, and is recommended. It has more helpful information in the error messages and event log entries. It also has a Prepare MQSeries Wizard, which is helpful.

Q. What are the signs that MQSeries isn't configured correctly?

Most issues with MQSeries are caused by permission problems. The following summarizes the problems or errors you may see in either MQSeries Explorer or the event log that indicate a permission problem:

  • In the left pane, after expanding the Queue Managers node, you right-click a queue manager and do not see menu items for New and Delete.
  • A queue manager has queue associated with it, but the queue manager node will not expand to show you those queues.
  • After right-clicking a queue manager and selecting Connect you get this error message: "Access not authorized. You are not authorized to perform this action. (AMQ4036)"

Event log

Event Type:Warning

Event Source:MQSeries

Event Category:None

Event ID:8079

Description

Access was denied when attempting to retrieve group membership information for user 'billjoy@northamerica'.

MQSeries, running with the authority of user 'musr_mqadmin@billjoy1', was unable to retrieve group membership information for the specified user.

Ensure Active Directory access permissions allow user 'musr_mqadmin@billjoy1' to read group memberships for user 'billjoy@northamerica'. To retrieve group membership information for a domain user, MQSeries must run with the authority of a domain user.

Event Type:Warning

Event Source:MQSeries

Event Category:None

Event ID:8561

Description

Domain controller unavailable.

MQSeries was unable to contact the domain controller to obtain information for user 'billjoy@northamerica'.

Ensure that a domain controller for the domain on which user 'billjoy@northamerica' is defined is available. Alternatively, if you are using a computer that is not currently connected to the network and have logged on using a domain user ID, you may wish to log on using a local user ID instead.

Event Type:Warning

Event Source:MQSeries

Event Category:None

Event ID:8062

Description

Unexpected return code, '10', from command 'RUNMQCHI -qSYSTEM.CHANNEL.INITQ -mQueueMan'.

An unexpected return code, '10', was returned by command 'RUNMQCHI -qSYSTEM.CHANNEL.INITQ -mQueueMan'. This command was issued by the MQSeries service for queue manager 'QueueMan'.

Verify that the command and parameters are correct.

Event Type:Error

Event Source:MQSeries

Event Category:None

Event ID:9509

Description

Program cannot open queue manager object.

The attempt to open either the queue or queue manager object 'SYSTEM.CHANNEL.INITQ' on queue manager 'QueueMan' failed with reason code 2042.

Ensure that the queue is available and retry the operation.

Q. I have one or more of these symptoms. How do I fix it?

How to fix the permissions issue depends on how you need to be logged in to the MQSeries computer. For a more detailed discussion than what is provided in this document, see http://www-4.ibm.com/software/ts/mqseries/support/faqs/w2k.html. In a nutshell, the two scenarios are:

Logging in using a domain account.

Issue #1: When you are logged in using a domain account, MQSeries will always attempt to contact the domain controller (DC). If you are not connected to the network, you will see one or more of the errors described above.

Solution: If you need to use a domain account, you must stay connected to the network where the DC is.

Issue #2: If MQSeries can contact the DC it will attempt to look up group membership information for the domain account you used to log in. By default, it will look this information up using the local MUSR_MQADMIN account, which was created during setup (along with a local group named MQM). This local account will typically not have the permissions it needs and you will get event 8079 (see above) in your event log.

Solution: Using the Prepare MQSeries Wizard, select the option that says there is a Windows domain controller on the network, and then specify domain credentials (most likely the same account you used to log in) that have permission to look up group membership for your login account. NOTE: if you are using MQSeries 5.2 you need to run dcomcnfg.exe, select "IBM MQSeries Services" on the Application tab, click Properties, select the Identity tab, select This user, and type the credentials there.

Issue #3: Logging in using a local computer account.

Solution: When logging in using a local account, MQSeries does not try to contact any DC, so all you need to do is make sure you are logging in with an administrative account.

Other Considerations

  • When sending large messages (greater than 128 KB) to MQSeries, you will experience a long delay. See KB Article 301117
  • Only one instance of the BizTalk Adapter for MQSeries MMC Snap-in may be open at a given instance. Auto-refresh is not supported. Hence, multiple Snap-ins can easily get out of sync visually.
  • Memory consumed by Microsoft Distributed Transaction Coordinator (msdtc.exe) continues to increase while running long periods of stress. You will notice the increase on the BizTalk Server that is running the receive function. This is normally noticed after receiving continuous messages for more than 24 hours. For more information see KB article 307383
    Note   Restarting the Distributed Transaction Coordinator Service (MSDTC) will reset the memory usage of msdtc.exe. Stopping MSDTC will also stop Message Queuing (MSMQ), BizTalk Messaging Service and the BizTalk Adapter for MQSeries Service (receive function). Restarting BizTalk Adapter for MQSeries service will also restart MSDTC and BizTalk Messaging Service. You will have to manually start the MSMQ service.
  • If you are installing MQSeries for the first time, you will need to reboot your system before installing the BizTalk Adapter for MQSeries.
  • If you want to the adapter to continue working with no user logged on to the system, you need to do the following: In Component Services, if you configure the BizTalk Adapter for MQSeries COM+ Component to run under a specific user (instead of the default interactive user), you must also configure the BizTalk Server Interchange Application COM+ Component to run under a specific user. Likewise, on the MQSeries system, if this is done for the MQHelper Component, then you will need to configure the MQSeries objects to be accessed by that user. This is done by using the Setmqaut command.
  • The receive Component does not support dynamic configuration. Each time a change occurs in the BizTalk Adapter for MQSeries configuration, the receive service needs to be restarted.
  • You need to be a local administrator on the BizTalk Server and MQSeries Server for installation, starting the service, making changes in the Configuration Manager of the adapter and so on.
  • This Adapter does not support UTF-8 format.
  • In MQSeries, Queue Manager must have the same CCSID property as the current system ANSI code page. When a Queue Manager is created, this property is set accordingly by default. However, in some cases you may find that it has changed, and needs to be adjusted manually.
  • When attempting to run the Adapter Trace Utility on an application that has not been started, trace information for that application will not be available. To remedy this, stop the Default Session, start the application, and then start the Default Session. For more information, see KB article Q307331.
  • Running multiple instances of the Adapter Trace Utility (ATU) is not supported. ATU writes to the registry only when it is closed. If you make changes to one instance and load another instance, you will notice that they are out of sync.

MQSeries to BizTalk Server Encoding Summary

Ee265631.bts_accmqseries_44(en-US,BTS.10).gif

Figure 44: Messaging Encoding

Notes

  1. The application on the AS/400 creates a document and places it on a remote queue definition defined in MQSeries. This remote queue definition points to the alias of the MQSeries queue manager installed on Windows 2000. The encoding of the document at this point is coded character set identifier (CCSID) 500. This is IBM-500 single byte EBCDIC encoding.
  2. Because applications on the Windows 2000 Server do not understand the CCSID 500 encoding, the document must be converted to another encoding scheme. This is accomplished by setting the CONVERT attribute on the sender channel to 'yes'.
  3. Because the CONVERT attribute is set to 'yes', the MQSeries on the AS\400 will convert the document to CCSID 437 before the document is transmitted. CCSID 437 is a single byte ASCII encoding that represents the IBM-437 codeset. A hot fix was developed by the product team to address this issue. Specifically, the hot fix eliminates the need to set the CONVERT attribute on the sending channel. It does this by letting the MQSeries function MQGET perform the conversion on the receiving computer. See the MQSeries Information Center for more information.
  4. When the message arrives to the queue manager on the Windows 2000 Server, it will be placed in the transmission queue specified by the queue manager alias definition. The encoding of the document at this point is CCSID 437.
  5. The BizTalk Adapter for MQSeries will monitor the transmission queue. When a document is placed into the queue with a remote queue name that matches a mapping defined in the BizTalk Adapter for MQSeries, the BizTalk Adapter for MQSeries will remove the document from the queue.
  6. The adapter assumes that all incoming documents are ASCII encoded. Before the BizTalk Adapter for MQSeries submits the document to BizTalk Server, the BizTalk Adapter for MQSeries will convert the document to UCS-2 encoding.
  7. The BizTalk Adapter for MQSeries submits the UCS-2 encoded document to BizTalk Server.

Troubleshooting

If the document is in XML format with an encoding tag, you may receive a BizTalk parser error. This is because the encoding tag may conflict with the document's physical encoding. An example of this would be an XML document with a UTF-8 encoding tag. Because the BizTalk Adapter for MQSeries always converts the document to UCS-2, the document's actual encoding will differ from the encoding specified by the document itself. The workaround for this error is straightforward – remove the encoding tag. This can be done either by the sender of the document or by the use a BizTalk Server preprocessor.

MQSeries Overview

MQSeries Role

  • Provides assured delivery of messages
  • IBM's equivalent to Microsoft's MSMQ
  • Supports a wide range of platforms

    OS/390 (IBM mainframe)

    Microsoft Windows NT

    OS/400 (IBM AS/400)

    Sun Solaris

    Tandem NonStop Kernel

    and others

  • Versions

    Windows NT

    • 2.0
    • 5.0, added MMC snap-in
    • 5.1
    • 5.2 (current) MS DTC support

    OS/390

    • 1.2
    • 2.1
    • 5.2 (current, 2.1 with hot fixes)

MQSeries Basic Components

Queue Managers

  • Supports multiple QM per computer (except OS/400)
  • QMs can be stopped & started independently
  • QMs have their own listeners
  • QM names independent of computer names
  • QMs all run under MQSeries service

Local Queues

  • Queues physically reside on local computer
  • Two types of Local queues

    Normal queues are used for application data

    Transmission queues used as transfer points for messages bound for other queue managers

  • Both are used by the BizTalk Adapter for MQSeries

Remote Queue Definitions

  • Reference to a queue that resides on a different queue manager
  • Definition contains the remote Queue manager's name and the Xmit queue to use
  • Definition can also contain a specific remote queue name.
  • More or less a routing table entry
  • Used by the BizTalk Adapter for MQSeries

Alias Queues

  • Reference to a queue defined on the local computer
  • Allows a friendly name

Channels

  • Define communication endpoints between Queue managers
  • Definition includes transmission protocol and parameters specific to that protocol

    TCP/IP – sockets port

    LU62 – CPIC side information

    SPX – sockets port

    NetBIOS – pipe name

  • Channels are paired

    Sender – Receiver

    Server – Requester

    Server Conn – Client Conn

  • The first two pairs are for Queue manager to Queue manager communication
  • The third is for Queue manager to client communication
  • Server Conn – Client Conn

    Server conn channels accessible through the MQSeries client APIs

    On OS/390 requires extra software called the client connectivity feature

    Client conn can be defined by two methods

    • Environment var MQSERVER=CHANNEL1/TCP/server-address(port) Only allows one QM to be defined
    • Channel table, which can be generated on any NT queue manager Allows multiple QMs to be defined

Listeners

  • Executable that is actually providing the endpoint defined by the channels
  • Setup by default on 5.2

Configuration

  • Command line -Runmqsc qmname

    Can be run interactively

    Can be feed a command file

    Available on all versions

    Commands fairly consistent across all platforms

    Commands documented in MQSC Command Reference

  • MMC snap-in

    Available only on NT version 5.1 and higher

    Does not work over Terminal Server

Tracing and Logs

  • Tracing
    • Can be started from the MQServices snap-in
    • Creates trace log for every process (filename contains the PID)
    • Can be viewed from the snap-in or with notepad
    • Located in C:\Program Files\MQSeries\errors
  • General logs

    C:\Program Files\MQSeries\errors

  • Logs of Queue Manager

    C:\Program Files\MQSeries\qmgrs\MQS1\errors

Verify Installation

  • Located in C:\Program Files\MQSeries\bin

    amqtsivt.exe – verifies DTC support

    amqsput.exe – command line tool to put messages in a queue

    amqsget.exe – command line tool to get messages from a queue

References

Things to Keep in Mind

  • MQSeries is case sensitive.
  • You need to reboot after installing MQSeries for the BizTalk Adapter for MQSeries for COM component to get registered.
  • BizTalk Adapter for MQSeries works with the following versions of MQSeries Server running on Windows 2000:
    • IBM MQSeries Server version 5.1 with Support Pac 75 and CSD U200134 or later, or
    • IBM MQSeries Server version 5.2

Additional Information

http://www.microsoft.com/biztalk/evaluation/adapters/mqseries.asp

http://www.microsoft.com/biztalk

http://www.microsoft.com/biztalk/mqseries

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft