EAI MQSeries Server Transport

This chapter discusses the EAI MQSeries Server Transport business service. It includes the following topics:

This chapter assumes that you understand the architecture and operation of IBM WebSphere MQ (formerly known as IBM MQSeries). For more information, consult the IBM WebSphere MQ documentation at: http://www.ibm.com/support.

About the EAI MQSeries Server Transport Business Service

The Siebel EAI MQSeries Server Transport provides a messaging solution to help you integrate data between Siebel Business Applications and external applications that can interface with IBM WebSphere MQ. The EAI MQSeries Server Transport business service transports messages to and from IBM WebSphere MQ queues. It uses the Message queuing API (MQI).

Note: The EAI MQSeries Server Transport can connect only to IBM WebSphere MQ Server software. The IBM WebSphere MQ Server must be running on the same system as your Siebel Server. Before using the EAI MQSeries Server Transport, you must install and configure the IBM WebSphere MQ software. Contact your IBM sales representative for details.

The EAI MQSeries Server Transport supports the inbound and outbound methods described in Outbound Methods for a Transport Business Service and Inbound Methods for a Transport Business Service. This topic includes the following information:

About the MQPMO_SYNCPOINT Option

The EAI MQ Series Server Transport business service uses the MQPMO_SYNCPOINT option for sending messages to IBM WebSphere MQ using the IBM MQ API.

MQPMO_SYNCPOINT sends the message with syncpoint control. A syncpoint is a logical point in the execution of a program where changes made by the program can be saved. The message request operates within the unit of work: the message is not visible outside the unit of work until the unit of work is saved. If the unit of work is rolled backed, then the message is deleted. For more information about syncpoint options, consult the IBM WebSphere MQ documentation at:

http://www.ibm.com/support

EAI MQSeries Server Transport Parameters

In addition to supporting the common transport parameters presented in the second table in Common EAI Transport Parameters, the EAI MQSeries Server Transport uses the parameters shown in the following table. These can be specified as service method arguments, subsystem parameters, or user properties.

Note: To send to a model queue, the model queue must have a definition type of PERMANENT and the following arguments must be supplied in the workflow: Model Queue, Physical Queue, Queue Manager, and Message Text.

Argument	Display Name	Description
MqAcknowledgements	Receive Acknowledgements	Default is False. This parameter specifies whether or not delivery and arrival acknowledgements are to be received.
MqAckPhysicalQueueName	Acknowledgement Physical Queue Name	If the MqAcknowledgements is set to True, then this parameter contains the name of the physical queue for acknowledgements to responses.
MqAckQueueManagerName	Acknowledgement Queue Manager Name	Defaults to MqQueueManagerName if unspecified. If MqAcknowledgements is set to True, then this parameter contains the name of the queue manager for acknowledgements to responses.
MqModelQueueName	Model Queue Name	Name of the MQSeries model queue.
MqPhysicalQueueName	Physical Queue Name	Name of the MQSeries physical queue. You can also create an alias queue which points to a target queue and use the alias queue name as the input argument physical queue name and send messages to the target queue. Note: Using an alias queue works. However, since the alias queue does not have a backout queue defined, the receiver cannot roll back to the backout queue.
MqQueueManagerName	Queue Manager Name	Name of the MQSeries queue manager. If this parameter is not specified, then the default Queue Manager Name, as specified in the MQSeries configuration, is used. The Response Queue Manager is the same as MqQueueManagerName.
MqRespModelQueueName	Response Model Queue Name	Name of model queue for response connection.
MqRespPhysicalQueueName	Response Physical Queue Name	Name of physical queue for response connection.
MqFormat	MQSeries Format	The format of the message from the Siebel application to the outbound queue.
MqSleepTime	Sleep Time	Default is 20000 milliseconds. The timeout interval on receive calls, in milliseconds.

In addition to the EAI MQSeries Server Transport, you can run the MQSeries Server Receiver, which is a server component that periodically checks the MQSeries queues you specify, for inbound messages.

Note: The persistence of the message is the same as the persistence of the queue itself.

Exposing MQMD Headers as Properties

In the inbound direction, that is, when a message is received from a queue, the EAI MQSeries Server Transport feature exposes the MQMD headers as properties of a property set. The supported headers are summarized in the last table, about MQMD Message Headers, in this topic

In the outbound direction, that is, when a message is placed on a queue, the EAI MQ Server Transport supports the headers shown in the following table to be set by the caller.

Header	Value
CodedCharSetId	MQCCSI_Q_MGR, MQCCSI_INHERIT, MQCCSI_EMBEDDED, or any positive Long.
Encoding	MQENC_NATIVE or any positive Long.
Expiry	Any positive Long.
MsgType	Any nonnegative Long.
Persistence	MQPER_PERSISTENT, MQPER_NOT_PERSISTENT, or MQPER_PERSISTENCE_AS_Q_DEF.
Priority	MQPRI_PRIORITY_AS_Q_DEF or any nonnegative Long.
Report	The only settable value is MQRO_NONE.
ReplyToQ	Name of the reply queue, for example, myQueue. ReplyToQ is set in the message header of an incoming MQ message by the sender application. This sets dynamically the queue for the response sent by Siebel CRM. ReplyToQ is valid for the ReceiveDispatchSend method. Note: If the Response queue is specified using a static configuration, then the ReplyToQ header of the incoming message is ignored. The static configuration overrides dynamic queuing. ReplyToQ can also be set by the Siebel application, as MQMD_S_In_ReplyToQ while using the Send method, to specify the response parameters.
ReplyToQMgr	Name of the reply queue manager, for example, myQueueManager. ReplyToQMgr is set in the message header of an incoming MQ message by the sender application. This sets dynamically the queue manager for the response sent by Siebel CRM. ReplyToQMgr is valid for the ReceiveDispatchSend method. Note: If the Response queue is specified using a static configuration, then the ReplyToQMgr header of the incoming message is ignored. The static configuration overrides dynamic queuing. ReplyToQMgr can also be set by the Siebel application, as MQMD_S_In_ReplyToQMgr while using the Send method, to specify the response parameters.

You can set a MQMD message header for the Siebel application by specifying it as a property in a property set on the outbound side. Whereas on the inbound side, the MQMD message header of the response is exposed to the user as a property on the output property set.

On the inbound side, you can have the supported MQMD message headers as part of the output property set without having to do extra steps to see these MQMD message headers.

On the outbound side, you can set the MQMD message headers using the EAI MQSeries Server Transport. To modify the MQMD message headers on the outbound side, the property value for FullMQMDControl must be set to TRUE.

During the sending business service step (EAI MQSeries Server Transport.Send) within the workflow, input arguments are added that can modify MQMD headers. Once the property FullMQMDControl is set to TRUE, you can modify other MQMD headers as the examples show in the following table.

Note: In workflows and scripts, you set and get MQMD parameters using their full names, for example, MQMD_S_In_Encoding.

Property	Type	Example Value
MQMD_S_In_CodedCharSetId	Literal	1208
MQMD_S_In_Encoding	Literal	MQENC_NATIVE
MQMD_S_In_Expiry	Literal	MQEI_UNLIMITED
MQMD_S_In_MsgType	Literal	TestMsgHeader
MQMD_S_In_Persistence	Literal	MQPER_PERSISTENT
MQMD_S_In_Priority	Literal	MQPRI_PRIORITY_AS_Q_DEF
MQMD_S_In_ReplyToQ	Literal	MyQueue
MQMD_S_In_ReplyToQMgr	Literal	MyQueueManager

Note: When using the Message Type header (MQMD_S_In_MsgType), make sure that the message type set makes sense in context. For example, if the Send method is used to send a message to MQSeries, then do not set the MsgType to MQMT_REQUEST. If the SendReceive method is used to send and request a response from MQSeries, then the MsgType of MQMT_REQUEST is applicable (this is automatically set by the Siebel application). In the previous table, MsgType is set to TestMsgHeader.

The following table summarizes the MQMD message headers that are exposed as properties in a property set.

Field	Data Type	Description	Input or Output Property?
AccountingToken	MQBYTE32	Accounting token	Output
ApplIdentityData	MQCHAR32	Application data relating to identity	Output
ApplOriginData	MQCHAR4	Application data relating to origin	Output
BackCount	MQLONG	Backout counter	Output
CodedCharSetId	MQLONG	Character set identifier of message	Input and Output
CorrelId	MQBYTE24	Correlation identifier	Output
Encoding	MQLONG	Numeric encoding of message data	Input and Output
Expiry	MQLONG	Message lifetime	Input and Output
Feedback	MQLONG	Feedback or reason code	Output
Format	MQCHAR8	Format name of message data	Input and Output
GroupId	MQBYTE24	Group Identifier	Output
MsgFlags	MQLONG	Flags that specify attributes of the message or control its processing	Output
MsgSeqNumber	MQLONG	Sequence number of logical message within group	Output
MsgType	MQLONG	Message Type	Input and Output
Offset	MQLONG	Offset of data in physical message from start of logical message	Output
OriginalLength	MQLONG	Length of original message	Output
Persistence	MQLONG	Message persistence	Input and Output
Priority	MQLONG	Message priority	Input and Output
PutApplName	MQCHAR28	Name of application that sent the message	Output
PutApplType	MQLONG	Type of application that sent the	Output
PutDate	MQCHAR8	Date when message was sent	Output
PutTime	MQCHAR8	Time when message was sent	Output
ReplyToQ	MQCHAR48	Name of reply queue	Input and Output
ReplyToQMgr	MQCHAR48	Name of reply queue manager	Input
Report	MQLONG	Options for report messages	Output
UserIdentifier	MQLONG	User identifier	Output
Version	MQLONG	Structure version number	Output

EAI MQSeries Server Transport Named Subsystem

The EAI MQSeries Transport can read parameters from a named subsystem. For the EAI MQSeries Server Transport, the named subsystem type is MqSeriesServerSubsys.

The following is an example of the EAI MQSeries Server Transport and the commands to create a named subsystem and start a receiver:

create named subsystem MyMqSrvrSubsys for subsystem MQSeriesServerSubsys with 
MqPhysicalQueueName=Receiver, MqRespPhysicalQueueName=Sender, 
MqQueueManagerName=myQueueMgr

create named subsystem SiebelEcho for subsystem EAITransportDataHandlingSubsys with 
DispatchService="Workflow Utilities", DispatchMethod=ECHO

start task for comp MqSeriesSrvRcvr with 
ReceiverConnectionSubsystem=MyMqSrvrSubsys, 
ReceiverDataHandlingSubsystem=SiebelEcho, ReceiverMethodName=ReceiveDispatchSend

For a discussion of named subsystems for Siebel EAI, see . For more information about named subsystems, see Siebel System Administration Guide.

Using the SendReceive Method with MQSeries

The SendReceive method on the EAI MQSeries Server Transport sends a message and waits for a response from the target application on a response queue. This response message corresponds to the original message using the correlation ID in MQSeries.

Note: It is the responsibility of the external application to set the correlation ID of the response to the Siebel Business Application to the message ID of the original message.

Note: It is recommended that, when using the EAI MQSeries Server Transport business service with the SendReceive method, you check the TimedOut process property. If you send a message and the MQ transport times out waiting for a response, then the business service does not raise an error but the TimedOut value is true.

Dispatch Error Handling for the EAI MQSeries Server Transport

When using the ReceiveDispatch and ReceiveDispatchSend methods, certain MQSeries behavior might affect your messages.

Note: The transaction does not end when the message is received from the queue because it waits for the entire dispatch process to either complete successfully for commit or fail for rollback.

If all of the following conditions are met, then the message is sent to the Backout Requeue Queue of the current queue manager:

A dispatch error has occurred.
The RollbackOnDispatchError property is set to TRUE.
The message has been rolled back by a count exceeding the Backout Threshold of the queue.

Note: If the Backout Requeue Queue has not been specified for the Queue Manager, then the message is sent to the Dead Letter Queue of the current queue manager. If there is no specified Dead Letter Queue for the current queue manager, then the queue defaults to the SYSTEM.DEAD.LETTER.QUEUE.

Increasing the Maximum Message Length on IBM WebSphere MQ

The MaxMsgLength queue manager attribute in the IBM WebSphere MQ software defines the maximum length of a message that can be handled by a queue manager. The MaxMsgLength queue attribute is the maximum length of a message that can be handled by a queue.

The default maximum message length on IBM WebSphere MQ is 4 MB. If the message is too large for the queue, then MQRC_MSG_TOO_BIG_FOR_Q is returned. Similarly, if the message is too large for the queue manager, then MQRC_MSG_TOO_BIG_FOR_Q_MGR is returned.

If you are handling large messages, then you can change the MaxMsgLength queue manager and queue attributes independently. You can set the queue manager attribute value between 32768 bytes and 100 MB; you can set the queue attribute value between 0 and 100 MB.

After changing one or both of the MaxMsgLength attributes, restart your applications and channels to ensure that the changes take effect. For more information, consult the IBM WebSphere MQ documentation at:

http://www.ibm.com/support

Using the EAI MQSeries Server Transport on AIX

When you use the EAI MQSeries Server Transport on AIX, the shared memory segment required by the EAI MQSeries Server process can collide with the shared memory segment required by the queue manager. By default, the EAI MQSeries queue manager attempts to use shared memory segment number 8. The EAI MQSeries Server Transport does not rely on any specific number and uses whatever segment is given to the process by the AIX operating system.

However, if you are using the default configuration, then there is a possibility that the EAI MQSeries Server process gets segment number 8 from the operating system first, and as a result the queue manager cannot get its segment. In this case, the EAI MQSeries Server Transport service fails with an error code of 2059 because it cannot connect to the queue manager.

Fixing a Shared Memory Segment Conflict on AIX

You edit the mqs.ini file, found in the /var/mqm directory, to fix a shared memory segment conflict with the EAI MQSeries Server Transport on AIX.

To fix a shared memory segment conflict with the EAI MQSeries Server Transport on AIX

Shut down any queue manager connected to the EAI MQSeries Transport.
Edit the /var/mqm/mqs.ini file.
In the QueueManager section for each queue manager of interest, add an additional line explicitly specifying the shared memory segment to use. For example:
```
QueueManager:
Name=myQueueManager
Prefix=/var/mqm
Directory=myQueueManager
IPCCBaseAddress=12
```
Restart each queue manager.

Note: This example shows shared number 12 as the memory segment number. Valid values for the IPCCBaseAddress are 4, 5, 8, 9, 10, 11, and 12, although 8 has been found to be problematic. It is possible to get a shared memory segment conflict even with the number set to 12, if the operating system has allocated segment 12 to the EAI MQSeries Server process ahead of the queue manager. If this is the case, then a different segment number must be specified.

Configuring AIX to Run the Siebel Server with Less Memory

If the EAI MQSeries Server Transport business service on AIX continues to fail even after you have followed the previous procedures, then you can configure the AIX environment to run Siebel Server with less memory using the environment variable LDR_CNTRL. After you have finished, follow the procedures in the preceding topic. For more information about setting parameters for AIX, see Siebel Performance Tuning Guide.

To configure the AIX environment to run the Siebel Server with less memory

Shut down the Siebel Server.
In the shell that you use to bring up the Siebel Server, set the environment variable LDR_CNTRL. Using csh:
```
setenv LDR_CNTRL MAXDATA=0x30000000
```
Note: You can save the setting in the siebenv.sh or siebenv.csh.
Restart the Siebel Server with this environment variable.

About EAI MQSeries Transport Re-Entrance

The EAI MQSeries Server Receiver uses the EAI MQSeries Server Transport business service but cannot dispatch to a workflow that either uses this business service as one of its steps or dispatches directly to this business service.

While in-process re-entrance is not supported, you can indirectly invoke the EAI MQSeries Server Transport as one of the steps out of process by calling the Synchronous Server Requests business service.

About Message ID Tracking for an Inbound Message

You can keep track of Message IDs of inbound messages by creating a process property, MsgId, of type String, and then adding an output argument with the following configuration to the Send step of your process as shown in the following table.

Type	Output Argument
Output Argument	MQSeries Message Identifier

This captures the Message IDs for the Queue Manager assigned to the messages in the MsgId process property.

Invoking a Workflow Using MQSeries Server Receiver

Following are examples of commands to create named subsystems and start a MQSeries Server Receiver to invoke a workflow.

Note: If there is either an exception step or an error process in your workflow, then the workflow assumes that the error step or the error process handles the error and the workflow does not send the error out. To capture the error, insert a stop step into your workflow. Note that by adding a stop step, the caller gets the generic workflow stop error and not the original error, but the original error is stored in the Error Code and Error Message process properties.

Command to Create an EAI Transport Data Handling Subsystem

The following command creates an EAI Transport Data Handling Subsystem:

create named subsystem MYDataSubSys for subsystem EAITransportDataHandlingSubsys 
with DispatchWorkflowProcess="MQ Inbound Workflow"

Command to Create an EAI Transport Connection Subsystem

The following command creates an EAI Transport Connection Subsystem:

create named subsystem MYSubSys for subsystem mqseriesserversubsys with 
MQQueueManagerName=QueueMgr, MQPhysicalQueueName=LocalQueue

Command to Start an MQSeries Server Receiver

The following command starts an MQSeries Server Receiver:

start task for component MqSeriesSrvRcvr with ReceiverConnectionSubsystem=MYSubSys, 
ReceiverDataHandlingSubsystem=MYDataSubSys, ReceiverMethodName=ReceiveDispatch

When calling your workflow by the MQSeries Server Receiver, it is not necessary to include a step to pull the messages off the queue and pass them to the next step. The MQSeries Server Receiver automatically pulls the messages off the queue and passes them on if:

You have created a new process property of data type String and a default string of <Value>. This process property stores the inbound message text picked up by the MqSeriesSrvRcvr.
In your workflow step, where you handle the inbound messages from IBM WebSphere MQ, you insert an input argument of <Value> with type Process Property. The Property Name is the name of the process property that you created in the previous step.

Note: When you type in <Value>, the display name might change to Message Text or XML Document.