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, AIX connector_manager_connName
Windows

start_connector.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 C++ connector's library file is 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 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 77 shows the call to start_connector.bat that the Programs > IBM WebSphere Business Integration Adapters > Adapters > Connectors > Clarify option invokes.

Figure 77. Installed shortcut for IBM WebSphere Business Integration Adapter for Clarify

ProductDir\bin\start_connector.bat Clarify 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_connector.bat startup script is generic; that is, it can start up any C++ connector. Therefore, you do not have to create a custom startup script for a C++ connector. 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 C++ connector has a connector name of MyCPP, then to be started with the start_connector.bat startup script, the connector's runtime files must reside in the ProductDir\connectors\MyCPP directory and its DLL must reside in that directory with the name MyCPP.dll.

If your C++ connector does not meet the assumptions of the start_connector.bat startup script, you might need to copy and rename the start_connector.bat file, edit the renamed version as needed, and create a shortcut for this new startup file. IBM suggests that you rename the start_connector.bat file to start_connName.bat, where connName is the connector name for your connector. Possible reasons for creating a new start_connName.bat, startup script include:

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 C++ connector running on Windows is to copy an existing C++ connector's shortcut and edit the shortcut properties to change the connector name or add any other startup parameters.

For example, for the MyCPP C++ connector, you could copy the shortcut for the IBM WebSphere Business Integration Adapter for Clarify (see Figure 77) and replace Clarify with MyCPP, as Figure 78 shows.

Figure 78. Connector shortcut for MyCPP connector

ProductDir\bin\start_connector.bat MyCPP 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 C++ connector has a connector name of MyCPP, then it is started with the connector_manager_MyCPP startup script. The connector's runtime files must reside in the ProductDir/connectors/MyCPP directory and its DLL must reside in that directory with the name MyCPP.dll. In addition, the start_MyCPP.sh script must also reside in this ProductDir/connectors/MyCPP 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 79.

Figure 79. 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 79.

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