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.

    WebSphere MQ Integrator Broker

    When your integration broker is WebSphere MQ Integrator Broker, the startup script specifies the name of the WebSphere MQ Integrator 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 A sample of start_connName.bat which calls start_adapter.bat
 @echo off
 
call "%ADAPTER_RUNTIME%"\bin\wbia_connEnv.bat
 setlocal
 
REM If required, goto the connector specific directory. CONNDIR is defined 
 RED by caller
 cd /d %CONNDIR%
 
REM set variables that need to pass to start_adapter.bat
 REM set JVMArgs=
 REM set JCLASSES=
 REM set LibPath=
 REM set ExtDirs=
 
REM A sample to start a C++ connector
 REM call start_adapter.bat -nconnName -sServerName -dconnectorDLLfile -f... 
 REM -p... -c... ...
 
REM A sample to start a Java connector
 call start_adapter.bat -nconnName -sserverName -lconnectorSpecificClasses 
 -f... -p... -c... ...
 
endlocal
 

By convention, the start_connName.bat script has the standard syntax shown in Figure 79, with connName being the name of the connector and ICSinstance being the name of the InterChange Server instance.

Figure 79. Standard syntax for connector startup script

start_connName connName ICSinstance
  
 

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.

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. Call the CWConnEnv.bat environment file to initialize the startup environment.
  2. Move into the connector directory.
  3. Set the startup environment variables within the startup script with any connector-specific information and any connector-specific variables.
  4. Call the start_adapter.bat script to invoke the connector.

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 "%ADAPTER_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, including:

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.

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 WebSphere Business Integration Adapters 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.

Copyright IBM Corp. 1997, 2003