zos_archive – Archive files and data sets on z/OS.

Synopsis 

Create or extend an archive on a remote z/OS system.
Sources for archiving must be on the remote z/OS system.
Supported sources are USS (UNIX System Services) or z/OS data sets.
The archive remains on the remote z/OS system.
For supported archive formats, see option format.

Parameters 

src

List of names or globs of UNIX System Services (USS) files, PS (sequential data sets), PDS, PDSE to compress or archive.

USS file paths should be absolute paths.

GDS relative notation is supported.

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

VSAMs are not supported.

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

required: True
type: list
elements: str

format

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

required: False

type: dict

name

The compression format to use.

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

format_options

Options specific to a compression format.

required: False

type: dict

terse_pack

Compression option for use with the terse format, name=terse.

Pack will compress records in a data set so that the output results in lossless data compression.

Spack will compress records in a data set so the output results in complex data compression.

Spack will produce smaller output and take approximately 3 times longer than pack compression.

required: False
type: str
choices: pack, spack

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_archive module will use Data Facility Storage Management Subsystem data set services (DFSMSdss) program ADRDSSU to compress data sets into a portable format before using xmit or terse.

required: False
type: bool
default: False

dest

The remote absolute path or data set where the archive should be created.

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

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

If dest is a nonexistent USS file, it will be created.

If dest is an existing file or data set and force=true, the existing dest will be deleted and recreated with attributes defined in the dest_data_set option or computed by the module.

If dest is an existing file or data set and force=false or not specified, the module exits with a note to the user.

Destination data set attributes can be set using dest_data_set.

Destination data set space will be calculated based on space of source data sets provided and/or found by expanding the pattern name. Calculating space can impact module performance. Specifying space attributes in the dest_data_set option will improve performance.

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

required: True

type: str

exclude

Remote absolute path, glob, or list of paths, globs, data set name patterns or generation data sets (GDSs) in relative notation for the file, files or data sets to exclude from src list and glob expansion.

Patterns (wildcards) can contain one of the following, ?, *.

matches everything.

? matches any single character.

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

required: False
type: list
elements: str

group

Name of the group that will own the archive file.

When left unspecified, it uses the current group of the current use 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 destination archive file.

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 src file.

required: False

type: str

owner

Name of the user that should own the archive file, 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.

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

required: False

type: str

remove

Remove any added source files , trees or data sets after module zos_archive adds them to the archive. Source files, trees and data sets are identified with option src.

required: False
type: bool
default: False

dest_data_set

Data set attributes to customize a dest data set to be archived 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

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

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 will be deleted. Otherwise it will be created with the dest_data_set attributes or default values if dest_data_set is not specified.

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
default: False

encoding

Specifies the character encoding conversion to be applied to the source files before archiving.

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 and name as src and the same src is taken in consideration for archive.

Source 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 archiving will be skipped.

The original files in src will be converted. The module will revert the encoding conversion after a successful archive, but no backup will be created. If you need to encode using a backup and then archive take a look at zos_encode module.

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 before archiving. This is only used if encoding is set, otherwise is ignored.

required: False

type: list

elements: str

Attributes 

action: support: none

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 archive
- name: Archive file into a tar
  zos_archive:
    src: /tmp/archive/foo.txt
    dest: /tmp/archive/foo_archive_test.tar
    format:
      name: tar

# Archive multiple files
- name: Archive list of files into a zip
  zos_archive:
    src:
      - /tmp/archive/foo.txt
      - /tmp/archive/bar.txt
    dest: /tmp/archive/foo_bar_archive_test.zip
    format:
    name: zip

# Archive one data set into terse
- name: Archive data set into a terse
  zos_archive:
    src: "USER.ARCHIVE.TEST"
    dest: "USER.ARCHIVE.RESULT.TRS"
    format:
      name: terse

# Use terse with different options
- name: Archive data set into a terse, specify pack algorithm and use adrdssu
  zos_archive:
    src: "USER.ARCHIVE.TEST"
    dest: "USER.ARCHIVE.RESULT.TRS"
    format:
      name: terse
      format_options:
        terse_pack: "spack"
        use_adrdssu: true

# Use a pattern to store
- name: Archive data set pattern using xmit
  zos_archive:
    src: "USER.ARCHIVE.*"
    exclude_sources: "USER.ARCHIVE.EXCLUDE.*"
    dest: "USER.ARCHIVE.RESULT.XMIT"
    format:
      name: xmit

- name: Archive multiple GDSs into a terse
  zos_archive:
    src:
      - "USER.GDG(0)"
      - "USER.GDG(-1)"
      - "USER.GDG(-2)"
    dest: "USER.ARCHIVE.RESULT.TRS"
    format:
      name: terse
      format_options:
        use_adrdssu: true

- name: Archive multiple data sets into a new GDS
  zos_archive:
    src: "USER.ARCHIVE.*"
    dest: "USER.GDG(+1)"
    format:
      name: terse
      format_options:
        use_adrdssu: true

- name: Encode the source data set into Latin-1 before archiving into a terse data set
  zos_archive:
    src: "USER.ARCHIVE.TEST"
    dest: "USER.ARCHIVE.RESULT.TRS"
    format:
      name: terse
    encoding:
      from: IBM-1047
      to: ISO8859-1

- name: Encode and archive multiple data sets but skip encoding for a few.
  zos_archive:
    src:
      - "USER.ARCHIVE1.TEST"
      - "USER.ARCHIVE2.TEST"
    dest: "USER.ARCHIVE.RESULT.TRS"
    format:
      name: terse
      format_options:
        use_adrdssu: true
    encoding:
      from: IBM-1047
      to: ISO8859-1
      skip_encoding:
        - "USER.ARCHIVE2.TEST"

Notes 

Note

This module does not perform a send or transmit operation to a remote node. If you want to transport the archive you can use zos_fetch to retrieve to the controller and then zos_copy or zos_unarchive for copying to a remote or send to the remote and then unpack the archive respectively.

When packing and using use_adrdssu flag the module will take up to two times the space indicated in dest_data_set.

tar, zip, bz2 and pax are archived using python tarfile library which uses the latest version available for each format, for compatibility when opening from system make sure to use the latest available version for the intended format.

Return Values 

state

The state of the input src.

absent when the source files or data sets were removed.

present when the source files or data sets were not removed.

incomplete when remove was true and the source files or data sets were not removed.

returned: always

type: str

dest_state

The state of the dest file or data set.

absent when the file does not exist.

archive when the file is an archive.

compress when the file is compressed, but not an archive.

incomplete when the file is an archive, but some files under src were not found.

returned: success

type: str

missing

Any files or data sets that were missing from the source.

returned: success

type: list

archived

Any files or data sets that were compressed or added to the archive.

returned: success

type: list

arcroot

If src is a list of USS files, this returns the top most parent folder of the list of files, otherwise is empty.

returned: always

type: str

expanded_sources

The list of matching paths from the src option.

returned: always

type: list

expanded_exclude_sources

The list of matching exclude paths from the exclude option.

returned: always

type: list

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_archive – Archive files and data sets on z/OS.

Synopsis

Parameters

Attributes

Examples

Notes

See Also

Return Values

Synopsis 

Parameters 

Attributes 

Examples 

Notes 

See Also 

Return Values 