Starting up a new connector

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

Table 109. Startup scripts for a connector

Operating system Startup script
UNIX, AIX 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 with the appropriate 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 the Implementation Guide for WebSphere MQ Integrator Broker 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
     

    Make sure that the directory name matches the connector name (connName). The connector name is a string that uniquely identifies the connector. For more information, see The connector definition name.

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

    A Java connector's library file is a Java archive (jar) file. You created this jar file when you compiled the connector. For more information, see "Compiling the connector".

Creating startup scripts

As Table 109 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 platform on which you are developing your connector.

Startup script and shortcut on Windows systems

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

Figure 70 shows the call to start_PeopleSoft.bat that the Programs > IBM WebSphere Business Integration Adapters > Adapters > Connectors > PeopleSoft option invokes.

Figure 70. Installed shortcut for IBM WebSphere Business Integration Adapter for PeopleSoft

ProductDir\connectors\PeopleSoft\start_PeopleSoft.bat PeopleSoft ICSServer
 
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 a WebSphere MQ Integrator Broker instance, that instance name would appear in the shortcut command line.

To provide the ability to start up your own connector, you must generate its startup script and provide the shortcuts that invoke this startup script.

Creating the startup script

The start_connName.bat startup script is not generic; that is, no single startup script exists that can start up any Java connector. Instead, you must create a custom startup script for your Java connector and include the connector name (connName) in the startup script name. However, this startup script does make assumptions about your connector's runtime files. It assumes that the connector name identifies the following:

For example, if your Java connector has a connector name of MyJava, then it is started with the start_MyJava.bat startup script. The connector's runtime files must reside in the ProductDir\connectors\MyJava directory and its jar file must reside in that directory with the name CWMyJava.jar.

To create a custom Java connector startup script, you create a new startup script called start_connName.bat (where connName is your Java connector name) and copy into this new startup script the sample startup script shown in Figure 71.

Figure 71. Sample Java startup script for Windows platforms

REM @echo off
 call "%CROSSWORLDS%"\bin\CWConnEnv
 setlocal
 
REM Define local batch PATH to insure we execute our JRE
 set PATH="%CROSSWORLDS%"\bin;%PATH%
 
REM set the directory where the specific connector resides
 set CONNDIR=%CROSSWORLDS%\connectors\%1
 
REM goto the connector specific drive & directory
 cd /d %CONNDIR%
 
REM set the name to be the connector that is starting
 set CONNAME=%1
 set CONNPACKAGENAME=com.crossworlds.connectors.connName.connectorClass
 
REM set the server name to be the integration broker that is being targeted
 set SERVER=%2
 
REM set AGENT to the adapter jar.
 set AGENT=%CONNDIR%\CW%CONNAME%.jar
 
REM Add any application specific jars to the JCLASSES variable.
 set JCLASSES=.;%JCLASSES%;%AGENT%
 
REM config file location defaults to HOME\InterchangeSystem.cfg on the local machine
 
REM start the Java connector under the Java Application End
 "%CROSSWORLDS%\bin\java" -mx128m -Dorg.omg.CORBA.ORBClass=%ORBCLASSPATH% 
 -Dorg.omg.CORBA.ORBSingletonClass=%ORBCLASSPATH% -Duser.home="%CROSSWORLDS%" 
 -classpath %JCLASSES% AppEndWrapper -l%CONNPACKAGENAME% -n%CONNAME% -s%SERVER%
 %3 %4 %5
 
endlocal
 pause
 

In this start_connName.bat file, make sure you:

Creating the shortcut

A shortcut enables a connector to be started from a menu option within Programs > IBM WebSphere Business Integration Adapters > Adapters > Connectors. An easy way to create a shortcut to start a Java connector running on Windows is to copy an existing Java connector's shortcut and edit the shortcut properties to change the connector name or add any other startup parameters.

For example, for the MyJava Java connector, you could copy the shortcut for the IBM WebSphere Business Integration Adapter for PeopleSoft (see Figure 70) and replace PeopleSoft with MyJava (both in the startup script name and the connector name on the command line), as Figure 72 shows.

Figure 72. Connector shortcut for MyJava connector

ProductDir\bin\start_MyJava.bat MyJava MyICS
 

This simple way to create a shortcut for a Java connector assumes that you have already created the connector's custom startup script.

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 a WebSphere MQ Integrator Broker instance, that instance name would appear in the shortcut command line.

Startup script on UNIX systems

When the WebSphere Business Integration Adapters Installer installs connectors on a UNIX-based system, it takes the following steps:

The connector_manager_connName.sh startup script is not generic; that is, no single startup script exists that can start up any connector. Instead, you must create a custom startup script for your connector and include the connector name (connName) in the startup script name. This startup script does make assumptions about your connector's runtime files. It assumes that the connector name identifies the following:

For example, if your Java connector has a connector name of MyJava, then it is started with the connector_manager_MyJava startup script. The connector's runtime files must reside in the ProductDir/connectors/MyJava directory and its jar file must reside in that directory with the name CWMyJava.jar. In addition, the start_MyJava.sh script must also reside in this ProductDir/connectors/MyJava directory.

To create a custom connector startup script, take the following steps:

Custom connector manager script

To create a custom connector manager script, connector_manager_connName, you can use the Connector Script Generator tool (ConnConfig.sh in the product bin directory). Once you specify the connector name (connName), this tool generates the connector_manager_connName startup script and puts it in the bin subdirectory of the product directory. For information on this tool, see Appendix C, Connector Script Generator.

Custom startup script

To create a custom startup script, create a new startup script called start_connName.sh (where connName is your connector name) and copy into this new startup script the sample startup script shown in Figure 73.

Figure 73. Sample connector startup script for UNIX platforms

#!/bin/sh
 ################################################
 # General connector variable initialization section
 # No changes should be necessary
 # set CONNECTOR_TYPE  -- This is needed to differentate Java from C++ connectors 
 # set CONDIR  the directory where the specific connector resides, then change to this directory
 # set CONNAME the name to be the application connector that is starting
 # set SERVER  the server name to be the interchange that is being targeted
 # set CONJAR to the fullpath of the connector .jar file.
 
CONNAME=$1
 SERVER=$2
 . ${CROSSWORLDS}/bin/CWConnEnv.sh
 echo $CWCLASSES
 CONDIR=${CROSSWORLDS}/connectors/${CONNAME}
 if [ "${OS}" = "AIX" ]
 then
 LIBPATH=${CONDIR}:${LIBPATH}
 export LIBPATH
 else
 LD_LIBRARY_PATH=${CONDIR}:${LD_LIBRARY_PATH}
 export LD_LIBRARY_PATH
 fi
 
# Connector-specific variable initialization section
 # Set your Connector agent here 
 # The following two sections tell the script what language the connector was written in,
 # and help it make the correct calls. 
 # Please enable one of the next sections
 ###For C++ connectors enable the following:
 #CONNECTOR_TYPE="-d"
 #CONNECTOR_AGENT=${CONNAME}
 #AGENT=""
 #LOCAL_JVM_FLAGS=${CONN_CPP_JVM_FLAGS}
 ###For Java connectors enable the following:
 #CONNECTOR_TYPE="-l"                                                                
 #CONNECTOR_AGENT=com.crossworlds.connectors.connName.connBaseClass
 #AGENT=${CONDIR}/CW${CONNAME}.jar
 #LOCAL_JVM_FLAGS=${CONN_JAVA_JVM_FLAGS}
 
# Set any connector-specific startup options here (Like -t or -fno etc.)
 CON_START_OPTIONS=" "  
 
# Add any application-specific jars to CWCLASSES variable.
 CWCLASSES=${CWCLASSES}:%AGENT%
 
# We are using the JVM_FLAGS that are set in the CWSharedEnv.sh file, if you need to use 
 # different flags, change $JVM_FLAGS to be what you need to use.
 # No changes should be necessary below this line.
 
CLASSPATH=${CONJAR}:${CWCLASSES}
 echo $CLASSPATH
 ${CROSSWORLDS}/bin/check_path.sh "$CLASSPATH"
 if [ "${OS}" = "AIX" ]
 then
 exec ${CWJAVA} ${LOCAL_JVM_FLAGS} -Djava.library.path=${LD_LIBRARY_PATH} -Djava.ext.dirs= -classpath
  ${CLASSPATH} AppEndWrapper ${CONNECTOR_TYPE}${CONNECTOR_AGENT} -n${CONNAME} -s${SERVER}
 ${CON_START_OPTIONS} $3 $4 $5 $6 $7 $8 $9
 else
 exec ${CWJAVA} ${LOCAL_JVM_FLAGS} -Djava.library.path=${LIB_PATH} -Djava.ext.dirs= -classpath 
  ${CLASSPATH} AppEndWrapper ${CONNECTOR_TYPE}${CONNECTOR_AGENT} -n${CONNAME} -s${SERVER}
  ${CON_START_OPTIONS}  $3 $4 $5 $6 $7 $8 $9
 fi
 

In this start_connName.sh file, make sure you:

Note:
Make sure that the line to invoke the connector runtime is all on one line in your startup script; that is, no carriage returns should exist at the line breaks shown in the sample startup script in Figure 73.

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 the Implementation Guide for WebSphere MQ Integrator Broker in the WebSphere Business Integration Adapters documentation set.

Copyright IBM Corp. 1997, 2003