Merge pull request #392 from IBM/develop

Release zAppBuild 3.4.0

Author: dennis-behm

.gitattributes

@@ -17,3 +17,4 @@
 *.jcl zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
 *.mac zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
 *.json zos-working-tree-encoding=utf-8 git-encoding=utf-8
+*.yaml zos-working-tree-encoding=utf-8 git-encoding=utf-8

README.md

@@ -13,7 +13,7 @@ zAppBuild is a generic build solution for building z/OS applications using Apach
 For instructions on how to contribute enhancements and bug fixes to zAppBuild, please read the [Contributions Guidelines](CONTRIBUTIONS.md).
 
 ## How zAppBuild works
-The zAppBuild repository is intended to be cloned to a single location on Unix Systems Services (USS) and used to build all of your z/OS applications. This is done by simply copying the supplied `application-conf` folder (located in the [samples folder](samples)) to the application source repository you want to build and then verify/update the contained default configuration property values to ensure they meet the build requirements of your application. See the included [MortgageApplication](samples/MortgageApplication) sample for an example of an application that has been modified to be built by zAppBuild.  
+The zAppBuild repository is intended to be cloned to a single location on Unix Systems Services (USS) and used to build all of your z/OS applications. Global configuration properties are configured in the properties files in the [build-conf](build-conf/) directory. Specifying application-level properties is done by simply copying the supplied `application-conf` folder (located in the [samples folder](samples)) to the application source repository you want to build and then verify/update the contained default configuration property values to ensure they meet the build requirements of your application. See the included [MortgageApplication](samples/MortgageApplication) sample for an example of an application that has been modified to be built by zAppBuild.  
 
 **IMPORTANT** : The [datasets.properties](build-conf/datasets.properties) must be configured for your build machine before executing a build!  See [build-conf/README.md](build-conf/README.md) for more information.
 
@@ -28,6 +28,7 @@ The zAppBuild sample provides the following *language* build scripts by default:
 * PSBgen.groovy
 * MFS.groovy
 * ZunitConfig.groovy
+* CRB.groovy
 * Transfer.groovy (for transport non-buildable files like JCL or PROC into build libraries and register them as build output)
 
 All language scripts both compile and optionally link-edit programs. The language build scripts are intended to be useful out of the box but depending on the complexity of your applications' build requirements, may require modifications to meet your development team's needs.  By following the examples used in the existing language build scripts of keeping all application specific references out of the build scripts and instead using configuration properties with strong default values, the zAppBuild sample can continue to be a generic build solution for all of your specific applications.
@@ -67,5 +68,5 @@ languages | This folder contains the language specific build scripts that are as
 samples/application-conf | The `application-conf` folder contains application specific configuration properties used by build.groovy and language build scripts.  It is intended to be copied as a high level folder to the application repository and configured to meet the build requirments of the application. Ex. `myAppRepository/application-conf` | [samples/application-conf/README.md](samples/application-conf/README.md)
 samples/MortgageApplication | This is an updated version of the original [MortgageApplication](https://github.com/IBM/dbb/tree/master/Build/MortgageApplication) sample designed to be built by zAppBuild. | [samples/MortgageApplication/README.md](samples/MortgageApplication/README.md)
 utilities | This folder contains utility scripts which provide common utility functions used by the various zAppBuild build scripts. | [utilities/README.md](utilities/README.md)
-build.groovy | This is the main build script that is called to start the build process. | [BUILD.md](BUILD.md)
+build.groovy | This is the main build script that is called to start the build process. | [docs/BUILD.md](docs/BUILD.md)
 test | This folder contains testing framework for ZAppBuild which includes test scripts and related test content.| [test/README.md](/test/README.md)

build-conf/CRB.properties

@@ -0,0 +1,27 @@
+# Releng properties used by languages/CRB.groovy
+
+# The properties required to build using the CICS Resource Builder tool
+# Comma separated list of required build properties for Cicsyml.groovy
+crb_requiredBuildProperties=crb_zrbLocation,crb_resourceModelFile
+
+#
+# Absolute path to the CICS Resource Builder utility (zrb) on z/OS
+# crb_zrbLocation=/var/crb-1.0.3/cics-resource-builder/bin/zrb
+crb_zrbLocation=
+
+#
+# Absolute path to the CICS Resource Builder resource model YAML file on z/OS
+#  the resource model YAML files can be centrally managed within zAppBuilds build-conf directory
+#  or any absolute path outside of the build framework. 
+# We recommend to store the resource model YAML file in its dedicated git repository managed by the 
+#  CICS administration team.
+crb_resourceModelFile=${zAppBuildDir}/build-conf/cicsResourceBuilderConfigurations/${application}-model.yaml
+
+#
+# Absolute path to the CICS Resource Builder application constraints YAML file on z/OS
+#  the application constraints YAML files can be centrally managed within zAppBuilds build-conf directory
+#  or any absolute path outside of the build framework.
+# The CICS Resource Builder application constraints YAML file is an OPTIONAL file for the CICS Resource Builder.
+# We recommend to store the application constraints YAML file in its dedicated git repository managed by the 
+#  CICS administration team.
+crb_applicationConstraintsFile=${zAppBuildDir}/build-conf/cicsResourceBuilderConfigurations/${application}-constraints.yaml

build-conf/README.md

@@ -292,6 +292,28 @@ zunit_reportDatasets | Comma separated list of 'report' type data sets
 zunit_reportOptions | BPXWDYN creation options for creating 'report' type data sets
 zunit_dependenciesDatasetMapping | DBB property mapping to map dependencies to different target datasets
 
+### zCEE3.properties
+Application properties used by zAppBuild/language/zCEE3.groovy
+
+Property | Description
+--- | ---
+zcee3_shellEnvironment | Shell environment used to run the gradle command
+zcee3_gradlePath | Path to gradle executable
+zcee3_gradle_JAVA_OPTS | JAVA Options used with gradle
+
+### CRB.properties
+Application properties used by zAppBuild/language/CRB.groovy
+
+zAppBuild contains the CICS Resource Builder resource model YAML and the CICS Resource Builder application constraints YAML for the MortgageApplication sample in 
+**build-conf/cicsResourceBuilderConfigurations**
+
+Property | Description
+--- | ---
+crb_requiredBuildProperties | Comma separated list of required build properties for language/CRB.groovy
+crb_zrbLocation | Absolute path to the CICS Resource Builder utility (zrb) on z/OS
+crb_resourceModelFile | Absolute path to the CICS Resource Builder resource model YAML file on z/OS
+crb_applicationConstraintsFile | (Optional) Absolute path to the CICS Resource Builder application constraints YAML file on z/OS
+
 ### Transfer.properties
 Build properties used by zAppBuild/language/Transfer.groovy
 

build-conf/build.properties

@@ -6,49 +6,94 @@
 
 
 #######################################################################
-# Global build properties used by zappbuild
+# Global build properties used by zAppBuild
 #
 
 #
 # Comma separated list of additional build property files to load
 # Supports both relative path (to zAppBuild/build-conf/) and absolute path
-buildPropFiles=datasets.properties,dependencyReport.properties,Assembler.properties,BMS.properties,MFS.properties,PSBgen.properties,DBDgen.properties,ACBgen.properties,Cobol.properties,LinkEdit.properties,PLI.properties,REXX.properties,ZunitConfig.properties,Transfer.properties
+#
+# These properties files expect to contain centrally managed defaults
+#  such as system datasets, language script specific settings  
+#
+buildPropFiles=datasets.properties,dependencyReport.properties,Assembler.properties,BMS.properties,\
+MFS.properties,PSBgen.properties,DBDgen.properties,ACBgen.properties,Cobol.properties,\
+LinkEdit.properties,PLI.properties,REXX.properties,ZunitConfig.properties,Transfer.properties,\
+CRB.properties,zCEE3.properties
 
 #
 # Comma separated list of default application configuration property files to load
 # Supports both relative path (to zAppBuild/build-conf/) and absolute path
+# 
+# These properties files expect to contain centrally managed defaults
+#  and also may reference properties files containing configuration
+#  of the language script configurations such as return codes, deploy types   
+# 
+# See also application-conf/application.properties#applicationPropFiles
+# 
+# default: 
+# applicationDefaultPropFiles=defaultzAppBuildConf.properties
+#
+# extended sample to set default language script configurations:
+#
+# applicationDefaultPropFiles=defaultzAppBuildConf.properties,\
+# default-application-conf/searchPaths.properties,\
+# default-application-conf/scriptMappings.properties,\
+# default-application-conf/Cobol.properties,\
+# default-application-conf/BMS.properties,\
+# default-application-conf/PLI.properties,\
+# default-application-conf/Transfer.properties,\
+# default-application-conf/LinkEdit.properties,\
+# default-application-conf/ZunitConfig.properties
+# 
 applicationDefaultPropFiles=defaultzAppBuildConf.properties
 
 #
-# file extension that indicates the build file is really a build list or build list filter
-buildListFileExt=txt
-
+# applicationConfDir
+#
+# required build property that specifies the directory of the
+# application specific build configurations for zAppBuild, also known
+# as application-conf folder
 #
-# Alternate root directory for application-conf locations.  Allows for the deployment of
-# the application-conf directories to an alternate location rather in the application repository.
-# The expectation is that the root directory will have subfolders for all of the applications built
-# by zAppBuild in which the actual application-conf directory is located:
+# a sample of the application-conf can be found in
+#   samples/application-conf
+#
+# zAppBuild expects a file called application.properties in this directory. 
+#
+# The property also allows for the deployment of
+# the application-conf directories to an alternate location rather
+# in the application repository.
+#
+# Default:
+# Location within the application repository and resolving the configuration
+# based on workspace + application and application-conf
+#
+# applicationConfDir=${workspace}/${application}/application-conf
+# 
 #
 # Example: Static location on USS
-# applicationConfRootDir=/u/build/config/applications
+# applicationConfDir=/u/build/config/applications/${application}/application-conf
 # |- /u/build/config/applications
 # |                       |- App1
 # |                       |    |- application-conf
 # |                       |    |        |- application.properties
 # |                       |- App2
 # |                       |    |- application-conf
 #
-# Example: Application cofig files stored in zAppBuild
-# applicationConfRootDir=${zAppBuildDir}/applications
+# Example: Application config files stored in zAppBuild
+# applicationConfDir=${zAppBuildDir}/applications/${application}/application-conf
 # |- /u/build/zAppBuild/applications
 # |                          |- App1
 # |                          |    |- application-conf
 # |                          |    |        |- application.properties
 # |                          |- App2
 # |                          |    |- application-conf
 #
-# Defaults to ${workspace}
-applicationConfRootDir=
+applicationConfDir=${workspace}/${application}/application-conf
+
+#
+# file extension that indicates the build file is really a build list or build list filter
+buildListFileExt=txt
 
 #
 # Determine if a subfolder with a timestamp should be created in the buildOutDir location.
@@ -64,7 +109,7 @@ buildOutputTSformat=yyyyMMdd.HHmmss.mmm
 
 #
 # Minimum required DBB ToolkitVersion to run this version of zAppBuild
-#  Build initialization process validates the DBB Toolkit Version in use and matches that against this setting 
+#  Build initialization process validates the DBB Toolkit Version in use and matches that against this setting
 requiredDBBToolkitVersion=2.0.0
 
 #
@@ -91,7 +136,7 @@ metadataStoreType=file
 #metadataStoreDb2Url=jdbc:db2:<Db2 server location>
 
 # Db2 connection configuration property file
-# Sample is povided at $DBB_HOME/conf/db2Connection.conf 
+# Sample is povided at $DBB_HOME/conf/db2Connection.conf
 #metadataStoreDb2ConnectionConf=
 
 

build-conf/cicsResourceBuilderConfigurations/MortgageApplication-constraints.yaml

@@ -0,0 +1,14 @@
+---
+schemaVersion: resourceModel/1.0
+application:
+  name: MortgageApplication
+  description: MortgageApplication constraints
+  constraints:
+  - id: program-name-prefix
+    prefix: EPS
+  - id: mapset-name-prefix
+    prefix: EPSM
+  - id: transaction-name-prefix
+    prefix: EPS 
+  - id: resource-name-prefix
+    prefix: EPS 

build-conf/cicsResourceBuilderConfigurations/MortgageApplication-model.yaml

@@ -0,0 +1,92 @@
+---
+schemaVersion: resourceModel/1.0
+resourceModel:
+  target: cicsts-6.1.0
+  defines:
+  - type: mapset
+    attributes:
+      public:
+        name:
+          required: true
+          constraintId: mapset-name-prefix
+        group: 
+          required: true 
+          constraintId: resource-name-prefix           
+      private:
+        resident: NO
+        usage: NORMAL
+        uselpacopy: NO
+        status: ENABLED
+  - type: program
+    attributes:
+      public:
+        name:
+          required: true
+          constraintId: program-name-prefix
+        group: 
+          required: true
+          constraintId: resource-name-prefix        
+        datalocation:
+          required: true
+        language:
+          required: true
+        execkey:
+          required: true
+        concurrency:
+          required: true
+        dynamic:
+          required: true
+        executionset:
+          required: true
+      private:
+        usage: NORMAL
+        uselpacopy: NO
+        status: ENABLED
+        reload: NO
+        resident: NO
+        cedf: YES
+        api: CICSAPI
+        jvm: NO
+  - type: transaction
+    attributes:
+      public:
+        name:
+          required: true
+          constraintId: transaction-name-prefix
+        group: 
+          required: true
+          constraintId: resource-name-prefix
+        storageclear:
+          required: true
+        program: 
+          required: true
+          constraintId: program-name-prefix
+      private:
+        tranclass: DFHTCL00
+        status: ENABLED
+        twasize: 0
+        profile: DFHCICST
+        taskdataloc: ANY
+        taskdatakey: USER
+        runaway: SYSTEM
+        shutdown: DISABLED
+        isolate: YES
+        dynamic: NO
+        routable: NO
+        priority: 1
+        dtimout: NO
+        restart: NO
+        spurge: YES
+        tpurge: YES
+        dump: YES
+        trace: YES
+        confdata: NO
+        otstimeout: NO
+        action: BACKOUT
+        wait: YES
+        waittime: 0,0,0
+        ressec: NO
+        cmdsec: NO
+
+        
+        

build-conf/zCEE3.properties

@@ -0,0 +1,20 @@
+# Releng properties used by language/zCEE3.groovy
+
+#
+# Comma separated list of required build properties for zCEE3.groovy
+zcee3_requiredBuildProperties=zcee3_shellEnvironment, zcee3_gradlePath, zcee3_gradle_JAVA_OPTS
+
+#
+# Shell environment used to run the gradle command
+zcee3_shellEnvironment=bash
+
+#
+# Absolute path to gradle executable on z/OS UNIX System Services
+# for instance: /var/gradle/gradle-7.6/bin/gradle
+zcee3_gradlePath=
+
+#
+# JAVA Options used with gradle
+# for instance: zCEE_gradle_JAVA_OPTS=-Xmx512m -XX:MaxMetaspaceSize=256m -Dfile.encoding=UTF-8
+zcee3_gradle_JAVA_OPTS=-Dfile.encoding=UTF-8
+