Try SpotterCopy data to z/OS
| "added in version" 1.0.0 of ibm.ibm_zos_core"
Authors: Asif Mahmud (@asifmahmud), Ivan Moreno (@rexemin), Demetrios Dimatos (@ddimatos)
This plugin has a corresponding action plugin.
Install with ansible-galaxy collection install ibm.ibm_zos_core:==1.3.6
collections:
- name: ibm.ibm_zos_core
version: 1.3.6The M(zos_copy) module copies a file or data set from a local or a remote machine to a location on the remote machine.
Use the M(zos_fetch) module to copy files or data sets from remote locations to the local 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
- 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
- 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
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, destination must be a partitioned data set or a USS directory.
- If C(src) is a file and dest ends with "/" or destination is a directory, the file
is copied to the directory with the same filename as src.
- If C(src) is a directory and ends with "/", the contents of it will be copied into
the root of C(dest). It it doesn't end with "/", the directory itself will be copied.
- If C(src) is a VSAM data set, destination 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:
- Remote absolute path or data set where the file should be copied to.
- Destination can be a USS path or an MVS data set name.
- If C(dest) is a nonexistent USS file, it will be created.
- If C(dest) is a nonexistent data set, storage management rules will be used to determine
the volume where C(dest) will be allocated.
- If C(src) and C(dest) are files and if the parent directory of C(dest) does not
exist, then the task will fail.
- When the C(dest) is an existing VSAM(KSDS) or VSAM(ESDS), then source can be ESDS,
KSDS or RRDS. The C(dest) will be deleted and storage management rules will be used
to determine the volume where C(dest) will be allocated.
- When the C(dest) is an existing VSAM(RRDS), then the source must be RRDS. The C(dest)
will be deleted and storage management rules will be used to determine the volume
where C(dest) will be allocated.
- When C(dest) is and existing VSAM(LDS), then source must be LDS. The C(dest) will
be deleted and storage management rules will be used to determine the volume where
C(dest) will be allocated.
- When C(dest) is a data set, you can override storage management rules by specifying
both C(volume) and C(model_ds).
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`.
- C(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), the remote file or data set will be overwritten.
- If set to C(true), when copying files or a directory to a USS destination, the copying
operation will continue if it encounters existing files or directories and overwrite
any corresponding files.
- If set to C(true) and the user is copying a directory to a destination in USS that
already has content in it, the files will be appended to the destination.
- 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 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.
- C(volume) must be used with C(model_ds), otherwise the C(volume) value is ignored.
- 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
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.
- This is for simple values; for anything complex or with formatting, use U(https://docs.ansible.com/ansible/latest/modules/copy_module.html)
- If C(dest) is a directory, then content will be copied to C(/path/to/dest/inline_copy).
required: false
type: str
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.
- If C(encoding) is provided and C(src) is an MVS data set, task will fail.
- 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
model_ds:
description:
- When copying a local file/directory to a non-existing PDS, PDSE or PS, specify a
model data set to allocate the destination after.
- If this parameter is not provided, the destination data set will be allocated based
on the size of the local file/directory.
- Only valid if C(src) is a local file or directory and C(dest) does not exist.
required: false
type: str
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/data set.
required: false
type: bool
sftp_port:
description:
- Indicates which port should be used to connect to the remote z/OS system to perform
data transfer.
- If this parameter is not specified, C(ansible_port) will be used.
- If C(ansible_port) is not specified, port 22 will be used.
required: false
type: int
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 (dest) is a USS file or path, the backup_name must be a file
or path name, and the USS path or file must be an absolute path name.
- If the destination is an MVS data set, the backup_name must be an MVS data set name.
- If the backup_name is not provided, the default backup_name will be used. If the
destination 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 destination is an MVS data set, it will be a data set with a random name
generated by calling the ZOAU API. The MVS backup data set recovery can be done
by renaming it.
- 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
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.
required: false
type: bool
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: C(validate) is C(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 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: C(force) is C(false) 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