IBM
RTCz Integration Specification
RDz Integrated Development Environment (zIDE)
Version <0.9>
Author: <Alex Akilov>
Owner: <Alex Akilov>
Status: <Draft >
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
Revision History
Date
Version
Description
Author
04/14/2009
0.7
07/27/2009
0.8
08/28/2009
0.9
Initial version (based on RTCz twiki version Alex Akilov
0.6)
Updated version based on actual
Alex Akilov
implementation at the end of Sprint 7
Incorporated comments from Rosalind
Alex Akilov
Radcliffe
Table of Contents
1.
2.
3.
4.
Introduction
4
1.1
1.2
1.3
1.4
1.5
4
4
4
4
4
Purpose
Scope
Definitions, Acronyms, and Abbreviations
References
Overview
Requirements
4
2.1
2.2
2.3
2.4
4
4
4
4
Enable source control capabilities for artifacts that RDz tooling works with
Preserve the z/OS developer’s conceptual model that the RDz product promotes
RTCz should be able to work standalone
Build and environment settings should be shared between RTCz and RDz
Architectural Decisions
5
3.1
3.2
Overview
Technical issues/challenges
3.2.1 Eclipse project model vs. RDz project model
3.2.2 More on the RDz user’s conceptual model
3.2.3 Maintaining source control metadata in local vs. z/OS sandboxes
3.2.4 Use of EFS (Eclipse File System) and linked resources
3.2.5 Containment vs. Reference and the clone problem
3.3
Design decisions
3.3.1 Rejected approaches/proposals
3.3.2 Accepted approaches/decisions
5
5
5
5
6
6
6
6
7
7
Detailed Design and Implementation
9
4.1
4.2
4.3
4.4
4.5
4.6
4.7
Integrated Development setup
4.1.1 Implementation and installation notes
RTC source control component implementation
RTCz source control extensions
RTCz File Agent
Load zFiles to z/OS operation
4.5.1 Load zFiles to z/OS – Implementation notes
Share members as z/Files operation
4.6.1 Share members as zFiles – Implementation notes
RDz content synchronization after share or load
IBM Confidential
IBM, 2016
9
10
10
11
12
12
13
18
18
22
Page 2
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
4.8
Performing various maintenance operations after share or load
24
4.8.1 Create a new artifact in RDz project
24
4.8.2 Remove from subproject on a managed member
24
4.8.3 Delete managed member or data set containing managed members from RDz project
24
4.8.4 Rename managed member from RDz project
24
4.8.5 Rename data set containing managed members (in MVS subproject or Remote System Explorer)24
4.8.6 Rename zFolder in zComponent project (or move linked zFiles to a different zFolder)
24
4.8.7 Rename Data set definition which zFolders in zComponent projects are pointing to
24
4.8.8 Modify data set name in data set definition which zFolders are pointing to
24
4.8.9 Create a new zFile in zComponent project
24
4.8.10 Disconnect a zComponent project from the SCM
24
4.8.11 Delete linked zFile in zComponent project
24
4.8.12 Rename linked zFile in zComponent project
24
4.9
Build Integration
24
5.
6.
Implementation Details
25
5.1
5.2
25
26
26
28
30
Known Limitations
Interfaces
5.2.1 Proxy interfaces
5.2.2 ResourceInfo interfaces
5.2.3 Build Property interfaces
Appendix A – Glossary of terms
31
6.1
31
31
31
31
31
32
32
32
6.2
6.3
6.4
6.5
Core Jazz/RTC terminology by Jazz/RTC component
6.1.1 Source Control
6.1.2 Team Build
6.1.3 Process Component
Eclipse Terminology
z/OS Terminology
RDz Terminology
RTCz Terminology
IBM Confidential
IBM, 2016
Page 3
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
Software Design Specification
1. Introduction
This document details the design of the initial integration between the RTCz and RDz products.
1.1 Purpose
The purpose of this document is to describe the architecture, usage scenarios, APIs and current limitations
for the integration of the RDz and RTCz products.
1.2 Scope
The design described in this document covers the RDz v7.6 and RTCz v2.0 products.
1.3 Definitions, Acronyms, and Abbreviations
RDz
Rational Developer for System z
RTCz
Rational Team Concert for System z
See Appendix A for a more complete glossary of terms.
1.4 References
zComponent project structure
RTCz Mass Import tool
1.5 Overview
The remainder of this document is intended to capture the RTCz and RDz integration design.
2. Requirements
This chapter lists the primary requirements that were identified for the first pass at RTCz and RDz integration.
2.1 Enable source control capabilities for artifacts that RDz tooling works with
Initial focus is on version control and builds of artifacts referenced in RDz remote projects
2.2 Preserve the z/OS developer’s conceptual model that the RDz product promotes
Source artifacts are expected to reside on z/OS, support remote debugging, remote syntax check, remote build, etc.
2.3 RTCz should be able to work standalone
A shop that does not have RDz installed should be able to collaboratively develop and build z/OS applications using
RTCz without requiring any additional tools. Furthermore, in a mixed shop where some developers have RDz and
others do not, it should be possible to use RTCz standalone against the same Jazz server that RDz users use without
being broken. Due to the much richer set of tooling that supports z/OS development in RDz, the user experience of
those using RDz in combination with RTCz will be richer than those trying to use RTCz standalone. However, the
RTCz tooling should be sufficient to be productive and get the job done.
2.4 Build and environment settings should be shared between RTCz and RDz
A user that uses both RDz and RTCz products should be able to define environment settings and build processing
using a single technique (vs. having to do it the RDz way and the RTCz way). RDz customers that use SCMs
typically expect that builds are defined using the SCM infrastructure and those should override the RDz build
infrastructure. Therefore, the expectation is that RTCz build and environment settings would override the RDz build
specifications. Furthermore, environment settings (such as SYSLIB) are used during various RDz operations (e.g.
remote syntax check, open copy member, show dependencies, content assist) and should also be specified using the
RTCz way for SCM managed artifacts.
IBM Confidential
IBM, 2016
Page 4
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
3. Architectural Decisions
3.1 Overview
This chapter describes the integration architecture between RDz remote projects and the RTCz build and source
control components. It lays out the integration challenges that the design iteations that culminated in the eventual
design decisions.
3.2 Technical issues/challenges
3.2.1 Eclipse project model vs. RDz project model
The Eclipse resource framework is essentially designed to work like a local file system. The root of the file system is
the workspace, underneath this root there are Eclipse Projects (which are folders that have a special metadata file in
them) and inside those project folders there are other folders or files.
The RDz project model for remote projects (RDz actually supports several different types of projects) is based on the
Eclipse resource framework but it introduces several extensions. For one, the notion of project and subproject
containment is introduced. Eclipse projects cannot contain other projects, however, in RDz, project containment is
simulated through the use of metadata. That is, z/OS projects and subprojects are actually implemented as Eclipse
projects which hang off of the workspace root just like regular Eclipse projects. However, the z/OS project contains
metadata which tells it which other Eclipse projects are “contained” within it. This containment is actually a logical
relationship and not manifested on the file system as true folder containment.
RDz has a special navigator view, called z/OS projects, that can display these logical containment relationships based
on the metadata and not the physical containment (which the standard Eclipse navigator or project explorer views
display).
Note that in order to display this logical structure, the actual physical layout on the file system is hidden from the
user’s view. This is accomplished by implementing filters on the standard Eclipse navigator and project explorer
views that hide the physical Eclipse projects that implement the z/OS project and subprojects.
The following diagram shows the logical view presented in the z/OS projects view vs. the actual physical layout of the
projects that is hidden from the user’s view.
Logical View (z/OS Projects)
Physical view (Eclipse Project)
3.2.2 More on the RDz user’s conceptual model
As mentioned above, RDz actually supports several different types of projects (most of which are implemented using
standard Eclipse projects but with a particular nature that enables some RDz functionality). However, for z/OS
application development, RDz attempts to act like “a better ISPF” to the traditional z/OS application developer. RDz
attempts to preserve the ISPF user’s expectation that their source artifacts are located on the physical z/OS (MVS) file
system in data sets but the RDz tool simply facilitates a better user experience (e.g. graphical navigation, mouse
gestures) than the command or menu driven facilities that are provided in ISPF. RDz provides sophisticated tools that
attempt to preserve this user experience by downloading files to the workstation for editing with an editor that can
simulate the ISPF editor and uploading them back seamlessly as needed without forcing the user to have to think about
where on their local file system (let alone which Eclipse folder) those artifacts should be downloaded to, or what code
page conversions should be done on them and so on. Therefore, remote projects are the recommended way for RDz
users to work with z/OS applications, even though, if they choose to, users can opt to develop z/OS applications
without using remote projects. An important point to remember is that remote projects are not containers of artifacts
IBM Confidential
IBM, 2016
Page 5
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
but simply contain metadata that is interpreted as pointers to the physical artifacts on the remote file system. As such,
the same physical artifact may actually appear multiple times in different RDz MVS subprojects since the latter
represent logical references to the actual physical artifact up on the host.
3.2.3 Maintaining source control metadata in local vs. z/OS sandboxes
See RTC source control component implementation for some background about how RTC source control works.
In order to support remote development, the concept of a remote (z/OS) sandbox needs to be introduced (either instead
of, or in addition to the local sandbox that RTC uses).
Files that you extract into your local sandbox are kept track of by the source control feature via metadata files in your
Eclipse workspace as well as by monitoring timestamp changes to the files in the sandbox. If we wish to extract files
to a sandbox on the z/OS (MVS) file system, and we want to be able to keep track of them in the same way files on a
non-z/OS sandbox are kept track of via Jazz source control, we must be able to store metadata about the files on the
MVS file system along with being able to retrieve information about modification timestamps and so on. One of the
ways the MVS file system manages files is in terms of libraries called Partitioned Data Sets (PDS). Partitioned Data
Sets can be subdivided into members that can be likened to files on a hierarchical file system. However, PDSs do not
allow extended attributes to be attached to each of these members as you could on some hierarchical file systems.
Things like file timestamps, type, code page info and not so easy to come by for PDS members. However, there is an
enhanced version of PDSs called PDS/E (for extended) which do support extended attributes. If RTCz wants to be
able to support timestamps and extended attributes for members on the MVS file system it must prereq PDS/Es data
sets for use in z/OS sandboxes.
3.2.4 Use of EFS (Eclipse File System) and linked resources
To accomplish the remote development user experience, RDz remote projects employ the Eclipse EFS framework to
be able to map a resource in the local Eclipse workspace to its physical/remote location. In Eclipse jargon, this
concept is referred to as Linked Resources. This also facilitates the ability to allow multiple MVS subprojects to
reference the same remote resource and keep all of the local versions of that resource in sync with the remote copy.
The Eclipse recommendation for Team Providers is to be “link friendly” (i.e. support version control for projects that
contain linked resources but disallow the version controlling of the linked resources themselves).
The core RTC source control implementation follows this recommendation. Therefore, any resources that aren’t found
physically inside the project are ignored when sharing the project to the source control system.
Additionally, the source control component in RTC also uses EFS to implement the Eclipse manifestation of source
controlled artifacts. Unfortunately, Eclipse only allows one EFS provider per resource, which means that any resource
in the workspace that is source controlled in RTC, cannot also employ EFS to point at remote resources on z/OS and
vice versa.
3.2.5 Containment vs. Reference and the clone problem
As mentioned above, RDz projects are essentially based on references to external resources (with a many to one
relationship), whereas RTC source control is effectively based on containment (i.e. 1-1). That is, you identify a
resource by its relative location within a component (i.e. based on the containment structure). Although, theoretically,
you can store the same file in multiple components in RTCz, the identity of these cloned copies is not preserved and
no attempt is made to keep their contents in sync (although there is an optimization based on a hash performed on
large binary files that allows storing a single copy of the file contents pointed to by multiple components).
This makes it very difficult to take an RDz MVS subproject as is and persist it in the RTC source control structure.
You could convert the subproject into a container and import all of the members it references under this containment
structure prior to storing it into the SCM and then convert it back to references when you extract it back out.
However, due to the cloning issue you would end up with many copies of the same member in different places in the
SCM and you will quickly get into a major maintenance problem trying to keep all of those copies in sync.
3.3 Design decisions
There were quite a few iterations on the design of the integration between the RTCz and RDz products. This chapter
attempts to summarize some of the stepping stones that led to the eventual design.
IBM Confidential
IBM, 2016
Page 6
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
3.3.1 Rejected approaches/proposals
3.3.1.1 Use of EFS in RDz v7.5 projects to support Source Control Providers
RDz v7.5 introduced a new RDz project model that would be source control system friendly by being based on EFS.
The goal was to be able to share RDz remote projects (online or offline) directly into a source control provider.
Unfortunately, this turned out to be a non-starter once the issue of RTC not supporting persistence of linked resources
surfaced.
3.3.1.2 Data set Source Control components (or projects)
The next revision was based on the idea that since RDz is essentially a reference based project model, that RTCz will
manage data set members in a container structure (i.e. a source control component that is “tagged” as a z/OS data set
or a PDS project) and the RDz references could then be stored as references to this data set container. The argument
against this approach was that modern source control systems should not try to mimic the data set based organization
of artifacts and focus instead on a more natural grouping of artifacts centered on componentization of applications and
subsystems.
3.3.1.3 Use zComponent Projects as MVS subprojects
RTCz 2.0 introduced its own Eclipse project structure called a zComponent project. This project was designed to
support the standalone RTCz develop and build z/OS artifacts scenario but also to make it possible to integrate with
RDz. Originally, it was thought that RDz projects could consider zComponent projects as if they were subprojects.
However, the containment vs. reference issue mentioned above caused this idea to be dropped since it would alter the
RDz user experience too drastically and violate the second requirement.
3.3.2 Accepted approaches/decisions
3.3.2.1 Listening to the local sandbox and three way synchronization
The next stage in the evolution of the design (this one was adopted in the eventual solution) was to enhance the RDz
project model so that it could “listen” to a local sandbox location of “managed” artifacts in addition to the remote
copies that it already knows how to listen to. A three way synchronization scheme would be designed that would
allow RDz to detect changes on either the remote or local sandbox and propagate those changes to the other sandbox.
RTCz would be responsible for extracting both local and remote copies of the artifact from the repository and then tell
RDz to start listening to both local and z/OS sandboxes.
Note that since we’re treating the files on the z/OS file system as a sandbox, it should be understood that artifacts on
the z/OS file system that are managed in the SCM should be considered transient and can effectively be wiped out
from the file system and recreated as needed from the SCM. Furthermore, to support the optimistic locking model,
users would have their own sandbox (specified via a personal data set prefix) which should be reserved for their
exclusive use for a particular repository workspace. RTCz 2.0 will not support conflict resolution when two copies of
the same named file are loaded (e.g. from two different projects or repository workspaces) into a z/OS sandbox.
3.3.2.2 Links between zComponent artifacts and MVS subproject artifacts
To avoid confusion between when a zComponent project should be used vs. when an MVS subproject should be used,
we must differentiate between the role of RDz projects and zComponent projects. Since it was agreed that the two
projects have different purposes (RDz projects being a working set vs. zComponent projects being a componentization
and version control vehicle) it was decided that the right way to integrate between them is to introduce links between
the artifacts in the two projects. These links will be specified using two new wizards: Share members as zFiles and
Load zFiles to z/OS. The links are persisted in the Eclipse workspace as persistent properties so that they can be
reestablished the next time the workbench is restarted. However, if a different Eclipse workspace is used, the RDz
projects and links will all have to be reconstructed from scratch.
3.3.2.3 Data set prefix (sandbox) and the need to specify a build context when linking zFiles to MVS subprojects
RTCz metadata is actually split across several different model elements which are combined and interpreted together
during a build. These model elements include data set definitions, language definitions, translator definitions and
build definitions, among others. The build definition is actually the binding mechanism that provides the necessary
context to put all of the other constructs together. For one, data set definitions contain a partial data set name to which
IBM Confidential
IBM, 2016
Page 7
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
a prefix should be added. This prefix is specified in the build definition construct as a build property called
teamz.scm.dataset.prefix. Second, translator definitions can contain symbolic placeholders (variable substitution
parameters) that reference data set definitions symbolically rather than explicitly. Again, the build definition construct
contains the resolution values for these placeholders (implemented as build property key value pairs).
Lastly, to satisfy the build integration requirement, RTCz is expected to request an RTCz build (and specify which
build definition to use) when RDz’s build operation is invoked and the RDz project contains SCM managed artifacts.
Although the latter could be accomplished by prompting for the build definition each time a build is requested, the fact
that the dataset.prefix property is also defined in the build definition, makes it reasonable to simply prompt for a build
definition (or rather a personal, customized build request) when the linking between zFiles and RDz projects is made
(i.e. during the Share or Load wizards). This build context can be customized by the user (i.e. the build property
values can be overridden from the defaults retrieved from the build definition) the first time through the wizards for a
particular repository workspace. However, since the data set prefix property effectively establishes the z/OS sandbox
that is in use for that repository workspace, once the sandbox is live and in use, it’s best to keep the prefix (and hence
the location of the sandbox on z/OS) static for the duration of the RDz “session”. By “session” we mean from the time
artifacts from a repository workspace are associated with an RDz project until there are no longer any artifacts from
the repository workspace that are associated with an RDz project in the workspace (i.e. all artifacts from the repository
workspace were “disconnected” from the RDz projects that referenced them).
The build properties that the user specified in the build context are stored in the Eclipse workspace as persistent
properties and are reused the next time the user attempts to invoke either the load or share wizards to incrementally
link additional artifacts from the repository workspace to RDz projects in their Eclipse workspace.
3.3.2.4 Local sandbox contents vs.z/OS sandbox
Since the links between MVS subproject artifacts (members) and zComponent artifacts (zFiles) are on a per artifact
basis, there is a bit of a disparity between what gets loaded into the local sandbox and the remote z/OS sandbox. To
preserve the integrity of the zComponent project (and the metadata it contains), we must always load the full
zComponent project into the local sandbox and treat the zComponent project as a whole. Note that RTC allows
loading partial project contents (e.g. folders) into the local sandbox, but the RTCz load to z/OS wizard will not allow
that. As for the z/OS sandbox, it will only contain the actual sparse members that have been linked to the MVS
subproject (i.e. the folder containment structure in the zComponent project is not replicated on the MVS file system).
3.3.2.5 Using the RTCz File Agent to populate the z/OS sandbox
RTCz 2.0 introduces a special type of SCM client running on z/OS called File Agent. This client is somewhat limited
in terms of SCM capabilities (i.e. it doesn’t support two way synchronization between the z/OS file system and the
SCM) but it does support extraction of SCM artifacts into the z/OS file system as well as importing of z/OS file system
artifacts into the SCM. Although we could have used the Eclipse client as a means of populating the z/OS sandbox
(i.e. load the artifacts into the Eclipse workbench and then push them to the z/OS sandbox), to avoid the possible round
tripping problem that may occur if the SCM was located on z/OS and save bandwidth (and to leverage the File Agent
which is needed anyway to facilitate builds on z/OS), it was decided that we would use the File Agent to populate the
z/OS sandbox during the load to z/OS operation.
Since the File Agent does not use the standard RTC SCM load operation to load members, we must somehow
communicate the list of sparse members we wish to have the File Agent load. Since each file that we need to load has
to be described using multiple attributes (e.g. repository workspace ID, data set prefix, component name, data set
definition ID, path to the file within the component), it was decided that the best way to specify these attributes would
be via an XML format as described in the Implementation Details chapter.
Note that the counterpart Share operation would not use the File Agent and would download the files being shared to
the workstation (using RDz) and then push the files being shared into the SCM using the standard SCM check-in and
deliver operations.
3.3.2.6 Handling of file extensions
The MVS file system does not support defining file extensions on members in partitioned data sets. The member
name is restricted to be at most 8 single byte characters and cannot contain special characters such as a dot. Since
Eclipse keys off the file extension to decide what type of editor to open on a file, RDz allows annotating remote files
using a file extension. This information is kept in RDz metadata and is not attached to the actual physical artifact on
IBM Confidential
IBM, 2016
Page 8
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
z/OS. Furthermore, RDz allows defining default file extension mapping rules that automatically assign an extension to
a member in a data set based on some portion of the data set name. For example, one such rule says that if the data set
name contains the word COBOL, that any member within that data set should automatically be assumed to have a .cbl
extension. In RTCz, a file extension is a perfectly legal part of the zFile name, however, and can be persisted with the
zFile in the SCM. However, when the file gets loaded to z/OS, this extension gets stripped off by RDz and the
member gets assigned an extension based on the RDz data set mapping rules.
3.3.2.7 Summary of accepted decisions
 The SCM will be pre-populated using the RTCz mass import tool. Import can be done from PDSs.
 Artifacts (zFiles) will be extracted from the SCM to the local sandbox and the remote sandbox using a new SCM
Load operation (Load Files to z/OS). Only PDS/Es are supported in remote (z/OS) sandboxes (not PDSs).
 There will be a way to add new “unmanaged” members to be under SCM control (Share members as zFiles)
 RDz will maintain a registry of local sandbox and remote sandbox artifacts that are “linked” and will listen on
changes that occur to either of those, synchronizing changes from one sandbox to the other as needed. This
includes maintenance operations such as content changes, renames, deletes, and moves.
 Build properties such as compile options or the SYSLIB concatenation will be retrieved from RTCz as needed by
various RDz functions. Furthermore, any RDz projects that contain shared (linked) artifacts will delegate project
build requests to RTCz’s build infrastructure. However, computing build dependencies (which is needed for
various RDz operations such as content assist, syntax check, show dependencies, open copy member) will not
happen automatically yet in this release since it depends on dependency metadata gathering which RTCz does not
yet implement. See Build Integration in the detailed implementation chapter that explains what needs to be done
until smart build is supported in RTCz.
 For now, persistence of the “working set” information will be deferred. That is, the actual physical RDz project
and subproject will not be source control managed and will only exist in the Eclipse workspace. See Known
Limitations.
4. Detailed Design and Implementation
4.1 Integrated Development setup
When you co-install the RTCz and RDz products into the same Eclipse shell, you get all of the power of both products
including the Eclipse source control client and the RDz remote project tooling in the same workbench. Furthermore,
the RTCz extensions such as zComponent projects, data set definitions, language definitions are also available to RDz
to interact with.
Taking advantage of the additional integration feature (see Integrated Client Installation) allows RDz to provide a
working set view for a subset of the zFiles in the SCM managed zComponent projects as illustrated in the following
diagram:
IBM Confidential
IBM, 2016
Page 9
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
Eclipse Workspace
RDz project
area
RTCz Local
Sandbox
RTCz SCM
zComponent1
Component A
EPSCMORT.cbl
z1
zComponent2
Component B
z2
EPSMDRVR.cbl
Note that the RTCz local sandbox isn’t necessarily visible to the user if they are working exclusively in RDz’s z/OS
projects perspective. However, if they open the Project Explorer view (e.g. if they are working on cross platform
applications and have some Java or web projects that they need to work on as well), they will see the zComponent
projects that contain the full set of zFiles in the zComponent (i.e. not just the ones in the RDz working set) in the
Project Explorer view.
4.1.1 Implementation and installation notes
The separately installable RTCz/RDz integration feature provides contributions to the new team API that RDz v7.6
introduced (see Interfaces). Furthermore, this feature includes the two new wizards that allow members from MVS
subprojects to be added as zFiles to zComponent projects or zFiles that are under SCM control to be added to an MVS
subproject (which, under the covers, loads a remote copy of the zFile and points the MVS subproject to it). This
feature also includes the z/OS hyperlinks feature which allows work items in RTCz to create references to MVS
artifacts (not covered in this specification). If RDz is installed, the MVS artifacts referenced by these hyperlinks can
be opened in the Eclipse workbench directly. Lastly, this feature includes the RSE client that is used to communicate
to the File Agent RSE miner which is installed and configured on the z/OS system as part of the RSE server.
On the z/OS system, you will need to install the RTCz toolkit and configure it to plug into the RSE server that is
installed as part of RDz. See z/OS (toolkit) installation and configuration. The RTCz toolkit includes the File Agent
along with multiple front ends to it that allow it to be invoked from the command line, as a Java library or from the
Remote System Explorer daemon through a contribution to the RSE miner extension point. That is, RTCz provides a
File Agent Miner which can be used to contact the File Agent through the RSE transport layer.
4.2 RTC source control component implementation
At this point, a quick review of the core RTC source control component implementation is in order.
The source control feature in RTC is based on a checkout model and is designed to support parallel development using
optimistic locking. The source control component is designed as a client/server application. The client can either run
in the Eclipse workbench, or as a command line client, and with some limitations in the web browser or Visual Studio
IDE. Although the Java client/server API is used extensively in the source control component and this will likely
remain so from now on, the primary API that’s supposed to be used by clients for new function is the RESTful API
(available as of RTC 2.0) so that you can write other SCM queries from other tools or programming languages.
Furthermore, the API is divided into a low level source control API and a higher level File System Client API (there
are actually additional layers on top of this which RTCz does not use so we’re not listing them here). Note that RTCz
consumes but does not extend these APIs.
IBM Confidential
IBM, 2016
Page 10
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
The high level constructs and operations that the source control component manages are illustrated in the following
diagram:
The streams, components and repository workspaces are maintained in the source control repository itself. The Load
and Check-in operations are the mechanism through which you can interact and modify the artifacts in a sandbox
which is external to the repository. Furthermore, an Accept operation into a repository workspace also refreshes the
copy of the artifact in the external sandbox (local workspace) if the artifact has been previously loaded. A Share
Project operation (not listed in the diagram) is another way of adding or synchronizing an Eclipse project from the
external sandbox into the SCM. The Load operation can load a whole repository workspace, a subset of components
from within it, a folder within a component (or project) or a single file from a managed folder (if you use Load As).
The Share Project operation always operates on a whole Eclipse project. There is currently no other way to “Share”
artifacts other than whole Eclipse projects to the repository using the Eclipse source control client facilities.
The SCM is designed to operate using an optimistic locking model. This means that multiple users can load the source
base and modify it in parallel. If, in the meantime, someone delivered some changes to the stream, you can choose to
Accept those changes into your repository workspace and merge them with the changes you’ve been making, if
necessary. RTC 2.0 also supports pessimistic locking through a new Lock file operation.
4.3 RTCz source control extensions
As mentioned earlier, RTCz does not really extend the RTC source control component but introduces additional client
side usages of the core RTC source control and file system APIs. One such usage is the additional type of Load
operation (Load zFiles to z/OS). The new Share members as zFiles and Disconnect member from zFile operations do
not perform any direct SCM interactions. The actual remote load operation is performed through the RTCz File Agent
which implements a sparse loading operation on individual zFiles but allows them to be extracted directly into MVS
data sets as members. The File agent is also a user of the core RTC File System and source control APIs.
IBM Confidential
IBM, 2016
Page 11
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
4.4 RTCz File Agent
RTCz provides a variation on the command line SCM client which runs on z/OS, called File Agent (which is packaged
as part of the RTCz toolkit SMP/E installable package). However, although the File Agent can run as part of the SCM
command line client as a standalone utility, it can also be used as a Java library and called directly from any Java
application running on z/OS (USS) such as the RTCz build toolkit or the RSE server that is installed as part of RDz.
Note that File Agent is not a full featured SCM client. It can perform Share Project (during Mass Import) and Load
operations (full workspace load or sparse load) but it does not support Accept and Check-in operations. Furthermore,
it does not yet maintain any repository metadata about the extracted resources (i.e. so they can get checked back in) so
it does not behave as a true RTC SCM client in that respect either.
When used through the RSE interface it can be contacted from the client which can pass it an XML stream that
contains a list of files that it needs file agent to load (sparsely).
Here’s an example XML stream that contains directives to load 2 files from a repository workspace:
<?xml version="1.0" encoding="UTF-8"?>
<operations>
<loadFiles dataSetPrefix="U21.BLD" workspaceUUID="_vKV-cGD1Ed6JPsdAdwErlg">
<file componentName="TComp" dataSetDefinitionUUID="_8ZYWIGD2Ed6qVsasYnwCdw"
filePath="/Mortgage/zOSsrc/Cobol/EPSMLIST.cbl"/>
<file componentName="TComp"dataSetDefinitionUUID="_8ZYWIGD2Ed6qVsasYnwCdw"
filePath="/Mortgage/zOSsrc/Cobol/EPSNBRVL.cbl"/>
</loadFiles>
</operations>
4.5 Load zFiles to z/OS operation
The Load zFiles to z/OS operation is one of the primary integration points between RTCz and RDz. The way it works
is as follows:
The user initiates the Load to z/OS request.
The wizard comes up and prompts for the list of files to load and the target MVS subproject as well as the build
context (more on that later) and target data set prefix.
When the wizard finishes it performs a three step load operation:
1. Load the zComponent projects of the selected artifacts from the SCM into the Eclipse workspace
2. Construct the XML stream containing the list of selected artifacts and upload it to the File Agent, waiting for
it to populate the z/OS sandbox with the requested artifacts.
3. Once sandbox is ready, notify RDz of the local zFiles and remote members to add to the target subproject and
start listening on.
The following diagram illustrates the sequence of steps that occur when the load to z/OS operation runs:
IBM Confidential
IBM, 2016
Page 12
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
z/OS dev LPAR
4
F1
F1
F1
3
File Agent
on MVS
2
6
5
Repository Workspace
1.
2.
workstation
RDz client
RTCz SCM
1
RTCz client
6
3.
4.
5.
6.
RTCz client loads files from SCM to
Eclipse workspace
RTCz client sends request to File Agent
to load files remotely
File Agent retrieves files from SCM
File agent creates appropriate PDSE’s
and loads the members
RTCz client notifies RDz that local and
remote sandboxes are ready
RDz sets up listeners to remote and
local copies of files
4.5.1 Load zFiles to z/OS – Implementation notes
The Load operation is driven by the new Load zFiles to z/OS wizard.
In order for the user to be able to take advantage of the RDz remote development, debug and build facilities, they
would add their managed SCM members to z/OS projects/subprojects using this wizard and from then on, they can
continue working with those artifacts like they normally would using the facilities RDz provides.
This wizard mimics the standard RTC load wizard which loads the contents of repository workspaces into the Eclipse
workspace (or local sandbox). The difference is that this wizard specializes in loading zComponent projects but even
more specifically the zFiles inside those zComponent projects that you want to associate with an MVS subproject.
For this release, we will assume that the z/OS project and subproject must have been created prior to invoking this new
wizard.
There are several places where this wizard can be invoked from:



Everywhere where the load operation is available (e.g. team artifacts navigator->my workspaces->Context
menu over workspace or component, repository workspace editor drop down at the top or component context
menu, but probably not from the pending changes view).
In the Project Explorer inside a zComponent project
In the RDz z/OS Projects explorer inside an MVS subproject
The wizard needs to gather the following information:






IBM Confidential
Source Repository Workspace
Source Component
Source zComponent Project
Source zComponent artifacts (zFiles)
Target MVS subproject
Build Context
IBM, 2016
Page 13
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
Part of the above information is pre-filled based on the context that the wizard is invoked from. For example, if you
launched the Load action from a zComponent project already in the Eclipse workspace, then the wizard can skip the
steps required for selecting the zFiles and go directly to the target MVS subproject page.
Note that a zComponent project in the Eclipse workspace that isn't shared to the repository will not be allowed to
participate in this loading scheme. We would gray out the menu action in this case.
Note: as of this writing, it’s only possible to launch the load wizard from a repository workspace or component (within
a repository workspace) context (e.g. from the Team Artifacts Navigator, or from the repository workspace editor’s
drop-down menu). If you started from a component, the first page of the wizard will only display the zComponent
projects in the selected component.
If loading from the repository workspace, the wizard would let you drill down into the SCM component from which to
choose your zComponent Projects from. Under the SCM component the wizard will display the zComponent projects
within it and allow you to select zFiles within those projects to Add to your MVS subproject (and thus load them to
z/OS).
The first page of the wizard allows you to choose the zFiles in the zComponent project.
a selection of a folder is simply a fastpath for choosing all of the members within that folder. The folder itself is never
added to the MVS Subproject since it’s a phantom fragment of a data set that the zComponent project uses as a
componentization mechanism.
If any of the zFiles that you’ve chosen to load already exist in your Eclipse workspace, the next page of the wizard will
prompt you to confirm whether to overwrite those files.
IBM Confidential
IBM, 2016
Page 14
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
Next, the target MVS subproject must be specified. At this point, we require that the RDz project and subproject must
have been pre-created in your Eclipse workspace. The next page of the wizard simply presents a list of the existing
RDz projects and subprojects in your Eclipse workspace. In future releases we can add additional buttons to create a
new z/OS Project and MVS Subproject on the following wizard page (unless we decide to deprecate this wizard in
favor of a more powerful way to instantiate MVS Subprojects directly based on dependencies).
Once the target MVS subproject is chosen, we need to establish the build context (if going through the load or share
wizard for the first time for artifacts in this repository workspace). Again, if any zFiles from the chosen repository
workspace have already participated in a Share or Load zFiles operation, this build context will be pre-filled (it’s
stored in the Eclipse workspace as persistent properties keyed by the repository workspace) and you will not be
allowed to override it. If you ever do need to override it, you will need to choose the Disconnect member from zFile
menu action for all members in any MVS subproject in the Eclipse workspace that are associated with zFiles that are
IBM Confidential
IBM, 2016
Page 15
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
shared to the repository workspace that the build context is associated with. Starting from a fresh Eclipse workspace is
another, more drastic, alternative to be able to specify a new build context for your repository workspace. Also, you
can create another repository workspace and have a different build context (and prefix) associated with it, although it
can have the same exact contents as your original repository workspace.
Finally, the wizard computes the full z/OS file names of the zFiles based on the prefix specified in the associated build
context and the data set names specified in the data set definitions associated with the zFolders.
At the end of the wizard, the following conditions should exist:
The zComponent projects that contained the selected zFiles are loaded into the Eclipse workspace and are visible in
IBM Confidential
IBM, 2016
Page 16
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
the Project Explorer view (if it is open). In this case, the zFolder MortgageLoad was associated with the data set
definition
In this case, the LoadTest zComponent project contains a zFolder named MortgageLoad. This zFolder was associated
with the data set definition COBOL, which has a data set name of COBOL as follows:
The data set prefix from the build context is added to this data set name at allocation time so that the member that gets
created on z/OS is USER21.DEV.COBOL(EPSCMORT). The extension is actually an RSE/RDz feature that allows
tagging z/OS members with a file extension (if you view the member in ISPF this extension will not exist there).
The z/OS sandbox, pointed to by the data set prefix specified in the build context that was selected during the wizard,
contains newly allocated data sets whose name is computed as described above.
The MVS subproject contains references to the members in those data sets that were loaded to z/OS by the load
wizard.
IBM Confidential
IBM, 2016
Page 17
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
Note that the members themselves are added to the MVS subproject as “sparse” members (i.e. not inside their
containing data set). A future enhancement might be to give users the choice on whether they want the sparse members
to be added to the subproject or the whole data set. The latter is actually the preferred method of working in RDz
especially when dealing with lots of members in lots of different data sets. If you add a whole data set, the members are
neatly organized into folders inside the MVS subproject which makes it a bit easier to find needles in a haystack (you
can choose to collapse the data sets whose members you don’t want to see). In today’s implementation, a user may
choose to manually drag the container data set from the RSE view to the subproject after the load wizard completes to
accomplish this. However, it would be nice if this was optionally done for the user automatically by including a
checkbox to that effect in the Load wizard (and RDz providing an extension to the API to accept a boolean value
indicating that the whole data set should be loaded).
4.6 Share members as z/Files operation
The Share members as zFiles operation allows adding unmanaged members to zComponent projects and thus, by virtue
of the zComponent project being version controlled in the SCM, the member becomes version controlled as well. The
intent is to use this operation to make incremental additions to the SCM after a load to z/OS operation has been
performed and established your working set.
The following diagram illustrates the sequence of steps that occur during the Share members operation:
RTCz SCM
z/OS dev LPAR
Repository Workspace
RSE Server
(RDz)
F1
F1
F1
2
workstation
3
4
1.
2.
3.
RDz client
1
RTCz client
4.
RTCz provides RDz with list of members
to download
RDz sends request to RSE server to
download the files
RSE server downloads files to specified
zComponent folders and starts listening
on them. It also moves or copies them
to correspond to the specified data set
prefix
zComponent project is shared to SCM,
if needed
4.6.1 Share members as zFiles – Implementation notes
The Share operation (similarly to the Load operation) is driven by the Share members as zFiles wizard.
Also, like the Load wizard, this is a multi page wizard. It needs to gather the following information:
 Source members from an MVS subproject to add to source control (share).
 Target zComponent project to which you wish to add the members.
IBM Confidential
IBM, 2016
Page 18
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>

If the zComponent project is not yet shared to the repository, also need target repository, repository
workspace and component to which you wish to share the zComponent project.
 The build context and data set prefix that will be used to populate and process the z/OS sandbox.
In the z/OS Projects perspective, z/OS Projects view, user selects some artifacts from MVS subprojects and chooses
zComponent->Share members as zFiles from the context menu. In this release, your selected items will all go to a
single target zComponent project per invocation of the wizard.
A view showing the structure of the subprojects is presented letting you choose which additional members you want to
include in the selection. Selecting a folder (such as a project or subproject or data set) effectively means that all of the
members contained in that container are selected. Note that members in the MVS subproject that have been previously
added to a zComponent project are filtered out of the list of available members to Share.
The next page of the wizard allows you to choose an existing zComponent project in your Eclipse workspace or the
option to create a new zComponent project. Note that if the target zComponent project is already shared to the
repository, it is annotated with the repository workspace that it’s shared to.
If the zComponent project you’ve selected hasn’t been shared yet to the repository or is new, there will be an
additional page shown in the wizard to gather the info about where in the repository to share the project to:
IBM Confidential
IBM, 2016
Page 19
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
The next page of the wizard is the build context page which is identical to the page shown by the load wizard. If the
build context was previously associated with the repository workspace, this page of the wizard will be disabled this
time around.
The next page of the wizard gathers data set associations and language definition associations to the members being
shared. The first table shows a summary of all of the data sets from which members are being shared. You are asked
to select a data set definition (by clicking the browse button on the right for each row in the table, as there may be
multiple different incoming data sets depending on how many different data sets you’ve selected members to share
from). The data set definition you select for each incoming data set will be translated into a zFolder inside the
zComponent project that you’re sharing members to (and the zFolder will be associated with that data set definition).
In the second table, you are presented with the list of zFiles that will be created in the zComponent project and you are
given a choice (not yet implemented as of this writing) to choose a language definition for each member in a similar
manner to how you choose data set definitions in the first table.
IBM Confidential
IBM, 2016
Page 20
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
The Copy members into new data sets checkbox toggles whether the members that are being shared will be copied into
the new z/OS sandbox location (based on the specified prefix in the build context) or moved there (i.e. deleted from
their original data set).
The last page of the wizard is, again, an overwrite confirmation page. It is only shown if the members being shared
will conflict with the names of existing zFiles in the target zComponent project.
At the completion of the wizard, the MVS subproject contains the new data set in the z/OS sandbox that got created
(possibly, if the managed data set name didn’t exactly match the original name).
IBM Confidential
IBM, 2016
Page 21
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
Notice the decorator, indicating that you have an outgoing pending change to the repository workspace.
The target zComponent project (visible in the Project Explorer view, contains the newly added zFolders and zFiles as
follows:
The decorators on the folders indicate that there are outgoing changes in the zComponent project that should be
checked into the repository workspace. The project itself got shared to the repository workspace and the zFolder got
associated with the COBOL data set definition and the shared zFile got associated with the chosen language definition.
4.7 RDz content synchronization after share or load
Once members are shared as zFiles or loaded to z/OS (i.e. a link is created between the RDz logical resource and the
RTCz physical zFile), the following diagrams illustrate the internal workings of how synchronization is handled by
RDz.
IBM Confidential
IBM, 2016
Page 22
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
IBM Confidential
Version:
0.9
Date: <21/08/2009>
IBM, 2016
Page 23
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
4.8 Performing various maintenance operations after share or load
4.8.1 Create a new artifact in RDz project
If you discover after starting to work on your working set that you must create a new source member that doesn’t exist
in the SCM yet, you would add a new member to your data set and MVS subproject. If you wish to add this member
to SCM control, you must explicitly run the Share members as zFiles wizard to add the new member to a zComponent
project and manage it as part of that project.
4.8.2 Remove from subproject on a managed member
Not enabled. Must first use Disconnect member from zFile action and then you can remove or delete the member
from the RDz subproject without affecting the SCM.
4.8.3 Delete managed member or data set containing managed members from RDz project
Will also delete corresponding zFiles in the zComponent project and show up as a pending outgoing delete of the
zFiles in the pending changes view.
4.8.4 Rename managed member from RDz project
Will also rename corresponding zFile in the zComponent project and show up as a pending outgoing rename of the
zFile in the pending changes view.
4.8.5 Rename data set containing managed members (in MVS subproject or Remote System Explorer)
This operation is grayed out in RDz if the data set contains any members that are managed in the SCM. If you are able
to rename the data set somehow (e.g. through RSE explorer or ISPF), RDz will detect the change and present the new
name in the subproject. However, the new name will not be propagated to the SCM (or zComponent project).
4.8.6 Rename zFolder in zComponent project (or move linked zFiles to a different zFolder)
RDz listener should detect renames of shared zFiles and update its internal shadow file registry. If zFiles moved to a
new zFolder that has a different data set definition associated with it, no updates are made to the z/OS sandbox and the
members remain in the original data set.
4.8.7 Rename Data set definition which zFolders in zComponent projects are pointing to
No effect since zFolders only know the UUID of the data set definitions and not their names
4.8.8 Modify data set name in data set definition which zFolders are pointing to
zFiles that have been previously shared will not be made aware of the change and their existing copies in the z/OS
sandbox will still exist in the old data set. However, future loads from zFolders that point to the changed data set
definition will go to the new data set.
4.8.9 Create a new zFile in zComponent project
Will show up as an outgoing addition in the pending changes view. However, to add it to your MVS subproject
(working set) you must use the Load zFiles to z/OS wizard to add it explicitly to the subproject and the z/OS sandbox.
4.8.10 Disconnect a zComponent project from the SCM
No effect on RDz. RDz will continue to update the zFile in the zComponent project in the Eclipse workspace. Once
the zComponent project is shared to the SCM again (using the Team->Share Project action) the updated contents of
the zComponent project will be used to synchronize against the SCM copy.
4.8.11 Delete linked zFile in zComponent project
Corresponding member in the MVS subproject and z/OS sandbox will be deleted.
4.8.12 Rename linked zFile in zComponent project
Corresponding member in the MVS subproject and z/OS sandbox will be renamed.
4.9 Build Integration
RTCz also provides syntax check and build services for RDz when members in RDz subprojects are associated with
IBM Confidential
IBM, 2016
Page 24
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
zFiles.
Syntax check and content assist are handled as follows:
Until RTCz smart build is available, you are required to pre-populate your sandbox or set up your variable
substitutions in a way that will allow you to find the dependencies that the code in your RDz subprojects depends on.
That is, if you are working on a cobol program which has dependencies on some copy members and your copy
members are not in your RDz subproject, you have to make sure that your SYSLIB is configured in such a way that
when your program is syntax checked or its dependencies are searched for for content assist or show dependencies,
that the copy members are found somewhere in the SYSLIB you've specified. One way to do this is to run a build on
the repository workspace that is pointing at your data set prefix (z/OS sandbox) prior to starting your RDz
development session. Another way to do this is to create another RDz subproject that contains associations to all of
your dependencies and then leave that RDz project alone. If there are incoming changes to those members, the second
RDz project will reflect the changes to your z/OS sandbox but that will free you on focusing on your primary RDz
project which will include your actual working set.
When you choose the Remote Syntax check action for your program, RTCz is asked to compute the associated
SYSLIB for that program. RTCz looks up the language definition associated with that program and searches for a
translator in the language definition that is tagged with a checkbox that identifies that translator as the one that should
be used for Syntax Check. This translator's DD concatenations are scanned to find the SYSLIB and it is used to search
for the dependent copy members. The compile options specified in the translator are also returned to RDz so that it can
use them to perform the Syntax Check. Lastly, the other DD concatenations specified in the translator are composed
into an "Additional JCL" string that RDz submits along with the Syntax Check command.
As for Build, if there are shared members in the RDz subproject, RDz's build is delegated to RTCz. RTCz reuses the
build context that was specified for the repository workspace to which the members in the subproject are shared and
submits a build request for that repository workspace. Prior to this happening, the user is expected to commit all of
their changes to their repository workspace since the build runs against the repository workspace. The build is
submitted with the user's repository workspace and prefix as specified in their build context. No attempt is made to
retrieve the build results in the format that RDz expects and the user is expected to go to the RTCz build results page,
find the build that they submitted and inspect the results in the way RTCz returns build results.
5. Implementation Details
5.1 Known Limitations







Dependencies of working set members must currently be preloaded into the z/OS sandbox manually by the user.
This should be automated once dependency metadata (part of smart build) is available.
Share wizard requires that target zComponent project must be in the Eclipse workspace prior to being able to add
members to it. It should be possible to share the members directly to an existing zComponent project that is in the
repository workspace but isn’t yet loaded into the SCM (the share operation would then load the zComponent
project into the Eclipse workspace much like the load operation does currently)
Share wizard does not prompt to create a new repository workspace, new component, or a new folder to share the
zComponent project to (if project is previously unshared).
Load wizard requires that the target RDz project and MVS subproject must have been pre-created prior to
launching the Load zFiles to z/OS wizard. Instead, it should allow to prompt for creating a new RDz project and
MVS subproject as the target of the Load wizard if these have not been created prior to the invocation of the
wizard.
Depending on what ends up being contained in RTCz v2.0, launching the load wizard from the contexts other than
a repository workspace may need to be rolled into the next release.
An option (checkbox) should be provided in the Load wizard to allow choosing whether the containing data set
should be added to the subproject vs. just the members that are loaded. Makes for a more organized presentation
in the subproject, especially those that contain many members (since data sets can be collapsed).
Need a synchronize view that would allow re-linking disconnected members and zFiles. Currently, you must
choose whether you wish to load or share and that determines the direction of synchronization (potentially causing
you to wipe out changes you may have made on one side or the other) after members were disconnected (e.g. as a
result of a synchronization error or explicit user action to disconnect).
IBM Confidential
IBM, 2016
Page 25
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration



















Version:
0.9
Date: <21/08/2009>
The Build request that’s cached in the Eclipse workspace is currently not modifiable until all resources are
disconnected. The build request page of the wizards should be redesigned to make the data set prefix not
modifiable but all other properties should be hidden away and opened for modification via an Advanced button.
There should be an unload from z/OS operation that disconnects all members shared to a repository workspace
and prompts for whether you wish to delete them from the z/OS sandbox.
No sharing of RDz projects/subprojects themselves to SCM yet
Drag/Drop from zComponent Projects to RDz subprojects should pop-up the Loadz wizard.
Pending changes and compare viewers should present logical (RDz) project view once RDz projects (i.e.
metadata) can be shared to the SCM.
Automatic population of RDz projects from zComponent projects (using dependency information)
Migration tools to import RDz property groups into RTCz build metadata.
Completely eliminate need for property groups in RDz when working with RTCz.
No SCM support for offline RDz projects
No SCM support for USS subprojects
No attempts being made to handle name collisions of zFiles or zFolder/data sets across zComponent projects or
components.
No attempts being made to handle z/OS sandbox overloading (e.g. from multiple Eclipse workspaces or repository
workspaces)
No attempts being made to be smart about reloading into a z/OS sandbox (it’s always a complete overwrite)
No lifecycle management of z/OS sandboxes (e.g. unloading, refreshing)
Renames of data set names inside z/OS sandboxes is not supported
No checks to see if there are loaded zFiles in data sets when a data set name inside a data set definition is
renamed.
Merge some of the Team Artifact Navigator info (e.g. source control, Data set definitions) into the RSE explorer
view to present an “SCM” view similar to how Changeman and Endevor do it.
Support loading zComponent Projects to z/OS sandbox without RDz remote projects
Use PDS/E extended attributes to store jazz metadata about loaded artifacts.
5.2 Interfaces
The API is provided in a way that the team provider (RTCz) should be able to call RDz and vice-versa without
introducing plug-in dependencies between the products.
5.2.1 Proxy interfaces
RDz adds a common plug-in for team integration which defines a new extension point called ‘proxy’ and a couple of
interfaces for team (RTCz) and model (RDz) communication. Contributors of this extension point must provide a class
which implements the ITeamProxy interface which has the required methods for RDz to call for requesting or
performing team related activities. IModelProxy is the other interface that is defined in this plug-in which has the
required methods for team providers (RTCz) to call for requesting or performing model (RDz) related activities.
For team providers (RTCz) to access the model proxy, a class called ModelProxyFactory (singleton) is provided. The
team providers can call the method as follows to get the model proxy.
The repository provider id that gets passed in is stored for future communication with the team provider.
IBM Confidential
IBM, 2016
Page 26
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
5.2.1.1 IModelProxy interface (implemented by RDz)
5.2.1.2 ITeamProxy interface (implemented by RTCz)
Team providers (RTCz) contribute to the ‘proxy’ extension point and provide the implementation.
For RDz to access team proxy, a class called TeamProxyRegistry (singleton) is implemented. Team Proxy Registry
populates a registry of all the contributors to the ‘proxy’ extension point and returns back a particular team proxy
based on the given repository id. RDz calls the following method with repository id to get the team provider (RTCz)
for requesting or performing team related activities.
TeamProxyRegistry.getSingleton().getTeamProxy(repositoryId);
The ITeamProxy interface is the mechanism through which RDz queries build properties from the team provider and
delegates various operations to the team provider
IBM Confidential
IBM, 2016
Page 27
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
5.2.2 ResourceInfo interfaces
In addition to the two proxy interfaces, there are two interfaces that represent the model or team artifacts respectively.
These are called IModelResourceInfo and ITeamResourceInfo. These interfaces shield the products from having to
know anything about the internal representation of resources in model provider or team provider products.
IBM Confidential
IBM, 2016
Page 28
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
5.2.2.1 IModelResourceInfo interface (implemented by RDz)
IBM Confidential
IBM, 2016
Page 29
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
5.2.2.2 ITeamResourceInfo interface (implemented by RTCz)
5.2.3 Build Property interfaces
Lastly there are a couple of classes that need to be filled in by RTCz to support build integration. RTCz represents
build information in declarative constructs called Build Translators. These are in-turn associated with a particular
artifact (through a language definition). If the artifact is associated with an MVS subproject, RDz needs to query the
build properties for it from RTCz. RTCz returns two types of build properties to RDz currently, compile options (as
a string) and a collection of DD (data definition) statement objects.
5.2.3.1 DDStatement
5.2.3.2 DDElement
IBM Confidential
IBM, 2016
Page 30
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
6. Appendix A – Glossary of terms
6.1 Core Jazz/RTC terminology by Jazz/RTC component
6.1.1 Source Control
Repository Workspace
A repository workspace holds an individual developer's private copy of a source file base.
Stream
A stream is an artifact that holds a shared copy of a source file base.
Component
A top-level subdivision of the source file base. A component can contain any number of folders and files.
Change set
A group of related changes to files for folders in a workspace or stream.
Flow
A Flow is a standing arrangement between repository workspaces or streams that enables users to deliver and
accept change sets
Load
To extract projects or files from a repository workspace into a sandbox or Eclipse workspace
Accept
To add any change set to a repository workspace, such as a change set attached to a work item
Show Pending Changes
Display the synchronization view that allows changes from your Eclipse Workspace or sandbox to be checked
into a repository workspace or be accepted into an Eclipse workspace or sandbox
(Local) Sandbox
A location on the file system to which the files from the source control system are extracted so that they can be
manipulated via tools that are external to the source control system, such as IDEs and compilers.
6.1.2 Team Build
Build Definition
A build definition is a filled-in build template which contains build properties and instructions that define how
to use a certain type of build mechanism (e.g. Ant, Make, shell script) to build a source code base.
6.1.3 Process Component
Project Area
The representation of a software project, including the project area defines the project deliverables, team
structure, process, and schedule.
Team Area
A place within a project area for managing team membership, roles, assignments, and team artifacts.
Process Area
Process Area is a generic term that can be used in place of Team Area or Project Area.
6.2 Eclipse Terminology
Workspace
A location on a file system with an Eclipse-oriented structure that contains a collection of resources (files,
folders, projects). See also sandbox which has a less structured nature.
Project
A folder that contains a .project file that configures the folder to be a project in an Eclipse workspace.
Share Project operation
Add or synchronize a project in the Eclipse workspace to a source control repository.
Optimistic/Pessimistic Locking
In the source control sense, two approaches that allow either parallel or serialized access to source control
IBM Confidential
IBM, 2016
Page 31
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
artifacts. Optimistic permits multiple concurrent modifications to the same resources with the expectation that
changes will be merged later. Pessimistic requires that a resource that is being modified be locked from
changes by others so that no collisions or merges will be required later. When the lock is released, the
resource can be modified by others based on the latest version.
EFS
Eclipse File System. EFS is a framework provided by Eclipse that allows an artifact in the Eclipse workspace
to act as a symbolic link to a resource that is not physically contained in the Eclipse workspace.
6.3 z/OS Terminology
Data set
A file on the MVS file system that has a record organization. Data sets names are usually composed of
multiple segments called qualifiers.
PDS/E
Partitioned Data Set Extended. A data set that can be subdivided to contain multiple members. Similar to a
directory on other file systems.
HLQ
High level qualifier. The first segment of a data set name.
6.4 RDz Terminology
Remote System Explorer (RSE)
A toolset which contains client-side and server-side components that allow an Eclipse client to communicate to
a remote system, access remote files and perform remote operations.
z/OS Project
An Eclipse project which is a container for MVS or USS subprojects.
MVS Subproject
An Eclipse project which contains references to artifacts on a specific MVS host system.
USS Subproject
An Eclipse project which contains references to artifacts on the USS subsystem of a z/OS system.
Property Group
MVS subprojects are associated with a property group which contains a specification of how to syntax check
or build the artifacts in the subproject as well as how to search for dependencies.
6.5 RTCz Terminology
z/OS sandbox
In addition to the local sandbox used by the core RTC source control load operation, RTCz adds the concept of
a remote sandbox on the MVS file system. This concept is realized via a data set prefix which is specified
during a load operation to z/OS.
Data set prefix
This prefix is used to complete the names of data sets that are allocated or used during a source control load
operation to z/OS. This prefix property is specified in a build definition.
File agent
A source control client running on z/OS which can be used to retrieve files from the RTCz repository into the
MVS file system.
zComponent Project
A new type of Eclipse project introduced in RTCz 2.0 which contains folders and artifacts that are annotated
with metadata properties. The metadata can contain instructions on how to represent the contents of the
project on the z/OS file system as well as instructions on how to build the artifacts on z/OS. Folders within the
z/OS source folder in this project are associated with PDS/Es on MVS. Sequential data sets are not yet
supported but in the future will be able to exist as standalone files inside the source folder of this project.
zFolder
A folder in the z/OS source folder of a zComponent project that is associated with a Data set definition in the
repository. When loading the contents of this folder on the MVS file system, the data set definition that is
associated with the zFolder is used along with the data set prefix to find or allocate the data set on MVS and
IBM Confidential
IBM, 2016
Page 32
RTCz/zIDE Integration
RDz zIDE and RTCz Integration Specification
RDzIntegration
Version:
0.9
Date: <21/08/2009>
add the files from the zFolder as members of this target data set.
zFile
A file in a zFolder which has associated z/OS or build metadata (e.g. language definition).
Data set definition
A repository artifact which defines the name and characteristics of an MVS data set used in source control or
build operations
Language Definition
A specification of build processing rules for a particular type of artifact (e.g. COBOL)
Share members as zFiles
A wizard that allows “managing” z/OS data set members to the source control system.
Share/Link
A term used in this document to describe that a member in an MVS subproject is associated with a zFile in a
zComponent project that is managed under source control.
Disconnect member from zFile
An action that severs the link between a member in an MVS subproject and the zFile in the zComponent
project. The member is not deleted but once disconnected, no further synchronization will be performed
between the member and the zFile.
Antz
An extended version of the Apache Ant build infrastructure that includes extensions for building z/OS
applications.
End of Document
IBM Confidential
IBM, 2016
Page 33