v0.0.4 Alpha

.github/workflows/clang-format.yml

@@ -8,13 +8,13 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Install clang-format
-      run: sudo apt install -y cmake clang-format-19
+      run: sudo apt install -y cmake clang-format-20
     - name: clang-format
-      # Create symbolic link to clang-format-19 and 
+      # Create symbolic link to clang-format-20 and 
       # add it to PATH so that 'clang-format' can 
-      # be used to run 'clang-format-19'.
+      # be used to run 'clang-format-20'.
       run: |
-        ln -s $(which clang-format-19) clang-format
+        ln -s $(which clang-format-20) clang-format
         export PATH=$PWD:$PATH
         cmake .
         make lint

CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.15)
 
-project(CBXP VERSION 0.0.3
-             DESCRIPTION "A unified and standardized interface for extracting z/OS control block data."
+project(CBXP VERSION 0.0.4
+             DESCRIPTION "A unified and standardized interface for extracting and formatting z/OS control block data."
              LANGUAGES C CXX)
 
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "./dist")
@@ -39,12 +39,15 @@ endif()
 # ============================================================================
 file(
     GLOB CBXP_SRC_LIB
-    "cbxp/cbxp.cpp"
-    "cbxp/control_block_explorer.cpp"
-    "cbxp/logger.cpp"
+    "cbxp/*.cpp"
     "cbxp/control_blocks/*.cpp"
 )
 
+file(
+    GLOB CBXP_SRC_CLI
+    "cbxp/cli/*.cpp"
+)
+
 file(
     GLOB CBXP_SRC_ALL
     "cbxp/*.cpp"
@@ -77,7 +80,7 @@ target_link_options(libcbxp PUBLIC ${LINK_OPTIONS})
 # ============================================================================
 # Build '/bin/cbxp'
 # ============================================================================
-add_executable(cbxp "cbxp/main.cpp")
+add_executable(cbxp ${CBXP_SRC_CLI})
 
 target_link_libraries(cbxp libcbxp)
 
@@ -92,36 +95,32 @@ target_compile_options(cbxp PUBLIC ${COMPILE_OPTIONS})
 target_link_options(cbxp PUBLIC ${LINK_OPTIONS})
 
 # ============================================================================
-# Packaging
+# Install
 # ============================================================================
-add_custom_target(
-    package
-    COMMAND "mkdir"
-                "-p"
-                "cbxp-${CMAKE_PROJECT_VERSION}/bin"
-                "cbxp-${CMAKE_PROJECT_VERSION}/lib"
-                "cbxp-${CMAKE_PROJECT_VERSION}/include"
-    COMMAND "cp"
-                "LICENSE"
-                "cbxp-${CMAKE_PROJECT_VERSION}/"
-    COMMAND "cp"
-                "NOTICES"
-                "cbxp-${CMAKE_PROJECT_VERSION}/"
-    COMMAND "cp"
-                "./dist/cbxp"
-                "cbxp-${CMAKE_PROJECT_VERSION}/bin/"
-    COMMAND "cp"
-                "./dist/libcbxp.a"
-                "cbxp-${CMAKE_PROJECT_VERSION}/lib/"
-    COMMAND "cp"
-                "./cbxp/cbxp.h"
-                "cbxp-${CMAKE_PROJECT_VERSION}/include/"
-    COMMAND "pax"
-                "-x" "pax"
-                "-wzvf"
-                "./dist/cbxp-${CMAKE_PROJECT_VERSION}.pax.Z"
-                "cbxp-${CMAKE_PROJECT_VERSION}/*"
-    DEPENDS libcbxp cbxp
+if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
+    SET(CMAKE_INSTALL_PREFIX "~/cbxp-${CMAKE_PROJECT_VERSION}" CACHE PATH "install path" FORCE)
+endif(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
+
+include(GNUInstallDirs)
+
+install(
+    FILES "LICENSE" "NOTICES"
+    DESTINATION ${CMAKE_INSTALL_PREFIX}
+)
+
+install(
+    TARGETS cbxp
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)
+
+install(
+    TARGETS libcbxp
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+)
+
+install(
+    FILES "./cbxp/cbxp.h"
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
 
 # ============================================================================

Jenkinsfile

@@ -89,13 +89,13 @@ pipeline {
     stage('Lint') {
       steps {
         echo "Linting with clang-format ..."
-        sh "gmake lint"
+        sh "cmake --build . --target lint --parallel"
       }
     }
     stage('Cppcheck') {
       steps {
         echo "Running cppcheck ..."
-        sh "gmake check"
+        sh "cmake --build . --target check --parallel"
       }
     }
     stage('Create Python Distribution Metadata') {
@@ -118,7 +118,7 @@ pipeline {
 
             echo "Building '${wheel}' and '${tar}' ..."
             sh """
-                ${python} -m pip install build>=1.3.0
+                ${python} -m pip install build>=1.5.0
                 ${python} -m build
             """
 
@@ -139,25 +139,17 @@ pipeline {
             clean_python_environment()
             clean_git_repo()
           }
-          // Shell/C/C++ pax distribution
+          // CLI/C/C++ distribution
           def cbxp_version = get_cbxp_version()
-          def pax = "cbxp-${cbxp_version}.pax.Z"
-          echo "Building '${pax}' ..."
+          echo "Installing testing CBXP '${cbxp_version}' ..."
           sh """
-              cmake .
-              gmake package
-          """
-
-          echo "Install testing '${pax}' ..."
-          sh """
-              mkdir install-test
-              cd install-test
-              pax -rf ../dist/${pax}
-              ls -alT cbxp-${cbxp_version}/*
+              cmake . --install-prefix ${env.WORKSPACE}/install-test
+              cmake --build . --parallel
+              cmake --install .
           """
 
           echo "'Function testing './dist/cbxp' ..."
-          sh "gmake test"
+          sh "cmake --build . --target test --parallel"
 
           clean_git_repo()
         }
@@ -213,7 +205,9 @@ def create_python_executables_and_wheels_map(python_versions) {
           "cbxp-${cbxp_version}-cp3${python_version}-cp3${python_version}-zos.whl"
         ),
         "wheelPublish": (
-          "cbxp-${cbxp_version}-cp3${python_version}-cp3${python_version}-zos.whl"
+          // New wheel naming convention does not work with PyPi so we
+          // do still need to rename the wheel file.
+          "cbxp-${cbxp_version}-cp3${python_version}-none-any.whl"
         ),
         "tarPublish": "cbxp-${cbxp_version}.tar.gz"
       ]
@@ -334,14 +328,11 @@ def publish(
       echo "Building '${wheel_default}' ..."
 
       sh """
-        ${python} -m pip install build>=1.2.2
+        ${python} -m pip install build>=1.5.0
         ${python} -m build -w
       """
 
-      // Rename wheel file if the old naming convention is being used
-      if (wheel_default != wheel_publish) {
-        sh "mv ./dist/${wheel_default} ./dist/${wheel_publish}"
-      }
+      sh "mv ./dist/${wheel_default} ./dist/${wheel_publish}"
 
       if (tar_built == false) {
         tar_publish = python_executables_and_wheels_map[python]["tarPublish"]
@@ -354,29 +345,31 @@ def publish(
       upload_asset(release_id, wheel_publish)
 
       echo "Adding sha256 checksum for '${wheel_publish}' to ${checksums_file}..."
-      sh "cd dist && sha256sum -t ${wheel_publish} >> ${checksums_file}"
+      sh "cd dist && sha256sum ${wheel_publish} >> ${checksums_file}"
     }
 
     echo "Uploading '${tar_publish}' to '${release_title}' GitHub release ..."
     upload_asset(release_id, tar_publish)
 
     echo "Adding sha256 checksum for '${tar_publish}' to ${checksums_file}..."
-    sh "cd dist && sha256sum -t ${tar_publish} >> ${checksums_file}"
+    sh "cd dist && sha256sum ${tar_publish} >> ${checksums_file}"
 
-    // Build and publish Shell/C/C++ interface pax
+    // Build and publish CLI/C/C++ interface pax
     def cbxp_version = get_cbxp_version()
     def pax = "cbxp-${cbxp_version}.pax.Z"
     echo "Building '${pax}' ..."
     sh """
-        cmake .
-        gmake package
+        cmake . --install-prefix ${env.WORKSPACE}/cbxp-${cbxp_version}
+        cmake --build . --parallel
+        cmake --install .
+        pax -x pax -wzvf ./dist/${pax} cbxp-${cbxp_version}/*
     """
 
     echo "Uploading '${pax}' to '${release_title}' GitHub release ..."
     upload_asset(release_id, pax)
 
     echo "Adding sha256 checksum for '${pax}' to ${checksums_file}..."
-    sh "cd dist && sha256sum -t ${pax} >> ${checksums_file}"
+    sh "cd dist && sha256sum ${pax} >> ${checksums_file}"
 
     echo "Uploading '${checksums_file}' to '${release_title}' GitHub release ..."
     upload_asset(release_id, checksums_file)
@@ -422,7 +415,7 @@ def build_description(python_executables_and_wheels_map, release_tag, release_no
     + "> :warning: _Requires z/OS Open XL C/C++ 2.2 compiler._\\n"
     + "```\\ncurl -O -L https://github.com/ambitus/cbxp/releases/download/${release_tag}/${tar} "
     + "&& python3 -m pip install ${tar}\\n```\\n"
-    + "## Shell/C/C++ Interface Installation\\n"
+    + "## CLI/C/C++ Interface Installation\\n"
     + "```\\ncurl -O -L https://github.com/ambitus/cbxp/releases/download/${release_tag}/${pax} "
     + "&& pax -rf ${pax}\\n```\\n"
   )

README.md

@@ -9,18 +9,18 @@
 
 # CBXP (Control Block EXPlorer)
 
-A unified and standardized interface for extracting z/OS control block data.
+A unified and standardized interface for extracting and formatting z/OS control block data.
 
 ## Description
 
-z/OS Control Blocks are in-memory data structures that describe and control countless process, operating system components, and subsystems. Control blocks are ubiquitous on z/OS, but not very straight forward to access and extract information from. The mission of CBXP *(Control Block EXPlorer)* is to make it easy to extract z/OS control block data using industry standard tools and methodologies. CBXP accomplishes this by implementing a **C/C++ XPLINK ASCII** interface for extracting control blocks and post processing them into **JSON**. This makes it straight forward to integrate with industry standard programming languages and tools, which generally have well documented and understood foreign language interfaces for C/C++, and native and or third party JSON support that makes working with JSON data easy.
+z/OS Control Blocks are in-memory data structures that describe and control countless process, operating system components, and subsystems. Control blocks are ubiquitous on z/OS, but not very straight forward to access and extract information from. The mission of CBXP *(Control Block EXPlorer)* is to make it easy to extract and format z/OS control block data using industry standard tools and methodologies. CBXP accomplishes this by implementing a **C/C++ XPLINK ASCII** interface for extracting control block data and post processing it into **JSON**. This makes it straight forward to integrate with industry standard programming languages and tools, which generally have well documented and understood foreign language interfaces for C/C++, and native and or third party JSON support that makes working with JSON data easy.
 
 CBXP is the successor to the existing [cbxplorer](https://github.com/ambitus/cbexplorer) project. CBXP mainly improves upon this existing work by being implemented in C/C++ so that it is not limited to a specific programming language or tool. CBXP also focuses heavily on providing an interface that is simple and straight forward to use.
 
 ## Getting Started
 
 ### Minimum z/OS & Language Versions
-Currently, CBXP is being developed on **z/OS 3.1**. We hope to eventually support all z/OS versions that are fully supported by IBM.
+Currently, CBXP is being developed on **z/OS 3.2**. We hope to eventually support all z/OS versions that are fully supported by IBM.
 * [z/OS Product Lifecycle](https://www.ibm.com/support/pages/lifecycle/search/?q=5655-ZOS,%205650-ZOS)
 
 All versions of the **IBM Open Enterprise SDK for Python** that are fully supported by IBM are supported by CBXP.
@@ -33,12 +33,12 @@ All versions of the **IBM Open Enterprise SDK for Python** that are fully suppor
 ### Interfaces
 Currently, the following interfaces are provided for CBXP. Additional interfaces can be added in the future if there are use cases for them.
 * [Python Interface](https://ambitus.github.io/cbxp/interfaces/python)
-* [CLI Interface](https://ambitus.github.io/cbxp/interfaces/shell)
+* [CLI Interface](https://ambitus.github.io/cbxp/interfaces/cli)
 * [C/C++ Interface](https://ambitus.github.io/cbxp/interfaces/c_cpp)
 
 ### Supported Control Blocks
 
-Currently, CBXP only has support for extracting a handful of **System-Level Control Blocks** from **Live Memory** *(storage)*. See [Supported Control Blocks](https://ambitus.github.io/cbxp/supported_control_blocks) for more details.
+Currently, CBXP only has support for extracting and formatting a handful of **System-Level Control Blocks**. See [Supported Control Blocks](https://ambitus.github.io/cbxp/supported_control_blocks) for more details.
 
 ## Help
 * [GitHub Discussions](https://github.com/ambitus/cbxp/discussions)

cbxp/cbxp.cpp

@@ -1,28 +1,54 @@
 #include "cbxp.h"
 
-#include <algorithm>
-#include <iostream>
 #include <nlohmann/json.hpp>
 
 #include "control_block_explorer.hpp"
 #include "logger.hpp"
 
-cbxp_result_t* cbxp(const char* control_block, const char* includes_string,
-                    const char* filters_string, bool debug) {
-  nlohmann::json control_block_json;
+cbxp_result_t* cbxp_extract(const char* control_block_name,
+                            const size_t control_block_name_length,
+                            const char* includes, const size_t includes_length,
+                            const char* filters, const size_t filters_length,
+                            bool debug) {
+  std::string control_block_name_string;
+  std::string includes_string_string;
+  std::string filters_string_string;
 
-  std::string control_block_cpp_string;
-  std::string includes_string_cpp_string;
-  std::string filters_string_cpp_string;
-
-  if (control_block != nullptr) {
-    control_block_cpp_string = control_block;
+  if (control_block_name != nullptr) {
+    control_block_name_string.assign(control_block_name,
+                                     control_block_name_length);
+  }
+  if (includes != nullptr) {
+    includes_string_string.assign(includes, includes_length);
   }
-  if (includes_string != nullptr) {
-    includes_string_cpp_string = includes_string;
+  if (filters != nullptr) {
+    filters_string_string.assign(filters, filters_length);
   }
-  if (filters_string != nullptr) {
-    filters_string_cpp_string = filters_string;
+
+  CBXP::Logger::getInstance().setDebug(debug);
+
+  cbxp_result_t* p_cbxp_result = new cbxp_result_t();
+  CBXP::Logger::getInstance().debugAllocate(p_cbxp_result, 64,
+                                            sizeof(cbxp_result_t));
+
+  CBXP::ControlBlockExplorer explorer =
+      CBXP::ControlBlockExplorer(p_cbxp_result);
+
+  explorer.extractControlBlock(control_block_name_string,
+                               includes_string_string, filters_string_string);
+
+  return p_cbxp_result;
+}
+
+cbxp_result_t* cbxp_format(const char* control_block_name,
+                           const size_t control_block_name_length,
+                           const void* data, const size_t data_length,
+                           bool debug) {
+  std::string control_block_name_string;
+
+  if (control_block_name != nullptr) {
+    control_block_name_string.assign(control_block_name,
+                                     control_block_name_length);
   }
 
   CBXP::Logger::getInstance().setDebug(debug);
@@ -34,9 +60,7 @@ cbxp_result_t* cbxp(const char* control_block, const char* includes_string,
   CBXP::ControlBlockExplorer explorer =
       CBXP::ControlBlockExplorer(p_cbxp_result);
 
-  explorer.exploreControlBlock(control_block_cpp_string,
-                               includes_string_cpp_string,
-                               filters_string_cpp_string);
+  explorer.formatControlBlock(control_block_name_string, data, data_length);
 
   return p_cbxp_result;
 }