Merge pull request #68 from CICS/feat.CICSVersionInfo

Adds CICS version support via new module_util

Author: KyeMaloy97

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 docs/build/
 .idea
+.vscode/settings.json
 __pycache__
 venv*
 .venv

build.sh

@@ -33,6 +33,8 @@ echo "/* -----------------------------------------------------------------------
 echo "/*                          Integration tests Python 3.8                      */"
 echo "/* -------------------------------------------------------------------------- */"
 (set -x; ansible-test integration cics_cmci --python 3.8)
+(set -x; ansible-test integration cics_utilities --python 3.8)
+
 
 echo "/* -------------------------------------------------------------------------- */"
 echo "/*               Integration tests for missing libraries Python 3.8           */"
@@ -59,6 +61,7 @@ echo "/* -----------------------------------------------------------------------
 echo "/*                          Integration tests Python 2.7                      */"
 echo "/* -------------------------------------------------------------------------- */"
 (set -x; ansible-test integration cics_cmci --python 2.7)
+(set -x; ansible-test integration cics_utilities --python 2.7)
 deactivate
 
 source "$CMCI_PYTHON_38/bin/activate"

plugins/module_utils/cicsgetversion.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+
+# (c) Copyright IBM Corp. 2023
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+try:
+    import zoautil_py.datasets as Datasets
+    import zoautil_py.exceptions as ZOAUExceptions
+except ImportError as imp_exc:
+    ZOAUTIL_IMPORT_ERROR = imp_exc
+else:
+    ZOAUTIL_IMPORT_ERROR = None
+
+
+def get_dataset_member_version_record(dataset):  # type: (str) -> str
+    try:
+        records = Datasets.read("%s.SDFHSAMP(DFH0SINX)" % dataset)
+        return records.split("STATUS = ", 1)[1].split(" ")[0]
+    except ZOAUExceptions.ZOAUException:
+        raise Exception("Error reading dataset for calculating CICS version.")

requirements.txt

@@ -1,5 +1,6 @@
 # (c) Copyright IBM Corp. 2020,2021
 # Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
-requests==2.27.1
+requests==2.27.1;python_version<'3.7'
+requests==2.31.0;python_version>='3.7'
 xmltodict==0.12.0
 typing;python_version<"3.5"

tests/integration/targets/cics_utilities/host_vars/zos_host.yml

@@ -0,0 +1,15 @@
+pyz: "/python/v3r9/usr/lpp/IBM/cyp/v3r9/pyz"
+
+zoau: "/tools/zoautil"
+
+environment_vars:
+  _BPXK_AUTOCVT: "ON"
+  ZOAU_HOME: "{{ zoau }}"
+  PYTHONPATH: "{{ zoau }}/lib"
+  LIBPATH: "{{ zoau }}/lib:{{ pyz }}/lib:/lib:/usr/lib:."
+  PATH: "{{ zoau }}/bin:{{ pyz }}/bin:/bin:/var/bin"
+  _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
+  _TAG_REDIR_ERR: "txt"
+  _TAG_REDIR_IN: "txt"
+  _TAG_REDIR_OUT: "txt"
+  LANG: "C"

tests/integration/targets/cics_utilities/library/cics_version.py

@@ -0,0 +1,58 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) Copyright IBM Corp. 2023
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+from ansible.module_utils.basic import AnsibleModule
+from ansible_collections.ibm.ibm_zos_cics.plugins.module_utils.cicsgetversion import (get_dataset_member_version_record)
+
+from typing import Dict
+
+HIGH_LEVEL_QUALIFIER = 'CICS_HLQ'
+
+
+class CicsVersion(object):
+
+    def __init__(self):
+        self._module = AnsibleModule(
+            argument_spec=self.init_argument_spec(),
+        )  # type AnsibleModule
+        self.result = dict(changed=False)   # type: dict
+
+    def init_argument_spec(self):   # type: () -> Dict
+        return {
+            HIGH_LEVEL_QUALIFIER: {
+                'required': True,
+                'type': 'str'
+            },
+        }
+
+    def _fail(self, msg):  # type: (str) -> None
+        self._module.fail_json(msg=msg, **self.result)
+
+    def _exit(self):
+        self._module.exit_json(**self.result)
+
+    def main(self):
+        self.result['params'] = self._module.params
+
+        try:
+            cics_version = get_dataset_member_version_record(self._module.params.get(HIGH_LEVEL_QUALIFIER))
+            self.result['cics_version'] = cics_version
+            self.result['rc'] = 0
+            self._exit()
+        except Exception as e:
+            self.result['rc'] = 1
+            self.result['exception'] = e
+            self._fail("Error fetching version information from dataset with {0}".format(self._module.params.get(HIGH_LEVEL_QUALIFIER)))
+
+
+def main():
+    CicsVersion().main()
+
+
+if __name__ == '__main__':
+    main()

tests/integration/targets/cics_utilities/playbooks/cics_get_version.yml

@@ -0,0 +1,92 @@
+# (c) Copyright IBM Corp. 2023
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+---
+- name: CICS Version Integration Test
+  hosts: "all"
+  gather_facts: false
+
+  tasks:
+    ############################################################################
+    # Get CICS version for development version 
+    ############################################################################
+    - name: Retrieve CICS version information
+      environment: "{{ environment_vars }}"
+      cics_version:
+        CICS_HLQ: 'ANTZ.CICS.TS.DEV.INTEGRAT'
+      register: result
+
+    - name: Assert 1
+      ansible.builtin.assert:
+        that:
+          - result is not changed
+          - result.cics_version == '7.5.0'
+          - result.rc == 0
+          - "'exception' not in result"
+
+    ############################################################################
+    # Get CICS version for 6.1
+    ############################################################################
+    - name: Retrieve CICS version information
+      environment: "{{ environment_vars }}"
+      cics_version:
+        CICS_HLQ: 'CTS610.CICS740'
+      register: result
+      
+    - name: Assert 2
+      ansible.builtin.assert:
+        that:
+          - result is not changed
+          - result.cics_version == '7.4.0'
+          - result.rc == 0
+          - "'exception' not in result"
+
+    ############################################################################
+    # Get CICS version for 5.6
+    ############################################################################
+    - name: Retrieve CICS version information
+      environment: "{{ environment_vars }}"
+      cics_version:
+        CICS_HLQ: 'CTS560.CICS730'
+      register: result
+      
+    - name: Assert 3
+      ansible.builtin.assert:
+        that:
+          - result is not changed
+          - result.cics_version == '7.3.0'
+          - result.rc == 0
+          - "'exception' not in result"
+
+    ############################################################################
+    # Get CICS version for 5.4
+    ############################################################################
+    - name: Retrieve CICS version information
+      environment: "{{ environment_vars }}"
+      cics_version:
+        CICS_HLQ: 'CTS540.CICS710'
+      register: result
+      
+    - name: Assert 4
+      ansible.builtin.assert:
+        that:
+          - result is not changed
+          - result.cics_version == '7.1.0'
+          - result.rc == 0
+          - "'exception' not in result"
+        
+    ############################################################################
+    # Fail to get CICS version from incorrect HLQ
+    ############################################################################
+    - name: Fail to get CICS version information from incorrect HLQ
+      environment: "{{ environment_vars }}"
+      cics_version:
+        CICS_HLQ: 'ANZ.CIS.TS.EV.IEGRAT'
+      register: result
+      failed_when: false
+
+    - name: Assert 5
+      ansible.builtin.assert:
+        that:
+          - result is not changed
+          - result.rc != 0
+          - "'exception' in result"

tests/integration/targets/cics_utilities/runme.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# (c) Copyright IBM Corp. 2023
+# Apache License, Version 2.0 (see https://opensource.org/licenses/Apache-2.0)
+set -eux # This is important to ensure that return codes from failing tests are propagated
+ANSIBLE_LIBRARY=./library ansible-playbook -i zos_inventory playbooks/cics_get_version.yml

tests/integration/targets/cics_utilities/zos_inventory

@@ -0,0 +1,7 @@
+source_system:
+  hosts:
+    zos_host:
+      ansible_host: __ANSIBLE_TEST_HOST__
+      ansible_user: __ANSIBLE_TEST_USER__
+      ansible_python_interpreter: /python/v3r9/usr/lpp/IBM/cyp/v3r9/pyz/bin/python3.9
+      ansible_ssh_common_args: "-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null"

tests/unit/modules/test_cmci_get.py

@@ -14,7 +14,6 @@
 from ansible.module_utils import basic
 
 import pytest
-import re
 import sys
 
 
@@ -90,9 +89,10 @@ def test_unknown_host(monkeypatch):
     with pytest.raises(AnsibleFailJson) as exc_info:
         cmci_get.main()
 
-    exp = \
-        'Error performing CMCI request: <[^>]*>: Failed to establish a new connection: .*'
-    assert re.match(exp, exc_info.value.args[0]['msg']), exc_info.value.args[0]['msg'] + " didn't match"
+    if sys.version_info.major <= 2:
+        assert exc_info.value.args[0]['msg'].__contains__('Failed to establish a new connection')
+    else:
+        assert exc_info.value.args[0]['msg'].__contains__('([Errno -2] Name or service not known)')
 
 
 def test_invalid_port_type(cmci_module):  # type: (CMCITestHelper) -> None