DBB/zAppBuildについてのメモ - (2)zAppBuildプロパティー・ファイル

# はじめに
ここではzAppBuildが提供するプロパティー・ファイルについて見ていきます。
zAppBuildを使用してz/OSアプリケーションをビルドする場合、プロパティー・ファイルをカスタマイズすることでビルド環境やアプリケーションに依存する情報を設定し、ビルドの挙動を制御することになります。

※当記事はzAppBuild V3.1.0をベースにしています。

## 関連記事

[DBB/zAppBuildについてのメモ - (1)概要](https://qiita.com/tomotagwork/items/d3b08b10137a0d87416d)
[DBB/zAppBuildについてのメモ - (2)zAppBuildプロパティー・ファイル](https://qiita.com/tomotagwork/items/e6988a708a57d7296350)
[DBB/zAppBuildについてのメモ - (3)zAppBuildビルド・スクリプト](https://qiita.com/tomotagwork/items/f4df3965f62236689584)
[DBB/zAppBuildについてのメモ - (4)Metadata Store構成](https://qiita.com/tomotagwork/items/126907b52c3c8a5ec88d)

# zAppBuild全体像

zAppBuildが提供するファイル群のおさらいです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/57c42df5-ba58-05ea-3263-64c24783d434.png)
ここでは上の赤字部分に着目してみます。

# プロパティー・ファイルのカスタマイズ

## build-conf

build-conf関連のプロパティーでは、使用するz/OS環境に依存する情報を設定していきます。ビルド環境のUSS上にクローンしたzAppBuildの`dbb-zappbuild/build-conf/`以下にあるプロパティー・ファイルをカスタマイズしていきます。
これはビルド環境ごとに実施するものとなります。

参考: [build-conf](https://github.com/IBM/dbb-zappbuild/tree/main/build-conf)

ここではサンプルで提供されているプロパティー・ファイルをいくつかピックアップして見ていきます。

ビルド環境応じて関連するプロパティーをカスタマイズしていくことになりますが、まず必須なのがbuild.properties、datasets.properties、辺りです。
また、ここではCOBOLバッチのビルドを想定し、Cobol.propertiesをカスタマイズしていきます(他の言語やミドルウェアを使用する場合はそれに応じて追加でプロパティーを設定していくことになります)。

※各プロパティー・ファイルのパラメーターは上のGitHubのREADMEをご参照ください。


### build.properties

参考: [build.properties](https://github.com/IBM/dbb-zappbuild/blob/3.1.0/build-conf/build.properties)

ここではビルドに関する全般的な設定を行います。いくつか主要なプロパティーについて補足します。

#### buildPropFiles

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/build-conf/build.properties#LL4C1-L6C

build.properties以外に読み込むべきプロパティー・ファイルを指定します。

#### requireDBBToolkitVersion

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/build-conf/build.properties#LL46C1-L48C1

想定するDBBの最低バージョンが指定されています。これは使用するzAppBuildのバージョンによって決まっています(使用するzAppBuildの前提条件)。

#### Meadata Store関連

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/build-conf/build.properties#LL135C1-L149C33

DBBの依存関係関連のメタデータを保存するデータストアとして何を使用するかを指定します。デフォルトはfile(USS上のファイル)となっており、ロケーションは未指定なのでデフォルトだと$USER(ユーザーのホームディレクトリ)となります。
デフォルト設定の場合、例えばJENKIN1というユーザーを使用する場合、/u/JENKIN1がホームディレクトリだったとすると、/u/JENKIN1/.dbb/以下にメタデータが管理されます。

※Db2をMetadata Storeとして使用する場合はこの辺りのプロパティーを変更する必要があります。

### datasets.properties

参考: [datasets.properties](https://github.com/IBM/dbb-zappbuild/blob/3.1.0/build-conf/datasets.properties)

ここでは使用するz/OS環境の各種ライブラリのHLQを指定していきます。HLQは環境によって異なるのでここの設定は必須となります(アプリケーションで使用しないミドルウエアのライブラリなどは指定不要)。

<details><summary><font color="blue">datasets.properties設定例</font></summary><div>

例えば、Wazi as a ServiceのStock Image(ibm-zos-2-4-s390x-dev-test-wazi-7)を使用する場合の設定例はこんな感じになります。

```properties:datasets.properties
# Dataset references
# Build properties for Partition Data Sets (PDS) used by zAppBuild build scripts.
# Please provide a fully qualified DSN for each build property below.
# Ex:
# MACLIB=SYS1.MACLIB

# z/OS macro library. Example: SYS1.MACLIB
MACLIB=SYS1.MACLIB

# Assembler macro library. Example: CEE.SCEEMAC
SCEEMAC=CEE.SCEEMAC

# LE (Language Environment) load library. Example: CEE.SCEELKED
SCEELKED=CEE.SCEELKED

# High Level Assembler (HLASM) load library. Example: ASM.SASMMOD1
SASMMOD1=ASM.SASMMOD1

# Cobol Compiler Data Sets. Example: COBOL.V4R1M0.SIGYCOMP
SIGYCOMP_V4=
SIGYCOMP_V6=IGY.V6R4M0.SIGYCOMP

# PL/I Compiler Data Sets.  Example: PLI.V5R2M0.SIBMZCMP
IBMZPLI_V52=PLI.V6R1M0.SIBMZCMP
IBMZPLI_V51=

# CICS Macro Library. Example: CICSTS.V3R2M0.CICS.SDFHMAC
SDFHMAC=CICSTS.V6R1M0.CICS.SDFHMAC

# CICS Load Library. Example: CICSTS.V3R2M0.CICS.SDFHLOAD
SDFHLOAD=CICSTS.V6R1M0.CICS.SDFHLOAD

# CICS COBOL Library. Example: CICSTS.V3R2M0.CICS.SDFHCOB
SDFHCOB=CICSTS.V6R1M0.CICS.SDFHCOB

# CICS PLI Library. Example: CICSTS.V3R2M0.CICS.SDFHPL1
SDFHPL1=CICSTS.V6R1M0.CICS.SDFHPL1

# MQ COBOL Library. Example: CSQ.V9R1M0.SCSQCOBC
SCSQCOBC=MQCD.V9R3M0.SCSQCOBC

# MQ PLI Library. Example: CSQ.V9R1M0.SCSQPLIC
SCSQPLIC=MQCD.V9R3M0.SCSQPLIC

# MQ Assembler Library. Example: CSQ.V9R1M0.SCSQMACS
SCSQMACS=MQCD.V9R3M0.SCSQMACS

# MQ Load Library. Example: CSQ.V9R1M0.SCSQLOAD
SCSQLOAD=MQCD.V9R3M0.SCSQLOAD

# DB2 Load Library. Example: DB2.V9R1M0.SDSNLOAD
SDSNLOAD=DB2.V13R1M0.SDSNLOAD

# IMS Macro Library. Example: DFS.V11R1M0.SDFSMAC
SDFSMAC=IMS.V15R1M0.SDFSMAC

# IMS RESLIB. Example: DFS.V11R1M0.SDFSRESL
SDFSRESL=IMS.V15R1M0.SDFSRESL

# User generated library for DB/DC and DC installations. Example: DFS.V11R1M0.REFERAL
REFERAL=IMS15.REFERAL

# IBM Debug Library containing Exits
SEQAMOD=EQAW.SEQAMOD

# Optional IDz Load Library. Example: FEL.V14R0M0.SFELLOAD
SFELLOAD=FEL.SFELLOAD

# Optional IDZ zUnit / WAZI VTP library containing necessary copybooks. Example : FEL.V14R2.SBZUSAMP
SBZUSAMP=BZU.SBZUSAMP

# REXX Compiler Data Sets. Example: REXX.V1R4.SFANLMD
SFANLMD=REXX.V1R4M0.SFANLMD
```

</div></details>

### Cobol.properties

参考: [Cobol.properties](https://github.com/IBM/dbb-zappbuild/blob/3.1.0/build-conf/Cobol.properties)

ここではCOBOLのビルド環境に関する設定を行います。いくつか主要なプロパティーについて補足します。

#### cobol_requiredBuildProperties

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/build-conf/Cobol.properties#LL4C1-L8C24

COBOLのビルドに必要なプロパティーのリストを指定します。ビルド・スクリプト中ではここで指定したプロパティーが指定されているかどうかのチェックが行われます。

#### コンパイラー/リンカー

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/build-conf/Cobol.properties#LL10C1-L16C26

コンパイラー用、リンカー用それぞれのプログラムを指定します。

#### PDSデータセット関連

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/build-conf/Cobol.properties#LL18C1-L36C1

これらのプロパティーでは、ビルド時に使用されるPDSデータセットを指定しています。例えばCOBOLのソースは`${hlq}.COBOL`、COPYBOOKは`${hlq}.COPY`、生成されるロードモジュールは`${hlq}.LOAD`という具合です。`${hlq}`はビルド実行に動的に設定される変数です。

#### PDSデータセット作成時オプション

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/build-conf/Cobol.properties#LL38C1-L59C2

上で設定したビルド時に使用されるPDSデータセットは、存在しなければ動的に作成されます。これらのプロパティーでは、必要なPDSデータセットと動的に作成する際に使用されるオプションを指定します。
ここではVOLUME名などの指定がされていないので、基本的にはSMS管理のデータセットから動的にVOLUMEが判断されて使用される想定になっています。例えば、非SMS管理で動的にVOLUME名を指定したいのであれば、オプション設定を以下のように変更することになります。
`cobol_srcOptions=cyl space(1,1) lrecl(80) dsorg(PO) recfm(F,B) dsntype(library) vol(TEMP01)`

## application-conf

application-conf以下に管理されるプロパティー・ファイルでは、ビルドしたいアプリケーションに関連する設定を行います。アプリケーションに依存するものなので、基本的にはソース類と一緒にGitで管理されることになります。

[MortgageApplication](https://github.com/IBM/dbb-zappbuild/tree/3.1.0/samples/MortgageApplication)というサンプルのアプリケーションが提供されており、このアプリケーションをzAppBuildでビルドするための[application-conf](https://github.com/IBM/dbb-zappbuild/tree/3.1.0/samples/MortgageApplication/application-conf)も合わせて提供されているので、これをベースにapplication-confのプロパティーを見ていきます。

まず、application.properties、file.properties辺りは必須です。また、ここではCOBOLバッチのビルドを想定し、Cobol.propertiesをカスタマイズしていきます(他の言語やミドルウェアを使用する場合はそれに応じて追加でプロパティーを設定していくことになります)。

プロパティーはいくつかの箇所で指定が可能なもあります。プロパティー指定方法や優先順の詳細については以下のドキュメントもご参照ください。
参考: [File Property Management](https://github.com/IBM/dbb-zappbuild/blob/main/docs/FilePropertyManagement.md)

### application.properties

参考: [MortgageApplication/application-conf/application.properties](https://github.com/IBM/dbb-zappbuild/blob/3.1.0/samples/MortgageApplication/application-conf/application.properties)

ここではアプリケーション全般に関連する設定を行います。アプリケーションに関する特性を設定するものですので、アプリケーションごとにカスタマイズします。
基本激にはアプリケーションは基本的にはGitで管理される想定なので、Gitリポジトリ内でアプリケーションと一緒に管理されることになります。
いくつか主要なプロパティーについて補足します。

#### applicationPropFiles

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/application.properties#LL4C1-L6C9

application.properties以外に読み込むべきプロパティー・ファイルを指定します。

#### applicationSrcDirs

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/application.properties#LL9C1-L12C13

アプリケーション・ソースが含まれるトップのディレクトリ名を指定します。通常はGitでリポジトリーをCloneするとリポジトリ名と同じディレクトリが作成されるので、リポジトリ名と同じ名前を指定することになります。${application}はビルド時に動的に設定される変数です。

#### buildOrder

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/application.properties#LL15C1-L16C2

ビルドする順番を指定します。この例では、BMS、COBOL、LinkEditの順番に実行されることになります。

#### excludeFileList

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/application.properties#LL31C1-L31C16

fullbuildをする際にビルド対象から除外するファイルを指定します。

### file.properties

参考: [MortgageApplication/application-conf/file.properties](https://github.com/IBM/dbb-zappbuild/blob/3.1.0/samples/MortgageApplication/application-conf/file.properties)

ここではソース・ファイルに関連する設定を行います。いくつか主要なプロパティーについて補足します。

#### dbb.scriptMapping

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/file.properties#LL4C1-L9C6

ビルドに使用する言語別スクリプトと、ソースのマッピングを行います。
例えば上の例では、任意の場所にある`.cbl`という拡張子のついたファイルはCOBOLのソースとして判断し、Cobol.groovyというビルドスクリプトでビルドする、というマッピングが行われます。

参考: [DBB APIs - Build properties](https://www.ibm.com/docs/en/dbb/2.0.0?topic=apis-build-properties)

#### cobol_fileBuildRank

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/file.properties#LL12C1-L13C2

COBOLプログラムの中での優先順位付けを行います。(コンパイル/リンクの順序性がある場合の制御)
ランク(数値)が少ないものが優先度が高くなります。ランク付けされていないものは優先度が最下位となります。

#### cobol_linkEdit

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/file.properties#LL16C1-L17C2

ロード・モジュール作成しないようにする(LinkEditをスキップする)ソースを指定します(他のプログラムからスタティックにリンクされる場合など)。
上の例では`epsnbrvl.cbl`および`epsmlist.cbl`は他のプログラムからStatic Linkされる想定なのでLinkEditはスキップするよう設定しています。

#### isCICS

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/file.properties#LL20C1-L22C84

CICSプログラムとしてビルドすべきプログラムを指定します。
(zAppBuildのスクリプトではCICS個別のトランスレーターを使用するのではなく、言語環境提供の統合トランスレーターを使用する仕組みとなっている)

#### loadFileLevelProperties

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/file.properties#LL24C1-L32C3

共通のプロパティー・ファイルで全てのソースのビルド特性を制御するのは難しい場合があります。例外的なビルド特性を持つソースについては、そのソースごとに個別のプロパティーを設定する方が分かりやすい場合があります。そのような場合はこのプロパティーでソースごと(ファイルごと)のプロパティー・ファイルを用意し、それを使用することができます。
上の例では、`epsmlist.cbl`については個別のプロパティー・ファイルを使用することを宣言しています。実際のプロパティー・ファイルは「[epsmlist.cbl.properties](https://github.com/IBM/dbb-zappbuild/blob/3.1.0/samples/MortgageApplication/properties/epsmlist.cbl.properties)」が使用されることになります(パスやファイル名は、application.propertiesのpropertyFilePath、propertyFileExtensionで制御される)。

#### loadLanguageConfigurationProperties 

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/file.properties#LL35C1-L43C90

特定のグループ単位でプロパティーを制御したい場合もあります。上の例だと、`epsnbrvl.cbl`、`epsmpmt.cbl`を個別のプロパティーを設定する対象のソースとして指定しています。具体的なプロパティーとのマッピングは、[languageConfigurationMapping.properties](https://github.com/IBM/dbb-zappbuild/blob/3.1.0/samples/MortgageApplication/application-conf/languageConfigurationMapping.properties)で指定します。

### Cobol.properties
参考: [MortgageApplication/application-conf/Cobol.properties](https://github.com/IBM/dbb-zappbuild/blob/main/samples/MortgageApplication/application-conf/Cobol.properties)

ここではCOBOLのソースに関連する設定を行います。いくつか主要なプロパティーについて補足します。

#### cobol_compilerVersion

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/Cobol.properties#LL14C1-L16C3

COBOL Compilerのバージョンを指定します。

#### コンパイル/リンク関連オプション

https://github.com/IBM/dbb-zappbuild/blob/5a649f0a591625be0bfe39dd880ef1d43ba8272f/samples/MortgageApplication/application-conf/Cobol.properties#LL30C1-L45C10

Compilerオプション、LinkEditのオプション等を指定します。