The following sections describe the tasks necessary to distribute a connector agent:
In this instructions, InterChange Server Express host computer refers to the machine on which you are running InterChange Server Express
When you install an adapter, the Installer program automatically creates an installation of InterChange Server Express on the same machine as the adapter you are installing. If you want the adapter's connector agent to function in a distributed manner--that is, the connector agent is on one machine, and InterChange Server Express (and the collaborations that run as processes within it) is on another--you must tell the connector agent which InterChange Server Express it should use. This is done through the CWSharedEnv.bat file, or the CWSharedEnv.sh file, as follows:
On OS/400:
/QIBM/UserData/Webbiics/bin
set ORB_HOST=localhost
Replace localhost with the IP address of the InterChange Server Express host machine. For example:
set ORB_HOST=9.26.234.123
Perform the following prerequisite steps to prepare the agent host computer for the tasks that follow in subsequent sections:
Connectors depend on several files and directories to execute properly. Perform the following steps to properly migrate a connector agent:
For example, if the connector agent being distributed was that for the Adapter for JDBC, then copy the Jdbc directory into the \connectors directory.
Connector message files have the same name as the connector and have a .txt extension. For example, if the connector agent being distributed was that for the WebSphere Business Integration Adapter for JDBC, then copy the JDBCConnector.txt file into the \connectors\messages directory.
Connector agents require a number of pieces of information to run correctly, such as the name of InterChange Server Express, the name server, and the location of the supporting libraries.
Connector agents need to know the location of the product directory to reference things such as the supporting classes that are required.
Take one of the following two approaches to configure the startup mechanism of the connector agent so that it can reference the location of the WebSphere InterChange Server directory:
The advantages of this approach are that if one computer was going to host multiple distributed connector agents, then all of their startup scripts could then reference the same environment variable, and that you do not have to modify the connector startup script for this particular purpose.
The advantage of this approach is that the extra work of creating the environment variable is not required. Furthermore, if multiple instances of a single connector must be installed on multiple distributed computers then you only have to edit the file once and can use it on all of the necessary computers provided that the InterChange Server Express directory is the same on all of them.
Many of the other variables defined in the startup scripts make reference to the CROSSWORLDS variable (to ultimately reference dependency classes in the \lib directory, for instance), so the variable must be defined prior to any others that reference it. The lines below are from the start_connector.bat file in a Windows environment; the second of the lines was added to define the CROSSWORLDS variable:
setlocal set CROSSWORLDS=C:\CrossWorlds REM Define local batch PATH to insure we execute our jre set PATH="%CROSSWORLDS%"\bin;%PATH%
If the remote connector agent is on OS/400, it is recommended that you use /QIBM/UserData/WebBIICS as the ProductDir. All of the shell scripts that ship with OS/400 already have the CROSSWORLDS variable set within each shell script.
For connector agents to contact the InterChange Server, they must use the same name server as the ICS.
On the Linux platform, to specify the name server used by the connector agents, you can do one of following:
On the OS/400 platform, specify the name server for the connector agent by modifying the ORB_HOST and ORB_PORT variables in the /QIBM/UserData/bin/CWSharedEnv.sh file.
For a connector agent to communicate with InterChange Server Express, you must configure it to reference InterChange Server Express by the proper case-sensitive name. Similarly, you must configure the agent so that when it starts, it is assigned the proper case-sensitive name for the connector as defined in the InterChange Server Express repository. Take one of the following three approaches to configure the startup mechanism of the connector agent so that it can reference the location of the InterChange Server Express directory:
The advantage of this approach is that you can typically use a single connector startup script for multiple connectors, because you manually enter the variable information each time you execute the script.
The disadvantage of this approach is that the responsibility of passing the variables with the proper case and spelling is on you.
To use this approach on OS/400, you must first end the QWEBBIICS subsystem using "ENDSBS SBS(QWEBBIICS) OPTION(*IMMED)". Then you must either run the startup script for the connector manually from an interactive QShell or submit a batch job to do this using the SBMJOB command. The first parameter is the adapter name, such asJText, and the second parameter is the InterChange Server name, such as QWEBBIICS.
To use this aproach on Linux, you execute the start script and supply the names of the adapter and InterChange Server as arguments. For example, for the JDBC adapter, execute start_JDBC.sh under the directory ProductDir/connectors/JDBC, and supply names of the adapter and InterChange Server as arguments; for example, start_JDBC.sh JDBC WebSphereICS.
An alternative approach on Linux is to execute the script connector_manager under theProductDir/bin directory . When you do this, only the name of the adapter is required, because the name of the InterChange Server is hardcoded in connector_manager. For example, for the JDBC adapter, you execute this command: connector_manager -start JDBC.
This approach is less common in a Windows environment, where shortcuts make it easier to pass the variable information with less of a threat of misspelling the case-sensitive names.
In the following example, the start_JText.bat file on a Windows computer is modified to enable startup of the JTextConnector by hard-coding the variable information; note that the CONNDIR, CONNAME, and SERVER variables all required modification:
setlocal set CROSSWORLDS=C:\CrossWorlds REM Define local batch PATH to insure we execute our jre set PATH="%CROSSWORLDS%"\bin;%PATH% REM set the directory where the specific connector resides set CONNDIR="%CROSSWORLDS%"\connectors\JText REM goto the connector specific drive & directory cd /d %CONNDIR% REM set the name to be the application connector that is starting set CONNAME=JText REM set the server name to be the interchange that is being targeted set SERVER=CrossWorlds
In the following example, the start_JDBC.sh script on a Linux system is modified to enable startup of the JDBC adapter by hardcoding the variable information; note that only the CONNAME and SERVER variables require modification:
CONNAME=JDBC SERVER=WebSphereICS . /home/crossworlds/IBM/WebSphereItemSync/bin/CWConnEnv.sh CONDIR=${CROSSWORLDS}/connectors/${CONNAME}
On OS/400, this is done in a shell script, as in the following example:
#!/bin/sh export CROSSWORLDS=/QIBM/UserData/WebBIICS PARM1=$1 PARM2=$2 PARM3=$3 PARM4=$4 PARM5=$5 . ${CROSSWORLDS}/bin/CWConnEnv.sh # export the directory where the specific connector resides export CONNDIR=${CROSSWORLDS}/connectors/JText # goto the connector specific drive & directory cd ${CONNDIR} # export the name to be the application connector that is starting export CONNAME=JText # export the server name to be the interchange that is being targeted export SERVER=QWEBBIICS
The advantage of this approach is that you can ensure the case and spelling of the variables and minimize the amount of manual effort involved in starting the connector agent.
The disadvantage of this approach is that it is very customized to a particular agent; if you need to start multiple agents, then you must customize a startup script for each one.
The advantage of this approach is that you can ensure the case and spelling of the variables and minimize the amount of manual effort involved in starting the connector agent, just as when hard-coding the variables within the script, but without creating a custom script for each agent.
Connector agents require the WebSphere MQ client. The client must be installed on the agent host computer.