Try SpotterManage block of multi-line textual data on z/OS
| "added in version" 1.3.0 of ibm.ibm_zos_core"
Authors: Behnam (@balkajbaf), Demetrios Dimatos (@ddimatos)
Install with ansible-galaxy collection install ibm.ibm_zos_core:==1.9.0
collections:
- name: ibm.ibm_zos_core
version: 1.9.0Manage 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.
- 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 }}"
src:
aliases:
- path
- destfile
- name
description:
- 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
block:
aliases:
- content
default: ''
description:
- 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
force:
default: false
description:
- 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 C(force) option enables sharing of data sets through the disposition I(DISP=SHR).
required: false
type: bool
state:
choices:
- absent
- present
default: present
description:
- Whether the block should be inserted or replaced using I(state=present).
- Whether the block should be removed using I(state=absent).
type: str
backup:
default: false
description:
- Specifies whether a backup of destination should be created before editing the source
I(src).
- When set to C(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
marker:
default: '# {mark} ANSIBLE MANAGED BLOCK'
description:
- The marker line template.
- C({mark}) will be replaced with the values C(in marker_begin) (default="BEGIN")
and C(marker_end) (default="END").
- Using a custom marker without the C({mark}) variable may result in the block being
repeatedly inserted on subsequent playbook runs.
required: false
type: str
tmp_hlq:
description:
- 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 C(TMPHLQ) is used.
required: false
type: str
encoding:
default: IBM-1047
description:
- The character set of the source I(src). L(zos_blockinfile,./zos_blockinfile.html)
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
marker_end:
default: END
description:
- This will be inserted at C({mark}) in the closing ansible block marker.
required: false
type: str
backup_name:
description:
- Specify the USS file name or data set name for the destination backup.
- If the source I(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. C(/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 I(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
indentation:
default: 0
description:
- Defines the number of spaces needed to prepend in every line of the block.
required: false
type: int
insertafter:
description:
- If specified, the block will be inserted after the last match of the specified regular
expression.
- A special value C(EOF) for inserting a block at the end of the file is available.
- If a specified regular expression has no matches, C(EOF) will be used instead.
- Choices are EOF or '*regex*'.
- Default is EOF.
required: false
type: str
insertbefore:
description:
- If specified, the block will be inserted before the last match of specified regular
expression.
- A special value C(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:
default: BEGIN
description:
- This will be inserted at C({mark}) in the opening ansible block marker.
required: false
type: str
backup_name:
description: Name of the backup file or data set that was created.
returned: if backup=true, always
sample: /path/to/file.txt.2015-02-03@04:15~
type: str
changed:
description: Indicates if the source was modified. Value of 1 represents `true`,
otherwise `false`.
returned: success
sample: 1
type: bool
cmd:
description: Constructed ZOAU dmod shell command based on the parameters
returned: success
sample: dmod -d -b -c IBM-1047 -m "BEGIN\nEND\n# {mark} ANSIBLE MANAGED BLOCK" -e
"$ a\\PATH=/dir/bin:$PATH" /etc/profile
type: str
found:
description: Number of the matching patterns
returned: success
sample: 5
type: int
msg:
description: The module messages
returned: failure
sample: Parameter verification failed
type: str
rc:
description: The return code from ZOAU dmod when json.loads() fails to parse the
result from dmod
returned: failure
type: bool
stderr:
description: The error messages from ZOAU dmod
returned: failure
sample: BGYSC1311E Iconv error, cannot open converter from ISO-88955-1 to IBM-1047
type: str
stdout:
description: The stdout from ZOAU dmod when json.loads() fails to parse the result
from dmod
returned: failure
type: str