Variables

Variables can be defined in the build and application configuration files for the following purposes:

  • Control the behavior of build and task execution.
  • Store values for reuse in multiple build lifecycle and task configurations.
  • Set up default task variables to be overridden by application configuration files.

Variable scope

A variables: section can be defined in multiple locations of the build configuration:

  • The main variables section of the build configuration. These variables become globally available and can be used in all lifecycles and tasks during the build process.
  • A lifecycle variables section. These variables are available only to the lifecycle and its declared tasks.
  • A basic task or language task configuration. These variables are available only to the basic or language task that defined it.

In the following example, the region variable is declared at the top level of the build configuration, the organization variable is defined at the lifecycle level and the department variable is defined in a task.

# global variables available to all build lifecycles and tasks
variables:
  - name: region
    value: ASIA

lifecycles:
  - lifecycle: full
      # variables for all tasks in full lifecycle
      variables:
        - name: organization
          value: FINANCE

      tasks:
        - Start
        - task: FullAnalysis
          # variables available only to FullAnalysis task
          variables:
            - name: department 
              value: 67r
        - Languages
        - Finish

Variable values

Variable values can have the following Java types:

  • String - Simple text values that can be used in most zBuilder YAML properties
  • Boolean - true or false flags that can be used in zBuilder condition: properties.
  • Number - Numeric values that can be used in less than or greater than condition: properties.
  • List - Used to provide an ordered list of values.
  • Object - Used to provide a set of Name / Value Pairs.

Examples of supported variable values:

variables:
 - name: stringVariable
   value: This is a string # quotation characters are optional for strings
 - name: numberVariable
   value: 10
 - name: booleanVariable
   value: true
 - name: forcedStringVariable
   value: "true" # use quotations for force a number or boolean to be a string value
 - name: listVariable
   value:
     - apple
     - orange
     - peach
 - name: mapVariable
   value:
     - name: George Washington
     - occupation: US President
     - location: Mount Vernon, Virginia

Variable references

zBuilder YAML configuration properties as well as variable values can reference other variables. These references are replaced at execution time with the value of the variable that is being referenced. Variable values can reference variables within their scope or a higher scope.

The following types of references are possible:

  • In a reference replacement, the value contains a variable reference and nothing else. In this case the reference value maintains its value type when it is replaced.
  • In a reference insertion, the value contains both constant segments and variable references. In this case both the constant segments and the inserted values are converted to a String type and the resulting value is a String. Arrays can also be inserted. The array value is converted into a String value with each element concatenated with a comma delimiter. An alternate delimiter can be declared in the variable. Objects as variable references are not supported.
variables:
  # numVar is an Integer value
  - name: numberVar
    value: 10

  # reference replacement. Count value type is an Integer
  - name: count
    value: ${numberVar}

  # reference insertion. Message value type is a String
  - name: message
    value: Number of files processed is ${count}

Variable types

The zBuilder supports several different variable types to provide a more dynamic configuration model.

Basic variables

This is the common name value pair format.
Example: 

variables:
  - name: numberVar
    value: 10

File associated variables

These variables are used to define variables whose values apply to specific source files only. They should be referenced only in configuration sections where a list of source files is being processed like language task steps.

NOTE If a file associated variable is referenced in a configuration section where source files are not being processed, then the variable is treated as a basic variable.

Uses the forFiles: list of UNIX glob patterns to identify which source files should use this value.

[dbb-app.yaml]
application:
tasks:
  - task: Cobol
    variables: 
      # these files require an older compiler
      - name: compilerDS
        value: IGY.V4R2M0.SIGYCOMP
        forFiles: 
          - "**/cobol/epsnbrvl.cbl"
          - "**/cobol/epsmlist.cbl"

File associated variables are usually defined in an application configuration file as they are usually application file specific overrides to default variables. Because of this, a good practice is to provide a basic variable in the Language Task to act as a default value in cases where the file being processed does not match the for file patterns.

[Cobol.yaml]
tasks:
  - task: Cobol

    variables: 
      # default cobol compiler library
      - name: compilerDS
        value: IGY.V6R1M0.SIGYCOMP

. . .

steps:
  # COBOL compile step          
  - step: compile
    type: mvs
    pgm: IGYCRCTL
    dds:
      # add the compiler library to the TASKLIB DD
      - { name: "TASKLIB", dsn: "${compilerDS}", options: "shr" }

In the example above files MortgageApplication/cobol/epsnbrvl.cbl and MortgageApplication/cobol/epsmlist.cbl will be compiled with Cobol v4.2.0 and all other COBOL programs will be compiled with Cobol v6.1.0.

Conditional variables

A conditional variable is a variable whose value is determined when it is accessed based on one or more conditional expressions that evaluate to true. Two types of conditional variables are available: select and append.

Conditional select variables

A select conditional variable returns the value of the first condition that evaluates to true. The select variable extends the basic variable by adding a select: property. The main value: property (if provided) becomes the default value of the select variable if all the conditions evaluate to false. The main value element is optional in a select variable. Select conditional values can be of any supported type and can even have different value types for different conditions.

Example:

variables:
  # use the select conditional variable to determine deploy type
  - name: deployType
    value: LOAD  # default value if no condition is true
    select:
      - condition: ${IS_CICS}
        value: CICSLOAD
      - condition: ${IS_DLI}
        value: IMSLOAD
      - condition:${is_IMS}
        value: IMSLOAD

Conditional append variables

An append conditional variable returns an appended string that contains all the conditional values that evaluated to true. The append variable extends the basic variable by adding an append: property. The main value: property (if provided) becomes the initial start value of the returned string value. The main value element is optional in an append variable.

An append conditional variable always returns a string value. The initial value and all the appended values are converted to a string type. Arrays can also be appended to the value. The array value is converted into a string value with each element concatenated together with a comma delimiter. An alternate delimiter can be declared in the variable. Objects as variable references are not supported.

Example:

  # append conditional variable 
  - name: compileParms
    value: LIB  # initial value
    append:
      - condition: ${IS_CICS}
        value: CICS
      - condition: ${IS_SQL}
        value: SQL 
      - condition: ${DEBUG}
        value: TEST

Additional topics

For more information about variables see: