Starting up a new connector

To start up the connector, you execute a connector startup script. As Table 90 shows, the name of this startup script depends on the operating system which you are using.

Table 90. Startup scripts for a connector

Operating system Startup script
UNIX-based systems connector_manager_connName
Windows start_connName.bat

The startup script supports those adapters that the WebSphere Business Integration Adapters product provides. To start up a predefined connector, a system administrator runs its startup script. The startup scripts for most predefined connectors expect the following command-line arguments:

  1. The first argument is the connector name, which identifies the following:
  2. The second argument is the name of the integration broker instance against which the connector runs.
    WebSphere InterChange Server

    When your integration broker is InterChange Server (ICS), the startup script specifies the name of the ICS instance against which your connector runs. On Windows systems, this ICS instance name (which was specified in the installation process) appears in each of the connector shortcuts of the startup script.

    Other integrator brokers

    When your integration broker is a WebSphere message broker (WebSphere MQ Integrator, WebSphere MQ Integrator Broker, or WebSphere Business Integration Message Broker) or WebSphere Application Server, the startup script specifies the name of the broker instance against which your connector runs. On Windows systems, this instance name (which was specified in the installation process) appears in each of the connector shortcuts of the startup script.

  3. Optional additional startup parameters can be specified on the command line and are passed to the connector runtime.

    For more information about the startup parameters, see the System Administration Guide in the IBM WebSphere InterChange Server documentation set or your implementation guide in the WebSphere Business Integration Adapters documentation set.

WebSphere InterChange Server

Before you start a connector, InterChange Server must be running for the connector to complete its initialization and obtain its business objects from the repository.

Before you can start up a connector that you have developed, you need to ensure that a startup script supports your new connector. To enable a startup script to start your own connector, you must take the following steps:

  1. Prepare a connector directory for your connector.
  2. Create the startup script for your connector. For Windows systems, also create a shortcut for your connector startup.
  3. Set up the startup script as a Windows service (optional).

The following sections describe each of these steps.

Preparing the connector directory

The connector directory contains the runtime files for your connector. To prepare the connector directory, take the following steps:

  1. Create a connector directory for your new connector under the connectors subdirectory of the product directory:
    ProductDir\connectors\connName
    

    By convention, this directory name matches the connector name (connName). The connector name is a string that uniquely identifies the connector. For more information, see Naming the connector.

  2. Move your connector's library file to this connector directory.

    A C++ connector's library file is a DLL. You created this DLL when you compiled the connector. For more information, see "Compiling and linking a C++ connector".

Creating startup scripts

As Table 90 shows, a connector requires a startup script for the system administrator to start execution of the connector process. The startup script to use depends on the operating system on which you are developing your connector.

Startup script and shortcut on Windows systems

Starting a connector on a Windows system involves the following steps:

  1. Call the connector's startup script, start_connName.bat.

    The start_connName.bat script (where connName is the name of your connector) is a connector-specific startup script. It provides connector-specific information (such as application-specific libraries and their locations). By convention, this script resides in the connector directory:

    ProductDir\connectors\connName
    

    It is this start_connName.bat script that the user invokes to start the connector on a Windows system.

  2. Call the generic connector-invocation script, start_adapter.bat

    The start_adapter.bat file is generic to all connectors. It performs the actual invocation of the connector within the JVM. It resides in the bin subdirectory of the product directory. The start_connName.bat script must call the start_adapter.bat script to actually invoke the connector.

Figure 77 shows the steps to start a connector on a Windows system.

Figure 77. Starting a connector on a Windows system


When a WebSphere Business Integration Adapters Installer installs a predefined connector on a Windows system, it takes the following steps:

Important:
In previous releases, C++ connectors required a special startup script, called start_connector.bat. With this release (4.2.2 of IBM WebSphere InterChange Server and version 2.4 of WebSphere Business Integration Adapters), Java and C++ connectors can use the same startup script: start_connName.bat. New development of C++ connectors should use start_connName.bat as the startup script. However, the start_connector.bat script continues to be supported for backward compatibility.

To provide the ability to start up your own connector, you must duplicate these steps by:

Creating the startup script

To create a custom connector startup script, you create a new connector-specific startup script called start_connName.bat (where connName is your C++ connector name). For example, if your C++ connector has a connector name of MyCPP, its startup script name is start_MyCPP.bat. As a starting point, you can copy the startup-script template, which is located in the following file:

ProductDir\templates\start_connName.bat

Figure 78. shows a sample of the contents of the startup-script template for Windows. Please consult the version of this file released with your product for the most current contents.

Figure 78. Sample contents of the startup-script template for Windows

REM @echo off
setlocal
REM Set adapter specific variables
set ACCESS_JAR=%ACCESS_HOME%\lib\access.jar
set J2EE_JAR=%J2EE_HOME%\j2ee.jar
REM End adapter specific variables
REM Branch between WBIA_RUNTIME and CROSSWORLDS
REM IF WBIA_RUNTIME is set use start_adapter launcher to run adapter
If "%WBIA_RUNTIME%"=="" goto CROSSWORLDS
REM call CWConnEnv
call "%WBIA_RUNTIME%"\bin\CwConnEnv.bat
REM set the directory where the specific connector resides
set CONNDIR="%WBIA_RUNTIME%"\connectors\%1
REM goto the connector specific drive and directory. 
REM CONNDIR is defined by caller
cd /d %CONNDIR%
REM set variables that need to pass to callee
set JVMArgs=-AAA
set JCLASSES=AAA;%ACCESS_JAR%;%J2EE_JAR%;%JCLASSES%
set LibPath=AAA
set ExtDirs=AAA
call start_adapter.bat -nAccessDest -sWSICS 
       -lSamples.AccessTestConnector.AppConn 
       -fno -pnull -b -cAccessDest.cfg
goto END
:CROSSWORLDS
END
endlocal

By convention, the start_connName.bat script has the standard syntax shown in Figure 79, with connName being the name of the connector, ICSinstance being the name of the InterChange Server instance, and additionalOptions specifies additional startup parameters to pass to the connector invocation. These options include -c, -f, -t, and -x. For more information, see Table 92.

Figure 79. Standard syntax for Windows connector startup script

start_connName connName ICSinstance additionalOptions
 

As the connector developer, you control the content of start_connName.bat. Therefore, you can change the syntax of your connector startup script. However, if you change this standard syntax, make sure that all information that start_adapter.bat requires is available at the time of its invocation within start_connName.bat.

Note:
In the start_connName.bat syntax in Figure 79, the connName and ICSinstance arguments are required. The additionalOptions argument is optional.

The startup script with the standard syntax makes the following assumptions about your connector's runtime files based on the connector name (connName):

For example, for the MyCPP connector to meet these assumptions, its runtime files must reside in the ProductDir\connectors\MyCPP directory and its DLL must reside in that directory with the name MyCPP.dll. If y our connector cannot meet these assumptions, you must customize its startup script to provide the appropriate information to the generic connector-invocation script, start_adapter.bat.

In this start_connName.bat file, take the following steps:

  1. Move into the connector directory.
  2. Set the startup environment variables within the startup script with any connector-specific information and any connector-specific variables.
  3. Call the start_adapter.bat script to invoke the connector.
Note:
The start_adapter.bat script does not contain a pause statement to display information in the console. If startup fails and you want to view this information, include a pause statement in start_connName.bat to prevent the console from closing when the connector fails.

The following sections describe each of these steps.

Calling the environment file

The CWConnEnv.bat file contains environment settings for the IBM Java Object Request Broker (ORB) and the IBM Java Runtime Environment (JRE). The following line invokes this environment file within the startup script:

call "%WBIA_RUNTIME%"\bin\CWConnEnv

Moving into the connector directory

The start_connName.bat script must change to the connector directory before it calls the start_adapter.bat script. The connector directory contains the connector-specific startup script as well as other files needed at connector startup. You can define the name of this connector directory any way you wish. However, as discussed in Preparing the connector directory, by convention the connector directory name matches the connector name.

If the start_connName.bat script uses the standard syntax (see Figure 79), the connector name is passed in as the first argument (%1). In this case, the following lines move into the connector directory:

REM set the directory where the specific connector resides
set CONNDIR=%CROSSWORLDS%\connectors\%1

REM goto the connector specific drive & directory
cd /d %CONNDIR%

Alternatively, because the connector name is used in several components of the connector, you can define an environment variable to specify this connector name and then evaluate this environment variable for all subsequent uses of the connector name within the start_connName.bat script. The lines to set the environment variables for the connector name and connector directory could be as follows:

REM set the name of the connector
set CONNAME=%1

REM set the directory where the specific connector resides
set CONNDIR=%CROSSWORLDS%\connectors\%CONNAME%

REM goto the connector specific drive & directory
cd /d %CONNDIR%

Setting the environment variables

In the start_connName.bat script, you must provide any of the connector-specific information that the environment variables listed in Table 91 specify.

Table 91. Environment variables in the connector startup script

Variable name Value
ExtDirs Specify the location of any application-specific jar files.
JCLASSES Specify any application-specific jar files. Jar files are separated with a semicolon (;).
JVMArgs Add any arguments to be passed to the Java Virtual Machine (JVM).
LibPath Specify any application-specific library paths.

The start_adapter.bat file uses the information in Table 91 as follows:

In addition to the environment variables in Table 91, you can also define your own connector-specific environment variables. Such variables are useful for information that can change from release to release. You can set the variable to a value appropriate for this release and then include the variable in the appropriate line of the startup script. If the information changes in the future, you only have to change the variable's value. You do not have to locate all lines that use this information.

Invoking the connector

To actually invoke the connector within the JVM, the start_connName.bat script must call the start_adapter.bat script. The start_adapter.bat script provides information to initialize the necessary environment for the connector runtime (which includes the connector framework) with its startup parameters. Therefore, you must provide the appropriate startup parameters to start_adapter.bat. Table 92 shows the startup parameters that the start_adapter.bat script recognizes.

Table 92. Startup parameters for start_adapter.bat script

Startup parameter Description Required? Valid as additional
command-line option to start_connName.bat?
-cconfigFile The full path name of the connector's configuration file Required if integration broker is other than ICS Yes
-ddllName The name of the C++ connector's library file (dllName), which is a dynamic link library (DLL). This DLL name should not include the .dll file extension. Yes, for all C++ connectors No
-fpollFrequency

The amount of time between polling actions. Possible pollFrequency values are:

  • The number of milliseconds between polling actions
  • key: causes the connector to poll only when you type the letter p in the connector's startup window. The key option must be specified in lowercase.
  • no: causes the connector not to poll. The no option must be specified in lowercase.

No

Default is 1000 milliseconds

Yes
-j Indicates that the connector is written in Java No, as long as you specify the -l option for Java connectors No
-lclassname The name of the Java connector's connector class (className) Yes, for all Java connectors No
-nconnectorName The name of the connector (connectorName) to start Yes No
-sbrokerName The name of the integration broker (brokerName) to which the connector connects Yes No
-t Boolean value to turn off or on the connector property SingleThreadAppCalls, which guarantees that all calls the connector framework makes to the application-specific component are with one call-triggered flow. The default value is false. No Yes
-xconnectorProps

Initializes the value of an application-specific connector property. Use the following format for each property you specify:

propName=value
No Yes

Make sure that the call to start_adapter.bat includes the following startup parameters:

The syntax for the call to start_adapter.bat should have the following format:

call start_adapter.bat -nconnName -sICSinstance languageSpecificParams 
 -cCN_connNameConnector.cfg 
 -...

For example, the following line invokes the MyCPP connector:

call start_adapter.bat -dMyCPP
    -nMyCPP -sICSserver -cMyCPPConnector.cfg  -...

Note:
The preceding command line assumes that the connector is running against an InterChange Server instance whose name is ICSserver. If the connector runs against an instance of WebSphere MQ Integrator Broker or WebSphere Message Broker, that instance name would need to appear in the command line.

With the use of the CONNAME environment variable to hold the connector name, this call can be generalized to the following:

call start_adapter.bat -n%CONNAME% -s%2 languageSpecificParams
 -cCN_%CONNAME%Connector.cfg 
 -...

For the call to start_adapter.bat, keep the following points in mind:

Creating the shortcut

A shortcut enables a connector to be started from a menu option within Programs > IBM WebSphere Business Integration Adapters > Adapters > Connectors. The shortcut should list the call to the start_connName.bat script. If this script uses the standard syntax (see Figure 79), the shortcut would have the following form:

ProductDir\connectors\start_connName connName ICSinstance

If you define your own syntax for your start_connName.bat script, you must ensure that the shortcut uses this custom syntax.

If your menu already contains a shortcut for a C++ connector that uses the start_connName.bat startup script, an easy way to create a shortcut is to copy this existing connector's shortcut and edit the shortcut properties to change the connector name or add any other startup parameters.

For example, for the MyCPPconnector that uses the standard syntax for its startup script, you could create the following shortcut:

ProductDir\bin\start_MyCPP.bat MyCPP ICSinstance
Note:
The preceding command line assumes that the connector is running against an InterChange Server instance whose name is ICSinstance. If the connector runs against a WebSphere MQ Integrator Broker instance, that instance name would appear in the shortcut command line.

Startup script on UNIX systems

The Connector Development Kit (CDK) is supported only on Windows systems. It is not supported on UNIX-based systems. Because creation of a C++ connector is not supported on a UNIX-based system, you do not need to create startup scripts for such a connector.

Starting a connector as a Windows service

You can set up a connector to run as a Windows service that can be started and stopped by a remote administrator. For more information, see the System Installation Guide for Windows in the IBM WebSphere InterChange Server documentation set or your implementation guide in the IBM WebSphere Business Integration Adapter documentation set.

Note:
If you are using InterChange Server as your integration broker and you want to use the automatic-and-remote restart feature with the connector, do not start connector as a Windows service. Instead, start the MQ Trigger Monitor as a service. For more information, see the System Administration Guide in the IBM WebSphere InterChange Server documentation set.

Copyright IBM Corp. 1997, 2004