Application configuration

Application configuration refers to the ability for applications or application source files to override task variables declared in build configuration files. This can be useful in the following cases:

  • Application source files use a different folder structure from the common application structure.
  • A the compiler or link-edit parameters of a source file are different from the default parameters.

Example:

# build configuration
tasks: 
  - language: Cobol
    # file patterns of sources files to build with this language task
    sources: **/cobol/*.cbl

    variables:
      # default link parms
      - name: linkParms
        value:  MAP,RENT,COMPAT(PM5)

# application configuration
application:
  name: SAMPLE-APP
  
  # only individual task variables can be overridden
  tasks:
    # language task overrides are declared using the 'task:' keyword
    - task: Cobol
      # override the source file patterns for the Cobol language task
      sources: 
        - **/COBOL/*.cob
        - **/COBOL/BATCH/*.cobbat

      variables:
        # override these source files' link parms using file associated variable
        - name: linkParms
          value:  DYNAM,MAP,RENT,COMPAT(PM5)
          forFiles:
            - **/SAM1.cob
            - **/SAM2.cob

    # pre-defined task variable default values can be overridden
    - task: Start
      
      variables:
        # Change build log output location
        - name: logOutput 
          value: ${WORKSPACE}/output

How to define the application configuration

You can provide the application configuration in three ways:

  • Provide a dbb-app.yaml.
  • Use the CLI --config option
  • Use the build configuration include: application statement.

NOTE: The zBuilder requires an application configuration to be provided by default. If no application configuration can be located when the build process begins, then an error will occur. You can turn off the application configuration requirement by declaring a global variable in the build configuration:

variables:
  # turn off application configuration requirement
  - name: requireApplicationConfiguration
    value: false

The dbb-app.yaml file

The most common way to define application configuration is by providing a dbb-app.yaml file in the application root folder by using the format shown above.

Use the CLI --config option

In addition to the dbb-app.yaml file, you can also pass in an application configuration file by using a zBuilder command line option. Note that any name can be used for a passed-in application configuration file.

dbb build full --config /u/build/myOverrides.yaml

When the build process starts, the myOverrides.yaml file will be merged with the existing dbb-app.yaml file. If the myOverrides.yaml file contains a task variable that exists in the dbb-app.yaml file, then the myOverrides.yaml variable will overwrite the existing variable. See Command line options and arguments for more information on passing in an application configuration file.

Use the build configuration include: application statement

You might require that all build configurations including application configuration remain under the control to the build engineering team. With zBuilder this is done as an include statement in the build configuration file:

dbb-build.yaml]

include:
  # include the language task configuration
  - file: Languages.yaml

  # include application configurations
  - application: SampleApplication
    file: applications/SampleApplication.yaml
  - application: SampleApplication2
    file: applications/SampleApplication2.yaml

The application: property value must match the name of the application directory that was cloned onto z/OS Unix. The value of the file: property can be an absolute path or relative to the $DBB_BUILD. In the example above the application configuration files are located in $DBB_HOME/applications.

When the build process starts, zBuilder will first look to see if a include: application: statement exists for the application being built. If one exists, then it will ignore the other application configuration files if present.

Providing an application configuration file for each source file

The dbb-app.yaml file can define variable overrides for all source files in a single application configuration file by using file associated variables.

application:
  name: SAMPLE-APP
  tasks:
    - Cobol
      variables:
        - name: compiler
          value: IGY.V4R2M0.SIGYCOMP
          forFiles:
            - **/epsnbrvl.cbl
            - **/epsmpmt.cbl
            - **/epsmlist.cbl

        - name: compileParm
          value: LIB,RENT
          forFiles:
            - **/epsnbrvl.cbl
            - **/epsmpmt.cbl

However, you can also structure the application configuration so that each source file has a dedicated configuration YAML file. This can make updating source file configuration easier. This is done by using the include: statement in the dbb-app.yaml file.

Define a common location to store source file configuration files like config.

application:
  name: SAMPLE-APP
  include:
    # use a wild card to import all configuration files in the config folder
    - file: config/*.yaml

    # The rest of the `dbb-app.yaml` can be empty

The following code shows the epscmort.yaml, which overrides the variables of the epscmort.cbl source file only.

[overrides/epscmort.yaml]
application:

  # use the top-level forFiles property that will be applied to all variables declared in this file.
  forFiles: ‘**/epscmort.cbl’

  tasks:
    - Cobol
      variables:
        - name: compiler
          value: IGY.V4R2M0.SIGYCOMP
        - name: compileParm
          value: ‘LIB,RENT’

Additional topics

For more information about application configuration see: