zos_blockinfile – Manage block of multi-line textual data on z/OS

Synopsis

  • Manage block of multi-lines in z/OS UNIX System Services (USS) files, PS(sequential data set), PDS, PDSE, or member of a PDS or PDSE.

  • This module ensures a particular block of multi-line text surrounded by customizable marker lines is present in a USS file or data set, or replaces an existing block identified by the markers.

  • This is primarily useful when you want to change a block of multi-line text in a USS file or data set.

Parameters

backup

Specifies whether a backup of destination should be created before editing the source src.

When set to true, the module creates a backup file or data set.

The backup file name will be returned on either success or failure of module execution such that data can be retrieved.

required: False
type: bool
backup_name

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

If the source src is a USS file or path, the backup_name name must be a file or path name, and the USS file or path must be an absolute path name.

If the source is an MVS data set, the backup_name name must be an MVS data set name.

If the backup_name is not provided, the default backup_name name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp, e.g. /path/file_name.2020-04-23-08-32-29-bak.tar.

If the source is an MVS data set, it will be a data set with a random name generated by calling the ZOAU API. The MVS backup data set recovery can be done by renaming it.

If src is a data set member and backup_name is not provided, the data set member will be backed up to the same partitioned data set with a randomly generated member name.

required: False
type: str
block

The text to insert inside the marker lines.

Multi-line can be separated by ‘n’.

required: False
type: str
encoding

The character set of the source src. zos_blockinfile requires to be provided with correct encoding to read the content of USS file or data set. If this parameter is not provided, this module assumes that USS file or data set is encoded in IBM-1047.

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
insertafter

If specified, the block will be inserted after the last match of the specified regular expression.

A special value EOF for inserting a block at the end of the file is available.

If a specified regular expression has no matches, EOF will be used instead.

Choices are EOF or ‘regex’.

Default is EOF.

required: False
type: str
insertbefore

If specified, the block will be inserted before the last match of specified regular expression.

A special value BOF for inserting the block at the beginning of the file is available.

If a specified regular expression has no matches, the block will be inserted at the end of the file.

Choices are BOF or ‘regex’.

required: False
type: str
marker

The marker line template.

{mark} will be replaced with the values in marker_begin (default=”BEGIN”) and marker_end (default=”END”).

Using a custom marker without the {mark} variable may result in the block being repeatedly inserted on subsequent playbook runs.

required: False
type: str
default: # {mark} ANSIBLE MANAGED BLOCK
marker_begin

This will be inserted at {mark} in the opening ansible block marker.

required: False
type: str
default: BEGIN
marker_end

This will be inserted at {mark} in the closing ansible block marker.

required: False
type: str
default: END
src

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

The USS file must be an absolute pathname.

required: True
type: str
state

Whether the block should be inserted/replaced (present) or removed (absent).

required: False
type: str
default: present
choices: absent, present

Examples

- name: Insert/Update new mount point
  zos_blockinfile:
    src: SYS1.PARMLIB(BPXPRM00)
    marker: "/* {mark} ANSIBLE MANAGED BLOCK */"
    block: |
      " MOUNT FILESYSTEM('SOME.DATA.SET') TYPE(ZFS) MODE(READ)"
      "    MOUNTPOINT('/tmp/src/somedirectory')"

- name: Remove a library as well as surrounding markers
  zos_blockinfile:
    state: absent
    src: SYS1.PARMLIB(PROG00)
    marker: "/* {mark} ANSIBLE MANAGED BLOCK FOR SOME.DATA.SET */"

- name: Add ZOAU path to PATH in /etc/profile
  zos_blockinfile:
    src: /etc/profile
    insertafter: "PATH="
    block: |
      "ZOAU=/path/to/zoau_dir/bin"
      "export ZOAU"
      "PATH=$ZOAU:$PATH"

- name: Insert/Update HTML surrounded by custom markers after <body> line
  zos_blockinfile:
    path: /var/www/html/index.html
    marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"
    insertafter: "<body>"
    block: |
      <h1>Welcome to {{ ansible_hostname }}</h1>
      <p>Last updated on {{ ansible_date_time.iso8601 }}</p>

- name: Remove HTML as well as surrounding markers
  zos_blockinfile:
    path: /var/www/html/index.html
    state: absent
    marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"

- name: Add mappings to /etc/hosts
  zos_blockinfile:
    path: /etc/hosts
    block: |
      {{ item.ip }} {{ item.name }}
    marker: "# {mark} ANSIBLE MANAGED BLOCK {{ item.name }}"
  loop:
    - { name: host1, ip: 10.10.1.10 }
    - { name: host2, ip: 10.10.1.11 }
    - { name: host3, ip: 10.10.1.12 }

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. The zos_data_set module can be used to catalog uncataloged data sets.

For supported character sets used to encode data, refer to https://ibm.github.io/z_ansible_collections_doc/reference/supplementary_content/encode.html

When using ‘with_*’ loops be aware that if you do not set a unique mark the block will be overwritten on each iteration.

When more then one block should be handled in a file you must change the marker per task.

Return Values

changed
Indicates if the source was modified
returned: success
type: bool
sample:
1
found
Number of the matching patterns
returned: success
type: int
sample: 5
cmd
Constructed ZOAU dmod shell command based on the parameters
returned: success
type: str
sample: dmodhelper -d -b -c IBM-1047 -m “BEGINnENDn# {mark} ANSIBLE MANAGED BLOCK” -e “$ a\PATH=/dir/bin:$PATH” /etc/profile
msg
The module messages
returned: failure
type: str
sample: Parameter verification failed
stdout
The stdout from ZOAU dmod when json.loads() fails to parse the result from dmod
returned: failure
type: str
stderr
The error messages from ZOAU dmod
returned: failure
type: str
sample: BGYSC1311E Iconv error, cannot open converter from ISO-88955-1 to IBM-1047
rc
The return code from ZOAU dmod when json.loads() fails to parse the result from dmod
returned: failure
type: bool
backup_name
Name of the backup file or data set that was created.
returned: if backup=true, always
type: str