Using IBM Rational Team Concert for System z and the Jazz platform: Part 3. Govern your existing mainframe SCM systems with the IBM System z Jazz Gateway

How you can improve team collaboration but keep your current SCM

Do you want all of your teams truly collaborating in their development projects with IBM® Rational Team Concert™ and IBM® Jazz™ technology? Are you reluctant to give up the mainframe software configuration management (SCM) system that you have used and trusted for years? Does the prospect of integrating these new and trusted technologies seem overwhelming? This article is for you. It explains how you can jump start your development teams on Rational Team Concert while enabling governance of your existing mainframe SCM system.


Rosalind Radcliffe (, Chief Architect for Jazz on System z and Power Systems, IBM

Author photoRosalind Radcliffe is a Senior Technical Staff Member in IBM Software Group working in the Tivoli Division where she is responsible for the SOA Management Strategy, and is one of the architects responsible for the ITCAM for SOA product. Her current responsibilities include architect for the ITCAM for SOA platform bundle, as well as the relationship between Tivoli and the WebSphere ESB and Message Broker teams. Before her current role in SOA Management, she has worked in Tivoli Services, different parts of IBM development and test, and User Interface Design. She currently resides in Durham, North Carolina. When not at work, she spends time with her family.

Liam Doherty (, Software engineer and IBM Software Configuration and Library Manager (SCLM) architect, IBM

author photoLiam is a software engineer and IBM® Software Configuration and Library Manager (SCLM) architect in Perth, Australia. He has 28 years of experience with the MVS operating system, with IBM and other customers. Initially an application programmer in PL/I, IMS, IBM CICS, and IBM® DB2® database, he moved into more technical support roles, such as IMS database administrator, IBM® CICS® system programmer, and SCLM administrator before spending much of his career as a DB2 database architect. On moving to Perth, he took up a role at IBM that focused on SCLM and the SCLM additional products, both from an architectural perspective and a customer-facing support perspective. He was also one of the developers on SCLM Developer Toolkit. More recently, he has joined the Rational Team Concert for System z development team, using his experience with z/OS and z/OS software configuration management to assist in the development of the newest IBM Rational z/OS SCM offering. He attends the SHARE technical conference twice a year in the U.S. to give presentations on Rational Team Concert for System z, SCLM, and ISPF.

Jean-Yves B. Rigolet (, Software engineer, IBM

author photoJean-Yves is a software engineer in the IBM Software Group, working in the Rational software division. He has nearly 20 years of application and development tools experience in a variety of programming environments and platforms, including the IBM® WebSphere® Telecom Web Services Toolkit, IBM® VisualAge® Pacbase, and the VisualAge Generator products. He is based in the IBM France Software Laboratory, in Paris, where he is scrum master for Rational Team Concert for System z. Jean-Yves is also the author of In tune with IBM Jazz and IBM Rational Team Concert enterprise development tools paper, which has led him to present the Enterprise Modernization collaborative strategy at various conferences and events worldwide. Before joining Rational software, Jean-Yves spent several months launching a Workplace and Eclipse practice as part of the IBM Software Group Lab Services initiative and helped customers by building a workshop that he facilitated around Europe. During the earlier years of his career, he acquired solid experience in enterprise applications through building business applications for CGI Informatique, which was acquired by IBM.

11 February 2010


This is the third in a series of articles about the use of IBM® Rational Team Concert™ for System z® at the enterprise level. It explains the integration between Rational Team Concert for System z and external host-based software configuration management (SCM) products.

Rational Team Concert for System z provides the collaboration and governance support not provided by existing host-based SCM solutions. Being able to use these features while still using the existing host-based SCM brings immediate value to your organization, without having to change the existing development tools and build processes. In Part 1, we provided an overview to the features of Rational Team Concert for System z (see "View more content in this series"). With this article, we dive into new functions provided with Version 2 for simplified integration.

The System z Jazz Gateway, which is new with Version 2, makes it possible to access information about Jazz work items from an existing client that is running a mainframe, regardless of the system the Jazz server is running on. This article provides the details behind how the System z Jazz Gateway works with existing mainframe software configuration management systems, such as the IBM® Software Configuration and Library Manager (SCLM), to control the editing and promotion of development artifacts.

Extracting Jazz information from z/OS

The System z Jazz Gateway that is included with Rational Team Concert for System z provides a set of services to query your Jazz server from the host, where your existing system is running. You can visualize the System z Jazz Gateway as a server companion that is waiting for mainframe tool requests regarding work item attributes stored in your Jazz server. The purpose of this gateway is to leverage existing tools: a host software configuration management system, such as IBM SCLM, CA Endevor, Serena ChangeMan, or any other z/OS tool that you use for your software development.

Figure 1 gives an overview of the System z Jazz Gateway and shows the workflow, which comprises six steps to retrieve information from the server.

Figure 1. Overview of the gateway
Jazz Gateway workflow retrieving info from Jazz

These are the six steps for using the System z Jazz Gateway:

  1. Test the REXX or SCLM user exit setup parameters to pass to the REXX gateway client.
  2. The REXX client passes specified parameters to the gateway server and waits for a response.
  3. The IBM System z Jazz Gateway performs authentication, sets up REST URI, and sends a request to the Jazz server.
  4. The Rational Team Concert for System z server returns the work item XML code for the requested REST URI.
  5. The System z Jazz Gateway extracts the status and returns the complete XML back to the REXX client.
  6. The REXX client returns the status or the XML to the calling program.

The gateway can accept many connections from clients. It always answers, regardless of the status of the Rational Team Concert for System z server, so that these clients can adopt a strategy based on the answer.

Because most development processes in Rational Team Concert for System z are handled through work items, one common use scenario for the gateway is to enable or disable activities of your mainframe tool according to the value of a work item attribute. This scenario can help you align all of your multiplatform development, whether it is completely managed by Rational Team Concert for System z or still partially managed by your existing development tools that run on the mainframe.

Figure 2 shows an example of a work item status that can be returned to a terminal and used by your z/OS infrastructure.

Figure 2. Example of a work item status extraction on z/OS
Work item number 106 is in Resolved status.

Prepare the System z Jazz Gateway infrastructure

The rest of this article walks you through two sample scenarios that illustrate how to integrate Rational Team Concert for System z with SCLM by using the System z Jazz Gateway. These scenarios use two System z Jazz Gateway API services that help retrieve information about Jazz work items from a z/OS system:

  • Get the full XML content of a work item, from which you can get the value of a specific attribute that you are interested in.
  • Get the status of a work item directly.

Prepare your environment

To follow along with the examples in this article, ensure that you have completed all of these steps first:

  1. Install the Rational Team Concert for System z Server.
  2. Install the System z Jazz Gateway on your mainframe.
  3. Configure and test the System z Jazz Gateway.
  4. Ensure that you have followed all of the steps required to set up and use SCLM with the System z Jazz Gateway server.

For more information about these installation and configuration steps, see the Rational Team Concert for System z documentation.

Install the sample code

After you have prepared your environment, get the two REXX scripts, GETSUMM and BLZSCLM2, from the Download section of this article. To install them on your z/OS machine, follow these steps:

  1. Create a subdirectory (folder) on your workstation, and unzip the contents of the zipped file that you downloaded into that folder. The extracted files are all in text format.
  2. Use your mainframe file transfer protocol to upload the text files. You must use the following attributes:
    FB, LRECL=80, BLKSIZE=3120.
  3. Copy the GETSUMM file into a library that is in the SYSPROC or SYSEXEC DD allocations. The GETSUMM file is an ISPF edit macro and, as such, must be part of the SYSPROC or SYSEXEC DD allocation for it to function as an edit macro. You can rename it to any name that conforms to your site standards. Be sure to use the new name when you call the macro.
  4. Copy the BLZSCLM2 file to a library that is referenced by your SCLM project definition or that the SCLM user exits that are invoked by the project definition exit points. This file is a replacement for the BLZSCLM1 file that was included with Rational Team Concert for System z, Version
  5. Follow the instructions for BLZSCLM1 in the chapter about Setting up the System z Jazz Gateway to control SCLM workflow in the Rational Team Concert for System z documentation.

Customize SCLM automated process

An easy way to extend the behavior of SCLM is by using the user exit points provided by the tool to add your own process to the standard ones provided. SCLM user exit points can use the information returned by the System z Jazz Gateway Server. For more information on user exits, see the SCLM Library. Select the ISPF SCLM Guide and Reference that corresponds to your version of z/OS, and look for the user exits chapter.

Scenario 1. Automatic code annotation

In any complex development environment, it is important not only to keep track of changes made to code, but also to explain why the changes are made. This scenario shows how to automatically add comments to source code by using information from a Rational Team Concert work item. It uses the ISPF edit macro functionality to add the number and description of a work item at edit time and to generate a hyperlink to the work item inside the source code.

If you are new to ISPF edit macros, read the documentation cited in the Resources section at the end of this article.

Figure 3 provides an example of an automated comment added in the source code by using the macro. The first line of the comment indicates the date of the update (17/09/09) and the associated work item number (Work item 18). The second and third lines show the complete summary of the work item.

Figure 3. An automated comment in the source code
source code header with automated comment

Create an ISPF edit macro to add code change comments

The first thing to do is to create an edit macro by using the sample code provided and described below. Edit macros must be created as a member in a library that is allocated to either the SYSPROC or SYSEXEC DD in the ISPF allocations. You can call the member whatever you like. In this example, the member is called GETSUMM.

The edit macro sample is split into several procedures, which are illustrated in code listings 1 through 4 and described in detail in the following sections. The REXX macro main script is shown in Listing 1. The ISREDIT MACRO command indicates to ISPF that this is an edit macro and enables the ISPF edit macro. Next, the script obtains the work item number that the comment is to be created for. If the macro is called from within an edit session in SCLM, then the work item number is retrieved from the ISPF variable where SCLM stores the change code number entered on the SCLM edit panel. To use this macro outside of an SCLM context, a work item number can be passed to the macro as a parameter.

The macro then calls the getSummary procedure to retrieve the work item information from the Jazz repository, and, if no error is returned, then calls the buildComment and insertComment procedures. The next sections of this article describe each of these procedures in a more detail.

Listing 1. Get work item summary macro
/* Rexx */

   "ISREDIT MACRO (Workitem)"
   If Workitem = '' Then
      /* Assume this macro is being run from SCLM to get the   */
      /* SCLM entered change code that is being used.          */
      Workitem = NCCDE

   Call getSummary
   If WI_rc = 0 Then Call buildComment
   If WI_rc = 0 Then Call insertComment


Invoke the System z Jazz Gateway through the getSummary procedure

The getSummary procedure shown in Listing 2 calls the System z Jazz Gateway to query a work item and extract its summary from the XML returned by the System z Jazz Gateway.

Although this procedure contains a hard-coded, specific userid and password to provide a quick procedure to test, it can be modified to meet the security demands of a production system. You can, for example, use an encrypted file that contains your password. For more information about the security aspects of the gateway, read the chapter about Creating an encrypted password file for the System z Jazz Gateway in the Rational Team Concert for System z documentation.

One of the services provided by the gateway is to return the full content of a work item in XML format. This information is presented as title in the returned XML.

The getSummary procedure performs the following steps to add the work item information to the source code:

  1. Definition of the local variables
    • Server, Userid, and Password
    • The first three lines of the procedure define local variables for credentials to be used by the Gateway to access the Jazz server.
  2. Construction of the query parameter string
    • parm = Server' 'Userid' 'Password' 'Workitem
    • This line creates the query parameter string that will be passed to the gateway to retrieve the work item content. It does not set a state in the query parameter in order to get the full content of the work item returned by the gateway.
  3. Allocation of the XML returned by the gateway
    • Address TSO "ALLOC F(XMLRESP) UNIT(VIO) NEW " ||, "RECFM(V B) LRECL(32657) SP(1 5) TR"
    • To be able to parse the XML that is returned by the gateway, the procedure uses a TSO command to allocate a transient file, named XMLRESP, that will be filled with the work item content.
  4. Invoke the System z Jazz Gateway
    • This line defines the gateway invocation that will query the work item according to the parameter string parm. The command executed launches the gateway client JCL, called BLZGWCLI with the parm parameter.
  5. Parse the XML returned to get the work item summary
    • Address TSO "execio * diskr XMLRESP (stem xmlin. finis" parse var xmlin.1 . '<dc:title>' title '</dc:title>'
    • Next, the procedure reads the XML returned by the Gateway in the XMLRESP file. It parses the file content for the summary associated with the title attribute.
  6. Free XML file
    • Address TSO 'FREE F(XMLRESP)'
    • Now that the work item summary is ready to be added to the source comment, the procedure frees the XMLRESP file.
  7. The procedure writes a completion message to the terminal.
Listing 2. Get work item summary

   Server   = "<your_server_address>""      /* RTCz server */
   Userid   = "your_userid"
   Password = "your_password"
   parm     = Server' 'Userid' 'Password' 'Workitem

   /* Allocate new XML output file to VIO          */
                   "RECFM(V B) LRECL(32657) SP(1 5) TR"

   /* Invoke System z Jazz Gateway client to query workitem */
   Address ISPEXEC
   WI_rc = rc

   Address TSO
   "execio * diskr XMLRESP (stem xmlin. finis"

   parse var xmlin.1 . '<dc:title>' title '</dc:title>' .

   /* Free XML output file                         */
   Address TSO 'FREE F(XMLRESP)'

   /* Write completion message to terminal         */
   If WI_rc <> 0 Then
      Say 'Problem with Work item retrieval'


Build the comment to be inserted using the buildComment procedure

Listing 3 shows how the comment is formatted for insertion into the code. This procedure varies according to the software language that you are using and the way that you want to present your comment. This example formats two different lines for the header and the summary. The header of the comment, which is printed in the first element of a REXX stem variable cmline.1, is straightforward: a simple concatenation of the current date of the update followed by the work item number. The work item summary is split and stored into the subsequent elements of the REXX stem variable, named cmline.i.

Listing 3. Build comment

   /* This procedure takes the summary line and splits it into */
   /* COBOL comment lines that fit the complete comment.       */

   cmline.1 = '      ***  'Date('E')' Workitem ' ||, Left(Workitem,40,' ')'***'
   Do i = 2 by 1 while (length(strip(title,T)) > 49)
      n = Words(Substr(title,1,49))
      p = Wordindex(Substr(title,1,49),n)
      comment = Substr(title,1,p-1)
      cmline.i = '      ***           'Left(comment,49,' ')'***   '
      title    = Substr(title,p)
   cmline.i = '      ***           'Left(title,49,' ')'***   '


Insert the comment into the COBOL program by using the insertComment procedure

The final procedure inserts all of the lines stored in the REXX stem variable into the source code where the comment block is placed. The procedure uses the standard ISPF edit macro commands to achieve this, as shown in Listing 4. This example assumes that there is a comment block in the COBOL program that begins with the literal "*** Change activities:".

Listing 4. Insert comment

   /* This procedure looks for the existing comment block and  */
   /* inserts the work item comment after the last comment.    */

   Address ISPEXEC
   "ISREDIT FIND '*** Change activities:' First"
   "ISREDIT FIND '***                   ' Next"
   Do j = 1 to i
      NEWDATA = cmline.j


Try this yourself to experience this newly created link between the that code you maintain on z/OS and your collaboration platform, from which you can now guide all of your development.

Scenario 2. Promote approved code

Enforcing approval of work items

The second scenario shows how to use Rational Team Concert for System z to drive your mainframe SCM workflow and automate the promotion of your code to production level when a specific work item has received all of the approvals that it needs to be closed.

Although this example uses the Bugzilla workflow provided with some Rational Team Concert for System z project templates, it can easily be adapted to your own workflow, because it does not rely on any aspect that is specific to this workflow.

Rational Team Concert lets you easily request approvals, reviews, or verifications by using work items and the underlying process engine. To make these requests, you open the work item editor on the Approvals page and define the type of approval that you need, the users whose approval you want, and a due date. After you have defined an approval for the work item for your code promotions, your work item Approvals page should look similar to the one shown in Figure 4.

Figure 4. Work item approvals page
Jazz Process editor showing approvals

You can also configure approvals for the exact type and number of approvers you want and for controlling the workflow of a work item according to whether the approval has been accepted or rejected. The example in this scenario uses the latter configuration: controlling the process workflow to ensure that none of the new or updated code is put into production unless it is approved by a specific user, the product owner.

To force all work items to be closed automatically when approved, you need to configure approval trackings. Open the project editor Configuration view and navigate to Project Configuration > Configuration Data > Work Items (Advanced) > Approval Trackings, as illustrated in Figure 5.

Figure 5. Work item approval trackings
Shows Project Area selections described

Larger view of Figure 5.

In this example, there are currently no workflow actions set for the Approval and Review approval types. With the current settings, no automatic action is triggered by the Jazz process when a work item has been completely approved or reviewed. You can change these settings so that a work item is automatically closed when it is approved. SCLM, in turn, can check the state of the work item to allow or disallow the code promotion. To select this new behavior, change the value of the Approved status to force the Close action to be triggered. After changing the workflow action, the Approval Tracking settings should be similar those shown in Figure 6. Notice that no other workflow behavior is changed other than the one needed for this scenario.

Figure 6. Work item closed when approved
Approval tracking screen segment

Driving the source code promotion

After the Jazz process has been configured, you can change the way that the SCM follows the newly defined workflow when you try to promote code. Before changing any code used by Rational Team Concert for System z and SCLM on the mainframe, be sure to consider what can be returned to the REXX client by the System z Jazz Gateway.

The Bugzilla workflow, which is used in this scenario, makes the states presented in Listing 5, available for the Task and Defect work items managed in the project. This scenario uses the work item status to enable or disable code promotion.

Listing 5. Work item status
WIState.0 = 'XML Returned' 
WIState.1 = 'New' 
WIState.2 = 'In Progress' 
WIState.3 = 'Resolved' 
WIState.4 = 'Verified' 
WIState.5 = 'Closed' 
WIState.6 = 'Reopened'
WIState.7 = 'Triaged'
WIState.8 = 'Unknown'

Along with the work item status goes the resolution. Listing 6 shows the resolutions that can be expected for a work item in a Bugzilla workflow. The resolution attribute can be used to indicate if there is any code to be promoted or not.

Listing 6. Work item resolution
WIResolution.1 = "Fixed" 
WIResolution.2 = "Duplicate"
WIResolution.3 = "Won't Fix" 
WIResolution.4 = "Works for me" 
WIResolution.5 = "Invalid" 
WIResolution.7 = "Later"
WIResolution.8 = "Fixed Upstream"

Listing 7 shows how to check whether code can be promoted from Development to Test status. The rule applied here to allow promotion is to admit code to the next level only if the work item status is Resolved. In no other case is code allowed to be promoted to the Test level.

Listing 7. The Promote to Test script
When (WIState_rc < 3) | (WIState_rc > 5) Then Do
  Say 'Workitem number 'Strip(CCODE)' is in ' ||, WILiteral.WIState_rc 'status.' 
  Say 'This is not a valid status for promotion.'
  Exit 8 

Because the workflow process was configured in Rational Team Concert for System z to automatically change the work item status to Closed as soon as the work item change was reported as Approved or Reviewed, the work item status can be used to determine if the code can be promoted from Test to Production. To avoid updating the Production line for no good reason, and just replace the code with the same one instead, you can also check whether anything was actually fixed. Listing 8 illustrates how to check the Resolution attribute to see if something has been fixed or not.

Listing 8. Promote to Production script
When (WIState_rc = 5) Then Do 
  If WIResolution_rc <> 1 Then Do 
    Say 'The workitem resolution must be "Fixed" ' ||, 'to promote. 
	  The resolution is currently ' ||, WIResolution.WIResolutiom_rc 
    Say 'This is not a valid resolution for promotion.'
    Exit 8

Both code promotions on the mainframe SCM (from Development to Test and from Test to Promotion) are now allowed, according to the content of a work item following the process defined in the Rational Team Concert for System z project. Now you have reached the point at which you can test your code promotion, based on the samples installed. Figure 7 displays the result from SCLM when the code promotion is allowed and executed. Figure 8 displays the result when the work item does not meet the requirement for promotion.

Figure 7. Example of a code promotion on z/OS
Blue text output on black background
Figure 8. Example of a code promotion stopped on z/OS
Yellow text:

What's next

This part of the "Using IBM Rational Team Concert for System z and the Jazz platform" series provides the base knowledge to help you start integrating your host SCMs with Rational Team Concert for System z, thus solving some coexistence and migration challenges. By using two different scenarios, this article shows you not only how to get started with team collaboration across the various development organizations and platforms, from distributed to z/OS, but also some of the benefits of doing so.

The subsequent articles in this series will cover details of the new System z Scrum template, how to configure the components and streams within Rational Team Concert for System z, and integration with Rational Developer for System z and integrating Rational Team Concert for System z with your IBM® Rational® Build Forge® environment. Each article focusing on a different aspect of new functions provided with Rational Team Concert for System z V2.


REXX scripts for this articleRTCzArticleSamples.zip4KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Open source on developerWorks

Zone=Open source, Rational, DevOps
ArticleTitle=Using IBM Rational Team Concert for System z and the Jazz platform: Part 3. Govern your existing mainframe SCM systems with the IBM System z Jazz Gateway