Configuring the connector

The iSeries adapter uses standard connector properties for configuration as detailed in the next section and connector-specific properties as detailed in the following section.

This section includes the following topics:

Overview of Connector Configurator

Connector Configurator allows you to configure the connector component of your adapter for use with these integration brokers:

You use Connector Configurator to:

The mode in which you run Connector Configurator, and the configuration file type you use, may differ according to which integration broker you are running. For example, if WMQI is your broker, you run Connector Configurator directly, and not from within System Manager (see Running Configurator in stand-alone mode).

Connector configuration properties include both standard configuration properties (the properties that all connectors have) and connector-specific properties (properties that are needed by the connector for a specific application or technology).

Because standard properties are used by all connectors, you do not need to define those properties from scratch; Connector Configurator incorporates them into your configuration file as soon as you create the file. However, you do need to set the value of each standard property in Connector Configurator.

The range of standard properties may not be the same for all brokers and all configurations. Some properties are available only if other properties are given a specific value. The Standard Properties window in Connector Configurator will show the properties available for your particular configuration.

For connector-specific properties, however, you need first to define the properties and then set their values. You do this by creating a connector-specific property template for your particular adapter. There may already be a template set up in your system, in which case, you simply use that. If not, follow the steps in Creating a new template to set up a new one.

Note:
Connector Configurator runs only in a Windows environment. If you are running the connector in a UNIX environment, use Connector Configurator in Windows to modify the configuration file and then copy the file to your UNIX environment.

Starting Connector Configurator

You can start and run Connector Configurator in either of two modes:

Running Configurator in stand-alone mode

You can run Connector Configurator independently and work with connector configuration files, irrespective of your broker.

To do so:

You may choose to run Connector Configurator independently to generate the file, and then connect to System Manager to save it in a System Manager project (see Completing a configuration file.)

Running Configurator from System Manager

You can run Connector Configurator from System Manager.

To run Connector Configurator:

  1. Open the System Manager.
  2. In the System Manager window, expand the Integration Component Libraries icon and highlight Connectors.
  3. From the System Manager menu bar, click Tools>Connector Configurator. The Connector Configurator window opens and displays a New Connector dialog box.
  4. When you click the pull-down menu next to System Connectivity Integration Broker, you can select ICS, WebSphere Message Brokers or WAS, depending on your broker.

To edit an existing configuration file:

Creating a connector-specific property template

To create a configuration file for your connector, you need a connector-specific property template as well as the system-supplied standard properties.

You can create a brand-new template for the connector-specific properties of your connector, or you can use an existing connector definition as the template.

Creating a new template

This section describes how you create properties in the template, define general characteristics and values for those properties, and specify any dependencies between the properties. Then you save the template and use it as the base for creating a new connector configuration file.

To create a template in Connector Configurator:

  1. Click File>New>Connector-Specific Property Template.
  2. The Connector-Specific Property Template dialog box appears.
  3. You can use an existing template whose property definitions are similar to those required by your connector as a starting point for your template. If you do not see any template that displays the connector-specific properties used by your connector, you will need to create one.
Specifying general characteristics

When you click Next to select a template, the Properties - Connector-Specific Property Template dialog box appears. The dialog box has tabs for General characteristics of the defined properties and for Value restrictions. The General display has the following fields:

After you have made selections for the general characteristics of the property, click the Value tab.

Specifying values

The Value tab enables you to set the maximum length, the maximum multiple values, a default value, or a value range for the property. It also allows editable values. To do so:

  1. Click the Value tab. The display panel for Value replaces the display panel for General.
  2. Select the name of the property in the Edit properties display.
  3. In the fields for Max Length and Max Multiple Values, enter your values.

To create a new property value:

  1. Select the property in the Edit properties list and right-click on it.
  2. From the dialog box, select Add.
  3. Enter the name of the new property value and click OK. The value appears in the Value panel on the right.

The Value panel displays a table with three columns:

The Value column shows the value that you entered in the Property Value dialog box, and any previous values that you created.

The Default Value column allows you to designate any of the values as the default.

The Value Range shows the range that you entered in the Property Value dialog box.

After a value has been created and appears in the grid, it can be edited from within the table display.

To make a change in an existing value in the table, select an entire row by clicking on the row number. Then right-click in the Value field and click Edit Value.

Setting dependencies

When you have made your changes to the General and Value tabs, click Next. The Dependencies - Connector-Specific Property Template dialog box appears.

A dependent property is a property that is included in the template and used in the configuration file only if the value of another property meets a specific condition. For example, PollQuantity appears in the template only if JMS is the transport mechanism and DuplicateEventElimination is set to True.
To designate a property as dependent and to set the condition upon which it depends, do this:

  1. In the Available Properties display, select the property that will be made dependent.
  2. In the Select Property field, use the drop-down menu to select the property that will hold the conditional value.
  3. In the Condition Operator field, select one of the following:

    == (equal to)

    != (not equal to)

    > (greater than)

    < (less than)

    >= (greater than or equal to)

    <=(less than or equal to)

  4. In the Conditional Value field, enter the value that is required in order for the dependent property to be included in the template.
  5. With the dependent property highlighted in the Available Properties display, click an arrow to move it to the Dependent Property display.
  6. Click Finish. Connector Configurator stores the information you have entered as an XML document, under \data\app in the\bin directory where you have installed Connector Configurator.

Creating a new configuration file

When you create a new configuration file, you must name it and select an integration broker.

You also need to select an integration broker. The broker you select determines the properties that will appear in the configuration file. To select a broker:

Creating a configuration file from a connector-specific template

Once a connector-specific template has been created, you can use it to create a configuration file:

  1. Click File>New>Connector Configuration.
  2. The New Connector dialog box appears, with the following fields:
  3. A configuration screen appears for the connector that you are configuring. The title bar shows the integration broker and connector names. You can fill in all the field values to complete the definition now, or you can save the file and complete the fields later.
  4. To save the file, click File>Save>To File or File>Save>To Project. To save to a project, System Manager must be running.

    If you save as a file, the Save File Connector dialog box appears. Choose *.cfg as the file type, verify in the File Name field that the name is spelled correctly and has the correct case, navigate to the directory where you want to locate the file, and click Save. The status display in the message panel of Connector Configurator indicates that the configuration file was successfully created.
    Important:
    The directory path and name that you establish here must match the connector configuration file path and name that you supply in the startup file for the connector.
  5. To complete the connector definition, enter values in the fields for each of the tabs of the Connector Configurator window, as described later in this chapter.

Using an existing file

You may have an existing file available in one or more of the following formats:

Although any of these file sources may contain most or all of the connector-specific properties for your connector, the connector configuration file will not be complete until you have opened the file and set properties, as described later in this chapter.

To use an existing file to configure a connector, you must open the file in Connector Configurator, revise the configuration, and then resave the file.

Follow these steps to open a *.txt, *.cfg, or *.in file from a directory:

  1. In Connector Configurator, click File>Open>From File.
  2. In the Open File Connector dialog box, select one of the following file types to see the available files:
  3. In the directory display, navigate to the appropriate connector definition file, select it, and click Open.

Follow these steps to open a connector configuration from a System Manager project:

  1. Start System Manager. A configuration can be opened from or saved to System Manager only if System Manager has been started.
  2. Start Connector Configurator.
  3. Click File>Open>From Project.

Completing a configuration file

When you open a configuration file or a connector from a project, the Connector Configurator window displays the configuration screen, with the current attributes and values.

The title of the configuration screen displays the integration broker and connector name as specified in the file. Make sure you have the correct broker. If not, change the broker value before you configure the connector. To do so:

  1. Under the Standard Properties tab, select the value field for the BrokerType property. In the drop-down menu, select the value ICS, WMQI, or WAS.
  2. The Standard Properties tab will display the properties associated with the selected broker. You can save the file now or complete the remaining configuration fields, as described in Specifying supported business object definitions..
  3. When you have finished your configuration, click File>Save>To Project or File>Save>To File.

    If you are saving to file, select *.cfg as the extension, select the correct location for the file and click Save.

    If multiple connector configurations are open, click Save All to File to save all of the configurations to file, or click Save All to Project to save all connector configurations to a System Manager project.

    Before it saves the file, Connector Configurator checks that values have been set for all required standard properties. If a required standard property is missing a value, Connector Configurator displays a message that the validation failed. You must supply a value for the property in order to save the configuration file.

Setting the configuration file properties

When you create and name a new connector configuration file, or when you open an existing connector configuration file, Connector Configurator displays a configuration screen with tabs for the categories of required configuration values.

Connector Configurator requires values for properties in these categories for connectors running on all brokers:

Note:
For connectors that use JMS messaging, an additional category may display, for configuration of data handlers that convert the data to business objects.

For connectors running on ICS, values for these properties are also required:

Important:
Connector Configurator accepts property values in either English or non-English character sets. However, the names of both standard and connector-specific properties, and the names of supported business objects, must use the English character set only.

Standard properties differ from connector-specific properties as follows:

The fields for Standard Properties and Connector-Specific Properties are color-coded to show which are configurable:

Setting standard connector properties

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

Important:
Because this connector supports all integration brokers, configuration properties for all brokers are relevant to it.

You must set at least the following standard connector configuration properties before running the connector:

To change the value of a standard property:

  1. Click in the field whose value you want to set.
  2. Either enter a value, or select one from the drop-down menu if it appears.
  3. After entering all the values for the standard properties, you can do one of the following:
Connector-specific properties

Connector-specific configuration properties provide information needed by the connector 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 2 lists the connector-specific configuration properties for the connector. See the section that follows for explanations of the properties.

Table 2. Connector-specific configuration properties
Name Possible values Default value Required?
ApplicationName iSeriesAdapter None Yes
UseDefaults default value None Yes
MessageFileName BIA_iSeriesAdapter.txt BIA_iSeriesAdapter.txt No
PollQuantity an integer greater than 1 1 No
ApplicationName

This is a unique name that must be specified for each connector.

UseDefaults

For example, some of the input parameters to a program are constant. So these attributes can be designed to have default values. If there is no default value and the UseDefaults property is set to true, the adapter errors out and throws a VerbProcessingFailedException error message. If UseDefaults is not set or set to false, and there are no default values, the adapter builds a string of length MaxLength with padded spaces for the attribute values.

MessageFileName

This is the name and path of the error message file if it is not located in the standard message location %CROSSWORLDS%\ connectors\messages. If the message file name is not in a fully qualified path, the message file is assumed to be located in the directory specified by the HOME environment variable or the startup parameter user.home. If a connector message file does not exist, the file BIA_iSeriesAdapter.txt is used as the message file.

PollQuantity

PollQuantity is an integer value above 1 specifying the number of items to poll from the data queues. Note that if n is specified as PollQuantity value then each queue configured using meta objects is polled n times. The default value is taken as 1.

Setting application-specific configuration properties

For application-specific configuration properties, you can add or change property names, configure values, delete a property, and encrypt a property. The default property length is 255 characters.

  1. Right-click in the top left portion of the grid. A pop-up menu bar will appear. Click Add to add a property. To add a child property, right-click on the parent row number and click Add child.
  2. Enter a value for the property or child property.
  3. To encrypt a property, select the Encrypt box.
  4. Choose to save or discard changes, as described for Setting standard connector properties.

The Update Method displayed for each property indicates whether a component or agent restart is necessary to activate changed values.

Important:
Changing a preset application-specific connector property name may cause a connector to fail. Certain property names may be needed by the connector to connect to an application or to run properly.
Encryption for connector properties

Application-specific properties can be encrypted by selecting the Encrypt check box in the Connector-specific Properties window. To decrypt a value, click to clear the Encrypt check box, enter the correct value in the Verification dialog box, and click OK. If the entered value is correct, the value is decrypted and displays.

The adapter user guide for each connector contains a list and description of each property and its default value.

If a property has multiple values, the Encrypt check box will appear for the first value of the property. When you select Encrypt, all values of the property will be encrypted. To decrypt multiple values of a property, click to clear the Encrypt check box for the first value of the property, and then enter the new value in the Verification dialog box. If the input value is a match, all multiple values will decrypt.

Update method

Refer to the descriptions of update methods found in the Standard configuration properties for connectors appendix, under Configuration property values overview.

Specifying supported business object definitions

Use the Supported Business Objects tab in Connector Configurator to specify the business objects that the connector will use. You must specify both generic business objects and application-specific business objects, and you must specify associations for the maps between the business objects.

Note:
Some connectors require that certain business objects be specified as supported in order to perform event notification or additional configuration (using meta-objects) with their applications. For more information, see the Connector Development Guide for C++ or the Connector Development Guide for Java.
If ICS is your broker

To specify that a business object definition is supported by the connector, or to change the support settings for an existing business object definition, click the Supported Business Objects tab and use the following fields.

Business object name

To designate that a business object definition is supported by the connector, with System Manager running:

  1. Click an empty field in the Business Object Name list. A drop-down list displays, showing all the business object definitions that exist in the System Manager project.
  2. Click on a business object to add it.
  3. Set the Agent Support (described below) for the business object.
  4. In the File menu of the Connector Configurator window, click Save to Project. The revised connector definition, including designated support for the added business object definition, is saved to an ICL (Integration Component Library) project in System Manager.

To delete a business object from the supported list:

  1. To select a business object field, click the number to the left of the business object.
  2. From the Edit menu of the Connector Configurator window, click Delete Row. The business object is removed from the list display.
  3. From the File menu, click Save to Project.

Deleting a business object from the supported list changes the connector definition and makes the deleted business object unavailable for use in this implementation of this connector. It does not affect the connector code, nor does it remove the business object definition itself from System Manager.

Agent support

If a business object has Agent Support, the system will attempt to use that business object for delivering data to an application via the connector agent.

Typically, application-specific business objects for a connector are supported by that connector's agent, but generic business objects are not.

To indicate that the business object is supported by the connector agent, check the Agent Support box. The Connector Configurator window does not validate your Agent Support selections.

Maximum transaction level

The maximum transaction level for a connector is the highest transaction level that the connector supports.

For most connectors, Best Effort is the only possible choice.

You must restart the server for changes in transaction level to take effect.

If a WebSphere Message Broker is your broker

If you are working in stand-alone mode (not connected to System Manager), you must enter the business object name manually.

If you have System Manager running, you can select the empty box under the Business Object Name column in the Supported Business Objects tab. A combo box appears with a list of the business object available from the Integration Component Library project to which the connector belongs. Select the business object you want from the list.

The Message Set ID is an optional field for WebSphere Business Integration Message Broker 5.0, and need not be unique if supplied. However, for WebSphere MQ Integrator and Integrator Broker 2.1, you must supply a unique ID.

If WAS is your broker

When WebSphere Application Server is selected as your broker type, Connector Configurator does not require message set IDs. The Supported Business Objects tab shows a Business Object Name column only for supported business objects.

If you are working in stand-alone mode (not connected to System Manager), you must enter the business object name manually.

If you have System Manager running, you can select the empty box under the Business Object Name column in the Supported Business Objects tab. A combo box appears with a list of the business objects available from the Integration Component Library project to which the connector belongs. Select the business object you want from this list.

Associated maps (ICS only)

Each connector supports a list of business object definitions and their associated maps that are currently active in WebSphere InterChange Server. This list appears when you select the Associated Maps tab.

The list of business objects contains the application-specific business object which the agent supports and the corresponding generic object that the controller sends to the subscribing collaboration. The association of a map determines which map will be used to transform the application-specific business object to the generic business object or the generic business object to the application-specific business object.

If you are using maps that are uniquely defined for specific source and destination business objects, the maps will already be associated with their appropriate business objects when you open the display, and you will not need (or be able) to change them.

If more than one map is available for use by a supported business object, you will need to explicitly bind the business object with the map that it should use.

The Associated Maps tab displays the following fields:

Resources (ICS)

The Resource tab allows you to set a value that determines whether and to what extent the connector agent will handle multiple processes concurrently, using connector agent parallelism.

Not all connectors support this feature. If you are running a connector agent that was designed in Java to be multi-threaded, you are advised not to use this feature, since it is usually more efficient to use multiple threads than multiple processes.

Messaging (ICS)

The messaging properties are available only if you have set MQ as the value of the DeliveryTransport standard property and ICS as the broker type. These properties affect how your connector will use queues.

Setting trace/log file values

When you open a connector configuration file or a connector definition file, Connector Configurator uses the logging and tracing values of that file as default values. You can change those values in Connector Configurator.

To change the logging and tracing values:

  1. Click the Trace/Log Files tab.
  2. For either logging or tracing, you can choose to write messages to one or both of the following:

Data handlers

The data handlers section is available for configuration only if you have designated a value of JMS for DeliveryTransport and a value of JMS for ContainerManagedEvents. Not all adapters make use of data handlers.

See the descriptions under ContainerManagedEvents in Appendix A, Standard Properties, for values to use for these properties. For additional details, see the Connector Development Guide for C++ or the Connector Development Guide for Java.

Saving your configuration file

When you have finished configuring your connector, save the connector configuration file. Connector Configurator saves the file in the broker mode that you selected during configuration. The title bar of Connector Configurator always displays the broker mode (ICS, WMQI or WAS) that it is currently using.

The file is saved as an XML document. You can save the XML document in three ways:

For details about using projects in System Manager, and for further information about deployment, see the following implementation guides:

Changing a configuration file

You can change the integration broker setting for an existing configuration file. This enables you to use the file as a template for creating a new configuration file, which can be used with a different broker.

Note:
You will need to change other configuration properties as well as the broker mode property if you switch integration brokers.

To change your broker selection within an existing configuration file (optional):

Completing the configuration

After you have created a configuration file for a connector and modified it, make sure that the connector can locate the configuration file when the connector starts up.

To do so, open the startup file used for the connector, and verify that the location and file name used for the connector configuration file match exactly the name you have given the file and the directory or path where you have placed it.

Using Connector Configurator in a globalized environment

Connector Configurator is globalized and can handle character conversion between the configuration file and the integration broker. Connector Configurator uses native encoding. When it writes to the configuration file, it uses UTF-8 encoding.

Connector Configurator supports non-English characters in:

The drop list for the CharacterEncoding and Locale standard configuration properties displays only a subset of supported values. To add other values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product directory.

For example, to add the locale en_GB to the list of values for the Locale property, open the stdConnProps.xml file and add the line in boldface type below:

<Property name="Locale" 
isRequired="true" 
updateMethod="component restart">
                <ValidType>String</ValidType>
            <ValidValues>
                                <Value>ja_JP</Value>
                                <Value>ko_KR</Value>
                                <Value>zh_CN</Value>
                                <Value>zh_TW</Value>
                                <Value>fr_FR</Value>
                                <Value>de_DE</Value>
                                <Value>it_IT</Value>
                                <Value>es_ES</Value>
                                <Value>pt_BR</Value>
                                <Value>en_US</Value>
                                <Value>en_GB</Value>
                    <DefaultValue>en_US</DefaultValue>
            </ValidValues>
    </Property>

Starting the connector

A connector must be explicitly started using its connector start-up script. On Windows systems the startup script should reside in the connector's runtime directory:

ProductDir\connectors\connName

where connName identifies the connector.

On UNIX systems the startup script should reside in the UNIX ProductDir/bin directory.

The name of the startup script depends on the operating-system platform, as Table 3 shows.

Table 3. Startup scripts for a connector
Operating system Startup script
UNIX-based systems connector_manager
Windows start_connName.bat

When the startup script runs, it expects by default to find the configuration file in the Productdir (see the commands below). This is where you place your configuration file.

Note:
You need a local configuration file if the adapter is using JMS transport.

You can invoke the connector startup script in any of the following ways:

For more information on how to start a connector, including the command-line startup options, refer to one of the following documents:

Stopping the connector

The way to stop a connector depends on the way that the connector was started, as follows:

Creating multiple connector instances

Creating multiple instances of a connector is in many ways the same as creating a custom connector. You can set your system up to create and run multiple instances of a connector by following the steps below. You must:

Create a new directory

You must create a connector directory for each connector instance. This connector directory should be named:

ProductDir\connectors\connectorInstance

where connectorInstance uniquely identifies the connector instance.

If the connector has any connector-specific meta-objects, you must create a meta-object for the connector instance. If you save the meta-object as a file, create this directory and store the file here:

ProductDir\repository\connectorInstance
Create business object definitions

If the business object definitions for each connector instance do not already exist within the project, you must create them.

  1. If you need to modify business object definitions that are associated with the initial connector, copy the appropriate files and use Business Object Designer to import them. You can copy any of the files for the initial connector. Just rename them if you make changes to them.
  2. Files for the initial connector should reside in the following directory:
    ProductDir\repository\initialConnectorInstance
    Any additional files you create should be in the appropriate connectorInstance subdirectory of ProductDir\repository.
Create a connector definition

You create a configuration file (connector definition) for the connector instance in Connector Configurator. To do so:

  1. Copy the initial connector's configuration file (connector definition) and rename it.
  2. Make sure each connector instance correctly lists its supported business objects (and any associated meta-objects).
  3. Customize any connector properties as appropriate.
Create a start-up script

To create a startup script:

  1. Copy the initial connector's startup script and name it to include the name of the connector directory:

    dirname

  2. Put this startup script in the connector directory you created in Create a new directory.
  3. Create a startup script shortcut (Windows only).
  4. Copy the initial connector's shortcut text and change the name of the initial connector (in the command line) to match the name of the new connector instance.

You can now run both instances of the connector on your integration server at the same time.

For more information on creating custom connectors, refer to the Connector Development Guide for C++ or for Java.

Copyright IBM Corporation 2003, 2005. All Rights Reserved.