zos_script – Run scripts in z/OS¶
Synopsis¶
The zos_script module runs a local or remote script in the remote machine.
Parameters¶
- chdir
Change the script’s working directory to this path.
When not specified, the script will run in the user’s home directory on the remote machine.
required: Falsetype: str- cmd
Path to the local or remote script followed by optional arguments.
If the script path contains spaces, make sure to enclose it in two pairs of quotes.
Arguments may need to be escaped so the shell in the remote machine handles them correctly.
required: Truetype: str- creates
Path to a file in the remote machine. If it exists, the script will not be executed.
required: Falsetype: str- encoding
Specifies which encodings the script should be converted from and to.
If
encoding
is not provided, the module determines which local and remote charsets to convert the data from and to.required: Falsetype: dict- from
The encoding to be converted from.
required: Truetype: str- to
The encoding to be converted to.
required: Truetype: str
- executable
Path of an executable in the remote machine to invoke the script with.
When not specified, the system will assume the script is interpreted REXX and try to run it as such. Make sure to include a comment identifying the script as REXX at the start of the file in this case.
required: Falsetype: str- remote_src
If set to
false
, the module will search the script in the controller.If set to
true
, the module will search the script in the remote machine.required: Falsetype: bool- removes
Path to a file in the remote machine. If it does not exist, the script will not be executed.
required: Falsetype: str- use_template
Whether the module should treat
src
as a Jinja2 template and render it before continuing with the rest of the module.Only valid when
src
is a local file or directory.All variables defined in inventory files, vars files and the playbook will be passed to the template engine, as well as Ansible special variables, such as
playbook_dir
,ansible_version
, etc.If variables defined in different scopes share the same name, Ansible will apply variable precedence to them. You can see the complete precedence order in Ansible’s documentation
required: Falsetype: booldefault: False- template_parameters
Options to set the way Jinja2 will process templates.
Jinja2 already sets defaults for the markers it uses, you can find more information at its official documentation.
These options are ignored unless
use_template
is true.required: Falsetype: dict- variable_start_string
Marker for the beginning of a statement to print a variable in Jinja2.
required: Falsetype: strdefault: {{- variable_end_string
Marker for the end of a statement to print a variable in Jinja2.
required: Falsetype: strdefault: }}- block_start_string
Marker for the beginning of a block in Jinja2.
required: Falsetype: strdefault: {%- block_end_string
Marker for the end of a block in Jinja2.
required: Falsetype: strdefault: %}- comment_start_string
Marker for the beginning of a comment in Jinja2.
required: Falsetype: strdefault: {#- comment_end_string
Marker for the end of a comment in Jinja2.
required: Falsetype: strdefault: #}- line_statement_prefix
Prefix used by Jinja2 to identify line-based statements.
required: Falsetype: str- line_comment_prefix
Prefix used by Jinja2 to identify comment lines.
required: Falsetype: str- lstrip_blocks
Whether Jinja2 should strip leading spaces from the start of a line to a block.
required: Falsetype: booldefault: False- trim_blocks
Whether Jinja2 should remove the first newline after a block is removed.
Setting this option to
False
will result in newlines being added to the rendered template. This could create invalid code when working with JCL templates or empty records in destination data sets.required: Falsetype: booldefault: True- keep_trailing_newline
Whether Jinja2 should keep the first trailing newline at the end of a template after rendering.
required: Falsetype: booldefault: False- newline_sequence
Sequence that starts a newline in a template.
required: Falsetype: strdefault: \nchoices: \n, \r, \r\n- auto_reload
Whether to reload a template file when it has changed after the task has started.
required: Falsetype: booldefault: False
Examples¶
- name: Run a local REXX script on the managed z/OS node.
zos_script:
cmd: ./scripts/HELLO
- name: Run a local REXX script with args on the managed z/OS node.
zos_script:
cmd: ./scripts/ARGS "1,2"
- name: Run a remote REXX script while changing its working directory.
zos_script:
cmd: /u/user/scripts/ARGS "1,2"
remote_src: true
chdir: /u/user/output_dir
- name: Run a local Python script in the temporary directory specified in the Ansible environment variable 'remote_tmp'.
zos_script:
cmd: ./scripts/program.py
executable: /usr/bin/python3
- name: Run a local script made from a template.
zos_script:
cmd: ./templates/PROGRAM
use_template: true
- name: Run a script only when a file is not present.
zos_script:
cmd: ./scripts/PROGRAM
creates: /u/user/pgm_result.txt
- name: Run a script only when a file is already present on the remote machine.
zos_script:
cmd: ./scripts/PROGRAM
removes: /u/user/pgm_input.txt
Notes¶
Note
When executing local scripts, temporary storage will be used on the remote z/OS system. The size of the temporary storage will correspond to the size of the file being copied.
The location in the z/OS system where local scripts will be copied to can be configured through Ansible’s remote_tmp
option. Refer to Ansible’s documentation for more information.
All local scripts copied to a remote z/OS system will be removed from the managed node before the module finishes executing.
Execution permissions for the group assigned to the script will be added to remote scripts. The original permissions for remote scripts will be restored by the module before the task ends.
The module will only add execution permissions for the file owner.
If executing REXX scripts, make sure to include a newline character on each line of the file. Otherwise, the interpreter may fail and return error BPXW0003I
.
For supported character sets used to encode data, refer to the documentation.
This module uses zos_copy to copy local scripts to the remote machine which uses SFTP (Secure File Transfer Protocol) for the underlying transfer protocol; SCP (secure copy protocol) and Co:Z SFTP are not supported. In the case of Co:z SFTP, you can exempt the Ansible user id on z/OS from using Co:Z thus falling back to using standard SFTP. If the module detects SCP, it will temporarily use SFTP for transfers, if not available, the module will fail.
This module executes scripts inside z/OS UNIX System Services. For running REXX scripts contained in data sets or CLISTs, consider issuing a TSO command with zos_tso_command.
The community script module does not rely on Python to execute scripts on a managed node, while this module does. Python must be present on the remote machine.
Return Values¶
- cmd
Original command issued by the user.
returned: changedtype: strsample: ./scripts/PROGRAM- remote_cmd
Command executed on the remote machine. Will show the executable path used, and when running local scripts, will also show the temporary file used.
returned: changedtype: strsample: /tmp/zos_script.jycqqfny.ARGS 1,2- msg
Failure or skip message returned by the module.
returned: failure or skippedtype: strsample: File /u/user/file.txt is already missing on the system, skipping script- rc
Return code of the script.
returned: changedtype: intsample: 16- stdout
The STDOUT from the script, may be empty.
returned: changedtype: strsample: Allocation to SYSEXEC completed.- stderr
The STDERR from the script, may be empty.
returned: changedtype: strsample: An error has ocurred.- stdout_lines
List of strings containing individual lines from STDOUT.
returned: changedtype: listsample:[ "Allocation to SYSEXEC completed." ]
- stderr_lines
List of strings containing individual lines from STDERR.
returned: changedtype: listsample:[ "An error has ocurred" ]