Generating build metadata automatically using the language definitions generator

Use the language definitions generator on the Rational Team Concert™ for System z® integrated development environment (IDE) client to create data set definitions, translators, and language definitions without using an editor.

Before you can use the language definitions generator, you must:

Importing a zComponent project to use with the language definitions generator

Complete this task to practice using the language definitions generator with a sample project, several of which were installed with the Rational Team Concert for System z client.
  1. In Rational Team Concert for System z, open the Resource perspective.
    1. Click Window.
    2. Hover over Open Perspective.
    3. Select Other.
    4. Select Resource.
    5. Click OK. The Project Explorer view is displayed.
  2. In the Project Explorer view, right-click your project and select Import. The Import wizard Select window opens.
  3. In the Import wizard Select window, expand the General node and select Existing Projects into Workspace.
  4. Click Next. The Import wizard Import Projects window opens.
  5. Select the Select root directory radio button and click Browse.
  6. Select the root directory of the project you want to import. Sample projects are stored in the rtcz\samples subdirectory of the Rational Team Concert for System z installation directory: C:\Program Files\IBM\SDP\rtcz\samples.
  7. Select the boxes next to the projects you want to import. The following sample projects are available:
    HelloWorldSample
    A simple “Hello World” COBOL application sample.
    HelloWorldSample2
    An additional “Hello World” application in host assembler, PL/I and C.
    MortgageApplication
    A COBOL sample application with multiple zComponent projects. To import this sample project, select all the projects whose names start with MortgageApplication.
  8. Click Finish.

Running the Rational Team Concert for System z language definitions generator

  1. Expand your project node.
  2. Select the setuprtcz.xml file, then select Run As > Ant Build.
    Note: The setuprtcz.xml is the name of the file that is included in the sample project. If you write your own file, make sure you give it the .xml file extension.
  3. Select the Properties tab, then clear the box next to Use global properties as specified in the Ant runtime preferences, then add following properties:
    • repositoryAddress. This is your Rational Team Concert for System z URL.
    • userId. This is your Rational Team Concert for System z user ID.
    • password. This is your Rational Team Concert for System z password.
    • projectArea. This is the name of your project area.
  4. Select the JRE tab, then select Run in the same JRE as the workspace.
  5. Click Apply, then Run. If you successfully run the language definitions generator, you will have created all required data set definitions, translators, and language definitions, and the metadata contained in your selected projects will be updated to point to the new definitions.
  6. Go to the Pending Changes view and verify your changes to the metadata.
  7. Go to the Work Items perspective, right-click your project area, and click Refresh. In the Team Artifacts view, your new data set definitions, language definitions, and translators should all be displayed within your project area.

Language definitions generator Ant tasks

Use the Rational Team Concert for System z language definitions generator to perform the following custom Ant tasks. Each task name represents the Java™ class name that implements the task.

InitTask

InitTask is a custom Ant task that initializes connections with the Rational Team Concert for System z server for other data set definition, translator, and language definition tasks. You must perform the InitTask before any other data set definition, translator, or language definition tasks.
Table 1. InitTask attributes
Attribute Description
repositoryAddress URL string to the Rational Team Concert for System z server
userId Rational Team Concert for System z user ID
password Rational Team Concert for System z password
passwordFile Rational Team Concert for System z password file
projectArea The name of the project area where associated data set definitions, translators, and language definitions are stored.
The following is an example of an InitTask:

<ld:init repositoryAddress="https://opusdejazz.raleigh.ibm.com:9443/jazz"userId="tami" password="tami" projectArea="Build Test"/>

DsDefTask

Use this task to create a data set definition.
Table 2. DsDefTask attributes
Attribute Description Default
name Definition name  
description Definition description  
dsName Data set name  
dsMember Member name  
prefixDSN true if the prefix you specified in the build request should be prepended to the data set name. true
dsDefUsageType
  • 0 = zFolder
  • 1 = new
  • 2 = temp
  • 3 = existing
0 (zFolder)
dsType
  • 0 = PDSE
  • 9 = UNSPECIFIED
0 (PDSE)
storageClass Storage class to which the data set is assigned.  
dataClass Data class used to create the data set.  
managementClass Management class used to manage the data set.  
volumeSerial Data set volume serial number  
GenericUnit generic group name or unit address  
spaceUnits Unit of allocation spaces to be used. The value must be one of the following:
  • trks (tracks)
  • blks (blocks)
  • cyls (cylinders)
 
recordUnit Unit of allocation quantity. The value must be one of the following:
  • U (single)
  • K (thousand)
  • M (million)
U
primaryQuantity Primary allocation quantity 1
secondaryQuantity Secondary allocation quantity 1
directoryBlocks Number of 256-byte directory blocks provided. 0
recordLength Logical length in bytes 80
blockSize Block size  
recordFormat A z/OS® data set record format string, such as F, FB, V, VB or U. Possible values include the following:
  • F (fixed)
  • V (variable)
  • U (undefined)
  • B (blocked)
  • A (Specifies that the file contains ASA control characters.)
  • M (Specifies that the file contains machine control characters.)
  • S (standard format if fixed; spanned format if variable)
  • T (truncated)
FB
The following is an example of a DsDefTask:

<!-- zFolders --> <ld:dsdef name="COBOL" dsName="COBOL" dsDefUsageType="0" dsType="0" spaceUnits="cyls" primaryQuantity="1" secondaryQuantity="1" recordFormat="FB" recordLength="80" blockSize="0" />  

<!-- New data sets --> <ld:dsdef name="OBJ" dsName="OBJ"  dsDefUsageType="1" dsType="0" spaceUnits="cyls" primaryQuantity="1" secondaryQuantity="1" recordFormat="FB" recordLength="80" blockSize="0" /> <ld:dsdef name="LOAD" dsName="LOAD"  dsDefUsageType="1" dsType="0" spaceUnits="cyls" primaryQuantity="1" secondaryQuantity="1" recordFormat="U" recordLength="0" blockSize="32760" />

<!-- Temporary data set --> <ld:dsdef name="TEMPFILE" dsDefUsageType="2" prefixDSN="false" dsType="9" spaceUnits="trks" primaryQuantity="5" secondaryQuantity="5" genericUnit="SYSALLDA" />

<!-- Existing data sets --> <ld:dsdef name="IGYCRCTL" dsName="COBOL.V4R1M0.SIGYCOMP" dsMember="IGYCRCTL" dsDefUsageType="3" prefixDSN="false"/> <ld:dsdef name="IEWBLINK" dsMember="IEWBLINK" dsDefUsageType="3" prefixDSN="false"/> <ld:dsdef name="SCEELKED" dsName="CEE.SCEELKED" dsDefUsageType="3" prefixDSN="false"/>

TranslatorTask

Use this task to create a translator. TranslatorTask accepts Allocation and Concatenation as child elements. Use the propertyName attribute with DD allocations or DD concatenations to specify certain build properties.
Table 3. TranslatorTask attributes
Attribute Description Default
name Translator name  
propertyName Build property name  
description Translator description  
dataSetDefinition Data set definition for translator module  
ddnamelist Alternate DD names list for the translator  
defaultOptions Option string that is passed to the translator.  
maxRC Maximum return code allowed 0
The following is an example of a TranslatorTask. Note that the SYSLIB DD concatenation contains one build property–teamz.mylib–and the SYSPRINT DD allocation contains another–teamz.sysprint.

<ld:translator name="ASMMAP" dataSetDefinition="ASMA90"

   defaultOptions="SYSPARM(MAP),DECK,NOOBJECT"

   ddnamelist="SYSLIN,,,SYSLIB,SYSIN,ANTPRINT"

   maxRC="0">

   <ld:concatenation name="SYSLIB">

      <ld:allocation dataSetDefinition="SDFHMAC"/>

      <ld:allocation propertyName="teamz.mylib"/>

   </ld:concatenation>

   <ld:allocation name="SYSIN" input="true"/>

   <ld:allocation name="SYSPUNCH" dataSetDefinition="OBJ" member="true"/>

   <ld:allocation name=SYSPRINT" propertyName="teamz.sysprint"/>

   <ld:allocation name="SYSUT1" dataSetDefinition="TEMPFILE"/>

   <ld:allocation name="SYSUT2" dataSetDefinition="TEMPFILE"/>

   <ld:allocation name="SYSUT3" dataSetDefinition="TEMPFILE"/>

</ld:translator>

LangDefTask

Use this task to create a language definition. Use the translators attribute to specify certain build properties.
Notes:
  • The runtime code assumes that any name you specify in the translators attribute is the name of a translator. When you do not specify a translator name, the runtime code treats the translator name as a build property. When this happens, you must define the build property in the associated build definition so that it points to a specific translator.
  • You can specify more than one translator in the translators attribute by using a colon as a delimiter.
Table 4. LangDefTask attributes
Attribute Description
name Language definition name
description Language definition description
translators Names of translators, delimited by a colon
defaultExtension Associated default file extension
languageCode Language code for the language definition. See Table 5 for the list of supported language codes.
subsystems Subsystems used in the language definition. When two or more subsystems are used, they are delimited by commas. See Table 6 for the list of supported subsystems.
Table 5. Supported language codes
Language code Description
ASM Assembler
BIN Binary
BND Bind
C C
CPP C++
EASY CA Easytrieve
COB COBOL
JCL JCL
LNK Link-edit
PLI PL/I
OTH Others
Table 6. Supported subsystems
Subsystem Description
CICS CICS
DB2 DB2
IMS IMS
The following is an example of a LangDefTask with subsystem specified in the subsystems attribute:

<ld:langdef name="COBOL-CICS-DB2" translators="IGYCRCTL-CICS-DB2" defaultExtension="cbl"

      languageCode="COB" subsystems="CICS,DB2"/>

The following is an example of a LangDefTask with a build property specified in the translators attribute.
Remember: When you do not specify a translator name, teamz.my.preprocessor is treated as a build property.

<ld:langdef name="MY PLI" translators="teamz.my.preprocessor,IBMPLI" defaultExtension="pli"

      languageCode="PLI" subsystems=""/>

DeleteDsDefsTask

Use this task to delete all data set definitions.
The following is an example of a DeleteDsDefsTask:

<ld:deletedsdefs/>

DeleteTranslatorsTask

Use this task to delete all translators.
The following is an example of a DeleteTranslatorsTask:

<ld:deletetranslators/>

DeleteLangDefsTask

Use this task to delete all language definitions.
The following is an example of a DeleteLangDefsTask:

<ld:deletelangdefs/>

ResolveMetadataTask

Use this task to associate zFiles with language definitions and zFolders with data set definitions. These associations are stored in the .antzBuild subdirectory of each zComponent project. You can make an association between zFiles and language definitions by using the zFile extension and the defaultExtension attribute of a given language definition. For example, if the language definition COBOL has the defaultExtension attribute cbl, the zFile HELLO.cbl is associated with that language definition. You can make an association between zFolders and data set definitions by using the names of zFolders and the names of data set definitions. For example, if you have a data set definition named HELLO.COBOL, the zFolder HELLO.COBOL is associated with the data set definition of the same name.

You can nest <langdefrule> and <dsdefrule> to supply association rules that override the defaults.

Table 7. ResolveMetadataTask attributes
Attribute Description Default
projectRoot Root directory of the zComponent project The directory where the script is stored.
Table 8. landefrule attributes
Attribute Description Default
match The regular expression used for this rule. This is used against the string (zFolder name)/(zFile name); for example COBOL/source.cbl. None
languageDefinition The name of the language definition you want to associate when the regular expression matches the string (zFolder name) (zFile name). None
Table 9. dsdefrule attributes
Attribute Description Default
match Regular expression used for this rule. This is used against zFolder name, for example COBOL. None
dataSetDefinition Data set definition name to be associated with when the regular expression matches. None
In the following example, zFolder BMS will be associated with the ASM data set definition. EPSCSMRT.cbl and EPSCMORT.cbl will be associated with the COBOL-DYNAM-CICS and COBOL-CICS-DYNAM-CICS-DB2 language definitions respectively.

<ld:resolvemetadata projectRoot="../MortgageApplication-EPSCMORT">

        <ld:dsdefrule match="BMS" dataSetDefinition="ASM"/>

        <ld:langdefrule match=".*/EPSCSMRT\.cbl$" languageDefinition="COBOL-DYNAM-CICS"/>

        <ld:langdefrule match=".*/EPSCMORT\.cbl$" languageDefinition="COBOL-DYNAM-CICS-DB2"/>

    </ld:resolvemetadata>


Feedback