HP NonStop Data Transformation Engine IBM WebSphere MQ Adapter Reference Guide Abstract This manual provides information about using the HP NonStop™ Data Transformation Engine IBM WebSphere (NonStop DTE) MQ messaging adapter on the HP NonStop server. Product Version NonStop Data Transformation Engine 6.7.
Document History Part Number Product Version Published 528266-001 NonStop Data Transformation Engine 6.7.1 June 2004 528266-002 NonStop Data Transformation Engine 6.7.
Contents About This Document Related References........................................................................................... 5 Chapter 1 - IBM WebSphere MQ Adapter Overview ....................................................................................................... 6 IBM WebSphere MQ Message Content ................................................................ 6 Transmission Queues....................................................................................
Contents Hex Group Message ID (-HGRP)....................................................................... 36 Hex Message ID (-HMID)................................................................................ 37 Ignore Group Message (-XGRP) ....................................................................... 38 Listen (-LSN) ............................................................................................. 38 Message Buffer Size (-MBS) ....................................................
About This Document This document contains detailed information about using the IBM WebSphere MQ adapter. For general information regarding using any of the Mercator Resource adapters, see the Resource Adapters Reference Guide. This document assumes that the reader knows the Windows environment, has used the Mercator Design Studio, and understands words such as mapping, type trees, and other basic Mercator terminology.
Chapter 1 - IBM WebSphere MQ Adapter This chapter introduces the IBM WebSphere MQ adapter. You can use the adapter with a Command Server, an Event Server, the Platform API, or with a map in a map rule. IBM WebSphere MQ software transports data between applications. For the receiving application to be able to successfully use data, it (the data) must be transformed.
Chapter 1 - IBM WebSphere MQ Adapter System and Configuration Requirements and values of a valid IBM WebSphere MQ Message Descriptor structure. When the Header adapter command (-HDR) is specified, any of the message header components may be included in mapping rules. For mapping purposes, definitions for the message descriptors and the IBM WebSphere MQ Link for the R/3 header are provided in the mg.mtt type tree, located in the examples\adapters\mq folder.
Chapter 1 - IBM WebSphere MQ Adapter System and Configuration Requirements • A Command Server must be installed on the computer upon which the IBM WebSphere MQ messaging adapter is to be installed. It is not necessary that it be installed in the same load library as the messaging adapter, but the JCL should reference all relevant load libraries.
Chapter 2 - Command Aliases Adapter commands can be specified by using a command string on the command line or by creating a command file that contains adapter commands. The execution command syntax is: -IM[alias} card_num -OM[alias] card_num where –IM is the Input Source – Override execution command and –OM is the Output Target – Override execution command, alias is the adapter alias, and card_num is the number of the input or output card, respectively.
Chapter 2 - Command Aliases GET > Source Settings GET > Source Settings Use the Map Designer GET settings to configure options for input map cards that use the IBM WebSphere MQ (client) or IBM WebSphere MQ (server) adapters. For the Source setting, select the data source as either MQSeries (client) or MQSeries (server) to use the IBM WebSphere MQ adapters. GET > Source > Command Setting Use the Command setting to enter adapter commands. For command syntax, refer to List of Commands.
Chapter 2 - Command Aliases GET > Source Settings Source > Transaction > OnFailure Setting Use the OnFailure setting with adapter sources to select the rollback or commit behavior if the map does not successfully complete. The default value is Rollback. Value Description Rollback If the map does not complete successfully, sources retrieved through the messaging adapter are not deleted. Commit The adapter behaves as if the map was successful and the action specified by the OnSuccess setting is taken.
Chapter 2 - Command Aliases PUT > Target Settings Value Description Card Check for success or failure at the completion of each card. If the card is successfully processed, use the OnSuccess setting. If the card fails, use the OnFailure setting. Source > Transaction > Warnings Setting Use the Warnings setting to determine whether to fail the map or ignore warning conditions for the specific input map card. The warning messages are written to the execution audit log. The default value is Ignore.
Chapter 2 - Command Aliases Value PUT > Target Settings Description CreateOnContent Upon successful completion of the burst, map, card, or rule (determined by Scope settings), send the message only if it has content. Target > Transaction > OnFailure Setting Use the OnFailure setting with adapter targets to select the rollback or commit behavior if the map does not complete successfully. The default value is Rollback.
Chapter 2 - Command Aliases PUT > Target Settings Target > Transaction > Warnings Setting Use the Warnings setting to determine whether to fail the map or ignore warning conditions for the specific output map card. The warning messages are written to the execution audit log. The default value is Ignore. Value Description Ignore Ignore warnings for this map card. Fail Fail the map upon receiving a warning for this map card. Note Warnings have a positive return code.
Chapter 2 - Command Aliases PUT > Target Settings Target > Retry > MaxAttempts Setting Use the MaxAttempts setting to specify the maximum number of times that Retry is attempted. The default value is 0. Value Description 0 - value This is an integer representing the maximum number of times that Retry is attempted. Target > Retry > Interval Setting Use the Interval setting to specify the number of seconds to wait before attempting Retry again. The default value is 0.
Chapter 3 - IBM WebSphere MQ Commands This chapter describes the functions and usage of the IBM WebSphere MQ commands and their respective options. IBM WebSphere MQ Server Adapter IBM WebSphere MQ supports both client and server modes either from a single platform or distributed across multiple platforms. To select the correct client or server adapter, you must specify the adapter to use for a source or target in map cards, execution settings, or on the command line.
Chapter 3 - IBM WebSphere MQ Commands Using the Adapter Commands After the server messaging adapter for IBM MQSeries is installed in an environment running the IBM MQSeries server software, specify the use of the server adapter as follows: in the Map Designer For the AdapterSource setting for an Input Card or the AdapterTarget setting for an Output Card dialog box, select the MQSeries (server) value.
Chapter 3 - IBM WebSphere MQ Commands Using the Adapter Commands For example, for the AdapterSource setting for an Input Card or the AdapterTarget setting for an Output Card dialog box, select the MQSeries (server) value.
Chapter 3 - IBM WebSphere MQ Commands Using the Adapter Commands In Map Rules and Component Rules Specify messaging adapter commands using GET and PUT functions when defining map rules in the Map Designer or in component rules in the Type Designer. The default adapter scope when using both GET and PUT functions is burst. GET and PUT functions have the following default behaviors: Result GET Function PUT Function Successful Completion All source messages on the source queue are deleted.
Chapter 3 - IBM WebSphere MQ Commands Using the Adapter Commands For information about the using the GET and PUT functions, refer to the Functions & Expressions Reference Guide. From the Integration Flow Designer Use the execution settings for a map in either the Integration Flow Designer, or Command Server to specify the adapter settings for the MQSeries adapter as a source or target.
Chapter 3 - IBM WebSphere MQ Commands MQSeries AdapterSource Settings MQSeries AdapterSource Settings Use the Map Designer AdapterSource settings to configure options for input map cards that use the MQSeries messaging adapters. AdapterSource Use the AdapterSource setting to select the data source. For the AdapterSource setting, select the MQSeries (server) to use the MQSeries messaging adapters. AdapterSource > SourceAdapterCommand Use the SourceAdapterCommand setting to enter adapter commands.
Chapter 3 - IBM WebSphere MQ Commands MQSeries AdapterSource Settings message is rolled back, and is left on the input queue. If Rollback is set and the map succeeds, the transaction is committed. If Rollback is not set, there is no MQSeries transaction syncpoint control activation. The message remains deleted, regardless of the completion status of the map.
Chapter 3 - IBM WebSphere MQ Commands MQSeries AdapterSource Settings AdapterRetry > Switch Use the Switch setting to activate AdapterRetry for the specific adapter (ON) or not (OFF). The default value is OFF. Value Description OFF AdapterRetry is inactive. ON Activates AdapterRetry for the adapter AdapterRetry > MaxAttempts Use the MaxAttempts setting to specify the maximum number of times that AdapterRetry is attempted. The default value is 0.
Chapter 3 - IBM WebSphere MQ Commands MQSeries AdapterSource Settings AdapterSource > AdapterScope Use the AdapterScope setting to specify when to check for success (OnSuccess) or failure (OnFailure) at the completion of the processing of either a map, burst, or card, so that the rollback and retry actions can be performed as specified. The default value is Map. Value Description Map Check for success or failure at the completion of each map.
Chapter 3 - IBM WebSphere MQ Commands MQSeries AdapterTarget Settings MQSeries AdapterTarget Settings Use the Map Designer AdapterTarget settings to configure options for output map cards that use the MQSeries messaging adapters. AdapterTarget Use the AdapterTarget setting to select the data target. Select MQSeries (server) to use the MQSeries messaging adapters. AdapterTarget > TargetAdapterCommand Use the TargetAdapterCommand setting to enter adapter commands.
Chapter 3 - IBM WebSphere MQ Commands MQSeries AdapterTarget Settings AdapterTarget > OnFailure Use the OnFailure setting with adapter targets to select the rollback or commit behavior if the map does not successfully complete. The default value is Rollback. Value Description Rollback If the map does not successfully complete, the message is not sent. Commit The adapter behaves as if the map was successful and the action (Create or CreateOnContent) specified by the OnSuccess setting is taken.
Chapter 3 - IBM WebSphere MQ Commands MQSeries AdapterTarget Settings AdapterRetry > Interval(Secs) Use the Interval(Secs) setting to specify the number of seconds to wait before attempting AdapterRetry again. The default value is 0.
Chapter 3 - IBM WebSphere MQ Commands List of Commands List of Commands The following table lists valid commands for the IBM WebSphere MQ adapter, the command syntax, and whether the command is supported (√) for use with sources, targets, or both: Name Syntax Source Target Cluster Queue Manager Name -CQMN [cluster_manager_name] Complete Message -CMSG √ Convert -CVT √ Correlation ID * -CID [correlation_ID] √ Default Header -DH Error Queue Manager Name -EQMN error_queue_mgr √ √ Error Qu
Chapter 3 - IBM WebSphere MQ Commands List of Commands Name Syntax Source Target Queue Manager Name -QMN queue_manager √ √ Queue Name -QN queue_name √ √ Refresh Message Cursor -REFRESH [reset_time] √ Require All Messages -ALLMSG √ Require All Segments -ALLSEG √ Trace -T [full_path] √ Transmission Error Queue Name -XEQN x_err_queue_name √ Transmission Queue Name -XQN x_queue_name √ Version 2 -V2 √ √ √ * The use of wildcards with this IBM WebSphere MQ adapter command is sup
Chapter 3 - IBM WebSphere MQ Commands List of Commands workload exit if one exists) according to the value of the DefBind queue attribute. This attribute may have one of two values: ♦ If MQOO_BIND_ON_OPEN is specified, the queue manager selects a particular instance of the cluster queue during the processing of the MQOPEN call, and all messages put using this queue handle are sent to that instance.
Chapter 3 - IBM WebSphere MQ Commands List of Commands If the queue contains segmented messages with some of the segments missing (perhaps the messages were delayed in the network and have not yet arrived), use the Complete Message adapter command (-CMSG) to prevent retrieval of segments belonging to incomplete logical messages. Note For information about incomplete message groups contributing to the size of CurrentQDepth, refer to Error! Reference source not found..
Chapter 3 - IBM WebSphere MQ Commands List of Commands quotation marks. For example, if you wanted to specify a correlation ID of My "New" ID, you would need to enter the following: -CID "My ""New"" ID" When a correlation identifier is specified for a source, the adapter retrieves the first message on the queue with that correlation ID. If no argument is supplied, the correlation ID of the first message retrieved is used.
Chapter 3 - IBM WebSphere MQ Commands List of Commands Note Do not try to specify values for these fields if you use the -DH option in the adapter command. Using that option causes values you provided in these fields to be ignored by the adapter and replaced with the default IBM WebSphere MQ values. If you need to explicitly specify values for these fields, use the -HDR option in the adapter command (without the -DH option).
Chapter 3 - IBM WebSphere MQ Commands List of Commands The name of the error queue must be specified. By default, the queue manager used is the one specified with the Queue Manager Name adapter command (-QMN). Group Message (-GRP) Use the Group Message adapter command (-GRP) for data sources to specify retrieval of messages from a single group from the source.
Chapter 3 - IBM WebSphere MQ Commands List of Commands Header (-HDR) Use the Header adapter command (-HDR) to specify the inclusion of the IBM WebSphere MQ message descriptor in the source and target data. -HDR When Header adapter command (-HDR) is used for a data source, the message descriptor appears first, before the message content. Use the Header adapter command (-HDR) to include any of the message descriptor components in mapping rules.
Chapter 3 - IBM WebSphere MQ Commands List of Commands Hex Correlation ID (-HCID) Use the Hex Correlation ID adapter command (-HCID) to specify correlation identifiers using hexadecimal pair notation. This passes to the adapter the exact correlation ID to locate, even if that correlation ID contains non-printable values, spaces, or even null characters. -HCID hex_correlation_ID Option Description hex_correlation_ID Hexadecimal correlation identifiers.
Chapter 3 - IBM WebSphere MQ Commands List of Commands Option Description hex_group_ID Hexadecimal group message identifiers. For example, the ASCII group message ID My Msg is represented as 4D79204D7357 when specified with the Hex Group Message ID adapter command (-HGRP). The space character must be encoded in the hex pair notation. Note The hexadecimal group message ID wildcard notation is not encoded in the hex pair notation. The wildcard character * is entered literally.
Chapter 3 - IBM WebSphere MQ Commands List of Commands Ignore Group Message (-XGRP) Use the Ignore Group Message adapter command (-XGRP) for data sources to ignore the group messages on the queue and not to treat them as individual, physical messages. The default behavior of the IBM WebSphere MQ adapter is to process all physical messages, including group messages, as individual events.
Chapter 3 - IBM WebSphere MQ Commands List of Commands If the Listen adapter command (-LSN) is not issued and the message is not available for the adapter to retrieve immediately, the map completes, but returns the following warning in the audit log: (2033) MQSeries Warning: No message available. Message Buffer Size (-MBS) Use the Message Buffer Size adapter command (-MBS) to specify the size of the message buffer.
Chapter 3 - IBM WebSphere MQ Commands List of Commands You must always specify a value when using the -FORMAT adapter command. Failure to do so will result in map failure and a corresponding error message is generated. Note If you use a user-defined format, you must also provide the corresponding dataconversion exit so that receiving applications can read the message using the MQGMO_CONVERT option. For Mercator applications, this means using the -CVT adapter command for the IBM WebSphere MQ inputs.
Chapter 3 - IBM WebSphere MQ Commands List of Commands When a message ID is specified for a target, the adapter places the message on the queue with that message ID assigned. If this command is not specified for a target, the message is put on the queue using a unique message identifier generated by the queue manager.
Chapter 3 - IBM WebSphere MQ Commands List of Commands For example, to specify the target queue named target_q under the queue manager qmgr for message outputs (where 16 is the numeric value of the MQOO_OUTPUT option), the syntax would be: -QMN qmgr -QN target_q -MQOO 16 To specify the source queue named source_q under the queue manager qmgr, for message input in browse mode with shared access (where 10 is the numeric superposition of the MQOO_INPUT_SHARED (2) and MQOO_BROWSE (8) options), the syntax woul
Chapter 3 - IBM WebSphere MQ Commands List of Commands ♦ If the Version 2 (-V2) command is omitted (which would enforce the use of Version 1 header from MQSeries 2.x). The created physical messages will be message segments of the original message. The Offset property of the message will provide information about the relative position of each of the segments in the original message. In this case, -CMSG adapter command can be used on input to automatically reassemble the original message.
Chapter 3 - IBM WebSphere MQ Commands List of Commands Queue Manager Name (-QMN) Use the Queue Manager Name adapter command (-QMN) to specify the name of the queue manager on which the queue (specified by the -QN command) exists. -QMN queue_manager_name Option Description queue_manager_name This is the name of the queue manager. This name is case-sensitive. When the Queue Manager Name adapter command (-QMN) is not specified, the default queue manager is used.
Chapter 3 - IBM WebSphere MQ Commands List of Commands Refresh Message Cursor (-REFRESH) Use the Refresh Message Cursor adapter command (-REFRESH) to ensure that higher-priority messages are enqueued in front of any existing messages with a lower priority so that the higher-priority messages can trigger the associated maps to run. This command is only used when using an IBM WebSphere MQ event input with the Event Server.
Chapter 3 - IBM WebSphere MQ Commands List of Commands After T1 occurs, both messages have already been placed on the queue (with M1 in front of M2). However, they are not being recognized by the message cursor. After T2 occurs, the message cursor recognizes message M2 and it positions itself on that message. After T3 occurs, message M1 is also committed, but it is now beyond the message cursor.
Chapter 3 - IBM WebSphere MQ Commands List of Commands adapter's list upon moving them to the error queue. Note, however, that if, for some reason, messages cannot be stored on the error queue (for example, PUT is disabled for the error queue), the messages will remain on the input queue and in the internal adapter's list which again provides the possibility of a memory leak.
Chapter 3 - IBM WebSphere MQ Commands List of Commands Trace (-T) Use the Trace adapter command (-T) to produce a log file with the default name mqstrace.log in the map execution directory. -T Optionally, you can specify a directory location and a name (full path) for the trace file to be created. -T [full_path] The trace file contains information about connections to IBM WebSphere MQ, message sizes, IBM WebSphere MQ error messages, and adapter error messages. Note For OS/390 Batch and CICS, the mqstrace.
Chapter 3 - IBM WebSphere MQ Commands List of Commands (-XQN), the local queue is used. If the transmission queue specified with the Transmission Error Queue Name adapter command (-XEQN) does not exist, the queue specified by the MQSeries DefaultXmitQ attribute (DEFXMITQ in MQSC) on the local queue manager is used.
Chapter 3 - IBM WebSphere MQ Commands List of Commands If the Version 2 adapter command (-V2) is not specified, the default is _VERSION_2, which corresponds to MQSeries Version 5.x or 6.x. The Version 2 adapter command (-V2) is used with sources and targets. Note If the Header adapter command (-HDR) is used in conjunction with the Version 2 adapter command (-V2), then the version information mapped in the header is ignored.
Chapter 3 - IBM WebSphere MQ Commands MQSeries Adapter Commands for Compatibility MQSeries Adapter Commands for Compatibility The Number of Messages (–NM) and the Duplicate Message ID (-DID) adapter command functionality have been retained to provide compatibility support for Mercator Software version 1.4.2 maps using these commands. These commands are for use only with data sources. The following table lists the version-1.4.
Chapter 3 - IBM WebSphere MQ Commands MQSeries Adapter Commands for Compatibility The Duplicate Message ID adapter command (-DID) must also be specified. The Number of Messages adapter command (-NM) concatenates the specified number of messages into a single buffer returned for mapping. When the Number of Messages adapter command (-NM) is used, the message cursor is not returned to the head of the queue for other source cards in the same map that use the identical queue manager and queue.
Chapter 4 - Syntax Summary This chapter displays the syntax of the IBM WebSphere MQ adapter commands for data sources and targets.
Chapter 4 - Syntax Summary Data Targets Data Targets The following is the syntax of the IBM WebSphere MQ adapter commands used for data targets: -QN queue_name [-CQMN [cluster_manager_name]] [-HDR |-DH |[-MID [message_ID]|-HMID hex_message_ID] [-CID [correlation_ID]|-HCID hex_correlation_ID] [-FORMAT message_format] ] [-MQOO option_number] [-PKT packet_size] [-QMN queue_manager_name] [-T [full_path]] [-V2] [-XEQN x_err_queue_name] [-XQN x_queue_name] Wildcard Support The use of wildcards with the IBM We
Chapter 5 - Using the Messaging Adapter When using the IBM WebSphere MQ adapter for a source, messages are served by default from the queue in a first-in-first-out (FIFO) manner unless you specify a particular message using a message or correlation identifier. When using the adapter for a target, messages are placed on the queue you specify. Message identifiers are assumed to be unique for a particular queue.
Chapter 6 - Example Files The IBM WebSphere MQ type tree (named mq.mtt) is provided in the examples\adapters\mq folder. Types describing different IBM WebSphere MQ message formats are provided so that you can easily select the message types needed for input or output or the descriptor that you need to include with any message data you want. To access an example for this adapter, click Start > Programs > Mercator version number > Design Studio > Examples and navigate to Resource Adapters.
Chapter 6 - Example Files Using the Sample Type Tree Use one of these types for the type of an input or output card. Add a message content type as a component of MessageData. The mq.mtt type tree has definitions for: ♦ MQSeries Header MessageDescriptor The MessageDescriptor Header type defines the components and format of the message descriptor. (Use this for OS/390 Batch, OS/390 CICS, or IBM WebSphere MQ 2.x).
Chapter 6 - Example Files Using the Sample Type Tree The mq.mtt type tree is organized so that you can drag the MQSeries root type to another type tree to easily use any of the IBM WebSphere MQ-specific headers. For example: Mapping Message Data Only By default, the adapter does not use message descriptors. On input, it returns only the body of the received message, and on output, it treats the data that it receives as the message body.
Chapter 6 - Example Files Using the Sample Type Tree To use the type tree for mapping message data only 1 Define the message content for your message (shown below as Message group under CreditInfo category). 2 Add it as a component of MessageData. 3 Use MessageData as an input or output card type.
Chapter 6 - Example Files Using the Sample Type Tree The following example shows a sample type tree definition: Mapping the IBM WebSphere MQ Link for R/3 Header If you use IBM WebSphere MQ to send and receive data from an SAP R/3 system, you may want to use the IBM WebSphere MQ Link for R/3. This link communicates with R/3 using inbound and outbound server queues. When using the IBM WebSphere MQ Link for R/3, message data is in IDoc format, prefixed by the IBM WebSphere MQ Link for R/3 Header. The mq.
Chapter 6 - Example Files Using the Sample Type Tree To map the message descriptor and the IBM WebSphere MQ Link for R/3 Header, use this type as the card type. To map only the IBM WebSphere MQ Link for R/3 Header, use this type as the card type.
Chapter 7 - Troubleshooting For information about error codes and messages returned by the adapters, see Appendix A - Return Codes and Error Messages. Trace Log Use the Trace adapter command (–T) to create a trace file to report adapter activity information, recording events that occur while the adapter is retrieving and sending data. The trace command produces a log file with the default name mqstrace.log in the map execution directory.
Appendix A - Return Codes and Error Messages Return codes and messages are returned when the particular activity completes. Return codes and messages may also be recorded as specified in the audit logs, trace files, execution summary files, etc. Messages The following is a listing of all the codes and messages that can be returned as a result of using the IBM WebSphere MQ adapter for sources or targets. In addition to these codes, the WebSphere MQ adapter can return WebSphere MQ error codes.
Appendix A - Return Codes and Error Messages Return Code Message -1013 Error queue operation could not complete -1014 Unable to Begin Commitment Control (Tandem) -1015 Unable to Backout (Tandem) -1016 Unable to Commit (Tandem) -1017 Segmentation not supported (Tandem) IBM WebSphere MQ Adapter Reference Guide 64 Messages
Index Require All Segments (-ALLSEG), 47 Trace (-T), 48 Transmission Error Queue Name (-XEQN), 48 Transmission Queue Name (-XQN), 49 Version 2 (-V2), 49 Complete Message (-CMSG) adapter command, 30 Convert (-CVT) adapter command, 31 Correlation ID (-CID) adapter command, 31 -CQMN adapter command, 29 -CVT adapter command, 31 A AdapterRetry MQSeries, 22, 26 AdapterScope MQSeries, 24, 27 AdapterSource MQSeries, 21 AdapterTarget MQSeries, 25 AdapterWarnings MQSeries, 23, 27 alias for client and server, 20 -ALL
Index I MQOPEN Options(-MQOO) adapter command, 41 MQSeries adapter commands Duplicate Message ID, 51 Number of Messages (-NM), 51 AdapterSource settings, 21 AdapterRetry, 22 Interval(Secs), 23 MaxAttempts, 23 Switch, 23 AdapterScope, 24 AdapterSource, 21 AdapterWarnings, 23 FetchUnit, 24 OnFailure, 22 OnSuccess, 21 SourceAdapterCommand, 21 AdapterTarget settings, 25 AdapterRetry, 26 MaxAttempts, 26 Switch, 26 AdapterRetryInterval(Secs), 27 AdapterScope, 27 AdapterTarget, 25 AdapterWarnings, 27 OnFailure, 2
Index Q PUT > Target settings, 12 T -T adapter command, 48 Target > Transaction settings OnFailure, 13 OnSuccess, 12 Scope, 13 Warnings, 14 Target settings Retry, 14 Interval, 15 MaxAttempts, 15 Switch, 14 TargetAdapterCommand MQSeries, 25 Trace (-T) adapter command, 48 trace log, 62 Transmission Error Queue Name (-XEQN) adapter command, 48 Transmission Queue Name (-XQN) adapter command, 49 type tree, 56 Q -QMN adapter command, 44 -QN adapter command, 44 -QTY adapter command, 43 Quantity (-QTY) adapter
