From 450a4e57840ec0bec1f42140057bd72ebe676c5b Mon Sep 17 00:00:00 2001 From: Leonard Carcaramo Date: Fri, 22 May 2026 15:10:13 -0400 Subject: [PATCH 1/6] Start 0.0.4 doc updates Signed-off-by: Leonard Carcaramo --- Gemfile.lock | 92 +++++----- _config.yml | 6 +- filters.md | 32 ++-- include_patterns.md | 30 ++-- index.md | 21 ++- interfaces/c_cpp.md | 323 +++++++++++++++++++++++++++++------- interfaces/cli.md | 138 +++++++++++++++ interfaces/python.md | 92 ++++++++-- interfaces/shell.md | 74 --------- release_notes.md | 3 + supported_control_blocks.md | 6 +- 11 files changed, 581 insertions(+), 236 deletions(-) create mode 100644 interfaces/cli.md delete mode 100644 interfaces/shell.md diff --git a/Gemfile.lock b/Gemfile.lock index 8b9bcce..b21db2e 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,34 +1,33 @@ GEM remote: https://rubygems.org/ specs: - activesupport (8.0.3) + activesupport (8.1.3) base64 - benchmark (>= 0.3) bigdecimal concurrent-ruby (~> 1.0, >= 1.3.1) connection_pool (>= 2.2.5) drb i18n (>= 1.6, < 2) + json logger (>= 1.4.2) minitest (>= 5.1) securerandom (>= 0.3) tzinfo (~> 2.0, >= 2.0.5) uri (>= 0.13.1) - addressable (2.8.7) - public_suffix (>= 2.0.2, < 7.0) + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) base64 (0.3.0) - benchmark (0.4.1) - bigdecimal (3.2.3) + bigdecimal (4.1.2) coffee-script (2.4.1) coffee-script-source execjs coffee-script-source (1.12.2) colorator (1.1.0) commonmarker (0.23.12) - concurrent-ruby (1.3.5) - connection_pool (2.5.4) + concurrent-ruby (1.3.6) + connection_pool (3.0.2) csv (3.3.5) - dnsruby (1.73.0) + dnsruby (1.73.1) base64 (>= 0.2) logger (~> 1.6) simpleidn (~> 0.2.1) @@ -36,24 +35,25 @@ GEM em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) - ethon (0.15.0) + ethon (0.18.0) ffi (>= 1.15.0) + logger eventmachine (1.2.7) - execjs (2.10.0) - faraday (2.14.0) + execjs (2.10.1) + faraday (2.14.2) faraday-net_http (>= 2.0, < 3.5) json logger - faraday-net_http (3.4.1) - net-http (>= 0.5.0) - ffi (1.17.2-aarch64-linux-gnu) - ffi (1.17.2-aarch64-linux-musl) - ffi (1.17.2-arm-linux-gnu) - ffi (1.17.2-arm-linux-musl) - ffi (1.17.2-arm64-darwin) - ffi (1.17.2-x86_64-darwin) - ffi (1.17.2-x86_64-linux-gnu) - ffi (1.17.2-x86_64-linux-musl) + faraday-net_http (3.4.2) + net-http (~> 0.5) + ffi (1.17.4-aarch64-linux-gnu) + ffi (1.17.4-aarch64-linux-musl) + ffi (1.17.4-arm-linux-gnu) + ffi (1.17.4-arm-linux-musl) + ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x86_64-darwin) + ffi (1.17.4-x86_64-linux-gnu) + ffi (1.17.4-x86_64-linux-musl) forwardable-extended (2.6.0) gemoji (4.1.0) github-pages (232) @@ -111,8 +111,8 @@ GEM html-pipeline (2.14.3) activesupport (>= 2) nokogiri (>= 1.4) - http_parser.rb (0.8.0) - i18n (1.14.7) + http_parser.rb (0.8.1) + i18n (1.14.8) concurrent-ruby (~> 1.0) jekyll (3.10.0) addressable (~> 2.4) @@ -224,8 +224,8 @@ GEM gemoji (>= 3, < 5) html-pipeline (~> 2.2) jekyll (>= 3.0, < 5.0) - json (2.15.0) - just-the-docs (0.10.1) + json (2.19.5) + just-the-docs (0.12.0) jekyll (>= 3.8.5) jekyll-include-cache jekyll-seo-tag (>= 2.0) @@ -235,7 +235,8 @@ GEM kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) liquid (4.0.4) - listen (3.9.0) + listen (3.10.0) + logger rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) logger (1.7.0) @@ -244,33 +245,36 @@ GEM jekyll (>= 3.5, < 5.0) jekyll-feed (~> 0.9) jekyll-seo-tag (~> 2.1) - minitest (5.25.5) - net-http (0.6.0) - uri - nokogiri (1.18.10-aarch64-linux-gnu) + minitest (6.0.6) + drb (~> 2.0) + prism (~> 1.5) + net-http (0.9.1) + uri (>= 0.11.1) + nokogiri (1.19.3-aarch64-linux-gnu) racc (~> 1.4) - nokogiri (1.18.10-aarch64-linux-musl) + nokogiri (1.19.3-aarch64-linux-musl) racc (~> 1.4) - nokogiri (1.18.10-arm-linux-gnu) + nokogiri (1.19.3-arm-linux-gnu) racc (~> 1.4) - nokogiri (1.18.10-arm-linux-musl) + nokogiri (1.19.3-arm-linux-musl) racc (~> 1.4) - nokogiri (1.18.10-arm64-darwin) + nokogiri (1.19.3-arm64-darwin) racc (~> 1.4) - nokogiri (1.18.10-x86_64-darwin) + nokogiri (1.19.3-x86_64-darwin) racc (~> 1.4) - nokogiri (1.18.10-x86_64-linux-gnu) + nokogiri (1.19.3-x86_64-linux-gnu) racc (~> 1.4) - nokogiri (1.18.10-x86_64-linux-musl) + nokogiri (1.19.3-x86_64-linux-musl) racc (~> 1.4) octokit (4.25.1) faraday (>= 1, < 3) sawyer (~> 0.9) pathutil (0.16.2) forwardable-extended (~> 2.6) + prism (1.9.0) public_suffix (5.1.1) racc (1.8.1) - rake (13.3.0) + rake (13.4.2) rb-fsevent (0.11.2) rb-inotify (0.11.1) ffi (~> 1.0) @@ -283,20 +287,20 @@ GEM sass-listen (4.0.0) rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.9.2) + sawyer (0.9.3) addressable (>= 2.3.5) faraday (>= 0.17.3, < 3) securerandom (0.4.1) simpleidn (0.2.3) terminal-table (1.8.0) unicode-display_width (~> 1.1, >= 1.1.1) - typhoeus (1.5.0) - ethon (>= 0.9.0, < 0.16.0) + typhoeus (1.6.0) + ethon (>= 0.18.0) tzinfo (2.0.6) concurrent-ruby (~> 1.0) unicode-display_width (1.8.0) - uri (1.0.3) - webrick (1.9.1) + uri (1.1.1) + webrick (1.9.2) PLATFORMS aarch64-linux-gnu diff --git a/_config.yml b/_config.yml index e90534c..7fd5490 100644 --- a/_config.yml +++ b/_config.yml @@ -15,9 +15,9 @@ title: CBXP -cbxp_version: 0.0.3 +cbxp_version: 0.0.4 description: >- # this means to ignore newlines until "baseurl:" - 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. permalink: /:title/ logo: "/assets/images/logo.svg" @@ -72,7 +72,7 @@ callouts: mermaid: # Version of mermaid library # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ - version: "11.13.0" + version: "11.15.0" # Exclude from processing. # The following items will not be processed, by default. diff --git a/filters.md b/filters.md index 419f62b..ebff86b 100644 --- a/filters.md +++ b/filters.md @@ -10,7 +10,7 @@ How to use filters to filter repeated control block data.   -Some control blocks like the [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) are **Repeated**. When extracting these **Repeated** control blocks, you may want to only extract the entries that match one or more **Filters**. CBXP allows **Filters** to be provided when extracting **Repeated** control block data. +Some control blocks like the [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) are **Repeated**. When extracting these **Repeated** control blocks from **Live Memory**, you may want to only extract the entries that match one or more **Filters**. CBXP allows **Filters** to be provided when extracting **Repeated** control block data from **Live Memory**. ## Filter Basics @@ -20,13 +20,13 @@ Some control blocks like the [ASCB](https://www.ibm.com/docs/en/zos/latest?topic   -The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks where the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER`. +The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER`. ###### Python Script ```python from cbxp import CBXPFilter, CBXPFilterOperation, cbxp -cbdata = cbxp( +cbdata = cbxp.extract( "assb", filters=[ CBXPFilter( @@ -40,7 +40,7 @@ cbdata = cbxp( ###### Shell Script ```shell -cbxp -f assbjbni=IBMUSER assb +cbxp extract -f assbjbni=IBMUSER assb ``` ## Using Multiple Filters @@ -51,13 +51,13 @@ Multiple **Filters** can be used.   -The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks where both the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER` and the **Control Block Field** `ASSBJBNS` matches the **Filter Value** `BPXAS`. +The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where both the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER` and the **Control Block Field** `ASSBJBNS` matches the **Filter Value** `BPXAS`. ###### Python Script ```python from cbxp import CBXPFilter, CBXPFilterOperation, cbxp -cbdata = cbxp( +cbdata = cbxp.extract( "assb", filters=[ CBXPFilter( @@ -76,7 +76,7 @@ cbdata = cbxp( ###### Shell Script ```shell -cbxp -f assbjbni=IBMUSER -f assbjbns=BPXAS ascb +cbxp extract -f assbjbni=IBMUSER -f assbjbns=BPXAS ascb ``` ## Using Filters With Include Patterns @@ -87,13 +87,13 @@ cbxp -f assbjbni=IBMUSER -f assbjbns=BPXAS ascb   -The following example extracts all [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) and corresponding [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks where the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER`. +The following example extracts all [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) and corresponding [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER`. ###### Python Script ```python from cbxp import CBXPFilter, CBXPFilterOperation, cbxp -cbdata = cbxp( +cbdata = cbxp.extract( "ascb", includes=["assb"], filters=[ @@ -108,7 +108,7 @@ cbdata = cbxp( ###### Shell Script ```shell -cbxp -i assb -f assb.assbjbni=IBMUSER ascb +cbxp extract -i assb -f assb.assbjbni=IBMUSER ascb ``` ## Using Filters With `fnmatch` Patterns @@ -119,13 +119,13 @@ cbxp -i assb -f assb.assbjbni=IBMUSER ascb   -The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks where the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER*`. +The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER*`. ###### Python Script ```python from cbxp import CBXPFilter, CBXPFilterOperation, cbxp -cbdata = cbxp( +cbdata = cbxp.extract( "assb", filters=[ CBXPFilter( @@ -139,7 +139,7 @@ cbdata = cbxp( ###### Shell Script ```shell -cbxp -f 'assbjbni=IBMUSER*' assb +cbxp extract -f 'assbjbni=IBMUSER*' assb ``` ## Filtering Numeric Data @@ -150,13 +150,13 @@ cbxp -f 'assbjbni=IBMUSER*' assb   -The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks where the **Control Block Field** `ASSB_TIME_ON_CP` is **Less Than** `30000`. +The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where the **Control Block Field** `ASSB_TIME_ON_CP` is **Less Than** `30000`. ###### Python Script ```python from cbxp import CBXPFilter, CBXPFilterOperation, cbxp -cbdata = cbxp( +cbdata = cbxp.extract( "assb", filters=[ CBXPFilter( @@ -169,5 +169,5 @@ cbdata = cbxp( ###### Shell Script ```shell -cbxp -f 'assb_time_on_cp<3000' assb +cbxp extract -f 'assb_time_on_cp<3000' assb ``` diff --git a/include_patterns.md b/include_patterns.md index edd171a..f7a32d6 100644 --- a/include_patterns.md +++ b/include_patterns.md @@ -25,7 +25,7 @@ How to use include patterns to include additional control blocks.   {: .warning } -> _When using the [Shell Interface](../interfaces/shell) for CBXP, ensure that **Include Patterns** that contain **Wildcards** are surrounded with quotes._ +> _When using the [CLI Interface](../interfaces/cli) for CBXP, ensure that **Include Patterns** that contain **Wildcards** are surrounded with quotes._ > >   > @@ -43,7 +43,7 @@ How to use include patterns to include additional control blocks.   -**Include Patterns** provide a method for including **Additional Control Blocks** that can be found from the **Root Control Block** being extracted. +**Include Patterns** provide a method for including **Additional Control Blocks** that can be found from the **Root Control Block** being extracted when extracting control block data from **Live Memory**. ## Include Pattern Basics @@ -57,18 +57,18 @@ In the following example, `psa` is the **Root Control Block** and `cvt.ecvt` is   -The following example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information), includes the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information), and includes the [ECVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-ecvt-information) with the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information). +The following example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block from **Live Memory**, includes the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block, and includes the [ECVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-ecvt-information) control block with the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block. ###### Python Script ```python from cbxp import cbxp -cbdata = cbxp("psa", includes=["cvt.ecvt"]) +cbdata = cbxp.extract("psa", includes=["cvt.ecvt"]) ``` ###### Shell Script -```python -cbxp -i cvt.ecvt psa +```shell +cbxp extract -i cvt.ecvt psa ```   @@ -88,7 +88,7 @@ cbxp -i cvt.ecvt psa   -The following example extracts the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information), and includes the [ECVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-ecvt-information) and the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information). +The following example extracts the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block from **Live Memory**, and includes the [ECVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-ecvt-information) control block and the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information) control block. ###### Python Script ```python @@ -98,7 +98,7 @@ cbdata = cbxp("cvt", includes=["ecvt", "asvt"]) ``` ###### Shell Script -```python +```shell cbxp -i ecvt -i asvt cvt ``` @@ -119,18 +119,18 @@ CBXP also supports **Wildcarding**. Coding `*` at the very end of your include p   -The following example extracts the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) and includes all **Known Control Blocks** that are pointed to directly by it. Additionally, `asvt.*` causes the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information) and all **Known Control Blocks** that are pointed to directly by the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information) to also be included. +The following example extracts the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block from **Live Memory** and includes all **Known Control Blocks** that are pointed to directly by it. Additionally, `asvt.*` causes the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information) control block and all **Known Control Blocks** that are pointed to directly by the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information) to also be included. ###### Python Script ```python from cbxp import cbxp -cbdata = cbxp("cvt", includes=["*", "asvt.*"]) +cbdata = cbxp.extract("cvt", includes=["*", "asvt.*"]) ``` ###### Shell Script -```python -cbxp -i "*" -i "asvt.*" cvt +```shell +cbxp extract -i "*" -i "asvt.*" cvt ```   @@ -156,18 +156,18 @@ cbxp -i "*" -i "asvt.*" cvt   -The following example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information), includes the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information), and includes **All Known Control Blocks** that can be found starting from the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information). +The following example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block from **Live Memory**, includes the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block, and includes **All Known Control Blocks** that can be found starting from the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block. ###### Python Script ```python from cbxp import cbxp -cbdata = cbxp("psa", includes=["cvt.**"]) +cbdata = cbxp.extract("psa", includes=["cvt.**"]) ``` ###### Shell Script ```python -cbxp -i "cvt.**" psa +cbxp extract -i "cvt.**" psa ```   diff --git a/index.md b/index.md index adf5283..51cad85 100644 --- a/index.md +++ b/index.md @@ -17,7 +17,7 @@ has_toc: false ## Mission Statement -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.   @@ -25,7 +25,7 @@ CBXP is the successor to the existing [cbxplorer](https://github.com/ambitus/cbe ## 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. @@ -40,13 +40,13 @@ 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](./interfaces/python) -* [Shell Interface](./interfaces/shell) +* [CLI Interface](./interfaces/cli) * [C/C++ Interface](./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](./supported_control_blocks) for more details. +Currently, CBXP only has support for extracting and formatting a handful of **System-Level Control Blocks** from **Live Memory**. See [Supported Control Blocks](./supported_control_blocks) for more details. ## Architecture @@ -57,16 +57,19 @@ Currently, CBXP only has support for extracting a handful of **System-Level Cont flowchart LR python(Python Interface) ---CBXP style python fill:#ffcb3c,color:#000,stroke:#ffcb3c - shell(Shell Interface) ---CBXP - style shell fill:#33cc22,color:#000,stroke:#33cc22 + cli(CLI Interface) ---CBXP + style cli fill:#33cc22,color:#000,stroke:#33cc22 C(C/C++ Interface) ---CBXP style C fill:#01559e,color:#fff,stroke:#01559e subgraph C/C+ CBXP(["CBXP (64-bit XPLINK ASCII)"]) style CBXP fill:#0096ff,color:#fff,stroke:#0096ff end - subgraph "Live Memory (Storage)" - CBXP--- control_blocks_storage@{ shape: procs, label: "Control Blocks"} - style control_blocks_storage color:#fff,stroke:#fff + CBXP--- Extract + CBXP--- Format + Extract ---control_blocks_memory + subgraph "Live Memory" + control_blocks_memory@{ shape: procs, label: "Control Blocks"} + style control_blocks_memory color:#fff,stroke:#fff end diff --git a/interfaces/c_cpp.md b/interfaces/c_cpp.md index 385701f..efd56a3 100644 --- a/interfaces/c_cpp.md +++ b/interfaces/c_cpp.md @@ -12,25 +12,34 @@ The following C/C++ interface is provided to facilitate exploitation of CBXP by   {: .note } -> _The **C/C++** interface for CBXP downloaded from [GitHub](https://github.com/ambitus/cbxp/releases)._ +> _The **C/C++** interface for CBXP can be installed from [zopen community](https://github.com/zopencommunity/cbxpport) using the [`zopen`](https://zopen.community/Guides/ThePackageManager) package manager._ +> +>
+> +> ```shell +> zopen install cbxp +> ``` +> _The **C/C++** interface for CBXP may also optionally be downloaded from [GitHub](https://github.com/ambitus/cbxp/releases)._   {: .note } -> _The **CBXP PAX** provides a **Static Library** for CBXP at `/lib/libcbxp.a` and a **C Header** for CBXP at `/include/cbxp.h`. To compile code that uses the **C/C++** interface for CBXP, **Include** `/include/cbxp.h` at **Compile Time** and **Link** with `/lib/libcbxp.a`._ +> _A `libcbxp.a` **Static Library** and `cbxp.h` **C Header** are provided for use by C/C++ callers. To compile code that uses the **C/C++** interface for CBXP, **Include** `cbxp.h` at **Compile Time** and **Link** with `libcbxp.a`._   {: .note } -> _When compiling and linking **C/C++** code with `/lib/libcbxp.a`, it is recommended to use [IBM Open XL C/C++ 2.2](https://www.ibm.com/docs/en/open-xl-c-cpp-zos/2.2.0) or newer. See [Binary Compatibility](https://www.ibm.com/docs/en/open-xl-c-cpp-zos/2.2.0?topic=guide-binary-compatibility) for more details._ +> _When compiling and linking **C/C++** code with `libcbxp.a`, it is recommended to use [IBM Open XL C/C++ 2.2](https://www.ibm.com/docs/en/open-xl-c-cpp-zos/2.2.0) or newer. See [Binary Compatibility](https://www.ibm.com/docs/en/open-xl-c-cpp-zos/2.2.0?topic=guide-binary-compatibility) for more details._ -  -## `cbxp()` +## `cbxp_extract()` ```c -cbxp_result_t* cbxp(const char* control_block, const char* includes_string, - const char* filters_string, bool debug); +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); ``` ### 📄 Description @@ -38,25 +47,68 @@ cbxp_result_t* cbxp(const char* control_block, const char* includes_string,   {: .note } -> _`includes_string` and `filters_string` are **Optional Parameters** that can be excluded by specifying `NULL` or `nullptr`._ +> _`includes` and `filters` are **Optional Parameters** that can be excluded by specifying `NULL` or `nullptr`._   -Extract **Control Blocks** from **Live Memory** *(storage)* and post-process them into **JSON**. +Extract and format **Control Block Data** from **Live Memory**. ### 📥 Parameters -* `control_block`
- A **NULL-Terminated ISO8859-1 Encoded String** that contains name of the **Control Block** to extract. +* `control_block_name`
+ A pointer to a **NULL-Terminated ISO8859-1 Encoded String** that contains name of the **Control Block** to extract. + +* `control_block_name_length`
+ The length of `control_block_name`. + +* `includes`
+ A pointer to a **NULL-Terminated ISO8859-1 Encoded String** that contains a **Comma Delimited List** of [Include Patterns](../../include_patterns) that describe **Additional Control Blocks** to include that are accessible from the **Root Control Block** being extracted. -* `includes_string`
- A **NULL-Terminated ISO8859-1 Encoded String** that contains a **Comma Delimited List** of [Include Patterns](../../include_patterns) that describe **Additional Control Blocks** to include that are accessible from the **Root Control Block** being extracted. +* `includes_length`
+ The length of `includes`. -* `filters_string`
- A **NULL-Terminated ISO8859-1 Encoded String** that contains a **Comma Delimited List** of [Filters](../../filters) that are used to filter the entries returned in **Repeated** control block data. +* `filters`
+ A pointer to a **NULL-Terminated ISO8859-1 Encoded String** that contains a **Comma Delimited List** of [Filters](../../filters) that are used to filter the entries returned in **Repeated** control block data. + +* `filters_length`
+ The length of `filters`. * `debug`
- A **Boolean** that if set to `true` indicates that **Debug Messages** should be printed. If set to `false`, no **Debug Messages** will be printed. + A **Boolean** that if set to `true`, indicates that **Debug Messages** should be printed. If set to `false`, no **Debug Messages** will be printed. + +### 📤 Returns +* `cbxp_result_t*`
+ A pointer to a [`cbxp_result_t`](#cbxp_result_t) **C Struct**. + +## `cbxp_format()` + +```c +cbxp_result_t* cbxp_format(const char* control_block_name, + const size_t control_block_name_length, + const void* p_data, const size_t data_length, + bool debug); +``` + +### 📄 Description + +Format **Caller-Provided Control Block Data**. + +### 📥 Parameters + +* `control_block_name`
+ A pointer to a **NULL-Terminated ISO8859-1 Encoded String** that contains name of the **Control Block** to format. + +* `control_block_name_length`
+ The length of `control_block_name`. + +* `data`
+ A pointer to a **Buffer** containing **Raw Control Block Data** to format. + +* `data_length`
+ The length of `data`. + +* `debug`
+ A **Boolean** that if set to `true`, indicates that **Debug Messages** should be printed. If set to `false`, no **Debug Messages** will be printed. ### 📤 Returns * `cbxp_result_t*`
@@ -77,7 +129,7 @@ void cbxp_free(cbxp_result_t* cbxp_result, bool debug);   -Free all **Dynamically Allocated Memory** associated with a [`cbxp_result_t`](#cbxp_result_t) pointer returned by `cbxp()`. +Free all **Dynamically Allocated Memory** associated with a [`cbxp_result_t`](#cbxp_result_t) pointer returned by `cbxp_extract()` / `cbxp_format()`. ### 📥 Parameters @@ -85,7 +137,7 @@ Free all **Dynamically Allocated Memory** associated with a [`cbxp_result_t`](#c A pointer to a [`cbxp_result_t`](#cbxp_result_t) **C Struct**. * `debug`
- A **Boolean** that if set to `true` indicates that **Debug Messages** should be printed. If set to `false`, no **Debug Messages** will be printed. + A **Boolean** that if set to `true`, indicates that **Debug Messages** should be printed. If set to `false`, no **Debug Messages** will be printed. ### 📤 Returns * `void`
@@ -97,74 +149,84 @@ Free all **Dynamically Allocated Memory** associated with a [`cbxp_result_t`](#c typedef struct { char* result_json; int result_json_length; - int return_code; + unsigned int return_code; } cbxp_result_t; ``` ### 📄 Description -The **C Struct** that is used to store all **Result Information** returned by CBXP. +The **C Struct** that is used to store all **Result Information** returned by [`cbxp_extract()`](#cbxp_extract) and [`cbxp_format()`](#cbxp_format). ### 📋 Fields * `result_json`
- When the call to `cbxp()` is **Successful**, this field contains pointer to a **NULL-Terminated ISO8859-1 Encoded JSON String**. When the call to `cbxp()` is **Unsucessful**, this field contains a **NULL Pointer**. + When the call to `cbxp_extract()` / `cbxp_format()` is **Successful**, this field contains pointer to a **NULL-Terminated ISO8859-1 Encoded JSON String**. When the call to `cbxp_extract()` / `cbxp_format()` is **Unsucessful**, this field contains a **NULL Pointer**. * `result_json_length`
- When the call to `cbxp()` is **Successful**, this field contains the length of the **NULL-Terminated ISO8859-1 Encoded JSON String** stored in the `result_json` field. When the call to `cbxp()` is **Unsuccessful**, this field contains `0`. + When the call to `cbxp_extract()` / `cbxp_format()` is **Successful**, this field contains the length of the **NULL-Terminated ISO8859-1 Encoded JSON String** stored in the `result_json` field. When the call to `cbxp_extract()` / `cbxp_format()` is **Unsuccessful**, this field contains `0`. * `return_code`
- This field will be set by `cbxp()` to one of the following values: + This field will be set by `cbxp_extract()` / `cbxp_format()` to one of the following values: * ✅ `0`
- The call to `cbxp()` was **Successful**. + The call to `cbxp_extract()` / `cbxp_format()` was **Successful**. * ❌ `1`
- The call to `cbxp()` was **Unsuccessful** due to an **Unknown Control Block** being specified with the `control_block` parameter. + The call to `cbxp_extract()` / `cbxp_format()` was **Unsuccessful** due to an **Unknown Control Block** being specified with the `control_block_name` parameter. * ❌ `2`
- The call to `cbxp()` was **Unsuccessful** due to a bad [Include Pattern](../../include_patterns) being specified within the `includes_string` parameter. + The call to `cbxp_extract()` was **Unsuccessful** due to a bad [Include Pattern](../../include_patterns) being specified within the `includes` parameter. * ❌ `3`
- The call to `cbxp()` was **Unsuccessful** due to a bad [Filter](../../filters) being specified within the `filters_string` parameter. + The call to `cbxp_extract()` was **Unsuccessful** due to a bad [Filter](../../filters) being specified within the `filters` parameter. + * ❌ `4`
+ The call to `cbxp_format()` was **Unsuccessful** due to the data provided in the `data` parameter being too small to format the specified control block from. + * ❌ `5`
+ The call to `cbxp_format()` was **Unsuccessful** due to the `data` parameter being a **NULL** pointer. ## 💻 Examples   {: .note } -> _The following examples assume that the **CBXP PAX** is extracted in the **Current Working Directory**._ +> _The following examples assumes that CBXP was installed from [zopen community](https://github.com/zopencommunity/cbxpport) using the [`zopen`](https://zopen.community/Guides/ThePackageManager) package manager._ >

> ``` -> . -> |-- cbxp-{{ site.cbxp_version }} -> | |-- LICENSE -> | |-- NOTICES -> | |-- bin -> | | `-- cbxp -> | |-- include -> | | `-- cbxp.h -> | `-- lib -> | `-- libcbxp.a -> |-- cbxp-{{ site.cbxp_version }}.pax.Z -> |-- main.c -> |-- main.cpp +> /usr/local/zopen/usr/local/zopen/cbxp/cbxp/ +> |-- LICENSE +> |-- NOTICES +> |-- README.md +> |-- altbin +> |-- bin +> | `-- cbxp +> |-- include +> | `-- cbxp.h +> |-- install_test.sh +> |-- lib +> | `-- libcbxp.a +> |-- metadata.json +> |-- setup.sh +> |-- share +> | `-- altman +> | `-- man1 +> `-- test.status +> +> 8 directories, 10 files > ```   -The following **C** example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block and prints the returned **JSON String**. +The following **C** example uses [`cbxp_extract()`](#cbxp_extract) to extract and format the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block from **Live Memory**, and prints the returned **JSON String**. ###### C ```c #include -#include #include int main() { - // Call CBXP - puts("Calling CBXP from C..."); - cbxp_result_t* cbxp_result = cbxp("psa", NULL, NULL, false); + // Call 'cbxp_extract()' + puts("Calling 'cbxp_extract()' from C..."); + cbxp_result_t* cbxp_result = cbxp_extract("psa", 3, NULL, 0, NULL, 0, false); // Make sure call was successful if (cbxp_result->return_code != 0) { - fprintf(stderr, "Error: CBXP return with RC=%d\n", cbxp_result->return_code); + fprintf(stderr, "Error: 'cbxp_extract()' returned with rc=%d\n", cbxp_result->return_code); // Print Result JSON } else { puts(cbxp_result->result_json); @@ -180,16 +242,19 @@ int main() { ###### Shell ```shell # Compile -ibm-clang64 -c -fzos-le-char-mode=ascii -I./cbxp-{{ site.cbxp_version }}/include -o main.o main.c +ibm-clang64 -c -fzos-le-char-mode=ascii \ + -I /usr/local/zopen/usr/local/zopen/cbxp/cbxp/include \ + -o extract.o extract.c # Link -ibm-clang++64 -fzos-le-char-mode=ascii -o main ./cbxp-{{ site.cbxp_version }}/lib/libcbxp.a main.o +ibm-clang++64 -fzos-le-char-mode=ascii -o extract \ + /usr/local/zopen/usr/local/zopen/cbxp/cbxp/lib/libcbxp.a extract.o # Run -./main +./extract ```   -The following **C++** example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block and prints the returned **JSON String**. +The following **C++** example uses [`cbxp_extract()`](#cbxp_extract) to extract and format the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block from **Live Memory**, and prints the returned **JSON String**. ###### C++ ```cpp @@ -198,13 +263,152 @@ The following **C++** example extracts the [PSA](https://www.ibm.com/docs/en/zos #include int main() { - // Call CBXP - std::cout << "Calling CBXP from C++..." << std::endl; - cbxp_result_t * cbxp_result = cbxp("psa", nullptr, nullptr, false); + // Call 'cbxp_extract()' + std::cout << "Calling 'cbxp_extract()' from C++..." << std::endl; + cbxp_result_t * cbxp_result = cbxp_extract("psa", 3, nullptr, 0, nullptr, 0, false); + + // Make sure call was successful + if (cbxp_result->return_code != 0) { + std::cerr << "Error: 'cbxp_extract()' returned with rc=" + << cbxp_result->return_code << std::endl; + // Print result JSON + } else { + std::cout << cbxp_result->result_json << std::endl; + } + + // Cleanup + cbxp_free(cbxp_result, false); + + return 0; +} +``` + +###### Shell +```shell +# Compile +ibm-clang++64 -c -fzos-le-char-mode=ascii \ + -I /usr/local/zopen/usr/local/zopen/cbxp/cbxp/include \ + -o extract.o extract.cpp +# Link +ibm-clang++64 -fzos-le-char-mode=ascii -o extract \ + /usr/local/zopen/usr/local/zopen/cbxp/cbxp/lib/libcbxp.a extract.o +# Run +./extract +``` + +  + +The following **C** example uses [`cbxp_format()`](#cbxp_format) to format **Caller-Provided** [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) control block data and prints the returned **JSON String**. + +###### C +```c +#include +#include +#include + +int main() { + // Open ascb.bin + FILE *fp = fopen("ascb.bin", "rb"); + if (fp == NULL) { + fprintf(stderr, "Error: ascb.bin not found\n"); + return -1; + } + + // Get size of ascb.bin + fseek(fp,0,SEEK_END); + long size = ftell(fp); + fseek(fp,0,SEEK_SET); + + // Allocate memory to load control block data + void* data = malloc(size); + if (data == NULL) { + fprintf(stderr, "Error: unable to allocate memory to load control block data\n"); + fclose(fp); + return -1; + } + + // Read control block data + fread(data, sizeof(void), size, fp); + + // Close file + fclose(fp); + + // Call 'cbxp_format()' + puts("Calling 'cbxp_format()' from C..."); + cbxp_result_t* cbxp_result = cbxp_format("ascb", 4, data, size, false); + + // Make sure call was successful + if (cbxp_result->return_code != 0) { + fprintf(stderr, "Error: 'cbxp_format()' returned with rc=%d\n", cbxp_result->return_code); + // Print Result JSON + } else { + puts(cbxp_result->result_json); + } + + // Cleanup + cbxp_free(cbxp_result, false); + free(data); + + return 0; +} +``` + +###### Shell +```shell +# Compile +ibm-clang64 -c -fzos-le-char-mode=ascii \ + -I /usr/local/zopen/usr/local/zopen/cbxp/cbxp/include \ + -o format.o format.c +# Link +ibm-clang++64 -fzos-le-char-mode=ascii -o format \ + /usr/local/zopen/usr/local/zopen/cbxp/cbxp/lib/libcbxp.a format.o +# Run +./format +``` + +  + +The following **C++** example uses [`cbxp_format()`](#cbxp_format) to format **Caller-Provided** [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) control block data and prints the returned **JSON String**. + +###### C++ +```cpp +#include +#include + +#include + +int main() { + // Open ascb.bin + std::ifstream file("ascb.bin", std::ios::binary | std::ios::ate); + if (!file.is_open()) { + std::cerr << "Error: ascb.bin not found" << std::endl; + return -1; + } + + // Get size of ascb.bin + std::streamsize size = file.tellg(); + file.seekg(0, std::ios::beg); + + // Create vector to store control block data + std::vector data; + data.resize(size); + + // Read control block data + file.read(data.data(), size); + + // Close file + file.close(); + + // Call 'cbxp_format()' + std::cout << "Calling 'cbxp_format()' from C++..." << std::endl; + cbxp_result_t * cbxp_result = cbxp_format("ascb", 4, + static_cast(data.data()), + size, false); // Make sure call was successful if (cbxp_result->return_code != 0) { - std::cerr << "Error: CBXP returned with RC=" << cbxp_result->return_code << std::endl; + std::cerr << "Error: 'cbxp_format()' returned with rc=" + << cbxp_result->return_code << std::endl; // Print result JSON } else { std::cout << cbxp_result->result_json << std::endl; @@ -220,9 +424,12 @@ int main() { ###### Shell ```shell # Compile -ibm-clang++64 -c -fzos-le-char-mode=ascii -I./cbxp-{{ site.cbxp_version }}/include -o main.o main.cpp +ibm-clang++64 -c -fzos-le-char-mode=ascii \ + -I /usr/local/zopen/usr/local/zopen/cbxp/cbxp/include \ + -o format.o format.cpp # Link -ibm-clang++64 -fzos-le-char-mode=ascii -o main ./cbxp-{{ site.cbxp_version }}/lib/libcbxp.a main.o +ibm-clang++64 -fzos-le-char-mode=ascii -o format \ + /usr/local/zopen/usr/local/zopen/cbxp/cbxp/lib/libcbxp.a format.o # Run -./main +./format ``` \ No newline at end of file diff --git a/interfaces/cli.md b/interfaces/cli.md new file mode 100644 index 0000000..d974a30 --- /dev/null +++ b/interfaces/cli.md @@ -0,0 +1,138 @@ +--- +layout: default +parent: Interfaces +nav_order: 2 +--- + +# CLI + +The following CLI interface is provided to facilitate exploitation of CBXP by shell callers. +{: .fs-6 .fw-300 } + +  + +{: .note } +> _The **CLI** interface for CBXP can be installed from [zopen community](https://github.com/zopencommunity/cbxpport) using the [`zopen`](https://zopen.community/Guides/ThePackageManager) package manager._ +> +>
+> +> ```shell +> zopen install cbxp +> ``` +> _The **CLI** interface for CBXP may also optionally be downloaded from [GitHub](https://github.com/ambitus/cbxp/releases)._ + +  + +## `cbxp extract` + +``` +cbxp extract [flags] +``` + +### 📄 Description + +Extract and format **Control Block Data** from **Live Memory**. + +### 🚩 Flags + +* `-i`, `--include `
+ **Include** control blocks that are **Accessible** from the **Root Control Block** being extracted using an [Include Pattern](../../include_patterns). + +* `-f`, `--filter`
+ **Filter** repeated control block data using a [Filter](../../filters). + +### 🌐 Global Flags + +* `-d`, `--debug`
+ Print **Debug Messages**. + +* `-h`, `--help`
+ Display **Usage Information**. + +### 💻 Examples + +The following example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block from **Live Memory** and prints **Debug Messages**. + +###### Shell Script +```shell +cbxp extract -d psa +``` + +  + +The following example extracts the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block from **Live Memory**, includes the [ECVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-ecvt-information) control block and the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information) control block, and includes all **Known Control Blocks** that are pointed to directly by the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information) control block. + +###### Shell Script +```shell +cbxp extract -i ecvt -i 'asvt.*' cvt +``` + +  + +The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where both the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER` and the **Control Block Field** `ASSBJBNS` matches the **Filter Value** `BPXAS`. The output is then piped into `jq` to **Format** it. + +###### Shell Script +```shell +cbxp extract -f assb.assbjbni=IBMUSER assb | jq +``` + +## `cbxp format` +``` +cbxp format [flags] +``` + +### 📄 Description + +Format **Control Block Data** from a **File/Pipe**. + +### 🚩 Flags + +* `-F`, `--file `
+ Format control block data from a specified **File** or **Pipe**. + +* `-o`, `--offset `
+ Specify an **Offset** into the provided data to start formatting at. + +### 🌐 Global Flags + +* `-d`, `--debug`
+ Print **Debug Messages**. + +* `-h`, `--help`
+ Display **Usage Information**. + +### 💻 Examples + +The following example formats [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block data from a **File** and prints **Debug Messages**. + +###### Shell Script +```shell +cbxp format -F cvt.bin -d cvt +``` + +  + +The following example formats [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block data from a **Pipe**. + +###### Shell Script +```shell +cat cvt.bin | cbxp format cvt +``` + +  + +The following example formats [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) control block data from a **File** at an offset of **0x40** bytes. + +###### Shell Script +```shell +cbxp format -F ascboffset.bin -o 0x40 ascb +``` + +  + +The following example formats [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) control block data from a **File** at an offset of **64** bytes. + +###### Shell Script +```shell +cbxp format -F ascboffset.bin -o 64 ascb +``` diff --git a/interfaces/python.md b/interfaces/python.md index 3743eda..5cb47d5 100644 --- a/interfaces/python.md +++ b/interfaces/python.md @@ -21,19 +21,19 @@ The following Python interface is provided to facilitate exploitation of CBXP by > ``` > _The **Python Interface** for CBXP may also optionally be downloaded from [GitHub](https://github.com/ambitus/cbxp/releases)._ -## `cbxp.cbxp()` +## `cbxp.extract()` ```python -def cbxp( - control_block: str, - includes: list[str] = [], - filters: list[CBXPFilter] = [], - debug: bool = False +def extract( + control_block: str, + includes: list[str] = None, + filters: list[CBXPFilter] = None, + debug: bool = False, ) -> dict: ``` ### 📄 Description -Extract **Control Blocks** from **Live Memory** *(storage)* and post-process them into a **Python Dictionary**. +Extract and format **Control Block Data** from **Live Memory**. ### 📥 Parameters @@ -51,7 +51,7 @@ Extract **Control Blocks** from **Live Memory** *(storage)* and post-process the ### 📤 Returns * `dict`
- A **Python Dictionary** that contains the **Extracted Control Block Data** requested. + A **Python Dictionary** that contains **Formatted Control Block Data**. ### ❌ Raises * `CBXPError`
@@ -59,36 +59,36 @@ Extract **Control Blocks** from **Live Memory** *(storage)* and post-process the ### 💻 Examples -The following example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block and prints **Debug Messages**. +The following example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block from **Live Memory** and prints **Debug Messages**. ###### Python Script ```python from cbxp import cbxp -cbdata = cbxp("psa", debug=True) +cbdata = cbxp.extract("psa", debug=True) ```   -The following example extracts the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information), includes the [ECVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-ecvt-information) and the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information), and includes all **Known Control Blocks** that are pointed to directly by the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information). +The following example extracts the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information) control block from **Live Memory**, includes the [ECVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-ecvt-information) and the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information), and includes all **Known Control Blocks** that are pointed to directly by the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information). ###### Python Script ```python from cbxp import cbxp -cbdata = cbxp("cvt", includes=["ecvt", "asvt.*"]) +cbdata = cbxp.extract("cvt", includes=["ecvt", "asvt.*"]) ```   -The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks where the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER`. The built-in Python library `json` is then used to convert the resulting Python dictionary into a **JSON String**. +The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER`. The built-in Python library `json` is then used to convert the resulting Python dictionary into a **JSON String**. ###### Python Script ```python import json from cbxp import CBXPFilter, CBXPFilterOperation, cbxp -cbdata = cbxp( +cbdata = cbxp.extract( "assb", filters=[ CBXPFilter( @@ -101,3 +101,67 @@ cbdata = cbxp( cbjson = json(cbdata, indent=2) ``` + +## `cbxp.format()` + +```python +def format( + control_block: str, + data: bytes, + offset: int = None, + debug: bool = False, +) -> dict: +``` + +### 📄 Description +Format **Caller-Provided Control Block Data** from **Live Memory**. + +### 📥 Parameters + +* `control_block`
+ The name of the **Control Block** to format. + +* `data`
+ A **Bytes Object** containing the **Raw Control Block Data** to format. + +* `offset`
+ An **Optional** offset into the provided **Raw Control Block Data** to start formatting at. + +* `debug`
+ A **Boolean** that if set to `True` indicates that **Debug Messages** should be printed. If set to `False`, no **Debug Messages** will be printed. + +### 📤 Returns +* `dict`
+ A **Python Dictionary** that contains the **Formatted Control Block Data**. + +### ❌ Raises +* `CBXPError`
+ Raises `CBXPError` when an error or condition that prevents the operation from completing successfully occurs. + +### 💻 Examples + +The following example formats **Caller-Provided** [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) control block data. + +###### Python Script +```python +from cbxp import cbxp + +with open("ascb.bin", "rb") as f: + data = f.read() + +cbdata = cbxp.format("ascb", data) +``` + +  + +The following example formats **Caller-Provided** [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) control block data at an offset of `0x40` bytes. + +###### Python Script +```python +from cbxp import cbxp + +with open("ascboffset.bin", "rb") as f: + data = f.read() + +cbdata = cbxp.format("ascb", data, offset=0x40) +``` diff --git a/interfaces/shell.md b/interfaces/shell.md deleted file mode 100644 index 8203562..0000000 --- a/interfaces/shell.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -layout: default -parent: Interfaces -nav_order: 2 ---- - -# Shell - -The following shell interface is provided to facilitate exploitation of CBXP by shell callers. -{: .fs-6 .fw-300 } - -  - -{: .note } -> _The **Shell Interface** for CBXP downloaded from [GitHub](https://github.com/ambitus/cbxp/releases)._ - -  - -{: .note } -> _Wherever you **Install**/**Extract** the **CBXP PAX**, make sure to add the path to the `bin` directory where the `cbxp` executable resides to `PATH` in `/etc/profile` (global) or `~/.profile`/`~/.bashrc` (local/individual)._ - -  - -### 📄 Description - -Extract **Control Blocks** from **Live Memory** *(storage)*, post-process them into **JSON**, and write the result JSON to the `stdout` file descriptor. - -  - -``` -cbxp [options] [CONTROL_BLOCK] -``` - -* `-d`, `--debug`
- Print **Debug Messages**. - -* `-i`, `--include `
- **Include** control blocks that are **Accessible** from the **Root Control Block** being extracted using an [Include Pattern](../../include_patterns). - -* `-f`, `--filter`
- **Filter** repeated control block data using a [Filter](../../filters). - -* `-v`, `--version`
- Display **Version Information**. - -* `-h`, `--help`
- Display **Usage Information**. - -### 💻 Examples - -The following example extracts the [PSA](https://www.ibm.com/docs/en/zos/latest?topic=rqe-psa-information) control block and prints **Debug Messages**. - -###### Shell Script -```shell -cbxp -d psa -``` - -  - -The following example extracts the [CVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-cvt-information), includes the [ECVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-ecvt-information) and the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information), and includes all **Known Control Blocks** that are pointed to directly by the [ASVT](https://www.ibm.com/docs/en/zos/latest?topic=iar-asvt-information). - -###### Shell Script -```shell -cbxp -i ecvt -i 'asvt.*' cvt -``` - -  - -The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks where both the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER` and the **Control Block Field** `ASSBJBNS` matches the **Filter Value** `BPXAS`. The output is then piped into `jq` to **Format** it. - -###### Shell Script -```shell -cbxp -f assb.assbjbni=IBMUSER assb | jq -``` diff --git a/release_notes.md b/release_notes.md index dea8b37..d314d13 100644 --- a/release_notes.md +++ b/release_notes.md @@ -5,6 +5,9 @@ nav_order: 4 # Release Notes +## v0.0.4 - ?? ??, 2026 +* Add support for formatting **Caller-Provided** control block data ([#37](https://github.com/ambitus/cbxp/pull/37)) + ## v0.0.3 - March 20, 2026 * Add support for extracting [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control block data ([#17](https://github.com/ambitus/cbxp/pull/17)) * Add support for extracting [OUCB](https://www.ibm.com/docs/en/zos/latest?topic=rqe-oucb-information) control block data ([#26](https://github.com/ambitus/cbxp/pull/26)) diff --git a/supported_control_blocks.md b/supported_control_blocks.md index 5740437..f017992 100644 --- a/supported_control_blocks.md +++ b/supported_control_blocks.md @@ -11,16 +11,16 @@ Control blocks that are natively supported by CBXP.   {: .warning } -> _CBXP only supports extracting fields from **System-Level Control Blocks** that are **Documented Programming Interfaces** in the [z/OS MVS Data Areas](https://www.ibm.com/docs/en/zos/latest?topic=zos-mvs) documentation._ +> _CBXP only supports extracting and formatting fields from **System-Level Control Blocks** that are **Documented Programming Interfaces** in the [z/OS MVS Data Areas](https://www.ibm.com/docs/en/zos/latest?topic=zos-mvs) documentation._   {: .warning } -> _Since CBXP runs in **Problem State**, only **Non-Fetch Protected** control block data can be extracted from **Live Memory** (storage). Also, access to control block data is **NOT Serialized**, meaning that CBXP may occasionally extract control block data that is **Malformed** or otherwise **NOT Valid**._ +> _Since CBXP runs in **Problem State**, only **Non-Fetch Protected** control block data can be extracted from **Live Memory**. Also, access to control block data is **NOT Serialized**, meaning that CBXP may occasionally extract control block data that is **Malformed** or otherwise **NOT Valid**._   -CBXP currently supports extracting the following **System-Level Control Blocks** from **Live Memory** *(storage)*. +CBXP currently supports extracting and formatting the following **System-Level Control Blocks** from **Live Memory**.   From ee96047c8959eadea56ecc2b7aa8b8a995f33ecd Mon Sep 17 00:00:00 2001 From: Leonard Carcaramo Date: Tue, 9 Jun 2026 14:22:10 -0400 Subject: [PATCH 2/6] Cleanup documentation. Signed-off-by: Leonard Carcaramo --- include_patterns.md | 7 +++++-- interfaces/c_cpp.md | 9 +++++++-- interfaces/python.md | 18 ------------------ release_notes.md | 3 ++- supported_control_blocks.md | 4 ++++ 5 files changed, 18 insertions(+), 23 deletions(-) diff --git a/include_patterns.md b/include_patterns.md index f7a32d6..50d7f0f 100644 --- a/include_patterns.md +++ b/include_patterns.md @@ -31,14 +31,14 @@ How to use include patterns to include additional control blocks. > > ❌ > ```shell -> cbxp -i cvt.* psa +> cbxp extract -i cvt.* psa > ``` > >   > > ✅ > ```shell -> cbxp -i "cvt.*" psa +> cbxp extract -i "cvt.*" psa > ```   @@ -182,12 +182,15 @@ cbxp extract -i "cvt.**" psa subgraph ASCBs["ASCB Array"] ASCB1["ASCB"] ASCB1--> ASSB1["ASSB"] + ASCB1--> LDAX1["LDAX"] ASCB1--> OUCB1["OUCB"] ASCB2["ASCB"] ASCB2--> ASSB2["ASSB"] + ASCB2--> LDAX2["LDAX"] ASCB2--> OUCB2["OUCB"] ASCB3["ASCB"] ASCB3--> ASSB3["ASSB"] + ASCB3--> LDAX3["LDAX"] ASCB3--> OUCB3["OUCB"] end diff --git a/interfaces/c_cpp.md b/interfaces/c_cpp.md index efd56a3..6b751c0 100644 --- a/interfaces/c_cpp.md +++ b/interfaces/c_cpp.md @@ -62,7 +62,7 @@ Extract and format **Control Block Data** from **Live Memory**. The length of `control_block_name`. * `includes`
- A pointer to a **NULL-Terminated ISO8859-1 Encoded String** that contains a **Comma Delimited List** of [Include Patterns](../../include_patterns) that describe **Additional Control Blocks** to include that are accessible from the **Root Control Block** being extracted. + A pointer to a **NULL-Terminated ISO8859-1 Encoded String** that contains a **Comma Delimited List** of [Include Patterns](../../include_patterns) describing **Additional Control Blocks** to include that are accessible from the **Root Control Block** being extracted. * `includes_length`
The length of `includes`. @@ -85,7 +85,7 @@ Extract and format **Control Block Data** from **Live Memory**. ```c cbxp_result_t* cbxp_format(const char* control_block_name, const size_t control_block_name_length, - const void* p_data, const size_t data_length, + const void* data, const size_t data_length, bool debug); ``` @@ -129,6 +129,11 @@ void cbxp_free(cbxp_result_t* cbxp_result, bool debug);   +{: .warning} +> _`cbxp_free()` is guaranteed to cleanup all **Dynamically Allocated Memory** associated with a [`cbxp_result_t`](#cbxp_result_t) pointer returned by `cbxp_extract()` / `cbxp_format()` correctly. You should not attempt to use `free()` or `delete` to do this yourself. Doing so may result in **Undefined Behavior**._ + +  + Free all **Dynamically Allocated Memory** associated with a [`cbxp_result_t`](#cbxp_result_t) pointer returned by `cbxp_extract()` / `cbxp_format()`. ### 📥 Parameters diff --git a/interfaces/python.md b/interfaces/python.md index 5cb47d5..59c6228 100644 --- a/interfaces/python.md +++ b/interfaces/python.md @@ -108,7 +108,6 @@ cbjson = json(cbdata, indent=2) def format( control_block: str, data: bytes, - offset: int = None, debug: bool = False, ) -> dict: ``` @@ -124,9 +123,6 @@ Format **Caller-Provided Control Block Data** from **Live Memory**. * `data`
A **Bytes Object** containing the **Raw Control Block Data** to format. -* `offset`
- An **Optional** offset into the provided **Raw Control Block Data** to start formatting at. - * `debug`
A **Boolean** that if set to `True` indicates that **Debug Messages** should be printed. If set to `False`, no **Debug Messages** will be printed. @@ -151,17 +147,3 @@ with open("ascb.bin", "rb") as f: cbdata = cbxp.format("ascb", data) ``` - -  - -The following example formats **Caller-Provided** [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) control block data at an offset of `0x40` bytes. - -###### Python Script -```python -from cbxp import cbxp - -with open("ascboffset.bin", "rb") as f: - data = f.read() - -cbdata = cbxp.format("ascb", data, offset=0x40) -``` diff --git a/release_notes.md b/release_notes.md index d314d13..93fe328 100644 --- a/release_notes.md +++ b/release_notes.md @@ -5,8 +5,9 @@ nav_order: 4 # Release Notes -## v0.0.4 - ?? ??, 2026 +## v0.0.4 - June ??, 2026 * Add support for formatting **Caller-Provided** control block data ([#37](https://github.com/ambitus/cbxp/pull/37)) +* Add support for extracting [LDAX](https://www.ibm.com/docs/en/zos/latest?topic=isg-ihaldax-information) control block data ([#38](https://github.com/ambitus/cbxp/pull/38)) ## v0.0.3 - March 20, 2026 * Add support for extracting [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control block data ([#17](https://github.com/ambitus/cbxp/pull/17)) diff --git a/supported_control_blocks.md b/supported_control_blocks.md index f017992..569c1ae 100644 --- a/supported_control_blocks.md +++ b/supported_control_blocks.md @@ -31,6 +31,7 @@ CBXP currently supports extracting and formatting the following **System-Level C * [ASCB](https://www.ibm.com/docs/en/zos/latest?topic=iar-ascb-information) * [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) * [OUCB](https://www.ibm.com/docs/en/zos/latest?topic=rqe-oucb-information) +* [LDAX](https://www.ibm.com/docs/en/zos/latest?topic=isg-ihaldax-information)   @@ -44,12 +45,15 @@ CBXP currently supports extracting and formatting the following **System-Level C subgraph ASCBs["ASCB Array"] ASCB1["ASCB"] ASCB1--> ASSB1["ASSB"] + ASCB1--> LDAX1["LDAX"] ASCB1--> OUCB1["OUCB"] ASCB2["ASCB"] ASCB2--> ASSB2["ASSB"] + ASCB2--> LDAX2["LDAX"] ASCB2--> OUCB2["OUCB"] ASCB3["ASCB"] ASCB3--> ASSB3["ASSB"] + ASCB3--> LDAX3["LDAX"] ASCB3--> OUCB3["OUCB"] end From 2dab3d057ba1f2a0f21b4867afa75d23303e0896 Mon Sep 17 00:00:00 2001 From: Leonard Carcaramo Date: Wed, 10 Jun 2026 15:57:03 -0400 Subject: [PATCH 3/6] Cleanup doc Signed-off-by: Leonard Carcaramo --- include_patterns.md | 6 +++--- release_notes.md | 2 +- supported_control_blocks.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/include_patterns.md b/include_patterns.md index 50d7f0f..32ce92b 100644 --- a/include_patterns.md +++ b/include_patterns.md @@ -182,15 +182,15 @@ cbxp extract -i "cvt.**" psa subgraph ASCBs["ASCB Array"] ASCB1["ASCB"] ASCB1--> ASSB1["ASSB"] - ASCB1--> LDAX1["LDAX"] + ASSB1--> LDAX1["LDAX"] ASCB1--> OUCB1["OUCB"] ASCB2["ASCB"] ASCB2--> ASSB2["ASSB"] - ASCB2--> LDAX2["LDAX"] + ASSB2--> LDAX2["LDAX"] ASCB2--> OUCB2["OUCB"] ASCB3["ASCB"] ASCB3--> ASSB3["ASSB"] - ASCB3--> LDAX3["LDAX"] + ASSB3--> LDAX3["LDAX"] ASCB3--> OUCB3["OUCB"] end diff --git a/release_notes.md b/release_notes.md index 93fe328..41638d0 100644 --- a/release_notes.md +++ b/release_notes.md @@ -5,7 +5,7 @@ nav_order: 4 # Release Notes -## v0.0.4 - June ??, 2026 +## v0.0.4 - June 12, 2026 * Add support for formatting **Caller-Provided** control block data ([#37](https://github.com/ambitus/cbxp/pull/37)) * Add support for extracting [LDAX](https://www.ibm.com/docs/en/zos/latest?topic=isg-ihaldax-information) control block data ([#38](https://github.com/ambitus/cbxp/pull/38)) diff --git a/supported_control_blocks.md b/supported_control_blocks.md index 569c1ae..b3cc6d5 100644 --- a/supported_control_blocks.md +++ b/supported_control_blocks.md @@ -45,15 +45,15 @@ CBXP currently supports extracting and formatting the following **System-Level C subgraph ASCBs["ASCB Array"] ASCB1["ASCB"] ASCB1--> ASSB1["ASSB"] - ASCB1--> LDAX1["LDAX"] + ASSB1--> LDAX1["LDAX"] ASCB1--> OUCB1["OUCB"] ASCB2["ASCB"] ASCB2--> ASSB2["ASSB"] - ASCB2--> LDAX2["LDAX"] + ASSB2--> LDAX2["LDAX"] ASCB2--> OUCB2["OUCB"] ASCB3["ASCB"] ASCB3--> ASSB3["ASSB"] - ASCB3--> LDAX3["LDAX"] + ASSB3--> LDAX3["LDAX"] ASCB3--> OUCB3["OUCB"] end From 5a1a8fb0b297c36ef454fc8f0bdf91372e45a3fe Mon Sep 17 00:00:00 2001 From: Leonard Carcaramo Date: Thu, 11 Jun 2026 12:14:19 -0400 Subject: [PATCH 4/6] Cleanup Signed-off-by: Leonard Carcaramo --- index.md | 21 ++++++++++++++------- interfaces/c_cpp.md | 2 +- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/index.md b/index.md index 51cad85..0a62ca3 100644 --- a/index.md +++ b/index.md @@ -55,21 +55,28 @@ Currently, CBXP only has support for extracting and formatting a handful of **Sy 
   flowchart LR
-    python(Python Interface) ---CBXP
+    python(Python Interface) <-->CBXP
     style python fill:#ffcb3c,color:#000,stroke:#ffcb3c
-    cli(CLI Interface) ---CBXP
+    cli(CLI Interface) <-->CBXP
     style cli fill:#33cc22,color:#000,stroke:#33cc22
-    C(C/C++ Interface) ---CBXP
+    C(C/C++ Interface) <-->CBXP
     style C fill:#01559e,color:#fff,stroke:#01559e
     subgraph C/C+
         CBXP(["CBXP (64-bit XPLINK ASCII)"])
         style CBXP fill:#0096ff,color:#fff,stroke:#0096ff
+        Extract
+        style Extract color:#fff,stroke:#fff
+        Format
+        style Format color:#fff,stroke:#fff
     end
-    CBXP--- Extract
-    CBXP--- Format
-    Extract ---control_blocks_memory
+    control_blocks_memory-->Extract
     subgraph "Live Memory"
-        control_blocks_memory@{ shape: procs, label: "Control Blocks"}
+        control_blocks_memory@{shape: procs, direction: RL, label: "Control Block Data"}
         style control_blocks_memory color:#fff,stroke:#fff
     end
+    CBXP<-->Extract
+    CBXP<-->Format
+    control_blocks_caller_provided-->Format
+    control_blocks_caller_provided@{shape: procs, label: "Caller-Provided Control Block Data"}
+    style control_blocks_caller_provided color:#fff,stroke:#fff
diff --git a/interfaces/c_cpp.md b/interfaces/c_cpp.md index 6b751c0..103bd9f 100644 --- a/interfaces/c_cpp.md +++ b/interfaces/c_cpp.md @@ -165,7 +165,7 @@ The **C Struct** that is used to store all **Result Information** returned by [` ### 📋 Fields * `result_json`
- When the call to `cbxp_extract()` / `cbxp_format()` is **Successful**, this field contains pointer to a **NULL-Terminated ISO8859-1 Encoded JSON String**. When the call to `cbxp_extract()` / `cbxp_format()` is **Unsucessful**, this field contains a **NULL Pointer**. + When the call to `cbxp_extract()` / `cbxp_format()` is **Successful**, this field contains a pointer to a **NULL-Terminated ISO8859-1 Encoded JSON String**. When the call to `cbxp_extract()` / `cbxp_format()` is **Unsucessful**, this field contains a **NULL Pointer**. * `result_json_length`
When the call to `cbxp_extract()` / `cbxp_format()` is **Successful**, this field contains the length of the **NULL-Terminated ISO8859-1 Encoded JSON String** stored in the `result_json` field. When the call to `cbxp_extract()` / `cbxp_format()` is **Unsuccessful**, this field contains `0`. From d177ed585efb56362da046c2154c78755d7d7b44 Mon Sep 17 00:00:00 2001 From: Leonard Carcaramo Date: Thu, 11 Jun 2026 12:25:07 -0400 Subject: [PATCH 5/6] Cleanup Signed-off-by: Leonard Carcaramo --- index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.md b/index.md index 0a62ca3..b25e580 100644 --- a/index.md +++ b/index.md @@ -55,11 +55,11 @@ Currently, CBXP only has support for extracting and formatting a handful of **Sy 
   flowchart LR
-    python(Python Interface) <-->CBXP
+    python(Python Interface)<-->CBXP
     style python fill:#ffcb3c,color:#000,stroke:#ffcb3c
-    cli(CLI Interface) <-->CBXP
+    cli(CLI Interface)<-->CBXP
     style cli fill:#33cc22,color:#000,stroke:#33cc22
-    C(C/C++ Interface) <-->CBXP
+    C(C/C++ Interface)<-->CBXP
     style C fill:#01559e,color:#fff,stroke:#01559e
     subgraph C/C+
         CBXP(["CBXP (64-bit XPLINK ASCII)"])

From 466ec746dfc958fb052526862832d4ca4f80e3be Mon Sep 17 00:00:00 2001
From: Leonard Carcaramo 
Date: Thu, 11 Jun 2026 13:13:14 -0400
Subject: [PATCH 6/6] Cleanup

Signed-off-by: Leonard Carcaramo 
---
 interfaces/cli.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/interfaces/cli.md b/interfaces/cli.md
index d974a30..da3661f 100644
--- a/interfaces/cli.md
+++ b/interfaces/cli.md
@@ -69,7 +69,7 @@ cbxp extract -i ecvt -i 'asvt.*' cvt
 
  
 
-The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where both the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER` and the **Control Block Field** `ASSBJBNS` matches the **Filter Value** `BPXAS`. The output is then piped into `jq` to **Format** it.
+The following example extracts all [ASSB](https://www.ibm.com/docs/en/zos/latest?topic=iar-assb-information) control blocks from **Live Memory** where both the **Control Block Field** `ASSBJBNI` matches the **Filter Value** `IBMUSER` and the **Control Block Field** `ASSBJBNS` matches the **Filter Value** `BPXAS`. The **JSON** output is then piped into `jq` to **Format** it.
 
 ###### Shell Script
 ```shell