Try SpotterCopy data to z/OS
| "added in version" 1.2.0 of ibm.ibm_zos_core"
Authors: Asif Mahmud (@asifmahmud), Demetrios Dimatos (@ddimatos), Ivan Moreno (@rexemin)
This plugin has a corresponding action plugin.
Install with ansible-galaxy collection install ibm.ibm_zos_core:==1.9.0
collections:
- name: ibm.ibm_zos_core
version: 1.9.0The L(zos_copy,./zos_copy.html) module copies a file or data set from a local or a remote machine to a location on the remote machine.
- name: Copy a local file to a sequential data set
zos_copy:
src: /path/to/sample_seq_data_set
dest: SAMPLE.SEQ.DATA.SET
- name: Copy a local file to a USS location and validate checksum
zos_copy:
src: /path/to/test.log
dest: /tmp/test.log
validate: true
- name: Copy a local ASCII encoded file and convert to IBM-1047
zos_copy:
src: /path/to/file.txt
dest: /tmp/file.txt
- name: Copy a local directory to a PDSE
zos_copy:
src: /path/to/local/dir/
dest: HLQ.DEST.PDSE
- name: Copy file with permission details
zos_copy:
src: /path/to/foo.conf
dest: /etc/foo.conf
mode: 0644
group: foo
owner: bar
- name: Module will follow the symbolic link specified in src
zos_copy:
src: /path/to/link
dest: /path/to/uss/location
local_follow: true
- name: Copy a local file to a PDS member and convert encoding
zos_copy:
src: /path/to/local/file
dest: HLQ.SAMPLE.PDSE(MEMBER)
encoding:
from: UTF-8
to: IBM-037
- name: Copy a VSAM (KSDS) to a VSAM (KSDS)
zos_copy:
src: SAMPLE.SRC.VSAM
dest: SAMPLE.DEST.VSAM
remote_src: true
- name: Copy inline content to a sequential dataset and replace existing data
zos_copy:
content: 'Inline content to be copied'
dest: SAMPLE.SEQ.DATA.SET
- name: Copy a USS file to sequential data set and convert encoding beforehand
zos_copy:
src: /path/to/remote/uss/file
dest: SAMPLE.SEQ.DATA.SET
remote_src: true
- name: Copy a USS directory to another USS directory
zos_copy:
src: /path/to/uss/dir
dest: /path/to/dest/dir
remote_src: true
- name: Copy a local binary file to a PDSE member
zos_copy:
src: /path/to/binary/file
dest: HLQ.SAMPLE.PDSE(MEMBER)
is_binary: true
- name: Copy a sequential data set to a PDS member
zos_copy:
src: SAMPLE.SEQ.DATA.SET
dest: HLQ.SAMPLE.PDSE(MEMBER)
remote_src: true
- name: Copy a local file and take a backup of the existing file
zos_copy:
src: /path/to/local/file
dest: /path/to/dest
backup: true
backup_name: /tmp/local_file_backup
- name: Copy a PDS on remote system to a new PDS
zos_copy:
src: HLQ.SRC.PDS
dest: HLQ.NEW.PDS
remote_src: true
- name: Copy a PDS on remote system to a PDS, replacing the original
zos_copy:
src: HLQ.SAMPLE.PDSE
dest: HLQ.EXISTING.PDSE
remote_src: true
force: true
- name: Copy PDS member to a new PDS member. Replace if it already exists
zos_copy:
src: HLQ.SAMPLE.PDSE(SRCMEM)
dest: HLQ.NEW.PDSE(DESTMEM)
remote_src: true
force: true
- name: Copy a USS file to a PDSE member. If PDSE does not exist, allocate it
zos_copy:
src: /path/to/uss/src
dest: DEST.PDSE.DATA.SET(MEMBER)
remote_src: true
- name: Copy a sequential data set to a USS file
zos_copy:
src: SRC.SEQ.DATA.SET
dest: /tmp/
remote_src: true
- name: Copy a PDSE member to USS file
zos_copy:
src: SRC.PDSE(MEMBER)
dest: /tmp/member
remote_src: true
- name: Copy a PDS to a USS directory (/tmp/SRC.PDS)
zos_copy:
src: SRC.PDS
dest: /tmp
remote_src: true
- name: Copy all members inside a PDS to another PDS
zos_copy:
src: SOME.SRC.PDS(*)
dest: SOME.DEST.PDS
remote_src: true
- name: Copy all members starting with 'ABC' inside a PDS to another PDS
zos_copy:
src: SOME.SRC.PDS(ABC*)
dest: SOME.DEST.PDS
remote_src: true
- name: Allocate destination in a specific volume
zos_copy:
src: SOME.SRC.PDS
dest: SOME.DEST.PDS
volume: 'VOL033'
remote_src: true
- name: Copy a USS file to a fully customized sequential data set
zos_copy:
src: /path/to/uss/src
dest: SOME.SEQ.DEST
remote_src: true
volume: '222222'
dest_data_set:
type: SEQ
space_primary: 10
space_secondary: 3
space_type: K
record_format: VB
record_length: 150
- name: Copy a Program Object and its aliases on a remote system to a new PDSE member MYCOBOL
zos_copy:
src: HLQ.COBOLSRC.PDSE(TESTPGM)
dest: HLQ.NEW.PDSE(MYCOBOL)
remote_src: true
executable: true
aliases: true
- name: Copy a Load Library from a USS directory /home/loadlib to a new PDSE
zos_copy:
src: '/home/loadlib/'
dest: HLQ.LOADLIB.NEW
remote_src: true
executable: true
aliases: true
- name: Copy a file with ASA characters to a new sequential data set.
zos_copy:
src: ./files/print.txt
dest: HLQ.PRINT.NEW
asa_text: true
src:
description:
- Path to a file/directory or name of a data set to copy to remote z/OS system.
- If C(remote_src) is true, then C(src) must be the path to a Unix System Services
(USS) file, name of a data set, or data set member.
- If C(src) is a local path or a USS path, it can be absolute or relative.
- If C(src) is a directory, C(dest) must be a partitioned data set or a USS directory.
- If C(src) is a file and C(dest) ends with "/" or is a directory, the file is copied
to the directory with the same filename as C(src).
- If C(src) is a directory and ends with "/", the contents of it will be copied into
the root of C(dest). If it doesn't end with "/", the directory itself will be copied.
- If C(src) is a directory or a file, file names will be truncated and/or modified
to ensure a valid name for a data set or member.
- If C(src) is a VSAM data set, C(dest) must also be a VSAM.
- Wildcards can be used to copy multiple PDS/PDSE members to another PDS/PDSE.
- Required unless using C(content).
type: str
dest:
description:
- The remote absolute path or data set where the content should be copied to.
- C(dest) can be a USS file, directory or MVS data set name.
- If C(dest) has missing parent directories, they will be created.
- If C(dest) is a nonexistent USS file, it will be created.
- If C(dest) is a new USS file or replacement, the file will be appropriately tagged
with either the system's default locale or the encoding option defined. If the USS
file is a replacement, the user must have write authority to the file either through
ownership, group or other permissions, else the copy will fail.
- If C(dest) is a nonexistent data set, it will be created following the process outlined
here and in the C(volume) option.
- If C(dest) is a nonexistent data set, the attributes assigned will depend on the
type of C(src). If C(src) is a USS file, C(dest) will have a Fixed Block (FB) record
format and the remaining attributes will be computed. If I(is_binary=true), C(dest)
will have a Fixed Block (FB) record format with a record length of 80, block size
of 32760, and the remaining attributes will be computed. If I(executable=true),C(dest)
will have an Undefined (U) record format with a record length of 0, block size of
32760, and the remaining attributes will be computed.
- When C(dest) is a data set, precedence rules apply. If C(dest_data_set) is set,
this will take precedence over an existing data set. If C(dest) is an empty data
set, the empty data set will be written with the expectation its attributes satisfy
the copy. Lastly, if no precendent rule has been exercised, C(dest) will be created
with the same attributes of C(src).
- When the C(dest) is an existing VSAM (KSDS) or VSAM (ESDS), then source can be an
ESDS, a KSDS or an RRDS. The VSAM (KSDS) or VSAM (ESDS) C(dest) will be deleted
and recreated following the process outlined in the C(volume) option.
- When the C(dest) is an existing VSAM (RRDS), then the source must be an RRDS. The
VSAM (RRDS) will be deleted and recreated following the process outlined in the
C(volume) option.
- When C(dest) is and existing VSAM (LDS), then source must be an LDS. The VSAM (LDS)
will be deleted and recreated following the process outlined in the C(volume) option.
- When C(dest) is a data set, you can override storage management rules by specifying
C(volume) if the storage class being used has GUARANTEED_SPACE=YES specified, otherwise,
the allocation will fail. See C(volume) for more volume related processes.
required: true
type: str
mode:
description:
- The permission of the destination file or directory.
- If C(dest) is USS, this will act as Unix file mode, otherwise ignored.
- It should be noted that modes are octal numbers. The user must either add a leading
zero so that Ansible's YAML parser knows it is an octal number (like C(0644) or
C(01777))or quote it (like C('644') or C('1777')) so Ansible receives a string and
can do its own conversion from string into number. Giving Ansible a number without
following one of these rules will end up with a decimal number which will have unexpected
results.
- The mode may also be specified as a symbolic mode (for example, ``u+rwx`` or ``u=rw,g=r,o=r``)
or a special string `preserve`.
- I(mode=preserve) means that the file will be given the same permissions as the source
file.
required: false
type: str
force:
default: false
description:
- If set to C(true) and the remote file or data set C(dest) is empty, the C(dest)
will be reused.
- If set to C(true) and the remote file or data set C(dest) is NOT empty, the C(dest)
will be deleted and recreated with the C(src) data set attributes, otherwise it
will be recreated with the C(dest) data set attributes.
- To backup data before any deletion, see parameters C(backup) and C(backup_name).
- If set to C(false), the file or data set will only be copied if the destination
does not exist.
- If set to C(false) and destination exists, the module exits with a note to the user.
required: false
type: bool
backup:
default: false
description:
- Specifies whether a backup of the destination should be created before copying data.
- When set to C(true), the module creates a backup file or data set.
- The backup file name will be returned on either success or failure of module execution
such that data can be retrieved.
required: false
type: bool
volume:
description:
- If C(dest) does not exist, specify which volume C(dest) should be allocated to.
- Only valid when the destination is an MVS data set.
- The volume must already be present on the device.
- If no volume is specified, storage management rules will be used to determine the
volume where C(dest) will be allocated.
- If the storage administrator has specified a system default unit name and you do
not set a C(volume) name for non-system-managed data sets, then the system uses
the volumes associated with the default unit name. Check with your storage administrator
to determine whether a default unit name has been specified.
required: false
type: str
aliases:
default: false
description:
- If set to C(true), indicates that any aliases found in the source (USS file, USS
dir, PDS/E library or member) are to be preserved during the copy operation.
- Aliases are implicitly preserved when libraries are copied over to USS destinations.
That is, when C(executable=True) and C(dest) is a USS file or directory, this option
will be ignored.
- Copying of aliases for text-based data sets from USS sources or to USS destinations
is not currently supported.
required: false
type: bool
content:
description:
- When used instead of C(src), sets the contents of a file or data set directly to
the specified value.
- Works only when C(dest) is a USS file, sequential data set, or a partitioned data
set member.
- If C(dest) is a directory, then content will be copied to C(/path/to/dest/inline_copy).
required: false
type: str
tmp_hlq:
description:
- Override the default high level qualifier (HLQ) for temporary and backup datasets.
- The default HLQ is the Ansible user used to execute the module and if that is not
available, then the value C(TMPHLQ) is used.
required: false
type: str
asa_text:
default: false
description:
- If set to C(true), indicates that either C(src) or C(dest) or both contain ASA control
characters.
- When C(src) is a USS file and C(dest) is a data set, the copy will preserve ASA
control characters in the destination.
- When C(src) is a data set containing ASA control characters and C(dest) is a USS
file, the copy will put all control characters as plain text in the destination.
- If C(dest) is a non-existent data set, it will be created with record format Fixed
Block with ANSI format (FBA).
- If neither C(src) or C(dest) have record format Fixed Block with ANSI format (FBA)
or Variable Block with ANSI format (VBA), the module will fail.
- This option is only valid for text files. If C(is_binary) is C(true) or C(executable)
is C(true) as well, the module will fail.
required: false
type: bool
encoding:
description:
- Specifies which encodings the destination file or data set should be converted from
and to.
- If C(encoding) is not provided, the module determines which local and remote charsets
to convert the data from and to. Note that this is only done for text data and not
binary data.
- Only valid if C(is_binary) is false.
required: false
suboptions:
from:
description:
- The encoding to be converted from
required: true
type: str
to:
description:
- The encoding to be converted to
required: true
type: str
type: dict
validate:
default: false
description:
- Specifies whether to perform checksum validation for source and destination files.
- Valid only for USS destination, otherwise ignored.
required: false
type: bool
is_binary:
default: false
description:
- If set to C(true), indicates that the file or data set to be copied is a binary
file or data set.
- When I(is_binary=true), no encoding conversion is applied to the content, all content
transferred retains the original state.
- Use I(is_binary=true) when copying a Database Request Module (DBRM) to retain the
original state of the serialized SQL statements of a program.
required: false
type: bool
executable:
default: false
description:
- If set to C(true), indicates that the file or library to be copied is an executable.
- If the C(src) executable has an alias, the alias information is also copied. If
the C(dest) is Unix, the alias is not visible in Unix, even though the information
is there and will be visible if copied to a library.
- If I(executable=true), and C(dest) is a data set, it must be a PDS or PDSE (library).
- If C(dest) is a nonexistent data set, the library attributes assigned will be Undefined
(U) record format with a record length of 0, block size of 32760 and the remaining
attributes will be computed.
- If C(dest) is a file, execute permission for the user will be added to the file
(``u+x``).
required: false
type: bool
force_lock:
default: false
description:
- By default, when C(dest) is a MVS data set and is being used by another process
with DISP=SHR or DISP=OLD the module will fail. Use C(force_lock) to bypass this
check and continue with copy.
- If set to C(true) and destination is a MVS data set opened by another process then
zos_copy will try to copy using DISP=SHR.
- Using C(force_lock) uses operations that are subject to race conditions and can
lead to data loss, use with caution.
- If a data set member has aliases, and is not a program object, copying that member
to a dataset that is in use will result in the aliases not being preserved in the
target dataset. When this scenario occurs the module will fail.
required: false
type: bool
remote_src:
default: false
description:
- If set to C(false), the module searches for C(src) at the local machine.
- If set to C(true), the module goes to the remote/target machine for C(src).
required: false
type: bool
backup_name:
description:
- Specify a unique USS file name or data set name for the destination backup.
- If the destination C(dest) is a USS file or path, the C(backup_name) must be an
absolute path name.
- If the destination is an MVS data set name, the C(backup_name) provided must meet
data set naming conventions of one or more qualifiers, each from one to eight characters
long, that are delimited by periods.
- If the C(backup_name) is not provided, the default C(backup_name) will be used.
If the C(dest) is a USS file or USS path, the name of the backup file will be the
destination file or path name appended with a timestamp, e.g. C(/path/file_name.2020-04-23-08-32-29-bak.tar).
If the C(dest) is an MVS data set, it will be a data set with a randomly generated
name.
- If C(dest) is a data set member and C(backup_name) is not provided, the data set
member will be backed up to the same partitioned data set with a randomly generated
member name.
required: false
type: str
local_follow:
default: true
description:
- This flag indicates that any existing filesystem links in the source tree should
be followed.
required: false
type: bool
use_template:
default: false
description:
- Whether the module should treat C(src) as a Jinja2 template and render it before
continuing with the rest of the module.
- Only valid when C(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 L(Ansible special variables,https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html#special-variables),
such as C(playbook_dir), C(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 L(in Ansible's
documentation,https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#understanding-variable-precedence)
type: bool
dest_data_set:
description:
- Data set attributes to customize a C(dest) data set to be copied into.
required: false
suboptions:
block_size:
description:
- The block size to use for the data set.
required: false
type: int
directory_blocks:
description:
- The number of directory blocks to allocate to the data set.
required: false
type: int
key_length:
description:
- The key length to use when creating a KSDS data set.
- I(key_length) is required when I(type=KSDS).
- I(key_length) should only be provided when I(type=KSDS)
required: false
type: int
key_offset:
description:
- The key offset to use when creating a KSDS data set.
- I(key_offset) is required when I(type=KSDS).
- I(key_offset) should only be provided when I(type=KSDS)
required: false
type: int
record_format:
choices:
- FB
- VB
- FBA
- VBA
- U
description:
- If the destination data set does not exist, this sets the format of the data
set. (e.g C(FB))
- Choices are case-insensitive.
required: false
type: str
record_length:
description:
- The length of each record in the data set, in bytes.
- For variable data sets, the length must include the 4-byte prefix area.
- 'Defaults vary depending on format: If FB/FBA 80, if VB/VBA 137, if U 0.'
required: false
type: int
sms_data_class:
description:
- The data class for an SMS-managed dataset.
- Optional for SMS-managed datasets that do not match an SMS-rule.
- Not valid for datasets that are not SMS-managed.
- Note that all non-linear VSAM datasets are SMS-managed.
required: false
type: str
sms_management_class:
description:
- The management class for an SMS-managed dataset.
- Optional for SMS-managed datasets that do not match an SMS-rule.
- Not valid for datasets that are not SMS-managed.
- Note that all non-linear VSAM datasets are SMS-managed.
required: false
type: str
sms_storage_class:
description:
- The storage class for an SMS-managed dataset.
- Required for SMS-managed datasets that do not match an SMS-rule.
- Not valid for datasets that are not SMS-managed.
- Note that all non-linear VSAM datasets are SMS-managed.
required: false
type: str
space_primary:
description:
- If the destination I(dest) data set does not exist , this sets the primary space
allocated for the data set.
- The unit of space used is set using I(space_type).
required: false
type: int
space_secondary:
description:
- If the destination I(dest) data set does not exist , this sets the secondary
space allocated for the data set.
- The unit of space used is set using I(space_type).
required: false
type: int
space_type:
choices:
- K
- M
- G
- CYL
- TRK
description:
- If the destination data set does not exist, this sets the unit of measurement
to use when defining primary and secondary space.
- Valid units of size are C(K), C(M), C(G), C(CYL), and C(TRK).
required: false
type: str
type:
choices:
- KSDS
- ESDS
- RRDS
- LDS
- SEQ
- PDS
- PDSE
- MEMBER
- BASIC
- LIBRARY
description:
- Organization of the destination
required: true
type: str
type: dict
ignore_sftp_stderr:
default: false
description:
- During data transfer through SFTP, the module fails if the SFTP command directs
any content to stderr. The user is able to override this behavior by setting this
parameter to C(true). By doing so, the module would essentially ignore the stderr
stream produced by SFTP and continue execution.
- When Ansible verbosity is set to greater than 3, either through the command line
interface (CLI) using B(-vvvv) or through environment variables such as B(verbosity
= 4), then this parameter will automatically be set to C(true).
required: false
type: bool
version_added: 1.4.0
version_added_collection: ibm.ibm_zos_core
template_parameters:
description:
- 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 L(official documentation,https://jinja.palletsprojects.com/en/latest/templates/).
- These options are ignored unless C(use_template) is true.
required: false
suboptions:
auto_reload:
default: false
description:
- Whether to reload a template file when it has changed after the task has started.
type: bool
block_end_string:
default: '%}'
description:
- Marker for the end of a block in Jinja2.
type: str
block_start_string:
default: '{%'
description:
- Marker for the beginning of a block in Jinja2.
type: str
comment_end_string:
default: '#}'
description:
- Marker for the end of a comment in Jinja2.
type: str
comment_start_string:
default: '{#'
description:
- Marker for the beginning of a comment in Jinja2.
type: str
keep_trailing_newline:
default: false
description:
- Whether Jinja2 should keep the first trailing newline at the end of a template
after rendering.
type: bool
line_comment_prefix:
description:
- Prefix used by Jinja2 to identify comment lines.
required: false
type: str
line_statement_prefix:
description:
- Prefix used by Jinja2 to identify line-based statements.
required: false
type: str
lstrip_blocks:
default: false
description:
- Whether Jinja2 should strip leading spaces from the start of a line to a block.
type: bool
newline_sequence:
choices:
- '
'
- "\r"
- "\r\n"
default: '
'
description:
- Sequence that starts a newline in a template.
type: str
trim_blocks:
default: true
description:
- Whether Jinja2 should remove the first newline after a block is removed.
- Setting this option to C(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.
type: bool
variable_end_string:
default: '}}'
description:
- Marker for the end of a statement to print a variable in Jinja2.
type: str
variable_start_string:
default: '{{'
description:
- Marker for the beginning of a statement to print a variable in Jinja2.
type: str
type: dict
backup_name:
description: Name of the backup file or data set that was created.
returned: if backup=true or backup_name=true
sample: /path/to/file.txt.2015-02-03@04:15~
type: str
checksum:
description: SHA256 checksum of the file after running zos_copy.
returned: When ``validate=true`` and if ``dest`` is USS
sample: 8d320d5f68b048fc97559d771ede68b37a71e8374d1d678d96dcfa2b2da7a64e
type: str
cmd:
description: The MVS command issued, if applicable.
returned: failure
sample: REPRO INDATASET(SAMPLE.DATA.SET) OUTDATASET(SAMPLE.DEST.DATA.SET)
type: str
dest:
description: Destination file/path or data set name.
returned: success
sample: SAMPLE.SEQ.DATA.SET
type: str
dest_created:
description: Indicates whether the module created the destination.
returned: success and if dest was created by the module.
sample: true
type: bool
destination_attributes:
contains:
block_size:
description: Block size of the dataset.
sample: 32760
type: int
record_format:
description: Record format of the dataset.
sample: FB
type: str
record_length:
description: Record length of the dataset.
sample: 45
type: int
space_primary:
description: Allocated primary space for the dataset.
sample: 2
type: int
space_secondary:
description: Allocated secondary space for the dataset.
sample: 1
type: int
space_type:
description: Unit of measurement for space.
sample: K
type: str
type:
description: Type of dataset allocated.
sample: PDSE
type: str
description: Attributes of a dest created by the module.
returned: success and destination was created by the module.
sample:
block_size: 32760
record_format: FB
record_length: 45
space_primary: 2
space_secondary: 1
space_type: K
type: PDSE
type: dict
gid:
description: Group id of the file, after execution.
returned: success and if dest is USS
sample: 100
type: int
group:
description: Group of the file, after execution.
returned: success and if dest is USS
sample: httpd
type: str
mode:
description: Permissions of the target, after execution.
returned: success and if dest is USS
sample: 420
type: str
msg:
description: Failure message returned by the module.
returned: failure
sample: Error while gathering data set information
type: str
note:
description: A note to the user after module terminates.
returned: When ``force=true`` and ``dest`` exists
sample: No data was copied
type: str
owner:
description: Owner of the file, after execution.
returned: success and if dest is USS
sample: httpd
type: str
rc:
description: The return code of a USS or MVS command, if applicable.
returned: failure
sample: 8
type: int
size:
description: Size(in bytes) of the target, after execution.
returned: success and dest is USS
sample: 1220
type: int
src:
description: Source file or data set being copied.
returned: changed
sample: /path/to/source.log
type: str
state:
description: State of the target, after execution.
returned: success and if dest is USS
sample: file
type: str
stderr:
description: The stderr of a USS command or MVS command, if applicable.
returned: failure
sample: No such file or directory "/tmp/foo"
type: str
stderr_lines:
description: List of strings containing individual lines from stderr.
returned: failure
sample:
- u"FileNotFoundError: No such file or directory '/tmp/foo'"
type: list
stdout:
description: The stdout from a USS command or MVS command, if applicable.
returned: failure
sample: Copying local file /tmp/foo/src to remote path /tmp/foo/dest
type: str
stdout_lines:
description: List of strings containing individual lines from stdout.
returned: failure
sample:
- u"Copying local file /tmp/foo/src to remote path /tmp/foo/dest.."
type: list
uid:
description: Owner id of the file, after execution.
returned: success and if dest is USS
sample: 100
type: int