Requesting user builds

A user build is a build request that generates JCL statements to build a program with IBM® Engineering Workflow Management (EWM) system definitions. The user build submits the build request outside of the IBM Engineering Workflow Management build infrastructure. The user build provides an alternative to the IBM Engineering Workflow Management personal build.

Before you begin

The COBOL, PL/I , or C/C++ program must be assigned to a language definition that is associated with at least one translator. The build steps are defined in the language definition and all the required information to generate the JCL statements is in the translator.

If you want to add error feedback support to a user build, see Adding error feedback support to user builds.

About this task

You can run a User Build for COBOL, PL/I, and C/C++ files in the following projects:
  • A zComponent project in Engineering Workflow Management.
  • A z/OS® project in IBM Developer for z Systems®.
Starting from IBM Developer for z Systems V14.0, User Build identifies whether any of the system definition and properties that participate in the build for the selected file has a condition set. In such case, it makes one of the following decisions based on the conditions:
  • Whether the condition is understandable or translatable:
    • If it refers to a step return code, it will be translated into JCL.
    • If it is understandable, it will be resolved during the User Build generation time.
    The following table describes ant conditions that are supported.
    • equals
    • isfalse
    • isgreaterthan
    • islessthan
    • isset
    • istrue
  • If the condition is neither understandable or translatable. it is not supported. Hence any non-supported condition will be ignored. In this case, relational logic conditions, such as and, or, xor, and not, are not supported.
Refer to Conditions for detailed explanation on each ant condition.
Refer to Running System z System definitions generator Ant tasks for more detailed information about conditions for system definition. You can specify conditions in the following items participating in the Engineering Workflow Management Enterprise Extension build:
  • Language Definition Properties

    Condition determines whether a property is considered in the language definition and translator of the property.

  • Translators

    Condition determines the final list of translators that are used for building a program assigned by the language definition.

  • DD Concatenations or DD Allocations

    Condition defines the final list of data set definitions that the translator uses.

Starting from IBM Developer for z Systems V14.0 and the corresponding RTC integration with CLM V6.0.5, User Build supports definition of a DD Allocation as in-stream data as part of a Engineering Workflow Management build definition. You can define contents of a Data Set Definition entry as instream DD and specify the textual entries that makes up the data content. User Build generated build, such as generated JCL, considers when a Data Set Definition entry in a translator has been defined as in-stream data, the resulting JCL translates it and generates JCL compliant in-stream Data Set Definition entry contents.

After an initial successful user build, you have the option to save time by reusing the generated JCL from a previous build. When you start a build, you are prompted to indicate if you want to use the previously generated JCL. If yes is selected, the previously generated JCL for the file is used and a progress status is displayed. After the job completes, the User Build Job ID is displayed. During the build, data sets for recording error feedback information are created, these files are deleted after the job completes.

Requesting a user build from a zComponent project

Procedure

  1. Select a COBOL, PL/I, or C/C++ program in a zComponent project and then select User Build. The Configure User Build operation window prompts you for information about loading the main source file and any additional dependencies.
  2. Select the remote system and a build definition.
  3. In the Resource prefix to load field, specify a prefix for the name of a partitioned data set (PDS). The source file and any dependent files are loaded to this PDS for the build. This prefix is added to the data set definition to construct the partitioned data set name. For example, if you specify USERID.USER.BUILD, and the data set definition for the main source file is COBOL, then the source file is loaded into USERID.USER.BUILD.COBOL. If the data set definition for a copybook is COPY, then it is loaded into USERID.USER.BUILD.COPY. If the resulting data set names do not exist on the remote system, they are allocated during the build. The values that you specify on the Configure User Build operation window are saved for the next time you request a build for the resource.
    1. Optional: To select dependent files to upload, click Next. The Additional files to load page shows the list of zComponent projects in the Eclipse workspace. To load dependent files, follow one of these steps:
      • To manually select dependent files to upload, expand the projects that contain the files you want to upload and select the files. The JCL statements that are generated by a user build request build only one main source file. If you select any additional source files (.cbl, .pli, .c, or .cPP), a warning message states that only the main source file is built by the generated JCL statements.
        Note: The files that you select are saved for the next time you request a build for the resource. If you select the discovery option, all manually selected files are cleared. To recover your manual selections, click Cancel.
      • To have the product discover dependencies and upload them, select Discover the dependencies to load for building mainFile. To discover dependencies, the product searches user libraries and team libraries. If the main file is open in an editor, the product also uses the editor's dependency checking function to discover new or changed dependent files that are not yet checked in or delivered. If all dependencies are not loaded into your workspace, then a warning message lists the dependent files that are missing from the workspace.
  4. Optional: To see the list of libraries to be searched for dependencies, expand Search order. The Search order field lists the libraries to be searched for dependencies in the order that they are searched. The product searches for dependent files in user libraries first and then in team libraries.
  5. Click Finish. The main source file, and any dependent files you specified on the Additional files to load page, are loaded into the PDS. The data set prefix that you specified in the Resource prefix to load field is used for the partitioned data set (PDS). If the PDS does not exist, it is allocated. If the member exists, it is overwritten. The product generates JCL statements to run the build steps that are defined in the language definition that is assigned to the main source file. A message window opens stating that the generated JCL statements are being submitted.

    You can change the automatic submission of the JCL statements by changing the User Build preferences. You can access the preferences by clicking the Preferences link from either the Configure User Build operation window or the Additional files to load window. The preferences that you apply on the User Build preferences page are saved for the next time you request a build for the resource.

    By default, the Submit the generated JCL option on the User Build preferences page is selected. For the option to open and edit the JCL statements after you click Finish, clear the box and apply this preference. In the message window, you can initiate the following actions:
    • To open the generated JCL statements in an editor session, click Open. You can submit the JCL statements from the editor and look for any errors in the job output.
    • To submit the JCL statements, click Submit. A job submission confirmation window opens. To locate the job ID in the Remote Systems view, click Locate Job. The job ID is highlighted in the Retrieved Jobs filter of the JES subsystem. Any compilation errors are shown in the Remote Error List view.

    The User Build preferences page also contains the default JCL job card. You can customize the JCL statements to use different values for the job parameters or add information such as an accounting number or programmer name.

    On the JCL job card, you can change the REGION parameter to allow more than 2048Kb. A JOB statement REGION parameter applies to all steps of the job and overrides any EXEC statement REGION parameters. You can specify REGION=0M in the default job card. A value equal to 0K or 0M gives the job step all the storage available under and over 16 megabytes. The resulting size of the region under and over 16 megabytes depends on system options and what system software is installed.

    The generated JCL statements create a TSO environment by generating a custom IKJEFT01 EXEC step. The step uses the information in the ISPF.conf and rsed.envvars files to use the ISPF or TSO command or exec call method that is provided in the translator.

Requesting a user build from a z/OS project

Procedure

Select a COBOL, PL/I, or C/C++ program in a z/OS project and then select zComponent > User Build.

Results

The product generates JCL statements to run the build steps that are defined in the language definition that is assigned to the main source file. The JCL statements are automatically submitted.

The generated JCL statements create a TSO environment by generating a custom IKJEFT01 EXEC step. The step uses the information in the ISPF.conf and rsed.envvars files to use the ISPF or TSO command or exec call method that is provided in the translator.

What to do next

You can change the automatic submission of the JCL statements by changing the User Build preferences. You can access the preferences by selecting Window > Preferences from the menu bar.

The User Build preferences page contains the default JCL job card. You can customize the JCL statements to use different values for the job parameters or add information such as an accounting number or programmer name.

By default, the Submit the generated JCL option on the User Build preferences page is selected. To open and edit the JCL statements, clear the box and apply this preference. The preferences that you apply on the page are saved for the next time you request a build for the resource.


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