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.
You configure connector properties from Connector Configurator, which you access from System Manager.
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
| 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> |
The queue that is used by the integration broker to send administrative messages to the connector.
The default value is CONNECTORNAME/ADMININQUEUE.
The queue that is used by the connector to send administrative messages to the integration broker.
The default value is CONNECTORNAME/ADMINOUTQUEUE.
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.
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.
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.
Identifies the integration broker type that you are using. If you are using an ICS connector, this setting must be ICS.
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.
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.
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.
The ConcurrentEventTriggeredFlows property has no effect on connector polling, which is single-threaded and performed serially.
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:
The default value is JMS.
This property only appears if the DeliveryTransport property is set to the value JMS.
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.
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.
Level of trace messages for the connector controller. The default is 0.
The queue that is used by the connector to send business objects to the integration broker.
The default value is DELIVERYQUEUE.
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.
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:
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.
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:
This script resides in the \bin directory below the product directory. With a text editor, add the following line as the first line in the CWSharedEnv.sh script:
export LDR_CNTRL=MAXDATA=0x30000000
This line restricts heap memory usage to a maximum of 768 MB (3 segments * 256 MB). If the process memory grows more than this limit, page swapping can occur, which can adversely affect the performance of your system.
Notes:
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.
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.
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.
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.
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.
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.
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.
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.
Specifies the password for the JMS provider. A value for this property is optional.
There is no default.
Specifies the user name for the JMS provider. A value for this property is optional.
There is no default.
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:
The default is en_US.
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.
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.
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.
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.
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.
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.
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.
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.
The amount of time between polling actions. Set PollFrequency to one of the following values:
The default is 10000.
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.
The queue that is used by the integration broker to send business objects to the connector.
The default value is REQUESTQUEUE.
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
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.
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.
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.
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.
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.
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.
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.
The name of the file where the application-specific component writes trace messages. Specify the filename in an absolute path. The default is STDOUT.
Message format on the transport.
Possible values are: