Configuring Standard Connector Properties for WebSphere InterChange Server

This section describes standard configuration properties applicable to connectors whose integration broker is WebSphere InterChange Server (ICS). Standard configuration properties provide information that is used by a configurable component of InterChange Server called the connector controller. Like the connector framework, the code for the connector controller is common to all connectors. However, you configure a separate instance of the controller for each connector.

A connector, which consists of the connector framework and the application-specific component, has been referred to historically as the connector agent. When a standard configuration property refers to the agent, it is referring to both the connector framework and the application-specific component.

For general information about how connectors work with InterChange Server, see the Technical Introduction to IBM WebSphere InterChange Server.

Important:
Not all properties are applicable to all connectors that use InterChange Server. For information specific to an connector, see its adapter guide.

You configure connector properties from Connector Configurator, which you access from System Manager.

Note:
Connector Configurator and System Manager run only on the Windows system. Even if you are running the connector on a UNIX system, you must still have a Windows machine with these tools installed. Therefore, to set connector properties for a connector that runs on UNIX, you must start up System Manager on the Windows machine, connect to the UNIX InterChange Server, and bring up Connector Configurator for the connector.

A connector obtains its configuration values at startup. If you change the value of one or more connector properties during a runtime session, the property's update semantics determine how and when the change takes effect. There are four different types of update semantics for standard connector properties:

To determine the update semantics for a specific property, refer to the Update Method column in the Connector Configurator window, or see the Update Method column of the table below.

The following table provides a quick reference to the standard connector configuration properties. You must set the values of some of these properties before running the connector. See the sections that follow for explanations of the properties.
Property Name Possible
Values
Default
Value
Update
Method
Notes
AdminInQueue valid JMS queue name CONNECTORNAME /ADMININQUEUE






AdminOutQueue valid JMS queue name CONNECTORNAME/ADMINOUTQUEUE

AgentConnections 1-4 1 server restart multi-threaded connector only
AgentTraceLevel 0-5 0 dynamic





ApplicationName application name the value that is specified for the connector name component restart value required
BrokerType ICS, WMQI

ICS is required if your broker is ICS
CharacterEncoding ascii7, ascii8, SJIS, Cp949, GBK, Big5, Cp297,Cp273,Cp280, Cp284,Cp037, Cp437 ascii7 component restart
ConcurrentEventTriggeredFlows 1 to 32,767 no value component restart
ContainerManagedEvents JMS or no value JMS
guaranteed event delivery
ControllerStoreAndForwardMode true or false true dynamic
ControllerTraceLevel 0-5 0 dynamic
DeliveryQueue
CONNECTORNAME/DELIVERYQUEUE component restart JMS transport only
DeliveryTransport MQ, IDL, or JMS IDL component restart
FaultQueue
CONNECTORNAME/FAULTQUEUE component restart
DuplicateEventElimination True/False False component restart JMS transport only, ContainerManagedEvents must be <NONE>
JvmMaxHeapSize heap size in megabytes 128m component restart
JvmMaxNativeHeapSize size of stack in kilobytes 128k component restart
JvmMinHeapSize heap size in megabytes 1m component restart
jms.MessageBrokerName If FactoryClassName is IBM, use crossworlds.queue.manager. If FactoryClassName is Sonic, use localhost:2506. crossworlds.queue.manager server restart JMS transport only
jms.FactoryClassName CxCommon.Messaging. jms.IBMMQSeriesFactory or CxCommon.Messaging. jms.SonicMQFactory or any Java class name CxCommon.Messaging. jms.IBMMQSeriesFactory server restart JMS transport only
jms.NumConcurrentRequests positive integer 10 component restart JMS transport only
jms.Password Any valid password
server restart JMS transport only
jms.UserName Any valid name
server restart JMS transport only
Locale en_US , ja_JP, ko_KR, zh_C, zh_T, fr_F, de_D, it_I, es_E, pt_BR
Note:
These are only a subset of supported locales.
en_US component restart
LogAtInterchangeEnd true or false false component restart
MaxEventCapacity 1-2147483647 2147483647 dynamic RepositoryDirectory value must be <REMOTE>
MessageFileName path/filename Connectorname.txt or InterchangeSystem.txt component restart
MonitorQueue any valid queue name CONNECTORNAME/MONITORQUEUE component restart JMS transport only, DuplicateEventElimination must be True
OADAutoRestartAgent true or false false dynamic
OADMaxNumRetry a positive number 1000 dynamic
OADRetryTimeInterval a positive number in minutes 10 dynamic
PollEndTime HH:MM HH:MM component restart
PollFrequency a positive integer in milliseconds

no (to disable polling) key (to poll only when the letter p is entered in the connector's Command Prompt window)

10000 dynamic
PollQuantity 1-500 1 component restart Number of items to poll from application
PollStartTime HH:MM(HH is 0-23, MM is 0-59) HH:MM component restart
RepositoryDirectory location where repository is located <REMOTE> component restart <REMOTE> for ICS broker
RequestQueue valid JMS queue name CONNECTORNAME/REQUESTQUEUE component restart
ResponseQueue valid JMS queue name CONNECTORNAME/RESPONSEQUEUE component restart
RestartRetryCount 0-99 3 dynamic
RestartRetryInterval a sensible positive value in minutes 1 dynamic
SourceQueue valid MQSeries queue name CONNECTORNAME/SOURCEQUEUE component restart

Valid only if delivery transport is JMS and ContainerManagedEventsis specified.

SynchronousRequestQueue
CONNECTORNAME/ SYNCHRONOUSREQUESTQUEUE component restart
SynchronousResponseQueue
CONNECTORNAME/ SYNCHRONOUSRESPONSEQUEUE component restart
SynchronousRequestTimeout
0 component restart
WireFormat CwXML, CwBO cwxml agent restart CwXML for non-ICS broker; CwBO if RepositoryDirectory is <REMOTE>

AdminInQueue

The queue that is used by the integration broker to send administrative messages to the connector.

The default value is CONNECTORNAME/ADMININQUEUE.

AdminOutQueue

The queue that is used by the connector to send administrative messages to the integration broker.

The default value is CONNECTORNAME/ADMINOUTQUEUE.

AgentConnections

The AgentConnections property controls the number of IIOP connections opened for request transport between an application-specific component and its connector controller. By default, the value of this property is set to 1, which causes InterChange Server to open a single IIOP connection.

This property enhances performance for a multi-threaded connector by allowing multiple connections between the connector controller and application-specific component. When there is a large request/response workload for a particular connection, the IBM WebSphere administrator can increase this value to enhance performance. Recommended values are in the range of 2 to 4. Increasing the value of this property increases the scalability of the Visigenic software, which establishes the IIOP connections. You must restart the application-specific component and the server for a change in property value to take effect.

Important:
If a connector is single-threaded, it cannot take advantage of the multiple connections. Increasing the value of this property causes the request transport to bottleneck at the application-specific component. To determine whether a specific connector is single- or multi-threaded, see the installing and configuring chapter of its adapter guide.

AgentTraceLevel

Level of trace messages for the application-specific component. The default is 0. The connector delivers all trace messages applicable at the tracing level set or lower.

ApplicationName

Name that uniquely identifies the connector's application. This name is used by the system administrator to monitor the WebSphere business integration system environment. This property must have a value before you can run the connector.

BrokerType

Identifies the integration broker type that you are using. If you are using an ICS connector, this setting must be ICS.

CharacterEncoding

Specifies the character code set used to map from a character (such as a letter of the alphabet, a numeric representation, or a punctuation mark) to a numeric value.

Note:
Java-based connectors do not use this property. A C++ connector currently uses the value ASCII for this property. If you previously configured the value of this property to ascii7 or ascii8, you must reconfigure the connector to use either ASCII or one of the other supported values. To determine whether a specific connector is written in Java or C++, see the installing and configuring chapter of its adapter guide.
Important:
By default only a subset of supported character encodings display in the drop list. To add other supported values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product directory. For more information, see the appendix on Connector Configurator.

Attention: Do not run a non-internationalized connector against InterChange Server version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will be processed.

The default value is ascii.

ConcurrentEventTriggeredFlows

Determines how many business objects can be concurrently processed by the connector controller for event delivery. Set the value of this attribute to the number of business objects you want concurrently mapped and delivered. For example, set the value of this property to 5 to cause five business objects to be concurrently processed. The default value is 1.

Setting this property to a value greater than 1 allows a connector controller for a source application to simultaneously map multiple event business objects, and to simultaneously deliver them to multiple collaboration instances. Setting this property to enable concurrent mapping of multiple business objects can speed delivery of business objects to a collaboration, particularly if the business objects use complex maps. Increasing the arrival rate of business objects to collaborations can improve overall performance in the system.

Note:
To implement concurrent processing for an entire flow (from a source application to a destination application) also requires that the collaboration be configured to use multiple threads and that the destination application's application-specific component be able to process requests concurrently. To configure the collaboration, set its Maximum number of concurrent events property high enough to use multiple threads. For an application-specific component to process requests concurrently, it must be either multi-threaded, or be capable of using Connector Agent Parallelism and be configured for multiple processes (setting the Parallel Process Degree configuration property greater than 1).
Important:
To determine whether a specific connector is single- or multi-threaded, see the installing and configuring chapter of its adapter guide.

The ConcurrentEventTriggeredFlows property has no effect on connector polling, which is single-threaded and performed serially.

ContainerManagedEvents

Setting this property to JMS allows a JMS-enabled connector with a JMS event store to provide guaranteed event delivery, in which an event is removed from the source queue and placed on the destination queue as a single JMS transaction. This property can also be set to no value.

Notes:

  1. When ContainerManagedEvents is set to JMS, you must also configure the following properties to enable guaranteed event delivery: PollQuantity = 1 to 500, SourceQueue = SOURCEQUEUE. In addition, you must configure a data handler with the MimeType, DHClass, and DataHandlerConfigMOName (optional) properties. To set those values, use the Data Handler tab of Connector Configurator. The fields for the values under the Data Handler tab will be displayed only if you have set ContainerManagedEvents to JMS.

  2. When ContainerManagedEvents is set to JMS, the connector does not call its pollForEvents() method, thereby disabling that method's functionality.

The default value is JMS.

This property only appears if the DeliveryTransport property is set to the value JMS.

ControllerStoreAndForwardMode

Sets the behavior of the connector controller after it detects that the destination application-specific component is unavailable. If this property is set to true and the destination application-specific component is unavailable when an event reaches InterChange Server, the connector controller blocks the request to the application-specific component. When the application-specific component becomes operational, the controller forward the request to it.

Important:
If the destination application's application-specific component becomes unavailable after the connector controller forwards a service call request to it, the connector controller fails the request.

If this property is set to false, the connector controller begins failing all service call requests as soon as it detects that the destination application-specific component is unavailable.

The default is true.

ControllerTraceLevel

Level of trace messages for the connector controller. The default is 0.

DeliveryQueue

The queue that is used by the connector to send business objects to the integration broker.

The default value is DELIVERYQUEUE.

DeliveryTransport

Specifies the transport mechanism for the delivery of events. Possible values are MQ for WebSphere MQ, IDL for CORBA IIOP, or JMS for Java Messaging Service.

If ICS is the broker type, the value of the DeliveryTransport property can be MQ, IDL, or JMS, and the default is IDL.

If WMQI is the broker type, JMS is the only possible Delivery Transport value.

The connector sends service call requests and administrative messages over CORBA IIOP if the value configured for the DeliveryTransport property is MQ or IDL.

WebSphere MQ and IDL

Use WebSphere MQ rather than IDL for event delivery transport, unless you have compelling reasons not to license and maintain two separate products. WebSphere MQ offers the following advantages over IDL:

JMS

Enables communication between the connector controller and client connector framework using Java Messaging Service (JMS).

If you select JMS as the delivery transport, additional JMS properties such as "jms.MessageBrokerName," "jms.FactoryClassName," "jms.Password," and "jms.UserName," display in Connector Configurator. The first two of these properties are required for this transport.

Important:
There may be a memory limitation if you use the JMS transport mechanism for a connector in the following environment:

In this environment, you may experience difficulty starting the both the connector controller (on the server side) and the connector (on the client side) due to memory use within the WebSphere MQ client. If your installation uses less than 768M of process heap size, IBM recommends that you set:

Notes:

DuplicateEventElimination

Setting this property to true enables a JMS-enabled connector with a non-JMS event store to ensure that duplicate events are not delivered to the delivery queue. To make use of this feature, during connector development a unique event identifier must be set as the business object's ObjectEventId attribute in the application specific code.

This property can also be set to false.

Note:
When DuplicateEventElimination is set to true, you must also configure the MonitorQueue property to enable guaranteed event delivery.

FaultQueue

If the connector experiences an error while processing a message then the connector moves the message to the queue specified in this property, along with a status indicator and a description of the problem.

The default value is CONNECTORNAME/FAULTQUEUE.

JvmMaxHeapSize

The maximum heap size for the agent (in megabytes). This property is applicable only if the RepositoryDirectory value is <REMOTE>.

The default value is 128m.

JvmMaxNativeStackSize

The maximum native stack size for the agent (in kilobytes). This property is applicable only if the RepositoryDirectory value is <REMOTE>.

The default value is 128k.

JvmMinHeapSize

The minimum heap size for the agent (in megabytes). This property is applicable only if the RepositoryDirectory value is <REMOTE>.

The default value is 1m.

jms.FactoryClassName

Specifies the class name to instantiate for a JMS provider. You must set this connector property when you choose JMS as your delivery transport mechanism (DeliveryTransport).

The default is CxCommon.Messaging.jms.IBMMQSeriesFactory.

jms.MessageBrokerName

Specifies the broker name to use for the JMS provider. You must set this connector property when you choose JMS as your delivery transport mechanism (DeliveryTransport).

The default is crossworlds.queue.manager.

jms.NumConcurrentRequests

Specifies the maximum number of concurrent service call requests that can be sent to a connector at the same time. Once that maximum is reached, new service calls block and wait for another request to complete before proceeding.

The default value is 10.

jms.Password

Specifies the password for the JMS provider. A value for this property is optional.

There is no default.

jms.UserName

Specifies the user name for the JMS provider. A value for this property is optional.

There is no default.

Locale

Specifies the language code, country or territory, and, optionally, the associated character code set. The value of this property determines such cultural conventions as collation and sort order of data, date and time formats, and the symbols used in monetary specifications. For more information, see the overview chapter of the connector guide for an internationalized connector.

A locale name has the following format:

ll_TT.codeset
 

where:

ll
a two-character language code (usually in lower case)

TT
a two-letter country or territory code (usually in upper case)

codeset
the name of the associated character code set; this portion of the name is often optional.

The default is en_US.

Important:
By default only a subset of supported locales display in the drop list. To add other supported values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product directory. For more information, see the appendix on Connector Configurator.

Attention: If the connector has not been internationalized, the only valid value for this property is en_US. Do not run a non-internationalized C++ connector against InterChange Server version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will be processed. To determine whether a specific connector has been internationalized, see the installing and configuring chapter of its connector guide.

LogAtInterchangeEnd

Specifies whether to log errors to InterChange Server's log destination, in addition to the location specified in the LogFileName property. Logging to the server's log destination also turns on email notification, which generates email messages for the MESSAGE_RECIPIENT specified in the InterchangeSystem.cfg file when errors or fatal errors occur. As an example, when a connector loses its connection to its application, if LogAtInterChangeEnd is set to true, an email message is sent to the specified message recipient. The default is false.

MaxEventCapacity

The maximum number of events in the controller buffer. This property is used by flow control and is applicable only if the value of the RepositoryDirectory property is <REMOTE>.

The value can be a positive integer between 1 and 2147483647. The default value is 2147483647.

MessageFileName

The name of the connector message file. The standard location for the message file is \connectors\messages. Specify the message filename in an absolute path if the message file is not located in the standard location.

If a connector message file does not exist, the connector uses InterchangeSystem.txt as the message file. This file is located in the product directory.

Important:
To determine whether a specific connector has its own message file, see the installing and configuring chapter of its adapter guide.

OADAutoRestartAgent

Specifies whether the Object Activation Daemon (OAD) automatically attempts to restart the application-specific component after an abnormal shutdown. The properties OADMaxNumRetry and OADRetryTimeInterval are related to this property. This property is required for automatic restart.

The default value is false.

OADMaxNumRetry

Specifies the maximum number of times that the OAD automatically attempts to restart the application-specific component after an abnormal shutdown.

The default value is 1000.

OADRetryTimeInterval

Specifies the number of minutes of the retry time interval that the OAD automatically attempts to restart the application-specific component after an abnormal shutdown. If the application-specific component does not start within the specified interval, the OAD repeats the attempt as many times as specified in OADMaxNumRetry.

The default is 10.

PollEndTime

Time to stop polling the event queue. The format is HH:MM, where HH represents 0-23 hours, and MM represents 0-59 seconds.

You must provide a valid value for this property. The default value is HH:MM, but must be changed.

PollFrequency

The amount of time between polling actions. Set PollFrequency to one of the following values:

The default is 10000.

Important:
Some connectors have restrictions on the use of this property. To determine whether a specific connector does, see the installing and configuring chapter of its adapter guide.

PollStartTime

The time to start polling the event queue. The format is HH:MM, where HH represents 0-23 hours, and MM represents 0-59 seconds.

You must provide a valid value for this property. The default value is HH:MM, but must be changed.

RequestQueue

The queue that is used by the integration broker to send business objects to the connector.

The default value is REQUESTQUEUE.

RepositoryDirectory

The location of the repository from which the connector reads the XML schema documents that store the meta-data of business object definitions.

When the integration broker is ICS, this value must be set to <REMOTE> because the connector uses the InterChange Server repository to obtain its connector-definition information

ResponseQueue

Designates the JMS response queue, which delivers a response message from the connector framework to the integration broker. When the integration broker is InterChange Server, InterChange Server sends the request and waits for a response message in the JMS response queue.

RestartRetryCount

Specifies the number of times the connector attempts to restart itself. When used for a parallel connector, specifies the number of times the master connector application-specific component attempts to restart the slave connector application-specific component.

The default is 3.

RestartRetryInterval

Specifies the interval in minutes at which the connector attempts to restart itself. When used for a parallel connector, specifies the interval at which the master connector application-specific component attempts to restart the slave connector application-specific component.

The default is 1.

SourceQueue

Designates the JMS source queue for the connector framework in support of guaranteed event delivery for JMS-enabled connectors that use a JMS event store. For further information, see ContainerManagedEvents.

The default value is SOURCEQUEUE.

SynchronousRequestQueue

Delivers request messages that require a synchronous response from the connector framework to the broker. This queue is necessary only if the connector uses synchronous execution. With synchronous execution, the connector framework sends a message to the SynchronousRequestQueue and waits for a response back from the broker on the SynchronousResponseQueue. The response message sent to the connector bears a correlation ID that matches the ID of the original message.

SynchronousResponseQueue

Delivers response messages sent in reply to a synchronous request from the broker to the connector framework. This queue is necessary only if the connector uses synchronous execution.

SynchronousRequestTimeout

Specifies the time in minutes that the connector waits for a response to a synchronous request. If the response is not received within the specified time then the connector moves the original synchronous request message into the fault queue along with an error message.

The default value is 0.

TraceFileName

The name of the file where the application-specific component writes trace messages. Specify the filename in an absolute path. The default is STDOUT.

WireFormat

Message format on the transport.

Possible values are:

Copyright IBM Corp. 1997, 2003