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:
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. |
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:
The following sections describe each of these steps.
The connector directory contains the runtime files for your connector. To prepare the connector directory, take the following steps:
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.
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".
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.
Starting a connector on a Windows system involves the following steps:
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.
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:
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, 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.
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:
The following sections describe each of these steps.
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
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%
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.
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:
|
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:
If the name of the connector is passed in as the first argument (%1) to the start_connName.bat script (see Figure 72), the -n startup parameter can be specified as follows:
-n%1Connector
If you define an environment variable for the connector name (such as CONNAME), this -n parameter could appear as follows:
-n%CONNAME%Connector
If the name of the ICS instance is passed in as the second argument (%2) to the start_connName.bat script (see Figure 72), the -s startup parameter can be specified as follows:
-s%2
Other integration brokers |
---|
When your integration broker is a WebSphere message broker (WebSphere MQ Integrator, WebSphere MQ Integrator Broker, WebSphere Integration Message Broker), or WebSphere Application Server, the -c option is also a required startup parameter. |
To specify connector-specific classes (or package): -l
For example, if you follow the recommended naming conventions, the language-specific parameter for the Java connector name is MyJava would be:
-lcom.crossworlds.connectors.MyJava.MyJavaAgent
If you define an environment variable for the connector name (such as CONNAME), this -l parameter could appear as follows:
-lcom.crossworlds.connectors.%CONNAME%.%CONNAME%Agent
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 -...
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:
call start_adapter.bat -n%CONNAME% -s%2 languageSpecificParams -cCN_%CONNAME%Connector.cfg %3 %4 %5
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
Starting a connector on a UNIX-based system involves the following steps:
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.
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.
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.
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:
The connector_manager_connName script calls the connector_manager script, providing the appropriate command-line arguments, such as a local configuration file or a threading type.
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:
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.
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 \ #.${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:
The following sections describe each of these steps.
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
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}"
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.
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 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)
|
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:
|
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:
Because the name of the connector is passed in as the first argument ($1) to the start_connName.sh script (see Figure 72), the -n startup parameter can be specified as follows:
-n${1}Connector
If you define an environment variable for the connector name (such as CONNAME), this -n parameter could appear as follows:
-n${CONNAME}Connector
If the name of the ICS instance is passed in as the second argument ($2) to the start_connName.sh script (see Figure 72), the -s startup parameter can be specified as follows:
-s${2}
Other integration brokers |
---|
When your integration broker is WebSphere MQ Integrator Broker, WebSphere Integration Message Broker, or WebSphere Application Server, the -c option is also a required startup parameter. |
To specify connector-specific classes (or package): -l
For example, if you follow the recommended naming conventions, the language-specific parameter for the Java connector name is MyJava would be:
-lcom.crossworlds.connectors.MyJava.MyJavaAgent
If you define an environment variable for the connector name (such as CONNAME), this -l parameter could appear as follows:
-lcom.crossworlds.connectors.${CONNAME}.${CONNAME}Agent
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 -lclassName -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 -...
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} -lclassName -cCN_${CONNAME}Connector.cfg -...
For the call to start_adapter.sh, keep the following points in mind:
exec ${ADAPTER_RUNTIME}/bin/start_adapter.sh -n${CONNAME}Connector -s${2} -lclassName -cCN_${CONNAME}Connector.cfg ${3} ${4} ${5}
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.