`tso_command`

This building block runs one or more TSO commands on the target z/OS® environment with the provided options and receives a structured response. The TSO commands are written directly in the environment variables file, or written in a file or a Jinja2 template.

This building block is not related to artifacts.

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: RUN A TSO COMMAND NOT RELATED TO ARTIFACTS
      short_name: TSO_COMMAND 
      steps:  
      - name: TEST STEP FOR TSO_COMMAND 
        short_name: TSO_COMMAND_TEST 
        properties:
        - key: template
          value: tso_command
        - key: var_tso_command
          value: my_var_tso_command

is_artifact: False

In this example, the value of the var_tso_command property is my_var_tso_command, but it can be any other string.

If you do not indicate the var_tso_command property in a step of the deployment method, then the default value for this property (the tso_command_default variable) will be used.

In both cases, this value (my_var_tso_command or tso_command_default) must be declared in the environment variables file. For Python, the entire path to this file is indicated in the --envFile argument of The Python deployment command.

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

The value of the var_tso_command property or the tso_command_default variable must contain the following variables, depending on where your TSO commands are located.

commands: List

A list of TSO commands directly under the variable. This variable is incompatible with the src variable.

It surfaces the commands parameter of the Ansible zos_tso_command module.
dest: Path

The full or relative path to the target file to be created on the Ansible controller. This target file contains the jinja2 template rendered. This variable is required if use_template is set to True.

It surfaces the dest parameter of the Ansible template module if src is a Jinja2 template.
max_rc: Integer
Default: 0

The maximum return code authorized for a TSO command. If more than one TSO command is submitted, the max_rc variable applies to all TSO commands.

It surfaces the max_rc parameter of the Ansible zos_tso_command module.
src: Path

The full or relative path to the file that contains the TSO commands. This file is on the Ansible controller. It can be a .sh file or a Jinja2 template. This variable is required if use_template is set to True. This variable is incompatible with commands variable.

It surfaces the src parameter of the Ansible template module if src is a Jinja2 template.
use_template: Boolean
Default: False

The variable that indicates whether the src variable contains a Jinja2 template.

The following examples illustrate the declaration of the environment variables for this building block:

The following sample TSO command is written directly under the commands variable. It lists the TESTUSER user profile.
```
my_var_tso_command:
  commands:
    - LU TESTUSER
  max_rc: 4 
```
The following example shows TSO commands that are written in a file on the Ansible Controller.
```
my_var_tso_command:
  src: "my_files_and_templates/my_tsocmd_file.txt"
```

The following example shows TSO commands that are written in a Jinja2 template, which will be rendered into the dest file.

my_var_tso_command:
  use_template: True
  src: "my_files_and_templates/my_tsocmd_template.j2"
  dest: “my_files_and_templates/my_new_tsocmd.txt"

The Python variables

The value of the var_tso_command property or the tso_command_default variable must contain the following variables, depending on where your TSO commands are located.

commands

List

A list of TSO commands directly under the variable. This variable is incompatible with the src variable.

dest

Path

The full or relative path to the target file to be created in the z/OS environment. This target file contains the jinja2 template rendered. This variable is required if use_template is set to True.

max_rc

Integer
Default: 0

The maximum return code authorized for a TSO command. If more than one TSO command is submitted, the max_rc variable applies to all TSO commands.

search_paths

List

The variable that indicates the list of paths where included Jinja2 templates are stored. It is used when use_template is set to True.

src

Path

The full or relative path to the file that contains the TSO commands. This file is on the z/OS environment. It can be a .sh file or a Jinja2 template. This variable is required if use_template is set to True. This variable is incompatible with commands variable.

use_template: Boolean
Default: False

The variable that indicates whether the src variable contains a Jinja2 template.

The following examples illustrate the declaration of the environment variables for this building block:

The following sample TSO command is written directly under the commands variable. It lists the TESTUSER user profile.
```
my_var_tso_command:
  commands:
    - LU TESTUSER
  max_rc: 4 
```
The following example shows TSO commands that are written in a file on the z/OS environment.
```
my_var_tso_command:
  src: "/tmp/my_tsocmd_file.txt"
```

The following example shows TSO commands that are written in a Jinja2 template, which will be rendered into the dest file.

my_var_tso_command:
  use_template: True
  src: "/tmp/my_tsocmd_template.j2"
  dest: “/tmp/my_new_tsocmd.txt"  
  search_paths:
  - "{{working_folder}}/include"

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.