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.

    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 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 @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 72, 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 112.

Figure 72. 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 72, 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 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. 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 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. Table 112 shows the startup parameters that the start_adapter.bat script recognizes.

Table 112. 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 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.sh 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 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 script

To start a connector, the connector_manager_connName.sh script has the syntax shown in Figure 74, with connName being the name of the connector and additionalOptions is an optional argument that specifies additional startup parameters to pass to the connector invocation. These options include -f and -x. For more information, see Table 113.

Figure 74. Syntax for starting a UNIX connector

connector_manager_connName -start additionalOptions
 

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 75. 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 75. Sample contents of the startup-script template for UNIX-based systems

#!/bin/sh
# set environment 
\
#.${WBIA_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 ${WBIA_RUNTIME}/bin/start_adapter.sh -nconnName -sserverName 
-dconnSpecificDLLfile -f... -p... -c... ...
# Call base script start_adapter.sh to start a Java connector
exec ${WBIA_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:

. ${WBIA_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. Table 113. Table 113 shows the startup parameters that the start_adapter.sh script recognizes.

Table 113. Startup parameters for start_adapter.sh script

Startup parameter Description Required? Valid as additonal
command-line option for connector_manager_connName?
-b

Runs the connector as a background thread; that is, the connector does not receive any input from standard input (STDIN). The generic connector_manager script (called by each connector_manager_connName script) automatically specifies this option when it invokes the start_connName.sh script. Therefore, to prevent a connector from being run in the background, you can remove the -b parameter from the start_connName.sh invocation.

See the description No
-cconfigFile The full path name of the connector's configuration file Required if integration broker is other than ICS Yes
-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.

The value that the -f parameter specifies overrides the polling frequency in the connector's configuration file.

No

Default is 1000 milliseconds

Yes
-lclassname

The name of the Java connector's connector class (className)

Note:
The -b parameter is not a valid command-line option for the connector_manager_connName script.
Yes 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
-tthreadingType

Specifies the threading model to use for the connector. Possible values for threadingType are:

  • SINGLE_THREADED: only a single thread accesses the application.
  • MAIN_SINGLE_THREADED: only the main thread accesses the application.
  • MULTI_THREADED: multiple threads can access the application

No No
-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.sh includes the following startup parameters:

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 ${WBIA_RUNTIME}/bin/start_adapter.sh -nconnDefName -sICSinstance
 -lclassName -cCN_connNameConnector.cfg 
 -...

For example, the following line invokes the MyJava connector:

exec ${WBIA_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 ${WBIA_RUNTIME}/bin/start_adapter.sh -n${CONNAME}Connector -s${2} 
-lclassName -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 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