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-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. |
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. |
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 C++ connector's library file is a DLL. You created this DLL when you compiled the connector. For more information, see "Compiling and linking a C++ connector".
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 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 77 shows the steps to start a connector on a Windows system.
Figure
77. 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 C++ connector name). For example, if your C++ connector has a connector name of MyCPP, its startup script name is start_MyCPP.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 78. 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 78. 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 79, with connName being the name of the connector and ICSinstance being the name of the InterChange Server instance.
Figure 79. 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 MyCPP connector to meet these assumptions, its runtime files must reside in the ProductDir\connectors\MyCPP directory and its DLL must reside in that directory with the name MyCPP.dll. 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 79), 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 91 specify.
Table 91. 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 91 as follows:
In addition to the environment variables in Table 91, 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, including:
If the name of the connector is passed in as the first argument (%1) to the start_connName.bat script (see Figure 79), 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 79), 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 the name of the connector DLL: -d
For example, if you follow the recommended naming conventions, the language-specific parameter for the C++ connector name is MyCPP would be:
-dMyCPP
If you define an environment variable for the connector name (such as CONNAME), this -d parameter could appear as follows:
-d%CONNAME%
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 MyCPP connector:
call start_adapter.bat -dMyCPP -nMyCPP -sICSserver -cMyCPPConnector.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:
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 79), 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 C++ 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 MyCPPconnector that uses the standard syntax for its startup script, you could create the following shortcut:
ProductDir\bin\start_MyCPP.bat MyCPP ICSinstance
The Connector Development Kit (CDK) is supported only on Windows systems. It is not supported on UNIX-based systems. Because creation of a C++ connector is not supported on a UNIX-based system, you do not need to create startup scripts for such a connector.
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.