Operating connectors may include such tasks as starting, pausing, stopping, and shutting down connectors. For information about configuring connectors, including setting properties, supported business objects, and associated maps, see the System Implementation Guide.
While administering connectors, you can also decide whether to optimize your JMS Transport. For additional information, please refer to Administering JMS transport optimization.
You can start, pause, stop, and shut down connectors from either System Monitor or the InterChange Server Component Management view of System Manager.
This section covers the following topics:
"Starting, stopping, and pausing connectors"
Steps for configuring flow control for connectors
You can view the state of a connector either by logging on to System Monitor and opening a view that contains connector states or by using the InterChange Server Component Management view of System Manager. To log on to System Monitor, follow the instructions in Steps for logging on to System Monitor. To use the InterChange Server Component Management view of System Manager, follow the instructions in Steps for connecting to an InterChange Server instance..
The state of a connector is represented differently, depending on which tool you are using either System Monitor or System Manager.
Steps for using System Monitor to view connector states
Perform the following steps to see the state of connectors using System Monitor:
When the product is installed, the default view is set to System Overview, and the default monitor contained in that view is set to System Overview. These defaults can be changed to suit your monitoring needs. See Setting up views to monitor the system for instructions.
Figure 23. System Monitor, System Overview displaying connector status
Steps for using System Manager to view connector states
Perform the following steps to view the state of a connector in System Manager:
The connectors appear under the expanded Connectors folder with different colored lights to indicate their different states.
Table 11 lists the connector states represented by the display color
of each connector and shows what actions are being performed during that
state.
Connector State | Subscription requests processed | Service call requests processed | Subscription deliveries processed |
---|---|---|---|
Active (green) | Yes | Yes | Yes |
Paused (yellow) | Yes | Yes | No |
In recovery or unknown (grey) |
|
|
|
Inactive (red) | No | No | No |
This section describe how to start, stop, and pause connectors. The following topics are covered:
"Steps for starting, stopping, and pausing connectors using System Monitor"
System Manager commands for changing connector states
"Steps for manually starting a connector"
"Steps for setting automatic and remote restart for a connector"
The first time you start a connector, it must be initialized. Initializing a connector requires that you start it manually. For instructions on manually starting a connector, see "Steps for starting a connector manually on UNIX" or "Steps for starting a connector manually on Windows".
If the connector does not start, check to make sure that the command line to start it includes the current InterChange Server name. For more information on the connector's password to InterChange Server, refer to the System Installation Guide for Unix or for Windows .
After the connector has been initialized, you can start, stop, and pause it using System Monitor or System Manager.
Perform the following steps to start, stop and pause connectors using System Monitor:
Figure 24. System Monitor, icons for starting, pausing, restarting, or shutting down components
Perform the following steps to start, stop and pause connectors using System Manager:
The following list describes the commands you can use to change the connector state and describes their processing actions:
The procedure for manually starting a connector depends on whether your operating system is UNIX or Windows. This section provides the following information:
Steps for starting a connector manually on UNIX
To start a connector, use the connector manager script in the AdapterFrameworkProductDir/bin directory with the following syntax:
connector_manager_connector -start
where connector is the name of the connector that you want to start. The case and spelling of this connector name must match the name of the connector's subdirectory under:
AdapterFrameworkProductDir/connectors
For example, the following command starts the e-Mail connector and provides the default password to InterChange Server:
connector_manager_EMail -start
The e-Mail connector has a AdapterFrameworkProductDir/connectors subdirectory named EMail. Therefore, the connector manager script must include EMail as the connector name (not Email).
The connector_manager_connector script is a wrapper for the generic connector manager script (AdapterFrameworkProductDir/bin/connector_manager). This wrapper includes the following information so that you do not need to specify it:
For example:
By default, the configuration information for a connector installed for use with InterChange Server resides in the InterChange Server repository. You can optionally use a connector configuration file that resides locally on the same machine as the connector. In some circumstances--for example, if you are using JMS--a local connector configuration file is mandatory.
For a local connector configuration file to be used, the file name and path for that file must be specified with the -c option as the value of the AGENTCONFIG_FILE variable in the connector_manager_connector script. The wrapper passes that information when it invokes connector_manager. The value can include either a literal or a relative path. If the value of the variable specifies a relative path, the startup script looks for the specified file in the directory where the product is installed.
When a connector starts up, it will first look for its configuration values in the file specified by the AGENTCONFIG_FILE variable, and will then look in the InterChange Server repository for any configuration values that it did not find in the local configuration file. Values for properties in the specified local configuration file take precedence over values for the same properties in the InterChange Server repository.
If you intend to use a local configuration file for your connector, you may need to supply or change the AGENTCONFIG_FILE value in the connector_manager_connector script. The necessity for this depends in part on which version of the product Installer you used to install the connector. You may have used either of two versions of the product Installer:
In either of the above cases, you do not need to modify the connector_manager_connector script from its default installed settings if you are using the configuration stored in the InterChange Server repository.
To specify a local configuration file, or to change its name or path, use the ConnConfig.sh command. This command opens a graphical interface that allows you to change the connector_manager_connector script graphically rather than in a text editor.
The generic connector manager script calls the appropriate
start_connector.sh script, which
handles the actual connector management for the connector. The IBM
WebSphere Business Integration Adapter product provides a
start_connector.sh script with each
connector. This
start_connector.sh script supports the
options in Table 12 for starting a connector.
Table 12. Command-Line Options for the start_connector.sh Script
Option | Additional Information |
---|---|
-b | This option runs the connector as a background thread; that is, no input is read from STDIN (standard input). The generic connector_manager script (called by each connector_manager_connector script) automatically specifies the -b option when it invokes the start_connector.sh script for a connector. You can remove this option from the start_connector.sh invocation to prevent a connector from being run in the background. The -b option is not valid on the command-line invocation of connector_manager_connector. |
-fpollFrequency | Poll frequency is the number of milliseconds between polling
actions.
The value of this parameter overrides any repository definitions. You can specify either -fkey or -fno, but not both. The -f option is valid on the command-line invocation of connector_manager_connector. The connector manager script can pass this option to its associated start_connector.sh script. |
-tthreading_type | The threading_type parameter specifies the
threading model:
The -t option is not valid on the command-line invocation of connector_manager_connector. Specify it inside the generic connector_manager script, in the invocation of the start_connector.sh script. |
You can also use the connector_manager_connector script to perform the following tasks:
connector_manager_connector -stop
connector_manager_connector -stat
connector_manager_connector -kill
Each connector manager script has a log file with the name:
connector_manager_connector.log
where connector is the name of the connector. Each log file contains messages generated by the connector_manager_connector script and the associated connector. For example, the connector_manager_Oracle.log file contains messages from the connector_manager_Oracle script and the IBM WebSphere InterChange Server connector for Oracle. The log files are located in the same location as the InterchangeSystem.log file: AdapterFrameworkProductDir/logs.
Steps for starting a connector manually on Windows
When you install the IBM WebSphere Business Integration Adapters on a Windows machine, a shortcut is created for each installed connector on the IBM WebSphere program menu. The connector is defined in the InterChange Server repository and is loaded when you load the repository.
Starting InterChange Server automatically initializes every connector defined in the repository. The connector is available for use whenever InterChange Server is running.
You can start the connector in several ways:
Start the connector by double-clicking the desktop shortcut created as part of the installation procedure.
Open a DOS Command Prompt window and navigate to the appropriate connector directory. At the prompt, enter the one of the statements below, depending on whether the connector is a Java connector or a C++ connector:
Java connector
start_Sap ConnectorName InterChangeServerName
C++ connector
start_connector ConnectorName InterChangeServerName
where ConnectorName is the name of the connector and InterChangeServerName is the name of the InterChange Server instance.
AdapterFrameworkProductDir\documentation\ wbia_adapters\featurechecklists\versionlist.htm
in your local directory, where AdapterFrameworkProductDir is the directory where you installed the WebSphere Business Integration Adapters product.
You can customize the startup for each connector by modifying
the connector shortcut or the
start_connector.bat
file. Use the connector startup parameters listed in Table 13 to customize the startup of a connector.
Table 13. Connector Startup Parameters
Parameter | Function |
---|---|
-c configFile | Name of the configuration file to be used during startup. If the filename specifies a relative path, the startup script looks for the file in the directory where the product is installed. This parameter is required only to use a local connector configuration file. If you are not using a local configuration file, enter the name of the configuration file used by the IBM WebSphere InterChange Server (by default, InterchangeSystem.cfg). |
-c | Causes the default configuration file to be used if the user-specified configuration file does not exist. |
-d | Specifies the name of the C++ connector's library file, which is a dynamic link library (DLL). This DLL name does not include the .dll file extension. The startup script specifies this option for all C++ connectors. |
-f pollFrequency | Poll frequency is the number of milliseconds between polling
actions.
The value of this parameter overrides any repository definitions. You can specify either -fkey or -fno, but not both. |
-j | Specifies that the connector is written in Java. This parameter is optional if you specify -l className. |
-l className | Specifies the name of the Java connector's global class, which is an extension of the connector base class. The startup script specifies this option for all Java connectors. |
-n connectorName | Specifies the name of the connector to start. |
-p password | Specifies the password that the connector uses to access InterChange Server. |
-s serverName | Specifies the name of the InterChange Server. This parameter is required. The name is case-sensitive. |
-t | Turns on the connector property SingleThreadAppCalls. This property guarantees that all calls the connector framework makes to the application-specific connector code are with one event-triggered flow. The default value is false. Important: Do not change the value of this property from its shipped value. Each connector has the appropriate setting for its threading model. Specify this option only when starting a connector you created. |
-x connectorProps | Passes application-specific connector properties to the connector. Use the format prop_name=value for each value you enter. |
The generic connector manager script calls the appropriate start_connector.sh script, which handles the actual connector management for the connector. The IBM WebSphere InterChange Server product provides a start_connector.sh script for each connector it delivers. Shutting down a connector stops the connector's processes. Before shutting down a connector, pause or stop each collaboration object that uses the connector (the collaboration must be configured to pause; see the collaboration documentation for details on how to do this). If the "Pause when critical error occurs" property has been set for a collaboration in the Collaboration General Properties window, the collaboration pauses automatically when a critical error occurs. The latest unprocessed events of such collaborations are then moved to the event submission queue.
You can perform either a "permanent" or a "temporary" shutdown of the connector. You control the type of shutdown by enabling or disabling (the default) automatic restart:
For instructions on enabling or disabling automatic restart, see "Steps for setting automatic and remote restart for a connector".
Perform the following steps to shut down a connector:
UNIX |
---|
Use the following command: connector_manager_<connector_name> -stop. |
Windows |
---|
Use System Monitor to shut down a connector. |
Instructions for shutting down a connector in Windows depends on which tool you use to monitor the system. The following sections detail steps for shutting down a connector using System Monitor or System Manager.
Steps for shutting down a connector in System Monitor:Perform the following steps in System Monitor to shut down a connector:
Steps for shutting down a connector in System Manager:Perform the following steps in System Manager to shut down a connector:
The color on the collaboration object icon turns to yellow.
This action is used to restart the connector after you have used the Shut Down Connector action in either System Monitor or the InterChange Server Component Management view of System Manager. This action is available only if you have enabled automatic and remote restart for the connector (see Steps for setting automatic and remote restart for a connector).
Instructions for restarting a connector depend on which tool you are using:
Steps for restarting a connector in System Monitor:Perform the following steps in System Monitor to restart a connector:
Steps for restarting a connector in System Manager:Perform the following steps in System Monitor to shut down a connector:
With the WebSphere MQ-triggered Object Activation Daemon (OAD), you can enable a connector to support the automatic-and-remote-restart feature, which allows the connector to handle the following conditions:
Perform the following steps to set up automatic and remote restart for a connector:
Use of the MQ-triggered OAD requires installation of the MQ-trigger Monitor and the configuration of certain queues. This monitor is installed as part of the WebSphere MQ software. These queues are created and configured by a special mqtriggersetup.bat script.
Steps for enabling connectors for MQ-triggered OAD
Perform the following steps to start Connector Configurator Express for the connector before you set the OAD properties:
Table 14. Configuring standard properties in Connector Configurator Express
Name | Possible values | Description | Default values |
---|---|---|---|
OADAutoRestartAgent | true or false | If this property is set to true, the MQ-triggered OAD automatically attempts to restart the connector after an abnormal shutdown. It can also be used to start the connector agent remotely. This value is dynamic. | false |
OADMaxNumRetry | Number | Number of maximum attempts. | 10,000 |
OADRetryTimeInterval | Minutes | Number of minutes between each retry. If the connector agent does not start in this time interval, another attempt to restart the agent is made. | 10 |
From within Connector Configurator Express, you can take any of the following actions:
Perform the following steps to enable automatic and remote restart for a connector for the first time:
Changing the value of the OADAutoRestartAgent property from True to False toggles the automatic-and-remote-restart feature on and off. This connector property is dynamic; that is, you do not need to restart InterChange Server Express for the change to take effect. Therefore, when you set OADAutoRestartAgent to False, automatic and remote restart is disabled. When you set this property to True, automatic restart is enabled.
If you shut down the connector agent when the automatic-and-remote-restart feature is enabled, you perform a temporary shutdown. The response of the connector depends on the method you use to shutdown the connector, as follows:
However, if you disable the automatic-and-remote-restart feature and then shut down the connector agent, you perform a permanent shutdown; that is, you must manually restart the connector.
Flow control is a configurable service that allows you to manage the flow of connector and collaboration object queues. The parameters for configuring flow control can be configured system-wide or on individual components, or both. If you configure both, the individual component configuration supersedes the system-wide configuration. For instructions on configuring flow control system-wide, seeSteps for configuring system-wide flow control. This section describes how to configure flow control for connectors.
To monitor how flow control is working in the system, you can view the Flow Control monitor and view provided as part of System Monitor or you can view the Statistics for collaboration objects or connectors from the InterChange Server Component Management view of System Manager. For more information on using the Flow Control monitor and view in System Monitor, see Steps for reviewing default monitors and Steps for using default views. For more information on viewing the flow control from the InterChange Server Component Management view of System Manager, see Collaboration object statistics or Connector statistics.
Perform the following steps to configure flow control for a connector, do the following: