uss_copy

This building block copies artifacts to a z/OS UNIX System Services directory. It creates the directory 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: COPY ARTIFACTS TO A USS DIRECTORY
      short_name: COPY_TO_USS
      steps:
      - name: TEST STEP FOR USS_COPY
        short_name: TEST_USS_COPY
        properties:
        - key: template
          value: uss_copy

types:
  - name: 'BIN'
  - name: 'TXT'
  - name: 'SH'
is_artifact: True

This building block is related to the following artifact types: UNIX or LINUX shell executable file, binary file, and text file in this example. However, it can be any type of artifact that you want to manage. 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:
uss_root_folder: '/tmp/wd_uss'

default_types: 'types'

types:
  - type: 'bin'
    uss: 
      dest: "{{ uss_root_folder }}/bin/"
      backup_dest: "{{ uss_root_folder }}/bin/back/"
      dest_mode: '0777'
      artifact_mode: '0755'
      owner: "user1"
      group: "SHOPZ1"
    is_binary: True
  - type: 'txt'
    uss: 
      dest: "{{ uss_root_folder }}/txt/"
      backup_dest: "{{ uss_root_folder }}/txt/back/"
      dest_mode: '0777'
      artifact_mode: '0755'
      owner: "user1"
      group: "SHOPZ1"
    encoding:
      from: UTF-8
      to: IBM-1047
  - type: 'sh'
    uss: 
      dest: "{{ uss_root_folder }}/sh/"
      backup_dest: "{{ uss_root_folder }}/sh/back/"
      dest_mode: '0777'
      artifact_mode: '0755'
      owner: "user1"
      group: "SHOPZ1"

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:

encoding

Dict

Use this variable if an encoding is needed. To indicate an encoding, specify the following embedded variables:
from

String

The initial encoding

to

String

The target encoding

For IBM encoding, use the IBM-xxx syntax (IBM-1047 for example).

It surfaces the encoding parameter of the Ansible zos_copy module if an encoding is set.

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 if an encoding is set.

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: 'txt'
    uss: 
      dest: "{{ uss_root_folder }}/txt/"
      backup_dest: "{{ uss_root_folder }}/txt/back/"
      dest_mode: '0777'
      artifact_mode: '0755'
      owner: "user1"
      group: "SHOPZ1"
    encoding:
      from: UTF-8
      to: IBM-1047
    rename_subs:
    - pattern: "CDRD(.*)"
      replace: "CDRP\1"
text_subs

Dict

A text_subs variable if you want to use text substitution for artifacts that are not binary files (is_binary: False). You can substitute a pattern, which is a regular expression, by a replacement text before the copy.
For example, you can enter the following code:
- type: 'txt'
    uss: 
      dest: "{{ uss_root_folder }}/txt/"
      backup_dest: "{{ uss_root_folder }}/txt/back/"
      dest_mode: '0777'
      artifact_mode: '0755'
    encoding:
      from: UTF-8
      to: IBM-1047
    text_subs:
    - pattern: "#SUB1"
      replace: "01"
    - pattern: "#SUB2"
      replace: "02"
    - pattern: "#SUB3"
      replace: "03"
uss
The variable for the z/OS UNIX System Services directory, with the following embedded variables:
artifact_mode

String

The permission on the artifacts.

It surfaces the mode parameter of the Ansible zos_copy module if an encoding is set, or the mode parameter of the ansible.builtin.copy module if no encoding is set.

dest

String
Required

The whole path to the destination z/OS UNIX System Services directory where each artifact is stored.

It surfaces the dest parameter of the Ansible zos_copy module if an encoding is set or the dest parameter of the ansible.builtin.copy module if no encoding is set.

It also surfaces the path parameter of the ansible.builtin.file module (state: directory).

It also surfaces the path parameter of the ansible.builtin.file module (state: file) if both an encoding and a group or owner are set.

dest_mode

Integer
Required

The permission on the z/OS UNIX System Services directory.

It surfaces the mode parameter of the ansible.builtin.file module (state: directory).

group

String

The name of the group that owns the objects of the z/OS® UNIX System Service directory. If it is not specified, it is the current group of the current user unless you are the root user, in which case it can preserve the previous ownership.

It surfaces the group parameter of the Ansible zos_copy module if an encoding is set, or the group parameter of the ansible.builtin.file module if no encoding is set.

owner

String

The name of the user that should own the objects of the z/OS UNIX System Service directory, as it would be passed to the chown UNIX command. If it is not specified, it is the current user unless you are the root user, in which case it can preserve the previous ownership.

It surfaces the owner parameter of the Ansible zos_copy module if an encoding is set, or the owner parameter of the ansible.builtin.file module if no encoding is set.

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. 

uss_root: '/tmp/uss_root'
types:
  - pattern: .*.BIN$
    directory: "{{ uss_root }}/bin/"
    directory_backup: "{{ uss_root }}/bin/back/"
    dest_mode: 0777
    artifact_mode: 0755
    is_binary: True
    owner: "user1"
    group: "SHOPZ1"
  - pattern: .*.SH$
    directory: "{{ uss_root }}/sh/"
    directory_backup: "{{ uss_root }}/sh/back/"
    dest_mode: 0777
    artifact_mode: 0755
    owner: "user1"
    group: "SHOPZ1"
  - pattern: .*.TXT$
    directory: "{{ uss_root }}/txt/"
    directory_backup: "{{ uss_root }}/txt/back/"
    encoding:
      from: UTF-8
      to: IBM-1047
    dest_mode: 0777
    artifact_mode: 0755
    owner: "user1"
    group: "SHOPZ1"

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:

artifact_mode

Integer

The permission on the artifacts.

dest_mode

Integer
Required

The permission on the z/OS UNIX System Services directory.

directory

String
Required

The whole path to the destination z/OS UNIX System Services directory where each artifact is stored.

encoding

Dict

Use this variable if an encoding is needed. To indicate an encoding, specify the following embedded variables:
from

String

The initial encoding

to

String

The target encoding

For IBM encoding, use the IBM-xxx syntax (IBM-1047 for example).

group

String

The name of the group that owns the objects of the z/OS UNIX System Service directory. If it is not specified, it is the current group of the current user unless you are the root user, in which case it can preserve the previous ownership.

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

owner

String

The name of the user that should own the objects of the z/OS UNIX System Service directory, as it would be passed to the chown UNIX command. If it is not specified, it is the current user unless you are the root user, in which case it can preserve the previous ownership.

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: .*.TXT$
    directory: "{{ uss_root_folder }}/txt/"
    directory_backup: "{{ uss_root_folder }}/txt/back/"
    encoding:
      from: UTF-8
      to: IBM-1047
    dest_mode: 0777
    artifact_mode: 0755 
    owner: "user1"
    group: "SHOPZ1"
    rename_subs:
    - pattern: "CDRD(.*)"
      replace: "CDRP\1"
text_subs

Dict

A text_subs variable if you want to use text substitution for artifacts that are not binary files (is_binary: False). You can substitute a pattern, which is a regular expression, by a replacement text before the copy.
For example, you can enter the following code:
  - pattern: .*.TXT$
    directory: "{{ uss_root_folder }}/txt/"
    directory_backup: "{{ uss_root_folder }}/txt/back/"
    encoding:
      from: UTF-8
      to: IBM-1047
    dest_mode: 0777
    artifact_mode: 0755 
    text_subs:
    - pattern: "#SUB1"
      replace: "01"
    - pattern: "#SUB2"
      replace: "02"
    - pattern: "#SUB3"
      replace: "03"

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.