member_restore

This building block restores artifacts from a backup PDS.

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: RESTORE ARTIFACTS FROM A BACKUP PDS
      short_name: RESTORE_ARTIFACTS 
      steps:
      - name: TEST FOR MEMBER_RESTORE
        short_name: TEST_RESTORE
        properties:
        - key: template
          value: member_restore

types:
  - name: 'LOAD'
  - name: 'DBRM'
  - name: 'CICSLOAD'
  - name: 'JCL'
is_artifact: True
This building block is related to the following artifact types:
  • Load module, CICS load module, DBRM, and JCL for CICS Db2 applications
  • IMS load module, Message Format Service (MFS) source, IMS program specification block (PSB), Data Definition Language (DDL) SQL statements, and IMS database descriptor (DBD) for IMS applications
  • Records like those generated by the IPVLANGX program (for Python only)
The names that you give to these artifact types correspond to the extensions of these artifacts in the package file. You can freely choose these extension names.

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_load_spec:
  type: LIBRARY
  space_primary: 10
  space_secondary: 20
  space_type: CYL
  record_format: U
  record_length: 0

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


hlq: 'NAZARE.WDEPLOY.ANSIBLE'

default_types: 'types'
default_copy_by_folder: False

types:
  - type: 'LOAD'
    copy_by_folder: '{{default_copy_by_folder}}'
    pds: 
      name: '{{ hlq }}.LOADLIB'
      spec: "{{common_pds_load_spec}}"
      backup: '{{ hlq }}.BACK.LOADLIB'
    is_load: True
    aliases: True
    force_lock: True
#   use_native_copy : True
#   native_copy_options: "-X"
  - 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
#   use_native_copy : True
  - type: 'CICSLOAD'
    copy_by_folder: '{{default_copy_by_folder}}'
    pds: 
      name: '{{ hlq }}.LOADLIB'
      spec: "{{common_pds_load_spec}}"
      backup: '{{ hlq }}.BACK.LOADLIB'
    is_load: True
    aliases: True
    force_lock: True
#   use_native_copy : True
#   native_copy_options: "-X" 
  - type: 'JCL'
    copy_by_folder: '{{default_copy_by_folder}}'
    pds: 
      name: '{{ hlq }}.JCL'
      spec: "{{common_pds_text_spec}}"
      backup: '{{ hlq }}.BACK.JCL'
    force_lock: True
    encoding:
      from: UTF-8
      to: IBM-1047
#   use_native_copy : True

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 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:

aliases

Boolean
Default value: True

This variable is valid only if is_load is set to True.

If this variable is set to True (default value), then all the aliases that are found in the PDS/E library or member are to be preserved during the copy operation.

It surfaces the aliases parameter of the Ansible zos_copy module if use_native_copy is not used.

force_lock

Boolean
Default value: False

A variable to authorize or forbid the copy when a task is accessing the target dataset.

If this variable is set to False (default value) and if the target dataset is in use, the building block fails. To check whether the dataset is used, a command is issued for which the user needs to have authority. See Installing and configuring ZOAU in the Z Open Automation Utilities documentation.

If this variable is set to True, then the copy is attempted, even if a task is accessing the target dataset.

Using force_lock can lead to the permanent loss of the original target information.

The force_lock variable is ineffective with the is_asa_text variable if the zos_core version is lower than 1.12.1 and if use_native_copy is not used.

It surfaces the force_lock parameter of the Ansible zos_copy module if use_native_copy is not used.

is_asa_text

Boolean
Default: False

An is_asa_text variable for the artifacts that contain ASA control characters. If this variable is set to True, the copy will preserve ASA control characters in the destination.

This variable is incompatible with the encoding variable.

The force_lock variable is ineffective with the is_asa_text variable if the zos_core version is lower than 1.12.1 and if use_native_copy is not used.

It surfaces the asa_text parameter of the Ansible zos_copy module if use_native_copy is not used.

is_binary

Boolean
Default: False

An is_binary variable set to True if the artifact type corresponds to a binary file. It is mandatory for all the binary files

As the artifact types can be freely chosen in the deployment method (and are therefore present in the deployment plan), you need to enter a variable in the environment variables file to specify their nature.

When is_binary is set to True, no encoding conversion is applied to the content. All the transferred content retains the original state.

It surfaces the is_binary parameter of the Ansible zos_copy module if use_native_copy is not used.

is_load

Boolean
Default: False

An is_load variable set to True if the artifact type corresponds to a load module.

As the artifact types can be freely chosen in the deployment method (and are therefore present in the deployment plan), you need to enter a variable in the environment variables file to specify their nature.

It surfaces the executable parameter of the Ansible zos_copy module if use_native_copy is not used.

native_copy_options

Valid only with use_native_copy: True

A variable to enter copy options.

If you do not indicate copy options, the copy command runs with the following default values:
  • "-F bin" for the binary files (is_binary: True)
  • -XI for the load modules and their preserved aliases (is_load: True and aliases: True)
  • -X for the load modules without their preserved aliases (is_load: True and aliases: False)
  • -T for the others files
pds
The variable for the PDS, with the following embedded variables:
backup

String
Required

The name of the backup PDS where each artifact is stored.

It surfaces the src parameter of the Ansible zos_copy module if use_native_copy is not used.

name

String
Required

The name of the PDS where each artifact is stored.

It surfaces the dest parameter of the Ansible zos_copy module if use_native_copy is not used.

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.

For example, you can enter the following code:

In the following example, pattern and replace are regular expressions. 
- type: 'JCL'
  copy_by_folder: '{{default_copy_by_folder}}'
  pds:
    name: '{{ hlq }}.JCL'
    spec: "{{common_pds_text_spec}}"
    backup: '{{ hlq }}.BACK.JCL'
  encoding:
    from: UTF-8
    to: IBM-1047
  rename_subs:
  - pattern: "CDRD(.*)"
    replace: "CDRP\1"
use_native_copy

Boolean
Default: False

If this variable is set to True, the copy step is faster because it uses the Wazi Deploy dedicated APIs instead of the Ansible zos_copy module.

In this case, Wazi Deploy uses the UNIX shell cp command with the provided native_copy_options.

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_load_spec:
   type: LIBRARY
   primary_space: 10CYL
   secondary_space: 20CYL
   record_format: U
   record_length: 0
common_pds_binary_spec:
   type: LIBRARY
   primary_space: 10CYL
   secondary_space: 20CYL
   record_format: FB
   record_length: 80
common_pds_txt_spec:
   type: LIBRARY
   primary_space: 10CYL
   secondary_space: 20CYL
   record_format: FB
   record_length: 80

hlq: 'NAZARE.WDEPLOY.PYTHON'
  
types:
  - pattern: .*\.LOAD$
    dataset: "{{ hlq }}.LOADLIB"
    dataset_backup: "{{ hlq }}.BACK.LOADLIB"
    spec: "{{ common_pds_load_spec }}"
    is_load: True
    aliases: True
    force_lock: True
#   use_native_copy : True
#   native_copy_options: "-X"
  - pattern: .*\.CICSLOAD$
    dataset: "{{ hlq }}.LOADLIB"
    dataset_backup: "{{ hlq }}.BACK.LOADLIB"
    spec: "{{ common_pds_load_spec }}"
    is_load: True
    aliases: True
    force_lock: True
#   use_native_copy : True
#   native_copy_options: "-X"
  - pattern: .*.DBRM$
    dataset: "{{ hlq }}.DBRM"
    dataset_backup: "{{ hlq }}.BACK.DBRM"
    spec: "{{ common_pds_binary_spec }}"
    is_binary: True
    force_lock: True
#   use_native_copy : True
  - pattern: .*.JCL$
    dataset: "{{ hlq }}.JCL"
    dataset_backup: "{{ hlq }}.BACK.JCL"
    spec: "{{ common_pds_txt_spec }}"
    force_lock: True
    encoding:
      from: UTF-8
      to: IBM-1047
#   use_native_copy : True

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 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:

aliases

Boolean
Default value: True

This variable is valid only if is_load is set to True.

If this variable is set to True (default value), then all the aliases that are found in the PDS/E library or member are to be preserved during the copy operation.

dataset

String
Required

The name of the dataset where each artifact type is stored.

dataset_backup

String
Required

The backup dataset where each artifact type is stored.

force_lock

Boolean
Default value: False

A variable to authorize or forbid the copy when a task is accessing the target dataset.

If this variable is set to False (default value) and if the target dataset is in use, the building block fails. To check whether the dataset is used, a command is issued for which the user needs to have authority. See Installing and configuring ZOAU in the Z Open Automation Utilities documentation.

If this variable is set to True, then the copy is attempted, even if a task is accessing the target dataset.

Using force_lock can lead to the permanent loss of the original target information.

is_asa_text

Boolean
Default: False

An is_asa_text variable for the artifacts that contain ASA control characters. If this variable is set to True, the copy will preserve ASA control characters in the destination.

This variable is incompatible with the encoding variable.

is_binary

Boolean
Default: False

An is_binary variable set to True if the artifact type corresponds to a binary file. It is mandatory for all the binary files

As the artifact types can be freely chosen in the deployment method (and are therefore present in the deployment plan), you need to enter a variable in the environment variables file to specify their nature.

is_load

Boolean
Default: False

An is_load variable set to True if the artifact type corresponds to a load module.

As the artifact types can be freely chosen in the deployment method (and are therefore present in the deployment plan), you need to enter a variable in the environment variables file to specify their nature.

is_record

Boolean
Default: False

An is_record variable set to True if the artifact type corresponds to a record generated by the IPVLANGX program.

native_copy_options

Valid only with use_native_copy: True

A variable to enter copy options.

If you do not indicate copy options, the copy command runs with the following default values:
  • "-F bin" for the binary files (is_binary: True)
  • -XI for the load modules and their preserved aliases (is_load: True and aliases: True)
  • -X for the load modules without their preserved aliases (is_load: True and aliases: False)
  • -T for the others files
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.

For example, you can enter the following code:

In the following example, pattern and replace are regular expressions. 
  - pattern: .\*.JCL$
    dataset: "{{ hlq }}.JCL"
    dataset_backup: "{{ hlq }}.BACK.JCL"
    spec: "{{ common_pds_txt_spec }}"
    encoding:
      from: UTF-8
      to: IBM-1047
    rename_subs:
    - pattern: "CDRD(.*)"
      replace: "CDRP\1"
use_native_copy

Boolean
Default: False

If this variable is set to True, the copy step is faster because it uses the Wazi Deploy dedicated APIs instead of the IBM Z Open Automation Utilities (ZOAU) Python API.

In this case, Wazi Deploy uses the UNIX shell cp command with the provided native_copy_options.

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.