Connector configuration

Connectors have two types of configuration properties: standard configuration properties and adapter-specific configuration properties. You must set the values of these properties before running the adapter.

You use Connector Configurator to configure connector properties:

A connector obtains its configuration values at startup. During a runtime session, you may want to change the values of one or more connector properties. Changes to some connector configuration properties, such as AgentTraceLevel, take effect immediately. Changes to other connector properties require component restart or system restart after a change. To determine whether a property is dynamic (taking effect immediately) or static (requiring either connector component restart or system restart), refer to the Update Method column in the Connector Properties window of Connector Configurator.

Standard connector properties

Standard configuration properties provide information that all connectors use. See Appendix A, Standard configuration properties for connectors for documentation of these properties.

Note:
When you set configuration properties in Connector Configurator, you specify your broker using the BrokerType property. Once this is set, the properties relevant to your broker will appear in the Connector Configurator window.

Connector-specific properties

Connector-specific configuration properties provide information needed by the connector agent at runtime. connector-specific properties also provide a way of changing static information or logic within the connector agent without having to recode and rebuild the agent.

Table 13 lists the connector-specific configuration properties for the connector. See the sections that follow for explanations of the properties.

Table 13. Connector-specific configuration properties
Name Possible values Default value Required
ArchiveQueue Queue to which copies of successfully processed messages are sent
CWLD_ARCHIVE
 
No
CCSID Character set for queue manager connection null Yes
ConfigurationMetaObject Configuration meta-object

 
Yes
DataHandlerClassName Name of data handler class

 
No
DataHandlerConfigMO Name of data handler configuration meta-object
MO_DataHandler_
 Default
 
No
DataHandlerMimeType Mime type of file

 
No
ErrorQueue Queue for unprocessed messages
CWLD_ERROR
 
No
InDoubtEvents
FailOnStartup
 Reprocess
 Ignore
 LogError
 
Reprocess
 
No
InProgressQueue In-progress event queue
CWLD_InProgress
 
No
InputQueue Name of poll queues
CWLD_Input
 
Yes
LookupQueuesUsingJNDI true or false
false
 
No
MessageFormatProperty Property name specifying message format
JMSType
 
No
MessageResponseResultProperty Property in response message that indicates the result of the request operation
CWLD_Result
 
Yes
PollQuantity Number of messages to retrieve from each queue specified in the InputQueue property
1
 
No
QueueConnectionFactoryName Name of connection factory to look up using JNDI context

 
Yes
ReplyToQueue Queue to which response messages are delivered when the connector issues requests
CWLD_REPLYTO
 
No
UnsubscribedQueue Queue to which unsubscribed messages are sent
CWLD_UNSUBSCRIBED
 
No
UseDefaults true or false false

ArchiveQueue

Queue to which copies of successfully processed messages are sent.

The default value is CWLD_ARCHIVE.

CCSID

The character set for the queue manager connection.

Default = null.

ConfigurationMetaObject

Name of static meta-object containing configuration information for the connector.

There is no default value.

DataHandlerClassName

Data handler class to use when converting messages to and from business objects.

DataHandlerConfigMO

Name of data handler meta-object. Provides configuration information for the data handler.

The default value is MO_DataHandler_Default.

DataHandlerMimeType

Allows you to request a data handler based on a particular MIME type.

ErrorQueue

Queue to which messages that could not be processed are sent.

The default value is CWLD_ERROR.

InDoubtEvents

Specifies how to handle in-progress events that are not fully processed due to unexpected connector shutdown. Choose one of four actions to take if events are found in the in-progress queue during initialization:

The default value is Reprocess.

InProgressQueue

Message queue where messages are held during processing. You can configure the connector to operate without this queue by using System Manager to remove the default InProgressQueue name from the connector-specific properties. Doing so prompts a warning at startup that event delivery may be compromised if the connector is shut down while are events pending.

The default value is CWLD_InProgress.

InputQueue

Message queues that will be polled by the connector for new messages. The connector accepts multiple semi-colon delimited queue names. For example, to poll the following three queues: MyQueueA, MyQueueB, and MyQueueC, the value for connector configuration property InputQueue would equal: MyQueueA;MyQueueB;MyQueueC.

If the InputQueue property is not supplied, the connector will start up properly, print a warning message, and perform request processing only. It will perform no event processing.

The connector polls the queues in a round-robin manner and retrieves up to pollQuantity number of messages from each queue. For example, if pollQuantity equals 2, and MyQueueA contains 2 messages, MyQueueB contains 1 message and MyQueueC contains 5 messages, the connector retrieves messages in the following manner:

Since we have a pollQuanity of 2, the connector will retrieve at most 2 messages from each queue per call to pollForEvents. For the first cycle (1 of 2), the connector retrieves the first message from each of MyQueueA, MyQueueB, and MyQueueC. That completes the first round of polling and if we had a pollQuantity of 1, the connector would stop. Since we have a pollQuanity of 2, the connector starts a second round of polling (2 of 2) and retrieves one message each from MyQueueA and MyQueueC--it skips MqQueueB since it is now empty. After polling all queues 2x each, the call to the method pollForEvents is complete. Here's the sequence of message retrieval:

  1. 1 message from MyQueueA
  2. 1 message from MyQueueB
  3. 1 message from MyQueueC
  4. 1 message from MyQueueA
  5. Skip MyQueueB since it's now empty
  6. 1 message from MyQueueC

The default value is CWLD_Input.

LookupQueuesUsingJNDI

If this property is true, the connector assumes that queue names represent stored objects in the JNDI context, and resolves the queue name by looking it up in the configured JNDI store. A queue object must exist in the store and be associated with the name provided. When this property is false, the connector passes the queue name to the JMS provider and allows it to resolve it in a vendor-specific manner.

The default value is false.

MessageFormatProperty

Property name specifying message format. This value determines the conversion properties used during subscription delivery and is then set for output messages. If value is JMSType or unspecified, the connector uses the JMS message type as the format.

The default value is JMSType.

MessageResponseResultProperty

Property in response message that indicates the result of the request operation. The default value is CWLD_Result.

PollQuantity

Number of messages to retrieve from each queue specified in the InputQueue property during a pollForEvents scan.

The default value is 1.

QueueConnectionFactoryName

Name of connection factory to look up using JNDI context.

ReplyToQueue

Queue to which response messages are delivered when the connector issues requests. You can also use attributes in the child dynamic meta-object to ignore a response. For more information on the these attributes, see JMS headers and dynamic child meta-object Attributes

The default value is CWLD_REPLYTO.

UnsubscribedQueue

Queue to which unsubscribed messages are sent.

The default value is CWLD_UNSUBSCRIBED.

UseDefaults

On a Create operation, if UseDefaults is set to true, the connector checks whether a valid value or a default value is provided for each isRequired business object attribute. If a value is provided, the Create operation succeeds. If the parameter is set to false, the connector checks only for a valid value and causes the Create operation to fail if it is not provided. The default is false.

JNDI provider properties

This section describes connector properties for establishing the context of a Java Naming and Directory Interface (JNDI) provider. This information is taken from J2EE (Java 2 Enterprise Edition). For more information on JNDI environment variables and configuration, see www.javasoft.com. For information on configuring JNDI with the MA88 Patch, see Configuring JNDI with WebSphere MQ Java client libraries.

Table 14. Java Naming and Directory Interface (JNDI) provider properties
Property Name Description
CTX_InitialContextFactory
 
Fully qualified class name of the factory class that will create an initial context. (e.g "com.sun.jndi.fscontext")
CTX_ProviderURL
 
Configuration information for the service provider to use. The value of the property should contain a URL (e.g. "ldap://somehost:389")
CTX_ObjectFactories
 

CTX_StateFactories
 

CTX_URLPackagePrefixes
 

CTX_DNS_URL
 

CTX_Authoritative
 

CTX_Batchsize
 

CTX_Referral
 

CTX_SecurityProtocol
 

CTX_SecutiryAuthentication
 

CTX_SecurityPrincipal
 

CTX_SecurityCredentials
 

CTX_Language
 
Properties specifying additional information about security and object lookup in the JNDI context. See J2EE documentation for more information.

Configuring JNDI with WebSphere MQ Java client libraries

This section describes how to configure JNDI with WebSphere MQ Java client libraries. If you are using WebSphere MQ V5.2 or earlier, you must download these libraries from www.ibm.com/support/us/ and install them. Note that the download may be referred to on the site as "SupportPac MA88."

If you are using WebSphere MQ V5.3, the client libraries are packaged with the product and thus you are not required to perform the following steps.

  1. Download and install the MQ Java client libraries.
  2. Modify the classpath and variables as follows:
    SET PATH=%PATH%;"%MQ_JAVA_INSTALL_PATH%"\lib
     SET CP="%MQ_JAVA_INSTALL_PATH%"\lib\fscontext.jar;
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\jms.jar
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\jndi.jar
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\jta.jar
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\ldap.jar
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\providerutil.jar
     SET CP=%CP%;%CROSSWORLDS%\rt.jar;
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\com.ibm.mq.jar;
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\com.ibm.mq.iiop.jar;
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\com.ibm.mqbind.jar;
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib;
     SET CP=%CP%;"%MQ_JAVA_INSTALL_PATH%"\lib\com.ibm.mqjms.jar
     SET CLASSPATH=%CP%;%CLASSPATH%
     
  3. Add %CP% to the -classpath in
    %MQ_JAVA_INSTALL_PATH%\bin\JMSAdmin.bat and start_JMS.bat:
     
  4. Modify
    %MQ_JAVA_INSTALL_PATH%\bin\JMSAdmin.config
     

    as follows:

    INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory
     PROVIDER_URL=file:/C:/JNDI-Directory
     SECURITY_AUTHENTICATION=none
     

    where PROVIDER_URL points to an existing directory where the.bindings file will be created.

  5. Create queues for the default queue manager.
  6. Create the .jndi file. Here is a sample:

    *

    *  JNDI Configured Objects for Information Pipeline
     *  Used by WebSphere MQ JMS*
     *
     *
     DEFINE QCF(ISSMWS14QCF) +
     TRAN(client) HOST(MZIBERW2K) PORT(1414) +
     CHANNEL(CHANNEL1) CLIENTID(' ')
     *
     * Queues
     *
     DEFINE Q(INPUTQ) +
     QUEUE(INPUTQ) +
     TARGCLIENT(JMS)
     *
     DEFINE Q(REPLYQ) +
     QUEUE(REPLYQ) +
     TARGCLIENT(JMS)
     

    where MZIBERW2K is the name of the host machine,

    CHANNEL1 is the name of the channel, and

    INPUTQ and REPLYQ are the Q names.

  7. Change directories to %MQ_JAVA_INSTALL_PATH%\bin and run JMSAdmin:
    >JMSAdmin.bat<sample.jndi
     

    where sample.jndi is the file created in step 3.

The result should be a .binding file in the directory specified in PROVIDER_URL.

Copyright IBM Corp. 1997, 2003