Introduction. Welcome!...2 Typographical Conventions...2 Related Documentation...4 Viewing this Document...4 Printing this Document...

Transcription

1 CHAPTER Introduction Welcome!...2 Typographical Conventions...2 Related Documentation...4 Viewing this Document...4 Printing this Document...5 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0 1

2 CHAPTER 1 Introduction Welcome! This guide describes how to install, configure, and use the webmethods B2B MQSeries Adapter (MQSeries Adapter). It contains information for administrators who configure and manage a webmethods B2B system and for application developers who want to create B2B services that exchange data with IBM MQSeries systems. To use this guide effectively, you should: C Understand the basic concepts described in the webmethods B2B Server Administrator s Guide and the webmethods B2B Integrator User s Guide. C Know how to create flow, Java, and/or C/C++ B2B services. C Be familiar with the concepts of messaging and queuing generally and MQSeries specifically. Typographical Conventions This document uses the following typographical conventions: Convention Example Procedures are highlighted by a blue box in the left column. Procedures are described as a series of numbered steps. Characters that you must type exactly are shown in a typewriter (courier) font. Variable information that you must type based on your specific situation or environment is shown in italics. Keyboard keys are shown in uppercase. Keys that you must press simultaneously are joined with the + symbol. Directory paths are shown with the \ directory delimiter unless the subject is UNIX-specific. In these cases, the / is used. If you are working in a UNIX environment, substitute a / for the \ shown in the procedures in this book. Procedure Title Type: setup and then press ENTER. 1. Select the File command from the Activity menu. Type: B2BServerDirectory\setup and then press ENTER. Press ENTER; then press TAB. Press CTRL+ALT+M. B2BServerDirectory\packages\Default 2 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

3 Typographical Conventions Convention Information that you must read before beginning a procedure or that alerts you to negative consequences of certain actions is denoted with this special symbol. Notes that provide related, but noncritical, information are denoted with this special symbol. Example Caution: If the folder is not already open in the Document Browser, open it before you start the following procedure. Note: When you start the webmethods B2B Integrator, you will be asked to log on to a webmethods B2B Server. Program Code Conventions For programming code and command syntax, this document uses the following typographical conventions: Convention Keywords and values that you must type exactly as printed are shown in typewriter (courier) font. Variable values or parameters that you must supply are shown in italics. Keywords or values that are optional are enclosed in [ ]. Do not type the [ ] symbols in your own code. Example %CoSymbol% %VarName% %loop LoopVar [null=nullvalue]% Program Code Conventions For programming code and command syntax, this document uses the following typographical conventions: Convention Keywords and values that you must type exactly as printed are shown in typewriter font. Variable values or parameters that you must supply are shown in italics. Keywords or values that are optional are enclosed in [ ]. Do not type the [ ] symbols in your own code. Example %CoSymbol% VarName %loop LoopVar [null=nullvalue]% webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0 3

4 CHAPTER 1 Introduction Related Documentation The following documents are useful companions to this guide. Some documents are in PDF format and others are in HTML. Refer to this book webmethods B2B Server Administrator s Guide webmethods B2B Integrator User s Guide webmethods B2B Java API Reference webmethods B2B Integrator Online Reference For Information about using the Server Administrator to configure, monitor, and control the webmethods B2B Server. This book is for server administrators. You will find this book at: B2BServerDirectory\doc\B2BAdministratorsGuide.pdf Information about creating and testing B2B services and client applications. This book for application developers. You will find this book at: B2BIntegratorDirectory\doc\B2BIntegratorsGuide.pdf Descriptions of the Java classes you use to create B2B services. This reference is for developers who build B2B services using Java. You will find this book at: B2BServerDirectory\doc\API\Java\index.html Information about the controls in the B2B Integrator application windows and step-by-step procedures describing how to perform tasks with the B2B Integrator. You can access the online reference by clicking Help in an application window or dialog box. Other Useful Documentation For information about MQSeries, see IBM's online library at: For information about Java Messaging Service (JMS), see the Java Message Service specification from Sun Microsystems, Inc. at: Viewing this Document To view this document, which is in PDF format, you must have Acrobat Reader 4.0 or later installed on your computer. If you have an earlier version of Acrobat Reader, 4 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

5 Related Documentation you will receive the following error message when you open this document and Acrobat Reader will not display the images in this document: Could not find the ColorSpace named Cs8. If you do not have Acrobat Reader, or you do not have the correct version, you can download a copy from Printing this Document To produce a hard copy of this guide, print this document from Acrobat Reader. You will find the document s title page and table of contents at the end of the printed copy. To create a traditional, paper-based manual, simply move these pages to the front of the document after it is printed. webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0 5

6

7 CHAPTER Product Overview What is the MQSeries Adapter?...8 Architecture and Components...10 Message Handlers...11 Delivering Messages to MQSeries...11 Retrieving Messages from MQSeries...12 Listening for Messages on MQSeries...13 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0 7

8 CHAPTER 2 Product Overview What is the MQSeries Adapter? The webmethods B2B MQSeries Adapter (MQSeries Adapter) allows webmethods B2B to exchange information with other systems through an IBM MQSeries message queue. This capability lets you route documents or any piece of information from webmethods B2B to systems that use MQSeries message queuing as their information interface. For example, you might use the MQSeries Adapter to extract information from an XML-based purchase order, repackage it as an order record, and deliver it to a queue for processing by a back-end enterprise system. Or you might use the MQSeries Adapter to monitor a queue and to issue updates to various systems on your intranet when a message appears in that queue. What is Queuing? Queuing is a programming technique in which two programs exchange data asynchronously, without calling one another directly. Using queuing, two programs communicate by passing messages to one another via a queue. Conceptually, a queue is like an in box. When one program wants another program to process a piece of information, it simply puts that information into the other program s queue. On the other end, the receiving program monitors its designated queue and processes messages that other programs deposit in it. Programs exchange data via a queue Program A Program B Queue Systems that interface with one another through queuing never interact directly they only interact with their queues. (In fact, a program might not process its queue until hours, days, or weeks after another program deposits a message in it.) A queue manager, such as MQSeries, acts as an intermediary between the programs that want to exchange information. It functions as a server, controlling the flow of information in and out of a set of queues. The programs that want to communicate with one another 8 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

9 What is the MQSeries Adapter? whether they are the suppliers of information or the consumers of information are the queue manager s clients. Because these programs do not interact directly, they are considered peers of one another. Under this architecture, one program is not subordinate to, or a client of, the other. Note: It is important to understand that the queue manager does not actively process or distribute the messages it receives. Its role is to simply accept messages and hold them in the appropriate queue until a client explicitly requests them. What is a Message? A message is a discrete unit of information that one program wants to pass to another. For example, a message might be a string containing a purchase order, a binary data structure containing an employee record, or a blob containing a graphic image. The queue manager does not impose any constraints on the content or format of messages exchanged via a queue, and neither does the MQSeries Adapter. Note: When a program puts a message into a queue, the queue manager envelops the message with control information such as routing information, priority codes, and message type. The term message can also refer to the entire message structure that is, the control information plus the unit of information to be passed. In this context, the unit of information is usually referred to as the payload, the application data, or the user data. When this distinction is necessary, this book uses the term payload to refer to the content of the message. To use queuing effectively, programs that communicate via a queue must agree on a common message content and structure. For example, if Program A is designed to pick up and process cxml-formatted purchase orders from a queue named Orders, programs that interact with Program A must deliver properly-formatted cxml purchase orders to the Orders queue. Identifying the content and structure of the payload is a key activity you must perform when designing a system that exchanges data through the MQSeries Adapter. webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0 9

10 CHAPTER 2 Product Overview Architecture and Components The MQSeries Adapter provides a set of development tools that you use to build message handlers. A message handler is a B2B service that performs one or more messaging operations on a specified MQSeries queue. The MQSeries Adapter also contains run-time components needed to execute the message handlers you create. The message handlers that you build implement the MQSeries Java Messaging Service (JMS) API, and use IBM s Java MQSeries client software to interact with MQSeries queues. Caution: To use the MQSeries Adapter, you must have a JMS-compliant version of IBM s MQSeries Java client software installed on the webmethods B2B Server. For a complete list of requirements and prerequisites, see the webmethodsb2b Adapter: MQSeries Edition Installation Guide. The following diagram illustrates the run-time relationship between a message handler on the webmethods B2B Server and the queues on an MQSeries server. MQSeries Adapter Run-time Architecture webmethods B2B Server IBM MQSeries Server Queue A 1 2 Message Handler JMS MQSeries Java Client Queue B Queue C Queue D Queue E Part Description 1 Message Handler executes on the webmethods B2B Server. It uses the MQSeries Java Client software to open a session to an MQSeries server and to perform a single messaging operation (a Get, a Put, or a Listen) on a specific queue. 2 IBM MQSeries Server receives requests from the message handler and executes the requested operation on the specified queue. 10 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

11 Message Handlers Message Handlers A message handler is a flow service that you generate using the Messaging tools in the Server Administrator. You can build the following kinds of message handlers: Type Description Put Get Opens a session to an MQSeries server and delivers a message to a queue. Opens a session to an MQSeries server and retrieves a message from a queue. Listen Opens a session to an MQSeries server and monitors a queue for messages. When a message arrives in that queue, the message handler automatically retrieves the message and passes it to a B2B service that you specify. A message handler delivers or retrieves messages to or from the appropriate MQSeries queue based on control parameters that identify the queue. You assign values to these control parameters when you build the message handler; you should not alter them at run time. In addition, you can designate any message handler to be either transactional or nontransactional. A transactional message handler can control Logical Unit of Work (LUW) processing by using MQSeries Syncpoint features. That is, it can perform multiple requests as a single LUW. Requests issued within a given LUW can be controlled via COMMIT and ROLLBACK services. A non-transactional message handler performs a single request as an autonomous unit of work After you build a message handler, you invoke it just as you would invoke any other B2B service. In most cases, you will probably include a message handler in a flow service and use the Pipeline Editor to map values in or out of the message s payload. Delivering Messages to MQSeries The following diagram shows how the Put-type message handler delivers one or more messages to an MQSeries queue. In the following example, the message handler is invoked by a flow that gets a purchase order, extracts data values from the document, and then passes the result to the message handler, which sends it to MQSeries. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

12 CHAPTER 2 Product Overview Stages of the Message Delivery Process PO 1 B2B Flow Service IBM MQSeries Server node Data Transformation Service payload Queue A Queue B 2 Queue C MQSeries Message payload Control parameters Queue D PUT Msg Handler 3 Queue E Step Description A trading partner sends an XML-based purchase order to a B2B service that you create. The service extracts data from the XML document, generates the payload, and passes it to the Put message handler that you built using the MQSeries Adapter. The message handler accepts the payload, generates an MQSeries message, opens a session to the specified MQSeries server, and sends the message to the appropriate queue. If the message handler is a transactional message handler, it handles multiple messages as a single logical unit of work, then commits or rolls back the unit of work and closes the connection to the server. Retrieving Messages from MQSeries The following diagram shows how a Get message handler retrieves one or more messages from a queue on MQSeries. In the following example, the message handler automatically executes at a predefined time. When it executes, it checks the queue and passes the retrieved message(s) to another B2B service, which transforms the data into a document that it would pass to another B2B service. 12 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

13 Message Handlers Stages of the Message Delivery Process 1 B2B Flow Service IBM MQSeries Server GET Msg Handler control parameters payload 2 Queue A Queue B 3 MQSeries Message Queue C payload Queue D Data Transformation Service document Queue E... Step Description The webmethods Scheduler invokes the flow service containing the Get message handler. The message handler connects to MQSeries, retrieves a message from a specified queue, extracts the payload, puts it in the pipeline, and removes the message from the MQSeries queue. If the message handler is a transactional message handler, it retrieves multiple messages as a single unit of work, then commits or rolls back the unit of work, closes the connection to the queue, and removes the messages from the MQSeries queue. A service that you create takes the payload and processes it in the way you specify. Listening for Messages on MQSeries The following diagram shows how the Listen message handler monitors a queue for messages and automatically executes a B2B service when a message arrives in the queue. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

14 CHAPTER 2 Product Overview The Listening Process webmethods B2B Server IBM MQSeriesServer control parameters LISTEN Msg Handler 1 payload 2 Queue A Queue B 3 MQSeries Message Queue C payload Triggered Service document Queue D Queue E Step Description The Listen message handler connects to MQSeries and continuously monitors the specified queue. When a message arrives in the queue, the message handler retrieves the message and extracts the payload. The message handler invokes a specified B2B service and passes the payload to it. 14 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

15 CHAPTER Defining Server Settings for MQSeries Servers Overview of Server Settings...16 Defining Server Settings...17 webmethods B2B Adapter: MQSeries Edition User Guide VERSION

16 CHAPTER 3 Defining Server Settings for MQSeries Servers Overview of Server Settings Before you create a message handler, you must specify server settings that webmethods B2B uses to open a session to an MQSeries server. A server setting is a named set of parameters that you define using the B2B Server Administrator. These parameters include the connection values such as host name, port number, channel name, and others needed to establish a connection with a particular queue manager. How Does a Message Handler Use the Server Settings? At run time, a message handler locates the named set of server settings assigned to it. webmethods B2B uses the server settings parameters to open a session to the MQSeries server. The server settings specify which server and queue manager the service will connect to, and the way in which the connection will be made (under which port number, authorization profile, character format, and so forth). The following diagram shows a webmethods B2B Server on which six sets of server settings are defined. Each set describes a connection to a particular queue manager. For example, the server setting MQ_HRIS might define a queue manager on an HR server, the server setting MQ_Limelight might define a queue manager on a corporate mainframe, and so on. In this example, the message handler getledgerrecord uses the server setting MQ_Acct (specified by the message handler s connfac parameter) to connect to a queue manager. Message handlers use Server Settings to connect to a queue manager webmethods B2B Server getledgerrecord connfac=mq_acct Server Settings MQ_HRIS OAQ_CIRS connect to queue manager MQ_Limelight MQ_Northstar MQ_Marimba OAQ_Snap MQSeries Java Client 16 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

17 Defining Server Settings Note that server settings define a queue manager, not a particular queue. A separate parameter (named queue) in the message handler identifies with which queue the service interacts. Caution: When you create server settings, you actually build a JMS connection factory containing the connection parameters you specify. At run time, the MQSeries Adapter establishes a connection to a queue manager by retrieving and using the named connection factory. Defining Server Settings The procedure in this section describes how to create server settings. When you define server settings, keep the following points in mind: C C C You must define a set of server settings for each MQSeries queue manager that you need to access. A single set of server settings can be referenced by more than one message handler. If several message handlers access the same queue manager with the same connection attributes, they should all reference the same set of server settings. This way, if network changes occur (for example, the queue manager moves to another host machine or one queue manager replaces another), you only need to make changes to one set of server settings. You may define multiple server settings for the same MQSeries queue manager. You might do this, for example, if two message handlers use the same queue manager but need to connect to the queue manager with different security exits. Information You Need From Your MQSeries Administrator To define server settings, you need to know the following information about your MQSeries queue manager: C C The name of the MQSeries queue manager that you need to access. (This value is case-sensitive.) The names of Java classes, if any, containing user-exit code that the MQSeries Java client must execute when it makes a request to the queue manager. For more information about user exits, see Implementing Custom Code with User Exits on page 20. If your MQSeries queue manager does not reside on the same machine as webmethods B2B, you will also need the following information about your MQSeries server: C C The name of the host machine on which MQSeries resides. The port number where MQSeries listens for client requests. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

18 CHAPTER 3 Defining Server Settings for MQSeries Servers C C The name of the MQI server-connection channel assigned to the MQSeries queue manager. (This value is case-sensitive.) The CCSID (Coded Character Set Identifier) used by the machine on which webmethods B2B is installed. When webmethods B2B makes a connection to MQSeries, this value tells MQSeries which character encoding scheme the webmethods server machine uses. Caution: The CCSID specified for a Remote Server Setting is only used when establishing the connection to the remote Queue Manager. The CCSID used to encode the character data within the actual payload of the messages must be specified when you define a Message Destination. In most cases, you can leave this field blank. See CCSID Notes on page 33 for more information. C The user ID and password to be used to connect to the Queue Manager, if the Queue Manager is secured. These values can be overridden at application run time. To define a set of server settings Caution: You must have administrator privileges on the webmethods B2B Server to perform the following procedure. 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Server Settings. 3. Click the Add Server Settings button. 4. From the Provider list, select MQSeries if it is not already selected. 5. Complete the following fields (you will need the information supplied by your MQSeries administrator to complete some of these fields): In this field Alias Name Description Queue Manager Name Transport Type Specify A unique name for this set of server settings. (Message handlers will reference this collection of server settings by this name.) Do not use the following characters in the name: % #? & + < > An optional text description. The name of the queue manager to which you want to connect. Make sure the name you type matches the name of the queue manager on the MQSeries server exactly. This name is case-sensitive. Where the specified queue manager resides with respect to the webmethods B2B. 18 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

19 Defining Server Settings Select Local Remote If The queue manager is running on the same machine as webmethods B2B. The queue manager is running on another machine on the network. (Make sure that the MQSeries Queue Manager is configured for remote access if you use this transport method.) 6. If you selected the Remote option under Transport Type in the previous step, complete the following fields to specify network information about the queue manager. In this field Host Name Port Channel CCSID Specify The name of the server machine on which the MQSeries queue manager is installed. The port number where the MQSeries queue manager listens for client requests.( If you do not specify a port number, the MQSeries Adapter uses 1414 as the default.) The name of the MQI server-connection channel assigned to the queue manager. This value is case sensitive. Maximum characters: 20. The Coded Character Set Identifier (CCSID) used by the webmethods B2B machine. Optional. This numeric value specifies the code page used by the platform on which webmethods B2B is installed. For valid CCSID values, see IBM s MQSeries documentation. Note: The CCSID specified for a remote server setting is only used when establishing the connection to the remote Queue Manager. In most cases, you can leave this field blank. In contrast, the CCSID used to encode the character data within the actual payload of the messages must be specified when you define a Message Destination. See Defining MQSeries Message Destinations on page 24 and CCSID Notes on page 33 for more information. Default UserID Default Password The user ID to be used to connect to the Queue Manager, if the Queue Manager is secured. This value can be overridden at application run time. The password to be used in conjunction with the userid to connect to the Queue Manager, if the Queue Manager is secured. This value can be overridden at application run time. 7. If you selected the Remote option under Transport Type, and you want the MQSeries Java client to automatically execute client-side, user-exit webmethods B2B Adapter: MQSeries Edition User Guide VERSION

20 CHAPTER 3 Defining Server Settings for MQSeries Servers code (code that your site has developed) at certain points during a conversation with this queue manager, complete the User Exit parameters as described in Implementing Custom Code with User Exits on page Click Save. The Server Administrator builds a connection factory based on the values you have specified on this page, saves it to the Repository, and displays the Message Server Settings List screen. If you receive an error message when you click Save, verify that the settings you specified are correct. 9. Test the newly created server setting by clicking the Test Connection icon in the Message Server Settings List screen. Implementing Custom Code with User Exits User exits enable you to implement custom, client-side code that will execute at the following points during a conversation with a queue manager: This User Exit Send Receive Security Executes During a Put operation. The user-exit code executes after webmethods B2B passes a message to the MQSeries Java client but before the client sends the message to the queue manager. You might use this exit to alter or add information in the message header before a message is passed to the queue manager. During a Get or Listen operation. The user-exit code executes after the MQSeries Java client retrieves a message from the queue manager but before it passes that message to webmethods B2B. You might use this exit to filter or alter messages based on information in the message header. Each time a connection is made to the queue manager. You might use this exit to perform client-side authorization and/or authentication before establishing a connection with the queue manager. Creating Code for a User Exit The code you create must implement IBM s MQSendExit, MQReceiveExit, and/or MQSecurity folder, and conform to the specifications (method names, return values, and so on) required by the IBM MQSeries Java client. For more information about creating user exits, see Writing User Exits in the IBM manual, MQSeries Using Java (SC ). The following example class contains all three types of user exits. Public class MyMQExits implements MQSendExit, MQReceiveExit, MQSecurityExit { // Send exit public byte[] sendexit(mqchannelexit channelexitparms, MQChannelDefinition channeldefparms, 20 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

21 Defining Server Settings byte agentbuffer[]) { // your code goes here } // Receive exit public byte[] receiveexit(mqchannelexit channelexitparms, MQChannelDefinition channeldefparms, byte agentbuffer[]) { // your code goes here } // Security exit public byte[] securityexit(mqchannelexit channelexitparms, MQChannelDefinition channeldefparms, byte agentbuffer[]) { // your code goes here } When you finish defining a user exit, do the following: Copy the finished class file(s) to the machine on which webmethods B2B resides. Make sure the CLASSPATH includes the path to those class file(s). Use the following procedure to specify the User Exit parameters in the server settings for the queue manager to which you want the user exit code applied. To specify User Exit parameters 1. Start the B2B Server Administrator if it is not already running. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. Open the server settings for the queue manager to which you want to assign user-exit code. See Editing Server Settings on page 69 for the procedure to do this. 3. Scroll to the bottom of the Edit Server Settings page, and perform the following steps to complete the User Exits parameters for the appropriate Receive, Send, and/or Security field: 1. In the Java Class Name text box, specify the name of the Java class containing the code you want the MQSeries client to execute. 2. In the Initialization Parameters text box, specify any data values that you want webmethods B2B to pass to the Java class. 4. Click Save to save the updated settings. If you receive an error message when you click Save, verify that all settings on the Edit Server Settings page are correct. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

22

23 CHAPTER Defining MQSeries Message Destinations Defining MQSeries Message Destinations...23 webmethods B2B Adapter: MQSeries Edition User Guide VERSION

24 CHAPTER 4 Defining MQSeries Message Destinations Defining MQSeries Message Destinations Before you build message handlers for an MQSeries queue manager, you must create Message Destinations. A Message Destination represents an MQSeries queue that a message handler uses. Each Message Destination defines an MQSeries queue name and the default run-time attributes that the message handler uses. For example, you might create a destination that represents the queue into which you will be submitting messages, and another destination that represents the queue from which you will be receiving messages. When specifying queue names, you can either type the names of queues or you can select queue names from a list that you import. See Importing the Names of MQSeries Queues on page 29 for more information. Caution: Before you can create Message Destinations, you must specify your server settings (see Defining on page 17). However, when creating Message Destinations, you can specify queues that have not yet been defined. Just be sure that your MQSeries administrator defines the queues before you try to use message handlers with them. To define a Message Destination 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Destinations. 3. Select MQSeries in the Provider field, if it is not already selected. 4. Click the Add Destination button. The Create Message Destination screen is displayed. 5. In the Server Settings field, select the server setting that you created in Defining Server Settings on page If you imported the list of queue names used by your MQSeries queue manager, as described in Importing the Names of MQSeries Queues on page 29, perform the following steps to add a destination queue to webmethods B2B. a. To display a complete list of queue names, type * in the Add search pattern to find field and click Find. b. Select a queue to add by clicking on its name or on its corresponding Add button. A screen showing queue settings is displayed. c. Skip to step webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

25 Defining MQSeries Message Destinations Caution: To display a list of queue names matching certain criteria, type a character pattern and click Find. You may use the following wildcard characters in your pattern:? matches any single character * matches any string of characters Example: *FNCL* This example would produce a list of all queues containing the string FNCL anywhere in their names. Note that character patterns are case-sensitive for example, FNCL will not match fncl or Fncl. 7. If you did not import the list of queue names used by your MQSeries queue manager as described in Importing the Names of MQSeries Queues on page 29, specify a queue name now in the Destination name to add field and click Add. A screen showing queue settings is displayed. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

26 CHAPTER 4 Defining MQSeries Message Destinations 8. In the Alias Name field, type a unique name for the set of queue properties to create, or accept the default name. We suggest that you incorporate the name of the queue in your alias. Doing this makes it easy for you and others to determine the queue to which these parameters belong. For example, if your queue name is FNCLCo01, and you are creating a set of properties to deliver highpriority messages, you might specify an alias such as FNCLCo01_Pri9. 9. Type descriptive text in the Description field. Optional. 10. Complete the following fields to specify the properties you want the message handler to assign to messages that it puts in this queue: In this field Message Time to Live Priority Specify The length of time the delivered message is allowed to stay in the queue before the queue manager can discard it. Select one of the following: Unlimited The message can remain in the queue indefinitely. Limited The message is deleted after a specified period of time. When you use this option, you must specify an expiration period in the milliseconds text box. For example, to specify 10 seconds, set Limited to Specifying 0 milliseconds is equivalent to unlimited. Allow Application to set Lifetime The run-time value of the timetolive parameter determines the message s expiration period. For information about setting this parameter at run time, see Setting Optional Values in a Put Message Header. on page 39. The priority you want assigned to the delivered message. Select one of the following: Use Queue Default The message assumes the queue s default priority value (i.e., the default priority value the MQSeries administrator has assigned to the queue.) Priority The message is delivered with the priority you specify in the Priority text box. Valid priority values are integers 0 9, where 9 is the highest priority. Allow Application to set Priority The run-time value of the priority parameter in the message header sets the message s priority. For information about setting this parameter at run time, see Setting Optional Values in a Put Message Header. on page webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

27 Defining MQSeries Message Destinations In this field Delivery Mode Target Client Specify Whether or not messages delivered to this queue are to be logged (persisted) on the MQSeries server in such a way that they can be recovered if the server is restarted: Select one of the following: Use Queue Default Messages are logged or not according to the queue s default behavior (i.e., the default delivery mode the MQSeries administrator has assigned to the queue.) Not Persistent Messages are not logged to persistent storage. Persistent Messages are logged to persistent storage so that they can be recovered if the MQSeries server fails and is restarted. Allow Application to set Persistence The run time value of the deliverymode parameter determines whether a message delivered by this service is persisted or not. For information about setting this parameter at run time, see Setting Optional Values in a Put Message Header. on page 39. Whether or not the message will be consumed by a Java Messaging Service (JMS) client application. This setting determines whether the message is sent in JMS or MQSeries message format. Select one of the following: JMS Compliant Client Messages will be consumed by a JMS client application. When you select this option, messages are sent to the queue in JMS message format. Do not enable this option unless all consumers of the message are JMS clients. Non-JMS Compliant Client Messages will be consumed by a non-jms, MQSeries client application. When you select this option, messages are sent to the queue in standard, MQSeries format. Select this option if any consumer of the message is a non-jms application. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

28 CHAPTER 4 Defining MQSeries Message Destinations In this field CCSID Specify The Coded Character Set Identifier used to represent character data within the payload of messages sent to this Destination. The CCSID value specified here will affect the CCSID value that is placed into the MQSeries MQMD message descriptor, the CCSID= portion of the MQRFH2 header for JMS target clients, and possibly the actual data contained within the msgbody. If the Payload of the message is a text string, the Destination CCSID value is used to encode the data within the msgbody as it is converted from a Java string and placed into the msgbody. If the payload of the message is a byte array, the CCSID value should be set to indicate the encoding scheme used to represent any character data contained within the byte array. However, no data conversion occurs when the byte array is placed into the msgbody. For non-jms target clients, the CCSID value specified here will be placed directly into the MQMD CCSID field. If 0 is specified as the CCSID on the Destination, 1208 (the UTF8 code page) is placed into the MQMD. For JMS target clients, the CCSID value specified here will be placed into the CCSID= portion of the MQRFH2 JMS Header, and the CCSID of the Queue Manger is placed into the MQMD. If 0 is specified as the CCSID on the Destination, the CCSID of the Queue Manager is placed into the MQMD and the CCSID= portion is omitted from the MQRFH2 header. Note: The CCSID value that you specify as a remote server setting is only used when establishing the connection to the remote Queue Manager. See Defining Server Settings on page 17 and CCSID Notes on page 33 for more information. Numeric Encoding The encoding scheme into which numeric values in application data must be converted before the message is delivered to the queue. This value must match the numeric-encoding scheme for which the queue is configured. See your MQSeries Administrator to obtain the correct setting. Set Native to Enable if the queue is configured for System/390 numeric encoding. Set Native to Disable if you do not want numeric values to be converted to another encoding scheme. 28 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

29 Defining MQSeries Message Destinations 11. If you disabled native numeric encoding in the previous step, select one of the following options to describe the original format of the following data types: In this field Integer Decimal Float Specify The byte order used to represent multi-byte integer values in the application data. Normal Integers are in big-endian format (the lowest address contains the most significant byte; as in Java). Reversed Integers are in little-endian format (the highest address contains the most significant byte; as used by PCs). The format used for packed decimal values. Normal Packed decimal values are in big-endian format (as used by System/390). Reversed Packed decimal values are in little-endian format. The format in which floating-point values are represented. IEEE Normal Floats are in big-endian IEEE format (the lowest address contains the most significant byte). IEEE Reversed Floats are in little-endian IEEE format (the lowest address contains the most significant byte). System/390 Floats are in System/390 format. 12. Click Continue. The Message Destination List screen is displayed, showing the queue that you specified. Importing the Names of MQSeries Queues You can import queue names into webmethods B2B so that you can select them from a list when defining Message Destinations. This procedure consists of two tasks that you must complete in the following order: Task 1 Description Generate a file containing a list of the queue names associated with the queue manager. 2 Import the queue name file into webmethods B2B. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

30 CHAPTER 4 Defining MQSeries Message Destinations Caution: If your MQSeries administrator adds or deletes queues from a queue manager whose names you have imported, you must re-execute these tasks to refresh the list of queue names on webmethods B2B. Task 1 Generate the queue name file To create a file containing queue names for a queue manager, use IBM s RUNMQSC utility to display the queue names for a queue manager and direct the output from this utility to a file. (You must run this utility on the machine on which the MQSeries server runs. If you do not have administrative access to the MQSeries server, ask your administrator to perform this task for you.) You use the following sequence of command line commands to create a queue name file on an MQSeries server running under Windows NT or UNIX: where: RUNMQSC qmgrname > qnamefile display qmgr display queue(*) end qmgrname is the name of the queue manager for which you want to generate a list of queue names. qnamefile is the name of the file to which you want the list written. Example RUNMQSC QM_annuvin.webmethods.com > MQSC.out If the MQSeries server runs in a mainframe environment such as MVS or OS/400, run RUNMQSC as a batch job and direct the printed output from the batch job to a file. Within the batch job, do the following: Display details about the queue manager (display qmgr) Display details about all its queues (display queue (*)) Use a file-transfer utility to download the output file to your PC environment. Make sure to convert the contents of the file to ASCII format during the file transfer process. The file you generate with RUNMQSC should look similar to the following file listing, and will contain the names of the queues associated with your queue manager: 04L1830,5639-B43 (C) Copyright IBM Corp. 1994, ALL RIGHTS RESERVED. Starting MQSeries Commands. 1 : display qmgr AMQ8408: Display Queue Manager details. DESCR( ) DEADQ( ) DEFXMITQ( ) CHADEXIT( ) CLWLEXIT( ) CLWLDATA( ) 30 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

31 Defining MQSeries Message Destinations Name of queue manager Names of queues REPOS( ) REPOSNL( ) COMMANDQ(SYSTEM.ADMIN.COMMAND.QUEUE) QMNAME(QM_annuvin.webmethods.com) CRDATE( ) CRTIME( )... 2 : display queue(*) AMQ8409: Display Queue details. QUEUE(MQAI.REPLY ) TYPE(QLOCAL) AMQ8409: Display Queue details. QUEUE(SYSTEM.ADMIN.CHANNEL.EVENT) TYPE(QLOCAL) AMQ8409: Display Queue details. QUEUE(SYSTEM.ADMIN.COMMAND.QUEUE) TYPE(QLOCAL)... AMQ8409: Display Queue details. QUEUE(postcard) TYPE(QLOCAL) 3 : end 2 MQSC commands read. No commands have a syntax error. All valid MQSC commands were processed. Task 2 Import the queue names After you generate the queue name file, use the following procedure to import the queue names into webmethods B2B. To import MQSeries queue names into webmethods B2B 1. Start the B2B Server Administrator if it is not already running. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Provider Admin. 3. From the Provider list, select MQSeries if it is not already selected. 4. In the Queue Manager Name field, type the name of the queue manager whose queue names you are importing. Type the name exactly as it is defined on the MQSeries server. This value is case-sensitive. 5. In the Import File field, type the name of the file you created with the RUNMQSC utility in Task 1. Specify the complete path to this file and click Import. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

32 CHAPTER 4 Defining MQSeries Message Destinations 32 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

33 Defining MQSeries Message Destinations CCSID Notes When you define a Message Destination, the CCSID you specify is used to encode the character data within the actual payload of the messages. In contrast, the CCSID value that you specify as a remote server setting is only used when establishing the connection to the remote Queue Manager. See Create Server Settings on page 85 for more information. The following table shows how different combinations of CCSID settings provide different results. Destination Settings Server Settings Results JMS Target CCSID Remote CCSID QMGR CCSID MQMD MQRFH2 X 0 X default empty 0 X default N/A X 0 X empty 0 X N/A X 0 X empty 0 X N/A X 0 Local N/A empty 0 Local N/A N/A X 37 X default CCSID=37 37 X default N/A X 37 X CCSID=37 37 X N/A X 37 X CCSID=37 37 X N/A X 37 Local N/A CCSID=37 37 Local N/A N/A webmethods B2B Adapter: MQSeries Edition User Guide VERSION

34

35 CHAPTER Building Message Handlers Introduction...36 Building Message Handlers that Put Messages in a Queue...37 Building Message Handlers that Get Messages from a Queue...45 Building Services that Listen to a Queue...59 webmethods B2B Adapter: MQSeries Edition User Guide VERSION

36 CHAPTER 5 Building Message Handlers Introduction This chapter describes how to build services, called message handlers, which interact with MQSeries queues. Message handlers send (put) and retrieve (get) messages from a specific queue. You build a message handler using the B2B Server Administrator. When you create a message handler, it is registered on the webmethods B2B Server in a package that you specify. Once you build a message handler, you can invoke it in the same ways you invoke any other B2B service from a flow service, from a client application, from a Java service, and so on. Using the MQSeries Adapter, you can build the following types of message handlers. Each type interacts with a queue in a specific way. Type Description See Procedures in Put Get Connects to an MQSeries server and delivers a message to a specified queue. Opens a session to an MQSeries server and retrieves a message from a specified queue. Building Message Handlers that Put Messages in a Queue on page 37. Building Message Handlers that Get Messages from a Queue on page 45. In addition to the Put and Get message handlers, which you can invoke from a B2B service, the MQSeries Adapter also allows you to create the following type of message handler that you enable or disable in the webmethods B2B Server. Type Description See Procedures in Listen Opens a session to an MQSeries server, and monitors a specific queue for messages. When a message arrives in that queue, the messaging service automatically retrieves the message and passes it to a B2B service that you specify. Building Services that Listen to a Queue on page webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

37 Building Message Handlers that Put Messages in a Queue Building Message Handlers that Put Messages in a Queue Use the procedure in this section to build a message handler that delivers a message to a specific queue. Before you begin, verify that: C You have defined the server settings for the queue manager with which the message handler will interact, as described in Chapter 3, Defining Server Settings for MQSeries Servers. C You have created Message Destinations that identify your MQSeries queues, as described in Chapter 5, Defining MQSeries Message Destinations. C The package in which you want to install the message handler exists. See the webmethods B2B Server Administrator s Guide for information about creating packages. To build a service that puts a message in a queue 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Message Handlers. 3. From the Server Settings list, select the server settings that the message handler will use to connect to the queue manager at run time. Caution: If the screen displays the following error message: Or the Server Settings list does not display the server you want to use, you must create server settings for your queue manager. See Defining Server Settings for MQSeries on page 15 for the procedure to do this. 4. Click the Add Message Handler button. The destination queues that you defined should be displayed. 5. In the list of queues, locate the queue to which you want this message handler to deliver messages and click in that row. A screen is displayed, showing parameters for the message handler. 6. Complete the following fields to specify the name and location of the message handler: webmethods B2B Adapter: MQSeries Edition User Guide VERSION

38 CHAPTER 5 Building Message Handlers In this field Package Service Name Specify The package in which you want this message handler saved. A unique, unqualified name for this message handler. (Note that message handlers are automatically stored in the msghandlers:mqseries folder. Do not move them from this location.) 7. Complete the following Connection Management fields. For more information about connection pooling, see Connection Pool on page 56. In this field Connection Type Minimum Connections Maximum Connections Inactive Lifetime Specify Whether the message handler will use transaction semantics. See Transactional versus Nontransactional Message Handlers on page 53 for more information. Non-Transacted Will not use transactional semantics. Transactional Will use transactional semantics. The minimum number of connections you want webmethods B2B to maintain in the connection pool. The maximum number of connections you want webmethods B2B to maintain in the connection pool. The length of time, in milliseconds, that an inactive connection can remain in the pool. 8. Click Continue. The B2B Server Administrator will build the message handler using the parameters you have specified. The Message Handler List Screen is re-displayed, showing the new message handler. Notice that a new message handler is created in a disabled state, as indicated by the red icon in the Enabled column. (A green icon indicates the enabled state.) 9. To enable the message handler, click on the red icon and then click OK in the pop-up verification screen. The icon should change to green. 38 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

39 Building Message Handlers that Put Messages in a Queue Using a Put Message Handler After you create a Put message handler, you can invoke it from a B2B service or a client application. Inputs to the Put Message Handler When you invoke the Put message handler, you must pass to it the body of the message you want it to send. You may optionally pass certain values in the message header. C Passing the Body of the Message to a Put Message Handler. When the message handler is invoked, it expects to find the body of the message in the variable named msgbody. This variable can contain a String, a byte [ ], a Values object, or a Serializable Java Object. Beyond data type, there are no constraints on the content or format of the data in msgbody. At run time, the contents of msgbody becomes the payload that the MQSeries Adapter delivers to the queue. Depending on the type of data you put in msgbody, the MQSeries Adapter converts the message to one of the following JMS data types before sending it to the queue: msgbody data type String byte [ ] Values object Serializable Java Object Is converted to this JMS data type TextMessage BytesMessage ObjectMessage ObjectMessage As a developer, you must understand what the consumer (the application that will retrieve this message from the queue and use it) expects to receive so you can build the contents of msgbody to those requirements. If msgbody is null or contains an unsupported data type, an exception will occur. Caution: If you pass a Values object or a Serializable Java Object to msgbody, the contents of your variable is serialized and sent as an ObjectMessage containing the serialized data. If this message will not be consumed by a Java application, you should send your data as a type that the application can more easily use (e.g., String or byte [ ]). C Setting Optional Values in a Put Message Header. You may optionally set the following message header parameters when you invoke the message handler. These parameters are elements of a Record (a Values object) named msgheader. Note that the deliverymode, priority, and timetolive elements in msgheader allow you to dynamically specify the message s deliver mode, priority, and expiration period at run time. To use these values, the Message Destination used by the message handler must be configured to accept values from the application. For example, if you want to webmethods B2B Adapter: MQSeries Edition User Guide VERSION

40 CHAPTER 5 Building Message Handlers set message expiration at run time, you must set the Time to Live parameter to Allow Application to set Lifetime. For information about viewing and editing queue parameters, see Editing Message Handler on page 70. msgheader Element Data Type Description correlationid String A value that you can optionally assign to uniquely identify this message and relate it to a subsequent message. In a request/response scenario, you typically set correlationid to match the messageid of the request message. deliverymode String Specifies whether you want the message persisted (stored in such a way that it can be recovered if the server is restarted) on the MQSeries server. Set to one of the following values: Value Description 1 Do not persist. 2 Persist the message. -1 Use the queue s default persistence value. Be aware that deliverymode is used only when the Delivery Mode queue parameter is set to Allow Application to set Persistence. Otherwise, it is ignored. priority String Specifies the priority you want assigned to the message. Set a value from 0 9 (where 9 is the highest priority). Be aware that priority is used only when the Priority queue parameter is set to Allow Application to set Priority. Otherwise, it is ignored. timetolive String Specifies the message s maximum time-to-live period (i.e., the amount of time the message can exist in the queue before it is automatically deleted by the queue manager). Set the length of time in milliseconds or one of the following: Value Description 0 Unlimited time-to-live period. -1 Use the queue s default time-to-live period. Be aware that timetolive is used only when the Time to Live queue parameter is set to Allow Application to set Lifetime. Otherwise, it is ignored. C Other Input Parameters used by a Put Message Handler. If you view the Put message handler with B2B Integrator, you will see a number of input parameters besides msgbody and msgheader. However, if the message handler is transactional, it automatically passes the connectionid parameter as well. See Transactional versus Non-transactional Message Handlers on page 53 for more information about connectionid. 40 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

41 Building Message Handlers that Put Messages in a Queue These parameters are set when you build the message handler and should not be modified with the B2B Integrator or altered at run time These parameters contain the server information and other queuing details that you specified when you create the message handler. They are shown in the Integrator for troubleshooting and informational purposes only. Do not edit these values with the B2B Integrator or modify them at run time. If you need to change these values, use the B2B Server Administrator to edit the message handler. See Editing Message Handlers on page 70 for the procedure to do this. Outputs from the Put Message Handler When a Put message handler executes, it returns a record (a Values object) called message that contains the following elements: message Element Data Type Description messageid String The unique identifier assigned to the message when MQSeries placed it in the queue. timestamp String The date and time that MQSeries placed the message in the queue. correlationid String The correlationid specified in the message header. targetqueuename String The name of the queue in which MQSeries placed the message. deliverymode String The deliverymode assigned to the message that MQSeries placed it in the queue. priority String The priority assigned to the message that MQSeries placed in the queue. expiration String A timestamp indicating the time at which this message will expire in the queue. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

42 CHAPTER 5 Building Message Handlers For a description of the complete specification for a Put message handler, see wm.queue.runtime:put on page 108. Error Handling If the Put message handler does not execute successfully, it returns the following elements in the Values object: Element Name Type Description $error String The Java error message $errortype String The name of a Java exception class Common reasons for the message handler to return an error are: C msgbody is null or contains an unsupported data type. C The message handler cannot locate the server settings specified in the connfac parameter. C The message handler cannot locate the set of queue parameter specified in queue. C webmethods B2B cannot establish a connection to MQSeries. C MQSeries cannot deliver the message to the specified queue (e.g., the queue name is invalid or the queue has been disabled). C The connection between webmethods and MQSeries is dropped. Invoking a Put Message Handler from a Flow Service To invoke a Put message handler from a flow service, open the flow service with B2B Integrator and insert an INVOKE operation that calls the message handler. (Message handlers reside in the msghandlers:mqseries folder in the package where you saved them.) Then, use the Pipeline Editor to map the body of the message to msgbody. Caution: If you map a String List, String Table, or a Record List to msgbody, be aware that only the first element of the list is sent. In these cases, you should use loops to iterate over all elements in the String List, String Table, or Record List. If you want to specify values in the message header, use the Pipeline Editor to set those values explicitly or map them to other variables in the pipeline. For information about using the Pipeline Editor, see the webmethods B2B Integrator User s Guide. The following example shows a flow service that receives a file via FTP, maps the file to msgbody, and puts it in the queue. 42 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

43 Building Message Handlers that Put Messages in a Queue Example of a flow service that invokes a Put message handler The flow retrieves a file via FTP and then maps the file (contained in content) to the message handler s msgbody variable Invoking a Put Message Handler from a Java Service The following code sample shows a very simple Java service that assembles a message and then invokes a Put message handler. /** Demonstrates sending a String array to a message queue. If the array is sent as-is, only the first element will be mapped to the message body. Instead, the array is copied into a Vector, which is then mapped to the message body. The "priority" field in the message header is set to 9, the highest priority, and a message handler is invoked to send the message. */ public final static Values sendrequestlist( Values in ) { Values out = in; Vector msgcontent = new Vector(); String[] msgitems = null; msgitems = (String[])in.get( "list" ); if( msgitems == null msgitems.length == 0 ) { return out; } for( int i=0; i<msgitems.length; i++ ) { msgcontent.addelement( msgitems[ i ] ); } webmethods B2B Adapter: MQSeries Edition User Guide VERSION

44 CHAPTER 5 Building Message Handlers try { Values header = new Values(); header.put( "priority", 9 ); out.put( "msgheader", header ); out.put( "msgbody", msgcontent ); Service.doInvoke( "msghandlers.mqseries", "sendlisttopurchasing", out ); } catch( Exception e ) { Service.throwError( e ); } } return out; 44 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

45 Building Message Handlers that Get Messages from a Queue Building Message Handlers that Get Messages from a Queue Use the procedure in this section to build a message handler that retrieves a message from a specific queue. Before you begin, verify that: C You have defined the server settings for the queue manager with which the message handler will interact, as described in Chapter 3, Defining Server Settings for MQSeries Servers. C You have created Message Destinations that identify your MQSeries queues, as described in Chapter 5, Defining MQSeries Message Destinations. C The package in which you want to install the message handler exists. See the webmethods B2B Server Administrator s Guide for information about creating packages. To build a message handler that gets a message from a queue 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Message Handlers. 3. From the Server Settings list, select the server settings that define how this service will connect to the queue manager at run time. Caution: If the screen displays the following error message: Or the Server Settings list does not display the server you want to use, you must create server settings for your queue manager. See Defining Server Settings for MQSeries on page 15 for the procedure to do this. 4. Click Add Message Handler. The destination queues that you defined should be displayed. 5. In the list of queues, locate the queue to which you want this message handler to deliver messages and click in that row. A screen is displayed, showing parameters for the message handler. 6. Complete the following fields: webmethods B2B Adapter: MQSeries Edition User Guide VERSION

46 CHAPTER 5 Building Message Handlers In this field Package Service Name Specify The package in which you want this service saved. A unique, unqualified name for the service. (Note that message handlers are automatically stored in the msghandlers:mqseries folder. Do not move them from this location.) 7. In the Inbound Service Details section, select Explicit Get and then select one of the following options to specify what you want the message handler to do if the queue is empty when it tries to retrieve a message. Select Wait Indefinitely Wait for milliseconds No wait If you want the message handler to Wait until a message appears in the queue. If you select this option, the Get message handler does not return until a message appears in the queue. Wait for the specified length of time and then return to the calling program. Return immediately. Note: The use of the Wait Indefinitely option can significantly affect your ability to quickly reload the WmQueue package or shut down the webmethods B2B Server. Both of these tasks wait for active services to complete before performing the requested shutdown operation. If a Get message handler is running with Wait Indefinitely, these tasks will not finish until that message handler receives a message. For additional information about the effect of this option on the shutdown process, see Stopping the MQSeries on page 68. Note: An empty queue is an expected condition that does not raise an exception at run time. If a message handler finds no messages in the queue, it completes normally, without returning a message. This is true only when you have selected the Wait for or No Wait option. 8. In the Selector Option field, specify whether the message handler is configured to accept a Message Selector to selectively retrieve the next message from a queue that matches some specific criteria, or whether it does not accept a Message Selector, thereby accepting any messages on the queue. See Message Selector Support for Get and Listen Message Handlers on page 55 for more information. 9. Complete the following Connection Management fields. For additional information about connection pooling, see Connection Pool on page 56. In this field Connection Type Specify Whether the message handler will use transaction semantics. See Transactional versus Nontransactional Message Handlers on page 53 for more 46 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

47 Building Message Handlers that Get Messages from a Queue In this field Minimum Connections Maximum Connections Inactive Lifetime Specify information. Non-Transacted Will not use transactional semantics. Transactional Will use transactional semantics. The minimum number of connections you want webmethods B2B to maintain in the connection pool. You may set this value to 0. The maximum number of connections you want webmethods B2B to maintain in the connection pool. You must set this to a value greater than 0. The length of time, in milliseconds, that an inactive connection can remain in the pool. 10. Click Continue. The B2B Server Administrator builds a message handler using the parameters you have specified. The Message Handler List Screen is re-displayed, showing the new message handler. Notice that a new message handler is created in a disabled state, as indicated by the red icon in the Enabled column. (A green icon indicates the enabled state.) 11. To enable the message handler, click on the red icon and then click OK in the pop-up verification screen. The icon should change to green. Using a Get Message Handler After you create a Get message handler, you can invoke it from a B2B service or a client application. Inputs to the Get Message Handler You do not pass any inputs to a non-transactional Get message handler when you invoke it unless you have set up Message Selectors. However, if the message handler is transactional, it automatically passes the connectionid parameter. See Transactional versus Non-transactional Message Handlers on page 53 for more information about connectionid. If you view the Get message handler with B2B Integrator, you will see a number of input parameters whose values are already set. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

48 CHAPTER 5 Building Message Handlers These parameters are set when you build the message handler and should not be modified with the B2B Integrator or altered at run time These parameters contain addressing information and other operational details that you specified when you created the message handler. They are displayed in the B2B Integrator for troubleshooting and informational purposes only. Do not edit these values with B2B Integrator or modify them at run time. If you need to change these values, you must use the B2B Server Administrator. See Editing Message Handlers on page 70 for more information. Outputs from the Get Message Handler When a Get message handler executes, it returns a record (a Values object) named message. The messagebody element within message contains the payload. Depending on the type of JMS message in the payload, messagebody will be one of the following data types. (The MQSeries Adapter automatically converts the payload to one of these types when it receives a message.) If payload is message type ObjectMessage messagebody will contain A Values object if ObjectMessage contains a Values object -- OR webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

49 Building Message Handlers that Get Messages from a Queue If payload is message type MapMessage TextMessage messagebody will contain A Serializable Java object if ObjectMessage is not a Values object A Values object A String BytesMessage A byte [ ] Caution: The Get message handler cannot accept a JMS StreamMessage type. If it receives this type of message at run time, an exception will occur. If the queue is empty, message is not returned. Your program should test for the presence of message to determine whether or not a message was actually received. Caution: Once a message is successfully retrieved by Get, the MQSeries Adapter automatically sends an acknowledgement to the MQSeries queue manager and the message is removed from the queue. To ensure the message is not dropped, consider developing a service that persists the message so that it can be recovered in the event of a system failure. Besides messagebody, message contains the following elements. message Element Data Type Description messageid String A unique identifier that MQSeries assigns to the message. timestamp String The date and time that this message was originally placed in the queue. This value is assigned by MQSeries. correlationid String The correlation ID that was assigned to this message by the application that put the message in the queue. In a request/response scenario, correlationid typically matches the messageid of the request message. targetqueuename String The name of the queue from which this message was retrieved. deliverymode String The delivery mode assigned to this message by MQSeries. Will be one of the following: 1 Was not persisted 2 Was persisted -1 Used queue default priority String The priority assigned to this message by MQSeries. Will be a value from 0-9, where 9 indicates the highest priority. expiration String A timestamp indicating when this message was scheduled to expire. For a complete description of the Get message handler specification, see wm.queue.runtime:get on page 104. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

50 CHAPTER 5 Building Message Handlers Error Handling If the Get service does not execute successfully, it returns the following elements in the Values object: Element Name Type Description $error String The Java error message $errortype String The name of a Java exception class Common reasons for the Get message handler to return an error are: C It cannot locate the server settings specified in the connfac parameter. C It cannot locate the set of queue parameters specified in queue. C webmethods B2B cannot establish a connection to MQSeries. C The specified queue does not exist or is currently unavailable. C The connection between webmethods and MQSeries is dropped. Invoking a Get Message Handler from a Flow Service To invoke the Get message handler from a flow service, open the flow service with B2B Integrator and insert an INVOKE operation that calls the message handler. Use the Pipeline Editor to map the contents of messagebody (in message) to a variable in the pipeline. Caution: Message handlers are stored in the msghandlers:mqseries folder within the package in which they were created. In the following example, the flow step retrieves messages from the queue and inserts them into a database. Note that the message handler is a member of a REPEAT operation that executes until the queue is empty. 50 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

51 Building Message Handlers that Get Messages from a Queue Example of a flow service that invokes a Get message handler This flow retrieves a message from a queue and then maps the message (contained in messagebody) to a variable that will be used later in the flow Invoking a Get Message Handler from a Java Service The following code sample shows a very simple Java service that invokes the Get message handler and processes the returned message. /** Demonstrates receiving a Vector from a message queue and converting it to a String array. If the message body contains a Vector, each element is added to a String array. The array is placed into the pipeline with a name of "list". If message or message body are empty, or if message body is not a Vector, the service exits, preserving the pipeline. */ public final static Values receiverequestlist( Values in ) { Values out = in; try { Service.doInvoke( "msghandlers.mqseries", "getlistfrompartner", out ); } catch( Exception e ) { Service.throwError( e ); } Values msg = (Values)out.get( "message" ); if( msg == null ) { return out; } Object body = msg.get( "messagebody" ); webmethods B2B Adapter: MQSeries Edition User Guide VERSION

52 CHAPTER 5 Building Message Handlers Vector msgcontent = new Vector(); if( body instanceof Vector ) { msgcontent = (Vector)body; } else { return out; } if( msgcontent == null ) { return out; } String[] msgitems = new String[ msgcontent.size() ]; Object o = null; int i=0; for( Enumeration enum = msgcontent.elements(); enum.hasmoreelements(); ) { o = enum.nextelement(); if( o instanceof String ) { msgitems[ i ] = (String)o; i++; } } out.put( "list", msgitems ); } return out; 52 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

53 Transactional versus Non-transactional Message Handlers Transactional versus Non-transactional Message Handlers You can designate any message handler to be either transactional or nontransactional. A non-transactional message handler is stateless. It performs a single request as an autonomous unit of work. A non-transactional Get or Listen message handler removes each message from the MQSeries queue immediately after it processes the message. In the event of a message handler failure, messages can be lost unless you post every message to a persistent data store before attempting to process the messages. Even this approach leaves some window of opportunity for message to be lost while attempting to store the messages. A transactional message handler can control Logical Unit of Work (LUW) processing by using MQSeries Syncpoint features. That is, you group one or more requests into a single logical unit of work. You can control these requests within a given LUW by using predefined commit and rollback services. A transactional message handler removes any messages received within an LUW after the LUW is committed. If a rollback is issued, all messages received within the LUW are placed back into the queue and made available to satisfy the next Get or Listen request. To support transactional message handlers, the MQSeries Adapter includes the following: C C An option called Transactional, which you select when you create a message handler. The connectionid parameter. C When you select the Transactional option, the MQSeries Adapter adds the connectionid parameter to the message handler s input and output specifications. If the value of connectionid is not specified on the first invocation of the message handler, the message handler acquires a new connection and returns the value of connectionid. This connectionid must be used on all subsequent service invocations in order to group those invocations into a logical unit of work. A single connectionid parameter can be shared by a Get (or Listen)/Put message handler pair to group both inbound and outbound messages into a single logical unit of work. The commit, rollback, and closeconnection services. You use these services to ensure the data integrity of a logical unit of work. Each service has a single input parameter (connectionid) and performs the requested function. The closeconnection service should be the last service invoked when the message handler is finished with the connection. If a transacted connection is not explicitly closed by the closeconnection service, it will eventually be closed by the connection manager once it has exceeded its configured inactivity time, and an implicit Rollback occurs before closing the connection. See webmethods B2B Adapter: MQSeries Edition User Guide VERSION

54 CHAPTER 5 Building Message Handlers wm.queue.runtime:commit on page 104, on page 108, and wm.queue.runtime:closeconnection on page 104 for more information. Example Transactional Put Message Handler In this example, a Put flow service named invoke_put_piqa_1_trans invokes the transactional Put message handler put_piqa_1_trans to put records into an MQSeries queue. Specifically, this service performs the following actions: C Loops over an array. C C C Invokes the transactional Put message handler put_piqa_1_trans, which puts the records into an MQSeries queue. Invokes the predefined service commit (which is located in the WmQueue package) to commit a logical unit of work. Invokes the predefined service closeconnection (which is located in the WmQueue package) to close and free the connection associated with the message handler. 54 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

55 Message Selector Support for Get and Listen Message Handlers Message Selector Support for Get and Listen Message Handlers Message Selectors enable you to selectively retrieve the next message from a queue that matches some specific criteria. This functionality is used by the Request/Reply processing style that is prominent in many MQSeries designs. You can configure the WmQueue Get and Listen message handlers to accept Message Selectors. For Get message handlers, you can specify the Message Selector data values at configuration time or at run time. For Listen message handlers, you can specify the Message Selector data values only at configuration time. If Message Selector values are present in the pipeline when a Get message handler is invoked, these values will override the configured values. The following WmQueue header fields are exposed as Message Selector fields: C C C messageid and correlationid Use these fields to assign string values to select messages that match the specified data exactly. DeliveryMode Use this field to specify whether the selector should filter on Persistent (value of 2) or Non-Persistent (value of 1) messages. Priority Use this field to filter messages in a variety of ways. For example, you can specify a single value to compare with the Priority of the message and set that comparison to check for a message with a priority that is equal to, greater than, or less than the specified value. You may also specify a combination of Greater than and Less than priority selector fields that may be used to select messages with priorities within ranges of values. If the Greater than selector values is less than the Less than selector value, only message with priorities between the 2 values will be selected. For example, Greater than 2 and Less than 6 will select message with priority 3,4 or 5. If the Greater than value is greater than the Less than selector value, the selector will select message that fall outside the range. For example Greater than 6 or Less than 2, would select messages with priority 0,1,7,8 or 9. Caution: When you supply multiple fields with values, the Selector fields work in an and relationship. For example, if you specify correlationid=id: along with Priority=3, only a message with that specific correlationid and a priority of 3 would be selected. Caution: The Timestamp message header field was to be exposed with similar capabilities as the priority for range setting, but the current IBM JMS implementation (v1.0) does not properly support the JMSTimestamp field for a selector, so we chose not to expose Timestamp as a Selector field. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

56 CHAPTER 5 Building Message Handlers Connection Pools A connection is an object with attributes that identify a server setting and a user ID and password that enable you to connect to that server setting. A connection pool is a collection of connection objects with the same set of attributes. The MQSeries Adapter maintains connection pools in memory. Connection pools improve performance by enabling message handlers to reuse open connections instead of opening new connections. All non-transactional Get and Put message handlers use connection pooling. You cannot disable this feature. Each transactional Get or Put message handler will use a single non-pooled connection identified by its connectionid parameter. Each Listen message handler (transactional or nontransactional) will use its own non-pooled connection. For example, message handlers with the server setting MQS_Marimba, user ID MktgBuyer, and password starfish81, use one connection pool, and message handlers with the server setting MQS_Limelight, user ID AcctRecon, and password c1a1t1, use another. Connection pools are based on unique combinations of connection attributes Pooled connections for... Server Settings=MQS_Marimba User ID=MktgBuyer Password=starfish81 Pooled connections for... Server Settings=MQS_Marimba User ID=Supervisor Password=ylujth4 Pooled connections for... Server Settings=MQS_Limelight User ID=AcctRecon Password=c1a1t1 Run-time Behavior of Connection Pools At run time, the MQSeries Adapter creates a pool for each unique combination of connection attributes. Connection pools expand and contract within limits that you 56 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

57 Connection Pools specify, based on the demand for its connection objects. When a connection pool is established, it remains in memory until you restart the B2B server or reload the WmQueue package. When a message handler requests a connection, the MQSeries Adapter tries to obtain one from a connection pool as follows: C C C The MQSeries Adapter checks to see whether a connection pool exists that matches the message handler s connection attributes. If a pool does not exist that is, if this particular set of attributes has never been requested the MQSeries Adapter generates a pool and initializes it with the minimum number of connection objects specified. Once the pool is established, the message handler uses one of the objects in the pool to connect to MQSeries. If a pool exists, the message handler uses one of the inactive objects in the pool to connect to MQSeries. If all of the connections are in use (active), the MQSeries Adapter checks whether the pool has created its maximum number of connections. If the maximum number of connections has not been created, the Adapter adds another object to the pool for the message handler to use. If the maximum number of connections has already been created, the message handler waits until one of the pooled connections becomes available. Periodically, the MQSeries Adapter inspects the pool and removes inactive connections that have exceeded the expiration period that you specified. Connection Pool Parameters When you build a message handler, you specify the following connection pool parameters: Parameter Minimum Connections Maximum Connections Inactive Lifetime Description Specifies the minimum number of connection objects that must remain in the pool at all times. When the MQSeries Adapter initially creates the pool, it builds this number of connections. Minimum Connections must be greater than or equal to 0. Specifies the maximum number of connection objects that can exist in the pool. Once the maximum number is reached, subsequent message handlers will reuse inactive connections in the pool or, if all connections are in use, wait for one to free up. Maximum Connections must be greater than or equal to 1. Specifies the length of time in milliseconds that an inactive connection object can remain in the pool before it is cleared and removed from the pool. For example, to specify 10 seconds, specify The MQSeries Adapter periodically examines the connection pools and removes inactive connection objects that exceed this limit. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

58 CHAPTER 5 Building Message Handlers (The Adapter will never violate the Minimum Connections value. A minimum number of connections remain in the pool regardless of how long they are inactive.) The message handler that causes the MQSeries Adapter to establish a connection pool sets these parameters initially. Subsequent message handlers that use the same pool can increase these values, but not reduce them. You should experiment with these parameters to see which values provide the best performance in your environment. Settings that are too high will consume computing resources unnecessarily. Settings that are too low may degrade performance by forcing message handlers to wait for a connection object. You will need to adjust these values under varying client loads to determine the optimal values. Caution: If you change Minimum Connections, Maximum Connections, and Inactive Lifetime parameters in one message handler, make sure to change other all the other message handlers that use the same pool (i.e. all other message handlers with the same server setting, user ID and password values.) If you reduce any of these values, you will need to restart the server or reload the WmQueue package to put those values into effect. (The pool manager ignores Minimum Connections, Maximum Connections, and Inactive Lifetime values that are lower than those already in use by the pool.) Example Connection Pool Parameter Settings A message handler establishes a connection pool. The following shows the values for the connection pool parameters that were specified for the message handler and the connection pool values that the connection pool uses. Because this is the first message handler that establishes the connection pool, these values are the same. Message Handler Connection Pool Parameters Connection Pool Values Minimum Connections 3 Minimum Connections 3 Maximum Connections 10 Maximum Connections 10 Inactive Lifetime Inactive Lifetime Another message handler uses this connection pool. The following shows the values for the connection pool parameters for this message handler and the connection pool values that the connection pool uses. Message Handler Connection Pool Parameters Connection Pool Values Minimum Connections 5 Minimum Connections 5 Maximum Connections 10 Maximum Connections 10 Inactive Lifetime Inactive Lifetime Because the Minimum Connections and Inactive Lifetime values are higher for this message handler than what the connection pool was previously using, the MQSeries Adapter increases these values for the connection pool. The Maximum Connections value remains the same because its value is lower than the value the connection pool is currently using. 58 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

59 Building Services that Listen to a Queue Building Services that Listen to a Queue The Listen message handler is a specialized form of the Get message handler. A Listen message handler continually monitors a queue for messages. When a message appears, the Listen message handler fetches the message and passes it to a B2B service that you specify. Unlike the Put and Get message handlers, you never invoke a Listen message handler directly from a B2B service or client. Instead, Listen is like a real-time process that you enable or disable from the B2B Server Administrator. Caution: Before you create the Listen message handler, the message service and the exception service must be ready for use. Creation of the Listen Message Handler definition will fail with the error message Input field messageservice is not found or invalid or Input field exceptionservice is not found or invalid. To use the Listen message handler, you must create the following services: C C A service that executes when the message handler retrieves a message successfully. Usually, this service will process the message in some way. Such a service is known as the message service. A service that executes if the message handler experiences an error while retrieving a message for example, if it can t connect to MQSeries or the MQSeries administrator has closed the queue. Such a service is known as an exception service. Creating a Message Service A message service is a B2B service that you create to process the messages retrieved by the Listen message handler. You can create any type of B2B service (a flow service, a Java service, a C/C++ service) to act as the message service. When the Listen message handler invokes your service, it passes a variable named message in the Values object. message is a Values object containing the result of the Get operation that Listen executed to retrieve the message from the queue. For a description of the elements in message, see Outputs from the Get Message Handler on page 48. If the Listen message handler is transactional, it also passes a variable named connectionid in the Values object. The following example shows a message service that extracts messagebody and inserts it into a database. /** Provides services for processing messages and exceptions received from the WmQueue listen service. */ public final class messageprocess { /** Handles messages for a queue listener. The message is passed in the parameter "in". This service Expects messsagebody to be a String. If it is, the webmethods B2B Adapter: MQSeries Edition User Guide VERSION

60 CHAPTER 5 Building Message Handlers entire message is written to "requests" table. If not, the message is written to "requesterrors" table. These tables have a column for each field in the message. Assumes that a connection to the database has already been made. listen service does not expect any output, so this service returns a null Values object. */ public final static Values onmessage( Values in ) { // --- <<B2B-START(onMessage)>> --- // [i] object:0:required message Values msg = (Values)in.get( "message" ); Values args = new Values(); args.put( "$dbalias", "orderfulfill" ); args.put( "$dbrollbackonfail", "false" ); args.put( "$data", msg ); if( msg.get( "messagebody" ) instanceof String ) { args.put( "$dbtable", "requests" ); try { Service.doInvoke("pub.db", "insert", args ); } catch( Exception e ) { Service.throwError( e ); } } else { args.put( "$dbtable", "requesterrors" ); } try { Service.doInvoke("pub.db", "insert", args ); Service.throwError( "Body of incoming request is not a String: " + in.getstring( "messageid" ) ); } catch( Exception e ) { Service.throwError( e ); } } // --- <<B2B-END>> --- return null; Error Handling A message service should incorporate error-handling procedures in case it cannot process the message successfully. Note the following: C C C When a transactional Listen message handler receives a message that causes an exception and shuts down the message handler, that message is rolled back into the queue. Before re-starting the message handler, you should ensure that the erroneous message is removed from the queue, or else it will fail again. In the event of a system failure, be aware that a transactional Listen message handler will roll back any uncommitted messages. If the message service itself fails (causes an exception), the Listen message handler logs the error in the server s error log and then shuts itself down. 60 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

61 Building Services that Listen to a Queue Creating Exception Services An exception service is a B2B service that you create to respond to exceptions that occur when Listen attempts to get a message from a queue (e.g., Listen cannot connect to the MQSeries server or the specified queue name is invalid). If Listen experiences an exception while getting a message, it logs the error in the server s error log, executes the exception service, and then shuts itself down. Listen passes the following information to the exception service in the Values object: message Element Data Type Description exception String The text of the exception message received by the Listen message handler. Although you must provide an exception service, Listen does not impose any requirements or constraints on what that service does. Your service can take whatever level of action is appropriate for your site. For example, you may simply want to alert a particular administrator based on the value in exception. The following example shows an exception service that logs the error into an errors database. /** Handles exceptions for a queue listener. The exception is passed from in the parameter "in". The exception is logged to the "communicationerrors" table. a connection to the database has already been made. Assumes that listen does not expect any output from this service, so it returns a null Values object. */ public final static Values onexception( Values in ) { // --- <<B2B-START(onException)>> --- // [i] object:0:required exception Values args = new Values(); args.put( "$dbalias", "orderfulfill" ); args.put( "$dbrollbackonfail", "false" ); args.put( "$dbtable", "communicationerrors" ); args.put( "$data", in.get( "exception" ) ); try { Service.doInvoke( "pub.db", "insert", args ); } catch( Exception e ) { Service.throwError( e ); } } // --- <<B2B-END>> --- return null; Creating a Listen Message Handler Use the procedure below to create a Listen message handler. Before you begin, verify that: webmethods B2B Adapter: MQSeries Edition User Guide VERSION

62 CHAPTER 5 Building Message Handlers C C C C You have defined the server settings for the queue manager with which the message handler will interact, as described in Chapter 3, Defining Server Settings for MQSeries Servers. You have created Message Destinations that identify your MQSeries queues, as described in Chapter 5, Defining MQSeries Message Destinations. The package in which you want to install the message handler exists. See the webmethods B2B Server Administrator s Guide for information about creating packages. You know the names of the message service and the exception service this message handler will use. To build a message handler that listens to a queue 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Message Handlers. 3. From the Server Settings list, select the server settings that define how this service will connect to the queue manager at run time. Caution: If the screen displays the following error message: Or the Server Settings list does not display the server you want to use, you must create server settings for your queue manager. See Defining Server Settings for MQSeries on page 15 for the procedure to do this. 4. Click Add Message Handler. The destination queues that you defined should be displayed. 5. In the list of queues, locate the queue to which you want this message handler to deliver messages and click in that row. A screen is displayed, showing parameters for the message handler. 6. Complete the following fields: In this field Specify Package Service Name The package in which you want this service saved. A unique, unqualified name for the service. (Note that message handlers are automatically stored in the msghandlers:mqseries folder. Do not move them from this location.) 62 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

63 Building Services that Listen to a Queue 7. In the Inbound Service Details section, select Listen and complete the following fields: In this field Message service Specify The fully qualified name of the B2B service that this message handler will invoke after it gets a message from the queue. Example: msgs.fncl.gl:post_glitem Exception service The fully qualified name of the B2B service that this message handler will invoke if an exception occurs while it is getting a message from the queue. Example: msgs.oper:handleexceptions_glitem Shutdown Interval The maximum amount of time this message handler will remain active if you disable it with the B2B Server Administrator. Type an integer (greater than or equal to 0), representing the shutdown interval, in minutes. For information about how MQSeries Adapter uses this value, see Enabling/Disabling a Listen Message Handler on page In the Selector Option field, specify whether the message handler is configured to accept a Message Selector to selectively retrieve the next message from a queue that matches some specific criteria, or whether it does not accept a Message Selector, thereby accepting any messages on the queue. See Message Selector Support for Get and Listen Message Handlers on page 55 for more information. 12. Select an option for the Connection Type field as follows: In this field Connection Type Specify Whether the message handler will use transaction semantics. See Transactional versus Nontransactional Message Handlers on page 53 for more information. Non-Transacted Will not use transactional semantics. Transactional Will use transactional semantics. 13. Click Continue. The B2B Server Administrator builds a message handler using the parameters you have specified. The Message Handler List Screen is re-displayed, showing the new message handler. Notice that a new message handler is created in a disabled state, as indicated by the red icon in the Enabled column. (A green icon indicates the enabled state.) webmethods B2B Adapter: MQSeries Edition User Guide VERSION

64 CHAPTER 5 Building Message Handlers 14. To enable the message handler, click on the red icon and then click OK in the pop-up verification screen. The icon should change to green. Caution: Before you create the Listen message handler, the message service and the exception service must be ready for use. Creation of the Listen Message Handler definition will fail with the error message Input field `messageservice` is not found or invalid or Input field `exceptionservice` is not found or invalid. Enabling/Disabling a Listen Message Handler The only way to invoke a Listen message handler is to activate (enable) it from the B2B Server Administrator, as described in Creating a Listen Message Handler on page 61. Once you activate a Listen message handler, it automatically begins monitoring the specified queue and fetching messages from it. This behavior continues until you deactivate (disable) the message handler. Disabling the Message Handler You can disable the Listen message handler to stop it from fetching messages. When you disable a message handler, it does not immediately become deactivated it waits for one of the following events to occur before shutting down: It receives a message. - OR - The period of time specified in the message handler s Shutdown Interval elapses. The Shutdown Interval is a parameter you specify when you create a Listen message handler. Internally, this parameter specifies the length of time the Listen message handler waits for a message to arrive before issuing another Get request i.e., if Listen does not receive a message in the specified interval, the open Get process ends and a new one begins. However, operationally, this value determines the maximum length of time that the Listen message handler remains active after you disable it. Besides the case in which you explicitly disable a Listen message handler, Shutdown Interval affects reloading the WmQueue package and shutting down or restarting the webmethods B2B Server. Neither activity completes until all active services are finished. If Listen message handlers are active, they can be delayed as long as the longest Shutdown Interval. See Stopping the MQSeries Adapter on page 68 for more information about Listen and the server shutdown process. To disable a Listen message handler 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Message Handlers. 64 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

65 Building Services that Listen to a Queue 3. From the Server Settings list, select the server settings used by the message handler. 4. Locate the Listen message handler in the list, and then click the green icon in the Enabled column. The icon color will switch to red, indicating that the message handler has been disabled. Caution: Remember that the message handler is not actually disabled until it receives a message or its Shutdown Interval elapses, whichever occurs first. Also, while the message handler is being disabled you cannot perform any activities using the Queuing menu. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

66

67 CHAPTER Administration Starting the MQSeries Adapter...68 Stopping the MQSeries Adapter...68 Defining Server Settings...68 Editing Server Settings...69 Deleting Server Settings...69 Testing Server Settings...70 Defining Message Destinations...71 Viewing a List of Message Destinations...71 Defining Message Handlers...70 Editing Message Handlers...70 Deleting Message Handlers...71 Defining Message Destinations...71 Viewing a List of Message Destinations...71 Editing Message Destinations...72 webmethods B2B Adapter: MQSeries Edition User Guide VERSION

68 CHAPTER 6 Administration Starting the MQSeries Adapter The MQSeries Adapter loads automatically when you start the webmethods B2B Server. To verify that the MQSeries Adapter is available for use, use the B2B Server Administrator to display the Packages screen and verify that the MQSeries and WmQueue packages are loaded and enabled. See the webmethods B2B Server Administrator s Guide for information about loading and enabling packages. Stopping the MQSeries Adapter You can shut off access to the MQSeries Adapter by shutting down the webmethods B2B Server or by disabling the MQSeries package. See the webmethods B2B Server Administrator s Guide for the procedures to do this. Be aware that when you unload the WmQueue package, or when you restart or shut down the webmethods B2B Server, the server will wait for active Get, Put, and Listen operations to complete. If you have assigned an indefinite or lengthy waiting period to a Get service, the server will wait until that service retrieves a message or until the wait period elapses, whichever occurs first. Also, if you have assigned a lengthy Shutdown Interval to a Listen service the server will wait until that service retrieves a message or until the Shutdown Interval elapses, whichever occurs first. If the service is programmed to wait indefinitely, you may need to force the server to terminate from the console (i.e., use CTRL+C under Windows or kill process-id under Unix). Defining Server Settings For each MQSeries queue manager with which you will use webmethods B2B, you must define a set of server settings. Server settings are used to create connection factories objects that JMS uses at run time to establish a connection with MQSeries. You must create at least one set of server settings for each MQSeries queue manager that you will use with webmethods B2B. You may create more than one set per queue manager if your message handlers require different connection profiles (e.g., they access the same queue manager, but execute different user exits.) For more information about server settings, including procedures for creating them, see Chapter 3, Defining Server Settings for MQSeries Servers. 68 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

69 Editing Server Settings Editing Server Settings Use the following procedure to view or edit server settings that have been defined on your webmethods B2B Server. Caution: Make sure your MQSeries server is available before you start the following procedure. As part of this procedure, the MQSeries Adapter connects to the MQSeries server to verify that the revised parameters are valid. If a connection cannot be made, the MQSeries Adapter will not save your changes. To view or edit the connection settings for an MQSeries Server 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Server Settings. 3. Click the name of the server settings you want to view or edit. 4. If you want to edit these settings, click Edit. 5. On the Edit Server Settings page, make the changes you need and then click Save. If you receive an error message when you click Save, verify that all settings on the Edit Server Settings page are correct. Deleting Server Settings Use the following procedure to delete a set of server settings that reside on the webmethods server. Caution: Before you delete a server setting, you must delete all its associated message handlers. To delete server settings 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Server Settings. 3. Locate the name of the server settings you want to delete and click the under the Delete column in its row. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

70 CHAPTER 6 Administration Testing Server Settings Use the following procedure to test a set of server settings that reside on the webmethods server. To test server settings 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Server Settings. 3. Locate the name of the server settings you want to test in the Test Connection column and click to establish a connection. Defining Message Handlers For information about defining message handlers, see the following: To define a Put message handler Get message handler Listen message handler See Building Message Handlers that Put Messages in a Queue on page 37. Building Message Handlers that Get Messages from a Queue on page 45. Building Services that Listen to a Queue on page 59. Editing Message Handlers Use the following procedure to view or edit parameters of a message handler. To view or edit a message handler 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Message Handlers. 3. From the Server Settings list, select the server settings used by the message handler whose parameters you want to view or edit. 4. Click a message handler name listed in the Service column. 5. Click the Edit button. 70 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

71 Deleting Message Handlers 6. Make your changes. 7. Click the Submit button. Deleting Message Handlers Use the following procedure to delete a message handler. To delete a message handler 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Message Handlers. 3. From the Server Settings list, select the server settings used by the message handler that you want to delete. 4. Locate the message handler in the displayed list and click in the Delete column for that row. Defining Message Destinations For information about defining message destinations, see Defining MQSeries Message Destinations on page 24. Viewing a List of Message Destinations Use the following procedure to display the names of all the queues that webmethods B2B knows about for a particular MQSeries queue manager. To view a list of queue names 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Destinations. 3. Select MQSeries in the Provider field, if it is not already selected. 4. Click the Add Destination button. The Create Message Destination screen is displayed. 5. In the Server Settings field, select the server setting whose queue names you want to view. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

72 CHAPTER 6 Administration 6. To display a complete list of queue names, type * in the Enter search pattern to find field and click Find. 7. Select a queue to add by clicking on its name or on its corresponding Add button. A screen showing queue settings is displayed. Caution: To display a list of queue names matching certain criteria, type a character pattern and click Find. You may use the following wildcard characters in your pattern:? matches any single character * matches any string of characters Example: *FNCL* This example would produce a list of all queues containing the string FNCL anywhere in their names. Note that character patterns are case-sensitive for example, FNCL will not match fncl or Fncl. Caution: If the list seems incomplete, it may be out of date. You may need to import an updated list of queue names into B2B. See Importing the Names of MQSeries Queues on page 29 for the procedure to do this. Editing Message Destinations Use the following procedure to edit the settings of a message destination. To edit a message destination s settings 1. Start the B2B Server Administrator. See the webmethods B2B Server Administrator s Guide for the procedure to do this. 2. In the Messaging menu in the navigation area, select Destinations. 3. In the Destination Alias column, click the name of the message destination that you want to view. The Destination Settings screen displayed. 4. Click the Edit button. The Edit Message Destination screen is displayed. 5. Make your changes. 6. Click the Submit button. Caution: Changes that you make to a set of queue parameters are applied to all message handlers that use that set of queue parameters. 72 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

73 APPENDIX Screen Descriptions Create Message Destination...74 Create Message Destination (Locate a Queue)...78 Create Message Handler (Inbound Service Parameters)...80 Create Message Handler (Outbound Service Parameters)...84 Create Server Settings...85 Destination Settings (View)...88 Edit Message Destination...89 Edit Server Settings...90 Message Destination List (View)...91 Message Handler List...92 Message Handling Service (Edit)...94 Message Handling Service (View)...96 Message Server Settings List...98 Provider Administration...99 Server Settings (View) webmethods B2B Adapter: MQSeries Edition User Guide VERSION

74 APPENDIX A Screen Descriptions Create Message Destination Use this screen to define the set of queue parameters that message handlers will use. To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Destinations. 2. Select MQSeries in the Provider field, if it is not already selected. 3. Click the Add Destination button. The Create Message Destination screen is displayed. 4. In the Server Settings field, select a server setting. 5. Specify a queue name by typing its name in the Destination name to add field and clicking Add. MQSeries Queue Settings The fields in this section specify information about the queue and how a Put operation interacts with it. MQSeries Queue MGR Name Displays the name of the queue s manager. MQSeries Queue Name Displays the name of the queue for which you are creating a message handler. 74 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

75 Create Message Destination Alias Name Specifies a unique name for the set of queue properties you are about to create. Although it is not required, we suggest that you incorporate the name of the queue in your alias. This will make it easy for you and others to determine which queue these parameters belong to. For example, if your queue name is fnclco01, and you are creating a set of properties to deliver high-priority messages, you might specify an alias like fnclco01_pri9. Description Specifies a descriptive comment about this set of queue properties. This field is optional. Message Time To Live Specifies the length of time the delivered message is allowed to stay in the queue before the queue manager can discard it. Select one of the following: Setting Unlimited Limited Allow Application to set Lifetime Description The message can remain in the queue indefinitely. The message is deleted after the period of time that you specify in the milliseconds text box. For example, to specify 10 seconds, set Limited to The run-time value of the timetolive parameter determines the message s expiration period. Priority Specifies the priority you want assigned to the delivered message. Select one of the following: Setting Use Queue Default Priority Allow Application to set Priority Description The message assumes the queue s default priority value. The message is delivered with the priority you specify in the Priority text box. Valid priority values are integers 0 9, where 9 is the highest priority. The run-time value of the priority value in the message header sets the message s priority. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

76 APPENDIX A Screen Descriptions Delivery Mode Specifies whether or not messages delivered to this queue are to be logged (persisted) on the MQSeries server in such a way that they can be recovered if the server is restarted. Select one of the following: Setting Use Queue Default Not Persistent Persistent Allow Application to set Persistence Description Messages are logged or not logged according to the queue s default behavior. Messages are not logged to persistent storage. Messages are logged to persistent storage so that they can be recovered if the MQSeries server fails and is restarted. The run-time value of the deliverymode parameter determines whether a message delivered by this service is persisted or not. Target Client Specifies whether or not the message will be consumed by a Java Messaging Service (JMS) client application. This setting determines whether the message is sent in JMS or MQSeries message format. Select one of the following: Setting JMS Compliant Client Non-JMS Compliant Client Description The messages will be consumed by a JMS client application. When you select this option, messages are sent to the queue in JMS message format. Do not enable this option unless all consumers of the messages in this queue are JMS clients. The messages will be consumed by a non-jms, MQSeries client application. When you select this option, messages are sent to the queue in standard, MQSeries format. Select this option if any consumer of the message in this queue is a non-jms application. CCSID The Coded Character Set Identifier used to represent character data within the payload of messages sent to this Destination. The CCSID value specified here will affect the CCSID value that is placed into the MQSeries MQMD message descriptor, the CCSID= portion of the MQRFH2 header for JMS target clients, and possibly the actual data contained within the msgbody. If the Payload of the message is a text string, the Destination CCSID value is used to encode the data within the msgbody as it is converted from a Java string 76 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

77 Create Message Destination and placed into the msgbody. If the payload of the message is a byte array, the CCSID value should be set to indicate the encoding scheme used to represent any character data contained within the byte array. However, no data conversion occurs when the byte array is placed into the msgbody. For non-jms target clients, the CCSID value specified here will be placed directly into the MQMD CCSID field. If 0 is specified as the CCSID on the Destination, 1208 (the UTF8 code page) is placed into the MQMD. For JMS target clients, the CCSID value specified here will be placed into the CCSID= portion of the MQRFH2 JMS Header, and the CCSID of the Queue Manger is placed into the MQMD. If 0 is specified as the CCSID on the Destination, the CCSID of the Queue Manager is placed into the MQMD and the CCSID= portion is omitted from the MQRFH2 header. Note: The CCSID value that you specify as a remote server setting is only used when establishing the connection to the remote Queue Manager. See Create Server Settings on page 85 for more information. Numeric Encoding fields The fields in this section provide information about the way numeric values in the message are treated. Native Specifies the encoding scheme into which numeric values in application data must be converted before the message is delivered to the queue. This value must match the numeric-encoding scheme for which the queue is configured. See your MQSeries Administrator for the correct setting. Setting Disable Enable Description Select Disable if you do not want numeric values to be converted to another encoding scheme. Select Enable if the queue is configured for System/390 numeric encoding. Integer Specifies the byte order used to represent multi-byte integer values in the application data. Specify only when you select Disable in the Native field. Select one of the following: Setting Normal Reversed Description Integers are in big-endian format (the most significant byte has the lowest address). Integers are in little-endian format (the least significant byte has the lowest address). webmethods B2B Adapter: MQSeries Edition User Guide VERSION

78 APPENDIX A Screen Descriptions Decimal Specifies the format used for packed decimal values. Specify only when you select Disable in the Native field. Select one of the following: Setting Normal Reversed Description Packed decimal values are in big-endian format (as used by System/390). Packed decimal values are in little-endian format. Float Specifies the format in which floating-point values are represented. Specify only when you select Disable in the Native field. Select one of the following: Setting IEEE Normal IEEE Reversed System/390 Description Floats are in big-endian IEEE format. Floats are in little-endian IEEE format (as used by PCs). Floats are in System/390 format. Continue Opens the Message Destination List screen, which displays the new destination in the list. Cancel Cancels your request to create a new message handler and returns you to the Message Destination List screen. Create Message Destination (Locate a Queue) Use this screen to locate a queue for the Message Destination that you are creating. To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Destinations. 2. Select MQSeries in the Provider field, if it is not already selected. 3. Click the Add Destination button. The Create Message Destination screen is displayed. 78 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

79 Create Message Destination (Locate a Queue) 4. In the Server Settings field, select the server setting whose queues you want to locate. Enter search pattern to find Use to specify the search criteria you want to use to locate a queue. Type a character pattern for the search. You can use the following wildcard characters in your pattern: Wildcard Matches? Any single character * Any string of characters Example: *FNCL* This example would produce a list of all queues containing the character string FNCL anywhere in their names. Note that character patterns are case-sensitive for example, FNCL will not match fncl or Fncl. Caution: If the list seems incomplete, it may be out of date. You may need to import an updated list of queue names into B2B. See Importing the Names of MQSeries Queues on page 29 for the procedure to do this. Find Opens the Create Message Destination Select Destination to Add screen that lists the results of your search. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

80 APPENDIX A Screen Descriptions Create Message Handler (Inbound Service Parameters) Use this screen to specify details about an inbound message handler you are creating. An inbound message handler is a message handler that receives messages from queues by performing either a Get or a Listen operation. 80 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

81 Create Message Handler (Inbound Service Parameters) To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Message Handlers. 2. Select an alias name for a set of server settings from the Server Settings drop-down list. A list of message handler services and their associated destination queues is displayed. 3. Click Add Message Handler. The list of destination queues is re-displayed. 4. In the list of queues, locate the queue to which you want this message handler to deliver messages and click in that row. A screen is displayed, showing the inbound service parameters for the message handler. Destination Displays the name of the queue for which you are creating a message handler. Direction Displays Inbound (Message Queue to B2B) indicating the message handler you are creating is an inbound message handler; that is, on that receives messages from queues by performing either a Get or Listen operation. Inbound Service The fields in this section specify general information about the message handler you are creating. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

82 APPENDIX A Screen Descriptions Package Specifies the package in which you want the message handler flow service to be saved. Folder Name Displays the fully-qualified folder name of the folder in which the MQSeries Adapter will place the message handler flow service. All message handlers are automatically stored in the msghandlers:mqseries folder. Do not move them from this location. Service Name Specifies the name you want to use for the message handler flow service. Specify a unique, unqualified name for the service. Inbound Service Details Specifies the type of message operation you want the message handler to perform Listen or Get. Complete the following parameters based on your selection. Setting Listen Additional Parameters When you select Listen, fill in the following fields: Message service. Specifies the name of the B2B service that this message handler will invoke after it gets a message from the queue. Type the service s fully-qualified name, for example, msgs.fncl.gl:post_glitem. Exception service. Specify the name of the B2B service that this message handler will invoke if an exception occurs while it is getting a message from the queue. Type the service s fully-qualified name, for example, msgs.oper:handleexceptions_glitem. Shutdown Interval. Specifies the maximum amount of time this message handler will remain active after it receives a request to shut down. 82 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

83 Create Message Handler (Inbound Service Parameters) Setting Explicit Get Selector Option Additional Parameters When you select Explicit Get, select one of the following to specify what you want the message handler to do if the queue is empty when it tries to retrieve a message: Wait Indefinitely. The message handler will wait until a message appears in the queue. Wait for milliseconds. The message handler will wait the period of time you specify and then returns to the calling program. No wait. The message handler immediately returns to the calling program if there are no messages in the queue. Specifies whether the message handler is configured to accept a Message Selector to selectively retrieve the next message from a queue that matches some specific criteria, or whether it does not accept a Message Selector, thereby accepting any messages on the queue. With Selector. Uses a message selector. No Selector. Does not use a message selector. Connection Management Parameters The fields in this section specify whether connection pooling will be used for this message handler. Connection Type Specifies whether the message handler uses transactional semantics. Minimum Connections Specifies the minimum number of connections you want webmethods B2B to maintain in the connection pool. Maximum Connections Specifies the maximum number of connections you want webmethods B2B to maintain in the connection pool. Inactive Lifetime Specifies the length of time, in milliseconds, that an inactive connection can remain in the pool. Continue Creates the message handler flow service using the parameters you specified. Cancel Cancels your request to create a new message handler and returns you to the list of destination queues. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

84 APPENDIX A Screen Descriptions Create Message Handler (Outbound Service Parameters) Use this screen to specify details about the outbound message handler you are creating. An outbound message handler is a message handler that sends messages to queues by performing a Put operation. To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Message Handlers. 2. Select an alias name for a set of server settings from the Server Settings drop-down list. A list of message handler services and their associated destination queues is displayed. 3. Click Add Message Handler. The list of destination queues is re-displayed. 4. In the list of queues, locate the queue to which you want this message handler to deliver messages and click in that row. A screen is displayed, showing parameters for the message handler. Destination Displays the name of the queue for which you are creating a message handler. Direction Displays Outbound (B2B to Message Queue) indicating the message handler you are creating is an outbound message handler; that is, on that sends messages to queues by performing a Put operation. Outbound Service The fields in this section specify general information about the message handler you are creating. Package Specifies the package in which you want the message handler flow service to be saved. 84 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

85 Create Server Settings Folder Name Displays the fully-qualified folder name of the folder in which the MQSeries Adapter will place the message handler flow service. All message handlers are automatically stored in the msghandlers:mqseries folder. Do not move them from this location. Service Name Specifies the name you want to use for the message handler flow service. Specify a unique, unqualified name for the service. Connection Management Parameters The fields in this section specify whether connection pooling will be used for this message handler. Connection Type Specifies whether the message handler uses transactional semantics. Minimum Connections Specifies the minimum number of connections you want webmethods B2B to maintain in the connection pool. Type a value greater than or equal to 0. Maximum Connections Specifies the maximum number of connections you want webmethods B2B to maintain in the connection pool. Type a value greater than or equal to 1. Inactive Lifetime Specifies the length of time, in milliseconds, that an inactive connection can remain in the pool. Continue Creates the message handler flow service using the parameters you specified. Cancel Cancels your request to create a new message handler and redisplays the list of destinations. Create Server Settings Use this screen to create a set of server settings. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

86 APPENDIX A Screen Descriptions To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Server Settings. 2. Click Add Server Settings. Provider Displays MQSeries, which is the message queuing provider associated with the server settings. You cannot change this value. MQSeries Server Settings The fields in this section identify the set of server settings and the MQSeries queue manager to which the server settings apply. Alias Name Specifies the name of the set of server settings. When specifying Alias Name, do not use spaces or any of the following characters: %#?&+<> *. Alias Name is case-sensitive. This field is required. Description Specifies an optional description for the set of server settings. There are no restrictions on the characters you can specify or limit to the length of the description. Queue Manager Name Specifies the name of the MQSeries queue manager to which the settings apply. Type the name of MQSeries queue manager. This field is required. 86 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

87 Create Server Settings Transport Type Specifies the location of the queue manager in relation to webmethods B2B. If the queue manager is on the same computer as webmethods B2B, select Local. If the queue manager is on another computer, select Remote. Remote Settings The fields in this section specify settings required for remote queue managers. Host Name Specifies the host name or IP address of the remote computer on which the queue manager resides. This field is required when you specify Remote for Transport Type. Port Specifies the port number that the remote queue manager uses to listen for requests. This field is optional. If you do not specify a port number, the MQSeries Adapter uses Channel Specifies the name of the MQI server-connection channel assigned to the MQSeries queue manager. This field is required when you specify Remote for Transport Type. This field is case-sensitive. CCSID Specifies the Coded Character Set ID (CCSID) of the MQSeries client. This field is optional. If you do not specify a CCSID, MQSeries does not perform any character set conversion. Note: The CCSID specified for a remote server setting is only used when establishing the connection to the remote Queue Manager. In most cases you can leave this field blank. In contrast, the CCSID used to encode the character data within the actual payload of the messages must be specified when you define a Message Destination. See Create Message Destination on page 74 for more information. Default UserID The User ID to be used to connect to the Queue Manager, if the Queue Manager is secured. These values can be overwritten at application run time. Default Password The password to be used in conjunction with the userid to connect to the Queue Manager, if the Queue Manager is secured. These values can be overwritten at application run time. User Exits The fields in this section identify user exits that are invoked by the MQSeries client at certain points during a messaging operation. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

88 APPENDIX A Screen Descriptions Receive Specifies the Java class name and initialization parameters of the receive user exit used by this set of server settings, if any. If a receive user exit is specified, MQSeries invokes the exit after it receives a message, but before control reaches the message handling service. If you want to specify a user exit, type the fully-qualified Java package and class name for the user exit in the Java Class Name column. Type the initialization parameters for the user exit in the Initialization Parameters column. These fields are optional. Send Specifies the Java class name and initialization parameters of the send user exit used by this set of server settings, if any. If a send user exit is specified, MQSeries invokes the exit after it invokes the Put operation, but before it places the message on the queue. If you want to specify a user exit, type the fully-qualified Java package and class name for the user exit in the Java Class Name column. Type the initialization parameters for the user exit in the Initialization Parameters column. These fields are optional. Security Specifies the Java class name and initialization parameters for a security user exit used by this set of server settings, if any. If you want to specify a user exit, type the fully-qualified Java package and class name for the user exit in the Java Class Name column. Type the initialization parameters for the user exit in the Initialization Parameters column. These fields are optional. Save Saves the information you specified on the screen and creates a JMS connection object for these settings with the name specified in Alias Name. Cancel Cancels the request to add the set of server settings and returns to the Message Queue Server Settings screen. Destination Settings (View) Use this screen to view a set of queue properties that you have defined for a queue. 88 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

89 Edit Message Destination To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Message Handlers. 2. From the Server Settings drop-down list, select the server settings that define the queue manager to which the queue belongs. 3. In the Destination column, click the name of the queue parameters that you want to view. See Create Message Destination on page 74 for screen field descriptions. Edit Message Destination Use this screen to modify the parameter values of a message destination queue. Caution: When you make changes to the parameters on this page, your changes affect all message handlers that use this set of queue parameters. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

90 APPENDIX A Screen Descriptions To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Destinations. 2. Select MQSeries in the Provider field, if it is not already selected. 3. In the Destination Alias column, click the name of the queue that you want to edit. The queue settings are displayed. 4. Click Edit. See Create Message Destination on page 74 for screen field descriptions. Edit Server Settings Use this screen to modify an existing set of server settings. 90 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

91 Message Destination List (View) To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Server Settings. 2. Click the alias name (in the Name column) for the server settings you want to edit. 3. Click Edit. See Create Server Settings on page 85 for screen field descriptions. Message Destination List (View) Use this screen to view a list of destinations and their settings. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

92 APPENDIX A Screen Descriptions 1. To access this screen, start the B2B Server Administrator. 2. In the Messaging menu in the navigation area, select Destinations. Provider Displays MQSeries, which is the message queuing provider associated with the server settings. You cannot change this value. Add Destination Displays the Create Message Destination screen, which enables you to define a destination. Destination Alias Displays the alias names of all message destination queues. Click a name to view details about the queue. Actual Name Displays the names of all message destination queues. Click a name to view details about the queue. Usage Count Displays the number of message handlers that use each destination queue. Description Displays a text description of a destination queue. Delete Deletes a destination queue. Click to delete a destination queue. Message Handler List Use this screen to view the list of message handlers that you have created for a specified set of server settings. From this screen, you can: View and edit message handler services View queue settings Enable, disable, and delete message handlers To access this screen, start the B2B Server Administrator and then do the following: 92 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

93 Message Handler List 1. In the Messaging menu in the navigation area, select Message Handlers. 2. Select an alias name for a set of server settings from the Server Settings drop-down list. Server Settings Specifies the server settings whose message handlers you want to display. Select a set of server settings from the drop-down list. Add Message Handler Displays the Create Message Handler screen. Service Displays the names of flow services that implement message handlers using the selected server settings. Click the service name to view details about the service. Direction Displays which direction the message handler transports messages: Direction Description MQSeries to webmethods B2B (inbound). The message handler retrieves messages from queues by performing either a Get or Listen operation. webmethods B2B to MQSeries (outbound). The message handler sends messages to queues by performing a Put operation. Destination Displays the alias name of the queue on which the message handler operates. Click the queue name to view queue settings. Enabled Indicates whether the message handler is currently enabled or disabled. Indicator Color (green) Description The message handler is enabled. If the message handler is invoked, it can perform its message operation. If you need to disable a message handler, click the green indicator. (red) The message handler is disabled. To enable the message handler, click the red indicator. When a message handler is disabled, it cannot perform its message operation. If the message handler is invoked to perform a message operation, the message handler returns an error. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

94 APPENDIX A Screen Descriptions Delete Deletes the message handler from webmethods B2B. Click handler. to delete a message Message Handling Service (Edit) Use this screen to modify parameters for a specific message handler. To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Message Handlers. 2. Select a set of server settings from the Server Settings drop-down list. 3. Click the name of the message handler (in the Service column) that you want to edit. The message handler specifications are displayed. 4. Click Edit. Package Specifies the package in which the message handler flow service resides. Select a package from the drop-down list. Service Name Specifies the fully-qualified service name of the message handler flow service. You cannot change this field. 94 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

95 Message Handling Service (Edit) Destination Specifies the name of the queue parameters this message handler uses to interact with a queue. Service Action Specifies the type of messaging operation the message handler performs Put, Listen or Get. Setting Put Listen Explicit Get Description Specifies that the message handler send a message to queues by performing a Put operation. Specifies that the message handler receives messages from queues by performing the Listen operation. When you select Listen, complete the following fields: Message service. Specifies the name of the B2B service that this message handler will invoke after it gets a message from the queue. Type the service s fully-qualified name, for example, msgs.fncl.gl:post_glitem. Exception service. Specifies the name of the B2B service that this message handler will invoke if an exception occurs while it is getting a message from the queue. Type the service s fully-qualified name, for example, msgs.oper:handleexceptions_glitem. Shutdown Interval. Specifies the maximum amount of time this message handler will remain active after it receives a request to shut down. Specifies that the message handler receive messages from queues by performing the Get operation. When you select Explicit Get, select one of the following to specify what you want the message handler to do if the queue is empty when it tries to retrieve a message: Wait Indefinitely. The message handler will wait until a message appears in the queue. Wait for milliseconds. The message handler will wait the period of time you specify and then returns to the calling program. No wait. The message handler immediately returns to the calling program if there are no messages in the queue. State Specifies whether you want the message handler to be enabled or disabled. If the message handler is enabled, it can perform its message operation. If the message handler is disabled, the message handler returns an error when invoked to perform its message operation. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

96 APPENDIX A Screen Descriptions Selector Specifies whether the message handler is configured to accept a Message Selector to selectively retrieve the next message from a queue that matches some specific criteria, or whether it does not accept a Message Selector, thereby accepting any messages on the queue. With Selector Uses a message selector. Without Selector Does not use a message selector. Connection Management Parameters The fields in this section specify whether connection pooling will be used for this message handler. Connection Type Specifies whether the message handler uses transactional semantics. Minimum Connections Specifies the minimum number of connections you want webmethods B2B to maintain in the connection pool. Maximum Connections Specifies the maximum number of connections you want webmethods B2B to maintain in the connection pool. Inactive Lifetime Specifies the length of time, in milliseconds, that an inactive connection can remain in the pool. Submit Saves your changes to the message handler flow service. Cancel Cancels your request to change the message handler and returns you to the View Message Handler screen. Message Handling Service (View) Use this screen to view information about a message handler. 96 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

97 Message Handling Service (View) To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Message Handlers. 2. Select an alias name for a set of server settings from the Server Settings drop-down list. 3. Click the name of the message handler (in the Service column) for which you want to view information. Destination Displays the name of the message destination queue with which the message handler interacts. Direction Displays the direction of the message handler: Direction Inbound (Message Queue to B2B) Outbound (B2B to Message Queue) Description The message handler receives messages from queues by performing either a Get or Listen operation. The message handler sends messages to queues by performing a Put operation. Service Name Displays the fully qualified service name of the message handler flow service. Package Displays the package in which the message handler service resides. Service Action Displays the message operation that the message handler performs Put, Get, or Listen. State Displays whether the message handler is currently enabled or disabled. If the message handler is enabled, it can perform its message operation. If the message webmethods B2B Adapter: MQSeries Edition User Guide VERSION

98 APPENDIX A Screen Descriptions handler is disabled, the message handler returns an error when invoked to perform its message operation. Connection Management Parameters The fields in this section display whether connection pooling is be used for this message handler. Connection Type Specifies whether the message handler uses transactional semantics. Minimum Connections Displays the minimum number of connections you want webmethods B2B to maintain in the connection pool. Maximum Connections Displays the maximum number of connections you want webmethods B2B to maintain in the connection pool. Inactive Lifetime Displays the length of time, in milliseconds, that an inactive connection can remain in the pool. Edit Opens the Message Handling Service (Edit) screen from which you can update information for the message handler. Message Server Settings List Use this screen to view a list of the sets of server settings that you have created. From this screen, you can create a new set of server settings, edit an existing set of server settings, or delete a set of server settings. To access this screen, start the B2B Server Administrator and then do the following: 1. In the Messaging menu in the navigation area, select Server Settings. Add Server Settings Opens the Create Server Settings screen, allowing you to specify server settings for a specific queue manager. 98 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0

99 Provider Administration Name Displays the names of the sets of server settings that you have defined. Provider Displays MQSeries, which is the message queuing provider associated with the server settings. You cannot change this value. Description Displays text descriptions of the server settings. Test Connection Establishes a connection to the server setting and returns a status message. Click to establish a connection. Delete Deletes the set of server settings. Click the Name field. to delete the server settings identified in Provider Administration Use this screen to import a list of message queues for each MQSeries queue manager you will be using. webmethods B2B Adapter: MQSeries Edition User Guide VERSION

100 APPENDIX A Screen Descriptions 1 To access this screen, start the B2B Server Administrator. 2 In the Messaging menu in the navigation area, select Provider Admin. Provider Specifies the message queuing provider for which you want to perform administrative tasks. Select MQSeries from this list. MQSeries Queue Administration The fields in this section specify administrative tasks for the MQSeries Adapter. Queue Manager Name Specifies the name of the queue manager that has the list of message queues that you want to import. This name is case sensitive. Import File Specifies the name of the file you want to import. This file should contain the list of message queues for the queue manager specified in Queue Manager Name. Instructions for creating the file are on the lower portion of the screen. To identify the file, type the fully-qualified path and file name for the file in the Import File field. Import Imports the list of message queues from the file that you specified in the Import File field. Server Settings (View) Use this screen to view existing server settings. To access this screen, start the B2B Server Administrator and then do the following: 100 webmethods B2B Adapter: MQSeries Edition User Guide VERSION 2.0