`db2_bind_package`

This building block binds the DBRMs into a package by creating the bind package JCL and running it.

It is run on the artifacts that are listed under the step that it implements in The deployment plan.

To trigger the execution of this building block, you can enter the following code in the deployment method from which the deployment plan is generated. See How to trigger the execution of a building block. The following code is an example.

actions:
    - name: BIND THE DBRMS WITH A JCL
      short_name: BIND_DBRMS 
      states:
         - UNDEFINED
      steps:
      - name: TEST STEP FOR BIND_PACKAGE
        short_name: TEST_PACKAGE
        properties:
        - key: template
          value: db2_bind_package

types:
  - name: 'DBRM'
is_artifact: True

This building block is related to the following artifact type: database request module (DBRM). The name that you give to this artifact type corresponds to the extension of this artifact in the package file. You can freely choose this extension name.

To run correctly, this building block requires environment variables. Indicate them in a .yml file. Indicate The generic environment variables for the Ansible and Python building blocks and adapt their values to your target z/OS environment. Indicate also the variables that are specific to this building block.

The Ansible variables

To run this building block, indicate the following specific variables in an Ansible environment variables file:

common_pds_binary_spec:
  type: LIBRARY
  space_primary: 10
  space_secondary: 20
  space_type: CYL
  record_format: FB
  record_length: 80

default_package_jobcard: "BINDPKG JOB 'WD-PKGBIND',MSGLEVEL=(1,1),MSGCLASS=R,NOTIFY=&SYSUID"
default_db2_action: "REPLACE"
default_db2_user: "{{ ansible_user }}" 

db2_sys_def:
   sdsnload: DSN.V12R1M0.SDSNLOAD
   subsys: DBC1
   qualifier: GENADB0
   package: GENASA1
   sqlid: "{{default_db2_user}}"
   package_jobcard: "{{default_package_jobcard}}"
   package_action: "{{default_db2_action}}"
   package_job_max_rc: 4


default_copy_by_folder: False
default_types: 'types'
hlq: 'NAZARE.WDEPLOY.ANSIBLE'

types:
  - type: 'DBRM'
    copy_by_folder: '{{default_copy_by_folder}}'
    pds: 
      name: '{{ hlq }}.DBRM'
      spec: "{{common_pds_binary_spec}}"
      backup: '{{ hlq }}.BACK.DBRM'
    is_binary: True 
    force_lock: True
    db2_systems:
    - "{{ db2_sys_def }}"

Among all the variables that are shown in this extract, only some of them are used by this building block. The other variables are included so that you can copy and paste all the variables that might be relevant for other building blocks. To run this building block, you must declare the following variables:

The variables related to the artifact types.
Enter the name of the root that lists the types and characteristics of the artifacts to be deployed, if the building block applies to artifacts. By default, the root name is types but you can enter any other name if you define a var_type property in the deployment method step that is implemented by the building block. See The types variable.

Under this root, create a type variable for each artifact type that relates to this building block in the generated deployment plan. The value of each artifact type comes from the deployment method, where it is freely chosen.
Enter the following variables for each type variable:

db2_systems

List
Required

The list of Db2® system definitions. Each Db2 system definition contains the following variables:

package

String
Required

The name of the bind package.

package_action

String
Required

The Db2 action.

package_job_max_rc

Integer
Required

The maximum return code allowed for the successful completion of the zos_job_submit module. See zos_job_submit..

package_jobcard

String
Required

The parameters of the job card for the JCL that binds the package.

qualifier

String
Required

The Qualifier option of the bind.

sdsnload

String
Required

The name of the sdsnload library.

sqlid

String
Required

The Owner option of the bind.

subsys

String
Required

The identifier of the Db2 database runtime parameter.
rename_subs
Dict

Use this variable to rename some artifacts for the deployment. Then, the building block will process these artifacts under names that are different from the names in the application package.

In the following example, pattern and replace are regular expressions.
```
- type: 'DBRM'
    copy_by_folder: '{{default_copy_by_folder}}'
    pds: 
      name: '{{ hlq }}.DBRM'
      spec: "{{common_pds_binary_spec}}"
      backup: '{{ hlq }}.BACK.DBRM'
    is_binary: True 
    force_lock: True
    db2_systems:
    - "{{ db2_sys_def }}"
    rename_subs:
    - pattern: "CDRD(.*)"
      replace: "CDRP\1"
```

The Ansible JCL template

An execution JCL is generated and submitted for this building block. This JCL is generated from the following JCL template:

//********************************************************************
//*               BIND - BIND THE DB2 PACKAGE                        *
//********************************************************************
//{{item.db2_system.package_jobcard}}
//JOBLIB   DD  DISP=SHR,
//             DSN={{item.db2_system.sdsnload}}
//PKGBIND EXEC PGM=IKJEFT01,DYNAMNBR=20,COND=(4,LT)
//SYSTSPRT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSUDUMP DD  SYSOUT=*
//SYSIN    DD  DUMMY
//SYSTSIN  DD  *
DSN SYSTEM ({{item.db2_system.subsys}})
{% for artifact in item.artifacts %}
BIND  PACKAGE({{item.db2_system.package}}) +
   MEMBER({{ artifact.name }}) +
   LIBRARY('{{item.dest_pds}}') +
   QUALIFIER({{item.db2_system.qualifier}}) +
   OWNER({{item.db2_system.sqlid}}) +
   ACTION({{item.db2_system.package_action}}) +
   ISOLATION(CS) +
   RELEASE(COMMIT) +
   ENCODING(EBCDIC)
{% endfor %}
END
/*

In this template, item is the item of a list that contains the following variables:

db2_system: The Db2 system definition associated to the artifact type.
All the variables that are prefixed by db2_system come from what has been defined for this Db2 system definition in your environment file. For more information, see The Ansible variables.
artifacts: The list of the artifacts that this Db2 system definition is associated to.
dest_pds: The PDS that the artifacts have been copied to. This PDS is defined in the pds.name of the artifact type defined on your environment file. For more information, see The Ansible variables.

If more than one Db2 system definition exists for the artifact type, one JCL will be created for each Db2 system definition.

Note: You can provide your own template. To do so, create your Jinja2 JCL template and place it in the Ansible controller search path.

Then, in the deployment method step that corresponds to the execution of the building block, enter a property to indicate the name of your own template by using one of the following two methods:

Enter the template name directly as the value of the template_name property, like in the following example:
```
properties: 
- key: "template_name" 
  value: "my_template_name.j2"
```
Enter the name of the variable that contains the template name as the value of the var_template_name property, and declare this variable in the environment variables file.
In the following example, you enter my_template_variable as the value of the var_template_name property:
```
properties: 
- key: "var_template_name" 
  value: "my_template_variable"
```
Then, you declare this variable in the environment variables file. In the example, you enter my_template_name.j2 as the value of the my_template_variable variable:
```
my_template_variable: my_template_name.j2
```

To know how to define the variables in your Jinja2 template, see The variables in the Jinja2 templates.

The Python variables

To run this building block, indicate the following specific variables in a Python environment variables file. The whole path to this file is indicated in the --envFile argument of The Python deployment command.

common_pds_binary_spec:
   type: LIBRARY
   primary_space: 10CYL
   secondary_space: 20CYL
   record_format: FB
   record_length: 80

hlq: 'NAZARE.WDEPLOY.PYTHON'

default_db2_sdsnload: "DSN.V12R1M0.SDSNLOAD"
default_package_jobcard: "BINDPKG JOB 'WD-PKGBIND',MSGLEVEL=(1,1),MSGCLASS=R,NOTIFY=&SYSUID"
default_db2_user: 'IBMUSER'
default_db2_action: "REPLACE"

db2_sys_def:
   package_maxrc: 4
   user: "{{ default_db2_user }}"
   package: GENASA1
   qualifier: GENADB0
   subsys: DBC1
   package_jobcard: "{{default_package_jobcard}}"
   package_action: "{{default_db2_action}}"
   sdsnload: "{{default_db2_sdsnload}}"


types:
  - pattern: .*.DBRM$
    dataset: "{{ hlq }}.DBRM"
    dataset_backup: "{{ hlq }}.BACK.DBRM"
    spec: "{{ common_pds_binary_spec }}"
    is_binary: True
    db2_systems:
    - "{{ db2_sys_def }}"

The variables related to the artifact types.
Enter the name of the root that lists the types and characteristics of the artifacts to be deployed, if the building block applies to artifacts. By default, the root name is types but you can enter any other name if you define a var_type property in the deployment method step that is implemented by the building block. See The types variable.

Under this root, create a pattern variable for each artifact type that relates to this building block in the deployment plan. The value of each artifact type comes from the deployment method, where it is freely chosen. A pattern is a regular expression that selects the artifacts from their path in The application manifest file.

Enter the following variables for each pattern variable:

db2_systems

List
Required

The list of Db2 system definitions. Each Db2 system definition contains the following variables:

package

String
Required

The name of the bind package.

package_action

String
Required

The Db2 action.

package_jobcard

String
Required

The parameters of the job card for the JCL that binds the package.

package_maxrc

Integer
Required

The maximum return code allowed for the successful execution of the job.

qualifier

String
Required

The Qualifier option of the bind.

sdsnload

String
Required

The name of the sdsnload library.

subsys

String
Required

The identifier of the Db2 database runtime parameter.

user

String
Required

The Owner option of the bind.

rename_subs

Dict

Use this variable to rename some artifacts for the deployment. Then, the building block will process these artifacts under names that are different from the names in the application package.

In the following example, pattern and replace are regular expressions.

- pattern: .*.DBRM$
    dataset: "{{ hlq }}.DBRM"
    dataset_backup: "{{ hlq }}.BACK.DBRM"
    spec: "{{ common_pds_binary_spec }}"
    is_binary: True
    db2_systems:
    - "{{ db2_sys_def }}"
    rename_subs:
    - pattern: "CDRD(.*)"
      replace: "CDRP\1"

search_paths

List

The variable that indicates the list of paths where included Jinja2 templates are stored.

It is used when you provide your own template. For more information, see the note about providing your Jinja2 template in The Python JCL template.

The Python JCL template

An execution JCL is generated and submitted for this building block. This JCL is generated from the following JCL template:

This JCL is generated from the following JCL template.

//********************************************************************
//*               BIND - BIND THE DB2 PACKAGE                        *
//********************************************************************
//{{db2_system['package_jobcard'].strip()}}
//JOBLIB   DD  DISP=SHR,
//             DSN={{db2_system['sdsnload']}}
//PKGBIND EXEC PGM=IKJEFT01,DYNAMNBR=20,COND=(4,LT)
//SYSTSPRT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSUDUMP DD  SYSOUT=*
//SYSIN    DD  DUMMY
//SYSTSIN  DD  *
DSN SYSTEM ({{db2_system['subsys']}})
{% for item in items %}
BIND  PACKAGE({{db2_system['package']}}) +
   MEMBER({{ item['name'] }}) +
   LIBRARY('{{item_type['dataset']|upper}}') +
   QUALIFIER({{db2_system['qualifier']}}) +
   OWNER({{db2_system['user']}}) +
   ACTION({{db2_system['package_action']}}) +
   ISOLATION(CS) +
   RELEASE(COMMIT) +
   ENCODING(EBCDIC)
{% endfor %}
END
/*

This template contains the following variables:

db2_system: The Db2 system definition associated to the artifact type.
All the variables that are prefixed by db2_system come from what has been defined for this Db2 system definition in your environment file. For more information, see The Python variables.
items: The list of the artifacts that this Db2 system definition is associated to.
item_type['dataset']: The PDS that the artifacts have been copied to. This PDS is defined in the dataset variable of the artifact type defined on your environment file. For more information, see The Python variables.

If more than one Db2 system definition exists for the artifact type, one JCL will be created for each Db2 system definition.

Note: You can provide your own template. To do this, create your Jinja2 JCL template and place it in a folder of your choice. Set the DEPLOY_TEMPLATES_PATH environment variable like in the following example:

export DEPLOY_TEMPLATES_PATH=MY_TEMPLATE_FOLDER

Then, in the deployment method step that corresponds to the execution of the building block, enter a property to indicate the name of your own template by using one of the following two methods:

Enter the template name directly as the value of the template_name property, like in the following example:
```
properties: 
- key: "template_name" 
  value: "my_template_name.j2"
```
Enter the name of the variable that contains the template name as the value of the var_template_name property, and declare this variable in the environment variables file.
In the following example, you enter my_template_variable as the value of the var_template_name property:
```
properties: 
- key: "var_template_name" 
  value: "my_template_variable"
```
Then, you declare this variable in the environment variables file. In the example, you enter my_template_name.j2 as the value of the my_template_variable variable:
```
my_template_variable: my_template_name.j2
```

To know how to define the variables in your Jinja2 template, see The variables in the Jinja2 templates.

Return values

The result of each building block task is displayed in the evidence file, in The results level that is embedded in step_result.