Rational Team Concert

Many of the compilers and utility programs, when called by an assembler interface, as is done by Rational Team Concert (RTC), will utilize something call DD name substitution lists. These substitution lists allow you, the programmer, to use different DD names than the normal ones expected by the compilers, for compiler input and output.

 

The reason for this is to allow other processes that do not have DD name flexibility to precede or follow compiler steps. In this way the compiler can accept a different DD name as SYSIN input or can write output to a different DD name other than SYSPRINT.

 

The reason we have to use this method of substituting DD names is because dynamic data set allocation APIs such as BPXWDYN, behave differently than processes coded using JCL. JCL will allow you to pass the temporary data set between steps without having any regard for the DD name that it is allocated to. With BPXWDYN or TSO ALLOCATE, when a temporary data set is allocated to a DD name and that DD name is freed, the temporary data set is de-allocated and lost.

 

User Scenarios

When thinking of multistep language definitions in RTC, the classic example is a COBOL compile, followed by a link-edit. The output from the compile is an object deck, and the input to the binder is the same object deck. However this scenario works just fine. In the compiler step we allocate SYSLIN to a temporary object deck as output using the “Keep” option to keep the DD allocated after the compile finishes. Then in the binder step SYSLIN is allocated as input using the same temporary object deck.

 

This scenario works because both steps are using the same DD name, SYSLIN as output from the first step, and input into the second step.

 

COBOL compile translator

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Link-Edit translator

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The user scenario that requires us to use DD name substitution lists is when an initial step allocates a DD name that is output to a subsequent step, such as SYSUT2, but SYSUT2 in the subsequent step has a totally different use. To show this we will use an IEBGENER step that copies source code from SYSUT1 to SYSUT2, standard IEBGENER behaviour. The SYSUT2 output then needs to be passed as input into SYSIN for the COBOL compiler.

 

IEBGENER step

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

COBOL Compiler Step

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

In the above example the IEBGENER step keeps the SYSUT2 DD name allocated. But when the COBOL compiler step needs to run, it also needs SYSUT2 as a work DD so when it tries to allocate it the compile fails with message that SYSUT2 could not be allocated as it was in use:

 

 

Successfully using DD name substitution

As long as one of the programs you are calling in a multistep language definition can support DD name substitution, you will be able to manipulate the DD names to pass data between the translators. In the example above we used IEBGENER passing input into the COBOL compiler. Both of these programs support DD name substitution, so we will look at 2 examples of utilizing DD name substitution. The first in the IEBGENER step and the second in the COBOL compile step.

 

DD name substitution in IEBGENER

In the following screen capture we are replacing the SYSUT2 DD allocation with a SYSIN DD name. However because IEBGENER expects a SYSIN DD to be allocated, we also need to substitute the SYSIN DD allocation with something else. In this case we have chosen SYSDUMMY as SYSIN is actually dummied out.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Note that the DD names list is positional, so we have entered all of the required DDs in the correct order, with their substituted names. So SYSIN, which is at DD position 5 becomes SYSDUMMY and SYSUT2, at DD position 9, becomes SYSIN.

 

The COBOL translator step can then remain as normal without using DD names list, keeping its default DDs:

 

 

 

 

When the language definition is run through a build we can see how RTC manages the allocations:

 

 

 

DD name substitution in the COBOL compiler

In this example we leave the IEBGENER step as default, with no DD names list and normal IEBGENER allocations:

 

 

 

 

 

 

 

We then manage the incoming DDs through DD name substitution in the COBOL compiler.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Note again the positional DD names list, replacing only the required DDs with our substitute names. As the output from IEBGENER is SYSUT2 we need to have that as our replacement DD for SYSIN. However as the COBOL compiler requires a SYSUT2 already we need to substitute that for a different name. We could have use Tom, Dick or Harry as the name, but chose to use SYSUT02 by just adding an extra “0”. We are then able to use SYSUT2 from the IEBGENER step as a replacement DD for SYSIN.

 

Again looking at the output from the build we can see how RTC handles the allocations and free statements of these DD names:

 

 

Additional information

The DD names substitutions lists for the compilers (COBOL, PLI), the Assembler and the Utilities can all be found listed in the relevant manuals for the specific compilers or utilities, normally in the programmers guide. However for a quick reference of the position of the various DD names in each of the compiles and utilities looks in Appendix E of the SCLM Redbook : Getting Started with SCLM: A Practical Guide to SCLM and SCLM Advanced Edition

 

Think of this blog entry as an example of converting an existing process into an RTC language definition and translator. For some reason, after a recent work trip I had made a note to test whether I could build a translator that would run SQL. Not sure why I had that note on a scrap of paper, but there must have been a reason for it. With the usual "challenges" that DB2 throws up with SCMs, especially when it comes to Binding, I was not anticipating a simple task. Couple with that that most DB2 requests run through IKJEFT01 it meant that we would have to factor in the ISPF Gateway as well to invoke this translator.

In the end, it turned out not to be too challenging, but a couple of peculiar tweaks needed to be adhered to.

Running SQL means calling DSNTEP2 and giving it the SQL in a SYSIN DD allocation. So the easy part of the task was creating an SQL data set definition that would hold my various SQL members.

The translator and language definition seemed pretty straight forward as well. Calling some REXX that invoked DSNTEP2 and allocating SYSIN to the source being built.

The question was how to get DSNTEP2 working as a REXX exec. Normally DSNTEP2 is invoked as a TSO command through the SYSTSIN. However because of the way RTC invokes TSO/ISPF commands, through the ISPF Gateway, as well as how SYSPRINT is allocated, we need to provide a REXX that does the DSNTEP2 invocation. The DSNTEP2 REXX that we run from the TSO command or exec looks like this:

---

/* REXX */                                                             
  Address TSO                                                          
  "free F(SYSPRINT)"                                                   
  "alloc F(SYSPRINT) tracks space(5,5) unit(VIO) new"                  
  "NEWSTACK"                                                           
  queue "RUN PROGRAM(DSNTEP2) PLAN(DSNTEP91) LIB('DB9WK1.RUNLIB.LOAD')"
  queue "END"                                                          
  "DSN SYSTEM (DSN9)"                                                  
  db2_rc = rc                                                          
  "DELSTACK"                                                           
  "EXECIO * DISKR SYSPRINT (STEM db2out. FINIS "                       
  do i = 1 to db2out.0;say db2out.i;end                                
  "free F(SYSPRINT)"                                                   
Exit db2_rc                                                          

---

We need to read the allocated SYSPRINT DD and using the REXX "say" statement the contents will be written to the log produced by the ISPF gateway.

The contents of our SQL member is just normal SQL such as:

   SELECT * FROM CCM4001X_JAZZ.TABLE_MAP;   

We need to associate the member with the "Run SQL" language definition, then ensure that that language definition is picked up by our build definition. When the build runs, the SQL is executed.

 

The Rational team Concert infocenter is a bit of a daunting place for a z/OS System Programmer. They are used to separate guides, either written on paper or possibly chiseled out of stone tablets, I should know I was one. Installation Guild, Configuration Guide, User Guide, User Reference are all the norm for z/OS products. Rational Team Concert (RTC) is just part of the bigger Collaborative Lifecycle Management (CLM) picture, so as such the infocenter covers a lot of information, much of which the z/OS system programmer does not care too much about when installing the RTC z/OS bits and pieces.

The purpose of this blog entry is to provide the z/OS system programmer with the links to the stuff that is really really relevant so they don't spend all their time navigating through the web content looking for the relevant information that they require to perform an install of the RTC z/OS bits. We will be using the 4.0.3 infocenter as a reference point.

The first thing to note is all the install information is in the section on Rational Solution for Collaborative Lifecycle Management, and not in the section on Rational Team Concert. Once you open the documentation tree for Rational Solution for Collaborative Lifecycle Management you will see a section on installing. This is where all the relevant pieces you will need are contained.

So the first thing you need to check is the hardware and software prerequisites. The image below where you need to navigate to for this information. Click on the Hardware and software requirements link to display the page, and then click on System requirements link.

 

 

 

 

 

 

 

 

 

 

 

 

 

For version 4.0.3 this will take you to https://jazz.net/wiki/bin/view/Deployment/CLMSystemRequirements403, however this will be a different link for each version.  Pay close attention to the following topics:

• Java run-time versions supported on z/OS
• RTC ISPF Client and ISPF Gateway section

The next place to go is the z/OS system programmers checklist:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

For version 4.0.3 the infocenter link to this is https://pic.dhe.ibm.com/infocenter/clmhelp/v4r0m3/index.jsp?re=1&topic=/com.ibm.jazz.install.doc/topics/t_checklist_zos.html&scope=null and contains all the links for what a z/OS systems programmer in a checklist format. Pay particular attention to the Installation information for z/OS systems programmers, as this contains things like parmlib changes. You don't have to perform all the steps in the checklist, just the ones that are relevant for your install.

 

 

My article on editing and building SDF-II objects with RTC has been published on developerWorks. Check it out here http://www.ibm.com/developerworks/rational/library/screen-definition-ii-rational-team-concert/index.html?ca=drs-

My article on editing and building ISPF DTL objects using Rational team Concert has been published on developerWorks. Check it out here http://www.ibm.com/developerworks/rational/library/configure-rational-team-concert-build-dtl-components/index.html

RTC Enterprise Extensions has the ability to tag load modules with a timestamp when they were created using the SSI. In the translator for the link edit use the SSI(@{ssi_info}) option to tell RTC to put the timestamp into the SSI. 

Once the load module members are created the SSI will contain a hex representation of the timestamp.

If you want to quickly know when a load module was created but have lost your AMBLIST JCL you can easily check the timestamp in the SSI. Cut out the 8 character hex value and past it into your calculator in hex mode and then convert to decimal. This will give you the timestamp in Unix Epoch format, that is the number of seconds elapsed since the 1st January 1970. You can now cut that value and using a website that converts Unix Epoch timestamps such as http://www.epochconverter.com/, paste the value into the entry field and it will tell you the date the load module was created.