zos_unarchive – Unarchive files and data sets in z/OS.

Synopsis 

The zos_unarchive module unpacks an archive after optionally transferring it to the remote system.
For supported archive formats, see option format.
Supported sources are USS (UNIX System Services) or z/OS data sets.
Mixing MVS data sets with USS files for unarchiving is not supported.
The archive is sent to the remote as binary, so no encoding is performed.

Parameters 

src

The remote absolute path or data set of the archive to be uncompressed.

src can be a USS file or MVS data set name.

USS file paths should be absolute paths.

MVS data sets supported types are SEQ, PDS, PDSE.

GDS relative names are supported. e.g. USER.GDG(-1).

required: True

type: str

format

The compression type and corresponding options to use when archiving data.

required: True

type: dict

name

The compression format used while archiving.

required: True
type: str
choices: bz2, gz, tar, zip, terse, xmit, pax

format_options

Options specific to a compression format.

required: False

type: dict

xmit_log_data_set

Provide the name of a data set to store xmit log output.

If the data set provided does not exist, the program will create it.

If the data set provided exists, the data set must have the following attributes: LRECL=255, BLKSIZE=3120, and RECFM=VB

When providing the xmit_log_data_set name, ensure there is adequate space.

required: False

type: str

use_adrdssu

If set to true, the zos_unarchive module will use Data Facility Storage Management Subsystem data set services (DFSMSdss) program ADRDSSU to uncompress data sets from a portable format after using xmit or terse.

required: False
type: bool
default: False

dest_volumes

When use_adrdssu=True, specify the volume the data sets will be written to.

If no volume is specified, storage management rules will be used to determine the volume where the file will be unarchived.

If the storage administrator has specified a system default unit name and you do not set a 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: list
elements: str

dest

The remote absolute path or data set where the content should be unarchived to.

dest can be a USS file, directory or MVS data set name.

If dest has missing parent directories, they will not be created.

required: False

type: str

group

Name of the group that will own the file system objects.

When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership.

This option is only applicable if dest is USS, otherwise ignored.

required: False

type: str

mode

The permission of the uncompressed files.

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.

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

required: False

type: str

owner

Name of the user that should own the filesystem object, as would be passed to the chown command.

When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership.

required: False

type: str

include

A list of directories, files or data set names to extract from the archive.

GDS relative names are supported. e.g. USER.GDG(-1).

When include is set, only those files will we be extracted leaving the remaining files in the archive.

Mutually exclusive with exclude.

required: False
type: list
elements: str

exclude

List the directory and file or data set names that you would like to exclude from the unarchive action.

GDS relative names are supported. e.g. USER.GDG(-1).

Mutually exclusive with include.

required: False
type: list
elements: str

list

Will list the contents of the archive without unpacking.

required: False
type: bool
default: False

dest_data_set

Data set attributes to customize a dest data set that the archive will be copied into.

required: False

type: dict

name

Desired name for destination dataset.

required: False

type: str

type

Organization of the destination

required: False
type: str
default: seq
choices: seq, pds, pdse

space_primary

If the destination dest data set does not exist , this sets the primary space allocated for the data set.

The unit of space used is set using space_type.

required: False

type: int

space_secondary

If the destination dest data set does not exist , this sets the secondary space allocated for the data set.

The unit of space used is set using space_type.

required: False

type: int

space_type

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 k, m, g, cyl, and trk.

required: False
type: str
choices: k, m, g, cyl, trk

record_format

If the destination data set does not exist, this sets the format of the data set. (e.g fb)

Choices are case-sensitive.

required: False
type: str
choices: fb, vb, fba, vba, u

record_length

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

block_size

The block size to use for the data set.

required: False

type: int

directory_blocks

The number of directory blocks to allocate to the data set.

required: False

type: int

key_offset

The key offset to use when creating a KSDS data set.

key_offset is required when type=ksds.

key_offset should only be provided when type=ksds

required: False

type: int

key_length

The key length to use when creating a KSDS data set.

key_length is required when type=ksds.

key_length should only be provided when type=ksds

required: False

type: int

sms_storage_class

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

sms_data_class

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

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

tmp_hlq

Override the default high level qualifier (HLQ) for temporary data sets.

The default HLQ is the Ansible user used to execute the module and if that is not available, then the environment variable value TMPHLQ is used.

required: False

type: str

force

If set to true and the remote file or data set dest exists, the dest will be deleted.

required: False
type: bool
default: False

remote_src

If set to true, zos_unarchive retrieves the archive from the remote system.

If set to false, zos_unarchive searches the local machine (Ansible controller) for the archive.

required: False
type: bool
default: False

encoding

Specifies the character encoding conversion to be applied to the destination files after unarchiving.

Supported character sets rely on the charset conversion utility iconv version the most common character sets are supported.

After conversion the files are stored in same location as they were unarchived to under the same original name. No backup of the original unconverted files is there as for that unarchive can be executed again without encoding params on same source archive files.

Destination files will be converted to the new encoding and will not be restored to their original encoding.

If encoding fails for any file in a set of multiple files, an exception will be raised and the name of the file skipped will be provided completing the task successfully with rc code 0.

Encoding does not check if the file is already present or not. It works on the file/files successfully unarchived.

required: False

type: dict

from: The character set of the source src.

required: False

type: str
to: The destination dest character set for the files to be written as.

required: False

type: str
skip_encoding: List of names to skip encoding after unarchiving. This is only used if encoding is set, otherwise is ignored.

required: False

type: list

elements: str

Attributes 

action: support: full

description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
async: support: full

description: Supports being used with the async keyword.
check_mode: support: full

description: Can run in check_mode and return changed status prediction without modifying target. If not supported, the action will be skipped.

Examples 

# Simple extract
- name: Copy local tar file and unpack it on the managed z/OS node.
  zos_unarchive:
    src: "./files/archive_folder_test.tar"
    format:
      name: tar

# use include
- name: Unarchive a bzip file selecting only a file to unpack.
  zos_unarchive:
    src: "/tmp/test.bz2"
    format:
      name: bz2
    include:
      - 'foo.txt'

# Use exclude
- name: Unarchive a terse data set and excluding data sets from unpacking.
  zos_unarchive:
    src: "USER.ARCHIVE.RESULT.TRS"
    format:
      name: terse
    exclude:
      - USER.ARCHIVE.TEST1
      - USER.ARCHIVE.TEST2

# Unarchive a GDS
- name: Unarchive a terse data set and excluding data sets from unpacking.
  zos_unarchive:
    src: "USER.ARCHIVE(0)"
    format:
      name: terse

# List option
- name: List content from XMIT
  zos_unarchive:
    src: "USER.ARCHIVE.RESULT.XMIT"
    format:
      name: xmit
      format_options:
        use_adrdssu: true
    list: true

# Encoding example
- name: Encode the destination data set into Latin-1 after unarchiving.
  zos_unarchive:
    src: "USER.ARCHIVE.RESULT.TRS"
    format:
      name: terse
    encoding:
      from: IBM-1047
      to: ISO8859-1

- name: Encode the destination data set into Latin-1 after unarchiving.
  zos_unarchive:
    src: "USER.ARCHIVE.RESULT.TRS"
    format:
      name: terse
    encoding:
      from: IBM-1047
      to: ISO8859-1
      skip_encoding:
        - USER.ARCHIVE.TEST1

Notes 

Note

VSAMs are not supported.

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.

Return Values 

src: File path or data set name unpacked.

returned: always

type: str
dest_path: Destination path where archive was unpacked.

returned: always

type: str
targets: List of files or data sets in the archive.

returned: success

type: list

elements: str
missing: Any files or data sets not found during extraction.

returned: success

type: str
encoded: List of files or data sets that were successfully encoded.

returned: success

type: list
failed_on_encoding: List of files or data sets that were failed while encoding.

returned: success

type: list
skipped_encoding_targets: List of files or data sets that were skipped while encoding.

returned: success

type: list

zos_unarchive – Unarchive files and data sets in z/OS.

Synopsis

Parameters

Attributes

Examples

Notes

See Also

Return Values

Synopsis 

Parameters 

Attributes 

Examples 

Notes 

See Also 

Return Values 