[Enabler][1376]lineinfile_blockinfile_gdg/gds_and_special_character_support (#1516)

* Add support

* Add test case

* Changes for gdgs

* Add test case, and fix for gdg and special characters

* Fix sanity

* Add fragment

* Correct conditional

* Fix absent test

* Adjust check

* Fix bad test case

* Fix sanity and test cases

* Fix unusual names

* Fix new response

* Fix sanity

* Move validation of name

* Resolve comments

* Remove variables

* Add examples of use of gds

* Update zos_lineinfile.py

* Add comments

* Update plugins/modules/zos_blockinfile.py

Co-authored-by: Fernando Flores <[email protected]>

* Update plugins/modules/zos_blockinfile.py

Co-authored-by: Fernando Flores <[email protected]>

* Last chance

---------

Co-authored-by: Fernando Flores <[email protected]>

Author: AndreMarcel99

changelogs/fragments/1516-lineinfile_blockinfile_gdgsgds_and_special_character_support.yml

@@ -0,0 +1,9 @@
+minor_changes:
+  - zos_lineinfile - Added support for GDG and GDS relative name notation to use a data set.
+    And backup in new generations. Added support for data set names with special characters
+    like $, /#, /- and @.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1516).
+  - zos_blockinfile - Added support for GDG and GDS relative name notation to use a data set.
+    And backup in new generations. Added support for data set names with special characters
+    like $, /#, /- and @.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1516).

plugins/module_utils/backup.py

@@ -95,10 +95,10 @@ def mvs_file_backup(dsn, bk_dsn=None, tmphlq=None):
     dsn = _validate_data_set_name(dsn).upper()
     if is_member(dsn):
         # added the check for a sub-mmember, just in this case
-        if not bk_dsn:
-            bk_dsn = extract_dsname(dsn) + "({0})".format(temp_member_name())
-        elif "(" not in bk_dsn:
+        if not bk_dsn or "(" not in bk_dsn:
             bk_dsn = extract_dsname(dsn) + "({0})".format(temp_member_name())
+        elif DataSet.is_gds_positive_relative_name(bk_dsn):
+            bk_dsn = datasets.create(bk_dsn)
 
         bk_dsn = _validate_data_set_name(bk_dsn).upper()
         try:
@@ -128,7 +128,10 @@ def mvs_file_backup(dsn, bk_dsn=None, tmphlq=None):
             except exceptions.ZOAUException as copy_exception:
                 cp_rc = copy_exception.response.rc
         else:
-            cp_rc = _copy_ds(dsn, bk_dsn)
+            if DataSet.is_gds_positive_relative_name(bk_dsn):
+                cp_rc = datasets.copy(dsn, bk_dsn)
+            else:
+                cp_rc = _copy_ds(dsn, bk_dsn)
 
         if cp_rc == 12:  # The data set is probably a PDS or PDSE
             # Delete allocated backup that was created when attempting to use _copy_ds()
@@ -242,8 +245,8 @@ def _copy_ds(ds, bk_ds):
     module = AnsibleModuleHelper(argument_spec={})
     _allocate_model(bk_ds, ds)
     repro_cmd = """  REPRO -
-    INDATASET({0}) -
-    OUTDATASET({1})""".format(
+    INDATASET('{0}') -
+    OUTDATASET('{1}')""".format(
         ds, bk_ds
     )
     rc, out, err = module.run_command(

plugins/module_utils/data_set.py

@@ -1345,6 +1345,23 @@ def is_gds_relative_name(name):
         match = re.fullmatch(pattern, name)
         return bool(match)
 
+    @staticmethod
+    def is_gds_positive_relative_name(name):
+        """Determine if name is a gdg relative positive name
+        based on the GDS relative name syntax eg. 'USER.GDG(+1)'.
+        Parameters
+        ----------
+        name : str
+            Data set name to determine if is a GDS relative name.
+        Returns
+        -------
+        bool
+            Whether the name is a GDS positive relative name.
+        """
+        pattern = r'(.+)\(([\\]?[+]\d+)\)'
+        match = re.fullmatch(pattern, name)
+        return bool(match)
+
     @staticmethod
     def resolve_gds_absolute_name(relative_name):
         """Given a GDS relative name, returns its absolute name.
@@ -1727,6 +1744,7 @@ def _gather_data_set_info(self):
             dict -- Dictionary containing data set attributes
         """
         result = dict()
+        self.data_set = self.data_set.upper().replace("\\", '')
         listds_rc, listds_out, listds_err = mvs_cmd.ikjeft01(
             "  LISTDS '{0}'".format(self.data_set), authorized=True
         )

plugins/modules/zos_blockinfile.py

@@ -38,6 +38,8 @@
       - 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.
+      - Generation data set (GDS) relative name of generation already
+        created.  C(e.g. SOME.CREATION(-1).)
     type: str
     aliases: [ path, destfile, name ]
     required: true
@@ -110,6 +112,7 @@
       - 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.
+      - Use generation data set (GDS) relative positive name. C(e.g. SOME.CREATION(+1))
     required: false
     type: bool
     default: false
@@ -279,6 +282,20 @@
     marker_begin: "Begin Ansible Block Insertion 2"
     marker_end: "End Ansible Block Insertion 2"
     block: "{{ CONTENT }}"
+
+- name: Add a block to a gds
+  zos_blockinfile:
+    src: TEST.SOME.CREATION(0)
+    insertafter: EOF
+    block: "{{ CONTENT }}"
+
+- name: Add a block to dataset and backup in a new generation of gds
+  zos_blockinfile:
+    src: SOME.CREATION.TEST
+    insertbefore: BOF
+    backup: True
+    backup_name: CREATION.GDS(+1)
+    block: "{{ CONTENT }}"
 '''
 
 RETURN = r"""
@@ -456,13 +473,44 @@ def quotedString(string):
 
 
 def quotedString_double_quotes(string):
+    """Deletes the quote mark on strings.
+
+    Parameters
+    ----------
+    string : str
+        String to modify quote marks from.
+
+    Returns
+    -------
+    str
+        String scaping the quote marks.
+    """
     # add escape if string was quoted
     if not isinstance(string, str):
         return string
     return string.replace('"', '\\"')
 
 
 def check_double_quotes(marker, ins_bef, ins_aft, block):
+    """Verify the content of strings to determine if double
+      quotes are in the string.
+
+    Parameters
+    ----------
+    marker : str
+        String to verify quote marks from.
+    ins_bef : str
+        String to verify quote marks from.
+    ins_aft : str
+        String to verify quote marks from.
+    block : str
+        String to verify quote marks from.
+
+    Returns
+    -------
+    bool
+        If any string contain double quotes.
+    """
     if marker:
         if '"' in marker:
             return True
@@ -479,6 +527,42 @@ def check_double_quotes(marker, ins_bef, ins_aft, block):
 
 
 def execute_dmod(src, block, marker, force, encoding, state, module, ins_bef=None, ins_aft=None):
+    """Execute in terminal dmod command directly.
+
+    Parameters
+    ----------
+    src : str
+        The z/OS USS file or data set to modify.
+    block : str
+        The block to insert/replace into the src.
+    marker : str
+        The block will be inserted/updated with the markers.
+    force : bool
+        If not empty passes True option to dmod cmd.
+    encoding : str
+        Encoding of the src.
+    state : bool
+        Determine if will add or delete the block.
+    module : obj
+        Object to execute the command.
+    ins_bef : str
+        Insert the block before matching '*regex*' pattern or BOF.
+        choices:
+            - BOF
+            - '*regex*'
+    ins_aft : str
+        Insert the block after matching '*regex*' pattern or EOF.
+        choices:
+            - EOF
+            - '*regex*'
+
+    Returns
+    -------
+    int
+        RC of the execution of the command.
+    cmd
+        Command executed.
+    """
     block = block.replace('"', '\\"')
     force = "-f" if force else ""
     encoding = "-c {0}".format(encoding) if encoding else ""
@@ -505,6 +589,18 @@ def execute_dmod(src, block, marker, force, encoding, state, module, ins_bef=Non
 
 
 def clean_command(cmd):
+    """Deletes escaped characters from the str.
+
+    Parameters
+    ----------
+    cmd : str
+        Command to clean any escaped characters.
+
+    Returns
+    -------
+    str
+        Command without escaped characters.
+    """
     cmd = cmd.replace('/c\\\\', '')
     cmd = cmd.replace('/a\\\\', '', )
     cmd = cmd.replace('/i\\\\', '', )
@@ -667,18 +763,25 @@ def main():
     marker = "{0}\\n{1}\\n{2}".format(marker_begin, marker_end, marker)
     block = transformBlock(block, ' ', indentation)
     # analysis the file type
+    if "/" not in src:
+        dataset = data_set.MVSDataSet(
+            name=src
+        )
+        src = dataset.name
+
+    if data_set.DataSet.is_gds_relative_name(src):
+        module.fail_json(msg="{0} does not exist".format(src))
+
     ds_utils = data_set.DataSetUtils(src)
     if not ds_utils.exists():
         message = "{0} does NOT exist".format(str(src))
         module.fail_json(msg=message)
     file_type = ds_utils.ds_type()
-    if file_type == 'USS':
-        file_type = 1
-    else:
+
+    if file_type != "USS":
         if file_type not in DS_TYPE:
             message = "{0} data set type is NOT supported".format(str(file_type))
             module.fail_json(msg=message)
-        file_type = 0
 
     return_content = None
     if backup:
@@ -688,7 +791,7 @@ def main():
         if isinstance(backup, bool):
             backup = None
         try:
-            if file_type:
+            if file_type == "USS":
                 result['backup_name'] = Backup.uss_file_backup(src, backup_name=backup, compress=False)
             else:
                 result['backup_name'] = Backup.mvs_file_backup(dsn=src, bk_dsn=backup, tmphlq=tmphlq)