zos_encode – Perform encoding operations.

Synopsis

  • Converts the encoding of characters that are read from a UNIX System Services (USS) file or path, PS(sequential data set), PDS, PDSE, or KSDS(VSAM data set).

  • Writes the data to a UNIX System Services (USS) file or path, PS(sequential data set), PDS, PDSE, or KSDS(VSAM data set).

Parameters

backup

Creates a backup file or backup data set for dest, including the timestamp information to ensure that you retrieve the original file.

backup_file can be used to specify a backup file name if backup=true.

required: False
type: bool
backup_compress

Determines if backups to USS files or paths should be compressed.

backup_compress is only used when backup=true.

required: False
type: bool
backup_file

Specify the USS file name or data set name for the dest backup.

If dest is a USS file or path, backup_file must be a file or path name, and the USS path or file must be an absolute pathname.

If dest is an MVS data set, the backup_file must be an MVS data set name.

If backup_file is not provided, the default backup name will be used. The default backup name for a USS file or path will be the destination file or path name appended with a timestamp, e.g. /path/file_name.2020-04-23-08-32-29-bak.tar. If dest is an MVS data set, the default backup name will be a random name generated by IBM Z Open Automation Utilities.

required: False
type: str
dest

The location where the converted characters are output.

The destination dest can be a UNIX System Services (USS) file or path, PS(sequential data set), PDS, PDSE, member of a PDS or PDSE, or KSDS(VSAM data set).

If the length of the PDSE member name used in dest is greater than 8 characters, the member name will be truncated when written out.

If dest is not specified, the src will be used as the destination and will overwrite the src with the character set in the option to_encoding.

The USS file or path must be an absolute pathname.

required: False
type: str
from_encoding

The character set of the source src.

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

required: False
type: str
default: IBM-1047
src

The location can be a UNIX System Services (USS) file or path, PS(sequential data set), PDS, PDSE, member of a PDS or PDSE, or KSDS(VSAM data set).

The USS path or file must be an absolute pathname.

If src is a USS directory, all files will be encoded.

required: True
type: str
to_encoding

The destination dest character set for the output to be written as.

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

required: False
type: str
default: ISO8859-1

Examples

- name: Convert file encoding from IBM-1047 to ISO8859-1 for the same file
  zos_encode:
    src: /zos_encode/test.data

- name: Convert file encoding from IBM-1047 to ISO8859-1 to another file with
    backup
  zos_encode:
    src: /zos_encode/test.data
    dest: /zos_encode_out/test.out
    from_encoding: IBM-1047
    to_encoding: ISO8859-1
    backup: yes
    backup_compress: yes

- name: Convert file encoding from IBM-1047 to ISO8859-1 to a directory
  zos_encode:
    src: /zos_encode/test.data
    dest: /zos_encode_out/

- name: Convert file encoding from all files in a directory to another
    directory
  zos_encode:
    src: /zos_encode/
    dest: /zos_encode_out/
    from_encoding: ISO8859-1
    to_encoding: IBM-1047

- name: Convert file encoding from a USS file to a sequential data set
  zos_encode:
    src: /zos_encode/test.data
    dest: USER.TEST.PS
    from_encoding: IBM-1047
    to_encoding: ISO8859-1

- name: Convert file encoding from files in a directory to a partitioned
    data set
  zos_encode:
    src: /zos_encode/
    dest: USER.TEST.PDS
    from_encoding: ISO8859-1
    to_encoding: IBM-1047

- name: Convert file encoding from a USS file to a partitioned data set
    member
  zos_encode:
    src: /zos_encode/test.data
    dest: USER.TEST.PDS(TESTDATA)
    from_encoding: ISO8859-1
    to_encoding: IBM-1047

- name: Convert file encoding from a sequential data set to a USS file
  zos_encode:
    src: USER.TEST.PS
    dest: /zos_encode/test.data
    from_encoding: IBM-1047
    to_encoding: ISO8859-1

- name: Convert file encoding from a PDS encoding to a USS directory
  zos_encode:
    src: USER.TEST.PDS
    dest: /zos_encode/
    from_encoding: IBM-1047
    to_encoding: ISO8859-1

- name: Convert file encoding from a sequential data set to another
    sequential data set
  zos_encode:
    src: USER.TEST.PS
    dest: USER.TEST1.PS
    from_encoding: IBM-1047
    to_encoding: ISO8859-1

- name: Convert file encoding from a sequential data set to a
    partitioned data set (extended) member
  zos_encode:
    src: USER.TEST.PS
    dest: USER.TEST1.PDS(TESTDATA)
    from_encoding: IBM-1047
    to_encoding: ISO8859-1

- name: Convert file encoding from a USS file to a VSAM data set
  zos_encode:
    src: /zos_encode/test.data
    dest: USER.TEST.VS
    from_encoding: ISO8859-1
    to_encoding: IBM-1047

- name: Convert file encoding from a VSAM data set to a USS file
  zos_encode:
    src: USER.TEST.VS
    dest: /zos_encode/test.data
    from_encoding: IBM-1047
    to_encoding: ISO8859-1

- name: Convert file encoding from a VSAM data set to a sequential
    data set
  zos_encode:
    src: USER.TEST.VS
    dest: USER.TEST.PS
    from_encoding: IBM-1047
    to_encoding: ISO8859-1

- name: Convert file encoding from a sequential data set a VSAM data set
  zos_encode:
    src: USER.TEST.PS
    dest: USER.TEST.VS
    from_encoding: ISO8859-1
    to_encoding: IBM-1047

Notes

Note

It is the playbook author or user’s responsibility to avoid files that should not be encoded, such as binary files. A user is described as the remote user, configured either for the playbook or playbook tasks, who can also obtain escalated privileges to execute as root or another user.

All data sets are always assumed to be cataloged. If an uncataloged data set needs to be encoded, it should be cataloged first.

For supported character sets used to encode data, refer to https://ansible-collections.github.io/ibm_zos_core/supplementary.html#encode

Return Values

src
The location of the input characters identified in option I(src).
returned: always
type: str
dest
The name of the output file or data set. If dest is a USS file or path and the status has been changed in the conversion, the file status will also be returned.
returned: always
type: str
backup_file
Name of the backup file created.
returned: changed and if backup=yes
type: str
sample: /path/file_name.2020-04-23-08-32-29-bak.tar