Migrating to Rational Team Concert in z/OS
Installing and using Rational Team Concert in your z/OS environment
Rational Team Concert has spawned numerous blogs, forums, and other documentation, but there's not enough support for z/OS developers migrating from their current source code management system to Rational Team Concert.
This article introduces Rational Team Concert's repository architecture and conceptual framework for source code management and collaborative development. It includes a step-by-step guide for migrating from your current source code management solution to Rational Team Concert on z/OS and a planning guide to help ensure a successful source code migration.
As a z/OS developer, you might wonder if the hassle of migration is worth it, especially if your current system works well enough. If all you need to do is manage source code in a functional code repository, Rational Team Concert could be more platform than you need. If you're looking to overhaul and modernize your entire development process, you could want more features than Rational Team Concert alone provides.
Rational Team Concert is not just a source code management solution; it also manages process, planning, and work items, as shown in Figure 1.
Figure 1. Overview of Rational Team Concert
Rational Team Concert's ability to manage both distributed and z/OS source code in the same repository makes for an overall more integrated source code management solution. Migration is also an opportunity to review your development process, especially for effective team collaboration. If you find yourself managing complex projects over distributed teams, you might want to integrate Collaborative Lifecycle Management components as well.
Understanding Rational Team Concert
Rational Team Concert is more powerful than most source code management systems, and also more complex. Whereas most mainframe source repositories use data sets and members to store code, Rational Team Concert stores code in projects, folders, and files, within a database repository. In order to build code in z/OS, these artifacts are copied into z/OS data sets.
Table 1 introduces some of the terminology used in Rational Team Concert.
Table 1. Rational Team Concert terminology
|Project||An Eclipse project that contains related artifacts organized into folders and files.|
|Sandbox||A workspace stored as a folder on the hard disk (i.e., your local Eclipse workspace). It contains the projects you're currently working on. For the Rational Team Concert ISPF Client a sandbox is a collection of data sets with the same HLQ.MLQ.|
|Stream||Rational Team Concert is a stream-based repository, where different streams will hold various code branches. For instance, you could use a different stream to represent each of your code releases.|
|Repository workspace||This is a user’s private area in the repository where they can check-in code from their sandbox. It flows with a particular stream, which means code is delivered from the workspace to the stream. Code from the stream can be accepted to the repository workspace, which also updates the loaded code in the sandbox.|
|Component||A component is a collection of related projects. Components can be used to control access rights and facilitate sharing and reuse. A stream consists of a number of components. Each component can be shared between multiple streams, for example, two different versions of a product may contain the same components.|
|Change set||A unit of work containing a collection of related code changes that are delivered at a point in time.|
|Share||Sharing pushes new artifacts from a sandbox to a repository workspace.|
|Load||Load pulls selected artifacts from the repository workspace to the sandbox (again, an Eclipse workspace or MVS data set).|
|Accept||Pulls new change sets previously delivered to the stream by other developers to a repository workspace. If the change sets are related to projects that are loaded in your sandbox then your sandbox is automatically updated.|
|Check-in||Pushes local changes from your sandbox into a repository workspace, creating or modifying a change set.|
|Delivery||Pushes the checked-in change sets from the repository workspace to the stream.|
Figure 2 shows how operations described in Table 1 are performed against Rational Team Concert objects.
Figure 2. Source control in Rational Team Concert
Installing Rational Team Concert
The IBM Knowledge Center provides instructions for installing Rational Team Concert. Navigating installation can be confusing if you don’t know anything about the components that you are installing, however. As we guide you through the basic process, we'll also try to demystify key components and help you determine which ones you need.
Rational Team Concert is just one of a number of applications running in an application server connected to a database. As an example, the Jazz Team Server could run on Liberty on z/OS using DB2 for z/OS as the database. Rational Team Concert is part of Collaborative Lifecycle Management solution (CLM) suite, and it also provides various clients and build agents, as shown in Figure 3.
Figure 3. Architecture of Rational Team Concert
Step 1. Install Jazz Team Server
The first step of migrating to Rational Team Concert is to install Jazz Team Server. Start now by opening the installation instructions in the Rational Collaborative Lifecycle Management Interactive Installation Guide.
Before you begin your installation, you need to decide what platform you are going to install your server on, and where you will put the repository that holds the data. A section in the guide discusses various topologies. For the purpose of this discussion we recommend installing Jazz Team Server on z/Linux and DB2 for z/OS.
With that topology as our example, we can use the Interactive Installation Guide to step through the install. Selecting the options specified in Table 2 will give you instructions for installing the server on Linux on z Systems, running as a WebSphere Liberty Server, with a DB2 for z/OS repository database.
Table 2. Interactive Installation Guide
|Select the operating system for your application server||Linux for System z|
|Select the setup method||Custom setup|
|Select one or more applications to install||Jazz Team Server Change and Configuration Management|
|Optional applications (separate license)||Do not select|
|Supporting applications||Do not select|
|Jazz reporting service||Do not select|
|Select your database server||IBM DB2 for z/OS|
|Select your user registry type||LDAP|
|Are you configuring a data warehouse?||No|
2. Install Rational Team Concert on z/OS
Your next step is to install Rational Team Concert components on z/OS. You can get basic installation instructions from the IBM Knowledge Center. The installation checklist on this page guides you through a component installation. You can also use an ISPF-based configuration utility, which allows you to enter all your variables in one place, then generate a workflow of the components you wish to install. Using the workflow helps to ensure that you complete each installation step.
When you first open the installation, you might be a bit overwhelmed by the number of FMIDs it contains. If you are installing Jazz Team Server on a non z/OS platform, you actually only need to install a handful of them. Here are the FMIDs for Rational Team Concert v6.0.2.
Table 3. Required FMIDs for Rational Team Concert on z/OS
|HRCC602||Common components||SMP/E jobs; Configuration Utility; DB2 Unload/Reload jobs; Other common jobs and samples|
|HRBT602||Build toolkit||Build Toolkit; zImport; ISPF Client|
|HRBA602||Build agent||Rational Build Agent|
|HRDV602||Job Monitor||RDz Job Monitor (optional)|
Next, you might wonder what components are required. If you want to run z/OS builds, including compiles, assembles, link-edits, and so on, then you will need to install all of the above FMIDs, with the exception of the Job Monitor. If you already have RDz installed, Rational Team Concert will be able to use your current Job Monitor. Table 4 describes each component installed under the FMIDs in Table 3.
Table 4. Required components of a Rational Team Concert z/OS install
|Configuration Utility||An ISPF-based utility to help configuration. Contains an IVP to assist in installation problems.|
|Build Toolkit||A set of directories in the HFS containing jar files that are required by Rational Team Concert to drive the compiles and build activities.|
|zImport||Tool to aid the migration of code from a partitioned data set (PDS) into the Rational Team Concert repository.|
|ISPF Client||An ISPF-based dialog to perform source code management operations such as edit, check-in, deliver, and building z/OS-based artifacts.|
|Rational Build Agent||A process that runs on z/OS to provide communication with the Rational Team Concert Server so that code can be transferred to z/OS and processes run on this source.|
Step 3. Configure the ISPF gateway
Many processes can be executed directly by Rational Team Concert but some need to be executed from a REXX executable. For this you'll need to configure an ISPF gateway. The gateway can execute TSO/ISPF execs as build processes. While the ISPF editor and dialogue manager are standard parts of the installation, you might want an ISPF gateway configured just for Rational Team Concert. See the IBM Knowledge Center for configuration instructions.
Step 4. Configure Rational Team Concert components on z/OS
After you've installed all the required FMIDs you can configure the required components. The easiest way to do this is to use the ISPF-based Configuration Utility. After you've installed the utility, you can use the instructions on the documentation page to run the utility and configure your selected Rational Team Concert components for z/OS.
You should now have installed and configured Jazz Team Server and all the z/OS-based components you'll need to manage and build source code with Rational Team Concert. Next we'll look at various tools for managing source code in Rational Team Concert.
Source code management in Rational Team Concert
Mainframe source in Rational Team Concert is stored in a specific type of Eclipse project, called a zProject. Source code is usually stored in UTF-8 in Rational Team Concert. It is converted to EBCDIC when it's loaded to the mainframe for build, or through the use of the ISPF client.
Figure 4. Structure of a zProject
zProjects map to data sets and members in z/OS. zFolders map to data sets through the use of a data-set definition. zFiles map to members in those data set. In addition, zFiles are associated with a language definition, which tells Rational Team Concert how to build that member.
System definitions and build artifacts
Rational Team Concert does not use JCL (Job Control Language) to control builds. Instead, builds are driven by Ant-based tooling, ensuring that a common set of build tools can be used across z/OS and distributed platforms. You don't have to be familiar with Ant in order to use Rational Team Concert for source code management, however. Rational Team Concert provides wizards and dialogs that you can use to configure your system definitions and build artifacts. Table 5 describes the different types of system definitions that you will utilize in Rational Team Concert.
Table 5. System definitions in Rational Team Concert
|Data set definitions||Describes a data set and allows for a single definition within a repository. This can be an input data set, an output data set, an existing data set, or a temporary data set. During a build, if a data set does not exist, Rational Team Concert will use the definition to create it. This is similar to a DD in JCL.|
|Language definitions||A process that is associated to a part in order to build it. For example a COBOL compile may have two steps in the process: a compile step and a link-edit step. A language definition is similar to a JCL procedure with one or multiple steps.|
|Translators||Each step, for example a compile step, in a build process is called a translator. Think of a translator as a single step in a JCL procedure.|
In addition to system definitions, you will use wizards to create definitions that define the scope and location of a build. Table 6 describes two different types of build artifact.
Table 6. Build artifacts in Rational Team Concert
|Build definition||Defines to Rational Team Concert which components in a stream will be in the scope of the build and which language definitions are going to be processed, as well as the high-level qualifier where the source code is loaded and where build outputs will be generated. You can also use this definition to set build-specific properties.|
|Build engine||A definition on the server that points to the z/OS host and port where the Rational Build Agent is running.|
Creating system definitions
You can use Rational Team Concert's system definition dialogs to create data set definitions, language definitions, and translators, as shown in Figure 5.
Figure 5. System definitions in Rational Team Concert
When setting up your system definitions for the first time, it is best to use the system definitions XML. Working in the XML, rather than a dialog, allows you to modify and reload the definitions until they are complete. Definitions in XML can also be easily loaded onto another system.
See the Rational Team Concert Enterprise Extensions Build Administration Workshop to get the System Definition Toolkit and instructions for editing system definitions in an XML file. The workshop covers many aspects of build administration in depth, so we recommend taking the time to work through it. Note that you'll need a Jazz.net login to access the workshop.
Planning your source code migration
You have everything in place and a basic understanding of how to work with source code in Rational Team Concert. All that's left to do is migrate your code. A successful migration from a legacy mainframe source code management system to Rational Team Concert involves several planning stages. We'll conclude with an overview of the activities in each stage.
Before the migration
Define the structure of your streams
A stream can be thought of as a particular version of a product, or part of a product. For a dependency build to be successful, a stream needs to contain all the source needed to compile or build a resource—for instance, all the copybooks needed by a program. On the other hand, a stream does not need to include runtime libraries like CICS copybooks, which the build system will find on the build machine. It is tempting, but not a good practice, to define a large stream that contains everything. It is better to define smaller streams, scoped to applications or a set of related applications.
Define the structure of components in your stream
Component-based design is valid for every language. Put related artifacts or projects together so that components make sense from a variety of perspectives: code reuse, build operations, and team sharing. Consider the example of a public interface that is used by a number of different applications: if you're using streams scoped to a set of applications, it is likely that a stream will need to contain the public interface of an application contained in another stream. It's good practice to isolate the public interface in a dedicated component, which multiple parties can then access and use. In this setup you can also define and enforce how you'll share out and adopt new versions of the public interface.
Define the delivery flow
You'll want to define your process flow from development to delivery in production. You can do all the work in one stream, which over time matures and becomes ready to be declared GA (this is how we develop in Rational Team Concert), or you can define a hierarchy of streams (such as Prod, QA, Test, Dev) and establish criteria for promoting your code through the hierarchy.
Rational Team Concert supports both strategies, though its promotion functions are well-suited for a hierarchy. It's also possible to promote source-only or source and binaries. In the case of binaries, build metadata of the promoted parts are updated at the target level.
Identify your language definitions
Rational Team Concert's system definitions let you describe builds steps in one place only and apply them throughout the system. The first system definition you need to define is the language definition. In Rational Team Concert, a language definition will be associated with each buildable part.
When taking inventory of your legacy system, you will probably find more combinations of program types than you want to support in Rational Team Concert. It is important to reduce these combinations to the ones that are functionally relevant. The translators offer a mechanism called translator variables, that can be set at program level, and provide a way to manage exceptions (when for example a given program fits with a given language definition but requires an additional build option). It is also a good idea to define your system definition in a separate project area, that will then be visible to other project areas in the RTC Repository. This is useful if different project areas share similar build processes because it avoids duplication.
Tune the system definitions and your builds
Once you've defined your language definitions, you will iterate to make them really work by using a representative subset of the programs. Usually these steps occur on a test server. Once you are comfortable, you can export your system definitions, and import them in the production server where you'll run a more limited sniff test.
During the migration
Define the baselines that you want to import so that you can capture history in the Rational Team Concert SCMS. This will give you the ability to store a history of resources. More importantly, it will let you baseline components or take snapshots of streams, so that you can have a historical view of a system with all the resources in sync at that level. (As an example, the snapshot of release 23 of an application comprised of thousands of programs would contain the version of the sources used to build release 23.)
You should identify in your legacy source code management system which historical content you want to migrate in the Rational Team Concert SCM and which baselines are involved. All files don't have to be different between baselines. In case where they are identical, it's the same state of the file that will be shared between two baselines in Rational Team Concert.
Import a baseline from the legacy system into the right component or project
The SCM command line contains a command called
zImport on z/OS. zImport takes a mapping file as an input,
which allows you to define which files you want to import, where they
should go, and which language definition to associate to them. It is
important to tune the mapping file correctly in order to enforce rules for
the components you have setup.
Iterate to capture the needed history till the current version
The zImport API accepts an optional parameter, which is the repository workspace that has been used for the initial zImport. In order to create history and baselines in Rational Team Concert, you need to start with the older artifacts, put them in a set of partitioned data sets, and trigger the zImport. Then you'll replace these members with the next baseline, and trigger zImport with the same workspace. This will create the delta between the two baselines with the corresponding change sets. Iterate until you reach the current version.
An alternative to zImport is to use the ISPF Client to import a complete partitioned data set. The ISPF Client is out of the scope of this article but there are a number of tutorials and videos on Jazz.net discussing the ISPF Client.
Set translator variables
If you are dealing with exceptions, for example files that need a specific compiler option, then you'll need to setup a translator with a variable. The value of this variable needs to be provided by the appropriate files in the exception. See the z/OS documentation or the developerWorks blog post, "Using translator variables to control conditional processes" for more information about translator variables.
After the migration
Create your build definitions
A build definition describes to Rational Team Concert what to build. A z/OS Dependency build selects from a list of language definitions and will generate build scripts from them that will be run. The build definition defines the repository workspace that flows to the team stream containing the source code. The build definition contains the high-level qualifier where the source code is loaded and where build outputs will be generated. You can also set build-specific properties.
A build definition points to a build engine (type=Rational Build Agent). A build engine, with relation to a z/OS build, is a definition on the server that points to the z/OS host and port where the Rational Team Concert build agent is running.
The build agent, running on z/OS, is a task running in Unix System Services
that waits for requests from the build engine. This is the two-way
communication between the server and z/OS. The build agent, started by
startbfa.sh and configured by the configuration
utility, contains a Jazz userid and password. The repository workspace
must be readable by this build user.
Running your builds
After migrating your code to Rational Team Concert you can use dependency builds or simulated builds to generate build metadata for resources. A simulated build allows future dependency builds to only build parts that have changed since the migration.
Conclusion and next steps
This article has a number of links to documents and videos that should help you get started with Rational Team Concert. The best place to begin is to install and configure the recommended z/OS-based FMIDs, then work through the Rational Team Concert Enterprise Extensions Build Administration Workshop. The workshop will walk you through all aspects of setting up a test server on your desktop and configuring it to interact with your z/OS system.
- Installing Rational Team Concert
- Configuring Rational Team Concert for z/OS (four-part video series)
- Rational Team Concert Enterprise Extensions Build Administration Workshop
- Rational Team Concert for Application Lifecycle Management
- Try Rational Team Concert