Configure Rational Team Concert to build ISPF Dialog Tag Language components

Learn the different steps required for setting up the language definitions and translators

Many Rational customers use IBM Interactive System Productivity Facility (ISPF) Dialog Tag Language (DTL) on IBM z/OS systems to define and create their ISPF panels and messages. Invoking the ISPF DTL conversion utility requires different steps in the setup of the language definitions and translators in Rational Team Concert. Liam Doherty explains those steps.

Share:

Liam Doherty (dohertl@au1.ibm.com), Rational Team Concert Enterprise Extensions Architect, IBM

author photoLiam Doherty is an enterprise extensions architect and ISPF client developer for Rational Team Concert. He has more than 30 years of experience with the Multiple Virtual Storage (MVS) operating system. For the past 11 years, he has concentrated on source configuration management in Software Configuration and Library Manager (SCLM) and Rational Team Concert.



18 June 2013

Overview

Many IBM customers, as well as the IBM® Rational Team Concert™ development team, use the IBM Interactive System Productivity Facility (ISPF) Dialog Tag Language (DTL) to generate ISPF panels and messages. You can use DTL to ensure that all of your panels have a consistent look and feel when they employ the ISPF Common User Access (CUA) guidelines.

DTL parts are just members of libraries, the same as other parts. But to create the ISPF panels and messages, these DTL parts need to be passed through the DTL conversion utility, ISPDTLC. This utility takes the input members and any imbedded includes and generates the required ISPF panels and messages from them.

There are several steps required to implement DTL support. This includes creating the required IBM® z/OS® system definitions. To correctly find the dependencies between the DTL members and any included members that they use, Rational Team Concert provides a new DTL scanner, starting with the 4.0.3 release. Additionally, due to the way that ISPDTLC allocates the files that it uses, a sample REXX exec, called BLZDTLRX, is also provided to facilitate invoking ISPDTLC from a Rational Team Concert translator.

The examples in this article are from the Rational Team Concert development teams' implementation of DTL. The team used two different library types to contain the DTL parts, GML and GMLINC (GML is the initialism for General Markup Language). We could have used DTL and DTLINC just as well. The GML library contains the members that define the strings that are displayed on each panel. The GMLINC contains the included members that define the layout of the panel and the panel logic. The reason to separate all of the strings into the GML members was because translation to both uppercase and Japanese was required. So GMLUP and GMLJPN libraries would also be used, but the GMLINC library could be used in all cases.

To keep things simple, the scenario here is without the requirement to have uppercase and Japanese.


Create the required system definitions to manage DTL

There are several z/OS system definitions to create, including data set definitions, language definitions, and translators.

Data set definitions

The first definitions to create are the data set definitions required for input and output data sets. Table 1 shows the required attributes for each data set definition.

Table 1. List of data set definitions to create
NameUsageData set nameFormat, record length, blksize
GML Destination data set for a zFolder GML FB/80/27920
GMLINC Destination data set for a zFolder GMLINC FB/80/27920
Panels New data set used for build PANELS FB/80/27920
Messages New data set used for build MESSAGES FB/80/27920

Obviously, you can use whatever name you like for the data set definition and for the data set name.

Translators

There is only one translator to define, and that is the DTL Translator. This translator will call a REXX exec, described later, that performs the DTL translation by calling the ISPF ISPDTLC conversion exec. ISPDTLC expects the allocations for the input DTL and the output panels and messages to be constructed in a certain way. It is not possible to invoke the ISPDTLC exec directly from a Rational Team Concert translator, because Rational Team Concert allocates required files in a different way. So the 4.0.3 release provides a REXX that takes the Rational Team Concert allocations and translates them into the allocations expected by ISPDTLC.

Table 2. The three required allocations that are required
DD nameUseData set definition
DTLGML Concatenation of GML and GMLINC libraries GML
GMLINC
DTLPAN Generated ISPF panels Panels
DTLMSG Generated ISPF messages Messages

Notice in the DD Allocations (Figure 1) that specifying a member is set to no. This is because ISPDTLC expects the data sets to be allocated, not the output members.

Figure 1. DTL translator showing invocation parameters and data set allocations
DD Allocations required for the DTL translator

Language definitions

There are two language definitions required: One to scan and build the GML and the other to scan any includes, because includes can contain other includes.

  • Create the DTL language definition with a language of Other, using a file extension of .gml, and add the DTL translator that you created in the previous step.
  • For the DTL Include language definition, create it with a language of Other and a file extension of .gmlinc, but do not add a translator, because the includes are not required to be built, just scanned.
Figure 2. DTL language definition
Screen shows language definition for DTL
Figure 3. DTL Include language definition
language definition dialog window

In both the DTL and DTL Include examples, the scanners tab should be opened, and the Default Scanner for System z should be changed to the DTL Scanner for System z:

  1. Highlight the Default Scanner for System z and select Remove.
  2. Then click the Add button, and select DTL Scanner for System z from the list.

In addition, the Dependency Type will be set to all of the defaults, including the new DTLINC dependency type. For efficiency, perform the following tasks:

  1. Remove all of the dependency types other than DTLINC by highlighting the dependency types and clicking the Remove button.
  2. For the DTL language definition, select the DTLINC dependency type and click the Edit button.
  3. Select the Only the translators specified below radio button, and then select the DTL translator that you created previously.
Figure 4. Editing the dependency type
Ensure that only the DTL translator is used

When you are finished, the scanner-specific settings for the DTL language definition should look like those in Figure 5.

Figure 5. Source code scanners for DTL
Language Definition details view

For the DTL Include language definition, the only difference should be that the DTLINC dependency type does not use a specific translator, but has <all> translators selected.


Associate your source code with the required language definition

For the DTL scanner to pick up the dependencies, you need to associate your files with the correct language definition. In the actual Rational Team Concert development scenario described previously, there are includes in both the GML and GMLINC libraries. For example, there is a BLZ@ENT1 member in the GML library that contains all of the common strings that many panels use. Additionally, the action bar choice drop-down menus are also common parts included in most panel GML members.

As such, all of the GMLINC members, the BLZ@ENT1 and the action bar choice members are all associated with the DTL Include language definition. This language definition, described previously, does not have any translators, so will not build anything, but it will run the DTL scanner to capture any additional dependencies. All of the GML members that actually need to be run through the ISPDTLC conversion utility are associated with the DTL language definition.

After the language definitions have been associated with the files, it might be necessary to rescan the streams to update the source code data. If you have not activated source code scanning, you will need to do so:

  1. Expand the Enterprise Extensions node in your project area, and then right-click Source Code Data.
  2. Then select the Select Streams for Scanning option, and select the streams that contain your DTL code.

Note:

If you had already activated the streams for scanning, you might need to reset or update your source code data to ensure that all dependencies are tracked.


Analyze the impact

After the Source Code Data is up to date, you can use that information in the various impact analysis tools that Rational Team Concert provides.

  1. Take one of the GML parts that will be built, right-click, and select Enterprise Extensions > Open Source Code Data Editor.

The Source Code Data display (Figure 6) for that GML member will list of all the included members.

Figure 6. Source code data editor
Screen shows DTL included dependencies

In addition, you can analyze the actual impact. For example, if you want to see what parts are affected by a potential change to the BLZOPTS GMLINC member, which is one of the action bar choice includes:

  1. Right-click on the BLZOPTS part.
  2. Select Enterprise Extensions > Impact Analysis, and then select the Show files that depend on this file radio button, and click Finish.

Rational Team Concert will give you a list of potential files, as the example in Figure 7 shows.

Figure 7. Impact analysis results
GML files that are dependent on an included file

Learn more about the DTL invocation exec

The DTL invocation exec sample that is supplied in Version 4.0.3 of Rational Team Concert is fairly straight-forward in that it takes the GML member and associated included files as input, then outputs either an ISPF panel member or an ISPF message member, depending on the GML member being built.

This exec takes the member being built as input. Rational Team Concert allocates the GML and GMLINC data sets to the DTLGML DD, as well as the Panels data set to the DTLPAN DD and the Messages data set to the DTLMSG DD. (This was described in more detail previously in the Translators section.) The exec interrogates these allocations to find the physical data sets that have been allocated by Rational Team Concert. It then allocates the DTLPDDN file, because that is the expected input to the ISPDTLC conversion routine, and populates this file with the names of the physical data sets to be allocated by ISPDTLC.

ISPDTLC is then invoked with the required parameters to generate a US English panel or message member. Figure 8 shows the contents of the BLZDTLRX member.

Listing 1. Contents of BLZDTLRX, exec to invoke the ISPF DTL translator
/* REXX */                                                             
/*********************************************************************/
/*                                                                   */
/* Rational Team Concert, Version 4, Release 0, Level 3              */
/*                                                                   */
/*                                                                   */
/* Copyright:    Licensed Materials - Property of IBM                */
/*                                                                   */
/*               "Restricted Materials of IBM"                       */
/*                                                                   */
/*               5724-V04                                            */
/*                                                                   */
/*               Copyright IBM Corp. 2013                            */
/*                                                                   */
/*               US Government Users Restricted Rights -             */
/*               Use, duplication or disclosure restricted by        */
/*               GSA ADP Schedule Contract with IBM Corp.            */
/*                                                                   */
/* Modification History                                              */
/*                                                                   */
/*                                                                   */
/*********************************************************************/
/*                                                                   */
/* NAME := BLZDTLRX                                                  */
/*                                                                   */
/* DESCRIPTIVE NAME := RTC Exec to invoke ISPF DTL translator        */
/*                                                                   */
/* FUNCTION := Invoke the ISPF DTL conversion rotine ISPDTLC         */
/*********************************************************************/
                                                                       
   Parse Arg '('Member')'                                              
                                                                       
   Say 'Generating Panel for member : 'Member                          
   Say ''                                                              
                                                                       
   x = msg('off')                                                      
   Address TSO "FREE  F(DTLPDDN)"                                      
   x = msg('on')                                                       
   Address TSO "ALLOC F(DTLPDDN) UNIT(SYSALLDA) NEW SPACE(1 1) TR",    
                    "RECFM(F B) LRECL(80) BLKSIZE(27920)"              
                                                                       
   j = 0                                                               
   Lang = 'ENU'                                                        
                                                                       
   /* Get the DTLGML allocation of data sets */                        
   Address ISPEXEC "QBASELIB DTLGML ID(DTLGML)"                        
   If rc = 0 Then                                                      
   Do                                                                  
      /* Just work out if we are doing a Japanese conversion */        
      Do While DTLGML /= ''                                            
         PARSE VAR DTLGML DSname "," DTLGML                            
         j = j + 1                                                     
         dtlpddn.j = 'DTLGML 'Strip(DSname)                            
      End                                                         
   End                                                            
                                                                  
   /* Get the DTLPAN data set allocation */                       
   Address ISPEXEC "QBASELIB DTLPAN ID(DTLPAN)"                   
   If rc = 0 Then                                                 
   Do                                                             
      j = j + 1                                                   
      dtlpddn.j = 'DTLPAN 'Strip(DTLPAN)                          
   End                                                            
                                                                  
   /* Get the DTLMSG data set allocation */                       
   Address ISPEXEC "QBASELIB DTLMSG ID(DTLMSG)"                   
   If rc = 0 Then                                                 
   Do                                                             
      j = j + 1                                                   
      dtlpddn.j = 'DTLMSG 'Strip(DTLMSG)                          
   End                                                            
                                                                  
   Call InvokeDTL                                                 
                                                                  
   x = msg('off')                                                 
   Address TSO "FREE  F(DTLPDDN)"                                 
   x = msg('on')                                                  
                                                                  
Exit DTL_rc                                                       
                                                                  
InvokeDTL:                                                             
                                                                       
   'EXECIO 'j' DISKW DTLPDDN (FINIS STEM dtlpddn.'                     
                                                                       
   DTLParms = 'CUASUPP NOPREP NOLSTVIEW NODSNCHK NOGUI PROFDDN=DTLPDDN'
                                                                       
   /* If DBCS is required you may need to include the following */     
   /* DTLParms = 'JAPANESE DBCS KANA 'DTLParms                  */     
                                                                       
   DTLParms = 'ENGLISH 'DTLParms                                       
   Address TSO "%ISPDTLC "Member" ( "DTLParms                          
   DTL_rc = rc                                                         
                                                                       
Return

The actual REXX exec used by the Rational Team Concert development team is included in the compressed REXXDTL.rex file in the Downloads section of this article. It contains extra steps to process Japanese GML members, based on different allocated files, as well as for converting English members to uppercase English, which is a requirement for many IBM products. Screen captures of the DTL translators used by the Rational Team Concert development team are also included.


Build the DTL

The DTL is built in the same way as any other language definition. Ensure that you have added the DTL language definition to the languages definitions list in your build definition. As the files are built, there will be an ISPF Gateway output log included in your build results if you have Publishing turned on.

Figure 8. Built outputs for DTL
Screen segment of log files list for a DTL build

As Listing 2 shows, the output is standard ISPDTLC output wrapped in the ISPF gateway response XML.

Listing 2. Output from the DTL exec
Content-Type: text/plain

<?xml version="1.0"?>
<ISPF-OUTPUT>
 <SERVICE-REQUEST>
<service>ISPF</service>
<session>NONE</session>
<command>TSO EXEC 'MYUSER.RC0TEST.ID07592.EXEC'</command>
 </SERVICE-REQUEST>
 <SERVICE-RESPONSE>
  <ISPF-COMMAND>
   ISPSTART CMD(EXEC 'MYUSER.RC0TEST.ID07592.EXEC') NEWAPPL(ISR) NEST NESTMACS
  </ISPF-COMMAND>
  <ISPF>
  <![CDATA[
   Generating Panel for member : BLZSLRWS
    
   ISPC021I: ISPDTLC ISPF 6.1 Dialog Tag Language Conversion Utility
   ISPC020AI: ISPF Dialog Tag Language Conversion Utility for ISPF 6.1. Current
      APAR level: OA31516. Current PTF number: UA52343.
   ISPC022I: Converting source file "MYUSER.RC0TEST.GML(BLZSLRWS)"...
   ISPC029I: 0 warning(s) and 0 error(s) found.
   JAZZ_TRANSLATOR_RETURN_CODE = 0
  ]]>
  </ISPF>
  <RETURN-CODE>0</RETURN-CODE>
 </SERVICE-RESPONSE>
 <OPERATIONS-LOG>
 <![CDATA[

Summary

Setting up and building DTL parts really is no different from any other parts in Rational Team Concert, apart from the use of an intermediate REXX exec to handle the allocations. This article puts the complete process into an easy-to-understand format that you can use not only to get your DTL to build successfully but also to create your own processes for other types of languages.


Download

DescriptionNameSize
Rational Team Concert development team filesBuilding-DTL-with-RTC.zip110KB

Resources

Learn

Get products and technologies

  • Download Rational Team Concert from Jazz.net and try it free for up to 10 developers for as long as you want (requires registration). If you'd prefer, you can try it in the sandbox instead, without installing it on your own system.
  • Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, or use it in a cloud environment.

Discuss

Comments

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 Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=934307
ArticleTitle=Configure Rational Team Concert to build ISPF Dialog Tag Language components
publish-date=06182013