zmf_dataset_copy – Copy data to z/OS data set or member¶
Synopsis¶
Copy data from Ansible control node to a sequential data set, or a member of a partitioned data set (PDS or PDSE) on z/OS system.
Copy file or data set from z/OS system to a data set or member on z/OS system.
If the target data set or member already exists, it can be overwritten.
If the target data set does not exist, it can be allocated based on dataset_create_like, the size of the local data, or the source data set.
If the target member does not exist, it can be created.
Parameters¶
- dataset_checksum
Specifies the checksum to be used to verify that the target data set to copy to is not changed since the checksum was generated.
The module will fail and no data will be copied if the checksum is not matched which means the target data set has been modified.
This variable only take effects when dataset_src_zos=false.
This variable only take effects when dataset_force=true.
required: Falsetype: str- dataset_content
The contents to be copied to the target data set or member. This variable is used instead of dataset_src.
This variable only take effects when dataset_src_zos=false.
This variable only take effects when dataset_data_type=text.
Each line of the contents should be terminated with
\n
. For example,Sample profile\nTZ=EST5EDT\n
.If dataset_content is supplied and dataset_data_type=text, dataset_src is ignored.
required: Falsetype: str- dataset_create_like
When copying a local data to a non-existing PDS, PDSE or PS, specify a model data set to allocate the target data set.
For example, specifying a model data set like
ZOSMF.ANSIBLE.MODEL
, member name should not be provided in this variable.This variable only take effects when dataset_src_zos=false.
If this variable is not supplied, the target data set will be allocated based on the size of the local data.
The primary extent tracks will be specified as 4 times the size of the local data specified by dataset_src or dataset_content.
If dataset_data_type=text, then
RECFM=FB
andLRECL=80
will be used to allocate the target data set.If dataset_data_type=binary or dataset_data_type=record, then
RECFM=U
will be used to allocate the target data set.required: Falsetype: str- dataset_crlf
Specifies whether each input text line is terminated with a carriage return line feed (CRLF) or a line feed (LF).
If dataset_crlf=true, CRLF characters are used.
This variable only take effects when dataset_src_zos=false.
This variable only take effects when dataset_data_type=text.
required: Falsetype: booldefault: false- dataset_data_type
Specifies whether data conversion is to be performed on the data to be copied.
This variable only take effects when dataset_src_zos=false.
When dataset_data_type=text, data conversion is performed.
You can use dataset_encoding to specify which encodings the data to be copied should be converted from and to.
Each line of data, delimited by a Line Feed (LF), is converted and written as a record to the target data set.
The LF character is removed and the data is padded with the space character to the end of the record if it is a fixed record size data set.
For variable record size data set, the record is written without padding.
the module will fail if the record size of the data set is smaller than any line of text since not all data was written.
If dataset_encoding is not supplied, the data transfer process converts each byte from
ISO8859-1
toIBM-1047
by default.You can use dataset_crlf to control whether each input text line is terminated with a carriage return line feed (CRLF) or a line feed (LF).
If dataset_crlf is not supplied, LF characters are left intact by default.
You can use dataset_diff to specify whether the input consists of commands in the same format as produced by the z/OS UNIX ‘diff -e’ command.
If dataset_diff is not supplied, the input is regarded as not consisting of commands by default.
When dataset_data_type=binary, no data conversion is performed.
The data is written to the data set without respect to record boundaries. All records will be written at their maximum record length.
For fixed length record data set, the last record will be padded with nulls if required.
When 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: Falsetype: strdefault: textchoices: text, binary, record- dataset_dest
Data set or the name of the PDS or PDSE member on z/OS system where the data should be copied to.
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
ZOSMF.ANSIBLE.PS
, or a PDS or PDSE member likeZOSMF.ANSIBLE.PDS(MEMBER)
.If dataset_src_zos=false, dataset_dest should be a sequential data set or a member of a partitioned data set on z/OS system. If dataset_dest does not exist, it will be allocated based on dataset_create_like if supplied, or the size of the local data.
If dataset_src_zos=true and dataset_src specifies a USS file, dataset_dest should be a sequential data set or a member of an existing partitioned data set on z/OS system. If dataset_dest specifies a nonexistent sequential data set, it will be allocated.
If dataset_src_zos=true and dataset_src specifies a sequential data set, dataset_dest should also be a sequential data set on z/OS system. If dataset_dest does not exist, it will be allocated based on dataset_src.
If dataset_src_zos=true and dataset_src specifies a partitioned data set, dataset_dest should also be a partitioned data set without specific member provided on z/OS system. If dataset_dest does not exist, it will be allocated based on dataset_src.
If dataset_src_zos=true and dataset_src specifies a member of a partitioned data set, dataset_dest should be an existing sequential data set or a member of a partitioned data set on z/OS system. If dataset_dest specifies a member of a nonexistent partitioned data set, it will be allocated based on dataset_src.
required: Truetype: str- dataset_dest_volser
The volume serial to identify the volume to be searched for an uncataloged target 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.
If this variable is provided and dataset_dest is a nonexistent data set, dataset_dest_volser must point to a volume on a 3390 device.
required: Falsetype: str- dataset_diff
Specifies whether the input consists of commands in the same format as produced by the z/OS UNIX ‘diff -e’ command.
These commands are used to add, replace and delete lines in the target data set. The following commands are supported.
a
c
d
s/.//
opt
g|<n>
, whereg
means global,n
means search and replacen
times.Each command may be optionally preceded by a line or line range, as allowed by the z/OS UNIX ‘ed’ command.
The module will fail if an error is detected while processing a command.
This variable only take effects when dataset_src_zos=false.
This variable only take effects when dataset_data_type=text.
required: Falsetype: booldefault: false- dataset_encoding
Specifies which encodings the data to be copied should be converted from and to.
This variable only take effects when dataset_src_zos=false.
This variable only take effects when dataset_data_type=text and dataset_diff=false.
required: Falsetype: dict- from
The character set of the data to be copied.
Supported character sets rely on the charset conversion utility (iconv) version. The most common character sets are supported.
required: Truetype: str- to
The destination character set for the target data set.
Supported character sets rely on the charset conversion utility (iconv) version. The most common character sets are supported.
required: Truetype: str
- dataset_force
Specifies whether the target data set must always be overwritten.
If dataset_force=true and dataset_checksum is not supplied, the target data set or member will always be overwritten.
If dataset_force=true and dataset_checksum is supplied, the target data set or member will be overwritten only when the checksum is matched.
If dataset_force=false, the source data will only be copied if the target data set or member does not exist.
required: Falsetype: booldefault: true- dataset_migrate_recall
Specifies how a migrated data set is handled.
When dataset_migrate_recall=wait, the migrated data set is recalled synchronously.
When dataset_migrate_recall=nowait, request the migrated data set to be recalled, but do not wait.
When dataset_migrate_recall=error, do not attempt to recall the migrated data set.
required: Falsetype: strdefault: waitchoices: wait, nowait, error- dataset_src
If dataset_src_zos=false, this variable specifies the local path on control node of the data to be copied to. For example,
/tmp/dataset_input/member01
. This path can be absolute or relative. The module will fail if dataset_src has no read permission. The data is interpreted as one of binary, text, record or ‘diff -e’ format according to the value of dataset_data_type and dataset_diff. If dataset_content is supplied and dataset_data_type=text, dataset_src is ignored.If dataset_src_zos=true, this variable specifies the source file or data set from z/OS system to be copied to. If this variable specifies the source file, it should be the absolute source file name, for example,
/etc/profile
. If this variable specifies the source data set, it should be the name of the data set or member, for example,ZOSMF.ANSIBLE.PS
orZOSMF.ANSIBLE.PDS(MEMBER)
. If the source data set is uncataloged, you can use dataset_src_volser to specify the volume of the uncataloged source data set.required: Falsetype: str- dataset_src_volser
The volume serial to identify the volume to be searched for an uncataloged source 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.
This variable only take effects when dataset_src_zos=true.
required: Falsetype: str- dataset_src_zos
Specifies whether the source file or data set from z/OS system will be copied.
If dataset_src_zos=false, the local data from Ansible control node will be copied to the target data set or member.
If dataset_src_zos=true, the source file or data set from z/OS system will be copied to the target data set or member.
required: Falsetype: booldefault: false- zmf_credential
Authentication credentials, returned by module
zmf_authenticate
, for the successful authentication with z/OSMF server.If zmf_credential is supplied, zmf_host, zmf_port, zmf_user, zmf_password, zmf_crt and zmf_key are ignored.
required: Falsetype: dict- jwtToken
The value of JSON Web token, which supports strong encryption.
If LtpaToken2 is not supplied, jwtToken is required.
required: Falsetype: str- LtpaToken2
The value of Lightweight Third Party Access (LTPA) token, which supports strong encryption.
If jwtToken is not supplied, LtpaToken2 is required.
required: Falsetype: str- zmf_host
Hostname of the z/OSMF server.
required: Truetype: str- zmf_port
Port number of the z/OSMF server.
required: Falsetype: int
- zmf_crt
Location of the PEM-formatted certificate chain file to be used for HTTPS client authentication.
If zmf_credential is supplied, zmf_crt is ignored.
If zmf_credential is not supplied, zmf_crt is required when zmf_user and zmf_password are not supplied.
required: Falsetype: str- zmf_host
Hostname of the z/OSMF server.
If zmf_credential is supplied, zmf_host is ignored.
If zmf_credential is not supplied, zmf_host is required.
required: Falsetype: str- zmf_key
Location of the PEM-formatted file with your private key to be used for HTTPS client authentication.
If zmf_credential is supplied, zmf_key is ignored.
If zmf_credential is not supplied, zmf_key is required when zmf_user and zmf_password are not supplied.
required: Falsetype: str- zmf_password
Password to be used for authenticating with z/OSMF server.
If zmf_credential is supplied, zmf_password is ignored.
If zmf_credential is not supplied, zmf_password is required when zmf_crt and zmf_key are not supplied.
If zmf_credential is not supplied and zmf_crt and zmf_key are supplied, zmf_user and zmf_password are ignored.
required: Falsetype: str- zmf_port
Port number of the z/OSMF server.
If zmf_credential is supplied, zmf_port is ignored.
required: Falsetype: int- zmf_user
User name to be used for authenticating with z/OSMF server.
If zmf_credential is supplied, zmf_user is ignored.
If zmf_credential is not supplied, zmf_user is required when zmf_crt and zmf_key are not supplied.
If zmf_credential is not supplied and zmf_crt and zmf_key are supplied, zmf_user and zmf_password are ignored.
required: Falsetype: str
Examples¶
- name: Copy a local file to data set ZOSMF.ANSIBLE.PS
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "/tmp/dataset_input/sample1"
dataset_dest: "ZOSMF.ANSIBLE.PS"
- name: Copy a local file to PDS member ZOSMF.ANSIBLE.PDS(MEMBER) only if it does not exist
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "/tmp/dataset_input/member01"
dataset_dest: "ZOSMF.ANSIBLE.PDS(MEMBER)"
dataset_force: false
- name: Copy the contents to data set ZOSMF.ANSIBLE.PS
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_conntent: "Sample profile\nTZ=EST5EDT\n"
dataset_dest: "ZOSMF.ANSIBLE.PS"
- name: Copy a local file to uncataloged PDS member ZOSMF.ANSIBLE.PDS(MEMBER) as binary
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "/tmp/dataset_input/member01"
dataset_dest: "ZOSMF.ANSIBLE.PDS(MEMBER)"
dataset_dest_volser: "VOL001"
dataset_data_type: "binary"
- name: Copy a local file to data set ZOSMF.ANSIBLE.PS and convert from ISO8859-1 to IBM-037
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "/tmp/dataset_input/sample1"
dataset_dest: "ZOSMF.ANSIBLE.PS"
dataset_encoding:
from: ISO8859-1
to: IBM-037
- name: Copy a local file to data set ZOSMF.ANSIBLE.PS and validate its checksum
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "/tmp/dataset_input/sample1"
dataset_dest: "ZOSMF.ANSIBLE.PS"
dataset_checksum: "93822124D6E66E2213C64B0D10800224"
- name: Copy a remote file to data set ZOSMF.ANSIBLE.PS
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "/etc/profile"
dataset_dest: "ZOSMF.ANSIBLE.PS"
dataset_src_zos: true
- name: Copy a remote file to data set ZOSMF.ANSIBLE.PDS(MEMBER) only if it does not exist
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "/etc/profile"
dataset_dest: "ZOSMF.ANSIBLE.PDS(MEMBER)"
dataset_src_zos: true
dataset_force: false
- name: Copy a remote sequential data set to data set ZOSMF.ANSIBLE.PS
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.REMOTE.PS"
dataset_dest: "ZOSMF.ANSIBLE.PS"
dataset_src_zos: true
- name: Copy a remote partitioned data set to data set ZOSMF.ANSIBLE.PDS without the like-named members
zmf_dataset_copy:
zmf_host: "sample.ibm.com"
dataset_src: "ZOSMF.ANSIBLE.REMOTE.PDS"
dataset_dest: "ZOSMF.ANSIBLE.PDS"
dataset_src_zos: true
dataset_force: false
Return Values¶
- changed
Indicates if any change is made during the module operation.
returned: alwaystype: bool- message
The output message generated by the module to indicate whether the data set or member is successfully copied.
returned: on successtype: strsample:
"The target data set ZOSMF.ANSIBLE.PDS is created successfully, and ZOSMF.ANSIBLE.PDS(MEMBER) is updated successfully." "The target data set ZOSMF.ANSIBLE.PS is updated successfully." "No data is copied since the target data set ZOSMF.ANSIBLE.PS already exists and dataset_force is set to False."- dataset_checksum
The checksum of the updated data set when the local data is copied to.
returned: on successtype: strsample:
"93822124D6E66E2213C64B0D10800224"