Administering connectors

Administering 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 System Monitor or System Manager, and you can manually start connectors using scripts in Windows, OS/400 and i5/OS and Linux.

The generic connector manager script calls the appropriate start_connector.bat or start_connector.sh script, which handles the actual connector management (including shutdown) for the connector. The InterChange Server Express product provides a start_connector.bat or start_connector.sh script for each connector it delivers.

This section includes the following topics:

Viewing connector states

Starting, stopping, and pausing connectors

Steps for configuring flow control for connectors

Steps for changing user profiles for adapter agents on OS/400 and i5/OS

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 in System Manager. To use System Manager, follow the instructions in Steps for connecting to an InterChange Server Express instance.

The state of a connector is represented differently, depending on which tool you are using.

Steps for using System Monitor to view connector states

Perform the following steps to see the state of connectors in System Monitor:

  1. Log on to System Monitor (see Steps for logging on to System Monitor).
  2. If the System Overview view is not displayed, click the System Overview link under Views. The System Overview Monitor appears.

    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.

  3. Click the triangle next to the name of the server to display a list of components on the system.
  4. Click the triangle next to a running collaboration to display its associated connectors (see Figure 27).
    Figure 27. System Monitor, System Overview displaying connector state

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 Express instance that contains the connector you want to view. See Steps for connecting to an InterChange Server Express instance for instructions on connecting to an InterChange Server Express instance.
  2. Expand the InterChange Server Express instance, then expand the Connectors folder.

    The connectors appear under the expanded Connectors folder with different colored lights to indicate their different states.

    Figure 28. Connectors folder in the InterChange Server Component Management view

Table 6 lists the connector states represented by the display color of each connector and shows what actions are being performed during that state.

Table 6. Connector states
Connector state (color) 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.

This section covers the following topics:

Connector initialization

Steps for starting, stopping, and pausing connectors

System Manager commands for changing connector states

Steps for manually starting a connector on Windows

Steps for manually starting a connector on OS/400 and i5/OS

Steps for manually starting a connector on Linux

Shutting down a connector

Restarting a connector

Setting automatic and remote restart for a connector

Steps for using OAD as a Windows service

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 manually starting a connector on Windows.

If the connector does not start, check to make sure that the command line to start it includes the current InterChange Server Express name. For more information, refer to the WebSphere Business Integration Server Express installation guide for Windows, for Linux, or for OS/400 and i5/OS.

Steps for starting, stopping, and pausing connectors

After the connector has been initialized, you can start, stop, and pause it with System Monitor or System Manager.

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

  1. When viewing the System Overview view (see Figure 27), specify a connector by selecting the check 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 29).

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

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

  1. In System Manager, go to the Connectors folder in the InterChange Server Component Management view (see Figure 28).
  2. Right-click the name of a connector, then select Start ConnectorName, Pause ConnectorName, or Stop ConnectorName.

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 ConnectorName
Starts the selected connector if it is paused or stopped. Connectors poll the application and connector controllers read the persistent queue. Flows are processed.
Pause ConnectorName
Pauses the selected connector if it is running or stopped. Connectors stop polling the application and connector controllers stop reading new requests, but events continue to be processed.
Stop ConnectorName
Stops the selected connector 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 ConnectorName
Shuts down the selected connector. The connector's process is stopped.
Boot ConnectorName
Restarts the selected connector. 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.

Steps for manually starting a connector on Windows

When you install the IBM WebSphere Business Integration Adapters, 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. See the adapter guide for the connectors you are using for configuration instructions.

Perform one of the following steps to start the connector:

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 7 to customize the startup of a connector. -

Table 7. Connector startup parameters
Parameter Function
-b Causes the adapter agent to run as a background process. This prevents the agent from attempting to read for the 'q' (quit) character from system input. Agents reading from system input pose a performance bottleneck for agents running within an iSeries subsystem.
-c configFile Name of the configuration file to be used during startup. If the file name 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 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 Express.
-s serverName Specifies the name of the 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.

Steps for manually starting a connector on OS/400 and i5/OS

Connector agents running on an OS/400 and i5/OS are normally started and stopped in one of three ways.

Perform one of the following steps to manually start a connector on OS/400 and i5/OS:

Steps for manually starting a connector on Linux

Perform one of the following steps to manually start a connector on Linux:

Shutting down a connector

This section covers the following topics:

Steps for shutting down a connector in System Monitor

Steps for shutting down a connector in System Manager

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 check box is selected 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.

Instructions for shutting down a connector depend on which tool you use to monitor the system:

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 for the connector that you want to shut down by selecting the check box to its left and click the Pause button in the upper-left corner of the view (see Figure 29). Do this for each collaboration associated with the connector.
  2. Select the check box for the connector that you want to shut down and click the Shutdown button in the upper-left corner of the view (see Figure 29).
Steps for shutting down a connector in System Manager

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

  1. Expand the Collaboration Objects folder in the InterChange Server Component Management view (see Figure 32).
  2. Right-click the collaboration object associated with the connector and click Pause CollaborationName. Do this for each collaboration associated with the connector.

    The collaboration object icon changes to an icon with two vertical lines.

  3. From the expanded Connectors folder in the InterChange Server Component Management view, right-click the connector and click Shut Down ConnectorName.
Attention:
Do not use Ctrl+C or the ENDJOB CL command to shut down a connector. Doing so prevents the connector from shutting down in an orderly manner. In addition, if you use the Ctrl+C, the ENDJOB CL command, or if you use "q" or other manual methods to perform the shutdown, and the Object Activation Daemon (OAD) is enabled, OAD immediately restarts the connector.

Restarting a connector

The procedures described in this section restart the connector after you have used the Shut Down Connector action in either System Monitor or in System Manager in the InterChange Server Component Management view. 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).

This section covers the following topics:

Steps for using System Monitor to restart a connector

Steps for using System Manager to restart a connector

Steps for using System Monitor to restart a connector

Perform the following steps in System Monitor to restart a connector:

  1. From the System Overview view (see Figure 27), select the check box to the left of the connector that you want to restart.
  2. Click the Restart Agent button in the upper-left corner of the view (see Figure 29).
Steps for using System Manager to restart a connector

Perform the following steps in System Manager to restart a connector:

  1. Expand the Connectors folder in the InterChange System Component Management view of System Manager, (see Figure 28).
  2. Right-click the connector that you want to restart, then click Boot ConnectorName.

Setting automatic and remote restart for a connector

With the Object Activation Daemon (OAD), triggered by IBM WebSphere MQ, you can enable a connector to support the automatic-and-remote-restart feature, which allows the connector to handle the following conditions:

This section covers the following topics:

Steps for setting automatic and remote restart for a connector on Windows

Steps for setting automatic and remote restart for a connector on Linux

Steps for setting automatic and remote restart for a connector on OS/400 and i5/OS

Steps for enabling connectors for MQ-triggered OAD

Steps for setting automatic and remote restart for a connector on Windows

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

  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 (located in the bin directory) for each connector that needs to be restarted, for example:
    mqtriggersetup.bat WebSphereICS.queue.manager JDBC WebSphereICS D:/IBM/WebSphereServer/connectors/JDBC/start_JDBC.bat
Steps for setting automatic and remote restart for a connector on Linux

Perform the following steps to set automatic and remote restart for a connector on a Linux platform:

The arguments for the file are:

For example:

mqtriggersetup 
WebSphereICS.queue.manager 
JDBC 
/home/smbadmin/IBM/WebSphereItemSync/connectors/JDBC/start_JDBC.sh 
JDBC WebSphereICS
Steps for setting automatic and remote restart for a connector on OS/400 and i5/OS

Perform the following steps to set automatic and remote restart for a connector on a OS/400 and i5/OS platform:

  1. Run mqtriggersetup.sh with the required arguments to add and configure a queue to transport the triggering event. This file is located in the directory of your product installation, for example, /QIBM/ProdData/WBIServer44/bin. The arguments for the file are: For example:
    mqtriggersetup.sh 
    InstanceName.QUEUE.MANAGER 
    JDBC 
    /QIBM/UserData/WBIServer44/QWBIDFT44/connectors/JDBC/start_JDBC.sh 
    InstanceName 
    QWBIJDBCC 
    where InstanceName is the name of the InterChange Server Express instance, typed in capital letters.
  2. Enable WebSphere MQ Trigger Monitor. For example:
    STRMQMTRM INITQNAME(INITIATION.QUEUE)
    MQMNAME(InstanceName.QUEUE.MANAGER)
    where InstanceName is the name of the InterChange Server Express instance, typed in capital letters.
  3. Grant the QMQM user profile *USE authority to the following objects:
    The job description (*JOBD) for the adapter (for example, QWBISVR44/QWBIJDBCC for JDBC)
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 8.

    Table 8. 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 using OAD as a Windows service

Note:
This topic applies only to Windows platforms.

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

Important:
By default, connectors are installed as Windows services which need to be manually started. The remote restart feature does not function if the connector's Windows service is changed from manual to automatic.

Perform the following steps to install WebSphere MQ Trigger Monitor as a Windows service:

  1. Select Start > Programs > IBM WebSphere MQ > WebSphere MQ Services.
  2. Right-click the queue manager that WebSphere Business Integration Server Express is using, and click New > Trigger Monitor. The Create Trigger Monitor Service dialog box appears.
  3. Click the Parameters tab. In the queue name field, type the string "INITIATION.QUEUE". In the Description column, Trigger Monitor appears as one of the services for that queue manager.
  4. Run the Windows Service Setup tool. Select InterChange Server Express in the Service Component list
  5. In the Service Dependencies field, type 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.

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 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, see Steps 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 Express to be rebooted. System-wide configuration changes for flow control require InterChange Server Express 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 in System Manager in the InterChange Server Component Management view. 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, see Steps for viewing collaboration object statistics or Steps for viewing connector statistics.

Perform the following steps to configure flow control for a connector:

  1. In System Manager, navigate to the connector for which you want to configure flow control, then double-click that connector. Connector Configurator Express opens (see Figure 30).
    Figure 30. Connector Configurator Express, Standard Properties tab
  2. In the Standard Properties tab, click in the Value cell of the MaxEventCapacity property.
  3. Change the value to the maximum number of events that you want queued for a connector. The valid range of values for this property is from 1 to 2147483647.
  4. Click File > Save > to Project. The following message appears in the bottom section of Connector Configurator Express: Connector'ConnectorName' is saved successfully.
  5. Redeploy the connector.

Steps for changing user profiles for adapter agents on OS/400 and i5/OS

By default, the adapter agents on OS/400 and i5/OS run under QWBISVR44 user profile. So, this user profile must have the authority to read and possibly update the application information. If you cannot give profile QWBISVR44 this authority, you can change the user profile used for the adapter agent process.

Perform the following steps to change the user profile for the adapter agent process:

  1. Change the job description for the adapter agent using the CHGJOBD CL command as follows:
    CHGJOBD JOBD(QWBISVR44/jobdname) USER(newid)
    where jobdname is the job description name for the adapter agent and newid is the user profile you want the adapter agent to run under. The newid user profile should already have authority to your application information.
  2. Give authority to the adapter job description for your user profile using the following CL command:
    GRTOBJAUT OBJ(QWBISVR44/jobdname) OBJTYPE(*JOBD) USER(newid)
    where jobdname is the job description name for the adapter agent and newid is the user profile you want the adapter agent to run under.
  3. Give authority to QWBISVR44 library for your user profile using the following CL command:
    GRTOBJAUT OBJ(QWBISVR44) OBJTYPE(*LIB) USER(newid)
    where newid is the user profile you want the adapter agent to run under.
  4. Give authority to QWBISVR44 subsystem description for your user profile using the following CL command:
    GRTOBJAUT OBJ(QWBISVR44/QWBISVR44) OBJTYPE(*JOBD) USER(newid)
    where newid is the user profile you want the adapter agent to run under.
  5. Give authority to QWBISVR44 class in QWBISVR44 library for your user profile using the following CL command:
    GRTOBJAUT OBJ(QWBISVR44/QWBISVR44) OBJTYPE(*CLS) USER(newid)
    where newid is the user profile you want the adapter agent to run under.
  6. Give authority to connector directory where the adapter startup script is located for your user profile using the following CL command:
    CHGAUT OBJ('/pathToStartupScript') USER(newid) DTAAUT(*RWX)
    where pathToStartupScript is the path to the startup script for the adapter and newid is the user profile you want the adapter agent to run under.

Copyright IBM Corp. 2004, 2005