Creating a z/OS translator

Create a translator to represent an operation that is run on all the buildable files that are associated with a particular language definition.

Before you begin

You must create a project area before you begin this task. You must also create a data set definition that specifies the translator module you want to use during a build.
Restriction: Before you can create, modify, or delete a translator, you must have permission to change the translator. You can manage these permissions from the Project Configuration node on the Process Configuration tab in the Project Area editor.

About this task

You can create a translator one of two ways:
  1. Expand these nodes in the Team Artifacts navigator: Enterprise Extensions > System Definitions > z/OS > Language Definitions > Translators.
  2. From the main menu, select File > New > Other > Enterprise Extensions > z/OS > Translator.

The following task describes how to create a translator from the Translators node in the Team Artifacts navigator.

Procedure

  1. From the Team Artifacts view, select your repository connection and log in to your project area.
  2. Expand your project area node, and then expand Enterprise Extensions > System Definitions > z/OS > Language Definitions > Translators.
  3. Right-click the Translators node and click New Translator. The Translator editor opens with two tabs: General and History.
  4. In the Name field of the Translator editor, provide a name for the translator.
  5. Optional: On the General tab, in the Description field, provide a brief description of your new translator.
  6. Optional: If you want to use this translator to call a z/OS® binder to link-edit, select Link-edit.
  7. If you made changes to this translator that do not require a full analysis of buildable files, select Ignore changes to this system definition during a dependency build. For more information about analysis of buildable files, see Running dependency builds on z/OS and IBM i systems.
  8. In the Call Method field, select one of the following call options:
    • Called program
    • ISPF/TSO command or exec
    • Ant snippet
    • Ant build file
    Note: You cannot invoke an authorized program, such as IKJEFT01, using the Call Method options. However, the ISPF gateway enables client applications to connect to a z/OS host and run TSO and ISPF commands. For more information, see Configuring the ISPF gateway for build, deployment, and promotion support.
    1. If you select Called program, browse to the data set definition that specifies the translator module you want to use during a build.
      Note: You cannot save your new translator if you select Called program and do not specify a translator module in the Data Set definition field.
      1. Optional: In the Default options field, indicate any default compile or link-edit options, which are separated by commas.
        Note: For a link-edit translator, you can save time stamps in the system status index (SSI) of the generated program objects. Specify the SSI option in the default options of the link-edit translator. Include the SSI(@{ssi_info}) option at the end of default options. A time stamp that is stored in the SSI is also used by Rational Team Concert™.
      2. If necessary, in the DD names list field, specify a list of alternative DD names for the data sets that the translator uses.
    2. If you select ISPF/TSO command or exec, also select either ISPF or TSO. For either selection, specify the following options:
      Command/member
      Enter a string that represents an ISPF or TSO command or executable file. For example, EXEC ’YOURID.YOUREXEC(MEMBER)’. If your command or executable file is contained in a data set allocated to an ISPF data set definition, such as SYSPROC or SYSEXEC (as specified in ISPF.conf), you can specify just the executable file name. For more information about running ISPF commands or executable files, and about configuring the ISPF gateway, see Configuring the ISPF gateway for build, deployment, and promotion support.
      Publish ISPF Gateway Log
      To control the publishing of the ISPF log, select one of the following values. You can select when the log is published:
      Inherited
      The ISPF Gateway log is published in the build result, according to the settings in the build definition. This is the default behavior.
      No
      Select this option if you do not want to publish the ISPF Gateway log.
      Always
      The ISPF Gateway log is published in the build result for all builds.
      On error only
      The ISPF Gateway log is published in the build result, but only if the build fails.
      Consolidate ISPF Gateway Log
      To control whether the ISPF Gateway log is consolidated, select a value for Consolidate ISPF Gateway Log:
      Inherited
      The ISPF Gateway log is consolidated in the build result, according to the settings in build definition. This is the default behavior.
      No
      Select this option if you do not want to consolidate the ISPF Gateway log.
      Always
      The ISPF Gateway log is consolidated for all builds.
      On success only
      The ISPF Gateway log is consolidated for all builds only if the build completes successfully.
      Compact ISPF Gateway Log
      To control whether the ISPF Gateway log file produced is compacted. When uploaded to a build result, trailing whitespace is removed.
    3. If you select Ant Snippet, you can specify Ant syntax to be included during the dependency build when a language definition calls the translator. As part of the dependency build, Ant scripts have access to the build context, including variables and properties.
    4. To use an HFS build script, you need to select Ant build file. You need to specify the custom ant script:
      Build file
      Fill in the path of your custom build file. The path is relative to the load directory. You can refer to properties or attributes in this field.
      Build targets
      Specify the build targets to be invoked.
      Build return properties
      Fill in the list of properties returned by the ant script and separate them with commas. This makes the listed properties, presumably set by your script, available to the rest of the build environment.
      Note: If you choose Ant build file and change it to a different call method, a warning message will inform you that this change may break an HFS build.
    Tip: During a build, you can specify system variables in a z/OS translator to pass contextual information about the member the translator builds to a REXX script. When you modify translator variables, you can change how you compile a file or group of files without having to create a separate translator. Use one of the following variables with a z/OS command:
    • @{source.member.name}
    • @{source.member.scm.location}
    • @{source.member.file.extension}
    • @{source.dataset}
    • @{source.project}
    • @{source.component}
    • @{source.version}
    • @{source.reasontorebuild}
    • @{langdef.name}
    Here is an example:
    exec 'MYLIB.TEST.REXX(SCRIPT)' '@{source.project}, @{source.member.name}'

    You can define your own variables in a translator, and then use them in a command or option string; for example, if you define a variable that is called DAY and set its default value to MON, you can define a string like &DAY.DATA, and your build interprets it as MONDATA.

    You can override those variables with file or build properties whose prefixes are team.enterprise.build.var. In the previous example, if you define your build property team.enterprise.build.var.DAY as SUN, the string &DAY.DATA is interpreted as SUNDATA in a build.

    With translators that have the Call Method that is set to Called program, you can use temporary data sets to pass data from one translator to another; for example, if compilation and link-edit translators both have the Call Method that is set to Called program, the compilation translator can write an object deck in a temporary data set named &&OBJ and the link-edit translator can use the data set. In addition, you can publish the temporary data set after you write the SYSPRINT DD to it.

    If you set your translator call method to ISPF command or exec or TSO command or exec, you cannot use temporary data sets to pass data between translators, nor can you publish temporary data sets.

  9. Optional: In the Maximum Return Code field, enter either zero or any positive integer.
    Note: If you leave the Maximum Return Code field empty, z/OS applies a default value of zero.
  10. In the Data Set Properties section, click Add, Edit, or Remove to specify or change any DD concatenations in the concatenations table or variables that are required by the translator. For more information about modifying translators, see Building with Ant with Enterprise Extensions and the Rational Build Agent.
    1. When you add or edit an entry in the DD concatenations table, you can specify conditions for the DD names to determine whether the entry is processed. Conditions should be specified as Ant conditions, such as <ac:islessthan arg1="1" arg="2">. You can specify multiple DD names with the same name, as long each of them specifies a condition. However, if more than one DD of the same name includes a condition that evaluates to be true, the build fails with a warning message.
      The following notes apply when conditional DD names are used.
      Note:
      • To use conditions for DD names in the DD concatenations table, you must install the version 6.0.5 Build System Toolkit that provides the Ant build toolkit. If you use the Build System Toolkit from a previous version, errors occur.
      • Trust outputs must be true.
      • Preview builds might not accurately represent what would really happen in a build, because the preview build cannot always predict the correct system definitions to use for the preview. If you have multiple DD names defined, the first DD name defined is used.
    2. If you click Edit in the DD allocations section, the Edit DD Allocation editor opens with four tabs, each of which include certain options:
      • DD Resource
      • Output
      • Publishing
      • Other Properties.
      The options you can specify on each tab are as follows:
      • DD Resource
        Data set definition
        Specifies the translator module to use during a build. Click Browse to select the data set definition that specifies the translator module.
        Build property
        You can reference any property that is defined as a build property in the properties section of your build definition, with the ${build.property} format. There are two build properties, which are used commonly, that do not display in the build properties list. The properties are derived from the Load Directory and Resource Prefix in the Jazz Source Control section of a build:
        • ${team.enterprise.scm.resourcePrefix}
        • ${team.enterprise.scm.fetchDestination}
        Build properties differ from the four system variables in that the build properties are the same for all built members. However, the four system variables vary from member to member.
        HFS path
        Specify this field if there are HFS files in your package. Click the Properties button to specify the properties.

        For more details of the Permission, PATHDISP, FILEDATA, and OPTIONS sections, PATHPERM, PATHDISP, FILEDATA, and PATHOPTS, refer to Requesting dynamic allocation.

        Translator input
        Select this option to use the input from a translator when you add or edit a DD allocation.
        Instream DD
        Select this option to enter data into the stream when you add or edit a DD allocation.
      • Output
        Save data set as output
        Select Save data set as output if you want to define an input member as an output or modify a translator output member name. You supply the member name in the Pattern or variable field on the Other Properties tab. Selecting Save data set as output enables the Output can be consumed by other programs option and the Apply pattern to member name option on the Other Properties tab.
        Note: If a data set name contains build properties and the data set definition is marked as output, the data set name cannot be used. You need to rename the data set.
        Output can be consumed by other programs
        Outputs are processed to determine whether the outputs are used as input to other programs. The Output can be consumed by other programs check box is selected by default. However, if you know that the output is not used as input to other buildable files, clear the check box. Clearing the check box speeds up the collection of buildable files.
        Deployment type or variable
        Enter either a deployment type or click Browse to select a variable that exists in the translator you are editing.
      • Publishing
        Publish
        To control the publishing of the log from the DD, select a value for Publish. You can select where and when the log is published:
        Inherited
        The logs are published in both the PDS and the build result, according to the settings in the build definition. This is the default behavior.
        No
        Select this option if you do not want to publish the output.
        Always
        The logs are published in both the PDS and the build result for all builds.
        On error only
        The logs are published in both the PDS and the build result, but only if the build fails.
        The value selected for publishing the output is displayed in the DD allocation table under the Publish Type column.
        Consolidate
        To control whether the output of the translator is consolidated, select a value for Consolidate:
        Inherited
        The output is consolidated in both the PDS and the build result, according to the settings in the language definition. This is the default behavior.
        No
        Select this option if you do not want to consolidate the output.
        Always
        The output is consolidated for all builds.
        On success only
        The output is consolidated for all builds only if the build completes successfully.
        Compact
        To control whether the log files produced during z/OS builds are compacted. When the log file is in a physical PDS, the log file is compressed to save space.
        Note: Compacted log files in the PDS can be decompressed in TSO using the BLZCMD API. For more information, refer to ../../com.ibm.team.build.doc/topics/r_blzcmd_api_interface.html#r_blzcmd_api_interface.
        When uploaded to a build result, trailing whitespace is removed.
        Inherited
        The log file is compacted in both the PDS and the build result, according to the settings in the data set definition. This is the default behavior.
        No
        The log files are not compacted.
        Yes
        The log files are always compacted.
      • Other Properties
        Sequential data set
        If you specified Sequential for Data set type in the Data Set Definition, the Sequential data set option is selected by default. You can clear the check for Sequential data set only if the translator defines a variable.
        Append member name to data set name
        Select this option to add the member name to the data set name.
        Keep data set when translator completes
        Select this option to keep a temporary data set when the translator completes the processing. Keep data set when translator completes can not be selected if the Sequential data set option is selected.
        Use DISP=MOD to append data to an existing allocation
        Select Use DISP=MOD to append data to an existing allocation to append data from a temporary sequential data set (Type=Sequential) to an existing temporary allocation. Selecting DISP=MOD requires that the outputs are compatible. For example, you cannot use DISP=MOD to append output from a binder to output from a COBOL compilation, because they do not have compatible data control blocks (DCBs).
        Apply pattern to member name
        You must select Apply pattern to member name to change a translator output member name. This option is enabled when you select Save data set as output on the Output tab. For details about translator output pattern rules, see Translator output pattern rules.
        Pattern or variable
        Enter a pattern for the member name when you select Apply pattern to member name. You can also optionally click Browse to select an existing variable. In the Variable Selection editor, specify a variable and click OK.
        Condition
        You can specify conditions for the DD names to determine whether the entry is processed. Conditions should be specified as Ant conditions, such as <ac:islessthan arg1="1" arg="2">. You can specify multiple DD names with the same name, as long each of them specifies a condition. However, if more than one DD of the same name includes a condition that evaluates to be true, the build fails with a warning message.
        Note:
        • To use conditions for DD names in the DD allocations tables, you must install the version 6.0.5 Build System Toolkit that provides the Ant build toolkit. If you use the Build System Toolkit from a previous version, errors occur.
        • Trust outputs must be true.
        • Preview builds might not accurately represent what would really happen in a build, because the preview build cannot always predict the correct system definitions to use for the preview. If you have multiple DD names defined, the first DD name defined is used.
  11. Optional: You need to define outputs used by this translator if you choose Ant Sipper or Ant build file call method:
    • You can use paths relative to ${team.enterprise.build.hfs.outputdir} to specify the outputs.
    • The conditional property to identify an output for a particular build is set by the build script. In this case, you need to add this property to Build return properties.
      Note: An HFS output can be one of several different types, directories must end with a slash (/).
  12. On the History tab, you can see all changes made over time by different users to the translator. You can review the state of the translator at any point in time, which is useful for debugging and fixing dependency build problems.
  13. To save your new translator, click Save.

What to do next

You can also duplicate any translator. To duplicate a translator, complete the following steps:
  1. Open the Team Artifacts view.
  2. Expand the Translators node.
  3. Right-click the translator to duplicate and click Duplicate.
  4. In the Duplicate system definition window, in the Name field, provide a name for the duplicate translator.
  5. To duplicate the translator, click OK. The new duplicate translator is displayed under the Translators node. If it is not, refresh the view.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki