Starting up a new connector

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

Table 110. 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 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 110 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 70 shows the steps to start a connector on a Windows system.

Figure 70. 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:

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 Java connector name). For example, if your Java connector has a connector name of MyJava, its startup script name is start_MyJava.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 71. 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 71. 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 72, with connName being the name of the connector and ICSinstance being the name of the InterChange Server instance.

Figure 72. 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 MyJava connector to meet these assumptions, its runtime files must reside in the ProductDir\connectors\MyJava directory and its jar file must reside in that directory with the name BIA_MyJava.jar. 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 72), 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 111 specify.

Table 111. 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 111 as follows:

In addition to the environment variables in Table 111, 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 MyJava connector:

call start_adapter.bat -lcom.crossworlds.connectors.MyJava.MyJavaAgent
     -nMyJava -sICSserver -cMyJavaConnector.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 72), 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 Java 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 MyJavaconnector that uses the standard syntax for its startup script, you could create the following shortcut:

ProductDir\bin\start_MyJava.bat MyJava 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

Starting a connector on a UNIX-based system involves the following steps:

  1. Call the connector's startup script, connector_manager_connName with its -start option.

    The connector_manager_connName script (where connName is the name of your connector) is a connector-specific startup script. It identifies the name of the connector and provides the action to take on this connector with one of its options, which include -start and -stop. This script is generated with the Connector Script Generator tool. Once generated, the script resides in the bin subdirectory of the product directory. It is this connector_manager_connName.bat script that the user invokes to start the connector on a UNIX-based system.

  2. Call the generic connector manager script, connector_manager.

    The connector_manager file is generic to all connectors. It generates the call to the connector-specific invocation script, start_connName.sh. the actual invocation of the connector within the JVM. It resides in the bin subdirectory of the product directory. The connector_manager_connName script calls the connector_manager script.

  3. Call the connector-specific invocation script, start_connName.sh

    The start_connName.bat script provides connector-specific information (such as application-specific libraries and their locations). By convention, this script resides in the connector directory:

    ProductDir/connectors/connName
     
    

    The connector_manager script calls the start_connName.sh script to actually prepare the connector-specific information for connector invocation.

  4. Call the generic connector-invocation script, start_adapter.sh

    The start_adapter.sh 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.sh script must call the start_adapter.sh script to actually invoke the connector.

Figure 73 shows the steps to start a connector on a UNIX-based system.

Figure 73. Starting a connector on a UNIX-based system

When a WebSphere Business Integration Adapters Installer installs a predefined connector on a UNIX-based system (such as Solaris, HP-UX, or AIX), it takes the following steps:

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

In this sequence of steps, there are two scripts that are not generic; that is, no single script exists that can work with any connector:

Connector-specific connector-manager startup stcript

To create a connector-specific connector-manager startup 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.

Connector-specific invocation script

To create a connector-specific invocation script, you create a new connector-specific script called start_connName.sh (where connName is your Java connector name). For example, if your Java connector has a connector name of MyJava, its startup script name is start_MyJava.sh. As a starting point, you can copy the startup-script template, which is located in the following file:

ProductDir/templates/start_connName.sh
 

Figure 74. shows a sample of the contents of the invocation-script template for UNIX. Please consult the version of this file released with your product for the most current contents.

Figure 74. Sample contents of the startup-script template for UNIX-based systems

#!/bin/sh
 
# set environment 
 \
 #.${ADAPTER_RUNTIME}/bin/wbia_connEnv.sh
 
# If required, go to directory where connector class files reside
 cd /
 cd "${CONNDIR}"
 
# Please define the following variables that need to pass to callee
 export JCLASSES=
 export LibPath=
 export ExtDirs=
 export JVMArgs=
 
# Call base script start_adapter.sh to start a C++ connector 
 exec ${ADAPTER_RUNTIME}/bin/start_adapter.sh -nconnName -sserverName 
 -dconnSpecificDLLfile -f... -p... -c... ...
 
# Call base script start_adapter.sh to start a Java connector
 exec ${ADAPTER_RUNTIME}/bin/start_adapter.sh -nconnName -sserverName 
 -lconnSpecificClasses -f... -p... -c... ...
 

On UNIX-based systems, the start_connName.sh script has the syntax shown in Figure 72. However, unlike the start_connName script on Windows systems, this syntax for start_connName on UNIX-based systems must follow that shown in Figure 72. The connector_manager script calls start_connName with this syntax. As the connector developer, you control the content of start_connName.sh but you should not change the syntax of this script.

If you follow the suggested naming conventions (see Table 109), your connector-specific invocation script can make the following assumptions about your connector's runtime files based on the connector name (connName):

For example, for the MyJava connector to meet these assumptions, its runtime files must reside in the ProductDir/connectors/MyJava directory and its jar file must reside in that directory with the name BIA_MyJava.jar. 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.sh.

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

  1. Call the CWConnEnv.sh 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.sh script to invoke the connector.

The following sections describe each of these steps.

Calling the environment file

The CWConnEnv.sh 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:

. ${ADAPTER_RUNTIME}/bin/CWConnEnv.sh
 
Moving into the connector directory

The start_connName.sh script must change to the connector directory before it calls the start_adapter.sh 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.

The start_connName.sh script expects the connector name to be passed in as the first argument ($1). Therefore, the following lines move into the connector directory:

# set the directory where the specific connector resides
 CONNDIR=${CROSSWORLDS}/connectors/$1
 export CONNDIR
 
# If required, go to directory where connector class files reside
 cd /
 cd "${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.sh script. The lines to set the environment variables for the connector name and connector directory could be as follows:

# set the name of the connector
 CONNAME=$1
 export CONNNAME
 
REM set the directory where the specific connector resides
 CONNDIR=${CROSSWORLDS}/connectors/${CONNAME}
 export CONNDIR
 
# If required, go to directory where connector class files reside
 cd /
 cd "${CONNDIR}"
 
Setting the environment variables

In the start_connName.sh script, you must specify any of the connector-specific information that the environment variables listed in Table 111. The start_adapter.sh script uses these environment variables in the same way as the start_adapter.bat script does on Windows systems. You can also define your own connector-specific environment variables for information that can change from release to release. For more information, see Setting the environment variables.

Invoking the connector

To actually invoke the connector within the JVM, the start_connName.sh script must call the start_adapter.sh script. The start_adapter.sh 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.sh, 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.sh should have the following format:

exec ${ADAPTER_RUNTIME}/bin/start_adapter.sh -nconnDefName -sICSinstance
  languageSpecificParams -cCN_connNameConnector.cfg 
  -...
 

For example, the following line invokes the MyJava connector:

exec ${ADAPTER_RUNTIME}/bin/start_adapter.sh -nMyJavaConnector -sICSserver
  -lcom.crossworlds.connectors.MyJava.MyJavaAgent 
  -cMyJavaConnector.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 a WebSphere MQ Integrator Broker instance, 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:

exec ${ADAPTER_RUNTIME}/bin/start_adapter.sh -n${CONNAME}Connector -s${2} 
  languageSpecificParams -cCN_${CONNAME}Connector.cfg 
  -...
 

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

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