Configuring the connector

The Connector Configurator tool provides a graphical user interface for configuring the connector. When you are finished specifying values for the connector's configuration properties, the Connector Configurator generates a configuration file for the connector and places it in the connector's local repository.

Important:
If the business integration adapter is running on UNIX, you must create the configuration file using Connector Configurator on Windows and then copy the file to your UNIX machine. When you create the configuration file, make sure that you observer UNIX path and file name conventions when setting properties.

When you ran the IBM WebSphere Business Integration adapter installer, it loaded a connector definition file for the connector in ProductDir\connectors\repository\ConnName. The connector definition file provides initial values for some configuration file properties. The next step is to use Connector Configurator to create a configuration file for the connector. While the connector definition file provides some starting values for the configuration file, the configuration file contains all the standard and application-specific properties for the connector, and specifies its supported business objects. Appendix C, Standard configuration properties for connectors, describes these properties in detail.

If you manually installed a new connector (one not pre-built by IBM) you must create a new configuration file for that connector, using Connector Configurator.

Tip

Use the information provided below together with the adapter user guide for the connector you are configuring, which contains:

  • Complete instructions for using Connector Configurator
  • Detailed information about the supported settings for the connector's standard properties, application-specific properties, and logging and tracing options.

The sections below discuss Connector Configurator settings that apply to every connector working with a WebSphere message broker.

Specifying the location of the connector's local repository

You can specify the location you want to use for the local repository using the standard property, RepositoryDirectory. The default location is ProductDir\repository.

Specifying the queues to be used by the connector

In Configuring the WebSphere MQ queues, you defined a set of queues to be used by the connector to communicate with the message broker. In the Connector Configurator, click the Standard Properties tab and assign these queues to the connector using the following standard properties:

Setting the connection mode with the queue manager

The default connection mode is bindings mode. Specify client mode as follows:

  1. In the Connector Configurator, click the Standard Properties tab.
  2. Assign to the standard property, jms.MessageBrokerName, the following value: QueueMgrName:[Channel]:[HostName]:[PortNumber], where the variables represent the following:
    QueueMgrName
    The name of the queue manager.
    Channel
    The channel used by the client.
    HostName
    The name of the machine where the queue manager is to reside.
    PortNumber
    The port number to be used by the queue manager for listening.

For example:

jms.MessageBrokerName = WMQIB.Queue.Manager:CHANNEL1:RemoteMachine:1456
 

Setting configuration properties for synchronous execution

If your connector uses synchronous execution, click the Standard Properties tab and set the following properties:

Configuring logging and tracing options

Logging is used to communicate system messages, component state changes, failures, and tracing information. The following files are generated:

Table 12. Connector logging and tracing files.

Default file name and path Description

Temporary log file:

ProductDir\broker_name_connector_name_tmp.log.

During startup, the connector generates a temporary log file. This file contains all messages that are logged during startup, including connector properties and business object definitions that are passed to the connector framework. and the file is written to the directory in which the product is installed.

Connector log file:

UNIX: A connector logs messages to STDOUT by default, then those messages are rerouted to ProductDir/logs/connector_manager_ConnName .log.

WINDOWS: A connector logs messages to STDOUT by default, but can be configured to send to a local destination log file in the ProductDir directory.

The connector's log file is used to store messages issued by the connector. It also contains messages regarding WebSphere MQ communication errors.

Connector message file:

ProductDir\connectors\messages\ConnName_LocaleName.txt

This file contains the full text for each message issued by the connector. You can use this file to look up the text of message IDs you see in the log file. If the locale specified in the connector configuration file is not supported, the file ConnName.txt is used.

Trace file:

Defaults to STDOUT for both UNIX and Windows.

Contains trace messages as specified by the selected trace level.

The logging system is always active and provides an accurate monitor of the connector.

To troubleshoot a problem, you can turn on tracing. Trace messages help you monitor actions taken in components of the business integration system. Trace levels define the amount of detail written to the trace file. The higher the trace level, the more detail you receive. Tracing differs from logging in the following ways:

Tracing is off by default because it produces messages that are more detailed than you normally need.

For information about viewing logging and tracing messages using LogViewer, see Using Log Viewer to view connector messages.

Configuring connector logging

To configure connector logging options, click the Trace/Log Files tab and specify the following:

  1. To have log messages routed to STDOUT, click the To console (STDOUT) check box.
  2. To have log messages routed to a file, click the To file check box and specify the full-path name of the log file you want to use. You can have log messages routed to the console and to a file by specifying both the "To console" and "To file" options.
  3. If you designated the use of a log file, also specify the following options:
    1. To limit the size of the log file, set Log file size to a numeric value and unit of measure.
    2. To permit the log file to grow with no limit, click the Unlimited check box.
    3. If you have set a maximum size for the log file and you want to use file archiving, set Number of archives to the number of archive files you want to maintain.

For more information about managing log files, see Managing log and trace files.

Configuring connector tracing

To configure connector tracing options:

  1. Click the Trace/Log Files tab.
  2. To have trace messages routed to STDOUT, check To console (STDOUT).
  3. To have trace messages routed to a file, check To file and specify the full-path name of the trace file you want to use. You can have trace messages routed to the console and to a file by specifying both the To console and To file options.
  4. If you designated the use of a trace file, also specify the following options:
    1. To limit the size of the trace file, set Trace file size to a numeric value and unit of measure.
    2. To permit the trace file to grow with no limit, check Unlimited.
    3. If you have set a maximum size for the trace file and you want to use file archiving, set Number of archivesto the number of archive files you want to maintain.
  5. To set the tracing level:
    1. Click the Standard Properties tab.
    2. Set the AgentTraceLevel property to one of the values listed in Table 13.

Refer to the adapter user guide for the connector you are configuring for more details about the information generated by the different trace levels for that connector. You can set connector tracing to one of the following levels:

Table 13. Connector trace levels.

Trace level Description
1 Traces initialization and the sending and receipt of business objects.
2 Prints messages for level 1. In addition, provides more details than Level 1 for the same types of events.
3 Prints messages for levels 1 and 2. In addition, traces the exchange of messages between the connector agent and the messaging driver.
4 Prints messages for levels 1 through 3. In addition, traces the passing of business objects between internal levels of the connector.
5 Prints messages for levels 1 through 4. In addition, traces the passing of administrative messages between internal levels of the connector.

A new or changed tracing level takes effect when you restart the connector.

For more information about archiving trace files, see Managing log and trace files.

Configuring the connector startup files, shortcuts, and environment variables

The procedure for starting a connector and the set-up tasks required both depend on the platform where the connector is running.

For Windows

When you install WebSphere Business Integration Adapters on Windows, a shortcut is created for each installed connector on the WebSphere Business Integration Adapters program menu (Start > Programs > IBM WebSphere Business Integration Adapters > Adapters > Connectors). You must use the startup options listed in Appendix D, Connector startup options to customize the following:

For UNIX

In the UNIX environment, you start a connector by running connector_manager_connName script, which is a wrapper for the generic connector manager script (ProductDir/bin/connector_manager). This wrapper includes the following information:

If you have created a custom adapter or if you have installed an adapter using electronic software delivery (ESD), you need to do the following before you start up the connector for the first time:

  1. Run the Connector Script Generator tool to update the connector_manager_connName script with the name of the connector's configuration file. See Appendix E, Using the Connector Script Generator tool, for more information about running this tool.

    Alternatively, you can navigate to the ProductDir/bin directory and edit the connector_manager_connName file to specify the name of the connector's configuration file. In the file, locate the AGENTCONFIG_FILE variable and set it to the full-path name of the configuration file as follows:

    AGENTCONFIG_FILE=ConfigFile
     
    
  2. If desired, update your PATH environment variable to include the ProductDir/bin directory.
  3. Ensure that the CWSharedEnv.sh file is sourced from the shell startup script (such as .cshrc) for your account.
Customizing the startup script

The generic connector manager script calls the appropriate start_connector.sh script, which is the actual script that manages the particular connector. Each WebSphere Business Integration adapter includes a start_connector.sh script. You can modify the start_connector.sh script to include any of the supported startup options listed in Appendix D, Connector startup options.

Note:
For information about creating a startup files for connectors, see Connector Development Guide for C++ or Connector Development Guide for Java.

Copyright IBM Corp. 1997, 2003