Add force (disp=shr) option to zos_lineinfile and update zos_blockinfile with the same locking test case. (#731)

* Add DISP=SHR by function force to the user

* Add helper function for force cases only for EOF inserts

* Test cases added

* Just to check in the change case

* All test cases for force in zos_lineinfile working properly

* Test cases for force blockinfile

* Fixes for style of code

* One identation error

* One identation error

* One identation error

* Documentation error

* All test cases for line infile and block infile

* Comments

* Change the stdout to assert with expected of ds

* Error of test case

* Fragment added

* Solve typo errors

* Update to remove uncessary comment

Signed-off-by: ddimatos <dimatos@gmail.com>

* Update changelog fragment

Signed-off-by: ddimatos <dimatos@gmail.com>

* Update module with force comments

Signed-off-by: ddimatos <dimatos@gmail.com>

* Solve some test problems

* Copyright year

* Copyright year

* Add cases for other ecodes

* Add test for all encodings

* Cover all encodes test cases with force

* Blockinfile force added for other encodes and DS types

---------

Signed-off-by: ddimatos <dimatos@gmail.com>
Co-authored-by: Andre Marcel Gutierrez Benitez <andre@MacBook-Pro-de-Andre-2.local>
Co-authored-by: Andre Marcel Gutierrez Benitez <andre@mbp-de-andre-2.gdl.mex.ibm.com>
Co-authored-by: ddimatos <dimatos@gmail.com>

Author: 4 people

changelogs/fragments/731-zos_linefile-disposition_share.yaml

@@ -0,0 +1,6 @@
+minor_changes:
+- zos_lineinfile - would access data sets with exclusive access so no other
+  task can read the data, this enhancement allows for a data set to be opened
+  with a disposition set to share so that other tasks can access the data when
+  option `force` is set to `true`.
+  (https://github.com/ansible-collections/ibm_zos_core/pull/731)

plugins/modules/zos_lineinfile.py

@@ -173,6 +173,18 @@
     required: false
     type: str
     default: IBM-1047
+  force:
+    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
+    default: false
 notes:
   - 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
@@ -218,6 +230,14 @@
     regexp: '^(.*)User(\d+)m(.*)$'
     line: '\1APPUser\3'
     backrefs: yes
+
+- name: Add a line to a member while a task is in execution
+  zos_lineinfile:
+    src: SOME.PARTITIONED.DATA.SET(DATA)
+    insertafter: EOF
+    line: 'Should be a working test now'
+    force: True
+
 """
 
 RETURN = r"""
@@ -271,7 +291,7 @@
 DS_TYPE = ['PS', 'PO']
 
 
-def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs):
+def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs, force):
     """Replace a line with the matching regex pattern
     Insert a line before/after the matching pattern
     Insert a line at BOF/EOF
@@ -292,6 +312,7 @@ def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs
         encoding: {str} -- Encoding of the src.
         first_match: {bool} -- Take the first matching regex pattern.
         backrefs: {bool} -- Back reference
+        force: {bool} -- force for modify a member part of a task in execution
 
     Returns:
         str -- Information in JSON format. keys:
@@ -310,10 +331,11 @@ def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs
         backref=backrefs,
         state=True,
         debug=True,
+        force=force,
     )
 
 
-def absent(src, line, regexp, encoding):
+def absent(src, line, regexp, encoding, force):
     """Delete lines with matching regex pattern
 
     Arguments:
@@ -322,14 +344,15 @@ def absent(src, line, regexp, encoding):
             regexp will be ignored.
         regexp: {str} -- The regular expression to look for in every line of the src.
         encoding: {str} -- Encoding of the src.
+        force: {bool} -- force for modify a member part of a task in execution
 
     Returns:
         str -- Information in JSON format. keys:
             cmd: {str} -- dsed shell command
             found: {int} -- Number of matching regex pattern
             changed: {bool} -- Indicates if the source was modified.
     """
-    return datasets.lineinfile(src, line, regex=regexp, encoding=encoding, state=False, debug=True)
+    return datasets.lineinfile(src, line, regex=regexp, encoding=encoding, state=False, debug=True, force=force)
 
 
 def quotedString(string):
@@ -364,7 +387,8 @@ def main():
         backup_name=dict(type='str', required=False, default=None),
         firstmatch=dict(type='bool', default=False),
         encoding=dict(type='str', default="IBM-1047"),
-        tmp_hlq=dict(type='str', required=False, default=None)
+        tmp_hlq=dict(type='str', required=False, default=None),
+        force=dict(type='bool', required=False, default=False)
     )
     module = AnsibleModule(
         argument_spec=module_args,
@@ -385,6 +409,7 @@ def main():
         firstmatch=dict(arg_type="bool", required=False, default=False),
         backrefs=dict(arg_type="bool", dependencies=['regexp'], required=False, default=False),
         tmp_hlq=dict(type='qualifier_or_empty', required=False, default=None),
+        force=dict(arg_type='bool', required=False, default=False),
         mutually_exclusive=[["insertbefore", "insertafter"]],)
 
     try:
@@ -406,6 +431,7 @@ def main():
     ins_bef = parsed_args.get('insertbefore')
     encoding = parsed_args.get('encoding')
     tmphlq = parsed_args.get('tmp_hlq')
+    force = parsed_args.get('force')
 
     if parsed_args.get('state') == 'present':
         if backrefs and regexp is None:
@@ -453,9 +479,10 @@ def main():
     # state=present, insert/replace a line with matching regex pattern
     # state=absent, delete lines with matching regex pattern
     if parsed_args.get('state') == 'present':
-        return_content = present(src, quotedString(line), quotedString(regexp), quotedString(ins_aft), quotedString(ins_bef), encoding, firstmatch, backrefs)
+        return_content = present(src, quotedString(line), quotedString(regexp), quotedString(ins_aft), quotedString(ins_bef), encoding, firstmatch,
+                                 backrefs, force)
     else:
-        return_content = absent(src, quotedString(line), quotedString(regexp), encoding)
+        return_content = absent(src, quotedString(line), quotedString(regexp), encoding, force)
     stdout = return_content.stdout_response
     stderr = return_content.stderr_response
     rc = return_content.rc

tests/functional/modules/test_zos_blockinfile_func.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (c) IBM Corporation 2020, 2022
+# Copyright (c) IBM Corporation 2020, 2022, 2023
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -17,6 +17,8 @@
     DsGeneral,
     DsNotSupportedHelper,
     DsGeneralResultKeyMatchesRegex,
+    DsGeneralForce,
+    DsGeneralForceFail,
 )
 import os
 import sys
@@ -238,6 +240,14 @@
     test_ds_block_insertafter_eof_with_backup_name=dict(
         block="export ZOAU_ROOT\nexport ZOAU_HOME\nexport ZOAU_DIR",
         state="present", backup=True, backup_name=MVS_BACKUP_DS),
+    test_ds_block_insertafter_regex_force=dict(
+        path="",insertafter="ZOAU_ROOT=",
+        block="ZOAU_ROOT=/mvsutil-develop_dsed\nZOAU_HOME=\\$ZOAU_ROOT\nZOAU_DIR=\\$ZOAU_ROOT",
+        state="present", force=True),
+    test_ds_block_insertafter_regex_force_fail=dict(
+        path="",insertafter="ZOAU_ROOT=",
+        block="ZOAU_ROOT=/mvsutil-develop_dsed\nZOAU_HOME=\\$ZOAU_ROOT\nZOAU_DIR=\\$ZOAU_ROOT",
+        state="present", force=False),
     expected=dict(test_uss_block_insertafter_regex_defaultmarker="""if [ -z STEPLIB ] && tty -s;
 then
     export STEPLIB=none
@@ -1498,6 +1508,17 @@ def test_ds_block_insertafter_eof_with_backup(ansible_zos_module, dstype, encodi
         ansible_zos_module.all.zos_data_set(name=backup_ds_name, state="absent")
 
 
+@pytest.mark.ds
+@pytest.mark.parametrize("dstype", DS_TYPE)
+def test_ds_block_insertafter_regex_force(ansible_zos_module, dstype):
+    TEST_ENV["DS_TYPE"] = dstype
+    DsGeneralForce(
+        ansible_zos_module, TEST_ENV,
+        TEST_INFO["test_ds_block_insertafter_regex_force"],
+        TEST_INFO["expected"]["test_uss_block_insertafter_regex_defaultmarker"]
+    )
+    
+
 #########################
 # Negative tests
 #########################
@@ -1545,4 +1566,14 @@ def test_ds_not_supported(ansible_zos_module, dstype):
     DsNotSupportedHelper(
         TEST_INFO["test_ds_block_insertafter_regex"]["test_name"], ansible_zos_module,
         TEST_ENV, TEST_INFO["test_uss_block_insertafter_regex"]
-    )
+    )
+
+
+@pytest.mark.ds
+@pytest.mark.parametrize("dstype", DS_TYPE)
+def test_ds_block_insertafter_regex_fail(ansible_zos_module, dstype):
+    TEST_ENV["DS_TYPE"] = dstype
+    DsGeneralForceFail(
+        ansible_zos_module, TEST_ENV,
+        TEST_INFO["test_ds_block_insertafter_regex_force_fail"],
+    )