db2_bind_plan

This building block binds the DBRMs into a plan by creating the bind plan 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_PLAN
        short_name: TEST_PLAN
        properties:
        - key: template
          value: db2_bind_plan

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_plan_jobcard: "BINDPLA JOB 'WD-PLANBIND',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
   plan: GENAONE
   sqlid:  "{{default_db2_user}}"
   plan_jobcard: "{{default_plan_jobcard}}"
   plan_action: "{{default_db2_action}}"
   plan_job_max_rc: 4
   plan_pklist: '*.GENASA1.*'


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

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 default_plan_jobcard variable, whose value is the default value of the db2_sys_def.plan_jobcard variable.
  • The default_db2_action variable, whose value is the default value of the db2_sys_def.plan_action variable.
  • The default_db2_user variable, whose value is the default value of the db2_sys_def.sqlid variable.
  • The Db2 system definition (db2_sys_def) of each db2_system that is used by the artifact types listed in the types root.
    The following table lists and explains all the variables that constitute the Db2 system definition:
    Variables with sample values Explanations
    db2_sys_def.sdsnload Name of the sdsnload library.
    db2_sys_def.subsys Identifier of the Db2® database runtime parameter.
    db2_sys_def.qualifier Qualifier option of the bind.
    db2_sys_def.plan Name of the bind plan.
    db2_sys_def.sqlid Owner option of the bind.
    db2_sys_def.plan_jobcard Parameters of the job card for the JCL that binds the plan.
    db2_sys_def.plan_action Db2 action.
    db2_sys_def.plan_job_max_rc Maximum return code allowed for the successful completion of the zos_job_submit module. See zos_job_submit.
    db2_sys_def.plan_pklist List of the packages to be included, with commas as separators.
  • 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.

    Specify one or more Db2 systems (db2_sys_def) for each artifact type.

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 PLAN                           *
//********************************************************************
//{{item.db2_system.plan_jobcard}}
//JOBLIB   DD  DISP=SHR,
//             DSN={{item.db2_system.sdsnload}}
//PLABIND 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}})
BIND  PLAN({{item.db2_system.plan}}) +
   PKLIST({{item.db2_system.plan_pklist}}) +
   QUALIFIER({{item.db2_system.qualifier}}) +
   OWNER({{item.db2_system.sqlid}}) +
   ACTION({{item.db2_system.plan_action}}) +
   ISOLATION(CS) +
   RELEASE(COMMIT) +
   ENCODING(EBCDIC)
END
/*
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 Coding 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_plan_jobcard: | 
  BINDPLA JOB 'WD-PLANBIND',MSGLEVEL=(1,1),MSGCLASS=R,NOTIFY=&SYSUID
  /* ---
default_db2_user: 'JENKINS' 
default_db2_action: "REPLACE"

db2_sys_def:
   plan_maxrc: 4
   user: "{{ default_db2_user }}"
   plan: GENAONE
   qualifier: GENADB0
   subsys: DBC1
   plan_jobcard: "{{default_plan_jobcard}}"
   plan_action: "{{default_db2_action}}"
   sdsnload: "{{default_db2_sdsnload}}"
   plan_pklist: '*.GENASA1.*'


types:
  - pattern: .*.DBRM$
    dataset: "{{ hlq }}.DBRM"
    dataset_backup: "{{ hlq }}.BACK.DBRM"
    spec: "{{ common_pds_binary_spec }}"
    is_binary: 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 default_db2_sdsnload variable, whose value is the default value of the db2_sys_def.sdsnload variable.
  • The default_plan_jobcard variable, whose value is the default value of the db2_sys_def.plan_jobcard variable.
  • The default_db2_user variable, whose value is the default value of the db2_sys_def.user variable.
  • The default_db2_action variable, whose value is the default value of the db2_sys_def.plan_action variable.
  • The Db2 system definition (db2_sys_def) of each db2_system that is used by the artifact types listed in the types root.
    The following table lists and explains all the variables that constitute the Db2 system definition:
    Variables with sample values Explanations
    db2_sys_def.sdsnload Name of the sdsnload library.
    db2_sys_def.subsys Identifier of the Db2 database runtime parameter.
    db2_sys_def.qualifier Qualifier option of the bind.
    db2_sys_def.user Owner for the bind.
    db2_sys_def.plan Name of the bind plan.
    db2_sys_def.plan_jobcard Parameters of the job card for the JCL that binds the plan.
    db2_sys_def.plan_action Db2 action.
    db2_sys_def.plan_maxrc Maximum return code allowed for the successful completion of the zos_job_submit module. See zos_job_submit.
    db2_sys_def.plan_pklist List of the packages to be included, with commas as separators.
  • 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.

    Specify one or more Db2 systems (db2_sys_def) for each artifact type.

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 PLAN                           *
//********************************************************************
//{{db2_system['plan_jobcard'].strip()}}
//JOBLIB   DD  DISP=SHR,
//             DSN={{db2_system['sdsnload']}}
//PLABIND 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']}})
BIND  PLAN({{db2_system['plan']}}) +
   PKLIST({{db2_system['plan_pklist']}}) +
   QUALIFIER({{db2_system['qualifier']}}) +
   OWNER({{db2_system['user']}}) +
   ACTION({{db2_system['plan_action']}}) +
   ISOLATION(CS) +
   RELEASE(COMMIT) +
   ENCODING(EBCDIC)
END
/*
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 Coding 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.