Try SpotterFetch z/OS data set or member from z/OS
| "added in version" 2.9 of ibm.ibm_zos_zosmf"
Authors: Yang Cao (@zosmf-Young), Yun Juan Yang (@zosmf-Robyn)
preview | supported by community
Install with ansible-galaxy collection install ibm.ibm_zos_zosmf:==3.0.1
collections:
- name: ibm.ibm_zos_zosmf
version: 3.0.1Retrieve the contents of a sequential data set, or a member of a partitioned data set (PDS or PDSE) from z/OS system.
Save the retrieved data set or member on Ansible control node.
Data set or member that already exists at I(dataset_dest) will be overwritten if it is different than the I(dataset_src).
- name: Fetch a data set and store in /tmp/dataset/sample.ibm.com/ZOSMF.ANSIBLE.PS
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PS"
dataset_dest: "/tmp/dataset"
- name: Fetch a PDS member and store in /tmp/dataset/ZOSMF.ANSIBLE.PDS/MEMBER
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PDS(MEMBER)"
dataset_dest: "/tmp/dataset"
dataset_flat: true
- name: Fetch an uncataloged PDS member and store in /tmp/dataset/sample.ibm.com/ZOSMF.ANSIBLE.PDS/MEMBER
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PDS(MEMBER)"
dataset_volser: "VOL001"
dataset_dest: "/tmp/dataset"
- name: Fetch a data set as binary
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PS"
dataset_dest: "/tmp/dataset"
dataset_data_type: "binary"
- name: Fetch a data set in record format
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PS"
dataset_dest: "/tmp/dataset"
dataset_data_type: "record"
- name: Fetch a data set and convert it from IBM-037 to ISO8859-1
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PS"
dataset_dest: "/tmp/dataset"
dataset_encoding:
from: IBM-037
to: ISO8859-1
- name: Fetch a range of records from a data set (the first 500 lines)
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PS"
dataset_dest: "/tmp/dataset"
dataset_range:
start: 0
end: 499
- name: Fetch a range of records from a data set (the final 500 lines)
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PS"
dataset_dest: "/tmp/dataset"
dataset_range:
end: 500
- name: Fetch 100 lines of records from the first matched line that contains "ansible" in a data set
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PS"
dataset_dest: "/tmp/dataset"
dataset_search:
keyword: "ansible"
maxreturnsize: 100
- name: Fetch a data set and validate its checksum
zmf_dataset_fetch:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.PS"
dataset_dest: "/tmp/dataset"
dataset_checksum: "93822124D6E66E2213C64B0D10800224"
zmf_crt:
default: null
description:
- Location of the PEM-formatted certificate chain file to be used for HTTPS client
authentication.
- If I(zmf_credential) is supplied, I(zmf_crt) is ignored.
- If I(zmf_credential) is not supplied, I(zmf_crt) is required when I(zmf_user) and
I(zmf_password) are not supplied.
required: false
type: str
zmf_key:
default: null
description:
- Location of the PEM-formatted file with your private key to be used for HTTPS client
authentication.
- If I(zmf_credential) is supplied, I(zmf_key) is ignored.
- If I(zmf_credential) is not supplied, I(zmf_key) is required when I(zmf_user) and
I(zmf_password) are not supplied.
required: false
type: str
zmf_host:
default: null
description:
- Hostname of the z/OSMF server.
- If I(zmf_credential) is supplied, I(zmf_host) is ignored.
- If I(zmf_credential) is not supplied, I(zmf_host) is required.
required: false
type: str
zmf_port:
default: null
description:
- Port number of the z/OSMF server.
- If I(zmf_credential) is supplied, I(zmf_port) is ignored.
required: false
type: int
zmf_user:
default: null
description:
- User name to be used for authenticating with z/OSMF server.
- If I(zmf_credential) is supplied, I(zmf_user) is ignored.
- If I(zmf_credential) is not supplied, I(zmf_user) is required when I(zmf_crt) and
I(zmf_key) are not supplied.
- If I(zmf_credential) is not supplied and I(zmf_crt) and I(zmf_key) are supplied,
I(zmf_user) and I(zmf_password) are ignored.
required: false
type: str
dataset_src:
description:
- Data set or the name of the PDS or PDSE member on z/OS system to fetch.
- This variable must consist of a fully qualified data set name. The length of the
data set name cannot exceed 44 characters.
- For example, specifying a data set like C(ZOSMF.ANSIBLE.PS), or a PDS or PDSE member
like ``ZOSMF.ANSIBLE.PDS(MEMBER)``.
required: true
type: str
dataset_dest:
description:
- The local directory on control node where the data set or member should be saved
to. For example, C(/tmp/dataset).
- This directory can be absolute or relative. The module will fail if the parent directory
of I(dataset_dest) is a read-only file system.
- The directory C({{ dataset_dest }}/{{ zmf_host }}/) will be created to save the
data set, where I(zmf_host) is the hostname of the z/OSMF server.
- If I(zmf_host=zosmf.ibm.com), a data set named C(ZOSMF.ANSIBLE.PS) would be saved
into C({{dataset_dest}}/zosmf.ibm.com/ZOSMF.ANSIBLE.PS).
- If I(dataset_volser=VOL001), the above data set would be saved into C({{dataset_dest}}/zosmf.ibm.com/VOL001/ZOSMF.ANSIBLE.PS).
required: true
type: str
dataset_flat:
default: false
description:
- Specifies whether to override the default behavior of appending I(zmf_host) to the
destination.
- If I(dataset_flat=true), the data set will be fetched to the destination directory
using its name without appending I(zmf_host).
- For example, if I(dataset_dest=/tmp/dataset), a data set named C(ZOSMF.ANSIBLE.PS)
would be saved into C(/tmp/dataset/ZOSMF.ANSIBLE.PS).
required: false
type: bool
zmf_password:
default: null
description:
- Password to be used for authenticating with z/OSMF server.
- If I(zmf_credential) is supplied, I(zmf_password) is ignored.
- If I(zmf_credential) is not supplied, I(zmf_password) is required when I(zmf_crt)
and I(zmf_key) are not supplied.
- If I(zmf_credential) is not supplied and I(zmf_crt) and I(zmf_key) are supplied,
I(zmf_user) and I(zmf_password) are ignored.
required: false
type: str
dataset_range:
default: null
description:
- Specifies a range that is used to retrieve records of the data set.
- If this variable is specified, only the retrieved range of the data set will be
fetched to the destination directory.
- The retrieved range of the data set will be saved as C({{ dataset_dest }}/{{ zmf_host
}}/{{ dataset_src }}.range) on control node.
- For example, the retrieved range of the dat set named C(ZOSMF.ANSIBLE.PS) would
be saved as C(/tmp/dataset/ZOSMF.ANSIBLE.PS.range).
required: false
suboptions:
end:
description:
- This variable identifies the end record in the range to be retrieved.
- If this value is omitted or is set to 0, the range extends to the end of the
data set.
required: false
type: int
start:
description:
- This variable identifies the start record in the range to be retrieved.
- If this value is omitted, a tail range is returned.
required: false
type: int
type: dict
dataset_search:
default: null
description:
- Specifies a series of parameters that are used to search the content of data set.
- This variable only take effects when I(dataset_data_type=text).
- If this variable is specified, only the matched records in the data set will be
fetched to the destination directory.
- Records are returned starting with the first matching record. The I(dataset_range)
may be used to specify the range of records to be searched.
- The matched contents in the data set will be saved as C({{ dataset_dest }}/{{ zmf_host
}}/{{ dataset_src }}.search) on control node.
- For example, the matched contents in the data set named C(ZOSMF.ANSIBLE.PS) would
be saved as C(/tmp/dataset/ZOSMF.ANSIBLE.PS.search).
required: false
suboptions:
insensitive:
default: true
description:
- Specifies whether the comparison of I(keyword) is case insensitive.
- This variable only take effects when I(keyword) is defined.
required: false
type: bool
keyword:
default: null
description:
- Specifies a string or a regular expression that is used to search the data set.
required: false
type: str
maxreturnsize:
default: 100
description:
- The maximum number of records to return.
- This variable only take effects when I(keyword) is defined.
required: false
type: int
type: dict
dataset_volser:
default: null
description:
- The volume serial to identify the volume to be searched for an uncataloged data
set or member.
- The length of the volume serial cannot exceed six characters. Wildcard characters
are not supported. Indirect volume serials are not supported.
required: false
type: str
zmf_credential:
default: null
description:
- Authentication credentials, returned by module C(zmf_authenticate), for the successful
authentication with z/OSMF server.
- If I(zmf_credential) is supplied, I(zmf_host), I(zmf_port), I(zmf_user), I(zmf_password),
I(zmf_crt) and I(zmf_key) are ignored.
required: false
suboptions:
LtpaToken2:
default: null
description:
- The value of Lightweight Third Party Access (LTPA) token, which supports strong
encryption.
- If I(jwtToken) is not supplied, I(LtpaToken2) is required.
required: false
type: str
jwtToken:
default: null
description:
- The value of JSON Web token, which supports strong encryption.
- If I(LtpaToken2) is not supplied, I(jwtToken) is required.
required: false
type: str
zmf_host:
description: Hostname of the z/OSMF server.
required: true
type: str
zmf_port:
default: null
description: Port number of the z/OSMF server.
required: false
type: int
type: dict
dataset_checksum:
default: null
description:
- Specifies the checksum to be used to verify that the data set to be fetched is not
changed since the checksum was generated.
- If the checksum is matched which means the data set is not changed, the content
of the data set won't be fetched.
required: false
type: str
dataset_encoding:
default: null
description:
- Specifies which encodings the fetched data set should be converted from and to.
- This variable only take effects when I(dataset_data_type=text).
required: false
suboptions:
from:
description:
- The character set of the source data set. Select an alternate EBCDIC code page.
required: true
type: str
to:
description:
- The destination character set for the output to be written as.
required: true
type: str
type: dict
dataset_data_type:
choices:
- text
- binary
- record
default: text
description:
- Specifies whether data conversion is to be performed on the returned data.
- When I(dataset_data_type=text), data conversion is performed.
- You can use I(dataset_encoding) to specify which encodings the fetched data set
should be converted from and to.
- A newline (NL) character is inserted between logical records. For data set with
fixed-length records, trailing blanks are removed.
- If I(dataset_encoding) is not supplied, the data transfer process converts each
record from C(IBM-1047) to C(ISO8859-1) by default.
- When I(dataset_data_type=binary), no data conversion is performed.
- The data transfer process returns each line of data as-is, without translation.
No delimiters are added between records.
- When I(dataset_data_type=record), no data conversion is performed.
- Each logical record is preceded by the 4-byte big endian record length of the record
that follows. This length doesn't include the prefix length.
- For example, a zero-length record is 4 bytes of zeros with nothing following.
required: false
type: str
dataset_migrate_recall:
choices:
- wait
- nowait
- error
default: wait
description:
- Specifies how a migrated data set is handled.
- When I(dataset_migrate_recall=wait), the migrated data set is recalled synchronously.
- When I(dataset_migrate_recall=nowait), request the migrated data set to be recalled,
but do not wait.
- When I(dataset_migrate_recall=error), do not attempt to recall the migrated data
set.
required: false
type: str
changed:
description: Indicates if any change is made on managed node during the module operation.
returned: always
type: bool
dataset_checksum:
description: The checksum of the fetched data set
returned: on success when I(dataset_search) and I(dataset_range) are not specified
sample: 93822124D6E66E2213C64B0D10800224
type: str
dataset_content:
description: The retrieved content of the data set.
returned: on success when I(dataset_data_type=text)
sample:
- First line of the data set
- Second line of the data set
type: list
dataset_matched_content:
description: The matched content in the data set with the specified search keyword.
returned: on success when I(dataset_data_type=text) and I(dataset_search) is specified
sample:
- First line of the data set
type: list
dataset_matched_range:
description:
- The range of the matched contents of the data set with the specified search keyword.
- Return I(dataset_matched_range=p,q), where I(p) is the first matched line in the
data set and I(q) is the number of lines returned.
returned: on success when I(dataset_data_type=text) and I(dataset_search) is specified
sample: 0,500
type: str
message:
description: The output message generated by the module to indicate whether the
data set or member is successfully fetched.
returned: on success
sample:
sample1: 'The data set ZOSMF.ANSIBLE.PDS(MEMBER) is fetched successfully and saved
in: /tmp/dataset/ZOSMF.ANSIBLE.PDS/MEMBER.'
sample2: 'The matched contents in the data set ZOSMF.ANSIBLE.PDS(MEMBER) is fetched
successfully and saved in: /tmp/dataset/ZOSMF.ANSIBLE.PDS/MEMBER.serarch.'
sample3: The data set ZOSMF.ANSIBLE.PDS(MEMBER) is not fetched since no matched
contents is found with the specified search keyword.
sample4: 'A range of records in the data set ZOSMF.ANSIBLE.PDS(MEMBER) is fetched
successfully and saved in: /tmp/dataset/ZOSMF.ANSIBLE.PDS/MEMBER.range.'
sample6: The data set ZOSMF.ANSIBLE.PDS(MEMBER) is not fetched since no contents
is returned in the specified range.
sample7: The data set ZOSMF.ANSIBLE.PDS(MEMBER) is not fetched since it is not
changed.
type: str