zos_copy – Copy data to z/OS

Synopsis

  • The 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 zos_fetch module to copy files or data sets from remote locations to the local machine.

Parameters

backup

Specifies whether a backup of destination should be created before copying data.

When set to 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
backup_file

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_file 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_file name must be an MVS data set name.

If the backup_file is not provided, the default backup_file 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. /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 dest is a data set member and backup_file 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
content

When used instead of src, sets the contents of a file or data set directly to the specified value.

Works only when 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 https://docs.ansible.com/ansible/latest/modules/copy_module.html

If dest is a directory, then content will be copied to /path/to/dest/inline_copy.

required: False
type: str
dest

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 dest is a nonexistent USS file, it will be created.

If dest is a nonexistent data set, it will be allocated.

If src and dest are files and if the parent directory of dest does not exist, then the task will fail.

When the dest is an existing VSA:ref:KSDS <KSDS_module> or VSA:ref:ESDS <ESDS_module>, then source can be ESDS, KSDS or RRDS.

When the dest is an existing VSA:ref:RRDS <RRDS_module>, then the source must be RRDS.

When dest is and existing VSA:ref:LDS <LDS_module>, then source must be LDS.

required: True
type: str
encoding

Specifies which encodings the destination file or data set should be converted from and to.

If encoding is not provided, no encoding conversions will take place.

If encoding is provided and src is an MVS data set, task will fail.

Only valid if is_binary is false.

required: False
type: dict
from

The encoding to be converted from

required: True
type: str
to

The encoding to be converted to

required: True
type: str
force

If set to true, the remote file or data set will be overwritten.

If set to false, the file or data set will only be copied if the destination does not exist.

If set to false and destination exists, the module exits with a note to the user.

required: False
type: bool
is_binary

If set to true, indicates that the file or data set to be copied is a binary file/data set.

required: False
type: bool
local_follow

This flag indicates that any existing filesystem links in the source tree should be followed.

required: False
type: bool
default: True
mode

The permission of the destination file or directory.

If 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 0644 or 01777)or quote it (like '644' or '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.

preserve means that the file will be given the same permissions as the source file.

required: False
type: str
model_ds

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 src is a local file or directory and dest does not exist.

required: False
type: str
remote_src

If set to false, the module searches for src at the local machine.

If set to true, the module goes to the remote/target machine for src.

required: False
type: bool
src

Absolute local path to a file to copy to the remote z/OS system.

If remote_src is true, then src must be the absolute path to a UNIX System Services (USS) file, name of a data set, or data set member.

If src is a directory, destination must be a partitioned data set or a USS directory.

If 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 src is a VSAM data set, destination must also be a VSAM.

Required unless using content.

required: False
type: str
validate

Specifies whether to perform checksum validation for source and destination files.

Valid only for USS destination, otherwise ignored.

required: False
type: bool

Examples

- 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
    encoding:
      from: ISO8859-1
      to: IBM-1047

- 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
  zos_copy:
    src: /path/to/local/file
    dest: HLQ.SAMPLE.PDSE(MEMBER)

- 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
    encoding:
      from: ISO8859-1
      to: IBM-1047

- 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_file: /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

Notes

Note

Destination data sets are assumed to be in catalog. When trying to copy to an uncataloged data set, the module assumes that the data set does not exist and will create it.

Destination will be backed up if either backup is true or backup_file is provided. If backup is false but backup_file is provided, task will fail.

When copying local files or directories, 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 or directory being copied. Temporary files will always be deleted, regardless of success or failure of the copy task.

VSAM data sets can only be copied to other VSAM data sets.

For supported character sets used to encode data, refer to https://ansible-collections.github.io/ibm_zos_core/supplementary.html#encode

Return Values

src
Source file or data set being copied.
returned: changed
type: str
sample: /path/to/source.log
dest
Destination file/path or data set name.
returned: success
type: str
sample: SAMPLE.SEQ.DATA.SET
checksum
SHA256 checksum of the file after running zos_copy.
returned: C(validate) is C(true) and if dest is USS
type: str
sample: 8d320d5f68b048fc97559d771ede68b37a71e8374d1d678d96dcfa2b2da7a64e
backup_file
Name of the backup file or data set that was created.
returned: if backup=true or backup_file=true
type: str
gid
Group id of the file, after execution.
returned: success and if dest is USS
type: int
sample: 100
group
Group of the file, after execution.
returned: success and if dest is USS
type: str
sample: httpd
owner
Owner of the file, after execution.
returned: success and if dest is USS
type: str
sample: httpd
uid
Owner id of the file, after execution.
returned: success and if dest is USS
type: int
sample: 100
mode
Permissions of the target, after execution.
returned: success and if dest is USS
type: str
sample: 420
size
Size(in bytes) of the target, after execution.
returned: success and dest is USS
type: int
sample: 1220
state
State of the target, after execution.
returned: success and if dest is USS
type: str
sample: file
note
A note to the user after module terminates.
returned: C(force) is C(false) and dest exists
type: str
sample: No data was copied
msg
Failure message returned by the module.
returned: failure
type: str
sample: Error while gathering data set information
stdout
The stdout from a USS command or MVS command, if applicable.
returned: failure
type: str
sample: Copying local file /tmp/foo/src to remote path /tmp/foo/dest
stderr
The stderr of a USS command or MVS command, if applicable.
returned: failure
type: str
sample: No such file or directory “/tmp/foo”
stdout_lines
List of strings containing individual lines from stdout.
returned: failure
type: list
sample:
["u\"Copying local file /tmp/foo/src to remote path /tmp/foo/dest..\""]
stderr_lines
List of strings containing individual lines from stderr.
returned: failure
type: list
sample:
[{"u\"FileNotFoundError": "No such file or directory \u0027/tmp/foo\u0027\""}]
rc
The return code of a USS or MVS command, if applicable.
returned: failure
type: int
sample: 8
cmd
The MVS command issued, if applicable.
returned: failure
type: str
sample: REPRO INDATASET(SAMPLE.DATA.SET) OUTDATASET(SAMPLE.DEST.DATA.SET)