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
|Name||Usage||Data set name||Format, 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.
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 name||Use||Data set definition|
|DTLGML||Concatenation of GML and GMLINC libraries||
|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
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
Figure 3. DTL Include language definition
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:
- Highlight the Default Scanner for System z and select Remove.
- 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:
- Remove all of the dependency types other than DTLINC by highlighting the dependency types and clicking the Remove button.
- For the DTL language definition, select the DTLINC dependency type and click the Edit button.
- 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
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
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:
- Expand the Enterprise Extensions node in your project area, and then right-click Source Code Data.
- Then select the Select Streams for Scanning option, and select the streams that contain your DTL code.
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.
- 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
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:
- Right-click on the BLZOPTS part.
- 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
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
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[
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.
|Rational Team Concert development team files||Building-DTL-with-RTC.zip||110KB|
- More about Rational Team Concert:
- Find Rational Team Concert articles and links to many other resources on IBM developerWorks, and check the product overview page, features and benefits, system requirements, and the user information center.
- Check the Rational Team Conncert page on Jazz.net.
- Watch the Using Rational Team Concert in a globally distributed team webcast or a demonstration of the Dashboards and reports, or listen to the podcast about IBM Rational Team Concert and Jazz.
- Explore the Rational software area on developerWorks for technical resources, best practices, and information about Rational collaborative and integrated solutions for software and systems delivery.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, anytime, and many of the Getting Started ones are free.
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.
- Get connected with your peers and keep up on the latest information in the Rational community and the Rational forums.
- Rate or review Rational software. It's quick and easy.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.