With the System z® Jazz™ Gateway, you can programmatically
retrieve work item numbers and status from the Rational Team Concert™ for System z repository.
The System z Jazz Gateway runs as a server daemon
on z/OS®, Windows®, Linux®,
and other platforms, to perform SSL authentication to a Jazz repository. It passes a work item number
in a REST URI to the Jazz repository
to get the work item XML, and then returns either the work item status
or the complete work item XML to the client.
How the System
z Jazz Gateway communicates
with the Jazz repository
The System z Jazz Gateway server daemon communicates with
a particular port to retrieve client requests. On z/OS, you make these requests by submitting
a System z Jazz Gateway server job. You can modify your REXX™ client to specify a particular
port so that the client and the System
z Jazz Gateway server daemon
can communicate with each other through a socket connection.
- To call the REXX client,
use a REXX EXEC like a stand-alone
EXEC or an SCLM user exit to set up required parameters like these:
- userid
- password
- Jazz repository URL
- port number
- work item number
- The REXX client passes this
information to the System z Jazz Gateway server daemon and waits
for a response.
- The System z Jazz Gateway server daemon authenticates
with the Jazz repository and
passes the work item request through a REST URI.
- The Jazz Gateway server
returns the work item information in XML, and the server daemon does
one of the following:
- It extracts the work item status from the XML.
- It passes the complete XML back to the REXX client, which returns it to the calling
EXEC.
Installing the Jazz Gateway
The Jazz Gateway is installed on z/OS using SMP/E as part of the Build System
Toolkit for System z component.
If you want to install the gateway on the supported distributed platforms,
you must download the Jazz Gateway
.zip file from the Rational
Team Concert for System
z All Downloads section on Jazz.net.
Installing the Jazz Gateway
on UNIX
Complete the following steps to install the Jazz Gateway on UNIX:
- Download the RTCz-JazzRestGateway-2.0.0.2.zip from
the Rational Team
Concert for System z All
Downloads section on Jazz.net: https://jazz.net/downloads/rational-team-concert-z/releases/2.0.0.2
- Unzip the following .jar files to your Jazz Gateway install directory:
- RTCz-JazzGateway-<buildID>.jar
- log4j-1.2.12.jar
- com.ibm.team.repository.common_1.0.1.I200909060153.jar
- org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar
- commons-httpclient-3.0.jar
Invoking the Jazz Gateway
on UNIX using Java
Complete the following steps to invoke
the Jazz Gateway on UNIX:
- Open a shell terminal
- Change to the directory where the gateway files are installed
- Enter the following command:
java -cp .\RTCz-JazzGateway-<buildID>.jar;.\log4j-1.2.12.jar;
.\com.ibm.team.repository.common_0.6.1.I200810072228.jar;.\org.eclipse.osgi_3.3.2.R33x_v20080105.jar;.\commons-httpclient-3.0.jar com.ibm.teamz.jazz.gateway.JazzGateway 6666
Note: For
this example 6666 is the port number used by the gateway.
- Enter CTRL+C to stop the gateway.
Example UNIX shell script
The following example
is a shell script for stopping and starting Jazz Gateway. You can customize the example
according to your environment by changing the value of
JAVA_HOME and
GTW_DIR.
#! /bin/sh
#
# RTCzGateway-daemon: Starts/stops the Jazz Gateway
#
#
name="IBM Jazz Gateway"
export JAVA_HOME=<Java_sdk_directory>
export GTW_DIR=<Jazz_gateway_directory>
port=${2:-3456}
PID=GtwPid.$port
cmd="$JAVA_HOME/bin/java -classpath $GTW_DIR/RTCz-JazzGateway-I20090929-1150.jar:$GTW_DIR/log4j-1.2.12.jar:$GTW_DIR/com.ibm.team.repository.common_1.0.1.I200909060153.jar:$GTW_DIR/org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar:$GTW_DIR/commons-httpclient-3.0.jar com.ibm.teamz.jazz.gateway.JazzGateway $port"
Start() {
if [ -f $PID ]
then
echo "$name $port already started"
else
echo "Starting $name $port daemon... "
$cmd >$PID.log 2>&1&
echo $! >$PID
fi
}
Stop() {
if [ -f $PID ]
then
echo "Shutting down $name $port daemon: "
kill -9 `cat $PID`
rm $PID
else
echo "$name $port daemon not started "
fi
}
Restart() {
Stop
Start
}
# See how we were called.
case "$1" in
start)
Start
;;
stop)
Stop
;;
restart)
Restart
;;
*)
echo $"Usage: $0 {start|stop|restart} <port_number>"
exit 1
esac
exit $?
You can use this script as a system initialization
script. The administration of this type of shell scripts differs for
each UNIX or Linux platform on which the Jazz Gateway
is supported. The following table lists the location of system initialization
scripts for each system:
| System |
Location |
| AIX |
/etc/rc.d |
| Red Hat |
/etc/rc.d/init.d |
| SUSE |
/etc/init.d |
| Solaris |
/etc/init.d |
Installing the Jazz Gateway
on Windows
Complete the following steps to install the Jazz Gateway on Windows:
- Download the RTCz-JazzRestGateway-2.0.0.2.zip from
the Rational Team
Concert for System z All
Downloads section on Jazz.net: https://jazz.net/downloads/rational-team-concert-z/releases/2.0.0.2
- Unzip the following .jar files to your Jazz Gateway install directory:
- RTCz-JazzGateway-<buildID>.jar
- log4j-1.2.12.jar
- com.ibm.team.repository.common_1.0.1.I200909060153.jar
- org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar
- commons-httpclient-3.0.jar
Invoking the Jazz Gateway on Windows using Java
Complete
the following steps to invoke the Jazz Gateway
on Windows:
- Open a command prompt window
- Change to the directory where the gateway files are installed
- Enter the following command:
java -cp .\RTCz-JazzGateway-<buildID>.jar;.\log4j-1.2.12.jar;.\com.ibm.team.repository.common_0.6.1.I200810072228.jar;.\org.eclipse.osgi_3.3.2.R33x_v20080105.jar;.\commons-httpclient-3.0.jar com.ibm.teamz.jazz.gateway.JazzGateway 6666
Note: For
this example 6666 is the port number used by the gateway.
You can use the command file
startgw.cmd to
start the gateway. Before starting the gateway, update the
JAVA_HOME variable
in the script.
Example for setting up a Windows service
The
Jazz Gateway is a Java application; therefore, it does not include
direct support for running as a Windows service. However, there are
several service wrappers available. This example uses Java Service
Launcher. You can modify this example for the service wrapper that
you use.
Configuring the Java Service Launcher
Complete
the following steps to configure the Java Service Launcher (JSL) for
the Jazz Gateway:
- Open a command prompt and change directories to the bin directory
that contains the jsl.ini file.
- Edit the jsl.ini file in the bin directory:
- From the command prompt, run jsl -debug to test
your configuration. This will run Jazz Gateway. You should see a message
similar to:
Debugging IBM Jazz Gateway (gateway_port_number)
Now starting JVM
ControlHandler registered after JVM start
- Resolve any additional errors before continuing.
- Check the log file you set in systemout setting
to determine whether the gateway is listening to the port number specified
by the PORT variable.
- Enter CTRL+C to end the debug test.
Installing the Windows service and starting the Jazz
Gateway
Complete the following steps to install the JSL
Windows service and start the Jazz Gateway:
- From the command prompt, change directories to the jsl bin directory.
- Run jsl -install.
- Open the Windows services control panel (Start > Run
> services.msc).
- Find the IBM Jazz Gateway service (or whatever
you named it in the .ini file).
- Right-click and select Start.
- Request builds to ensure your build engine is successfully processing
build requests.
- After the initial setup, the service will start automatically
when the system boots, because of the the starttype=auto setting
in the ini file.
Note: If you need to change the settings in the .ini file, you
must first stop and uninstall the service (see instructions below).
Then make your changes to the .ini file and reinstall the service.
Stopping
the Jazz Gateway service
Complete the following steps to
stop the Jazz Gateway service:
- Open the Windows services control panel (Start > Run
> services.msc).
- Find the IBM Jazz Gateway service (or whatever
you named it in the .ini file).
- Right-click and select Stop.
Uninstalling the Windows service
Complete
the following steps to uninstall the JSL Windows service:
- Open the Windows services control panel (Start > Run
> services.msc).
- Find the IBM Jazz Gateway service (or whatever
you named it in the .ini file).
- Right-click and select Stop.
- From the command prompt, change directories to the jsl bin directory.
- Run jsl -remove.