Rational Team Concert for System z Beta Program

Rational Team Concert for System z Beta Program
Rational Team Concert for System z
Beta Program
Installation and User’s Guide
Version 2.0 Beta 3
Rational Team Concert for System z
Beta Program
Installation and User’s Guide
Version 2.0 Beta 3
Note
Before using this information and the product it supports, read the information in “Notices” on page 107.
This edition applies to the beta 3 version of IBM Rational Team Concert for System z V2.0 (product number
5724-V82).
© Copyright International Business Machines Corporation 2009.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Introduction to Rational Team Concert
for System z beta . . . . . . . . . . v
About this beta guide .
.
.
.
.
.
.
.
.
.
. v
Chapter 1. Rational Team Concert for
System z prerequisites . . . . . . . . 1
Chapter 2. Setting up the Rational Team
Concert for System z client . . . . . . 3
Chapter 3. Installing and configuring
Rational Team Concert for System z . . 5
Chapter 4. Setting up the Jazz Team
Server for System z on Windows and
Linux . . . . . . . . . . . . . . . . 7
Installing and Configuring the Jazz Team Server for
System z. . . . . . . . . . . . . . .
Starting and stopping the Apache Tomcat server .
Running the setup wizard . . . . . . . . .
Adding your server ports to the Jazz Team Server
configuration . . . . . . . . . . . . .
. 7
. 7
. 8
. 9
Chapter 5. Installing and configuring
the Jazz Team Server for System z on
z/OS . . . . . . . . . . . . . . . . 11
Software prerequisites . . . . . . . . . . .
SMP/E installation . . . . . . . . . . . .
Configuring your installation . . . . . . . .
Creating additional Jazz Team Server directories
(required) . . . . . . . . . . . . . .
Customizing the configuration files (required) . .
Review Tomcat port configuration
(recommended) . . . . . . . . . . . .
Running the Jazz Team Server for System z with
Tomcat and Derby . . . . . . . . . . .
Running the Jazz Team Server for System z with
Tomcat and DB2 for z/OS . . . . . . . .
11
12
12
12
13
15
15
17
Chapter 6. Installing Jazz Team Server
for System z on Linux for System z . . 23
Installation prerequisites . . . . . . . . .
Overview of installing Jazz Team Server for System
z . . . . . . . . . . . . . . . . .
Preparing to install the Jazz Team Server for
System z . . . . . . . . . . . . .
Installing Jazz Team Server for System z. . .
Setting up the database . . . . . . . .
Setting up a DB2 database . . . . . . .
DB2 prerequisites . . . . . . . . . .
Setting up DB2 for z/OS to use with the Jazz
Team Server for System z. . . . . . . .
© Copyright IBM Corp. 2009
. 23
. 24
.
.
.
.
.
25
25
26
26
27
. 27
Customizing Jazz Team Server for System z
properties files for DB2 for z/OS . . . . .
Creating the Jazz Team Server database tables .
Starting the server . . . . . . . . . .
Configuring Security-Enhanced Linux . . . .
.
.
.
.
28
30
31
33
Chapter 7. Setting up the Rational
Build Agent. . . . . . . . . . . . . 35
Installing and running the agent
Running an agent . . . . .
Configuring the agent . . . .
Changing the agent port . .
Configuring a different shell .
Build Agent Lookup Service . .
Lookup Service Setup . . .
on
.
.
.
.
.
.
z/OS
. .
. .
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
35
36
36
36
36
37
37
Chapter 8. User scenarios for Rational
Team Concert for System z . . . . . . 39
Scenario 1: Getting started with Rational Team
Concert for System z . . . . . . . . . . .
Scenario 2: Using the System z Jazz Gateway to
integrate with existing SCMs . . . . . . . .
Starting the System z Jazz Gateway server . . .
Creating an encrypted password file for the
System z Jazz Gateway . . . . . . . . .
Setting the REXX Gateway client to communicate
with the server . . . . . . . . . . . .
Setting up the System z Jazz Gateway to control
SCLM workflow . . . . . . . . . . . .
Using SCLM with Rational Team Concert for
System z work items . . . . . . . . . .
Scenario 3: Preview of the mass import tool . . .
Overview of the Rational Team Concert for
System z mass import tool . . . . . . . .
Importing z/OS partitioned data set members to
a zComponent project . . . . . . . . . .
Options supported by the Rational Team Concert
for System z mass import tool . . . . . . .
An overview of creating a mapping file to use
with the Rational Team Concert for System z
mass import tool . . . . . . . . . . .
Rational Team Concert for System z mass import
tool: mapping file rule restrictions . . . . . .
Scenario 4: Using the Rational Build Agent to
execute command-driven builds . . . . . . .
Defining and running a build using the Rational
Build Agent . . . . . . . . . . . . .
Scenario 5: Using the Rational Build Agent and Job
Monitor to execute builds using JCL . . . . . .
Job Monitor customization . . . . . . . .
Submitting JCL inside the build command . . .
Scenario 6: Using the Rational Build Agent and Antz
build extensions to compile a COBOL application .
Preparing your environment. . . . . . . .
Configuring the Rational Build Agent shell script
39
41
42
42
42
43
44
46
46
46
48
50
50
51
52
56
56
60
65
65
66
iii
Configuring the Rational Build Agent Service .
Creating data set definitions . . . . . . .
Creating translators. . . . . . . . . .
Creating language definitions . . . . . .
Creating a shared zComponent project . . .
Adding System z build containers and
associating them with data set definitions . .
Adding System z build artifacts and associating
them with language definitions . . . . . .
Creating a new build definition. . . . . .
Requesting a build . . . . . . . . . .
.
.
.
.
.
66
67
69
72
72
. 73
. 73
. 74
. 75
Appendix A. Running the Jazz Build
Engine on z/OS . . . . . . . . . . . 77
Appendix B. Troubleshooting the Jazz
Team Server . . . . . . . . . . . . 79
Troubleshooting the Jazz Team Server setup wizard 81
Troubleshooting Antz builds . . . . . . . . . 81
Appendix C. Troubleshooting Rational
Build Agent issues . . . . . . . . . 83
Troubleshooting the Rational Build Agent
Testing host name resolution . . .
Testing the connection . . . . . .
Additional troubleshooting procedures
bfagent reference . . . . . . . .
bfagent.conf reference . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Exporting the database using the Jazz Team Server
repository tools . . . . . . . . . . . . . 93
Running repository tools to import a Jazz Team
Server for System z database . . . . . . . . 93
Creating database tables using Jazz Team Server for
System z repository tools . . . . . . . . . . 94
.
.
.
.
.
.
83
83
83
84
85
85
Appendix E. Antz tasks and data types
.
.
.
.
.
.
.
.
.
96
96
97
97
98
98
99
99
99
Appendix F. Job Monitor security . . . 101
Security considerations . .
JES Security . . . . .
Job Monitor configuration
Security definitions . .
.
.
file
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
101
101
104
104
Notices . . . . . . . . . . . . . . 107
Trademarks .
Appendix D. Additional Jazz Team
Server for System z repository tools
tasks on z/OS . . . . . . . . . . . . 93
iv
95
Antz custom data types . . . . . . . . .
BuildableResourceCollection custom data type.
BuildableResourceList Custom Datatype . . .
BuildableResource Custom Datatype . . . .
ComponentSelector Custom Datatype . . .
ProjectSelector Custom Datatype . . . . .
LanguageDefinitionSelector Custom Datatype .
Antz Compile Custom Data Task . . . . . .
Compile Custom Data Task . . . . . . .
Rational Team Concert for System z Beta Program: Installation and User’s Guide
.
.
.
.
.
.
.
.
.
.
.
.
. 109
Introduction to Rational Team Concert for System z beta
IBM Rational Team Concert for System z is a collaborative software delivery
environment that teams can use to simplify, automate, and govern application
development on System z. This beta program is intended to provide early access to
the product while it is being developed.
Rational Team Concert for System z includes the following features:
v Specialized support for traditional language artifacts such as COBOL
v Integrated collaborative software delivery lifecycle tools for System z
development, including source control, change management, build and process
management
v Support for multitier software development and application modernization
efforts
v Native z file system support
v System z artifact build script generation and management
Rational Team Concert for System z extends the base Rational Team Concert
functions in the following ways:
v Supports running the Jazz Team Server in a System z environment.
v Supports using DB2 for System z as the Jazz Team Server back-end repository.
v Extends the core Build System Toolkit to include a System z Jazz Gateway that
allows external software configuration management systems (SCMs) to query
Jazz-based work items.
v Provides support for a System z project structure and System z build support
through the use of Ant scripting and the Rational Build Agent.
Based on the open and extensible Jazz platform, Rational Team Concert for System
z empowers software teams to collaborate in real time in the context of specific
roles and processes. The product integrates source control, work items, build
management, dashboards, and process support into a single solution for System z.
About this beta guide
This guide provides information about installing, configuring, and using the beta
version of Rational Team Concert for System z.
The information in this guide supplements the Rational Team Concert online help
available from the help menu of the installed client and at http://
publib.boulder.ibm.com/infocenter/rtc/v2r0m0/index.jsp.
Note: You can find additional information about Rational Team Concert when you
register at Jazz.net.
This guide provides instructions for installing the following Rational Team Concert
for System z beta components:
v Jazz Team Server for System z
v Rational Team Concert for System z client
v Build System Toolkit for System z
© Copyright IBM Corp. 2009
v
v Rational Build Agent
After you complete the installation, you can work with Rational Team Concert
basic tutorials or explore the Rational Team Concert for System z beta user
scenarios, which are included in this guide.
vi
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Chapter 1. Rational Team Concert for System z prerequisites
The Rational Team Concert for System z client and Jazz Team Server for System z
include the software required for basic operation. The Rational Build Agent and
the Jazz Build Engine have additional prerequisites.
Supported environments
v
v
v
v
Microsoft Windows 2003 Server with Service Pack 2 (32-bit and 64-bit)
Microsoft Windows 2008 Server (32-bit and 64-bit)
Microsoft Windows XP (32 and 64-bit)
Red Hat Enterprise Linux 5.0 Update 1
– x86, 32-bit
– System z, 64-bit
v SUSE Linux Enterprise Server 10 with Service Pack 1
– x86, 32-bit
– System z, 64-bit
v z/OS 1.9, or 1.10 (recommended)
Note: The Rational Team Concert for System z client is not supported on any
64-bit platform.
Additional Required Software
v Apache Derby 10.3.2.2 (included)
v Apache Tomcat 5.5 (included)
v Windows and Linux x86: IBM JRE 1.5 SR9-0 +IZ45776+IZ49644+IZ49635
(included)
v Linux on System z: IBM JRE 1.5 SR9 IBM JRE 1.5 SR9-SSU (included)
v z/OS : IBM 31-bit SDK for z/OS Java 2 Technology Edition V5 at PTF UK42388
(SR9) or later (not included)
Optional Software
v IBM DB2 z/OS 9.1 (not included)
Supported Build Toolkit Environments
v z/OS V1.9, or z/OS V1.10 (recommended)
v DASD requirements: 30000 tracks in 3390 tracks (maximum - this could be
significantly reduced depending on which functions on z/OS are installed/used)
v IBM 31-bit SDK for z/OS Java 2 Technology Edition V5
Supported Client environments
The minimum client hardware is:
v Processor: Intel® Pentium® 3 or 4 (minimum); intel Core 2 Duo (recommended)
v Memory: 1 GB minimum
v Display: 1024 x 768 minimum resolution
v Other hardware: 10/100 mbps wired connectivity or 802.11b
© Copyright IBM Corp. 2009
1
The client is supported on the following 32-bit operating systems:
v Windows® Vista with Service Pack 1
v Windows XP with Service Pack 2
v Red Hat Enterprise Linux 5.0 Update 1
v SUSE Linux Enterprise Desktop 10 with Service Pack 1
Additional Required Software (included)
v IBM® JRE 1.5 Service Release SR9-0 +IZ45776+IZ49644+IZ49635
Additional prerequisites for the Rational Build Agent and the
Build System Toolkit
The Rational Build Agent has the following additional prerequisites:
z/OS UNIX shell interface
During installation, run all commands on z/OS in the z/OS UNIX shell.
The Build System Toolkit has the following additional prerequisites:
Additional permissions
The user IDs associated with the Jazz Build Engine and Rational Build
Agent requires read and execute permissions to the installation directory
and its subdirectories. These user IDs also require read, write, and execute
permissions to the work directory and configuration directory. See the user
scenario section for additional directory and data set usage information.
Software requirements
IBM 31-bit SDK for z/OS Java 2 Technology Edition V5 (which includes
the required IBM JZOS Batch Launcher) is required and must be installed
and configured separately. For more information, see http://
www.ibm.com/servers/eserver/zseries/software/java/j5pcont31.html. The
JZOS Java Launcher is required to run the Jazz Build Engine. For more
information about the JZOS Batch Launcher, see the Installation and User’s
Guide at http://www.ibm.com/servers/eserver/zseries/software/java/
pdf/jzosinstal.pdf.
2
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Chapter 2. Setting up the Rational Team Concert for System z
client
About this task
To install the Rational Team Concert for System z Beta 3, use the launchpad.
Although the launchpad has an option for updating a previous installation, this is
not supported for Beta 3.
Notes:
v The Rational Team Concert for System z client is not supported on Linux for
System z.
v If you participated in a previous beta program, you cannot update this
installation or migrate any code created during use of the previous beta.
1. Start the launchpad application. The launchpad application is in the ″rtcz″
directory created when you unzipped the installation package.
a. To run the file on Windows, run the command: launchpad.exe.
Note: You must have administrator privileges to run the launchpad.
b. To run the file on Linux, run the command: sh launchpad.sh.
Note: The Linux commands to start the launchpad program are only for the
Rational Team Concert for System z for Eclipse IDE.
2. Select Rational Team Concert for System z Client. The Installation Manager
wizard starts to guide you through the installation of the client.
What to do next
The user scenario section includes instructions on how and when to connect the
Rational Team Concert for System z client to the Jazz Team Server.
© Copyright IBM Corp. 2009
3
4
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Chapter 3. Installing and configuring Rational Team Concert
for System z
The installation method for the beta is the IBM Installation Manager for Windows,
Linux, and Linux on System z and SMP/E for z/OS. Download the appropriate
package for the target platform from the Rational Team Concert for System z beta
Jazz.net download site and unzip it onto the target machine.
Important: Some of the unzip packages are greater than 2GB in size. On a Unix
platform, an unzip program that supports file sizes larger than 2GB is required.
The Rational Team Concert for System z beta package includes several components
specifically designed for application development on System z. You can download
all Rational Team Concert for System z beta files from the beta Web site. The
Rational Team Concert for System z beta package includes the following
components:
v Jazz Team Server for System z
v Rational Team Concert for System z client
v Build System Toolkit for System z (includes the System z Jazz Gateway and the
Jazz Build Engine)
v Rational Build Agent
To install and run the beta program, go to the beta Web site at
http://jazz.net/downloads/rational-team-concert/betas/z2.0Beta3 and follow the
instructions provided on the Getting started tab.
Note: If you participated in a previous beta program, you cannot migrate any code
created during use of the previous beta.
All Rational Team Concert for System z components that can be installed on the
System z machine are contained within an SMP/E package. This package is
contained within the download file RTCz-SMPE-2.0Beta3.zip. This file also contains
the Program Directory for the SMP/E package. The SMP/E package contains four
FMIDs that can be selectively installed based on which parts are needed.
Continue with the installation of the Jazz Team Server for System z by following
the instructions in one of the following chapters appropriate for your server
environment platform.
© Copyright IBM Corp. 2009
5
6
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Chapter 4. Setting up the Jazz Team Server for System z on
Windows and Linux
This section describes the tasks required for configuring and running the Jazz
Team Server.
Note: If you participated in a previous beta program, you cannot migrate any code
created during use of the previous beta.
Installing and Configuring the Jazz Team Server for System z
About this task
Complete the following steps to install the Rational Team Concert for System z
Jazz Team Server:
1. Start the launchpad application. The launchpad application is in the ″rtcz″
directory created when you unzipped the installation package.
a. To run the file on Windows, run the command: launchpad.exe.
Note: You must have administrator privileges to run the launchpad.
b. To run the file on Linux, run the command: sh launchpad.sh.
Note: The Linux commands to start the launchpad program are only for the
Rational Team Concert for System z for Eclipse IDE.
2. Select Jazz Team Server for System z. The Installation Manager wizard starts
to guide you through the installation of the server. The Jazz Team Server for
System z is installed by default to \Program Files\IBM\JazzTeamServer on
Windows and /opt/IBM/JazzTeamServer on Linux. The installation directory is
referred to later in this guide as JazzInstallDir. If you chose a different path,
please use that path for JazzInstallDir.
What to do next
You are now ready to start the Apache Tomcat server.
Starting and stopping the Apache Tomcat server
Apache Tomcat is installed in the directory JazzInstallDir/server/tomcat. The
Web application (jazz.war) has been installed in the Apache Tomcat directory
webapps. In a command window, set your current directory to
JazzInstallDir/server/. The server startup and shutdown scripts are located in
this directory.
About this task
As part of this beta package, the open source application server Tomcat and the
Derby database are also installed. Derby has a 10 user maximum. These supporting
applications are installed pre-configured. Accepting the defaults enables you to
start the server as soon as the installation is complete. If you want to configure a
Websphere Application Server instance to run the Jazz server or use a DB2
database, you can find instructions on how to do this in the online help of the
© Copyright IBM Corp. 2009
7
Rational Team Concert for System z client installation.
1. Complete these optional steps to start the Apache Tomcat server:
a. Apache Tomcat is configured to use the ports 9080 and 9443 in file
JazzInstallDir/server/tomcat/conf/server.xml. If necessary, change the
ports according to your system setup. If you change the ports, you also
need to update the configuration settings of the Jazz server repository HTTP
ports in the Advanced Properties configuration panel of the Jazz
Administrative Web user interface later during setup.
2. To start the server, from the JazzInstallDir/server directory, run this
command: server.startup.bat
3. A separate Apache Tomcat console window opens and several informational
messages launch, including a message about the Apache Tomcat Native Library.
These informational messages do not affect the Jazz Team Server functionality.
Important: Do not close the Apache Tomcat console window or the server will
stop.
4. The directory JazzInstallDir/server/tomcat/logs contains the server log files.
If you cannot start the server, check the log files.
What to do next
Tip: When you are ready to stop the server, from the JazzInstallDir/server
directory, run this command: server.shutdown.bat.
Running the setup wizard
Run the setup wizard to verify that the server is operating properly. The setup
wizard also guides you through configuration of the server.
Before you begin
To verify that the Jazz Team Server is connecting to the database, look at the server
log or console output. The connection and database information is echoed on its
first access. The directory JazzInstallDir/jazz/server/tomcat/logs is used for the
server log files. This procedure assumes your server is available using the
hostname localhost and the default port 9443. If necessary, replace localhost with
your server hostname and replace the port number.
About this task
Complete the following steps to run the setup wizard:
1. Start the setup wizard to configure your server. Use the URL:
https://ipaddress:port/jazz/setup, where ipaddress is the IP address where
you started Tomcat, and port is the secure port that you specified when you
started Tomcat.
2. Enter the default user name and password:
v User name: ADMIN
v Password: ADMIN
Note: User name and password are case-sensitive.
3. Choose one of the two setup paths available on the setup wizard:
8
Rational Team Concert for System z Beta Program: Installation and User’s Guide
v The Fast Path Setup uses the default configuration. Use this option if you
want to get the server running quickly. Using the fast path, you set up the
user registry.
v The Custom Setup guides you through the detailed server configuration.
During the custom setup, you set up the following items:
– Database
– E-mail notification
– User registry
Note: For the Rational Team Concert for System z beta, the Tomcat user
registry is the supported user registry and Derby is the supported database. It
is sufficient for the purpose of this beta to run the Fast Path Setup. Create an
administrator, assign a developer license, and then use this ID to get started on
the user scenarios provided later in this document. Instructions for creating a
project and a team are included in this guide in Scenario 1: Getting started with
Rational Team Concert for System z.
What to do next
When the initial setup is complete, you can configure additional options using the
Jazz Team Server Administrative Web user interface using this URL:
https://localhost:9443/jazz/admin.
Adding your server ports to the Jazz Team Server configuration
Port numbers are used for composing URLs for things like feed links and item
links in e-mail notifications. If you use port numbers other than the default port
numbers, then you must update your Jazz Team Server configuration to use your
port numbers.
To update your configuration, use the Advanced Properties configuration page of
the administrative Web user interface to modify the following properties:
Property name:
com.ibm.team.repository.servlet.internal.ServletConfigurationService
v Repository HTTP port
v Repository HTTPS port
Property name: com.ibm.team.repository.service.internal.webuiInitializer.
ConfigPropertyInitializer
v Repository HTTP port
v Repository HTTPS port
You are now ready to connect to the server with the Rational Team Concert client
or a Web browser. See Scenario 1: Getting started with Rational Team Concert for
System z later in this guide.
Chapter 4. Setting up the Jazz Team Server for System z on Windows and Linux
9
10
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Chapter 5. Installing and configuring the Jazz Team Server for
System z on z/OS
This information provides step-by-step instructions for configuring the Jazz Team
Server for System z® on z/OS®.
These instructions are intended for system administrators responsible for installing
and maintaining the Jazz™ Team Server for System z on z/OS. Instructions for
installing the Rational® Team Concert client on your workstation are also included.
To understand the instructions, you should be familiar with the Windows® and
z/OS operating systems.
Note: If you participated in a previous beta program, you cannot migrate any code
created during use of the previous beta.
Software prerequisites
Before you can install Rational Team Concert for System z on z/OS, you must
ensure that the prerequisite applications are installed and operational. Be aware of
optional software requirements. For the Jazz Team Server for System z, you must
configure an application server and a database to use the Jazz Team Server for
System z.
For this beta program you can choose one of the following application server and
database options:
v Apache Tomcat 5.5 application server and Apache Derby database (both
included with the Jazz Team Server for System z download package)
v Apache Tomcat 5.5 application server (included) and DB2 Version 9.1 for z/OS
(not included)
Restriction: WebSphere Application Server is not supported for this beta program,
but will be an available option when Rational Team Concert for System z v2.0 is
released.
Tip: These instructions will indicate whether specific steps are required or optional
depending on which application server and database combination you choose.
These software products are required for installing Rational Team Concert for
System z 2.0 Beta 3:
v z/OS V1.9 or z/OS V1.10 (recommended)
v IBM® 31-bit SDK for z/OS Java™ 2 Technology Edition, V5, which includes the
IBM JZOS Batch Launcher. The minimum service level required is UK42388(SR
9). The Jazz Team Server for System z depends on IBM Java JRE 1.5 SR 9 or
greater.1
The following software is optional:
v DB2® Version 9.1 for z/OS, with the Universal JDBC driver configured to ensure
interoperability between the database and z/OS2
Notes:
© Copyright IBM Corp. 2009
11
1. For more information on the IBM 31-bit SDK for z/OS Java 2 Technology
Edition V5, which includes the JZOS Java Launcher and Toolkit, see IBM 31-bit
SDK for z/OS Java 2 product pages at http://www.ibm.com/servers/eserver/
zseries/software/java/j5pcont31.html. The JZOS Java Launcher is required to
run the Jazz Team Server repository tools. For more information about the JZOS
Batch Launcher, see the Installation and User’s Guide at http://www.ibm.com/
servers/eserver/zseries/software/java/pdf/jzosinstal.pdf.
2. See Using the DB2 Universal JDBC Driver to access DB2 for z/OS at
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/
com.ibm.websphere.ejbfep.multiplatform.doc/info/ae/ae/tdat_jdbcdb2cfg.html.
SMP/E installation
This topic provides information related to installing Rational Team Concert for
System z on z/OS.
The instructions assume you have already completed the Rational Team Concert
for System z System Modification Program/Extended (SMP/E) installation. The
SMP/E instructions are in the Program Directory included with the product
download package.
Notes about the Program Directory:
v The Program Directory refers to specific path names, if you extract your files to a
different location, you must update the path names to match your location.
v In some cases, the Program Directory refers to documentation for Rational Team
Concert for System z V1.0.1 for additional configuration tasks. Instead use this
beta ″Installation and User’s Guide″ for all configuration tasks.
The SMP/E installation installs two MVS™ datasets, hlq.SBLZSAMP and
hlq.SBLZAUTH, where hlq is a high-level qualifier chosen during the SMP/E
installation. As noted in the Program Directory, hlq.SBLZAUTH should be APF
authorized. Many of the additional configuration steps in this guide involve
editing and submitting JCL that is found in the hlq.SBLZSAMP data set.
The SMP/E installation also installs one z/OS UNIX® System Services file
directory/@[email protected]/usr/lpp/jazz.
Note: /@[email protected] is the path prefix specified during the SMP/E installation.
After you complete the SMP/E installation, follow the subsequent instructions for
the following tasks:
v Complete the installation and customization on z/OS
v Configure the Jazz Team Server for System z
v Install the Rational Team Concert client on your computer
Configuring your installation
Before you can configure your Jazz Team Server on z/OS, you must ensure that
the SMP/E installation has ended successfully.
Creating additional Jazz Team Server directories (required)
The Jazz Team Server on z/OS requires two directories in addition to the USS
directory created by the SMP/E installation. One is a directory used to store Jazz
Team Server for System z configuration files and the other is a working directory.
12
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Sample member BLZCPDIR in hlq.SBLZSAMP is used to create and populate these
directories with the required files from the SMP/E installed directory.
The following three symbolic references are used throughout this guide to refer to
these particular directories:
Symbolic
name
Use
Variable in
BLZCPDIR
Default directory
@[email protected]
The path prefix specified
during the SMP/E install.
HOME
@[email protected]
The Jazz Team Server for
System z configuration
files directory.
CONF
/etc/jazz
@[email protected]
The Jazz Team Server for
System z working
directory.
WORK
/u/jazz
Space recommendations:
The Jazz Team Server for System z directories in Beta 3 should have the following
allocations:
@[email protected]
700 cylinders 3390, for running the Jazz Team Server for System z on z/OS
@[email protected]
2 cylinders 3390
RACF file access requirements: The Jazz Team Server for System z directories
require the following RACF file access permissions:
1. @[email protected] must be accessible for read and write by the user ID under which
the Tomcat server executes.
2. @[email protected] must be accessible for read and write by the user ID under which
the Tomcat server executes.
3. @[email protected] must be accessible for read and write by the user ID under which
the Jazz Team Server for System z repository tools are run.
Configure member BLZCPDIR in hlq.SBLZSAMP using the instructions contained in
the sample. Use the SUBMIT command to submit the modified JCL and check the
job log. If everything is set up properly, all steps end with return code 0.
Customizing the configuration files (required)
Several Jazz Team Server for System z configuration files must be modified based
on the directories you have chosen for @[email protected], @[email protected], and @[email protected]
The topics in this section provide instructions for modifying the configuration files.
The Jazz Team Server for z/OS properties files are ASCII files. You can use one of
the following techniques to edit ASCII files under z/OS UNIX:
v Download or use FTP to transfer the files to a Windows PC, modify them, and
transfer them back to the z/OS system.
v If you use Rational Developer for System z, use Remote System Explorer to
connect and modify the files.
v If you have z/OS 1.10 or z/OS 1.9 with the PTF for APAR OA22250, use ISPF
option 3.17 to edit ASCII files under USS.
v If you have other tools for editing ASCII files under USS, use those tools.
Chapter 5. Installing and configuring the Jazz Team Server for System z on z/OS
13
Customizing the provisioning profiles (required)
This topic describes what you must change in the provisioning profiles to
customize them.
About this task
If you have used the @[email protected], you should edit the following files:
@[email protected]/provision_profiles/profile.ini
Change url=file:/usr/lpp/jazz/server/update-site to
url=file:/@[email protected]/usr/lpp/jazz/server/update-site.
For example, if @[email protected] is set to myroot, then this setting resolves to
url=file:/myroot/usr/lpp/jazz/server/update-site.
@[email protected]/provision_profiles/rtcz-license-profile.ini
Change url=file:/usr/lpp/jazz/server/license-update-site to
url=file:/@[email protected]/usr/lpp/jazz/server/license-update-site.
For example, if @[email protected] is set to myroot, then this setting resolves to
url=file:/myroot/usr/lpp/jazz/server/license-update-site.
@[email protected]/provision_profiles/nl1profile.ini
Change url=file:/usr/lpp/jazz/server/nl1-update-site to
url=file:/@[email protected]/usr/lpp/jazz/server/nl1-update-site.
For example, if @[email protected] is set to myroot, then this setting resolves to
url=file:/myroot/usr/lpp/jazz/server/nl1-update-site.
@[email protected]/provision_profiles/nl2profile.ini
Change url=file:/usr/lpp/jazz/server/nl2-update-site to
url=file:/@[email protected]/usr/lpp/jazz/server/nl2-update-site.
For example, if @[email protected] is set to myroot, then this setting resolves to
url=file:/myroot/usr/lpp/jazz/server/nl2-update-site.
@[email protected]/provision_profiles/rtcz-profile.ini
Change url=file:/usr/lpp/jazz/server/update-site to
url=file:/@[email protected]/usr/lpp/jazz/server/update-site.
For example, if @[email protected] is set to myroot, then this setting resolves to
url=file:/myroot/usr/lpp/jazz/server/update-site.
Customizing the logging utility files
The @[email protected]/catalina_base/log4j.properties file configures the logging
framework used by the Jazz Team Server for System z.
By default, the log4j.properties file writes Jazz Team Server messages to the
Tomcat Application Server stdout file (generally, the application server job log), as
well as to a separate file that is specified in the log4j.properties file. Edit the
@[email protected]/catalina_base/log4j.properties file and locate the line:
[email protected]@/logs/jazz.log
This line should be updated to reflect the value that you are using for your Jazz
Team Server for System [email protected]@ directory, for example:
log4j.appender.file.File=/u/jazz/logs/jazz.log
14
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Review Tomcat port configuration (recommended)
To avoid port conflicts, review the Tomcat application server default port settings
to make sure they are not the same as other application server instances that you
have installed.
About this task
By default, the Tomcat application server included with this beta package uses a
nonsecure port port 9080 and secure port 9443, along with ports 9005, 9009, and
8082. These default ports might conflict with a default WebSphere Application
Server instance that you have installed. Review the Tomcat server.xml file, which
defines these ports and is located at @[email protected]/catalina_base/conf/server.xml.
Tip: If you modify the default ports in the server.xml file, record the changes so
you can use these ports when you complete the scenario tasks.
Choose one of the following options based on the application server and database
you are using:
v Running the Jazz Team Server for System z with Tomcat and Derby
v Running the Jazz Team Server for System z with Tomcat and DB2 for z/OS
Running the Jazz Team Server for System z with Tomcat and
Derby
Running the Jazz Team Server for System z with Tomcat and Derby involves
several sample JCL members and configuration property files.
Before you begin
These instructions assume that you are using the sample
teamserver_derby.properties file. If you use a different properties file name,
change the sample JCL members to point to your properties file.
1. Edit the file teamserver_derby.properties in the @[email protected] directory.
2. Change com.ibm.team.repository.db.jdbc.location = @[email protected]/
repositoryDB to your path, for example,
com.ibm.team.repository.db.jdbc.location = /u/jazz/repositoryDB
3. Also change @[email protected] to your path in the following properties:
a. [email protected]@/workitemindex
b. [email protected]@/contentservice
c. [email protected]@/contentservice
d. [email protected]@/versionedcontentservice
Starting Tomcat using the Derby database
Now you are ready to start Tomcat using the default Derby database. If you need
to run other Jazz Team Server for System z repository tools functions, such as
importing or exporting data for migration or creating a new database, see
Appendix D, “Additional Jazz Team Server for System z repository tools tasks on
z/OS,” on page 93.
Configure member BLZSRV2 in hlq.SBLZSAMP using the instructions contained in the
sample. Use the SUBMIT command to submit the modified JCL and check the job
Chapter 5. Installing and configuring the Jazz Team Server for System z on z/OS
15
log carefully for errors and messages that the server startup has completed. You
can adjust the WLM Service Class for the BLZSRV2 job to meet your system
requirements.
You can stop the Jazz Team Server for System z by stopping this job.
Running the setup wizard
Run the setup wizard to verify that the server is operating properly. The setup
wizard also guides you through configuration of the server.
Before you begin
To verify that the Jazz Team Server is connecting to the database, look at the server
log or console output. The connection and database information is echoed on its
first access. The directory JazzInstallDir/jazz/server/tomcat/logs is used for the
server log files. This procedure assumes your server is available using the
hostname localhost and the default port 9443. If necessary, replace localhost with
your server hostname and replace the port number.
About this task
Complete the following steps to run the setup wizard:
1. Start the setup wizard to configure your server. Use the URL:
https://ipaddress:port/jazz/setup, where ipaddress is the IP address where
you started Tomcat, and port is the secure port that you specified when you
started Tomcat.
2. Enter the default user name and password:
v User name: ADMIN
v Password: ADMIN
Note: User name and password are case-sensitive.
3. Choose one of the two setup paths available on the setup wizard:
v The Fast Path Setup uses the default configuration. Use this option if you
want to get the server running quickly. Using the fast path, you set up the
user registry.
v The Custom Setup guides you through the detailed server configuration.
During the custom setup, you set up the following items:
– Database
– E-mail notification
– User registry
Note: For the Rational Team Concert for System z beta, the Tomcat user
registry is the supported user registry and Derby is the supported database. It
is sufficient for the purpose of this beta to run the Fast Path Setup. Create an
administrator, assign a developer license, and then use this ID to get started on
the user scenarios provided later in this document. Instructions for creating a
project and a team are included in this guide in Scenario 1: Getting started with
Rational Team Concert for System z.
What to do next
When the initial setup is complete, you can configure additional options using the
Jazz Team Server Administrative Web user interface using this URL:
https://localhost:9443/jazz/admin.
16
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Completing the installation
The tasks required to complete the installation should be performed by your Jazz
Team Server for System z administrator. After the server is installed, you must
consider some configuration options before continuing.
About this task
Some files contain passwords. Those files should be protected so that they are
readable only by users who are authorized to know the account passwords.
v The Jazz Team Server requires that the database password is stored in
JazzInstallDir/server/conf/jazz/teamserver.properties.
When properties files are saved, the application always makes a backup copy of
the previous version in the same directory. If you want to remove all files that
contain the cleartext password, remove the backup properties files after
configuring the server for the first time.
v When connecting to the server with the Rational Team Concert for System z
client or a Web browser, you might see security certificate warnings. To disable
the warning, see Disabling security certificate settings at http://
publib.boulder.ibm.com/infocenter/rtc/v1r0m0/index.jsp?topic=/
com.ibm.team.install.doc/topics/t_disable_server_certificates.html.
v You are now ready to connect to the server with the Rational Team Concert for
System z client or a Web browser.
Running the Jazz Team Server for System z with Tomcat and
DB2 for z/OS
Before you begin
Running the Jazz Team Server for System z with Tomcat and DB2 for z/OS
involves several sample JCL members and configuration property files. These
instructions assume that you are using the sample teamserver_db2z.properties
file. If you use a different properties file name, change the sample JCL members to
point to your properties file.
About this task
Using a database with DB2 on z/OS requires additional configuration steps.
Setting up a DB2 database
The DB2 setup tasks should be performed by your DB2 administrator.
DB2 prerequisites
Ensure that DB2 Version 9.1 for z/OS with the Universal JDBC driver is installed
and running on the z/OS system that is used as the database server. This might
not be the same system on which the Jazz Team Server runs.
The Jazz Team Server for System z requires the WLM procedures associated with
the DB2 stored procedures SYSPROC.DSNUTILS and SYSIBM.SQLxxx to be active.
If necessary, verify the stored procedures are active by comparing the names of the
DB2 WLM environment variables with the active WLM procedures. Use the SQL
SELECT command to retrieve the WLM procedure names through DB2 SPUFI or
your preferred technique:
SELECT DISTINCT WLM_ENVIRONMENT FROM SYSIBM.SYSROUTINES WHERE
(NAME='DSNUTILS' OR (SCHEMA='SYSIBM' AND NAME LIKE 'SQL%'));
Chapter 5. Installing and configuring the Jazz Team Server for System z on z/OS
17
This command produces results like the following:
---------+---------+---------+---------+---------+---------+--WLM_ENVIRONMENT
---------+---------+---------+---------+---------+---------+--DSN9WLM1
Use the following command from the z/OS console to display the WLM active
procedures: D WLM,APPLENV=*. This command produces results like the
following:
SDSF SYSLOG
2493.101 2094 2094 07/10/2008 0W
14886 COMMAND ISSUED
RESPONSE=RALNS32
IWM029I 16.31.12 WLM DISPLAY 465
APPLICATION ENVIRONMENT NAME
STATE
STATE DATA
BBOASR1
AVAILABLE
BBOASR2
AVAILABLE
BBOC001
AVAILABLE
CBINTFRP
AVAILABLE
CBNAMING
AVAILABLE
CBSYSMGT
AVAILABLE
DSN9WLM1
AVAILABLE
DSN9WLM2
AVAILABLE
DSN9WLM3
AVAILABLE
In this case, you can see that the DSN9WLM1 procedure is active.
Setting up DB2 for z/OS to use with the Jazz Team Server for
System z
When running the Jazz Team Server for System z with DB2 for z/OS, you must
create a DB2 storage group and a DB2 database. You must also authorize the Jazz
Team Server for System z user to that storage group and database.
About this task
The following steps must be performed before running the repository tools
database builder utility, which creates the Jazz repository tables in your database
instance. None of these steps is performed by the Jazz Team Server database
builder utility.
Creating a storage group
The storage group must be appropriate to the machine. The following
example shows a DB2 SQL create statement:
CREATE STOGROUP JAZZSTG VOLUMES ('*') VCAT yourHlq ;
Notes:
1. You can replace the JAZZDB name on the CREATE DATABASE statement
with a different name.
2. The storage group name is used later for the Jazz Team Server for
System z teamserver_db2z.properties
com.ibm.team.repository.db.db2.dsn.stogroup property.
3. yourHlq is the high-level qualifier of your DB2 files. It must exist on
your system, and the Jazz Team Server for System z user must have
full access to it.
Creating a database
The database must be appropriate to the system. The following example
shows a DB2 SQL create statement:
CREATE DATABASE JAZZDB STOGROUP JAZZSTG BUFFERPOOL bp8kx ;
18
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Notes:
1. You can replace the JAZZDB name on the CREATE DATABASE statement
with a different name.
2. The database name is used later for the Jazz Team Server for System
zteamserver_db2z.properties
com.ibm.team.repository.db.db2.dsn.dbname property.
3. bp8kx is the buffer pool name, for example BP8K0 (The Jazz Team
Server for System z requires an 8K page size.)
4. The buffer pool name is used later for the Jazz Team Server for System
z teamserver_db2z.properties
com.ibm.team.repository.db.db2.dsn.bufferpool property.
5. You can define multiple Jazz DB2 databases in a DB2 subsystem to
contain separate Jazz repositories. This is done in conjunction with the
Jazz Server teamserver_db2z.properties file directive
com.ibm.team.repository.db.schemaPrefix, as discussed in
“Customizing Jazz Team Server for System z properties files for DB2
for z/OS.”
Authorizing a Jazz Team Server for System z user
The Jazz Team Server for System z requires a user ID and password to
access the Jazz Team Server for System z DB2 repository. The user ID and
password are specified later in the teamserver_db2z.properties file. This
user ID is not used to log on to the Jazz Team Server for System z. It is
used only to provide authority for the Jazz Team Server for System z to
access the DB2 for z/OS database. Specifically, this user ID requires
permissions as shown here. In the following example, the user has the
name jazz.
GRANT DBADM ON DATABASE jazzdb TO jazz ;
GRANT USE OF STOGROUP jazzstg TO jazz ;
GRANT USE OF BUFFERPOOL bpx TO jazz ;
COMMIT ;
In addition, if the value of field DBADM CREATE AUTH is set to NO on
panel DSNTIPP during DB2 installation, you must grant SYSADM
authorization to the Jazz Team Server for System z user.
GRANT SYSADM TO jazz ;
COMMIT ;
Customizing Jazz Team Server for System z properties files for
DB2 for z/OS
This section describes how to edit the teamserver_db2z.properties file to
configure the database connection.
About this task
Use the -DIS DDF command for your DB2 for z/OS subsystem to display some of
the values you need to supply. For example, you can retrieve the location, ipaddr,
and port (tcpport) from the following display:
-DSN9 DIS
DSNL080I
DSNL081I
DSNL082I
DSNL083I
DSNL084I
DSNL085I
DDF
-DSN9 DSNLTDDF DISPLAY DDF REPORT FOLLOWS: 548
STATUS=STARTD
LOCATION
LUNAME
GENERICLU
NS32DB
NETA.NS32DB
-NONE
TCPPORT=3500 SECPORT=3510 RESPORT=3501 IPNAME=-NONE
IPADDR=9.42.81.74
Chapter 5. Installing and configuring the Jazz Team Server for System z on z/OS
19
DSNL086I SQL
DOMAIN=RALNS32.rtp.raleigh.ibm.com
DSNL086I RESYNC DOMAIN=RALNS32.rtp.raleigh.ibm.com
DSNL099I DSNLTDDF DISPLAY DDF REPORT COMPLETE
To configure the server, edit the @[email protected]/teamserver_db2z.properties file and
locate the following lines:
com.ibm.team.repository.db.vendor = db2z
com.ibm.team.repository.db.jdbc.location=//ipAddress:ipPort
/location:user=jazzDBuser;password={password};
com.ibm.team.repository.db.jdbc.password=jazzDBpswd
com.ibm.team.repository.db.db2.dsn.dbname=JAZZDB
com.ibm.team.repository.db.db2.dsn.bufferpool=bp8kx
com.ibm.team.repository.db.db2.dsn.stogroup=JAZZSTG
#com.ibm.team.repository.db.schemaPrefix=xx
Edit these lines to match the database configuration you created in previous steps,
and also to match your DB2 configuration. Edit the location, user, password,
dbname, bufferpool, and stogroup properties according to your configuration.
Specifically, edit the following:
1. In the following line:
com.ibm.team.repository.db.jdbc.location=//ipAddress:ipPort/
location:user=jazzDBuser;password={password};
replace:
v ipAddress with your ipaddr.
v ipPort with your tcpport.
v location with the value listed in the DDF report under LOCATION.
v jazzDBuser with the user ID you created, which has appropriate access to the
DB2 database.
Note: Do not modify password={password}.
2. In the following line:
com.ibm.team.repository.db.jdbc.password=jazzDBpswd
replace jazzDBpswd with the password for your DB2 user.
3. In the following line:
com.ibm.team.repository.db.db2.dsn.dbname=JAZZDB
replace JAZZDB with the name of the database you created.
4. In the following line:
com.ibm.team.repository.db.db2.dsn.bufferpool=bp8kx
replace bp8kx with the bufferpool you chose when you created the database.
5. In the following line:
com.ibm.team.repository.db.db2.dsn.stogroup=JAZZSTG
replace JAZZSTG with the storage group you created.
6. In the following line:
#com.ibm.team.repository.db.schemaPrefix=xx
you can remove the # and replace xx with a prefix of your choice. This is
optional. It enables you to have multiple Jazz repositories in one DB2
subsystem.
20
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Note: To create several Jazz databases in the same DB2 subsystem, you must
differentiate the table owners for the Jazz tables. To do so, the Jazz Team Server
for System z uses the com.ibm.team.repository.db.schemaPrefix directive to
add a prefix to the Jazz DB2 objects so that they are unique within a DB2
subsystem. The prefix set in com.ibm.team.repository.db.schemaPrefix will be
added to the owner along with an underscore. For example, table
WORKITEMS_SNAPSHOT.WORKITEM_CHNGS will be created as
X1_WORKITEMS_SNAPSHOT.WORKITEM_CHNGS, in a given database when
com.ibm.team.repository.db.schemaPrefix=X1.
In addition, replace all instances of @[email protected] with the path that you selected for
@[email protected] in the following properties:
v [email protected]@/workitemindex
v [email protected]@/contentservice
v [email protected]@/contentservice
v [email protected]@/versionedcontentservice
Note: Jazz Team Server for System z will create these directories.
Creating database tables using Jazz Team Server for System z
repository tools
When you use DB2 for z/OS, initially you must use the Jazz Team Server for
System z repository tools to create the required database tables and indexes for the
Jazz Team Server for System z.
About this task
Ensure the teamserver_db2z.properties file has been configured correctly as
described in “Customizing Jazz Team Server for System z properties files for DB2
for z/OS” on page 19. Then you must:
1. Configure member BLZCREDB in hlq.SBLZSAMP by following the instructions in
the sample JCL.
v The Jazz Team Server for System z and the Jazz Team Server repository tools
require access to the DB2 V9 JDBC license jar file on your system. This file is
named db2jcc_license_cisuz.jar and is located by default at
/usr/lpp/db2910_jdbc/classes.
v If the file is in a different directory, then modify the sample job to point to
the correct location.
2. Submit the modified JCL and check the job log. The following message must
end the STDOUT: The database tables were created successfully. The
details are in the JCL sample.
Starting Tomcat using the DB2 for z/OS database
At this point you are ready to start Tomcat using the DB2 for z/OS database. If
you need to run other Jazz Team Server for System z repository tools functions,
like importing or exporting data for migration or recreating a new database, see
Appendix D, “Additional Jazz Team Server for System z repository tools tasks on
z/OS,” on page 93.
Configure member BLZSRV1 in hlq.SBLZSAMP using the instructions contained in the
sample. Use the SUBMIT command to submit the modified JCL and check the job
log carefully for errors and messages that the server startup has completed. You
can adjust the WLM Service Class for the BLZSRV1 job to meet your system
requirements.
Chapter 5. Installing and configuring the Jazz Team Server for System z on z/OS
21
You can stop the Jazz Team Server for System z by stopping this job.
Completing the installation
The tasks required to complete the installation should be performed by your Jazz
Team Server for System z administrator. After the server is installed, you must
consider some configuration options before continuing.
About this task
Some files contain passwords. Those files should be protected so that they are
readable only by users who are authorized to know the account passwords.
v The Jazz Team Server requires that the database password is stored in
JazzInstallDir/server/conf/jazz/teamserver.properties.
When properties files are saved, the application always makes a backup copy of
the previous version in the same directory. If you want to remove all files that
contain the cleartext password, remove the backup properties files after
configuring the server for the first time.
v When connecting to the server with the Rational Team Concert for System z
client or a Web browser, you might see security certificate warnings. To disable
the warning, see Disabling security certificate settings at http://
publib.boulder.ibm.com/infocenter/rtc/v1r0m0/index.jsp?topic=/
com.ibm.team.install.doc/topics/t_disable_server_certificates.html.
v You are now ready to connect to the server with the Rational Team Concert for
System z client or a Web browser.
22
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Chapter 6. Installing Jazz Team Server for System z on Linux
for System z
This information provides step-by-step instructions for installing and configuring
the Jazz Team Server for System z on Linux® for System z.
These instructions are intended for system administrators responsible for installing
and maintaining the Jazz Team Server for System z on Linux for System z.
Instructions for installing the Rational Team Concert client on your workstation are
also included. To understand the instructions, you must be familiar with Windows
and Linux for System z operating systems.
Rational Team Concert for System z builds on the core Rational Team Concert
product by providing a Jazz Team Server that runs on Linux for System z.
Rational Team Concert for System z V2.0 Beta 3 is supported on Linux for System
z. The following limitations apply to installing the product on Linux for System z
for this beta program:
v Only the Jazz Team Server for System z is supported on Linux for System z. The
Rational Team Concert for System z client and Build System Toolkit for System z
are not supported.
v Installing the Jazz Team Server for System z on Linux for System z is completed
using Installation Manager. The installation and configuration processes are very
similar to the processes used for x86-based Linux, and documentation of those
processes generally applies to Jazz Team Server for System z on Linux for
System z.
Note: If you participated in a previous beta program, you cannot migrate any
code created during use of the previous beta.
v This document describes the configuration of the Tomcat application server with
a Derby database or DB2 for z/OS.
v Use a graphical desktop with your preferred Window Manager to install
Rational Team Concert for System z for Beta 3.
v The included Installation Guide referenced from the launchpad is not updated
with specific Rational Team Concert for System z information. It applies to the
base Rational Team Concert product.
Installation prerequisites
Before you can install Rational Team Concert for System z on Linux for System z,
you must ensure that the required disk space is allocated and the prerequisite
applications are installed and operational.
Rational Team Concert for System z requires the following disk space for
installation and temporary files:
v Rational Team Concert for System z installation distribution - 1200 MB (This file
can be deleted after it is unpacked.)
v Rational Team Concert for System z installation directories - 1200 MB
v Rational Team Concert for System z installed directories (including Installation
Manager) - 600 MB
© Copyright IBM Corp. 2009
23
The installation package includes:
v Java Runtime Environment (JRE) for Linux for System z (IBM J9 VM 1.5.0 64-bit)
v Apache Tomcat Version 5.5 Web application server containing the Jazz Team
Server Web application
v A Derby database and all necessary database libraries
Important: The Jazz Team Server with a Derby database supports up to 10
users. To support more than 10 users, use DB2.
Make sure you have the following prerequisite applications installed and
operational before you proceed with the installation on Linux for System z:
v Operating system: RedHat Enterprise Linux, Version 5 Update 1 or later, or
SUSE Linux Enterprise Server, Version 10 Service Pack 1
v Application Server: Apache Tomcat Server V5.5 (included)
v Optional: DB2 V9.1 for z/OS with the Universal JDBC driver configured to
ensure interoperability between the database and z/OS
Notes:
v The Derby database included in the default configuration requires no
installation, but this database has a 10-user limit.
v DB2 for z/OS is obtained separately. These instructions assume that you have
completed the basic installation configuration steps for DB2 for z/OS. See Using
the DB2 Universal JDBC Driver to access DB2 for z/OS.
Overview of installing Jazz Team Server for System z
You can install the Jazz Team Server for System z Beta 3 using Installation
Manager.
Before you begin
For best results working with the Installation Manager, establish a graphical
desktop session with your Linux for System z system. These instructions do not
include details about configuring your Linux on System z system. Some of the
options include:
SLES 10:
1. Start a VNC server.
2. Connect a VNC viewer to that VNC server.
3. From the VNC viewer, launch a graphical desktop using the kde
command.
RedHat:
1. Start a default VNC server.
2. Connect a VNC viewer to that VNC server.
3. From the VNC viewer, launch a graphical desktop using the kde
command.
RedHat:
1. Configure the .vnc/xstartup file for the user that will launch the VNC
server to support a graphical desktop from VNC.
2. Start this VNC server and connect to it with a VNC viewer.
24
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Configure your database and your server according to your installation
environment:
v Apache Tomcat Server with the default Derby database
v Apache Tomcat Server with a DB2 database on z/OS
About this task
These instructions provide an overview of the steps required for installing the Jazz
Team Server for System z.
1. Ensure you meet all installation and configuration prerequisites.
2. Download and copy the Standard edition of the Jazz Team Server for System z
compressed (.zip) file. Extract the contents of the .zip file and use the
launchpad script to launch Installation Manager to install the Jazz Team Server
for System z.
3. If you plan to use a DB2 database, set up the database to work with Jazz Team
Server for System z and create the Jazz Team Server database tables.
4. Verify and complete your installation.
Preparing to install the Jazz Team Server for System z
Before installing the Jazz Team Server for System z, you must complete special
conditions for a successful setup on Linux for System z.
v If Security-Enhanced Linux (SELinux) is enabled, you must disable it or change
the security context of the Java Runtime Environment (JRE) to allow text
relocation to install and run Rational Team Concert for System z.
Note: For more details, see “Configuring Security-Enhanced Linux” on page 33.
v Increase the maximum number of files that the Tomcat user can handle to 5,000.
You can do this by adding the following lines to /etc/security/limits.conf:
tomcat_user hard nofile 5000
tomcat_user soft nofile 5000
Note: Replace tomcat_user with the name of the user who launches the Tomcat
server.
v The reports component requires that 32-bit X11 libraries be installed on the
server. The required packages are libXp, libXinerama, and mesa-libGL.
v Ensure that the user ID that runs the Tomcat server has write access to the /tmp
directory.
Installing Jazz Team Server for System z
Download the installation files for Linux for System z from the Jazz download
page at http://Jazz.net/downloads/rational-team-concert/betas/z2.0Beta3, and
extract the contents to a directory on your file system on Linux for System z using
the unzip utility. The unzip utility will create a directory called rtcz under the
destination directory for the extracted files.
About this task
The Jazz Team Server for System z installation path names must not contain
spaces. A Derby database is included in the default configuration and requires no
installation; however, the Derby database has a 10-user limit.
Chapter 6. Installing Jazz Team Server for System z on Linux for System z
25
1. From your graphical desk top, under the directory where you extracted the
Rational Team Concert for System z installation files, navigate to the rtc
directory and run launchpad.sh.
2. For Beta 3, the only supported launchpad option is to complete a new
installation. Click the link for a new installation.
3. You will be prompted to install both Installation Manager and Jazz Team Server
for System z.
4. Follow the Installation Manager prompts to complete the installation.
Important: Be sure to leave the check box selected to install the optional
Tomcat Application Server feature.
By default, the Jazz Team Server for System z will be installed to the
/opt/ibm/JazzTeamServer directory. This directory will be referred to as
JazzInstallDir for the rest of these instructions. If you choose a different
directory, substitute your installation directory for the JazzInstallDir.
Setting up the database
After your Jazz Team Server for System z is installed, you must configure the
database.
Fast path: If you are using the included Derby database, no additional database
setup is required. Proceed to “Starting the server” on page 31.
The overview steps for setting up a DB2 database on z/OS are:
1. Create a database.
2. Configure the properties files.
3. Install the DB2 z/OS license files on your Linux on System z system.
4. Create the database tables.
If you are using DB2, proceed to “Setting up a DB2 database on DB2 for z/OS.”
Setting up a DB2 database on DB2 for z/OS
Set up a DB2 database to work with the Jazz Team Server for System z.
Before you begin
If you are using a DB2 database on z/OS, the Jazz Team Server for System z and
the Jazz Team Server for System z repository tools need access to the JDBC license
.jar file that is shipped with DB2 for z/OS. To set access to the license file,
complete the following steps:
v Create a directory called db2z under the JazzInstallDir/server directory.
v In the directory you created, place a copy of the db2jcc_license_cisuz.jar file
from your z/OS system. You can find this .jar file in the DB2 9.1 SDSNJCC file
system, which is typically mounted at a file path like /usr/lpp/db2910_jdbc.
The db2jcc_license_cisuz.jar file is located in the classes subdirectory of that
directory.
Setting up a DB2 database
The DB2 setup tasks should be performed by your DB2 administrator.
26
Rational Team Concert for System z Beta Program: Installation and User’s Guide
DB2 prerequisites
Ensure that DB2 Version 9.1 for z/OS with the Universal JDBC driver is installed
and running on the z/OS system that is used as the database server.
The Jazz Team Server for System z requires the WLM procedures associated with
the DB2 stored procedures SYSPROC.DSNUTILS and SYSIBM.SQLxxx to be active.
If necessary, verify the stored procedures are active by comparing the names of the
DB2 WLM environment variables with the active WLM procedures. Use SQL
SELECT command to retrieve the WLM procedure names through DB2 SPUFI or
your preferred technique:
SELECT DISTINCT WLM_ENVIRONMENT FROM SYSIBM.SYSROUTINES WHERE
(NAME='DSNUTILS' OR (SCHEMA='SYSIBM' AND NAME LIKE 'SQL%'));
This command produces results like the following:
---------+---------+---------+---------+---------+---------+--WLM_ENVIRONMENT
---------+---------+---------+---------+---------+---------+--DSN9WLM1
Use the following command from the z/OS console to display the WLM active
procedures: D WLM,APPLENV=*. This command produces results like the
following:
SDSF SYSLOG
2493.101 2094 2094 07/10/2008 0W
14886 COMMAND ISSUED
RESPONSE=RALNS32
IWM029I 16.31.12 WLM DISPLAY 465
APPLICATION ENVIRONMENT NAME
STATE
STATE DATA
BBOASR1
AVAILABLE
BBOASR2
AVAILABLE
BBOC001
AVAILABLE
CBINTFRP
AVAILABLE
CBNAMING
AVAILABLE
CBSYSMGT
AVAILABLE
DSN9WLM1
AVAILABLE
DSN9WLM2
AVAILABLE
DSN9WLM3
AVAILABLE
In this case, you can see that the DSN9WLM1 procedure is active.
Setting up DB2 for z/OS to use with the Jazz Team Server for
System z
When running the Jazz Team Server for System z with DB2 for z/OS, you must
create a DB2 storage group and a DB2 database. You must also authorize the Jazz
Team Server for System z user to that storage group and database.
About this task
The following steps must be performed before running the repository tools
database builder utility, which creates the Jazz repository tables in your database
instance. None of these steps is performed by the Jazz Team Server database
builder utility.
Create a storage group
The storage group must be appropriate to the machine. The following
example shows a DB2 SQL create statement:
CREATE STOGROUP JAZZSTG VOLUMES ('*') VCAT yourHlq ;
Notes:
Chapter 6. Installing Jazz Team Server for System z on Linux for System z
27
1. The storage group can be named something other than JAZZSTG.
2. The storage group name is used later for the Jazz Team Server for
System z teamserver.properties
com.ibm.team.repository.db.db2.dsn.stogroupproperty.
3. yourHlq is the high-level qualifier of your DB2 files. It must exist on
your system, and the Jazz Team Server for System z user must have
full access to it.
Create a database
The database must be appropriate to the system. The following example
shows a DB2 SQL create statement:
CREATE DATABASE JAZZDB STOGROUP JAZZSTG BUFFERPOOL bp8kx ;
Notes:
1. The database can be named something other than JAZZDB.
2. The database name is used later for the Jazz Team Server for System
zteamserver.properties com.ibm.team.repository.db.db2.dsn.dbname
property.
3. bp8kx is the buffer pool name, for example BP8K0 (The Jazz Team
Server for System z requires an 8K page size)
4. The buffer pool name is used later for the Jazz Team Server for System
z teamserver.properties
com.ibm.team.repository.db.db2.dsn.bufferpool property.
5. You can define multiple Jazz DB2 databases in a DB2 subsystem to
contain separate Jazz repositories. This is done in conjunction with the
Jazz Server teamserver.properties file directive
com.ibm.team.repository.db.schemaPrefix, as discussed in
“Customizing Jazz Team Server for System z properties files for DB2
for z/OS” on page 19.
Authorize a Jazz Team Server for System z user
The Jazz Team Server for System z requires a user ID and password to
access the Jazz Team Server for System z DB2 repository. The user ID and
password are specified later in the teamserver.properties file. This user
ID does not log on to the Jazz Team Server for System z. It is used only to
provide authority for the Jazz Team Server for System z to access the DB2
for z/OS database. Specifically, this user ID requires permissions as shown
here. In the following example, the user has the name jazz.
GRANT DBADM ON DATABASE jazzdb TO jazz ;
GRANT USE OF STOGROUP jazzstg TO jazz ;
GRANT USE OF BUFFERPOOL bpx TO jazz ;
COMMIT ;
In addition, if the value of field DBADM CREATE AUTH is set to NO on
panel DSNTIPP during DB2 installation, you must grant SYSADM
authorization to the Jazz Team Server for System z user.
GRANT SYSADM TO jazz ;
COMMIT ;
Customizing Jazz Team Server for System z properties files
for DB2 for z/OS
By default, Jazz Team Server for System z uses the configuration file located in
JazzInstallDir/server/conf/jazz for configuration information about the
database connection.
28
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Edit the teamserver.properties file. Change the following lines to comments so
that the default Derby database will not be used. Specifically, change the following
lines:
# JDBC DB location, specifying this property disables system-based selection
# of default location
com.ibm.team.repository.db.vendor = DERBY
com.ibm.team.repository.db.jdbc.location = repositoryDB
to match these lines:
# JDBC DB location, specifying this property disables system-based selection
# of default location
#com.ibm.team.repository.db.vendor = DERBY
#com.ibm.team.repository.db.jdbc.location = repositoryDB
Uncomment the following properties that start with #com.ibm by removing the #.
Then follow the instructions later in this section to set the property values.
#
# DB2z configuration
#
# Comment out above lines, uncomment the following lines and customize
# example location to use DB2z
#com.ibm.team.repository.db.vendor = db2z
# Location name of the DB2z sub-system.
# ipAddress, ipPort and location be obtained by running the DB2 command -DISPLAY DDF
#com.ibm.team.repository.db.jdbc.location=//ipAddress:ipPort/
#location:fullyMaterializeLobData=false;user=jazzDBuser;password={password};
#com.ibm.team.repository.db.jdbc.password=jazzDBpswd
# DB2z Database name
#com.ibm.team.repository.db.db2.dsn.dbname=JAZZDB
# DB2z Bufferpool name
#com.ibm.team.repository.db.db2.dsn.bufferpool=bpx
# DB2z Storage Group name
#com.ibm.team.repository.db.db2.dsn.stogroup=JAZZSTG
Use the -DIS DDF command for your DB2 for z/OS subsystem to display some of
the values you need to supply. For example, you can retrieve the location, IP
address (ipaddr), and port (tcpport) from the following display:
-DSN9 DIS DDF
DSNL080I -DSN9 DSNLTDDF DISPLAY DDF REPORT FOLLOWS: 548
DSNL081I STATUS=STARTD
DSNL082I LOCATION LUNAME GENERICLU
DSNL083I NS32DB NETA.NS32DB -NONE
DSNL084I TCPPORT=3500 SECPORT=3510 RESPORT=3501 IPNAME=-NONE
DSNL085I IPADDR=9.42.81.74
DSNL086I SQL DOMAIN=RALNS32.rtp.raleigh.ibm.com
DSNL086I RESYNC DOMAIN=RALNS32.rtp.raleigh.ibm.com
DSNL099I DSNLTDDF DISPLAY DDF REPORT COMPLETE
Edit the following lines to match the database configuration you created in
previous steps, and also to match your DB2 configuration. Edit the location, user,
password, dbname, bufferpool, and stogroup properties according to your
configuration. Specifically, edit the following:
1. In line:
Chapter 6. Installing Jazz Team Server for System z on Linux for System z
29
com.ibm.team.repository.db.jdbc.location=//ipAddress:ipPort/
location:fullyMaterializeLobData=false;user=jazzDBuser;password={password};
delete:
fullyMaterializeLobData=false;
Also, replace:
v ipAddress with your IP address.
v ipPort with your TCP port.
v location with the value listed in the DDF report under LOCATION.
v jazzDBuser with the user ID you created that has appropriate access to the
DB2 database.
Important: Do not modify password={password}.
2. In line:
com.ibm.team.repository.db.jdbc.password=jazzDBpswd
replace jazzDBpswd with the password for your DB2 user.
3. In line:
com.ibm.team.repository.db.db2.dsn.dbname=JAZZDB
replace JAZZDB with the name of the database you created.
4. In line:
com.ibm.team.repository.db.db2.dsn.bufferpool=bpx
replace bpx with the bufferpool you chose when you created the database.
Make sure it supports 8K pages. Use a bufferpool such as BP8K0.
5. In line:
com.ibm.team.repository.db.db2.dsn.stogroup=JAZZSTG
replace JAZZSTG with the storage group you created.
6. Insert the following line if you choose:
com.ibm.team.repository.db.schemaPrefix=xx
replace xx with a prefix of your choice. This is optional. It enables you to have
multiple Jazz repositories in one DB2 subsystem.
Note: If you want to create several Jazz databases in the same DB2 subsystem,
you must differentiate the table owners for the Jazz tables. In order to do that,
the Jazz Team Server for System z uses the
com.ibm.team.repository.db.schemaPrefix directive to add a prefix to the Jazz
DB2 objects so that they are unique within a DB2 subsystem. The owner will
include the prefix set in com.ibm.team.repository.db.schemaPrefix along with
an underscore. For example, the table WORKITEMS_SNAPSHOT.WORKITEM_CHNGS will
be created as X1_WORKITEMS_SNAPSHOT.WORKITEM_CHNGS, in a given database
when com.ibm.team.repository.db.schemaPrefix=X1.
Creating the Jazz Team Server database tables
Create the database tables using the repository tools.
30
Rational Team Concert for System z Beta Program: Installation and User’s Guide
About this task
To create the database tables:
Run the command repotools.sh -createTables to create the database tables for a
Jazz repository.
The repotools.sh script is located in the JazzInstallDir/server directory.
The command uses the configuration properties in teamserver.properties for the
connection and size settings. By default, the command looks in the current
directory.
v Execute the following command:
./repotools.sh -createTables
This command creates the tablespace and all the required tables and indexes for a
Jazz Team Server repository.
Starting the server
This topic describes the different options for running the server startup scripts.
Starting the Apache Tomcat server
Before you begin
Apache Tomcat has been installed in the directory JazzInstallDir/server/tomcat.
The Web application (jazz.war) has been installed in the Apache Tomcat directory
webapps. In a command window, set your current directory to
JazzInstallDir/server. The server startup and shutdown scripts are located in
this directory.
v If you want to run the start and stop scripts from any other directory, you must
change the .ini files in JazzInstallDir/server/conf/jazz/provision_profiles
to use an absolute path.
v You can also use the Start Jazz Team Server option from your main application
start tab in the graphical desktop in the Jazz Team Server folder.
v Tomcat is configured to use the ports 9080 and 9443 in file JazzInstallDir/
server/tomcat/conf/server.xml. If necessary, change them as appropriate for
your system. If necessary, also update the configuration settings of Jazz Team
Server repository HTTP ports in the Advanced Properties configuration page in
the Jazz administrative Web interface.
v The directory JazzInstallDir/server/tomcat/logs contains the server log files.
If you have trouble starting the server, check the log files.
You are now ready to start the Tomcat server. To start the server, run the startup
file.
1. To start the server as user root, run this command:
./server.startup
If your user ID has administrator access, run this command:
sudo ./server.startup
Note: A separate Apache Tomcat console window is not visible. You can check
the server startup progress by viewing the log file at JazzInstallDir/server/
tomcat/logs/catalina.out.
2. To stop the server as user root, run this command:
./server.shutdown
Chapter 6. Installing Jazz Team Server for System z on Linux for System z
31
If your user ID has administrator access, run this command:
sudo ./server.shutdown
Note: This example runs the start and stop scripts directly from the directory
JazzInstallDir/server.
What to do next
When the server is started, proceed to “Running the setup wizard.”
Running the setup wizard
Run the setup wizard to verify that the server is operating properly. The setup
wizard also guides you through configuration of the server.
About this task
To verify that the Jazz Team Server for System z is connecting to the database, look
at the server log or console output. The connection and database information is
echoed on its first access. The directory JazzInstallDir/server/tomcat/logs is
used for the server log files.
This procedure assumes your server is available using hostname yourServerName
and the default port 9443. If necessary, replace yourServerName with your server
hostname and replace port 9443.
Start the setup wizard to configure your server. Use the URL: https://
yourServerName:9443/jazz/setup.
The default user name and password are case-sensitive.
v If you use the local operating system (Linux for System z) as a security
repository, log in as a JazzAdmin user that is defined in your Linux for System z
system.
v The default user name is: ADMIN
v The default password is: ADMIN
Choose a setup path. The setup wizard has two main paths.
v The Fast Path Setup uses the default configuration. If you want to get the server
running quickly, the fast path setup is a good option. During the Fast Path
Setup, you set up the following:
– user registry
v The Custom Setup guides you through the detailed server configuration,
including the ability to enable e-mail notifications. During the Custom Setup,
you set up the following:
– database
– e-mail notification
– user registry
When the initial setup is complete, additional options can be configured from the
Jazz Team Server Administrative Web user interface by using the URL:
https://yourServerName:9443/jazz/admin.
What to do next
If the server setup wizard does not load, check the following items:
v Verify that the application server has started. Use the URL: http://
yourServerName:9080.
32
Rational Team Concert for System z Beta Program: Installation and User’s Guide
v Verify the Jazz Team Server has started by logging in to the Jazz Team Server
Administrative Web interface using the URL: https://yourServerName:9443/
jazz/admin.
v
The URI root for the Jazz Team Server path must be /jazz. For example:
https://example.com:9443/jazz must be used rather than https://
example.com:9443.
Completing the installation
After the server is installed, you must consider some configuration options before
continuing.
About this task
Some files contain passwords. Those files should be protected so that they are
readable only by users authorized to know the password for the accounts.
v
– teamserver.properties - The Jazz Team Server requires that the database
password is stored in JazzInstallDir/server/conf/jazz/
teamserver.properties.
When properties files are saved, the application always makes a backup copy
of the previous version in the same directory. If you want to remove all files
that contain the cleartext password, remove the backup properties files after
configuring the server for the first time.
– cqconnector.properties sync engine requires that user passwords be stored in
an properties file.
– cqconnector.properties - The ClearQuest Connector requires that both
ClearQuest® user IDs and passwords be stored in a properties file.
v When connecting to the server with the Rational Team Concert for System z
client or a Web browser, you might see security certificate warnings. To disable
the warning, see Disabling security certificate settings at http://
publib.boulder.ibm.com/infocenter/rtc/v1r0m0/index.jsp?topic=/
com.ibm.team.install.doc/topics/t_disable_server_certificates.html.
v You are now ready to connect to the server with the Rational Team Concert
client or a Web browser.
Configuring Security-Enhanced Linux
If Security-Enhanced Linux (SELinux) is enabled, you must either disable it or
change the security context of the Java Runtime Environments (JREs) used for
installing and running Rational Team Concert to allow text relocation.
About this task
If you have set up a machine for the sole purpose of evaluating Rational Team
Concert and the SELinux features are not important to you, then the easiest way to
proceed is to disable SELinux.
Notes:
v SELinux is installed and enabled by default on Red Hat Enterprise Linux 5.
v SELinux is not installed on Suse Linux Enterprise Server 10.
v To disable SELinux from the command line:
1. Run the setup command (this is/usr/bin/setup).
2. Select Firewall Configuration and press Enter.
Chapter 6. Installing Jazz Team Server for System z on Linux for System z
33
3.
4.
v To
1.
2.
Use the tab and arrow keys to change the SELinux to Disabled.
Select OK and press Enter.
change the security context of the JRE:
In the JazzInstallDir/server directory, locate the directory jre.
Run the command chcon -R -t textrel_shlib_t against the jre directory. This
command recursively processes the files and allows text relocation. For
example:
chcon -R -t textrel_shlib_t /opt/IBM/JazzTeamserver/server/jre
34
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Chapter 7. Setting up the Rational Build Agent
This section describes how to complete the installation of the Rational Build Agent
on z/OS for Beta 3. You must have installed FMID HAHD200 as part of the
SMP/E package installation of Rational Team Concert for System z prior to
completing these steps. In addition, for Beta 3, you must mount the Rational Team
Concert for System z installation HFS as writeable to complete these steps. After
completing these steps, you can mount the installation HFS as read-only if you
prefer.
Refer to Installing Rational Team Concert for System z for information about the
FMIDs that can be installed independently from each other. The SMP/E package is
contained in the download file RTCz-SMPE-2.0Beta3.zip, along with the Program
Directory.
Installing and running the agent on z/OS
The build agent executable file has been installed into yourPathPrefix/usr/lpp/
jazz/bfagent during the SMP/E installation.
Complete these steps to finish the installation and to start the Rational Build
Agent:
1. You must make the build agent program controlled. To do so in USS, change
directories to yourPathPrefix/usr/lpp/jazz/bfagent and run the following
command from an authorized user:
extattr +p -s bfagent
2. 2. On the z/OS system, to start the build agent manually, change to
yourPathPrefix/usr/lpp/jazz/bfagent, and use the -s option:
bfagent -s -f /etc/rtcz/bfagent.conf
The agent runs as a stand-alone daemon and uses the default agent port 5555.
To change the default port, use the port setting in bfagent.conf. See “bfagent
reference” on page 85. Also see inetd tips below.
3. 3. On the z/OS system, use the telnet command to test the connection. See
“Testing the connection” on page 83.
Tips for using inetd or xinetd
If the UNIX TCP/IP daemon (inetd or xinetd) is installed and active on the z/OS
system, you can set up the Rational Build Agent to run as a service and start
automatically. For additional information on configuring inetd, refer to the z/OS
V1R9 Information Center at http://publib.boulder.ibm.com/infocenter/zos/v1r9/
index.jsp?topic=/com.ibm.zos.r9.cs3/cs3.htm (or the appropriate information center
for your version of z/OS). The full configuration of inetd is beyond the scope of
this document. In a simple example, you could:
1. Modify /etc/inetd.conf by adding this line:
bfagent stream tcp nowait userID /u/rtcz/bfagent -f /etc/rtcz/bfagent.conf
bfagent
Service name of the daemon. Default is bfagent (lowercase). The name must
match the name used in /etc/services.
© Copyright IBM Corp. 2009
35
stream tcp nowait
Specific inetd configuration statements (socket type, protocol, wait flag). Do
not modify.
User ID
User ID for the daemon process. The default is OMVSKERN. This user ID
must be a user ID with a valid OMVS security segment, BPX.DAEMON
permission and READ and EXECUTE permission to the installation and
configuration directories.
/u/rtcz/bfagent
Server program (absolute location of bfagent). Default is /u/rtcz/bfagent.
The arguments after this inetd argument are server arguments.
-f /etc/rtcz/bfagent.conf
Working directory (location of Build Forge server configuration file). The
default is /etc/rtcz/bfagent.conf.
Important: Copy the customized Build Forge configuration files to a new
directory (like /etc/rtcz/) to avoid overwriting them when applying
maintenance. The working directory defined here must reflect this change.
2. Add the following to /etc/services:
bfagent 5555/tcp #BUILD FORGE AGENT
3. Update the port in your bfagent.conf to map to your services entry:
port 5555
4. Restart inetd.
Running an agent
This section describes how to set up an agent to run. It is normally run as an
auto-starting service or daemon, but for the Rational Team Concert for System z
beta, you can start the bfagent program from the command line.
Configuring the agent
This section describes how to configure the agent after installation.
Changing the agent port
If you install the agent on a server where port 5555 is already occupied, you can
change the agent port after it is installed.
To change the port:
1. Modify the port value in your bfagent.conf file.
2. If you are running a stand-alone server (that is, you started with bfagent -s),
you can use the kill command to stop the current bfagent process and restart
using the command you used to start the agent the first time.
3. If you are running via inetd, you also need to modify your port setting in the
/etc/services file and restart inetd.
Configuring a different shell
You can configure an agent to use a shell other than the default shell by editing
parameters in the bfagent.conf file.
For example, to use the tcsh shell, you can set the shell parameter as follows:
36
Rational Team Concert for System z Beta Program: Installation and User’s Guide
shell /bin/tcsh
For more information on the bfagent.conf file, see “bfagent.conf reference” on page
85
Build Agent Lookup Service
Rational Build Agent service plug-ins provide the capability to look up the build
requests that use Rational Build Agent as the build engine. In the Rational
TeamConcert for System z client, you can create build definitions that use
RationalBuildAgent as the build engine. The Build Agent Lookup Service checks
build requests in the repository periodically to locate requests that use Rational
Build Agent as the build engine. When the build requests are found, they are
handled by the internal service and send command lines to Rational Build Agent.
The Build Agent Lookup Servicel handles multiple build requests in each lookup
period. However, if there is more than one build definition defined to use one
Rational Build Agent, and a user requests builds using these build definitions at
same time, the Build Agent Lookup Service only handles one build request in the
lookup period. A single Rational Build Agent should only receive one build request
at a time.
Lookup Service Setup
You can set up a BuildAgentLookupTask, known as the BuildAgentLookupService,
in the Jazz Administration Web interface. Go to the Jazz Administration > Server
tab > Advanced Properties > Build Agent section.
You can set two values on this panel:
Build Agent Loop Task Contributor id
This is the user running the build agent loop task service on the server
side. The default user id is ADMIN.
Note: Ensure that the user running the BuildAgentLookupTask has
permissions to perform build actions. The user needs full permissions for
build actions in the specified team areas. Follow these steps to give the
user the necessary permissions.
Chapter 7. Setting up the Rational Build Agent
37
1. The user must be a member of the specified Project Areas and Team
Areas.
2. The user is set to a specific role in the Project Area and Team Area. If
no role is set, the default setting is everyone.
3. The user role must have full permissions for build activities in the
Project Area and Team Area. You can define the permissions in the
Project Area > Process Configuration tab > Team configuration >
Permissions.
Build Agent loop task interval time
This value defines the interval running time of the BuildAgentLookupTask,
in seconds. The default value is 60 seconds.
38
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Chapter 8. User scenarios for Rational Team Concert for
System z
The user scenarios for the Rational Team Concert for System z beta program are
designed to introduce you to basic Rational Team Concert functions and to provide
early access to new System z components. In some cases, components that are still
being developed are available as previews and might not be fully functional.
The following scenarios are included:
Scenario 1: Getting started
This scenario includes information for using the basic functions of Rational
Team Concert and Rational Team Concert for System z.
Scenario 2: Using the System z Jazz Gateway to integrate with an existing SCM
Using SCLM (Software Configuration Library Manager) as an example, this
scenario explains how to use the System z Jazz Gateway and your existing
software configuration management system with Rational Team Concert
for System z.
Scenario 3: Preview of the mass import tool
This scenario describes how to use the Rational Team Concert for System z
mass import tool to import members from multiple partitioned data sets
into Rational Team Concert for System z source control.
Scenario 4: Using the Rational Build Agent to execute command-driven builds
This scenario describes how to use Rational Team Concert for System z
with the Rational Build Agent to run project builds.
Scenario 5: Using the Rational Build Agent and Job Monitor to execute builds
using JCL
This scenario describes how to use Rational Build Agent and the Job
Monitor to run project builds.
Scenario 6: Using the Rational Build Agent and Antz build extensions to
compile a COBOL application
This scenario explains how to uses Ant to build a simple COBOL
application on a z/OS build machine, use the Rational Team Concert for
System z data definition, translator, and language definition components to
define the build environment, and create a shared zComponent project
containing COBOL source code and a build.xml file that defines the Antz
build process.
Scenario 1: Getting started with Rational Team Concert for System z
There are many resources to help you get started with Jazz components and
Rational Team Concert for System z.
The Rational Team Concert for System z beta extends the functions of Rational
Team Concert. Most of the documentation for Rational Team Concert V2 and V1 is
appropriate for the System z version as well.
To help you get started, review the following resources:
© Copyright IBM Corp. 2009
39
Rational Team Concert help
The help content is available from the Rational Team Concert for System z
client by selecting Help → Help Contents after you launch the client.
Online resources
The Jazz.net community site and IBM developerWorks each have valuable
information. You can find direct links from Rational Team Concert for
System z client by selecting Help → Web Resources after you launch the
client.
The information from these sources is relevant to this beta program; however, the
following limitations apply:
v The Rational Team Concert for System z Beta 3 depends on Rational Team
Concert V2 Milestone 3 driver, so any limitations apply to both.
v Rational Team Concert V2 information that applies to platforms that are not
included in the Rational Team Concert for System z Beta 3 packages does not
apply at this time.
The Rational Team Concert for System z team can assist with answering questions
about how specific sections apply to the System z beta.
The “Getting started with Rational Team Concert” tutorial is useful for introducing
the basic concepts and terminology for Rational Team Concert and Rational Team
Concert for System z. The tutorial uses Java projects and a Windows server, but the
key concepts of Rational Team Concert for System z are still introduced.
In the section “Examine the Jazz Build,” for the System z beta, you have the option
to run a Jazz Build Engine on Windows or on z/OS. If you choose to run the Jazz
Build Engine on Windows or Linux, you can install it on a Windows or Linux 32
bit machine using the launchpad for the Client for Eclipse IDE, Server and
Optional Features package and run the jbe.exe (or jbe program on Linux) under the
jazz\buildsystem\buildengine\eclipse directory where you installed the files.
If you prefer to run the Jazz Build Engine on z/OS instead of Windows as the
tutorial instructs, see the additional information on customizing the Jazz Build
Engine JCL in Appendix A. Running the Jazz Build Engine on z/OS later in this guide.
The build section of the tutorial introduces basic concepts of Rational Team
Concert for System z builds; however, the build agent for native z/OS builds is the
Rational Build Forge agent as described in Scenario 2: Using the Build Forge agent
with Rational Team Concert for System z.
Complete the basic tutorial before you work on the other user scenarios in this
guide.
To start the tutorial, from the Rational Team Concert for System z client Help
menu, select Welcome → Tutorials → Get started with Rational Team Concert. The
tutorial will teach you how to:
v Set up a project and team.
v Get connected as a user.
v Create and understand work items.
v Organize team work.
v Save and share source.
v Use the Web user interface.
v Examine the Jazz build.
40
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Expect to spend a few hours to complete the tutorial.
For a faster introduction, see the Jazz technology platform quick reference at
https://jazz.net/jazzdocs/topic/com.ibm.team.platform.doc/topics/c_jazzplatform-quick-ref.html.
To get started using Rational Team Concert for System z, begin with the following
help topics, which are available from the help menu of the Rational Team Concert
for System z client or Jazz.net:
v Administering the Jazz Team Server through the Web interface: https://jazz.net/
jazzdocs/topic/com.ibm.team.repository.web.admin.doc/topics/
tworkwithadminwebui.html
v Working with projects, teams, and process: https://jazz.net/jazzdocs/topic/
com.ibm.team.platform.doc/topics/t_projects_teams_process.html
Explore the online help and the Jazz.net Web site for product details, concepts, and
troubleshooting, for Rational Team Concert, the Jazz platform, and new incubator
technologies. After completing the getting started tutorial, the remaining scenarios
in this guide will introduce you to the new functions of Rational Team Concert for
System z.
Scenario 2: Using the System z Jazz Gateway to integrate with existing
SCMs
With the System z Jazz Gateway, you can programmatically extract information
from the Rational Team Concert for System z repository. Jazz already provides a
REST interface to return work item information in the form of XML. The System z
Jazz Gateway provides the interface that handles the secure user ID authentication
and returns either the status of a work item or the complete XML.
This scenario depends on the SMP/E installation of FMID HAHB200 (Build System
Toolkit for System z).
This scenario uses SCLM, IBM’s z/OS software configuration management (SCM)
offering, to show how you can use the gateway as an interface to the Rational
Team Concert for System z repository. SCLM has a number of user exit points
where you can add your own processes. It is through the Edit and Promote user
exit points in SCLM that you access the System z Jazz Gateway server.
Additionally, SCLM can assign “Change Codes” to modules to tag the code as in
process for a particular change. This change code maps to the Rational Team
Concert for System z work item, so using the change code input field in SCLM to
enter a Rational Team Concert for System z work item number we can perform the
required checks.
Apply this scenario if you are using an existing z/OS SCM to manage your source
code, such as SCLM, but want to use Rational Team Concert for System z to track
defects and other tasks through work items. Using the Jazz Gateway, you can deny
or allow processes to run on your z/OS by checking the current status of a work
item. For example, if a specified work item does not exist, or is not In Progress,
you can forbid edits. If the specified work item is not Resolved, you cannot move
the code to the next stage of development.
Chapter 8. User scenarios for Rational Team Concert for System z
41
Starting the System z Jazz Gateway server
About this task
To start the System z Jazz Gateway server, you must:
1. Configure the sample JCL member BLZGWSRV in hlq.SBLZSAMP, where hlq is
the high-level qualifier specified during the SMP/E installation.
2. Submit the modified JCL and check the job log. The following message must be
in the STDOUT: Gateway listening on port:3456 where 3456 is the port
number you assigned in the BLZGWSRV member.
Note: The gateway server must run in ASCII so ensure that you have specified
-Dfile.encoding=ISO8859-1. This should be set by default in the job.
Creating an encrypted password file for the System z Jazz
Gateway
About this task
The System z Jazz Gateway can accept a password in clear text or a password that
has been encrypted and stored in a file. In order to use an encrypted password,
run a JCL to create the file that will contain the password. The executable files that
invoke the REXX client must pass a file parameter instead of passing the clear text
password itself.
The password file must be named GatewayPass and it must be in the users home
directory.
To create an encrypted System z Jazz Gateway password file:
1. Configure the sample JCL member BLZGPASS in hlq.SBLZSAMP.
2. Set your ASCII and EBCDIC code pages. The password must be encrypted in
ASCII, but in the JCL it is in EBCDIC. Therefore, the password must be
converted to ASCII prior to being encrypted. By default the code pages are set
to ISO8859-1 for ASCII and IBM-1047 for EBCDIC.
3. Submit the modified JCL and check the job log. The following message must be
in the STDOUT: Password stored in file: "/u/youruser/GatewayPass" where
/u/youruser is the directory where you created the password file. This should
either be your home directory or you must copy the password file to your
home directory after the job is finished.
Note: The password has to be encoded using the same code page that the
server requires. By default, the server will have been started with the
-Dfile.encoding=ISO8859-1 option. The job that creates the password must use
the same code page as the server in the –Dfile.encoding option.
Setting the REXX Gateway client to communicate with the
server
These steps describes how to set up and use the REXX Gateway client to
communicate with the Jazz Gateway server.
About this task
Before you can use the System z Jazz Gateway server, you must configure the
REXX Gateway client by completing the following steps:
42
Rational Team Concert for System z Beta Program: Installation and User’s Guide
1. Using the instructions in the sample REXX, configure member BLZGWCLI in
hlq.SBLZSAMP. Set the parameters for the server address where the gateway is
running and the port number that the gateway is monitoring. If you use an
encrypted password file, set your ASCII and EBCDIC code pages. The
password has been encrypted in ASCII but the other parameters are set to
EBCDIC prior to being passed through to the gateway. Therefore, the encrypted
password string also must be converted to EBCDIC. By default the code pages
are set to ISO8859-1 for ASCII and IBM-1047 for EBCDIC.
2. To test the System z Jazz Gateway server, configure member BLZGWTST in the
hlq.SBLZSAMP data set using the instructions in the sample REXX.
Remember: If you use an encrypted password file, set the password variable to
file to instruct the REXX Gateway client to get the password file from the user’s
home directory.
3. To run the test enter TSO EX hlq.SBLZSAMP(BLZGWTST). If you had set the test to
return the work item status and if the work item exists, you will receive a
message indicating the status of the work item similar to: Workitem number 1
is in New status. Note that this command is a sample and hlq.SBLZSAMP is the
name of the data set where you uploaded the members. (Your data set name
might be different.)
Results
If you set the test to return the full XML, you will receive the following message:
XML Returned for workitem number 1. The view will change to the returned XML.
Setting up the System z Jazz Gateway to control SCLM
workflow
SCLM has a number of user exit points that use the information returned by the
System z Jazz Gateway server. This topic describes the steps to set up and use
SCLM with the System z Jazz Gateway server.
Before you begin
You must have configured the REXX Gateway client as described in the previous
step.
About this task
Complete the following steps to set up the System z Jazz Gateway:
1. If your SCLM project is not already invoking CCVFY and PROMOTE user
exits, you can start them by modifying the FLMCNTRL macro and rebuilding
the project definition. The FLMCNTRL macro will look something like this:
Chapter 8. User scenarios for Rational Team Concert for System z
43
*
**********************************************************************
*
PROJECT CONTROLS
**********************************************************************
*
*
FLMCNTRL ACCT=DOHERTL.ACCOUNT.FILE,
C
CCVFY=SCLMEXIT,
* CCVFY USER EXIT
C
CCVFYCM=TSOLNK,
* METHOD TO CALL EXIT
C
CCVFYDS=DOHERTL.PROJDEFS.SOURCE,
C
PRMVFY=SCLMEXIT,
* PROMOTE VERIFY USER EXITC
PRMVFYCM=TSOLNK,
* METHOD TO CALL EXIT
C
PRMVFYDS=DOHERTL.PROJDEFS.SOURCE,
C
MAXVIO=999999,
C
VIOUNIT=VIO
*
2. The SCLMEXIT member below contains an invocation of the actual user exit. If
your site already has SCLM user exits in place then you can add the SELECT
CMD ... statement shown in the REXX code below into your existing user exits.
If your site does not have SCLM user exits in place, then create a member in
your project definition library that contains the code below, and make sure
your user exit invocation statements point to it, as shown in the previous
figure. You should change BLZ.SBLZSAMP to the data set name where you
uploaded the samples.
/* REXX */
ARG parm
Address ISPEXEC
"SELECT CMD(EX 'BLZ.SBLZSAMP(BLZSCLM1)' '"parm"') NEST"
Exit rc
3. Using the instructions in the sample REXX, configure member BLZSCLM1 in
the data set where you uploaded the samples. This member will call the REXX
Gateway client to check the work item status. It will then allow or deny the
SCLM action through the user exit return codes.
Remember: If you use an encrypted password file, set the password variable to
file to instruct the REXX Gateway client to get the password file from the user’s
home directory.
Using SCLM with Rational Team Concert for System z work
items
The following test cases indicate the results that occur under the conditions set in
the SCLM user exit code.
The terms ″change code″ and ″work item″ are interchangeable in these scenarios
because the SCLM change code is passed through to Rational Team Concert for
System z as a work item. The SCLM user exit checks the last change code saved
against a member and uses that to check the status of a work item in Rational
Team Concert for System z.
The SCLM user exit code uses an SCLM hierarchy of DEV → TEST → PROD.
Test case 1: Ensure that edit is not allowed if a change code is not entered
Instructions: Go to SCLM edit and select a member to edit, but do not
enter a work item in the change code field.
Result: The user exit returns the following message: You must enter a
valid workitem number. Only numerics and no leading blanks or zeros.
44
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Test case 2: Ensure that edit is not allowed if a change code is entered that is not
valid Instructions: Go to SCLM edit, select a member to edit, but in the change
code field, enter a work item that is not valid.
Result: The user exit returns the following message:
===> E: GWClient128E SOCKET(Read) rc=0 Error=Work Item 5555 does not exist.
Search for a different work item number. HTTP status is : 404.
The status of the socket set is GWClient Connected Free 39 Used 1
Workitem number 5555 does not exist in the RTC repository,
or the gateway server is not running.
Test case 3: Ensure that edit is not allowed if a work item in a state other than
“In Progress” is entered
Instructions: Go to SCLM edit, select a member to edit, then in the Change
Code field, enter a valid work item that is in Resolved status.
Result: The user exit returns the following message: Workitem number 96
is in Resolved status. This is not a valid status for edit.
Test case 4: Ensure that edit is allowed if the work item number entered in the
change code is in “In Progress” status
Instructions: Go to SCLM edit, select a member to edit, then in the Change
Code field, enter a valid work item that is in In Progress status.
Result: Edit is allowed on the member.
Test case 5: Try to promote a member that has a change code assigned to it that
is not in resolved status.
Instructions: Go to SCLM promote, select a member to promote that has
been previously edited and has been assigned a change code that is a work
item that is still in In Progress status.
Result: Promotion fails with the following message: Workitem number 1 is
in New status. This is not a valid status for promotion.
Test case 6: Try to promote a member that has a change code assigned to it that
is in resolved status.
Instructions: Go to SCLM promote, select a member to promote that has
been previously edited and assigned a change code that is a work item
that is in Resolved status.
Note: This involves going to Rational Team Concert for System z after the
change in SCLM has been edited, built, and tested and is ready to be
promoted. When the member is ready to be promoted, change the work
item status to Resolved.
Result: Promotion is allowed to continue.
Test case 7: Try to promote a member from TEST to PROD when the work item
is in resolved status.
Instructions: In this scenario the status of the work item must be Closed
before promotion to PROD is allowed. Go to SCLM promote and select a
member to promote that was previously promoted to TEST when the work
item was in Resolved status. Try to promote that member to PROD while
the work item is still in Resolved status.
Result: The promotion fails, and the following message is displayed:You
can only promote higher than TEST when status has moved from
Resolved. This is not a valid status for promotion to PROD.
Chapter 8. User scenarios for Rational Team Concert for System z
45
Scenario 3: Preview of the mass import tool
Overview of the Rational Team Concert for System z mass
import tool
With the mass import tool, you can import members from multiple partitioned
data sets (PDS) on a z/OS system into Rational Team Concert for System z source
control. You can set up the import process using options and mapping files that
automatically create the required project structure and data set definitions. You can
also associate members with language definitions. A language definition describes
how members are built by specifying preprocessing tasks and setting the correct
compiler and compiler options.
The mass import tool is intended to be used by project administrators who are
responsible for setting up version and source control systems.
The import process automatically creates a new repository workspace that contains
projects, called zComponent projects, in which your PDS members are organized and
stored. You can use a mapping file to define a more detailed project structure
before you run the import command. With a mapping file, you can specify which
PDS members should be placed in which zComponent projects and subfolders,
called zFolders. The mapping file also specifies which component will contain each
zComponent project. You can also use the mapping file to associate fully qualified
PDS member names to a language definition that you previously created.
Run the mass import tool from the Rational Team Concert for System z command
line interface (CLI) using the zimport subcommand of the SCM command. The
SCM command is found in the following directory:@[email protected]/usr/lpp/jazz/
scmtools/eclipse, where @[email protected] is any path prefix specified during the
SMP/E installation. After you import the PDS members, they are contained by a
zComponent project in the newly created repository workspace.
Notes:
v You must run the zimport subcommand on System z, it will not run on
Windows or Linux.
v The JAVA_HOME environment variable must be set to a directory containing a
1.5 SDK. You can set this variable using a command like this: export
JAVA_HOME=/u/smith/java/J5.0. The JAVA_HOME variable can also be set in
/etc/profile for all users, or $HOME/.profile, where $HOME is the home
directory of a specific user.
v If you use the Command Line Interface on z/OS you must log in with a region
size large enough to run a Java Virtual Machine. This is normally 1000 MB, so
you must specify a region size of at least 1,000,000.
Importing z/OS partitioned data set members to a zComponent
project
Before you begin
Before you can import z/OS partitioned data set (PDS) members to a Rational
Team Concert zComponent project, the following conditions must be met:
v You must already have created a project area in Rational Team Concert for
System z. If you prefer, after you create the zComponent project, you can also
create a stream within that project area to be the default flow target for the
repository workspace that the mass import command creates, although this is
46
Rational Team Concert for System z Beta Program: Installation and User’s Guide
not a required step. You can also create language definitions to associate with
your imported z/OS members, although this is not a required step either.
v The Rational Team Concert for System z server must be running when you
begin a Rational Team Concert for System z mass import.
v The user whose authentication information is specified to the zimport command
must have permission to save data set definitions. Permissions for language
definitions are not required because the zimport command does not create those,
it just associates zFiles to existing language definitions.
1. Enter the zimport command, which is a subcommand of scm. Your command
line might look something like this:
scm zimport --hlq SMITH --mapfile /u/smith/mapping.txt
--projectarea TestProjectArea -s MyStream
-r https://localhost:9443/jazz -u username -P password
Tips:
v For more information on how to use the zimport command, run the scm
help zimport command.
v If you want to see what the results of the zimport command would be
without actually executing a mass import, specify either the -n or --dry-run
option to scm, like this:
2.
3.
4.
5.
6.
scm -n zimport --hlq SMITH --mapfile /u/smith/mapping.txt
--projectarea TestProjectArea -s MyStream
-r https://localhost:9443/jazz -u username -P password
Specify the -r option to indicate which Rational Team Concert for System z
repository to import the PDS members to.
Specify the -u option to indicate a user name for the repository.
Specify the -P option to indicate a password for the repository.
Specify the --hlq option to indicate the high-level qualifier of the partitioned
data sets whose members you want to import.
Specify the --mapfile option to indicate the location of the mapping file the
mass import tool should use.
7. Specify the --projectarea option to indicate the name of the project area where
you want to store the data set definitions, and where the language definitions
are stored.
8. Optional: Specify the -s option to indicate the name, alias, or universal unique
identifier (UUID) of the stream to set as the default flow target for the
repository workspace that the zimport command creates.
9. Optional: Specify the -q option to suppress all console output.
10. Optional: Specify the -v option to increase the verbosity of the output.
Note: If you specify both -q and -v, no output is displayed.
What to do next
After the zimport process is complete, a new Rational Team Concert for System z
repository workspace exists, which contains components that contain zComponent
projects, which themselves contain zFolders and zFiles that correspond to the
imported PDS and its members. If you specify the -s option, your new workspace
will use that default flow target. You should also see new data set definitions in
the Rational Team Concert for System z Team Artifacts view.
Chapter 8. User scenarios for Rational Team Concert for System z
47
Tip: You might have to refresh the list before these new data set definitions
display.
Rational Team Concert for System z will create a data set definition for each PDS
you import, and the corresponding zFolder will be associated with that data set
definition, too. If you specified any language definition mappings, the zFiles
should also be associated with those specified language definitions.
Options supported by the Rational Team Concert for System z
mass import tool
This topic lists and briefly describes the options available through the mass import
tool.
Run the mass import command, zimport, from the Rational Team Concert for
System z command line interface (CLI). The mass import tool supports the
following options:
-r
For repositoryURI. Use this option to specify the location of the repository
to which you want to import the partitioned data set (PDS) members.
-u
For user. Use this option to specify a user name for the repository.
-P
For password. Use this option to specify a repository password.
Important: Use a capital P for this option, not a lower case p.
--hlq
For HLQ. Use this option to specify the high-level qualifier (HLQ) of the
partitioned data sets you want to import.
--mapfile
For file. Use this option to specify the location of the mapping file to use.
This mapping file describes the structure of the project to which you want
to import the PDS members. You must always specify the location of the
mapping file, and your mapping file must contain the following two types
of mapping:
v Mapping from the PDS members to the zComponent project to which
you want to import them.
v Mapping from the zComponent project to the Jazz component to which
the project belongs.
It is optional for your mapping file to contain mapping from members to
their associated language definition.
Remember: The language definition must already exist in the specified
project area.
--projectarea
For projectArea. Use this option to specify the name of the project area
where the data set definitions that are related to the imported members
should be stored. This should be the same project area where the related
language definitions are stored.
48
-s
Optional: For stream. Use this option to specify the name, alias, or UUID of
the stream you want to set as the default flow target for the repository
workspace that is created with your mass import.
-q
Optional: For quiet. Use this option to suppress all console output.
-v
Optional: For verbosity. Use this option to increase the output verbosity.
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Mapping file format
The mapping file is line-delimited, wherein each line must follow this format:
<identifier character> : <key> = <value> The table below indicates possible line
combinations. For more information about mapping file rule restrictions, see
“Rational Team Concert for System z mass import tool: mapping file rule
restrictions” on page 50.
Table 1. Mass import line combinations
Identifier
Key
Value
Notes
C
zComponent project
name
Jazz component
name
Specifies to which
Jazz Component a
zComponent project
should belong.
zComponent projects
that do not match
project name rules
specified in the
mapping file cannot
be imported.
P1, 2
Fully qualified
member name (not
including HLQ)
zComponent project Specifies to which
name [:zFolder name] zComponent project
a PDS should be
imported. You can
use ″wildcards″ (*) in
the key to specify
multiple members to
put into the same
zComponent project.
Any member that
does not match a
member name rule
specified in the
mapping file cannot
be imported.
L1
Fully qualified
member name (not
including HLQ)
Language definition
name
Specifies a language
definition to associate
with imported
members. Remember:
The language
definition must
already exist in the
project area. You can
use wildcards in the
key, indicated by an
asterisk (*), to specify
multiple members to
associate with a
language definition.
Important:
1. For the P and L identifiers, members are referenced using pattern-matching
strings that consist of the name of the PDS (without the HLQ), followed by a
period, followed by the member name. For example, member HELLO in PDS
SMITH.TEST.COBOL would be matched by the pattern TEST.COBOL.HELLO. The
pattern TEST.COBOL.* would match any members in the data set named
SMITH.TEST.COBOL.
Chapter 8. User scenarios for Rational Team Concert for System z
49
2. For the P identifier, by default, zimport imports members from a PDS to the
specified zComponent project into a zFolder with the same name as the PDS.
Optionally, you can change the name of the zFolder by adding a colon (:) after
the name of the zComponent project, followed by a zFolder name of your
choosing. For example, if you want to import all members from a PDS named
MORT.BLD.TEST to zComponent project MortgageApp under a zFolder named
MORT.BLD, the mapping file rule should be
P:MORT.BLD.TEST.*=MortgageApp:MORT.BLD.
3. You can also make back references in any line in the mapping file by using
parentheses in the key and %n in the value. For example, if you want to import
all the members in PDSs named MORT.*.BLD.TEST to a zComponent project
named MORTApp in zFolders named whatever is between MORT. and .BLD,
you could write the rule as P:(MORT).(*).BLD.TEST.*=%1App:%2.
An overview of creating a mapping file to use with the
Rational Team Concert for System z mass import tool
Before you can use the zimport command to perform a Rational Team Concert for
System z mass import, you must create a mapping file to define a list of rules that
tell the zimport command three things it needs to know to run successfully:
v which zComponent project and zFolder to put members of a partitioned data set
(PDS) into
v which Jazz component should contain that zComponent project
v which language definition to associate with the PDS members
Note: You do not have to associate a language definition with imported
members. This is an optional step.
For a list and descriptions of these rules, see “Rational Team Concert for System z
mass import tool: mapping file rule restrictions.”
Rational Team Concert for System z mass import tool:
mapping file rule restrictions
The rules in a mapping file are line-delimited, and the following restrictions apply
to mapping file rules:
v The mass import tool ignores blank lines.
v The mass import tool ignores lines that begin with the pound sign (#).
v Lines must adhere to the following format, where rule-type must either be the
character P, the character C, or the character L:
rule-type:key=value
– P indicates that the rule maps a qualified member name to the zComponent
project and, optionally, the zFolder where it should be placed.
Note: After the P rule, you have the option of specifying a zFolder to which
to import the member. To do this, add [:zFolder] after the P rule, but replace
zFolder with the name of the folder where you want to import the member.
Such a line might look similar to this:
P:TEST.COBOL.HELLO=MyProject:MyFolder
Attention: The qualification of the member name in the P rule does not
include the high-level qualifier (HLQ).
– C indicates that the rule maps a zComponent project to the Jazz component
that should contain it.
50
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Important: If the zComponent project into which members are imported does
not match any C rules, those members will not be imported.
– L indicates that the rule maps a qualified member name (without a high-level
qualifier) to the name of a language definition to associate with it.
Important: The specified language definition must already exist in the project
area that you specified on the command line. Specifying language definitions
for imported members is optional, and members without an associated
language definition can still be imported.
The contents of a mapping file might look like the following example:
# Member to zComponent project mappings
# Specify the zComponent project and, optionally, the zFolder which will
# contain the imported members.
#
# Format:
# P:<member>=<zComponent project>[:<zFolder>]
P:MORTGAGE.*.(*).*=MortgageApp:%1
P:ALL.COBOL.*CALC=CalcApp:CobolSrc
P:ALL.COBOL.ATM*=ATMApp:CobolSrc
# zComponent project to Jazz Component mappings
# Specify the Jazz Component that each zComponent project will be shared to.
#
# Format:
# C:<zComponent project>=<Jazz Component>
C:MortgageApp=Mortgage
C:CalcApp=Sample Applications
C:ATMApp=Sample Applications
# Member to Language Definition mappings
# Optionally specify the Language Definition to associate with imported members.
#
# Format:
# L:<member>=<Language Definition name>
L:*.COBOL.*=COBOL
L:*.JCL.*=JCL
If you run the zimport command for a PDS named SMITH.MORTGAGE.BLD.COBOL,
indicate SMITH as the --hlq, and specify the mapping file rule
P:MORTGAGE.BLD.COBOL.*=MortgageApp, all of the contents of
SMITH.MORTGAGE.BLD.COBOL would be imported into a zComponent project named
MortgageApp, inside a zFolder named MORTGAGE.BLD.COBOL. If, instead, you
specify mapping file rule P:MORTGAGE.BLD.COBOL.*=MortgageApp:CobolSRC, the
zFolder would be named CobolSRC.
Scenario 4: Using the Rational Build Agent to execute
command-driven builds
This scenario introduces you to how Rational Team Concert for System z uses the
Rational Build Agent for building native z/OS artifacts using existing commands.
This scenario does not depend on the Job Monitor or other libraries. This scenario
requires the successful installation of FMID HAHD200 (Rational Build Agent) as
part of the SMP/E installation. If you want to use the example REXX exec from
this scenario, it is installed as part of FMID HAHB200 (Build System Toolkit for
System z).
In this beta, the agent is unchanged from the existing Rational Build Agent. The
new function provided by Rational Team Concert for System z enables you to
Chapter 8. User scenarios for Rational Team Concert for System z
51
define and run builds that use the Rational Build Agent. The Jazz Build Engine is
still supported by Rational Team Concert for System z.
Defining and running a build using the Rational Build Agent
Before you begin
You must already have created a project area in Rational Team Concert for System
z.
About this task
This task is relevant if you are adding a build definition to your project area and
you want to use the Rational Build Agent. The scenario assumes you have an
existing project area and you want to add a build definition that uses the Rational
Build Agent. This scenario uses a REXX exec to compile sample COBOL members.
You can use other commands if you prefer.
To complete the user scenario, follow these steps:
1. If you have not already started the Rational Build Agent, start it now using the
bfagent -s command as mentioned previously in the section on setting up the
Rational Build Agent.
Important: Commands executed through the Rational Build Agent run with the
authority of the user that starts the agent.
2. Locate the BLZCSAMP member in hlq.SBLZSAMP, where hlq is the high-level
qualifier used during the SMP/E installation of Rational Team Concert for
System z. Note that this member is actually installed as part of the installation
of FMID HAHB200.. The BLZCSAMP member provides a sample REXX exec to
complete a COBOL compilation. Review the comments in this sample member
to understand the parameters and possible customization needed for your
environment.
Setting up and running a build definition
1. In the Team Artifacts view, expand the project area folder in which you want to
create a build definition.
2. Right-click Builds → New Build Definition.
3. In the New Build Definition window, deselect Pre Build Command line and
Post Build Command line, select Create a new build, then click Next.
4. In the General Information window, enter a build definition ID and a brief
description of the build definition.
Important: Select Rational Build Agent from the Available Templates menu.
Click Next.
5. In the Additional Configuration window, select both General, Properties, and
Rational Build Agent, and then click Finish. The build definition you created
opens in the Build Definition editor.
Performing a connection test with the Rational Build Agent
1. Click the Build Agent tab you created in the previous steps.
2. Enter the following information to connect to Build Forge:
Hostname
The name of the system that uses the Rational Build Agent.
52
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Port
The port that communicates with Rational Build Agent. The default is port
5555.
User name
The name of the user who is connecting to the Rational Build Agent.
Note: This user name is used to authenticate the connection to the system,
it does not have to be the same user name that started the agent.
Password
The password for the given user name.
Confirm Password
Enter again the password for the given user name.
3. Click Test Connection. The results of the connection test are displayed in the
Rational Build Agent Connection Test Results box.
Example
Defining a command block for the Rational Build Agent to run
1. Click the Build Agent Command Line tab.
2. In the Command field, enter a process command to send to the Rational Build
Agent.
3. In the Working directory field, enter the working directory you want the
invoked process to use.
4. Click Save to save the build definition.
Tip: The first time you save a build definition, a new build engine called
″RationalBuildAgent″ will be defined for the project area. Make sure that the
″RationalBuildAgent″ is the selected build engine on the General tab of the
build definition.
Chapter 8. User scenarios for Rational Team Concert for System z
53
Example
To run the provided sample, you can set up a command block similar to the
following example:
Requesting a build
1. In the Team Artifacts view, right-click the build definition, then select Request
build. Alternately, you can click the Request Build icon in the upper right
corner of the Build Definition window. The Request Build window opens.
2. Click Submit.
The Builds window opens.
Tip: To monitor the progress of your build while it is processing, click the
refresh icon (circular arrows).
54
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Example
Checking the build results
1. After the build is complete, double-click your build in the Builds tab to view
the build results.
2. In the Contribution Summary section, click the log to view the Logs tab.
3. Select the log and click Open to display the detailed build results, including
Rational Build Agent information and the results of the command block you
entered.
Chapter 8. User scenarios for Rational Team Concert for System z
55
Scenario 5: Using the Rational Build Agent and Job Monitor to execute
builds using JCL
The purpose of this user scenario is to show how to use the Rational Team Concert
for System z components to submit a build for native z/OS artifacts and obtain
results using the Job Monitor. The first section of this scenario describes the
customization of the Job Monitor component, followed by an example of using
Rational Team Concert for System z and the Rational Build Agent to submit JCL
for a z/OS build. This scenario depends on the successful SMP/E installation of
FMID HAHC200 (Job Monitor) and HAHD200 (Rational Build Agent).
Note: If you have an existing instance of the Rational Developer for System z Job
Monitor on your system, it can be used for Job Monitoring in this scenario.
Job Monitor customization
Before you begin
The Job Monitor component depends on the SMP/E installation of FMID
HAHC200. You will need the assistance of a security administrator and a TCP/IP
administrator to complete this customization task, which requires the following
resources and special customization tasks:
v APF authorized data set
v Various security software updates
v TCP/IP port for internal communication
About this task
In order to verify the installation and to start using Job Monitor at your site, you
must perform the following tasks. Unless otherwise indicated, all tasks are
mandatory.
1. Define an APF authorized data set. For details see “PARMLIB changes.”
2. Create a started task procedure. For details see “PROCLIB changes” on page 57.
3. Customize the Job Monitor configuration files. For details see “BLZJCNFG, Job
Monitor configuration file” on page 57.
4. Update security definitions. For details see Appendix F, “Job Monitor security,”
on page 101.
PARMLIB changes
Refer to MVS™ Initialization and Tuning Reference (SA22-7592) for more information
on the PARMLIB definitions listed below. Refer to MVS System Commands
(SA22-7627) for more information on the sample console commands.
APF authorizations in PROGxx
In order for Job Monitor to access JES spool files, module BLZJMON in the
hlq.SBLZAUTH load library, where hlq is the high-level qualifier used during SMP/E
installation, and the Language Environment® (LE) runtime libraries
(CEE.SCEERUN*)must be APF authorized.
APF authorizations are defined in SYS1.PARMLIB(PROGxx), if your site followed
IBM® recommendations.
56
Rational Team Concert for System z Beta Program: Installation and User’s Guide
APF authorizations can be set dynamically (until the next IPL) with the following
console commands, where volser is the volume on which the data set resides if it
is not SMS managed:
v SETPROG APF,ADD,DSN=hlq.SBLZAUTH,SMS
v SETPROG APF,ADD,DSN=CEE.SCEERUN,VOL=volser
v SETPROG APF,ADD,DSN=CEE.SCEERUN2,VOL=volser
PROCLIB changes
The started task listed below must reside in a system procedure library defined to
your JES subsystem. In the instructions below, the IBM default procedure library,
SYS1.PROCLIB, is used.
Customize the sample started task member hlq.SBLZSAMP(BLZJJCL), as described
within the member, and copy it to SYS1.PROCLIB. As shown in the code sample
below, you have to provide the following:
v The high-level qualifier of the (authorized) load library, default BLZ. Replace BLZ
with your hlq.
v The Job Monitor configuration file, default hlq.SBLZSAMP(BLZJCNFG).
//*
//* JOB MONITOR
//*
//JMON
PROC PRM=,
* PRM='-TV' TO START TRACING
//
LEPRM='RPTOPTS(ON)',
//
HLQ=BLZ,
//
CFG=BLZ.SBLZSAMP(BLZJCNFG)
//*
//JMON
EXEC PGM=BLZJMON,REGION=0M,TIME=NOLIMIT,
//
PARM=('&LEPRM,ENVAR("_CEE_ENVFILE=DD:ENVIRON")/&PRM')
//STEPLIB DD DISP=SHR,DSN=&HLQ..SBLZAUTH
//ENVIRON DD DISP=SHR,DSN=&CFG
//SYSPRINT DD SYSOUT=*
//SYSOUT
DD SYSOUT=*
//
PEND
//*
BLZJCNFG, Job Monitor configuration file
Job Monitor provides JES related services. The behavior of Job Monitor can be
controlled with the definitions in BLZJCNFG.
Customize the sample Job Monitor configuration member hlq.SBLZSAMP(BLZJCNFG),
as shown in the following sample. Comment lines start with a pound sign (#),
when using a US code page. Data lines can only have a directive and its assigned
value, comments are not allowed on the same line.
Note: The BLZJMON started task must be restarted to pick up any changes you
make.
HOST_CODEPAGE=IBM-1047
SERV_PORT=6716
TZ=EST5EDT
#_BPXK_SETIBMOPT_TRANSPORT=TCPIP
#CODEPAGE=UTF-8
#CONCHAR=$
#CONSOLE_NAME=JMON
#GEN_CONSOLE_NAME=OFF
#LIMIT_COMMANDS=NOLIMIT
#LIMIT_VIEW=USERID
#LISTEN_QUEUE_LENGTH=5
#MAX_DATASETS=32
Chapter 8. User scenarios for Rational Team Concert for System z
57
#MAX_THREADS=200
#TIMEOUT=3600
#TIMEOUT_INTERVAL=1200
#SUBMITMETHOD=TSO
#TSO_TEMPLATE=BLZ.SBLZSAMP(BLZTSO)
HOST_CODEPAGE
The host code page. The default is IBM-1047. Change to match your host
code page.
SERV_PORT
The port number for Job Monitor host server. The default port is 6716.
Change as desired.
Note: Before selecting a port, verify that the port is available on your
system with the TSO commands NETSTAT and NETSTAT PORTL.
TZ
Time zone selector. The default is EST5EDT. The default time zone is UTC
+5 hours (Eastern Standard Time (EST) Eastern Daylight Savings Time
(EDT)). Change this to represent your time zone. Additional information
can be found in the UNIX System Services Command Reference (SA22-7802).
The following definitions are optional. If omitted, default values will be used as
specified below:
_BPXK_SETIBMOPT_TRANSPORT=<tcpip stack name>
Specifies the name of the TCPIP stack to be used. The default is TCPIP.
Uncomment and change to the requested TCPIP stack name, as defined in
the TCPIPJOBNAME statement in the related TCPIP.DATA.
Note: Coding a SYSTCPD DD statement in the server JCL does not set the
requested stack affinity.
CODEPAGE
The workstation code page. The default is UTF-8. The workstation code
page is set to UTF-8 and generally should not be changed. You might need
to uncomment the directive and change UTF-8 to match the workstation’s
code page if you have difficulty with NLS characters, such as the currency
symbol.
CONCHAR
Specifies the JES console command character. CONCHAR defaults to CONCHAR=$
for JES2, or CONCHAR=* for JES3. Uncomment and change to the requested
command character
CONSOLE_NAME
Specifies the name of the EMCS console used for issuing commands
against jobs (Hold, Release, Cancel and Purge). The default is JMON.
Uncomment and change to the desired console name, using the guidelines
below.
v CONSOLE_NAME must be either a console name consisting of 2 to 8
alphanumeric characters, or ’&SYSUID’ (without quotes).
v If a console name is specified, a single console by that name is used for
all users. If the console by that name happens to be in use, then the
command issued by the client will fail.
v If &SYSUID is specified, the client user ID is used as the console name.
Thus a different console is used for each user. If the console by that
58
Rational Team Concert for System z Beta Program: Installation and User’s Guide
name happens to be in use (for example, the user is using the SDSF
ULOG), then the command issued by the client might fail, depending on
the GEN_CONSOLE_NAME setting.
No matter which console name is used, the user ID of the client requesting
the command is used as the LU of the console, leaving a trace in syslog
messages IEA630I and IEA631.
IEA630I OPERATOR console NOW ACTIVE,
SYSTEM=sysid, LU=id
IEA631I OPERATOR console NOW INACTIVE, SYSTEM=sysid, LU=id
GEN_CONSOLE_NAME
Enables or disables automatic generating of alternative console names. The
default is OFF. Uncomment and change to ON to enable alternative console
names.
This directive is only used when CONSOLE_NAME=&USERID and the user ID is
not available as console name.
If GEN_CONSOLE_NAME=ON, an alternative console name is generated by
appending a single numeric digit to the user ID. The digits 0 through 9 are
attempted. If no available console is found, the command issued by the
client fails.
If GEN_CONSOLE_NAME=OFF, the command issued by the client fails.
Note: The only valid settings are ON and OFF.
LIMIT_COMMANDS
Defines against which jobs the user can issue selected JES commands
(Show JCL, Hold, Release, Cancel, and Purge). The default
(LIMIT_COMMANDS=USERID) limits the commands to jobs owned by the user.
Uncomment this directive and specify LIMITED or NOLIMIT to allow the user
to issue commands against all spool files, if permitted by your security
product.
Table 2. LIMIT_COMMANDS command permission matrix
Job owner
LIMIT_COMMANDS
User
Other
USERID (default)
Allowed
Not allowed
LIMITED
Allowed
Allowed only if explicitly
permitted by security profiles
NOLIMIT
Allowed
Allowed if permitted by
security profiles or when the
JESSPOOL class is not active
Note: Note: The only valid settings are USERID, LIMITED, and NOLIMIT.
LIMIT_VIEW
Defines what output the user can view. The default (LIMIT_VIEW=NOLIMIT)
allows the user to view all JES output, if permitted by your security
product. Uncomment this directive and specify USERID to limit the view to
output owned by the user.
Note: The only valid settings are USERID and NOLIMIT.
LISTEN_QUEUE_LENGTH
The TCP/IP listen queue length. The default is 5. Do not change unless
directed to do so by the IBM support center.
Chapter 8. User scenarios for Rational Team Concert for System z
59
LISTEN_QUEUE_LENGTH
The TCP/IP listen queue length. The default is 5. Do not change unless
directed to do so by the IBM support center.
MAX_DATASETS
The maximum number of spooled output data sets that Job Monitor will
return to the client (for example, SYSOUT, SYSPRINT, SYS00001, and so on).
The default is 32. The maximum value is 2147483647.
MAX_THREADS
Maximum number of users that can be using one Job Monitor at a time.
The default is 200. The maximum value is 2147483647. Increasing this
number may require you to increase the size of the Job Monitor address
space.
TIMEOUT
The length of time, in seconds, before a thread is killed due to lack of
interaction with the client. The default is 3600 (1 hour). The maximum
value is 2147483647. TIMEOUT=0 disables the function.
TIMEOUT_INTERVAL
The number of seconds between timeout checks. The default is 1200. The
maximum value is 2147483647.
SUBMITMETHOD=TSO
Submit jobs through TSO. The default (SUBMITMETHOD=JES) submits jobs
directly into JES. Uncomment this directive and specify TSO to submit the
job through TSO SUBMIT command. This method allows TSO exits to be
invoked; however, it has a performance drawback and for that reason it is
not recommended.
Note:
1. The only valid settings are TSO and JES.
2. If SUBMITMETHOD=TSO is specified, then TSO_TEMPLATE must also be
defined.
TSO_TEMPLATE
Wrapper JCL for submitting the job through TSO. The default value is
hlq.SBLZSAMP(BLZTSO). This statement refers to the fully qualified member
name of the JCL to be used as a wrapper for the TSO submit. See the
SUBMITMETHOD statement for more information.
Note:
1. A sample wrapper job is provided in BLZ.SBLZSAMP(BLZTSO). Refer to
this member for more information on the customization needed.
2. TSO_TEMPLATE has no effect unless SUBMITMETHOD=TSO is also specified.
Submitting JCL inside the build command
The Rational Build Agent allows you to submit JCL to JES. An agent running on
z/OS can monitor and report build results by communicating with an instance of
the Job Monitor running on the same z/OS system.
Rational Build Agent supports JCL submission through the .submitJCL command.
This scenario will demonstrate how to submit JCL contained in a build system data
set, as well as how to provide the JCL within a Build Definition.
60
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Prerequisites
The Rational Build Agent must be running on the target build system before
beginning this scenario. The Job Monitor must also be running on the same build
system as the agent.
In order to communicate with the Job Monitor, the Build Agent must have the
jcl_submit_user and job_monitor_port parameters set to appropriate values in the
bfagent.conf configuration file.
The jcl_submit_user parameter is used to provide the credentials that will be used
by Job Monitor when submitting jobs to JES. Add the following line to the
bfagent.conf file:
jcl_submit_user userid:encrypted_password
where userid is the system id of the user for submitting jobs, and
encrypted_password is an encrypted version of that user’s password. The encrypted
form of the password can be found by executing the following line at the USS
command prompt:
bfagent –e password
where password is the password to be encrypted. The command will print a text
string containing the encrypted value. The result will be similar to the following:
050405aaeb43166a00f763716b989f26651e2448ce309b72680a
The job_monitor_port parameter is used to specify the port to which Job Monitor
is listening. Add the following line to the bfagent.conf file:
job_monitor_port XXXX
where XXXX is the Job Monitor port. This port should match your SERV_PORT
setting for Job Monitor, which is set to 6716 in the hlq.SBLZSAMP(BLZJNCFG) file.
If an instance of the Rational Build Agent is running, you must restart the agent
prior to continuing with this scenario.
Submitting JCL Contained in a Build System Data Set
JCL contained in a data set on the target build system can be submitting using the
Rational Build Agent. The Job Monitor will submit the job to JES and report the
results of the request. Build results can then be viewed through the Rational Team
Concert for System z client.
1. Create a data set member containing the following JCL. Note that this job
contains inline COBOL source code that will be compiled and link-edited.
Customize the data set names contained in this job to values appropriate to
your target system.
//HELLO
JOB ,NOTIFY=DEARTH
//*
//* COBOL COMPILATION
//*
//COBOL
EXEC PGM=IGYCRCTL,PARM='NODECK,OBJECT,LIB'
//STEPLIB DD DSN=COBOL.V4R1M0.SIGYCOMP,DISP=SHR
//SYSIN
DD *
IDENTIFICATION DIVISION.
PROGRAM-ID. HELLO.
PROCEDURE DIVISION.
MAIN.
DISPLAY 'HELLO, RTCZ.'.
Chapter 8. User scenarios for Rational Team Concert for System z
61
STOP RUN.
/*
//SYSLIN
DD DSN=DEARTH.SAMPLE.OBJ(HELLO),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUT1
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//*
//LINKEDIT EXEC PGM=IEWBLINK,PARM='LIST,LET,MAP,XREF,REUS,RENT'
//SYSLIN
DD *
INCLUDE SYSLIB(HELLO)
NAME HELLO(R)
/*
//SYSLIB
DD DSN=DEARTH.SAMPLE.OBJ,DISP=SHR
//
DD DSN=CEE.SCEELKED,DISP=SHR
//SYSLMOD DD DSN=DEARTH.SAMPLE.LOAD(HELLO),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUT1
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//*
2. Create a Build Definition using Rational Team Concert for System z client.
a. In the Team Artifacts view, right click on the Build Engines icon and select
New Build Engine.
b. Specify the Build Engine ID as RationalBuildAgent, choose a Project or
Team Area, and click Save.
c. In the Team Artifacts view, right click on the Builds icon and select New
Build Definition.
d. Click Next.
e. Specify a Build Definition ID and select Rational Build Agent as the build
template.
f. Click Next.
g. Clear the Pre Build Command line checkbox and click Next.
h. Clear the Post Build Command line checkbox and click Finish.
i. On the Overview tab, select RationalBuildAgent as the Supporting Build
Engine.
j. The build agent tab should contain the following values:
1) Hostname: Your build machine’s IP address or hostname.
2) Port: 5555, or the port number you configured in your bfagent.conf file.
3) User name: the z/OS RACF user ID of the builder on the target build
machine.
4) Password and Confirm Password: The builder’s z/OS RACF password.
k. Specify the following values on the Build Command line tab:
1) Enter this command line into the Command input box. Replace
<PDS(MEMBER)> with the data set you created in step 1. Note that the
command begins with a leading period.
.submitJCL <PDS(MEMBER)>
2) Set working directory to a fully qualified USS path on the build
machine. This directory will be used as a work directory by the build
process. It must exist prior to requesting a build.
l. Click Save.
m. Request a build.
62
Rational Team Concert for System z Beta Program: Installation and User’s Guide
1) In the Team Artifacts view, select the build definition, right click, and
select Request Build.
2) Click Submit.
3) If a dialog stating that the build engine does not appear to be
processing requests is displayed, click OK to submit the request.
4) In the Builds view, check the status periodically. Click Update to refresh
the view.
n. When the build is completed, double-click the build result to view the build
log.
Providing JCL through a Rational Build Agent step command
You can also specify JCL inline as part of a Rational Build Agent step command.
This job submission method allows you to use substitution parameters to specify
values such as the HLQ of the source data sets. The parameters will be replaced
with values specified on the Build Definition properties tab prior to job
submission.
1. Ensure that you have data sets defined that will contain the object decks and
load modules that result from COBOL compilation and link editing.
2. Verify that you have defined a RationalBuildAgent build engine. If you have
not, follow steps 2a and 2b from the section titled Submitting JCL Contained in a
Build System Data Set.
3. Create a Build Definition using the Rational Team Concert for System z client.
a. In the Team Artifacts view, right-click the Builds icon and select New Build
Definition.
b. Click Next.
c. Specify a Build Definition ID and select Rational Build Agent as the build
template.
d. Click Next.
e. Clear the Pre Build Command line checkbox and click Next.
f. Clear the Post Build Command line checkbox and click Finish.
g. On the Overview tab, select RationalBuildAgent as the Supporting Build
Engine.
h. On the Properties tab, create a new property called HLQ. This property will
be used throughout the JCL to specify the high-level qualifier to be used for
source and output data sets on the target build system.
1) Click the Add button.
2) Select String as the property type and click OK.
3) Specify HLQ as the name.
4) Enter the HLQ of the target data sets as the value and click OK.
i. The build agent tab should contain the following values:
1) Hostname: Your build machine’s IP address or hostname.
2) Port: 5555, or the port number you configured in your bfagent.conf file.
3) User name: the z/OS RACF user ID of the builder on the target build
machine.
4) Password and Confirm Password: The builder’s z/OS RACF password.
j. j. Specify the following values on the Build Command line tab:
1) Enter this command line into the Command input box. Using the option
–c with the .submitJCL command allows you to specify JCL as part of
the command. Any occurrence of ${HLQ} will be replaced with the value
specified on the Properties tab of the Build Definition. Note that the
Chapter 8. User scenarios for Rational Team Concert for System z
63
command begins with a leading period. Be sure to verify that DD
statements in the JCL contain values appropriate for your target system.
. .submitJCL -c
//HELLO
JOB ,NOTIFY=${HLQ}
/*JOBPARM S=*
// SET HLQ=\'${HLQ}\'
//*
//* COBOL COMPILATION
//*
//COBOL
EXEC PGM=IGYCRCTL,PARM='NODECK,OBJECT,LIB'
//STEPLIB DD DSN=COBOL.V4R1M0.SIGYCOMP,DISP=SHR
//SYSIN
DD *
IDENTIFICATION DIVISION.
PROGRAM-ID. HELLO.
PROCEDURE DIVISION.
MAIN.
DISPLAY 'HELLO, RTCZ.'.
STOP RUN.
/*
//SYSLIN
DD DSN=&HLQ..SAMPLE.OBJ(HELLO),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUT1
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//*
//* LINKEDIT
//*
//LINKEDIT EXEC
PGM=IEWBLINK,PARM='LIST,LET,MAP,XREF,REUS,RENT'
//SYSLIN
DD *
INCLUDE SYSLIB(HELLO)
NAME HELLO(R)
/*
//SYSLIB
DD DSN=&HLQ..SAMPLE.OBJ,DISP=SHR
//
DD DSN=CEE.SCEELKED,DISP=SHR
//SYSLMOD DD DSN=&HLQ..SAMPLE.LOAD(HELLO),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUT1
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//*
2) Set the working directory to a fully qualified USS path on the build
machine. This directory will be used as a work directory by the build
process. It must exist prior to requesting a build.
k. Click Save.
l. Request a build:
1) In the Team Artifacts view, select the build definition, right-click, and
select Request Build.
2) Click Submit.
3) If a dialog stating that the build engine does not appear to be processing
requests is displayed, click OK to submit the request.
4) In the Builds view, check the status periodically. Click Update to refresh
the view.
m. When the build is completed, double-click the build result to view the
build log.
64
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Scenario 6: Using the Rational Build Agent and Antz build extensions
to compile a COBOL application
This scenario depends on the successful SMP/E installation of FMIDs HAHB200
(Rational Team Concert for System z Build Toolkit) and HAHD200 (Rational Build
Agent).
Apache Ant is a Java based build tool similar to the Unix make utility. Ant allows
builders to describe the steps required to build an application using an XML based
script. Rational Team Concert for System z provides a set of extensions to Apache
Ant called “Antz“ that makes it possible to build z/OS based applications using
Ant.
This scenario uses Antz to show you how to build a simple “Hello World!”
COBOL application on a z/OS build machine. You will learn to use the Rational
Team Concert for System z Data Set Definition, Translator, and Language
Definition components to define your build environment. You will then create a
shared zComponent project containing your COBOL source code and a build.xml
file that defines the Antz build process.
Preparing your environment
You must prepare your development environment prior to defining builds using
Antz. This scenario assumes that you have performed the following tasks:
v Prepared a Jazz Team Server. See Chapter 3, “Installing and configuring Rational
Team Concert for System z,” on page 5 for information regarding server
installation and configuration.
v Created a Project Area
v Created a user to perform the builds. Edit the user and verify that it has the
following Client Access Licenses for Rational Team Concert:
– Contributor
– Developer
– Build System
v Modified the process configuration to enable the user to save Data Set
Definitions, Language Definitions, and Translators.
v Installed and configured a Rational Team Concert for System z client. The client
should have a repository connection defined for your Jazz Team Server and be
connected to your Project Area.
v The Jazz Build System should be installed on the z/OS system that performs
builds.
v The Rational Build Agent should be installed and configured on the z/OS
system that performs builds.
Notes:
1. The Rational Build Agent will be started with a shell script which is described
later in this scenario.
2. This scenario does not depend on the Job Monitor.
Chapter 8. User scenarios for Rational Team Concert for System z
65
Configuring the Rational Build Agent shell script
The Jazz Build System contains a sample script named startbfa.sh that can be used
to start the Rational Build Agent on the build machine. The script can be found in
the pathPrefix/usr/lpp/jazz/buildsystem/buildtoolkit/examples/startbfa
directory, where pathPrefix is any prefix specified during the SMP/E installation.
This script is required for starting the Rational Build Agent for Beta 3 to specify
credentials for the Agent to connect to the Jazz Team Server for System z, as well
as to provide access to libraries needed for Antz and native compilation. You can
copy this script to a work directory to modify and execute if necessary.
The script must be tailored to suit your environment. Replace the variable strings
in the sample script as described in the following table:
Table 3. Sample script variable strings
Variable
Description
@[email protected]
Directory path to prefix the jazz directory.
Note: This is the prefix to the jazz directory,
so your prefix should include any prefix
specified as part of the SMP/E installation
as well as /usr/lpp.
@[email protected]
Directory path to the IBM 31 bit SDK for
z/OS Java 2 Technology Edition V5
@[email protected]
The jazz user id of the builder
@[email protected]
The Jazz Password File as defined by the
BLZBPASS Job. See Appendix A, “Running
the Jazz Build Engine on z/OS,” on page 77
for information on how to run the
BLZBPASS Job.
@[email protected]
STEPLIB DD to use in your z/OS build. For
example, SYS1.LINKLIB:CEE.SCEERUN
@[email protected]
Directory path to the Rational Build Agent
executable directory
@[email protected]
Directory path to the Rational Build Agent
configuration file directory
Run the startbfa.sh script when you are ready for the Rational Build Agent to be
started and accept build requests.
Configuring the Rational Build Agent Service
By default, the Rational Build Agent Service on the Jazz Team Server checks for
build status every 60 seconds. If you’d like to check status more frequently, you
can change this default value.
1. Use your web browser to log into the Jazz Build Server at https://
<yourserver>:9443/jazz.
2. Click Server.
3. Under Configuration, select Advanced Properties.
4. Under the Build Agent, change the value of the Build Agent Loop Task
property from 60 to 10. This causes the Rational Build Agent Service to poll for
build status every 10 seconds.
5. Click Save.
66
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Creating data set definitions
About this task
A data set definition is a new Jazz model object that will be stored in the Rational
Team Concert for System z repository. It is a container for information regarding a
data set on the z/OS system. All data sets referenced by a build process must have
a corresponding Data Set Definition. In this step, you will create the Data Set
Definitions required to build a simple “Hello World” application.
Create Data Set Definitions for each of the data sets that will be referenced by the
build process. The following table describes the Data Set Definitions that will be
required for this scenario.
Table 4. Required Data Set Definitions
Allocation
Parameters
Name
Type
Description
COBOL
Destination data set
for a zFolder
RECFM(F,B)
LRECL(80)
SPACE(1,1) CYL
Data set for COBOL
source files
LINK
Destination data set
for a zFolder
RECFM(F,B)
LRECL(80)
SPACE(1,1) CYL
Data set for link-edit
source files
OBJ
New data set used
for build
RECFM(F,B)
LRECL(80)
SPACE(1,1) CYL
Data set for object
decks
LOAD
New data set used
for build
RECFM(U) LRECL(0) Data set for load
SPACE(1,1) CYL
modules
TEMPFILE
Temporary data set
used for build
SPACE(5,5) TRACKS
UNIT(SYSALLDA)
IGYCRCTL
Existing data set
used for build
COBOL compiler
module
IEWBLINK
Existing data set
used for build
Link-editor module
SCEELKED
Existing data set
used for build
Data set containing
the link-edit stubs for
C/C++, PL/I,
COBOL, and Fortran
languages and
Language
Environmentprovided routines
Temporary data sets
required by the
COBOL compiler
1. Create a data definition that corresponds to the PDSE that will contain
COBOL source code on the build machine. Select the Data Set Definition icon
in Team Artifacts view, right click to show the context menu and click New
Data Set Definition. Name the data definition COBOL.
2. In the General section, specify the following parameters:
a. Usage: Destination data set for a zFolder This specifies that the new data
set definition corresponds to a zFolder contained within a zComponent
Project.
b. Data set Name: COBOL This is the name that will be used on the z/OS
system when this data set is created.
Chapter 8. User scenarios for Rational Team Concert for System z
67
3. For data set characteristics, specify the following parameters:
a. Space Units: Cylinders
b. Primary Quantity: 1
c. Secondary Quantity: 1
d. Directory Blocks: 0
4.
5.
6.
7.
e. Record Format: FB
f. Record Length: 80
g. Block Size: 0
Click Save.
Repeat steps 1 – 4 to create and save a new data set definition named LINK as
described in the table above.
Create a data definition named the data definition OBJ.
In the General section, specify the following parameters:
a. Usage: New data set used for build. This specifies that the new Data Set
Definition refers to an output data set that will be used by the build
process. In this scenario, the OBJ data set will be used to hold the object
decks produced by the COBOL compiler. If this data set does not exist, it
will be allocated during the build process.
b. Check Add data set prefix from build definition to data set name. This
indicates that this data set should be prefixed with the data set prefix
associated with the build request.
8. For data set characteristics, specify the following parameters:
a. Space Units: Cylinders
b. Primary Quantity: 1
c. Secondary Quantity: 1
d. Directory Blocks: 0
e. Record Format: FB
f. Record Length: 80
g. Block Size: 0
h. Data Set Type: Library(PDSE)
9. Create the Data Set Definition for the LOAD library named LOAD.
10. In the General section, specify the following parameters:
a. Usage: New data set used for build. This specifies that the new data set
Definition refers to an output data set that will be used by the build
process. In this scenario, the LOAD data set will be used to hold the load
module produced by the link-editor. If this data set does not exist, it will
be allocated during the build process.
b. Check Add data set prefix from build definition to data set name. This
indicates that this data set should be prefixed with the high-level qualifier
associated with the build request.
11. For data set characteristics, specify the following parameters:
a. Space Units: Cylinders
b. Primary Quantity: 1
c. Secondary Quantity: 1
d. Directory Blocks: 0
e. Record Format: U
f. Record Length: 0
68
Rational Team Concert for System z Beta Program: Installation and User’s Guide
g. Block Size: 32720 Block size must be larger than zero for beta 3. In the final
release, zero will be accepted as a valid value.
h. Data Set Type: Library(PDSE)
12. Create the Data Set Definition named TEMPFILE.
13. In the General section, specify the following parameters:
a. New Temporary data set used for build. This indicates that this data set
will be allocated as a temporary file to be used by the build process.
14. For data set characteristics, specify the following parameters:
a. Generic unit: SYSALLDA
b. Space units: Tracks
c. Primary quantity: 5
d. Secondary quantity: 5
e. Data set type: Unspecified
f. All other fields: Accept the default values.
15. Create the Data Set Definition named IGYCRCTL. This Data Set Definition
describes the characteristics of the IBM COBOL for z/OS compiler.
16. In the General section, specify the following parameters:
a. Usage: Existing data set used for build.
b. Data set name: The name of data set that contains the IGYCRCTL module.
For example, IGY.V4R1M0.SIGYCOMP
c. Member: IGYCRCTL
d. Uncheck Add data set prefix from build definition to data set name.
17. Create the Data Set Definition named IEWBLINK. This Data Set Definition
describes the IEWBLINK module that is used to bind a program and store it
in a program library.
18. In the General section, specify the following parameters:
a. Usage: Existing data set used for build.
b. Data set name: Keep it blank.
c. Member: IEWBLINK
d. Uncheck Add data set prefix from build definition to data set name.
19. Create the Data Set Definition named SCEELKED. This should be the name of
the data set on the build machine containing the COBOL and LE link edit
stubs (generally named CEE.SCEELKED).
20. In the General section, specify the following parameters:
a. Usage: Existing data set used for build.
b. Member: Blank
c. Uncheck Add data set prefix from build definition to data set name.
Creating translators
About this task
Translators are a new Jazz model object that will be stored in the Rational Team
Concert for System z repository. Translators describe an operation to be performed
on a file during a build. A set of Translators can be associated with a Language
Definition. During a build, the set of Translators associated with a Language
Definition will be iterated over and executed for each file associated with the
Language Definition.
Chapter 8. User scenarios for Rational Team Concert for System z
69
For this scenario, you will need two Translators; IGYCRCTL and IEWBLINK.
Creating the IGYCRCTL translator
About this task
The IGYCRCTL translator will be used to compile the COBOL program.
1. Expand the Language Definitions icon in the Team Artifacts view, select the
Translators icon, show the context menu and click New Translator. Name the
translator IGYCRCTL.
2. In the General section, specify the following parameters:
a. Data set definition: IGYCRCTL. This is the data set definition containing the
executable module to be used by this translator. Use Browse to select this
Data Set Definition from the list of definitions created in previous steps.
b. Default options: NODECK,OBJECT,LIB. These options correspond to the
PARM parameter field of the JCL EXEC statement.
c. DD names list: SYSLIN,,,SYSLIB,SYSIN,ANTPRINT
d. Maximum return code: 0
Setting up the IGYCRCTL DD allocations table:
About this task
The IGYCRCTL DD allocations table specifies the data set allocations expected by
the module associated with the translator. In this step, specify the following DD
allocations for use by the COBOL compiler.
1. Click Add next to the DD allocations table. In the dialog, enter the following
values:
a. DD name: SYSIN. This is the input COBOL source file.
b. Select Translator input.
2. Add a DD Allocation with the following values:
a. DD name: SYSLIN. This allocates the target object module data set.
b. Select Data set definition for Data set. This indicates that this data set
should be allocated using the characteristics specified in a Data Set
Definition.
c. Click Browse and select the OBJ Data Set Definition from the list.
d. Check Append member name to data set name. This tells the build process
to append the member name of the input data set to the data set name.
3. Create a DD allocation to be used by Antz to collect build output.
a. DD name: ANTPRINT
b. Check Data set definition for Data set.
c. Click Browse to select the TEMPFILE Data Set Definition.
4. Create DD allocations for the working data sets used by the COBOL compiler
during compilation.
a. Specify SYSUT1 as the DD name.
b. Check Data set definition for Data set.
c. Click Browse to select the TEMPFILE Data Set Definition.
d. Repeat steps a through c to create DD allocations for SYSUT2, SYSUT3,
SYSUT4, SYSUT5, SYSUT6, and SYSUT7.
70
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Creating the IEWBLINK translator
About this task
The IEWBLINK translator will be used to link-edit the “Hello World” module.
1. Expand the Language Definitions icon in the Team Artifacts view, select the
Translators icon, show the context menu and click New Translator. Name the
translator IEWBLINK.
2. In the General section, specify the following parameters:
a. Data Set Definition: IEWBLINK.
b. Default Options: LIST,LET,MAP,XREF,REUS,RENT.
c. DD names List: SYSLIN,,SYSLMOD,SYSLIB,,ANTPRINT
d. Maximum Return Code: 0
3. Set up the DD concatenation table. This table specifies concatenated data sets
that will be used by this translator.
a. Click Add next to the concatenations table.
b. Type SYSLIB in DD name.
c. Click Add.
d.
e.
f.
g.
h.
Select Data set definition: and click Browse.
Select OBJ and click OK.
Click OK on the Add data set definition panel.
Click Add.
Select SCEELKED and click OK.
i. Click OK on the Add data set definition panel.
j. Click OK on the Add DD concatenation panel.
Setting up the IEWBLINK DD allocations table:
About this task
To set up the IEWBLINK DD allocations table, complete the following steps:
1. Click Add next to the DD allocations table. In the dialog, enter the following
values:
a. DD name: SYSLIN
b. Select Translator input.
c. Click OK.
2. Click Add next to the DD allocations table. In the dialog, enter the following
values:
a. DD name: SYSLMOD.
b. Select Data set definition for Data set. This indicates that this data set
should be allocated using the characteristics specified in a Data Set
Definition.
c. Check Append member name to data set name. This tells the build process
to append the member name of the input data set to the data set name.
d. Click Browse and select LOAD from the list.
e. Click OK.
f. Click OK.
3. Click Add next to the DD allocations table. In the dialog, enter the following
values:
a. DD name: ANTPRINT
Chapter 8. User scenarios for Rational Team Concert for System z
71
b. Check Data set definition for Data set.
c. Click Browse to select TEMPFILE from the list.
d. Click OK.
4. Click Add next to the DD allocations table. In the dialog, enter the following
values:
a. DD name: SYSUT1
b. Check Data set definition for Data set.
c. Click Browse to select TEMPFILE from the list.
d. Click OK.
Creating language definitions
About this task
Language definitions are a new Jazz model object that will be stored in the
Rational Team Concert for System z repository. Each file to be built with the
Rational Team Concert for System z build process will have a language definition
associated with it.
For this scenario, you will define language definitions for COBOL compilation and
link-editing.
1. Select the Language Definitions icon in the Team Artifacts view, right click to
show the context menu, and click New Language Definition.
2. Specify the following parameters:
a. Name: COBOL.
b. Language: COBOL.
3. Click Add next to Translators.
4. Select Translator and click Browse.
5.
6.
7.
8.
9.
Select the IGYCRCTL translator.
Click OK on the Select a translator panel.
Click OK on the Add a translator panel.
Click Save.
Select the Language Definitions icon in the Team Artifacts view, right-click to
show the context menu, and click New Language Definition. This language
definition is for link-editing the program.
10. Specify the following parameters:
a. Name: LINKEDIT.
11. Click Add next to Translators.
12. Select Translator and click Browse.
13. Select the IEWBLINK translator.
14. Click OKon the Select a translator panel.
15. Click OKon the Add a translator panel.
16. Click Save.
Creating a shared zComponent project
About this task
Now that the build environment has been defined, you must now create and share
a zComponent project. A zComponent project is a specialized Eclipse project that
72
Rational Team Concert for System z Beta Program: Installation and User’s Guide
contains z/OS artifacts (source files, link edit files, etc.) and build metadata used
when performing builds on a z/OS system.
In this step, you will create a zComponent project to contain your COBOL source
code and share the project with your team.
1. Click Window > Open Perspective > Other from the main menu bar.
2. Select Resource and click OK.
3. Select File > New > Project from the main menu bar.
4. Select zComponent > zComponent Project and click Next.
5. Specify your project name and click Finish.
6. Select the created project in Project Explorer, right click to show the context
menu and select Team > Share Project.
7. Select the default component for the workspace and click Finish.
Adding System z build containers and associating them with
data set definitions
About this task
The zComponent project can be thought of as a collection of z/OS data sets.
zFolders are used to represent the data sets in your project. Perform the following
steps to create the zFolders required for this scenario.
1. Expand the project in Project Explorer.
2. Select the zOSsrc folder, right-click to show the context menu and click New >
Other > zFolder.
3. Specify COBOL as the zFolder name.
4. Select the COBOL Data Set Definition from the drop down selection box for
Data Set Definition. This associates the zFolder with a data set definition. When
this zFolder is processed by the Antz build, the values specified in the data set
definition will be used to allocate the zFolder’s corresponding z/OS data set.
5. Click Finish.
6. Follow steps 1 through 6 to create the LINK zFolder and associate it with the
LINK data set definition.
Adding System z build artifacts and associating them with
language definitions
About this task
You are now ready to define the artifacts required by this project. You will create a
COBOL source file and a file containing the bind instructions for the link editor.
You will also associate these resources with language definitions.
1. Select the COBOL folder, right-click to show the context menu and click New
> Other > zFolder.
2. Specify HELLO.cbl as the zFile name.
3. Select the COBOL Language Definition from the drop down selection box for
Language Definition.
4. Click Finish.
5. Double-click the created HELLO.cbl icon.
6. Type the following in the source editor and click File > Save. You can cut and
paste from the following example. Note that the first character should start
on the 8th column.
Chapter 8. User scenarios for Rational Team Concert for System z
73
IDENTIFICATION DIVISION.
PROGRAM-ID. HELLO.
PROCEDURE DIVISION.
MAIN.
DISPLAY 'Hello, world.'.
STOP RUN.
7. Select the LINK folder, right click to show the context menu and select New >
Other > zFile.
8. Specify HELLO.lnk as the zFile name.
9. Select the LINKEDIT language definition from the drop down selection box
for language definition.
10. Click Finish.
11. Double-click the created HELLO.lnk icon.
12. Type the following in the source editor and click File > Save. You can cut and
paste from the following example. Note that the first character should start
on the 2nd column.
INCLUDE SYSLIB(HELLO)
NAME HELLO(R)
13. Switch to the Work Items perspective.
14. Open the Pending Changes view. Check in and deliver all changes.
Creating a new build definition
About this task
Rational Team Concert for System z provides a new build definition template
named Antz – Rational Build Agent. This template allows you to define an
Ant-based build for use on System z using the Rational Build Agent.
1. In the Team Artifacts view, right click on the Builds icon and select New Build
Definition.
2. Click Next to create a new build.
3. Specify a Build Definition ID and select the Antz - Rational Build Agent
template.
4. Click Next.
5. Check Jazz Source Control - zOS. This specifies that you want to use the
Rational Team Concert for System z file agent to extract the files from the
repository and place them on the target build system.
6. Click Next.
7. Check Job Output Publishing. This option enables translator output reporting,
such as SYSPRINT, for this build definition.
8. Click Finish.
Using the Build Definition Editor
About this task
In the Build Definition Editor, do the following to configure this build definition:
1. On the Overview tab, check RationalBuildAgent for the Supported Build
Engines value.
2. The Build Agent tab should contain the following values:
a. Hostname: Your build machine’s IP address or hostname
b. Port: 5555 or the port number you configured in your bfagent.conf file
74
Rational Team Concert for System z Beta Program: Installation and User’s Guide
c. User name: The z/OS RACF user ID of the builder on the target build
machine.
d. Password and Confirm Password: The builder’s z/OS RACF password
3. When the Build Agent tab has been configured, click Test Connection to test
the connection to your build agent. If the connection was successful, you will
see the results similar to the following:
Message: Socket created successfully.
Authentication Pass.
Platform: os/390 19.00 03
Version: 7.1.2.0-0-0003
PingResult: PingOk
ExitStatus: 0
4. On the Job Output Publishing tab, ensure that Publish job output logs is
selected.
5. On Jazz Source Control - zOS, set the following values:
a. Build Workspace: Click Select to select the repository workspace to be built.
b. Load directory: Specify an absolute path in USS to be used to store
non-MVS build artifacts such as the Antz build.xml file. The user id
associated with the builder must have read/write/execute permissions on
this directory.
c. Data set prefix: Specify the prefix to be prepended to managed data sets.
For example, if “BUILDER TEST” was specified as the data set prefix, the
data set BUILDER.TEST.COBOL would be allocated for the COBOL zFolder
associated with the COBOL Data Set Definition in previous steps.
6. The Build File field on the Antz tab should be set to the absolute USS path of
the Antz build file. If you want to use the build.xml file contained in the
zComponent project you created previously, the path will be <load
directory>/<project directory>/build.xml. If you named the zComponent
project DEMO, the path to the build file could be given as
${teamz.scm.fetchDestination}/DEMO/build.xml. Note that
${teamz.scm.fetchDestination} is a property whose value points to the directory
specified in the Load directory field of the Jazz Source Control - zOS tab.
7. Click Save.
Requesting a build
About this task
You have now successfully defined all of the pieces needed to complete this
scenario. To request a build, perform the following steps:
1. In the Team Artifacts view, select your build definition, right-click to show the
context menu , and select Request Build.
2. Click Submit on the Request Build panel.
3. If a warning dialog stating that the build engine does not appear to be
processing requests is displayed, click OK to submit the request.
4. In the Builds view, check the status of your build periodically. Click Update to
refresh the status view.
5. When the build is completed, double-click the build result.
6. Go to the Logs tab.
7. Double-click the log file. The Logs tab should contain the following files:
a. Two ANTPRINT.log files. One file contains the output from the COBOL
compiler. Another file contains the output from the link-editor.
Chapter 8. User scenarios for Rational Team Concert for System z
75
b. build-XXXXXXXXXXXXXX.log This file contains the Rational Build Agent
Service build log.
8. Look at the last lines of the Rational Build Agent Service log. If you see a
Status:OK message, you have successfully completed this scenario.
9. The Downloads tab of the build results should contain the following files:
a. build.properties A properties file containing all properties and their values
used for the execution of this Antz build.
b. buildableFiles.xml An XML file containing information about each file that
was processed by the Antz build. Only those files associated with a
language definition are included in this list.
c. FAOperationList.xml An XML file containing operations that were requested
of the File Agent during this build.
d. fetchedFiles.xml An XML file containing information about each file that
was extracted from the repository during this build by the file agent.
e. macrodefs.xml An XML file containing Ant macros that were generated for
use by the build. The contents of these macros are created based on values
specified in language definitions associated with files processed by this
build.
76
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Appendix A. Running the Jazz Build Engine on z/OS
In addition to the Rational Build Agent, you can also run the Jazz Build Engine
with the Rational Team Concert for System z beta on z/OS, Windows, or Linux.
Setting up the Jazz Build Engine is optional. Complete these steps if you decide to
run the Jazz Build Engine on z/OS. These steps are only required if you decide to
run builds on z/OS.
Before you perform these setup steps, review ″Lesson 8: Team Builds″ in the
getting started tutorial listed in Scenario 1: Getting started with Rational Team Concert
for System z.
You must define a build engine instance using the Rational Team Concert for
System z client. Follow the instructions in the tutorial to create a build engine.
Before you start a build engine, create an encrypted password file for the build
engine to use to prevent casual observation:
1. Tailor member BLZBPASS, in hlq.SBLZSAMP, where hlq is the high-level
qualifier used during SMP/E installation. This password file can also be used
in your build scripts.
2. Submit the modified JCL.
3. The job must end with a return code 0.
Important: Do not save the modified JCL with any password in it.
To run the Jazz Build Engine:
1. Tailor member BLZBENG, in hlq.SBLZSAMP, following the instructions
contained in the sample JCL.
2. Submit the modified JCL. The job must remain active and the following
messages must end the STDOUT:
2009-03-27 11:08:46 Running build loop...
2009-03-27 11:08:46 Waiting for request..
When you submit a build request to this build engine from Rational Team Concert
for System z, you will see a message similar to:
2009-03-27 20:00:38 Found a request for build definition "SampleBuild"
Note: Make sure that the user ID that is associated with the build engine has read,
write, and execute permissions to the directory where you installed the Build
System Toolkit for System z, as well as appropriate access to any directories or
artifacts associated with your build scripts or build definitions.
© Copyright IBM Corp. 2009
77
78
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Appendix B. Troubleshooting the Jazz Team Server
You can use the administrative Web interface to troubleshoot server issues.
Before you begin
You must be logged in to the Administrative Web user interface and be a member
of the JazzAdmins group.
About this task
To troubleshoot server issues, in the from the administrative Web user interface,
click the Server tab. On this page, you can find server state information that can
help you troubleshoot problems.
Tip: Go to Jazz.net Tech Notes at http://jazz.net/library/#type=technote or Server
troubleshooting FAQ at https://jazz.net/wiki/bin/view/Main/
ServerTroubleshootingFAQ to find additional troubleshooting tips.
The table below lists common problems and ways to troubleshoot them.
Problem
What to check
Database is not available
Check the server status: click Status
summary.
v On the Status Summary page, in the
Server Status pane, verify that the
database status is connected. If the status
is unavailable, check the Database Status
pane for details. Possible failures include
a database configuration that is not valid
and a valid configuration to a database
that is not initialized.
Note: The Derby database supports only
one connection; if another server instance
is running, it might be using the only
database connection. If this problem
occurs, the Service Error Summary pane
lists multiple errors.
v In the Server VM pane, verify that the
server is running the correct JDK.
v
© Copyright IBM Corp. 2009
In the Service Error Summary pane,
check for error messages.
79
Problem
Unable to change configuration properties
What to check
Check the server configuration properties:
under Configuration, click one of the
following items:
v E-mail Settings
v Database Connections
v Feed Settings
v License Key Management
v Advanced Properties
On these pages, you can view and update
configuration properties. When you save
changes to configuration properties, they are
propagated to the teamserver.properties file.
If the database is not connected, you can
change configuration properties only by
editing the teamserver.properties file.
Failing services
Check the status of services: click
Component Status.
On the Component Status page, check the
stack trace for more information about
failing services.
Slow server activity
Check the running services: click Active
Services.
On the Active Services page, check the
running services and their stack traces.
Check for services that run for an extended
period of time.
Check the server activity: click Statistics.
On the Server Statistics page, check the
server activity, such as statistics for Web
services, asynchronous tasks, and cache
behavior.
Additional resources and tips
For more information, you can access the log feed:
v If you are running a secure connection, access the log feed from this location:
https://localhost:9443/jazz/service/
com.ibm.team.repository.common.internal.IFeedService?category=SystemLog
v If you are not running a secure connection, access the log feed from this
location: http://localhost:9080/jazz/service/
com.ibm.team.repository.common.internal.IFeedService?category=SystemLog
If the log feed is not available, you can view the Tomcat log file from a Windows
console window. Also, for Windows, Linux, and Linux on System z, the log files
are found at JazzInstallDir/tomcat/logs/catalina.out, where JazzInstallDir is the
location where you installed the server. For z/OS, the log files are found in the
JOB listing of the start job for the application server.
80
Rational Team Concert for System z Beta Program: Installation and User’s Guide
If the teamserver.properties file is not located during startup, the server does not
work properly and the Tomcat log and log feed contain errors. The server.startup
script provides the path to the property file.
Ensure that the default Tomcat connection ports 9080 and 9443 are not in use. For
Windows, Linux, and Linux on System z, the connection ports are defined in the
JazzInstallDir/tomcat/conf/server.xml file, where JazzInstallDir is the location
where you installed the server. For z/OS, server.xml is found in
@[email protected]/catalina_base/conf/server.xml.
If the problems persist, consider reinstalling the database or the Web archive
(WAR) file. You can reinstall the database from the original distribution file
(repositoryDB.zip) or from a backup file.
Troubleshooting the Jazz Team Server setup wizard
There are several actions you can take if the server setup wizard does not load.
About this task
Check the following items:
1. Use the following URL to verify that the application server has started:
http://localhost:9080.
2. Verify the Jazz Team Server has started by logging in to the Jazz Team Server
Administrative Web user interface using this URL: https://localhost:9443/
jazz/admin. If the page does not load or the server has errors, the server did
not start correctly. See the troubleshooting information in the Troubleshooting
server issues section of this guide.
3. The URI root for the Jazz Team Server path should be /jazz. For example
https://example.com:9443/jazz must be used, rather than
https://example.com:9443.
Troubleshooting Antz builds
File agent can not log in to the Jazz Team Server for System z
The following error message: CRHTC0201E Unable to log-in repository
″https://localhost:9443/jazz/″ indicates that the file agent running on the build
machine could not log in to the Jazz Team Server for System z that is running on
the same machine as the client. You can make the Jazz Team Server for System z
accessible from an Antz build by changing settings in the advanced server
properties.
Complete these steps to make the Jazz Team Server for System z accessible from an
Antz build when the server is running on the same machine as the client:
1. In a supported Web browser, on the Jazz Team Server for System z workstation,
navigate to the administrative page: https://localhost:9443/jazz/admin
2. From the left navigation, click Advanced Properties.
3. Scroll to
com.ibm.team.repository.servlet.internal.ServletConfigurationService.
4. For the Host Name property, enter a host name or IP address for the build
machine to use to access Jazz Team Server for System z.
5. Restart the Jazz Team Server for System z.
Appendix B. Troubleshooting the Jazz Team Server
81
Incorrect Data Set Definitions and Language Definitions in a
build
When two or more project areas are defined in one Jazz repository, the Antz build
attempts to find Data Set Definitions and Language Definitions in the project area
where the Rational Build Agent is defined. If an Antz build is defined in a different
project area, the Antz build pulls the Data Set Definitions and Language
Definitions from an incorrect project area.
Complete these steps to make the Antz build locate the correct definitions:
1. Delete the existing RationalBuildAgent build engine in the Team Artifacts view.
2. Create a new RationalBuildAgent build engine in the project area, where the
build definition that you want to run is defined.
3. In the Build Engine editor, check the build definition to ensure that it is
supported by the newly created RationalBuildAgent build engine.
This fix will not be required in the final release.
82
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Appendix C. Troubleshooting Rational Build Agent issues
This section describes procedures that you can use to troubleshoot the Rational
Build Agent installation process and other issues.
Troubleshooting the Rational Build Agent
This section describes procedures that you can use to troubleshoot the Rational
Build Agent that is not working correctly. Go through the procedures in order.
Testing host name resolution
Verify that the agent can be reached from the machine that is running the Jazz
Team Server for System z.
Ping your host system, for example:
C:\>ping mvs269.rtp.raleigh.ibm.com
Pinging mvs269.rtp.raleigh.ibm.com [9.12.128.138] with 32 bytes of data:
Reply
Reply
Reply
Reply
from
from
from
from
9.12.128.138:
9.12.128.138:
9.12.128.138:
9.12.128.138:
bytes=32
bytes=32
bytes=32
bytes=32
time=52ms
time=52ms
time=52ms
time=51ms
TTL=55
TTL=55
TTL=55
TTL=55
Ping statistics for 9.12.128.138:
Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 51ms, Maximum = 52ms, Average = 51ms
C:\>
A message similar to the following message indicates a problem:
Unknown host
There is a problem with the network configuration of the of the Jazz Team Server
for System z. Contact your network administrator.
Testing the connection
You can test the connection to the agent by using telnet.
To test the connection from the command line:
1. Connect to the agent with a telnet command. If you are logged on to the host
where the agent is running, you can use localhost as the host name.
telnet hostname 5555
This response indicates a successful connection:
200 HELLO - BuildForge Agent v7.0.1.buildnumber
2. Check authentication by issuing the following commands, using your login
credentials:
© Copyright IBM Corp. 2009
83
telnet localhost 5555
username user name
password password
cmd ping
go
Note: The commands are not processed until you type the go command.
The following message indicates success:
AUTH: set user account to <user name>
The following output of a telnet session is typical. In particular look for RESULT 0
at the end of the output as an indication of success.
200 HELLO - BuildForge Agent v7.1.0.0-0-0241
username bgreen
password rtc4fun
cmd ping
go
320 AUTH AuthOk["bgreen"]
320 SET EnvSet["BF_AGENT_VERSION","7.1.0.0-0-0241"]
320 SET EnvSet["BF_AGENT_PLATFORM","os/390 19.00 03"]
320 EXEC Locale["C"]
320 PTY Pty[*PtyPipe]
320 EXEC Locale["C"]
320 EXEC ExecShellPath["/bin/sh"]
300 HEARTBEAT 1
310 PLAT os/390 19.00 03
320 PING PingOk
251 RESULT 0
260 EOR
Additional troubleshooting procedures
To troubleshoot a Build Forge agent, try these procedures:
v Run bfagent from a shell. The correct response is similar to this message:
200 HELLO - Build Forge Agent v7.0.1.122
If you receive a message similar to the example and there are shared library
problems, you will receive messages regarding those problems. You can resolve
most shared library problems by setting the path correctly.
v Check that the agent is listening. Use the following command (assuming that the
port is the default, 5555):
telnet localhost 5555
A 200 HELLO response indicates that the agent is listening. If you do not get
this response, check your systems network configuration. Verify that the inetd
configuration is correct, or check with your system administrator.
v Check authentication. Issue the following commands, using your login
credentials:
telnet localhost 5555
username <user name>
password <password>
cmd ping
go
A message similar to the following message indicates that the authentication is
working correctly:
AUTH: set user account to <user name>
84
Rational Team Concert for System z Beta Program: Installation and User’s Guide
bfagent reference
The Build Forge agent is normally run as an auto-starting service or daemon, but
for the Rational Team Concert for System z beta, you can start the bfagent program
from the command line.
The syntax for the command is:
bfagent [-f configfile] [-s]
Option
-f configfile
Run using the configuration file in configfile, rather than bfagent.conf.
This is a runtime option on z/OS.
-s
Start as a standalone service. This option is an alternative to starting
bfagent with either the inetd or xinetd.
bfagent.conf reference
The bfagent.conf file stores settings for how the Rational Build Agent runs. The file
is in the same directory as the bfagent executable file.
Note: For Rational Team Concert for System z V2 Beta 1, this section provides
reference to Rational Build Agent configuration for multiple platforms and some
statements might not apply to z/OS.
The file lists all settings and internal defaults. Inactive settings are commented out.
Settings
activity_log path
Turns on activity logging. The information is appended to the file specified
by path. The path must exist and the agent user must have write
permission for it.
Note: The agent does not report an error if the path does not exist or if it
cannot write to the file.
Important: There is no limit on file size. The file must be manually
deleted. This setting is intended to be used temporarily for debugging the
agent. It is not intended as a permanent log for a working agent.
allow IP-address-or-range [...]
Use this setting for these conditions only:
v Agents running on Windows
v Agents running in standalone mode on UNIX or Linux when the -s
option on startup is used.
This setting limits connections to the agent. Connections are allowed only
from the IP addresses that match IP-address-or-range. By default,
connections are allowed from all addresses.
Specify one or both of the items:
v IP Address: A fully-qualified IPv4 or IPv6 address. For example, for
IPv4, 255.192.192.003. The specific IP address is allowed.
Appendix C. Troubleshooting Rational Build Agent issues
85
v IP Address range: A partially-qualified IPv4 or IPv6 address. These
examples are correct for IPv4, 192.168 or 192.168.63. All IP addresses that
match this qualification are allowed.
Note: If you are running the agent on a superserver such as inetd or
xinetd, use another method to control access. You can use a firewall, TCP
wrappers (hosts.allow and hosts.deny), or the built-in filtering capability of
xinetd.
bind
This setting allows you to specify an explicit bind address for the agent.
This, together with the ″port″ setting, determines how the agent will listen
for connections when it is started with the -s command line option. The
value given in the bfagent.conf file will force the agent to bind to the IPv4
localhost address; thus, the agent will only receive connections from a
console that is on the same machine. Example: bind 255.192.192.003
Note: It has no effect on agents that are started by the system’s service
architecture, such as inetd, xinetd, or launchd.
ccviewroot root-path
This setting specifies the default view root for this host. See ClearCase
documentation on init for more information. The internal defaults are as
follows:
v ccviewroot /view
command_output_cache size
This setting causes the agent to cache output until it reaches the specified
size in bytes. The internal default is not to cache. Using a cache can
significantly improve agent performance and reduce network overhead.
The cache size depends on how much output that commands wproduce.
Minimum value: 2048. A value of 2048 is used internally if the setting is
less than that.
cygwin
This setting is used only with agents on Windows.
This setting enables the agent to work on a Windows host using cygwin, a
Linux-like environment. When using cygwin, a number of Linux tools are
available to the agent.
When you use this setting, you might need to set cygwin_script_magic and
shell settings also. The example shows one way to configure these settings:
cygwin
shell C:\cygwin\bin\bash.exe --login -c "%s"
cygwin_script_magic #!/bin/bash
The shell setting must match your installation of Cygwin.
cygwin_script_magic
This setting is used only with agents on Windows when cygwin is set.
This setting specifies the #! line to use when executing steps. The default is
#!/bin/bash.
default_logon_domain
Specifies the domain to use when an authentication request does not
include a domain. If not specified, the agent machine’s domain is used.
disable_telnet
For best results, use telnet to test the agent connection.
86
Rational Team Concert for System z Beta Program: Installation and User’s Guide
For the agent, there is some built-in processing overhead associated with
processing and correctly handling telnet control sequences.
Use this setting to disable the agent from handling special telnet character
codes that can slightly improve performance. In product environments, use
this setting to benefit from the improved performance.
disable_transcode
Turns off processing that the agent performs to convert international data
when the operating system is not using UTF-8 encoding. To avoid mixed
encodings and data corruption, use UTF-8 for the agent operating system.
If the operating system does not use UTF-8 encoding, the agent must
convert data to the correct encoding for the operating system’s locale
settings.
If your operating system does not use UTF-8, use this setting for best
results and improved performance of the agent.
enable_agent_dll
This setting enables DLL process tracing, which is a debugging tool.
env_recursion_limit number-of-recursions
Sets the variable-replacement recursion limit for pre-parsing. If not set, the
limit is 32.
extensions
This setting specifies paths to external libraries of functions. The functions
can be used as dot commands in a step. If this setting is not specified,
external libraries are not loaded.
During parsing, the first token in the step command is taken as the
function name. The second token is a string, and the third is an integer
timeout value (in seconds).
Requirement: Dynamic loader support in the operating system. For
example, in UNIX or Linux you need /usr/include/dlfcn.h. These default
values are used internally.
v UNIX or Linux: /usr/local/bin/bfextensions.so
v Windows: c:\program files\ibm\build forge\agent\bfextensions.dll
getaddrinfo_using_addrconfig
This setting is used only for running the agent as a standalone service on
UNIX or Linux operating systems (bfagent -s). This setting makes the agent
use AI_ADDRCONFIG when calling getaddrinfo() to select a listening
interface. By default, AI_ADDRCONFIG is not used.
If you use this setting, the agent ignores interfaces that do not have a
properly configured address. It listens only for interfaces that have a
properly configured address.
lang lang-code
Use this setting only when the Management Console does not provide a
valid language.
This setting specifies the language that the agent uses to write messages
and command output. Typically it is not set explicitly because the agent
uses the language that the Management Console specifies. However,
setting the language can be useful if the desired locale is not available on
Appendix C. Troubleshooting Rational Build Agent issues
87
the computer. The setting is also useful as a backup, in case the
Management Console fails to communicate a language or communicates an
invalid language.
The internal default is en, as if it were explicitly set as follows:
lang en
leave_tmp_file
Use this setting only while you are troubleshooting.
This setting causes the temporary file that is used to hold step commands
to be retained, rather than deleted after command execution. In
troubleshooting, the file can be compared to the steps as they are displayed
in the Management Console.
Note: Do not use this setting for typical operations.
locale locale-code.charset-code
This setting is used only with UNIX and Linux operating systems.
Windows handles locales differently.
This setting specifies the language and multibyte character set that
localized applications use. This setting works by setting the LANG
environment variable for the agent context.
To set up the agent to treat command output as US English UTF-8, use the
UTF-8 locale for your operating system. For example, on Linux use the
following representation.
locale en_US.UTF-8
To determine the correct representation of the UTF-8 locale for your
operating system, run the locale -a command.
If this setting is not specified, the agent uses the locale of the operating
system. This setting is a convenience. This setting is especially useful if the
default locale of the operating system is not the locale that you want the
agent to use. The setting is especially useful if changing the system locale
to meet agent requirements is not practical.
magic_login user:encoded-password
The agent typically uses administrative privileges such as root or admin to
log on to the operating system. The magic_login setting is an alternative to
standard system authentication. With this setting, the system can
authenticate your login with a single user name and password.
If the agent is run as the root or admin user, this setting is ignored and
normal authentication is attempted.
The agent runs all commands using the permissions of the user who
started the agent, not the user name used to log in.
This setting is used in only these situations:
v When running the agent with administrative privileges is not possible.
For example, use this setting with UNIX systems that do not work with
PAM.
v When running the agent with administrative privileges is not
permissible because of security policies.
To configure a login for the agent:
88
Rational Team Concert for System z Beta Program: Installation and User’s Guide
1. To create a server authentication that uses a user name and password.
In the Management Console, click Servers → Server Auth.
2. For this example the user name is build and the password is
MySecretPassword.
3. Create a server that uses the agent. Associate the server authentication
with this server in the Authentication field.
4. Generate an encoded password for the agent. In the installation
directory for the agent, run bfagent -P with the password that you
choose.
An SMD5 hash-encoded password is returned, as follows:
bfagent -P "MySecretPassword"
eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
5. In bfagent.conf, set magic_login to use the desired user name and
encoded password.
magic_login build:eca0b7f2f4fbf110f7df570c70df844e1658744a4871934a
6. Start the agent.
7. Test the server connection. In Servers, select the server, and then click
Test Server.
map drive-and-user-spec[; ...]
This setting specifies a mapped drive. Some systems might require drive
mappings. For example, a drive mapping might be required because a shell
is run from a shared drive. Mappings specified on the agent are performed
before mappings specified by _MAP environment variables in the
Management Console. This example illustrates two drive mappings:
map X:=//host1/share;Z:=//host2/share(username,password)
map_drive_is_failure
When specified, this setting causes a step to fail upon encountering an
unmapped drive specification, before step execution. If this setting is not
specified, steps ignore drive failures and attempt to run the step. In that
case ensure that the failure generates a meaningful error message.
no_preparse_command
This setting disables the variable-expansion parsing that the agent typically
performs on a command before passing the command to the shell. See also
the _NO_PREPARSE_COMMAND environment variable, which can be
used for an single project or step.
no_pty
This setting is used only with agents that are running on UNIX or Linux
systems.
This setting can be used to help prevent the system shell from locking up
when the shell interacts with the pseudoterminal of the agent. This setting
is typically used with HP/UX and z/OS. You can also use two other
methods to help prevent this kind of lockup:
v Use an alternate shell.
v Use the nologonshell setting
The no_pty setting disables the pseudoterminal allocation.
Note: Using no_pty affects some commands. For example, the ls command
returns output in a single column rather than three columns. If you use
this setting, test thoroughly before you deploy the job to a production
environment.
Appendix C. Troubleshooting Rational Build Agent issues
89
nologonshell
Use this setting only with agents that are running on UNIX or Linux.
This setting causes the shell that the agent runs to be a normal shell, not a
logon shell. This setting is often in these cases:
v The logon shells provide verbose output.
v The logon shells change environment settings in unwanted ways.
v The logon shells attempt to communicate interactively with the user.
When set, standard methods of requesting that the shell be a normal shell
rather than a logon shell are used. This may not work on all platforms and
in such cases, the shellflag setting may be used to pass flags to the shell in
order to modify its behavior.
Those behaviors are not desirable for the agent, because it runs as a user
without being an interactive user.
Note: The Mac OS X 10.5 system uses /bin/bash, which does not respond
to nologonshell. Use shellflag -l.
Note: The z/OS operating system always uses the /etc/profile script for
both logon shells and non-logon shells. You might need to change the
contents of the script or use another shell if its behavior does not work
well with the agent.
See also the shellflag setting. Flags can be used to change logon script
behavior.
password_encrypt_module dll_path;conf_path
Required to enable SSL on the agent. It specifies paths to a DLL and
configuration file.
v dll_path is the path to bfcrypt.dll (it is typically ./bfcyrpt.dll).
v conf_path is the path to bfpwcrypt.conf (it is typically ./bfcrypt.conf).
port port-number-or-range [...]
This setting is used only with agents that are running in standalone mode
on UNIX or Linux when you issue the -s option on startup.
This setting specifies the port that the agent uses to listen for connections
with the Management Console.
v Agents running in standalone mode on UNIX or Linux (-s option on
startup).
Specifies the port that the agent uses to listen for connections with the
Management Console.
Note: The port is set to 5555 by default. For UNIX or Linux the setting is
in /etc/services.
shell shell_name [options]
This setting specifies the default shell. Internal defaults are as follows:
v Windows: shell cmd.exe /q /c "%s" unless the following settings are
used:
– If the cygwin setting is used, the default is shell C:\cygwin\bin\
bash.exe --login -c "%s"
– If the cygwin setting is not used, the default is shell cmd.exe /u /q
/c "%s"
90
Rational Team Concert for System z Beta Program: Installation and User’s Guide
v UNIX or Linux: The shell set for the user account, or /bin/sh if the
user’s shell can not be determined. Note that you cannot specify
parameters in this setting, but you can use the shellflag setting to pass
them. The agent automatically forces the default to be a logon shell by
inserting a hyphen. For example, /bin/ksh is sent as -ksh. If shell is set
explicitly, then nologonshell is set implicitly. See nologonshell.
v System i: Set the shell value to /bin/sh
You can override this setting from within a step. A step that starts with a
line containing #! overrides the shell setting and the nologonshell setting
is used to run the step commands.
shell_compatible_undef_vars
This setting forces the representation of undefined variables to be an empty
string. If not set, the representation is the variable name for variables of
format $VAR, ${VAR}, or %VAR% and the empty string for $[VAR].
shellarg
This setting is used only with agents that are running on UNIX or Linux.
Use this setting if it seems that commands are being scrambled. Some
shells on Red Hat Linux Enterprise require this setting.
The setting changes the way a command script is passed to the shell.
Normally the script is passed through standard input:
/bin/sh < /tmp/bfshellscript.sh
This setting causes scripts to be run by passing them as parameters:
/bin/sh /tmp/bfshellscript.sh
shellflag flag
This setting is used only with agents that are running on UNIX or Linux.
This setting adds a flag when a shell is running. Only one flag can be
specified. It is typically used to disable rc script processing in order to
reduce output or undesired processing.Examples:
v csh and derivatives: use shellflag -f to disable rc script processing.
v bash: use shellflag –-noprofile to disable profile script processing.
ssl_ca_location path
Specifies the keystore file that contains the certificate authority. If the agent
runs as a service, use an absolute path.
ssl_cert_location path
Specifies the keystore that contains the private certificate. If the agent runs
as a service, use an absolute path.
ssl_client_authentication [true | false]
Set to true to require client authentication when a connection is made to
the agent. If true, the Build Forge engine’s certificate must be added to the
agent’s certificate authority keystore.
ssl_cipher_group [grouplist | ALL]
Specifies individual cipher groups to use. Can be set to ALL.
ssl_cipher_override cyphers
Overrides the cipher group. Specify the ciphers to use.
ssl_key_location path
Specifies the keystore file that contains the key. If the agent runs as a
service, use an absolute path.
Appendix C. Troubleshooting Rational Build Agent issues
91
ssl_key_password password
Password for the key. This property is stored in clear text by default. You
can enable the agent to encrypt this password using its own key or the
Build Forge server’s key.
ssl_protocol protocol
The SSL handshake protocol to use, one of SSL, SSLv2, SSLv3, SSL_TLS,
TLS, TLSv1. The protocol must match the protocol used by the Build Forge
server.
update_path path
This setting identifies the full path to the Rational Build Agent executable.
The setting is established automatically during installation. The directory is
a default directory for the operating system or the installation directory
that you specify.
Note: This setting is ignored on Windows agents. The update path is taken
from registry keys. The keys are set during agent installation.
win_reexec_after_auth
Add this setting if you need to run agent commands on a network share
file system using Build Forge server authentication credentials. For
example, to modify files in a ClearCase dynamic view, the agent must
access ClearCase files on a networked shared file system.
The Rational Build Agent initially starts up with Windows system account
credentials. To run commands, the agent later authenticates with Windows
using Build Forge server authentication credentials.
Without this setting, the network share recognizes only the initial Windows
system account credentials and ignores the subsequent server
authentication credentials that are needed to access and write to files on
the network share file system.
The win_reexec_after_auth starts a new process after authenticating with
Windows again by using the server authentication credentials and forces
the shared file system to recognize the changed credentials.
When you use the win_reexec_after_auth setting, the agent runs as a
service and does not distinguish between commands that access network
share files and those that do not, so you might notice a performance
impact.
92
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Appendix D. Additional Jazz Team Server for System z
repository tools tasks on z/OS
Before completing any additional tasks, review the following Rational Team
Concert topic: Repository tools overview.
These instructions assume that you are using the default properties files of
teamserver_derby.properties (for Derby) or teamserver_db2z.properties (for DB2
9.1 on z/OS).
Exporting the database using the Jazz Team Server repository tools
This topic describes the steps and requirements for exporting the database using
repository tools.
About this task
To export the database with the Jazz Team Server for System z repository tools,
you must:
1. Configure one of the following members using the instructions in the sample
JCL:
v If you are using DB2 for z/OS, configure member BLZEXPOR in
hlq.SBLZSAMP.
v If you are using Derby, configure member BLZEXPO2 in hlq.SBLZSAMP.
2. Submit the modified JCL and check the job log. The following message must
end the STDOUT: Export completed successfully. The user ″ADMIN″ has
logged out of the database.
Notes:
a. All the server processes that are connected to the repository database must
be stopped, including the Jazz server and the Jazz build engine. If processes
are not stopped, the export will fail.
b. When you use repository tools, you can specify the codepage to use by
specifying the JVM option –Dfile.encoding.
v If you want to use UTF-8, specify -Dfile.encoding=UTF-8.
v If you want to specify Cp1047, which is an EBCDIC encoding used for
C/Java programming, specify -Dfile.encoding=Cp1047.
v If you export in UTF-8, you can move your .tar file to a distributed
system and import it using that system.
v If you export in Cp1047, your .tar file can only be imported using a
repository tools import performed on System z.
Running repository tools to import a Jazz Team Server for System z
database
This topic describes the steps and requirements for importing a Jazz Team Server
for System z database using repository tools.
© Copyright IBM Corp. 2009
93
About this task
To import a Jazz Team Server for System z database by running repository tools,
you must:
1. Configure one of the following members using the instructions in the sample
JCL:
v If you are using DB2 for z/OS, configure member BLZIMPOR in
hlq.SBLZSAMP.
v If you are using Derby, configure member BLZOMPO2 in hlq.SBLZSAMP.
2. Submit the modified JCL and check the job log. The following message must
end the STDOUT: Import completed successfully. The user ″ADMIN″ has
logged out of the database.
Notes:
a. All the server processes that are connected to the repository database must
be stopped, including the Jazz server and the Jazz build engine. If processes
are not stopped, the import will fail.
b. Pay attention to the JVM properties, like Xms and Xmx.
Creating database tables using Jazz Team Server for System z
repository tools
If you need to recreate a new Jazz Team Server for System z repository, you can
use the Jazz Team Server for System z repository tools to create the required
database tables and indexes for the Jazz Team Server for System z.
Before you begin
Ensure the teamserver_derby.properties file or the teamserver_db2z.properties
file have been configured correctly as described in earlier in this guide and, if you
are using DB2 for z/OS, have previously created the DB2 database.
About this task
Then you must:
1. Configure one of the following members by following the instructions in the
sample JCL.
v If you are using DB2 for z/OS, configure member BLZCREDB in hlq.SBLZSAMP.
v If you are using Derby, configure member BLZCRED2 in hlq.SBLZSAMP.
2. The Jazz Team Server for System z and the Jazz Team Server repository tools
require access to the DB2 V9 JDBC license jar file on your system. This file is
named db2jcc_license_cisuz.jar and is located by default at
/usr/lpp/db2910_jdbc/classes. If the file is in a different directory, then
modify the sample job to point to the correct location.
3. Submit the modified JCL and check the job log. The following message must
end the STDOUT: The database tables were created successfully. The
details are in the JCL sample.
94
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Appendix E. Antz tasks and data types
Antz provides a number of custom data types and tasks that allow the build script
author to define and select a set of buildable files from within a repository
workspace. Additional custom tasks allow execution of the translator steps defined
in a Language Definition through the invocation of generated Ant macro
definitions. For general information regarding getting started with Apache Ant,
please see http://ant.apache.org. Antz custom data types that can be included in a
build script (build.xml) are:
Table 5. Antz custom tasks and data types
Class name
Tag
Description
BuildableResourceCollection
<antz:buildablesett>
An Ant ResourceCollection
that represents a set of
buildable resources.
BuildableResourceList
<antz:buildablelist>
An Ant ResourceCollection
that can contain multiple
buildable resources.
BuildableResource
<antz:buildable>
An buildable resource.
ComponentSelector
<antz:componentselector>
A custom resource selector
that allows the resources to
be included in a
BuildableResourceCollection
based on the name of the
component that defines the
resource.
ProjectSelector
<antz:projectselector>
A custom resource selector
that allows the resources to
be included in a
BuildableResourceCollection
based on the name of the
project that defines the
resource.
LanguageDefinitionSelector
<antz:langdefselector>
A custom resource selector
that allows the resources to
be included in a
BuildableResourceCollection
based on the name of the
Language Definition
associated with the resource.
Antz provides the following custom task for use in z/OS based build scripts:
Table 6. Custom task for z/OS based build
© Copyright IBM Corp. 2009
Class name
Tag
Description
Compile
<antz:compile>
An Ant Task that compiles a
BuildableResourceCollection
that is provided as its child
element.
95
The following task and data types are also provided by Antz. However, they are
used in the macro definitions, which are generated from Language Definitions, and
are not intended for external use:
Table 7. Antz tasks and data types for macro definitions
Class name
Tag
Description
Alloc
<antz:alloc>
An Ant data type that
represents a data set
allocation.
Concat
<antz:concat>
An Ant data type that
represents a data set
concatenation.
Executable
<antz:mvsexec>
An Ant task that invokes an
MVS module specified in a
Translator contained in a
Language Definition.
Note: All custom Antz data types and tasks are defined in the
antlib:com.ibm.teamz.build.ant namespace. This namespace must be declared in
any build script that uses Antz tasks.
Antz custom data types
The BuildableResourceCollection, ComponentSelector, and ProjectSelector custom
data types provided by Antz, with parameters and examples, are described below.
BuildableResourceCollection custom data type
A BuildableResourceCollection is an Ant ResourceCollection that represents a set of
buildable resources. Buildable resources are defined as those repository workspace
assets that are associated with a language definition. A
BuildableResourceCollection is built based on the content of a buildable resource
XML file. This file is generally produced by the Build Forge Service preprocessor
when a build is requested.
A BuildableResourceCollection is defined using the <antz_buildableset/> tag.
BuildableResourceCollection parameter
Table 8. BuildableResourceCollection parameter
Attribute
Description
buildableList Path to the buildable resource XML file to be used when creating the
BuildableResourceCollection
BuildableResourceCollection examples
Create a resource collection based on the content of the file whose path is stored in
the property ${buildablefile} and assigns it the reference id ″mySet″.
<antz:buildableset id="mySet" buildableList="${buildablefile}"/>
Creates a resource collection that includes only the files that:
v Exist on the MVS file system
v Were defined within the project ″User Management″
96
Rational Team Concert for System z Beta Program: Installation and User’s Guide
v That are members defined in the MVS dataset DEARTH.COBOL.SET1
<restrict id="mySet">
<antz:buildableset buildableList="${buildablefile}"/>
<rsel:exists/>
<antz:projectselector name="User Management"/>
<rsel:name name="DEARTH.COBOL.SET1(*)"/>
</restrict>
BuildableResourceList Custom Datatype
A BuildableResourceList is an Ant ResourceCollection that can contain multiple
buildable resources defined with the <antz:buildable> tag with in-stream data.
A BuildableResourceList is defined using the <antz_buildablelist/> tag.
BuildableResourceList Example
Create a resource collection that contains one buildable resource that defined
link-edit input with in-stream data.
<antz:buildablelist>
<antz:buildable langDefName="LINKEDIT" memberName="HELLO">
INCLUDE SYSLIB(HELLO)
NAME HELLO(R)
</antz:buildable>
</antz:buildablelist>
BuildableResource Custom Datatype
A BuildableResource represents an Antz buildable resource and it can contain
in-stream data.
In-stream data are copied to a temporary data set, whose logical record length is
80, before being processed. Leading blanks are reserved. If one line of the in-stream
data contains more than 80 bytes, data truncation occurs. If one line of the
in-stream data is less than 80 bytes, trailing blank characters are appended.
A BuildableResource is defined using the <antz_buildable/> tag.
BuildableResource Parameters
Table 9. BuildableResource Parameters
Attribute
Description
langDefName
The name of the language definition, which this resource will be processed
with.
memberName Identify a name, which is used for generating a member when the output
is a partitioned data set.
BuildableResource Example
Create a buildable resource that defined link-edit input with in-stream data.
<antz:buildable langDefName="LINKEDIT" memberName="HELLO">
INCLUDE SYSLIB(HELLO)
NAME HELLO(R)
<rsel:exists/>
<antz:projectselector name="User Management"/>
</antz:buildable>
Appendix E. Antz tasks and data types
97
ComponentSelector Custom Datatype
A component selector is a custom resource selector that allows the resources to be
included in a BuildableResourceCollection based on the name of the component
that defines the resource. The <antz:componentselector> tag is used to specify a
component selector.
ComponentSelector Parameters
Table 10. ComponentSelector Parameters
Attribute
Description
name
The name of the project to which the resource’s component name will be
compared. Value can contain the special characters ″*″, representing a set of
0 or more characters, and ″?″, representing any character.
caseSensitive Indicates whether the comparison should be performed in a case sensitive
manner. Default is true.
ComponentSelector Example
Create a resource collection containing only those buildable resources whose
component name begins with ″myComponent″. Case is not considered.
<restrict id="mySet">
<antz:buildableset buildableList="${buildablefile}"/>
<antz:componentselector name="myComponent*" caseSensitive="false"/>
</restrict>
ProjectSelector Custom Datatype
A project selector is a custom resource selector that allows the resources to be
included in a BuildableResourceCollection based on the name of the project that
defines the resource. The <antz:projectselector> tag is used to specify a project
selector.
ProjectSelector Parameters
Table 11. ProjectSelector Parameters
Attribute
Description
name
The name of the project to which the resource’s project name will be
compared. Value can contain the special characters ″*″, representing a set of
0 or more characters, and ″?″, representing any character.
caseSensitive Indicates whether the comparison should be performed in a case sensitive
manner. Default is true.
ProjectSelector Example
Create a resource collection containing only those buildable resources whose
project name begins with ″myProject″. Case is not considered.
<restrict id="mySet">
<antz:buildableset buildableList="${buildablefile}"/>
<antz:projectselector name="myProject*" caseSensitive="false"/>
</restrict>
98
Rational Team Concert for System z Beta Program: Installation and User’s Guide
LanguageDefinitionSelector Custom Datatype
A Language Definition Selector is a custom resource selector that allows resources
to be included in a BuildableResourceCollection based on the name of the
Language Definition associated with the resource. The <antz:langdefselector> tag is
used to specify a language definition selector.
LanguageDefinitionSelector Parameters
Table 12. LanguageDefinitionSelector Parameters
Attribute
Description
name
The name of the Language Definition to which the resource’s Language
Definition will be compared. Value can contain the special characters ″*″,
representing a set of 0 or more characters, and ″?″, representing any
character.
caseSensitive Indicates whether the comparison should be performed in a case sensitive
manner. Default is true.
LanguageDefinitionSelector Example
Create a resource collection containing only those buildable resources whose
associated Language Definition’s name is “CobolCompile”.
<restrict id="mySet">
<antz:buildableset buildableList="${buildablefile}"/>
<antz:langdefselector name="CobolCompile" caseSensitive="false"/>
</restrict>
Antz Compile Custom Data Task
The Compile custom data task provided by Antz, with examples, is described
below.
Compile Custom Data Task
A Compile task is a custom Ant task that compiles a BuildableResourceCollection
that is provided as its child element. Internally, it invokes an Ant macro that
corresponds to the Language Definition associated with a buildable resource.
Compile Examples
This example code iterates over all buildable resources whose name matches
“*LINK(*)”, and executes the Antz macro that was generated for the Language
Definition associated with the resource.
<antz:compile>
<restrict>
<antz:buildableset buildableList="${buildfile}"/>
<rsel:name name="*LINK(*)"/>
</restrict>
</antz:compile>
This example code processes a buildable resource collection that contains buildable
resource with in-stream data.
<antz:compile>
<antz:buildablelist>
<antz:buildable langDefName="LINKEDIT" memberName="HELLO">
INCLUDE SYSLIB(HELLO)
Appendix E. Antz tasks and data types
99
NAME HELLO(R)
</antz:buildable>
<antz:buildablelist>
</antz:compile>
100
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Appendix F. Job Monitor security
This appendix contains information to assist you in setting up security for the Job
Monitor.
Security considerations
The security mechanisms used by Job Monitor relies on the file system it resides in
being secure. This implies that only trusted system administrators should be able
to update the program libraries and configuration files.
JES Security
Job Monitor allows clients access to the JES spool. The server provides basic access
limitations, which can be extended with the standard spool file protection features
of your security product. Operator actions (Hold, Release, Cancel, and Purge)
against spool files are done through an EMCS console, for which conditional
permits must be set up.
Actions against jobs - target limitations
Job Monitor does not provide users full operator access to the JES spool. Only the
Hold, Release, Cancel, and Purge commands are available, and by default, only for
spool files owned by the user. The commands are issued by selecting the
appropriate option in the client menu structure (there is no command prompt). The
scope of the commands can be widened, using security profiles to define for which
jobs the commands are available.
Similar to the SDSF SJ action character, Job Monitor also supports the Show JCL
command to retrieve the JCL that created the selected job output, and show it in
an editor window. Job Monitor retrieves the JCL from JES, making it a useful
function for situations in which the original JCL member is not easily located.
Table 13. Job Monitor console commands
Action
JES2
JES3
Hold
$Hx(jobid)
with x = {J, S or T}
*F,J=jobid,H
Release
$Ax(jobid)
with x = {J, S or T}
*F,J=jobid,R
Cancel
$Cx(jobid)
with x = {J, S or T}
*F,J=jobid,C
Purge
$Cx(jobid),P
with x = {J, S or T}
*F,J=jobid,C
Show JCL
not applicable
not applicable
The available JES commands listed in Table 13 are by default limited to jobs owned
by the user. This can be changed with the LIMIT_COMMANDS directive, as
documented in “BLZJCNFG, Job Monitor configuration file” on page 57.
© Copyright IBM Corp. 2009
101
Table 14. Job Monitor command permission matrix
LIMIT_COMMANDS
User
Other
USERID (default)
Allowed
Not allowed
LIMITED
Allowed
Allowed only if explicitly
permitted by security profiles
NOLIMIT
Allowed
Allowed if permitted by
security profiles or when the
JESSPOOL class is not active
JES uses the JESSPOOL class to protect SYSIN/SYSOUT data sets. Similar to SDSF,
Job Monitor extends the use of the JESSPOOL class to protect job resources as well.
If LIMIT_COMMANDS is not USERID, then Job Monitor will query for permission to the
related profile in the JESSPOOL class, as shown in the following table.
Table 15. Extended JESSPOOL profiles
Header
JESSPOOL profile
Required access
Hold
nodeid.userid.jobname.jobid
ALTER
Release
nodeid.userid.jobname.jobid
ALTER
Cancel
nodeid.userid.jobname.jobid
ALTER
Purge
nodeid.userid.jobname.jobid
ALTER
Show JCL
nodeid.userid.jobname.jobid.JCL
READ
Use the following substitutions in the preceding table:
nodeid
NJE node ID of the target JES subsystem
userid
Local user ID of the job owner
jobname
Name of the job
jobid
JES job ID
If the JESSPOOL class is not active, then there is different behavior for the LIMITED
and NOLIMIT value of LIMIT_COMMANDS, as described in “BLZJCNFG, Job Monitor
configuration file” on page 57. The behavior is identical when JESSPOOL is active,
since the class, by default, denies permission if a profile is not defined.
Actions against jobs - execution limitations
The second phase of JES spool command security, after specifying the permitted
targets, includes the permits needed to actually execute the operator command.
This execution authorization is enforced by the z/OS and JES security checks.
Note that Show JCL is not an operator command like the other Job Monitor
commands (Hold, Release, Cancel and Purge), so the limitations below do not
apply because there is no further security check.
Job Monitor issues all JES operator commands requested by a user through an
extended MCS (EMCS) console, whose name is controlled with the CONSOLE_NAME
directive, as documented in “BLZJCNFG, Job Monitor configuration file” on page
57.
102
Rational Team Concert for System z Beta Program: Installation and User’s Guide
This setup allows the security administrator to define granular command execution
permits using the OPERCMDS and CONSOLE classes.
v In order to use an EMCS console, a user must have (at least) READ authority to
the MVS.MCSOPER.console-name profile in the OPERCMDS class. Note that if no
profile is defined, the system will grant the authority request.
v In order to execute a JES operator command, a user must have sufficient
authority to the JES%.** (or more specific) profile in the OPERCMDS class. Note
that if no profile is defined, or the OPERCMDS class is not active, JES will fail the
command.
v The security administrator can also require that a user must use Job Monitor
when executing the operator command by specifying WHEN(CONSOLE(JMON)) on
the PERMIT definition. The CONSOLE class must be active for this setup to work.
Note that the CONSOLE class being active is sufficient; no profiles are checked for
EMCS consoles.
Assuming the identity of the Job Monitor server by creating a JMON console from
a TSO session is prevented by your security software. Even though the console can
be created, the point of entry is different (Job Monitor versus TSO). JES commands
issued from this console will fail the security check, if your security is set up as
documented in this publication and the user does not have authority to JES
commands through other means.
Note that Job Monitor cannot create the console when a command must be
executed if the console name is already in use. To prevent this, the system
programmer can set the GEN_CONSOLE_NAME=ON directive in the Job Monitor
configuration file or the security administrator can define security profiles to stop
TSO users from creating a console. The following sample RACF commands prevent
everyone (except those permitted) from creating a TSO or SDSF console:
v RDEFINE TSOAUTH CONSOLE UACC(NONE)
v PERMIT CONSOLE CLASS(TSOAUTH) ACCESS(READ) ID(#userid)
v RDEFINE SDSF ISFCMD.ODSP.ULOG.* UACC(NONE)
v PERMIT ISFCMD.ODSP.ULOG.* CLASS(SDSF) ACCESS(READ) ID(#userid)
Note: Without being authorized for these operator commands, users will still be
able to submit jobs and read job output through the Job Monitor, if they have
sufficient authority to possible profiles that protect these resources (like those in
the JESINPUT, JESJOBS and JESSPOOL classes).
Refer to Security Server RACF Security Administrator’s Guide (SA22-7683) for more
information on operator command protection.
Access to spool files
Job Monitor allows browse access to all spool files by default. This can be changed
with the LIMIT_VIEW directive, as documented in “BLZJCNFG, Job Monitor
configuration file” on page 57.
Table 16. Job Monitor browse permission matrix
Job owner
LIMIT_VIEW
User
Other
USERID
Allowed
Not allowed
Appendix F. Job Monitor security
103
Table 16. Job Monitor browse permission matrix (continued)
Job owner
LIMIT_VIEW
User
Other
NOLIMIT (default)
Allowed
Allowed if permitted by
security profiles or when the
JESSPOOL class is not active
To limit users to their own jobs on the JES spool, define the
″LIMIT_VIEW=USERID″ statement in the Job Monitor configuration file, BLZJCNFG.
If they need access to a wider range of jobs, but not all, use the standard spool file
protection features of your security product, like the JESSPOOL class.
When defining further protection, keep in mind that Job Monitor uses SAPI
(SYSOUT application program interface) to access the spool. This implies that the
user needs at least UPDATE access to the spool files, even for browse functionality.
This requisite does not apply if you run z/OS 1.7 (z/OS 1.8 for JES3) or higher.
Here READ permission is sufficient for browse functionality.
Refer to Security Server RACF Security Administrator’s Guide (SA22-7683) for more
information on JES spool file protection.
Job Monitor configuration file
The directives in the BLZJCNFG Job Monitor configuration file impact the security
setup. The security administrator and systems programmer can decide what the
settings should be for the following directives.
v LIMIT_COMMANDS={USERID | LIMITED | NOLIMIT}
Define against which jobs actions can be done (excluding browse and submit).
For more information, see “Actions against jobs - target limitations” on page 101.
v LIMIT_VIEW={USERID | NOLIMIT}
Define which spool files can be browsed. For more information, see “Access to
spool files” on page 103.
Note: Details on the BLZJCNFG directives are available in “BLZJCNFG, Job Monitor
configuration file” on page 57.
Security definitions
The following sections describe the required steps, optional configuration and
possible alternatives.
v “Define the Job Monitor started task.”
v “Define JES command security” on page 105.
Refer to the RACF Command Language Reference (SA22-7687), for more information
on RACF commands.
Define the Job Monitor started task
The following sample RACF commands create the BLZJMON, started tasks, with
protected user IDs (STCJMON) and group STCGROUP assigned to them. Replace the
#group-id and #user-id-* placeholders with valid OMVS IDs.
v ADDGROUP STCGROUP OMVS(GID(#group-id))
DATA('GROUP WITH OMVS SEGMENT FOR STARTED TASKS')
104
Rational Team Concert for System z Beta Program: Installation and User’s Guide
v ADDUSER STCJMON DFLTGROUP(STCGROUP) NOPASSWORD NAME('JOB MONITOR')
OMVS(UID(#user-id-jmon) HOME(/tmp) PROGRAM(/bin/sh) NOASSIZEMAX)
DATA('RATIONAL TEAM CONCERT')
v RDEFINE STARTED BLZJJCL.* DATA('JOB MONITOR')
STDATA(USER(STCJMON) GROUP(STCGROUP) TRUSTED(NO))
v SETROPTS RACLIST(STARTED) REFRESH
Note: Ensure that the started task user ID is protected by specifying the
NOPASSWORD keyword.
Define JES command security
Job Monitor issues all JES operator commands requested by a user through an
extended MCS (EMCS) console, whose name is controlled with the CONSOLE_NAME
directive, as documented in “BLZJCNFG, Job Monitor configuration file” on page
57.
The following sample RACF commands give Job Monitor users conditional access
to a limited set of JES commands (Hold, Release, Cancel, and Purge). Users only
have execution permission if they issue the commands through Job Monitor.
Replace the #console placeholder with the actual console name.
v RDEFINE OPERCMDS MVS.MCSOPER.#console UACC(READ)
DATA('RATIONAL TEAM CONCERT'))
v RDEFINE OPERCMDS JES%.** UACC(NONE)
v PERMIT JES%.** CLASS(OPERCMDS) ACCESS(UPDATE)
WHEN(CONSOLE(JMON)) ID(*)
v SETROPTS RACLIST(OPERCMDS) REFRESH
Note:
1. Usage of the console is permitted if no MVS.MCSOPER.#console profile is defined.
2. The CONSOLE class must be active for WHEN(CONSOLE(JMON)) to work, but there is
no actual profile check in the CONSOLE class for EMCS consoles.
3. Do not replace JMON with the actual console name in the WHEN(CONSOLE(JMON))
clause. The JMON keyword represents the point-of-entry application, not the
console name.
Attention: Defining JES commands with universal access NONE in your security
software might impact other applications and operations. Test this before activating
it on a production system.
Table 17 and Table 18 on page 106show the operator commands issued for JES2
and JES3, and the discrete security profiles that can be used to protect them.
Table 17. JES2 Job Monitor operator commands
Action
Command
OPERCMDS profile
Required access
Hold
$Hx(jobid)
with x = {J, S or T}
jesname.MODIFYHOLD.BAT
jesname.MODIFYHOLD.STC
jesname.MODIFYHOLD.TSU
UPDATE
Release
$Ax(jobid)
with x = {J, S or T}
jesname.MODIFYRELEASE.BAT
jesname.MODIFYRELEASE.STC
jesname.MODIFYRELEASE.TSU
UPDATE
Cancel
$Cx(jobid)
jesname.CANCEL.BAT
with x = {J, S or T} jesname.CANCEL.STC
jesname.CANCEL.TSU
UPDATE
Appendix F. Job Monitor security
105
Table 17. JES2 Job Monitor operator commands (continued)
Action
Command
OPERCMDS profile
Required access
Purge
$Cx(jobid),P
with x = {J, S or T}
jesname.CANCEL.BAT
jesname.CANCEL.STC
jesname.CANCEL.TSU
UPDATE
Table 18. JES3 Job Monitor operator commands
Action
Command
OPERCMDS profile
Required access
Hold
*F,J=jobid,H
jesname.MODIFY.JOB
UPDATE
Release
*F,J=jobid,R
jesname.MODIFY.JOB
UPDATE
Cancel
*F,J=jobid,C
jesname.MODIFY.JOB
UPDATE
Purge
*F,J=jobid,C
jesname.MODIFY.JOB
UPDATE
Note:
1. The Hold, Release, Cancel, and Purge JES operator commands, and the Show
JCL command, can only be executed against spool files owned by the client
user ID, unless LIMIT_COMMANDS= with value LIMITED or NOLIMIT is specified in
the Job Monitor configuration file. Refer to “Actions against jobs - target
limitations” on page 101 for more information on this.
2. Users can browse any spool file, unless LIMIT_VIEW=USERID is defined in the Job
Monitor configuration file. Refer to “Access to spool files” on page 103 for
more information on this.
3. Without being authorized for these operator commands, users will still be able
to submit jobs and read job output through Job Monitor, if they have sufficient
authority to possible profiles that protect these resources (like those in the
JESINPUT, JESJOBS and JESSPOOL classes).
Assuming the identity of the Job Monitor server by creating a JMON console from
a TSO session is prevented by your security software. Even though the console can
be created, the point of entry is different (Job Monitor versus TSO). JES commands
issued from this console will fail the security check, if your security is set up as
documented in this publication and the user does not have authority to the JES
commands through other means.
106
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law: INTERNATIONAL
BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION ″AS IS″
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. Some states do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
© Copyright IBM Corp. 2009
107
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
Intellectual Property Dept. for Rational Software
IBM Corporation
20 Maguire Road
Lexington, MA 02421-3112
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM’s suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
108
Rational Team Concert for System z Beta Program: Installation and User’s Guide
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs.
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
© your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs.
© Copyright IBM Corp. _enter the year or years_. All rights reserved.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
Trademarks
These terms are trademarks of International Business Machines Corporation in the
United States, other countries, or both:
Adobe, Acrobat, Portable Document Format (PDF), PostScript, and all Adobe-based
trademarks are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States, other countries, or both.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo,
Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or
registered trademarks of Intel Corporation or its subsidiaries in the United States
and other countries.
IT Infrastructure Library is a registered trademark of the Central Computer and
Telecommunications Agency which is now part of the Office of Government
Commerce.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States, other
countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product, or service names may be trademarks or service marks of
others.
Notices
109
110
Rational Team Concert for System z Beta Program: Installation and User’s Guide
Program Number: 5724-V82
Printed in USA
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement