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:
Connector Configurator Express allows you to configure the connector component of your adapter for use with the integration broker, InterChange Server Express.
You use Connector Configurator Express to:
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 Express 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 Express.
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 Express 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.
You can start and run Connector Configurator Express in either of two modes:
You can run Connector Configurator Express independently and work with connector configuration files.
To do so:
You may choose to run Connector Configurator Express independently to generate the file, and then connect to System Manager to save it in a System Manager project (see Completing a configuration file.)
You can run Connector Configurator Express from System Manager.
To run Connector Configurator Express:
To edit an existing configuration file:
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.
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 Express:
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 valuesThe 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:
To create a new property value:
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 dependenciesWhen 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:
== (equal to)
!= (not equal to)
> (greater than)
< (less than)
>= (greater than or equal to)
<=(less than or equal to)
When you create a new configuration file, you must name it and select the integration broker, InterChange Server Express.
You also need to select the integration broker to determine the properties that appear in the configuration file. To select the broker:
Once a connector-specific template has been created, you can use it to create a configuration file:
Enter the name of the connector. Names are case-sensitive. The name you enter must be unique, and must be consistent with the file name for a connector that is installed on the system.
Click InterChange Server Express.
Type the name of the template that has been designed for your connector. The available templates are shown in the Template Name display. When you select a name in the Template Name display, the Property Template Preview display shows the connector-specific properties that have been defined in that template.
Select the template you want to use and click OK.
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 Express, revise the configuration, and then resave the file.
Follow these steps to open a *.txt, *.cfg, or *.in file from a directory:
Choose this option if a repository file was used to configure the connector in an InterChange Server Express environment. A repository file may include multiple connector definitions, all of which appear when you open the file.
Choose this option if a *.txt file was delivered in the adapter package for the connector, or if a definition file is available under another extension.
Follow these steps to open a connector configuration from a System Manager project:
When you open a configuration file or a connector from a project, the Connector Configurator Express 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 InterChange Server Express is the broker. If not, change the broker value before you configure the connector. To do so:
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 Express checks that values have been set for all required standard properties. If a required standard property is missing a value, Connector Configurator Express displays a message that the validation failed. You must supply a value for the property in order to save the configuration file.
When you create and name a new connector configuration file, or when you open an existing connector configuration file, Connector Configurator Express displays a configuration screen with tabs for the categories of required configuration values.
Connector Configurator Express requires values for properties in these categories for connectors running InterChange Server Express:
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:
Standard configuration properties provide information that all connectors use. See Appendix. Standard configuration properties for connectors for documentation of these properties.
You must set at least the following standard connector configuration properties before running the connector:
To change the value of a standard property:
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.
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 |
This is a unique name that must be specified for each connector.
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.
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 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.
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.
The Update Method displayed for each property indicates whether a component or agent restart is necessary to activate changed values.
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 methodRefer to the descriptions of update methods found in the Standard configuration properties for connectors appendix, under Configuration property values overview.
Use the Supported Business Objects tab in Connector Configurator Express 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.
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.
To designate that a business object definition is supported by the connector, with System Manager running:
To delete a business object from the supported list:
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.
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 Express window does not validate your Agent Support selections.
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.
Each connector supports a list of business object definitions and their associated maps that are currently active in InterChange Server Express. 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:
These are the business objects supported by this connector, as designated in the Supported Business Objects tab. If you designate additional business objects under the Supported Business Objects tab, they will be reflected in this list after you save the changes by choosing Save to Project from the File menu of the Connector Configurator Express window.
The display shows all the maps that have been installed to the system for use with the supported business objects of the connector. The source business object for each map is shown to the left of the map name, in the Business Object Name display.
In some cases, you may need to explicitly bind an associated map.
Explicit binding is required only when more than one map exists for a particular supported business object. When InterChange Server Express boots, it tries to automatically bind a map to each supported business object for each connector. If more than one map takes as its input the same business object, the server attempts to locate and bind one map that is the superset of the others.
If there is no map that is the superset of the others, the server will not be able to bind the business object to a single map, and you will need to set the binding explicitly.
To explicitly bind a map:
When you open a connector configuration file or a connector definition file, Connector Configurator Express uses the logging and tracing values of that file as default values. You can change those values in Connector Configurator Express.
To change the logging and tracing values:
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.
When you have finished configuring your connector, save the connector configuration file. Connector Configurator Express saves the file in the broker mode that you selected during configuration. The title bar of Connector Configurator Express always displays the broker mode 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 System Implementation Guide.
After you have created a configuration file for a connector, 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.
Connector Configurator Express is globalized and can handle character conversion between the configuration file and the integration broker. Connector Configurator Express uses native encoding. When it writes to the configuration file, it uses UTF-8 encoding.
Connector Configurator Express 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>
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\iSeries.
On Linux systems the startup script should reside in the ProductDir/bin directory.
On i5/OS systems the startup script should reside in the /QIBM/UserData/WBIServer44/<instance>/connectors/<ConnInstance/ with which the connector runs.
For InterChange Server Express: /QIBM/UserData/WBIServer44/WebSphereICSName/connectors/iSeries/ start_iSeries.sh iSeries WebsphereICSName
For JMS,
/QIBM/UserData/WBIServer44/WebSphereAdapters/connectors/iSeries/
start_iSeries.sh iSeries
dummy -c/QIBM/UserData/WBIServer44/WbSphereAdapters/connectors
/iSeries/iSeriesConnector.cfg
The name of the startup script depends on the operating-system platform, as Table 3 shows.
Operating system | Startup script |
---|---|
Linux | connector_manager |
i5/OS | start_iSeries.sh |
Windows | start_iSeries.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.
Starting the connector on a Windows system:
Starting the connector on a Linux system:
connector_manager -start connName brokerName [-cconfigFile ]where connName is the name of the connector and brokerName identifies the integration broker.
For more information on how to start a connector, including the command-line startup options, refer to the System Administration Guide.
The way to stop a connector depends on the way the connector was started.
Connectors run in the background so they have no separate window. Instead, run the following command to stop the connector:
connector_manager -stop connName
where connName is the name of the connector.
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:
ProductDir\connectors\connectorInstance
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
where connectorInstance uniquely identifies the connector instance.
You can specify the InterChange Server Express server name as a parameter of startup.bat; an example is: start_iseries.bat connName serverName.
/QIBM/UserData/WBIServer44/WebShereICSName/connectors/connectorInstance
where connectorInstance uniquely identifies the connector instance and where WebSphereICSName is the name of the Interchange Server Express instance with which the connector runs.
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:
/QIBM/UserData/WBIServer44/WebSphereICSName/repository
/connectorInstance where WebSphereICSName is the name
of the Interchange Server Express
instance with which the connector runs.
If the business object definitions for each connector instance do not already exist within the project, you must create them.
ProductDir\repository\initialConnectorInstanceAny additional files you create should be in the appropriate connectorInstance subdirectory of ProductDir\repository.
Use the following steps to create a configuration file (connector definition) for the connector instance in Connector Configurator Express.
To create a startup script:
dirname