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

Synopsis
Parameters
Examples
Notes
See Also
Return Values

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 ¶

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 or replaced using state=present.

Whether the block should be removed using state=absent.

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

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

block

The text to insert inside the marker lines.

Multi-line can be separated by ‘n’.

Any double-quotation marks will be removed.

required: False

type: str

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_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

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
default: False

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, and the dataset must not be preallocated.

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

tmp_hlq

Override the default high level qualifier (HLQ) for temporary and backup datasets.

The default HLQ is the Ansible user used to execute the module and if that is not available, then the value TMPHLQ is used.

required: False

type: str

encoding

The character set of the source src. zos_blockinfile requires it to be provided with correct encoding to read the content of a 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

force

Specifies that the data set can be shared with others during an update which results in the data set you are updating to be simultaneously updated by others.

This is helpful when a data set is being used in a long running process such as a started task and you are wanting to update or read.

The force option enables sharing of data sets through the disposition DISP=SHR.

required: False
type: bool
default: False

indentation

Defines the number of spaces needed to prepend in every line of the block.

required: False
type: int
default: 0

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 }
- name: Add a code block to a member using a predefined indentation.
  zos_blockinfile:
    path: SYS1.PARMLIB(BPXPRM00)
    block: |
          DSN SYSTEM({{ DB2SSID }})
          RUN  PROGRAM(DSNTEP2) PLAN(DSNTEP12) -
          LIB('{{ DB2RUN }}.RUNLIB.LOAD')
    indentation: 16

- name: Update a script with commands containing quotes.
  zos_blockinfile:
    src: "/u/scripts/script.sh"
    insertafter: "EOF"
    block: |
          cat "//'{{ DS_NAME }}'"
          cat "//'{{ DS_NAME_2 }}'"

- name: Set facts for the following two tasks.
  set_fact:
    HLQ: 'ANSIBLE'
    MLQ: 'MEMBER'
    LLQ: 'TEST'
    MEM: '(JCL)'
    MSG: 'your first JCL program'
    CONTENT: "{{ lookup('file', 'files/content.txt') }}"

- name: Update JCL in a PDS member with Jinja2 variable syntax.
  zos_blockinfile:
    src: "{{ HLQ }}.{{MLQ}}.{{LLQ}}{{MEM}}"
    insertafter: "HELLO, WORLD"
    marker: "//* {mark} *//"
    marker_begin: "Begin Ansible Block Insertion 1"
    marker_end: "End Ansible Block Insertion 1"
    state: present
    block: |
      This is {{ MSG }}, and its now
      managed by Ansible.

- name: Update JCL in PDS member with content from a file.
  zos_blockinfile:
    src: "{{ HLQ }}.{{MLQ}}.{{LLQ}}{{MEM}}"
    insertafter: "End Ansible Block Insertion 1"
    marker: "//* {mark} *//"
    marker_begin: "Begin Ansible Block Insertion 2"
    marker_end: "End Ansible Block Insertion 2"
    block: "{{ CONTENT }}"

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 the documentation.

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. Value of 1 represents true, otherwise false.

returned: success
type: bool
sample:

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: dmod -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
sample: /path/to/file.txt.2015-02-03@04:15~

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

Synopsis¶

Parameters¶

Examples¶

Notes¶

See Also¶

Return Values¶

Synopsis ¶

Parameters ¶

Examples ¶

Notes ¶

See Also ¶

Return Values ¶