About Rational Team Concert for System z dependency data

You can use Rational Team Concert™ for System z® to obtain dependency data and then query it for your source artifacts in zComponent projects. Dependency data indicates the relationships between source files, such as a COBOL program that includes a shared copybook. You can gather dependency data by parsing source files in the Jazz™ Team Server repository. This parsing is controlled by the build process and, if it is enabled, happens when you update a stream during change delivery.

The parser collects information from the source code, such as the type of source–for example, main or include–and any dependencies, including a COBOL copybook. Parsing supports various languages, including COBOL, PLI, assembler, and others. The parser output is an XML document in resource definition framework (RDF) format. This RDF document is assigned a unique URI composed of the itemId and stateId of the file in the SCM. Those IDs are sufficient to retrieve an artifact from the SCM in a workspace or a stream.

You can use the SPARQL query language to perform various searches against dependency data. Rational Team Concert for System z provides an application programming interface (API) at the server and client levels to perform three default queries (getImpact, getDependents, getResource) or any SPARQL query that you write yourself.

The result of the queries is limited to the URI of the XML document. With the combination of these queries and the XML document, you can easily browse artifacts and navigate from one to another, according to whether you need, for example, to build a list of files for a given program, or to calculate the impact of a change to an included file.

Prerequisites: Creating SPARQL queries requires advanced Eclipse development skills.

About collecting dependency data

Rational Team Concert for System z collects dependency data when you deliver a change set to a stream in a zComponent Project. When you update a file, Rational Team Concert for System z updates the corresponding dependency data. It is important to note, however, that Rational Team Concert for System z keeps only the latest version of dependency data. This means that you should not turn on dependency metadata collection in several streams that contain the same component, because updating to one stream could corrupt the data from the other stream. To turn on dependency data collection for a single stream, you can define particular team areas related to the stream and customize the process at team level, instead of at the project level.

Dependency data contents

Rational Team Concert for System z stores the dependency data between one artifact and another in a generic format. This means that you can write queries related to dependencies in a generic way, regardless of source file language.
Note: Some characteristics are language-dependent, but these are discussed later.
Every resource captures the following dependency data:

<ns:name xmlns:ns="http://www.ibm.com/xmlns/zindex/">EPSMTCOM.cpy</ns:name>

<ns:fileTypeCd xmlns:ns="http://www.ibm.com/xmlns/zindex/">INCL</ns:fileTypeCd>

<ns:languageCd xmlns:ns="http://www.ibm.com/xmlns/zindex/">COB</ns:languageCd>

<ns:logicalName xmlns:ns="http://www.ibm.com/xmlns/zindex/">EPSMTCOM</ns:logicalName>

  • The name attribute is the name of the file, including the file extension.
  • The logicalName attribute is the name the compiler uses.
  • The fileTypeCd attribute is a generic attribute. Possible values include main, incl or unkn.
  • The languageCd attribute indicates the source file language.
Other general characteristics, such as record count or the number of comment and uncommented lines, are also available.
A dependency is expressed with an element that contains the following attributes:

<ns:dependency xmlns:ns="http://www.ibm.com/xmlns/zindex/">

<rdf:Description>

<ns:dependencyName xmlns:ns="http://www.ibm.com/xmlns/zindex2/">EPSNBRPM</ns:dependencyName>

<ns:dependencyType xmlns:ns="http://www.ibm.com/xmlns/zindex2/">COPY</ns:dependencyType>

<ns:fileTypeCd xmlns:ns="http://www.ibm.com/xmlns/zindex2/">INCL</ns:fileTypeCd>

</rdf:Description>

DependencyName and fileTypeCD match the logicalName and fileTypeCd resource values. The dependencyType indicates the type of dependency related to a given language.

About making Rational Team Concert for System z queries

You can make queries in Rational Team Concert for System z with the SPARQL query language. Rational Team Concert for System z offers an API for three default queries for browsing dependencies.

For more information about this API, refer to the following plug-ins: prerequisites
Server
com.ibm.teamz.rdf.query.service
Client
com.ibm.teamz.rdf.query.client
The default queries for browsing dependencies are:
getImpact(String dependencyName)
This query fetches all of the resources that include a dependency on an artifact with the given name.
getDependents(String dependencyName, String dependencyType)
This query fetches all of the resources whose logical name and fileTypeCd match a given dependencyName and fileType.
getResource(String resourceStorageURL)
This query fetches the XML representation of a resource stored at a given URI. The format of the URI contains a fixed part and a variable part. The fixed part is the server address and the path to the storage area. It would look like this:

https://localhost:9443/jazz/storage/rtcz/

The variable part is built from the itemId and stateId of the parsed resource. You can retrieve those attributes with the SCM API.
_itemId=<itemId>_stateId=<stateId>
This is an example of the complete URI:

https://localhost:9443/jazz/storage/rtcz/_itemId=_ILmFIIWEEd6tRoteGBvdPA_stateId=_IXz8YYWEEd6Gcog_JpIdrw

You can either build such a URI from a known artifact in the SCM, or you can obtain it from a query.
runQuery(String sparql)
This query executes a custom SPARQL statement and responds with a list of URIs of the found resources. The following is a sample SPARQL query, which is used by the getDependents query:

PREFIX zindex: <http://www.ibm.com/xmlns/zindex/>

SELECT ?zindex

WHERE {

zindex:logicalName "CustCopy";

zindex:fileTypeCd "INCL".  }


Feedback