rdz zide and rtcz integration specification€¦ · web viewrdz integrated development environment...

IBM

RTCz Integration SpecificationRDz Integrated Development Environment (zIDE)

Version <0.9>Author: <Alex Akilov>Owner: <Alex Akilov>

Status: <Draft >

RTCz/zIDE Integration Version: 0.9RDz zIDE and RTCz Integration Specification Date: <21/08/2009>RDzIntegration

Revision HistoryDate Version Description Author

04/14/2009 0.7 Initial version (based on RTCz twiki version 0.6)

Alex Akilov

07/27/2009 0.8 Updated version based on actual implementation at the end of Sprint 7

Alex Akilov

08/28/2009 0.9 Incorporated comments from Rosalind Radcliffe

Alex Akilov

Table of Contents1. Introduction 4

1.1 Purpose 41.2 Scope 41.3 Definitions, Acronyms, and Abbreviations 41.4 References 41.5 Overview 4

2. Requirements 42.1 Enable source control capabilities for artifacts that RDz tooling works with 42.2 Preserve the z/OS developer’s conceptual model that the RDz product promotes 42.3 RTCz should be able to work standalone 42.4 Build and environment settings should be shared between RTCz and RDz 4

3. Architectural Decisions 53.1 Overview 53.2 Technical issues/challenges 5

3.2.1 Eclipse project model vs. RDz project model 53.2.2 More on the RDz user’s conceptual model 53.2.3 Maintaining source control metadata in local vs. z/OS sandboxes 63.2.4 Use of EFS (Eclipse File System) and linked resources 63.2.5 Containment vs. Reference and the clone problem 6

3.3 Design decisions 63.3.1 Rejected approaches/proposals 73.3.2 Accepted approaches/decisions 7

4. Detailed Design and Implementation 94.1 Integrated Development setup 9

4.1.1 Implementation and installation notes 104.2 RTC source control component implementation 104.3 RTCz source control extensions 114.4 RTCz File Agent 124.5 Load zFiles to z/OS operation 12

4.5.1 Load zFiles to z/OS – Implementation notes 134.6 Share members as z/Files operation 18

4.6.1 Share members as zFiles – Implementation notes 184.7 RDz content synchronization after share or load 224.8 Performing various maintenance operations after share or load 24

IBM Confidential IBM, 2023


4.8.1 Create a new artifact in RDz project 244.8.2 Remove from subproject on a managed member 244.8.3 Delete managed member or data set containing managed members from RDz project 244.8.4 Rename managed member from RDz project 244.8.5 Rename data set containing managed members (in MVS subproject or Remote System Explorer)244.8.6 Rename zFolder in zComponent project (or move linked zFiles to a different zFolder) 244.8.7 Rename Data set definition which zFolders in zComponent projects are pointing to 244.8.8 Modify data set name in data set definition which zFolders are pointing to 244.8.9 Create a new zFile in zComponent project 244.8.10 Disconnect a zComponent project from the SCM 244.8.11 Delete linked zFile in zComponent project 244.8.12 Rename linked zFile in zComponent project 24

4.9 Build Integration 24

5. Implementation Details 255.1 Known Limitations 255.2 Interfaces 26

5.2.1 Proxy interfaces 265.2.2 ResourceInfo interfaces 285.2.3 Build Property interfaces 30

6. Appendix A – Glossary of terms 316.1 Core Jazz/RTC terminology by Jazz/RTC component 31

6.1.1 Source Control 316.1.2 Team Build 316.1.3 Process Component 31

6.2 Eclipse Terminology 316.3 z/OS Terminology 326.4 RDz Terminology 326.5 RTCz Terminology 32



RDz zIDE and RTCz Integration Specification 1. Introduction

This document details the design of the initial integration between the RTCz and RDz products.

1.1 PurposeThe 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 ScopeThe design described in this document covers the RDz v7.6 and RTCz v2.0 products.

1.3 Definitions, Acronyms, and AbbreviationsRDz

Rational Developer for System zRTCz

Rational Team Concert for System zSee Appendix A for a more complete glossary of terms.

1.4 ReferenceszComponent project structureRTCz Mass Import tool

1.5 OverviewThe remainder of this document is intended to capture the RTCz and RDz integration design.

2. RequirementsThis 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 withInitial 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 promotesSource 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 standaloneA 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 RDzA 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.


http://red019.rtp.raleigh.ibm.com/twiki/bin/view/RTCz/MassImportSprint6

http://red019.rtp.raleigh.ibm.com/twiki/bin/view/RTCz/RTCzProjectStructure


3. Architectural Decisions

3.1 OverviewThis 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 modelThe 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 modelAs 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



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 sandboxesSee 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 resourcesTo 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 problemAs 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 decisionsThere 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.



3.3.1 Rejected approaches/proposals

3.3.1.1 Use of EFS in RDz v7.5 projects to support Source Control ProvidersRDz 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 subprojectsRTCz 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 synchronizationThe 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 artifactsTo 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 subprojectsRTCz 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



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 sandboxSince 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 sandboxRTCz 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 extensionsThe 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



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 setupWhen 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:



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 notesThe 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 implementationAt 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.


Eclipse Workspace

RTCz Local Sandbox

RDz project area RTCz SCM

Component A

Component B

EPSCMORT.cbl

EPSMDRVR.cbl

zComponent1

zComponent2

z1

z2


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 extensionsAs 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.



4.4 RTCz File AgentRTCz 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 operationThe 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 workspace2. 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:



4.5.1 Load zFiles to z/OS – Implementation notesThe 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:

Source Repository Workspace Source Component Source zComponent Project Source zComponent artifacts (zFiles) Target MVS subproject Build Context


z/OS dev LPARFile Agent

on MVSF1F1F1

RTCz client loads files from SCM to Eclipse workspaceRTCz client sends request to File Agent to load files remotelyFile Agent retrieves files from SCMFile agent creates appropriate PDSE’s and loads the membersRTCz client notifies RDz that local and remote sandboxes are readyRDz sets up listeners to remote and local copies of files

Repository Workspace

RTCz SCM

workstation

RTCz clientRDz client5

2

4

1

3

6

6


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.



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



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



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.



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 operationThe 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:

4.6.1 Share members as zFiles – Implementation notesThe 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.


z/OS dev LPAR

RSE Server (RDz)

workstation

RTCz client

F1F1F1

RDz client1

23 4

Repository Workspace

RTCz SCM

RTCz provides RDz with list of members to downloadRDz sends request to RSE server to download the filesRSE 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 prefixzComponent project is shared to SCM, if needed


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:



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.



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).



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 loadOnce 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.



4.8 Performing various maintenance operations after share or load

4.8.1 Create a new artifact in RDz projectIf 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 memberNot 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 projectWill 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 projectWill 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 toNo 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 tozFiles 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 projectWill 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 SCMNo 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 projectCorresponding member in the MVS subproject and z/OS sandbox will be deleted.

4.8.12 Rename linked zFile in zComponent projectCorresponding member in the MVS subproject and z/OS sandbox will be renamed.

4.9 Build IntegrationRTCz also provides syntax check and build services for RDz when members in RDz subprojects are associated with



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).



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 InterfacesThe 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 interfacesRDz 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.



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



5.2.2 ResourceInfo interfacesIn 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.



5.2.2.1 IModelResourceInfo interface (implemented by RDz)



5.2.2.2 ITeamResourceInfo interface (implemented by RTCz)

5.2.3 Build Property interfacesLastly 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



6. Appendix A – Glossary of terms

6.1 Core Jazz/RTC terminology by Jazz/RTC component

6.1.1 Source ControlRepository 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

LoadTo 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 ChangesDisplay 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) SandboxA 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 BuildBuild 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 ComponentProject Area

The representation of a software project, including the project area defines the project deliverables, team structure, process, and schedule.

Team AreaA place within a project area for managing team membership, roles, assignments, and team artifacts.

Process AreaProcess Area is a generic term that can be used in place of Team Area or Project Area.

6.2 Eclipse TerminologyWorkspace

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 operationAdd or synchronize a project in the Eclipse workspace to a source control repository.

Optimistic/Pessimistic LockingIn the source control sense, two approaches that allow either parallel or serialized access to source control



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.

EFSEclipse 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 TerminologyData 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/EPartitioned Data Set Extended. A data set that can be subdivided to contain multiple members. Similar to a directory on other file systems.

HLQHigh level qualifier. The first segment of a data set name.

6.4 RDz TerminologyRemote 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 ProjectAn Eclipse project which is a container for MVS or USS subprojects.

MVS SubprojectAn Eclipse project which contains references to artifacts on a specific MVS host system.

USS SubprojectAn Eclipse project which contains references to artifacts on the USS subsystem of a z/OS system.

Property GroupMVS 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 Terminologyz/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 prefixThis 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 agentA source control client running on z/OS which can be used to retrieve files from the RTCz repository into the MVS file system.

zComponent ProjectA 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.

zFolderA 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



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 DefinitionA specification of build processing rules for a particular type of artifact (e.g. COBOL)

Share members as zFilesA wizard that allows “managing” z/OS data set members to the source control system.

Share/LinkA 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 zFileAn 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.

AntzAn extended version of the Apache Ant build infrastructure that includes extensions for building z/OS applications.

End of Document


rdz zide and rtcz integration specification€¦ · web viewrdz integrated development environment...

Documents