Building the MortgageApplication sample

In this tutorial, you set up the Mortgage Application sample as a Git repository and build the entire application by executing the zBuilder full lifecycle.

Prerequisites

Estimated time

This tutorial takes about 15 minutes to complete.

Steps

1. Extract the MortgageApplication sample

Copy the sample out of the DBB installation directory. Place it in a suitable location in the user's directory.

$ mkdir /u/dbbusr/workspace
$ cp -r $DBB_HOME/samples/MortgageApplication /u/dbbusr/workspace/MortgageApplication

The MortgageApplication sample consists of 6 COBOL programs, 2 BMS maps, 1 link card, and 6 total copybook dependencies.

Directory listing 
MortgageApplication
├── dbb-app.yaml      # zBuilder Application Configuration
├── zapp.yaml         # IDE DBB User Build Configuration
├── bms               # BMS Source 
│   ├── epsmlis.bms
│   └── epsmort.bms
├── cobol             # COBOL Source
│   ├── epscmort.cbl
│   ├── epscsmrd.cbl
│   ├── epscsmrt.cbl
│   ├── epsmlist.cbl
│   ├── epsmpmt.cbl
│   └── epsnbrvl.cbl
├── copybook          # Copybook Source
│   ├── epsmortf.cpy
│   ├── epsmtcom.cpy
│   ├── epsmtinp.cpy
│   ├── epsmtout.cpy
│   ├── epsnbrpm.cpy
│   └── epspdata.cpy
├── link              # Link Card Source
│   └── epsmlist.lnk
├── .gitattributes    # Maps file patterns to a z/OS Unix encoding
└── .gitignore        # Ignores files from being tracked by git

2. Set up the directory as a Git repository

Move to the directory and initialize as a new Git repository.

$ cd /u/dbbusr/workspace/MortgageApplication
$ git init
Initialized empty Git repository in /u/dbbusr/workspace/MortgageApplication/.git/

Add all files in the directory to the staging area and commit the result.

$ git add .
$ git commit -m "initial commit"

3. Define application-specific behavior in dbb-app.yaml

The dbb-app.yaml configuration file contains application-specific variable definitions and overrides. Unlike other zBuilder configuration files, dbb-app.yaml is located within the application directory. Overriding variables at this level enables zBuilder lifecycles, tasks, and steps to behave differently for every application.

The file included in the sample has already been configured for building Mortgage Application. For more information on each variable override for this sample, expand below:

Detailed walk-through

This section covers relevant definitions in the preconfigured dbb-app.yaml to understand how the file establishes custom build behavior for Mortgage Application.

Open the sample dbb-app.yaml zBuilder configuration file:

MortgageApplication/dbb-app.yaml 
version: 1.0.0
application:
  name: MortgageApplication
  tasks:
    - task: ImpactAnalysis 
      [...]
    # Variable overrides for the Cobol language task
    - task: Cobol
      variables:  
        # Need to build sub-module epsnbrvl.cbl first during cobol builds
        - name: fileBuildRank
          value: 1
          forFiles: "**/cobol/epsnbrvl.cbl"

        # Skip creating a load module for these programs as they will be 
        # statically linked to other programs
        - name: doLinkEdit
          value: false
          forFiles: 
            - "**/cobol/epsnbrvl.cbl"
            - "**/cobol/epsmlist.cbl"   

    # Variable overrides for the LinkEdit language task
    - task: LinkEdit
      variables: 
        # Set flag for link cards with CICS load modules
        - name: hasCICSModules
          value: true
          forFiles:
            - "**/link/epsmlist.lnk"

Notice variable definitions for the Cobol language task and the LinkEdit language task. Ignore the variable overrides for the other tasks which are not relevant to this tutorial.

Note: Each variable includes a forFiles definition so that the value only applies to certain source files. For more information, see File Associated Variables.

Cobol Language Task

You can modify build order priority to control the order in which files are processed within a language task. For MortgageApplication, the epsnbrvl.cbl source file represents a COBOL submodule statically called by other programs in the application. To ensure that this submodule builds before other programs, override the fileBuildRank built-in variable:

- name: fileBuildRank
  value: 1
  forFiles: "**/cobol/epsnbrvl.cbl"

Setting the variable to integer value 1 ranks epsnbrvl.cbl above the other COBOL programs so that the language task processes this program first.


In addition, you can skip conditional Language task steps for certain source files where the step does not need to be executed. For example, the link-edit step can be skipped for programs that do not need a load module generated because they will be statically linked to other programs.

Excerpt from Cobol.yaml: 
# Extracted from Cobol.yaml
tasks:
  # Cobol Language task
  - language: Cobol
    variables:
      - name: doLinkEdit # Perform link edit step by default
        value: true
    [...]
    
    steps:
    - step: linkEdit
      type: mvs
      pgm: IEWBLINK
      parm: ${linkEditParms}
      condition: ${doLinkEdit}
      [...]

Notice that doLinkEdit variable is defined as true and the linkEdit step uses it as the conditional.

For Mortgage Application, epsnbrvl.cbl and epsmlist.cbl are statically linked to other programs. Based on the step definition above, you can skip the link-edit step when you build these specific programs:

- name: doLinkEdit
  value: false
  forFiles: 
    - "**/cobol/epsnbrvl.cbl"
    - "**/cobol/epsmlist.cbl"

This definition overrides the doLinkEdit value of true (as defined in Cobol.yaml) for epsnbrvl.cbl and epsmlist.cbl so that the conditional linkEdit step will not execute.

LinkEdit Language task

In the same way doLinkEdit can be overriden to skip language task steps for certain files, you can also override variables used as conditions in DD statements to create custom behavior for certain files.

Excerpt from LinkEdit.yaml: 
# Extracted from LinkEdit.yaml
tasks:
  # LinkEdit Language task builds link cards
  - language: LinkEdit
    variables:
    - name: hasCICSModules
      value: false
    [...]
    
    steps:
    - step: linkEdit
      type: mvs
      pgm: IEWBLINK
      parm: ${linkEditParms}
      maxRC: 0
      dds:
        [...]
        - { name: "SYSLIB", dsn: "${HLQ}.OBJ", options: "shr" }
        - {                 dsn: "${SCEELKED}", options: "shr" }
        - {                 dsn: "${SDFHLOAD}", condition: "${hasCICSModules}", options: "shr" }
        - {                 dsn: "${SDSNLOAD}", condition: "${hasCICSModules}", options: "shr" }

As displayed, the hasCICSModules variable is set to false in LinkEdit.yaml. Therefore the last two conditional SYSLIB DD statement concantenations -- adding the SDFHLOAD and SDSNLOAD libraries to the SYSLIB -- will not be allocated in the generated DD statement by default.


Notice that the epsmlist.lnk link card includes the EPSMPMT and EPSMLIST object decks, producing the EPSMLIST load module:

MortgageApplication/link/epsmlist.lnk 
 INCLUDE  SYSLMOD(EPSMPMT)
 INCLUDE SYSLIB(EPSMLIST)
 NAME EPSMLIST(R)

The epsmlist.cbl source code, which produces the EPSMLIST object deck, contains EXEC CICS statements.

To add the SYSLIB conctenations that are needed to link objects that contain CICS modules, set the hasCICSModules configuration variable to true for this link card:

- name: hasCICSModules
  value: true
  forFiles:
    - "**/link/epsmlist.lnk"

This concludes the walk-through of configuration relevant to this tutorial. It does not cover overriding the impactQueryPatterns ImpactAnalysis built-in configuration variable, which is covered in the Incremental building with the Mortgage Application tutorial.



4. Explore the dbb build command.

For options and format, see DBB zBuilder Command line options and arguments.

5. Build the application

DBB build commands should be executed from the application directory. If not already, move to the MortgageApplication directory:

$ cd /u/dbbusr/workspace/MortgageApplication

Execute the full lifecycle to build all source within the application:

$ dbb build full --hlq DBBUSR.MORTAPP

BUILD

Lifecycle: full
Task: Start
> Build start at 20240925.101100.011
> Started by 'DBBUSR' on 'SYS1234'
Task: ScannerInit
Task: MetadataInit
Task: FullAnalysis
Stage: Languages
Language: BMS
> Building 'MortgageApplication/bms/epsmlis.bms'
> Building 'MortgageApplication/bms/epsmort.bms'
Language: Cobol
> Building 'MortgageApplication/cobol/epsnbrvl.cbl'
> Building 'MortgageApplication/cobol/epscmort.cbl'
> Building 'MortgageApplication/cobol/epscsmrd.cbl'
> Building 'MortgageApplication/cobol/epscsmrt.cbl'
> Building 'MortgageApplication/cobol/epsmlist.cbl'
> Building 'MortgageApplication/cobol/epsmpmt.cbl'
Language: LinkEdit
> Building 'MortgageApplication/link/epsmlist.lnk'
Task: Finish
> Build ended at 20240925.101107.011
> Duration of build : 00 min, 06 sec
> Total files processed : 9
> Build Status : CLEAN

The build processes 9 total files and exits with CLEAN status.

Summary

In this tutorial, you created a Git repository to track changes in the DBB sample Mortgage Application. You learned how to create application-specific build behavior by using dbb-app.yaml. Finally, you built the application by executing the full lifecycle. You should have all the basic building blocks to start building your own z/OS applications with zBuilder.

Logs

When the build finishes with a clean status, open the logs directory that the build created in your MortgageApplication directory. If you are using a z/OS UNIX editor, you might refresh to be able to see the new directory. The content of this output directory is standard: buildList.txt, BuildReport.html, BuildReport.json, and one log file for each program that was built.

Artifacts

The full lifecycle executes the MetadataInit task, which initializes the MetadataStore to maintain source, dependency, and build metadata. The DBB CLI interface is used to display and export this metadata.

Using the DBB CLI

After starting a DBB CLI session, you can see the latest build result in the listing of the MortgageApplication-main build group:

$ dbb list results MortgageApplication-main
IBM Dependency Based Build 3.0.0

BUILD RESULTS
group: MortgageApplication-main

label                                state           status
---------------------------          -------------   ---------
build-20240925.101100.011            2 'COMPLETE'    0 'CLEAN'

Use the following commands to inspect metadata artifacts created during the build:

$ dbb view result MortgageApplication-main <build label>
$ dbb view collection MortgageApplication-main sources
$ dbb view collection MortgageApplication-main outputs
$ dbb view file MortgageApplication-main sources MortgageApplication/cobol/epscmort.cbl

Next steps