sequential_archive

This building block copies artifacts from a z/OS® sequential data set to a sequential backup data set. It creates the sequential backup data set if it does not exist.

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: ARCHIVE ARTIFACTS TO A ZOS BACKUP DATA SET
      short_name: ARCHIVE_TO_ZOS 
      steps:
      - name: TEST STEP FOR SEQUENTIAL_ARCHIVE
        short_name: TEST_SEQ_ARCHIVE
        properties:
        - key: template
          value: sequential_archive

types:
  - name: 'seq'
  - name: 'seqa'
is_artifact: True

This building block is related to the following artifact type: sequential data set. 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:
seq_spec:
  type: SEQ
  space_primary: 5
  space_secondary: 2
  space_type: TRK
  record_format: FB
  record_length: 20  

seq_spec_a:
  type: SEQ
  space_primary: 2
  space_secondary: 1
  space_type: TRK
  record_format: FB
  record_length: 15

hlq: 'NAZARE.WDEPLOY.ANSIBLE'

default_types: 'types'

types:
  - type: 'seq'
    is_binary: False
    is_sequential: True
    encoding:
      from: UTF-8
      to: IBM-037
#   is_asa_text: False
    ds: 
      prefix: "{{ hlq }}.SEQ"
      backup_prefix: "{{ hlq }}.BACK.SEQ"
      spec: "{{seq_spec}}"

  - type: 'seqa'
    is_binary: False
    is_sequential: True
    encoding:
      from: UTF-8
      to: IBM-037
#   is_asa_text: False
    ds: 
      prefix: "{{ hlq }}.SEQ"
      backup_prefix: "{{ hlq }}.BACK.SEQ"
      spec: "{{seq_spec_a}}"

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:

ds
The variable for the z/OS sequential data set, with the following embedded variables:
backup_prefix

String
Required

The prefix of the z/OS sequential backup data set. The z/OS sequential backup data set will be the concatenation of this prefix and the artifact name.

It surfaces the dest parameter of the Ansible zos_copy module.

prefix

String
Required

The prefix of the z/OS sequential data set. The z/OS sequential data set will be the concatenation of this prefix and the artifact name.

It surfaces the src parameter of the Ansible zos_copy module.

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.

It surfaces the asa_text parameter of the Ansible zos_copy module.

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

It surfaces the is_binary parameter of the Ansible zos_copy module.

is_sequential

Boolean
Default: False

An is_sequential variable set to True if the artifact type corresponds to a sequential file. It is mandatory for all the sequential 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:
- type: 'seq'
    ds: 
      prefix: "{{ hlq }}.SEQ"
      backup_prefix: "{{ hlq }}.BACK.SEQ"
      spec: "{{seq_spec}}"
   encoding:
     from: UTF-8
     to: IBM-1047
#   is_asa_text: False
    is_binary: False
    is_sequential: True
    spec: "{{seq_spec}}"
   rename_subs:
   - pattern: "CDRD(.*)"
     replace: "CDRP\1"

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. 

seq_spec:
   type: SEQ
   primary_space: 5TRK
   secondary_space: 2TRK
   record_format: FB
   record_length: 20
seq_spec_a:
   type: SEQ
   primary_space: 2TRK
   secondary_space: 1TRK
   record_format: FB
   record_length: 15

hlq: 'NAZARE.WDEPLOY.PYTHON'

types:
  - pattern: .*.SEQ$
    dataset_prefix: "{{ hlq }}.SEQ"
    dataset_backup_prefix: "{{ hlq }}.BACK.SEQ"
    encoding:
      from: UTF-8
      to: IBM-037
#   is_asa_text: False
    is_binary: False
    is_sequential: True
    spec: "{{seq_spec}}"
  - pattern: .*.SEQA$
    dataset_prefix: "{{ hlq }}.SEQ"
    dataset_backup_prefix: "{{ hlq }}.BACK.SEQ"
    encoding:
      from: UTF-8
      to: IBM-037
#   is_asa_text: False
    is_binary: False
    is_sequential: True
    spec: "{{seq_spec_a}}"

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:

dataset_backup_prefix

String
Required

The prefix of the z/OS sequential backup data set. The z/OS sequential backup data set will be the concatenation of this prefix and the artifact name.

dataset_prefix

String
Required

The prefix of the z/OS sequential data set. The z/OS sequential data set will be the concatenation of this prefix and the artifact name.

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

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:
  - pattern: .*.SEQ$
    dataset_prefix: "{{ hlq }}.SEQ"
    dataset_backup_prefix: "{{ hlq }}.BACK.SEQ"
    encoding:
      from: UTF-8
      to: IBM-037
#   is_asa_text: False
    is_binary: False
    is_sequential: True
    spec: "{{seq_spec}}"
    rename_subs:
    - pattern: "CDRD(.*)"
      replace: "CDRP\1"

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.