Operating connectors

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.

You can start, pause, stop, and shut down connectors from the Web-based System Monitor.

This section covers the following topics:

"Connector states"

"Starting, stopping, and pausing connectors"

Configuring flow control for connectors

Connector states

You can view the state of a connector by logging on to the Web-based System Monitor and opening a view that contains connector states.

To see the state of connectors using the Web-based System Monitor, do the following:

  1. If the System Overview view is not displayed, click the System Overview link under Views in the left pane of the Web page. The System Overview Monitor appears in the body of the Web page.

    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 Using Views for instructions.

  2. Click the triangle next to the name of the server to reveal a list of components on the system.
  3. Click the triangle next to a running collaboration to reveal its associated connectors (see Figure 10).

    Figure 10. Web-based System Monitor, System Overview displaying connector status


Starting, stopping, and pausing connectors

This section describe how to start, stop, and pause connectors. The following topics are covered:

"Initializing a connector"

"Running, stopping, and pausing connectors using System Monitor"

Commands for changing connector states

"Manually starting a connector"

"Shutting down a connector"

"Restarting a connector"

"Setting Automatic and remote restart for a connector"

"Using OAD as a Windows service"

Initializing 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 "Starting a connector manually".

If the connector does not start, check to make sure that the command line to start it includes the current InterChange Server Express name.

Running, stopping, and pausing connectors using System Monitor

After the connector has been initialized, you can start, stop, and pause it using Web-based System Montor from System Manager:

Web-based System Monitor

  1. While viewing the System Overview view (see Figure 10), select a connector by placing check in the box to its left.
  2. Select the Start, Pause, or Stop icon from the icon group in the upper-left corner of the view (see Figure 11).

Figure 11. Web-based System Monitor, icons for starting, pausing, restarting, or shutting down components


Commands for changing connector states

The following list describes the commands you can use to change the connector state and describes their processing actions:

Start NameConnector
Starts the connector for the application Name if it is paused or stopped. Connectors poll the application and connector controllers read the persistent queue. Flows are processed.

Pause NameConnector
Pauses the connector for the application Name if it is running or stopped. Connectors stop polling the application and connector controllers stop reading the persistent queue. Flows are not processed.

Stop NameConnector
Stops the connector for the application Name if it is running or paused. Connectors stop polling the application and fail requests with an exception message. Connector controllers stop reading the persistent queue. Flows and requests are not processed.

Shut Down NameConnector
Shuts down the connector for the application Name. The connector's process is stopped.

Boot Up Connector Agent
Restarts the connector for the application Name. This action is available only if you have set the OADAutoRestartAgent property of the connector to True. See "Setting Automatic and remote restart for a connector".

Manually starting a connector

Starting a connector manually

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 Express repository and is loaded when you load the repository.

Starting InterChange Server Express automatically initializes every connector defined in the repository. The connector is available for use whenever InterChange Server Express is running.

Note:
To make a connector functional for the first time, you must configure it before you start the connector.

You can start the connector in several ways:

Note:
To figure out whether the connector is a Java connector or a C++ connector, navigate to ProductDir\documentation\wbia_adapters\featurechecklists\ versionlist.htm in your local directory, where ProductDir 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 6 to customize the startup of a connector.

Table 6. 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 InterChange Server Express (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.
  • To specify the number of milliseconds, provide a value for pollFrequency.
  • To cause the connector to poll only when you type the value p in the connector's Command Prompt window, specify the -fkey option.
  • If a connector is configured to processes only business object requests and not application events, polling is unnecessary; you can disable polling by specifying -fno.

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.

Shutting down a connector

The generic connector manager script calls the appropriate start_connector.sh script, which handles the actual connector management for the connector. The Business Integration Express for Item Sync 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 "Setting Automatic and remote restart for a connector".

To shut down a connector using Web-based System Monitor:

  1. From the System Overview view, select the collaboration object of the connector you want to shut down by placing a check in the box to its left, then click the Pause icon from the upper-left corner of the view (see Figure 11). Do this for each collaboration associated with the connector.
  2. Select the connector you want to shut down by placing check in the box to its left, then click the Shutdown icon from the upper-left corner of the view (see Figure 11).

Restarting a connector

This action is used to restart the connector after you have used the Shut Down Connector action the Web-based System Monitor. This action is available only if you have enabled automatic and remote restart for the connector (see "Setting Automatic and remote restart for a connector").

To restart a connector:

  1. From the System Overview view (see Figure 10), place a check in the box to the left of the connector you want to restart.
  2. Click the Restart Agent icon from the upper-left corner of the view (see Figure 11).

Setting Automatic and remote restart for a connector

You can enable a connector to attempt to restart automatically after it has shut down abnormally and to be capable of a remote restart from System Monitor. (If a connector is already a member of an HA group, the connector restart feature is redundant and should not be enabled.)

WebSphere MQ setup for automatic connector restart

To use WebSphere MQ to automatically restart a connector, perform these steps:

  1. Enable WebSphere MQ Trigger Monitor

    The WebSphere MQ monitor has to be running as a daemon to monitor the incoming triggering event and then activate the corresponding adapter. You must start the standalone process, runmqtrm (or runmqtmc if you are running WebSphere MQ client), on the same machine on which the connector agent resides. (Alternatively, you can install the WebSphere MQ monitor as a Windows NT service, as described later in this section.)

  2. Run the mqtriggersetup.bat file with required arguments. This batch file adds and configures a queue to transport the triggering event.

    The batch file is located in thedirectory of your product installation; for example:

    C:\IBM\WebSphereItemSync\bin\mqtriggersetup.bat
     

    The arguments for the file are:

    For example:

    mqtriggersetup.bat WebSphereICS.queue.manager iSoft C:\IBM\WebSphereItemSync\connectors\ISoft\Start_ISoft.bat WebSphereICS
     

Enabling OAD for connectors

To enable remote starting and automatic restart to be used by a connector for the first time, perform these steps:

  1. Start InterChange Server Express (ICS).
  2. From System Manager, double-click the connector. This opens Connector Configurator.
  3. Set the following standard properties in the Standard Properties tab. To enable OAD for the connector, set the OADAutoRestartAgent value to True:

    Table 7. Configuring standard properties in Connector Configurator
    Name Possible Values Description Default Values
    OADAutoRestartAgent true or false If set to true, the OAD will automatically attempt to restart the connector after an abnormal shutdown. It can also be used to start the connector agent remotely. This value is dynamic. false
    OADAutoRestartAgent true or false If set to true, the OAD will automatically attempt to restart the connector after an abnormal shutdown. It can also be used to start the connector agent remotely. This value is dynamic. false
    OADAutoRestartAgent true or false If set to true, the OAD will automatically attempt to restart the connector after an abnormal shutdown. It can also be used to start the connector agent remotely. This value is dynamic. false

The steps described above register one connector with the OAD. When you have performed these steps, OAD becomes active for that connector, and will automatically restart the connector until and unless you deactivate the OAD feature by changing the OADAutoRestartAgent value to False.

Toggling Automatic and Remote Restart

To toggle the automatic and remote restart feature on and off, change the value of the OADAutoRestartAgent property in the Connector Configurator window for the connector. The change is dynamic: When you set the value to False, automatic restart is disabled. When you set the value to True, automatic restart is enabled. You do not need to restart InterChange Server Express for the change to take effect.

If OAD Terminates Abnormally

If the connector shuts down abnormally and the OAD also terminates abnormally before it is able to restart the connector, the connector will not be automatically restarted when you restart OAD. If this occurs, you will need to restart the connector.

Using OAD as a Windows service

If you are configuring a connector for automatic restart or remote starting using OAD, do not install the connector to run as a Windows service. Instead, install WebSphere MQ Trigger Monitor to run as a Windows service. When the Windows system starts, OAD will automatically start as a Windows service; when InterChange Server Express restarts, it will start the connector through OAD.

To install WebSphere MQ Trigger Monitor as a Windows service:

  1. Choose Start>Programs>IBM WebSphere MQ>WebSphere MQ Services.
  2. Right-click on the queue manager that Business Integration Express for Item Sync is using, and choose New>Trigger Monitor. The Create Trigger Monitor Service dialog appears.
  3. Select the Parameters tab. In the queue name field, enter the queue name that you have set up for the adapter.
  4. In the Description column of the display, Trigger Monitor appears as one of the services for that queue manager.
  5. Run the Windows Service Setup tool. Select "InterChange Serve Express" in the Service Component field, and in the Service Dependencies field enter the name for your OAD Windows service.

After completing these steps, you can use the Services tool in Windows to start and stop the daemon.

Configuring flow control for connectors

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, seeConfiguring system-wide flow control. This section describes how to configure flow control for connectors.

Note:
Configuration changes for individual connectors or collaboration objects are dynamic, meaning they do not require ICS to be rebooted. System-wide configuration changes for flow control require ICS to be rebooted.

To monitor how flow control is working in the system, you can use the default Flow Control monitor provided as part of the Web-based System Monitor, or you can create new Flow Control monitors for individual connectors or collaboration objects. For more information about monitoring flow control, see the description of the default Flow Control monitor inUsing default monitors, and the instructions on creating new monitors inCreating new monitors using the Monitor Definition Wizard. After you have all the flow control monitors created, refer to the following sections to begin monitoring flow control: Using the Web-based System Monitor and Logging on to the Web-based System Monitor.

To configure flow control for a connector, do the following:

  1. In System Manger, navigate to the connector for which you want to configure flow control, then double-click that connector. Connector Configurator opens (see Figure 12).

    Figure 12. Connector Configurator, Standard Properties tab


  2. In the Standard Properties tab, click in the Value cell of the MaxEventCapacity property.
  3. Change the value to represent the maximum number of events you want queued for a connector. The valid range of values for this property is from 1 to 2147483647.
  4. Click Save > to Project from the File drop-down menu. The following message appears in the bottom section of Connector Configurator: Connector '<name_of_connector>' is saved successfully.

Copyright IBM Corp. 1997, 2003