Administering 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.

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:

"Viewing connector states"

"Starting, stopping, and pausing connectors"

Steps for configuring flow control for connectors

Viewing connector states

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:

  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 (see Figure 11) 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 Setting up views to monitor the system 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 23).

    Figure 23. System Monitor, System Overview displaying connector status

    The figure shows a view of the connector states. This screen displays the component name, the type of component, for example, collaboration or connector, the status of the component, for example, running, the time the connector was started and the total running time of the connector.

Note:
You may also view connector states using the Connector Overview view.

Steps for using System Manager to view connector states

Perform the following steps to view the state of a connector in System Manager:

  1. Connect to the InterChange Server instance that contains the connector you want to view. See Steps for connecting to an InterChange Server instance for instructions on connecting to an InterChange Server instance.
  2. Expand the InterChange Server instance, then expand the Connectors folder.

    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.

Table 11. Connector States

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

Starting, stopping, and pausing connectors

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

"Connector initialization"

"Steps for starting, stopping, and pausing connectors using System Monitor"

System Manager commands for changing connector states

"Steps for manually starting a connector"

"Shutting down a connector"

"Restarting a connector"

"Steps for setting automatic and remote restart for a connector"

Connector initialization

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.

Steps for starting, stopping, and pausing connectors using System Monitor

Perform the following steps to start, stop and pause connectors using System Monitor:

  1. While viewing the System Overview view (see Figure 23), 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 24).

Figure 24. System Monitor, icons for starting, pausing, restarting, or shutting down components

The figure shows Icon group for the connector. From left to right, the icon buttons are the Start button, which is a green circle with a white arrow pointing to the right, the Pause button, which is two vertical, parallel thin yellow bars, the Stop button, which is a red octagon, the Restart Agent button, which is a small blue arrow laying on top of a larger green arrow both pointing to the right, and the Shutdown button, which is a white X on a red square.

Note:
You may also start, stop or pause connectors from the Connector Overview. Connector Agents can be shutdown or restarted from this same view.

Steps for starting, stopping, and pausing connectors using System Manager

Perform the following steps to start, stop and pause connectors using System Manager:

  1. From the Connectors folder in the InterChange Server Component Management view of System Manager (see Figure 29), right-click the name of a connector.
  2. Select one of the start, pause, or stop connector options.

System Manager 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 "Steps for setting automatic and remote restart for a connector".

Steps for manually starting a connector

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:

Important:
If you are using Installer to update an existing connector that uses a local configuration file or whose connector_manager_connector script has been customized, back up the original connector_manager_connector script and configuration file before beginning installation

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.
  • 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 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. 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:
  • -tSINGLE_THREADED: only a single thread accesses the application (The SAP connector uses -tSINGLE_THREADED.)
  • -tMAIN_SINGLE_THREADED: only the main thread accesses the application
  • -tMULTI_THREADED: multiple threads can access the application

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.

Note:
The connector startup script requires the existence of the CWSharedEnv.sh file. If this file does not exist, the startup script generates a warning and exits. Before you attempt to run the connector startup script again, use the product Installer to create the CWSharedEnv.sh file. Verify that the shell startup script (such as .cshrc) sources the CWSharedEnv.sh file.

You can also use the connector_manager_connector script to perform the following tasks:

Note:
System Manager runs on a Windows client machine. It can monitor or stop a connector installed on a UNIX machine.

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.

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
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.
  • 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 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:

  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 24). 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 24).

Steps for shutting down a connector in System Manager:Perform the following steps in System Manager to shut down a connector:

  1. From the expanded Collaboration Objects folder n the InterChange Server Component Management view of System Manager, (see Figure 27), right-click the collaboration object associated with the connector, then choose Pause. Do this for each collaboration associated with the connector.

    The color on the collaboration object icon turns to yellow.

  2. From the expanded Connectors folder in the InterChange Server Component Management view of System Manager, right-click the connector, then select Shut Down.

Attention:
Do not use the Ctrl+C key sequence to shut down a connector. Doing so prevents the connector from shutting down in an orderly manner. In addition, if you do use the Ctrl+C key sequence, or if you use "q," or other manual methods to perform the shutdown, and OAD is enabled, OAD will immediately restart the connector.

Restarting a connector

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:

  1. From the System Overview view (see Figure 23), 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 24).

Steps for restarting a connector in System Manager:Perform the following steps in System Monitor to shut down a connector:

  1. From the expanded Connectors folder in the InterChange System Component Management view of System Manager, (see Figure 29), right-click the connector you want to restart.
  2. Click Boot <name_of_connector>.

Steps for setting automatic and remote restart for 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:

Note:
If the connector is already a member of a High Availability group, the automatic restart property would be redundant and should be disabled.

Perform the following steps to set up automatic and remote restart for a connector:

  1. Install IBM WebSphere MQ.

    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.

    Important:
    The WebSphere MQ-trigger Monitor must exist on the machine on which the connector agent resides. If multiple connector agents reside on a single machine, only one MQ-trigger Monitor needs to exist.
  2. Start the MQ-trigger Monitor.
    To start the MQ-triggered OAD, you must start MQ-trigger Monitor, which can be done in either of the following ways:
  3. Configure a connector for the automatic and remote restart. Refer to Steps for enabling connectors for MQ-triggered OAD below.
  4. Run the mqtriggersetup.bat script for each connector that needs to be restarted. (The mqtriggersetup.bat script is located in the bin directory.)

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:

  1. Start InterChange Server Express.
  2. Open System Manager.
  3. Double-click the connector under Integration Component Libraries. This opens Connector Configurator Express.
  4. On the Standard Properties tab, set the standard properties shown in Table 14.


    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:

Steps for 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, seeSteps for configuring 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 InterChange Server to be rebooted. System-wide configuration changes for flow control require InterChange Server to be rebooted.

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:

  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 25).

    Figure 25. Connector Configurator, Standard Properties tab

    The figure shows the Connector Configurator tab. From let to right, it features the Standard Properties tab, the Connector Specific Properties tab, the Supported Business Objects tab, the Associated Maps tab, the Resources tab, the Trace/Log Files tab, the Messaging tab and the Data Handler 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, 2004