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.
MVS data sets supported types are:
SEQ
,PDS
,PDSE
.VSAMs are not supported.
required: Truetype: listelements: str- format
The compression type and corresponding options to use when archiving data.
required: Falsetype: dict- name
The compression format to use.
required: Falsetype: strdefault: gzchoices: bz2, gz, tar, zip, terse, xmit, pax- format_options
Options specific to a compression format.
required: Falsetype: 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: Falsetype: strchoices: 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: Falsetype: 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 usingxmit
orterse
.required: Falsetype: booldefault: 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.
required: Truetype: str- exclude
Remote absolute path, glob, or list of paths, globs or data set name patterns 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.
required: Falsetype: listelements: 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: Falsetype: 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
or01777
)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: Falsetype: 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: Falsetype: 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: Falsetype: booldefault: False- dest_data_set
Data set attributes to customize a
dest
data set to be archived into.required: Falsetype: dict- name
Desired name for destination dataset.
required: Falsetype: str- type
Organization of the destination
required: Falsetype: strdefault: SEQchoices: 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: Falsetype: 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: Falsetype: 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
, andTRK
.required: Falsetype: strchoices: 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-insensitive.
required: Falsetype: strchoices: 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: Falsetype: int- block_size
The block size to use for the data set.
required: Falsetype: int- directory_blocks
The number of directory blocks to allocate to the data set.
required: Falsetype: 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: Falsetype: 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: Falsetype: 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: Falsetype: 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: Falsetype: str- force
If set to
true
and the remote file or data setdest
will be deleted. Otherwise it will be created with thedest_data_set
attributes or default values ifdest_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: Falsetype: booldefault: False
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: Compress 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: Compress 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: Compress 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: Compress data set pattern using xmit
zos_archive:
src: "USER.ARCHIVE.*"
exclude_sources: "USER.ARCHIVE.EXCLUDE.*"
dest: "USER.ARCHIVE.RESULT.XMIT"
format:
name: xmit
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
whenremove
was true and the source files or data sets were not removed.returned: alwaystype: 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: successtype: str- missing
Any files or data sets that were missing from the source.
returned: successtype: list- archived
Any files or data sets that were compressed or added to the archive.
returned: successtype: 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: alwaystype: str- expanded_sources
The list of matching paths from the src option.
returned: alwaystype: list- expanded_exclude_sources
The list of matching exclude paths from the exclude option.
returned: alwaystype: list