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..32ce92b 100644
--- a/include_patterns.md
+++ b/include_patterns.md
@@ -25,25 +25,25 @@ 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._
>
>
>
> ❌
> ```shell
-> cbxp -i cvt.* psa
+> cbxp extract -i cvt.* psa
> ```
>
>
>
> ✅
> ```shell
-> cbxp -i "cvt.*" psa
+> cbxp extract -i "cvt.*" psa
> ```
-**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
```
@@ -182,12 +182,15 @@ cbxp -i "cvt.**" psa
subgraph ASCBs["ASCB Array"]
ASCB1["ASCB"]
ASCB1--> ASSB1["ASSB"]
+ ASSB1--> LDAX1["LDAX"]
ASCB1--> OUCB1["OUCB"]
ASCB2["ASCB"]
ASCB2--> ASSB2["ASSB"]
+ ASSB2--> LDAX2["LDAX"]
ASCB2--> OUCB2["OUCB"]
ASCB3["ASCB"]
ASCB3--> ASSB3["ASSB"]
+ ASSB3--> LDAX3["LDAX"]
ASCB3--> OUCB3["OUCB"]
end
diff --git a/index.md b/index.md
index adf5283..b25e580 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
@@ -55,18 +55,28 @@ Currently, CBXP only has support for extracting a handful of **System-Level Cont
flowchart LR
- python(Python Interface) ---CBXP
+ python(Python Interface)<-->CBXP
style python fill:#ffcb3c,color:#000,stroke:#ffcb3c
- shell(Shell Interface) ---CBXP
- style shell fill:#33cc22,color:#000,stroke:#33cc22
- C(C/C++ Interface) ---CBXP
+ 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
+ Extract
+ style Extract color:#fff,stroke:#fff
+ Format
+ style Format color:#fff,stroke:#fff
end
- subgraph "Live Memory (Storage)"
- CBXP--- control_blocks_storage@{ shape: procs, label: "Control Blocks"}
- style control_blocks_storage color:#fff,stroke:#fff
+ control_blocks_memory-->Extract
+ subgraph "Live Memory"
+ 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 385701f..103bd9f 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_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) describing **Additional Control Blocks** to include that are accessible from the **Root Control Block** being extracted.
+
+* `includes_length`
+ The length of `includes`.
+
+* `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.
+
+### 📤 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* data, const size_t data_length,
+ bool debug);
+```
+
+### 📄 Description
+
+Format **Caller-Provided Control Block Data**.
### 📥 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 format.
-* `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.
+* `control_block_name_length`
+ The length of `control_block_name`.
-* `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.
+* `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.
+ 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,12 @@ 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()`.
+{: .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
@@ -85,7 +142,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 +154,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 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()` 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 +247,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 +268,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 +429,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..da3661f
--- /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 **JSON** 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..59c6228 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,49 @@ cbdata = cbxp(
cbjson = json(cbdata, indent=2)
```
+
+## `cbxp.format()`
+
+```python
+def format(
+ control_block: str,
+ data: bytes,
+ 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.
+
+* `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)
+```
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..41638d0 100644
--- a/release_notes.md
+++ b/release_notes.md
@@ -5,6 +5,10 @@ nav_order: 4
# Release Notes
+## 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))
+
## 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..b3cc6d5 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**.
@@ -31,6 +31,7 @@ CBXP currently supports extracting the following **System-Level Control Blocks**
* [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 the following **System-Level Control Blocks**
subgraph ASCBs["ASCB Array"]
ASCB1["ASCB"]
ASCB1--> ASSB1["ASSB"]
+ ASSB1--> LDAX1["LDAX"]
ASCB1--> OUCB1["OUCB"]
ASCB2["ASCB"]
ASCB2--> ASSB2["ASSB"]
+ ASSB2--> LDAX2["LDAX"]
ASCB2--> OUCB2["OUCB"]
ASCB3["ASCB"]
ASCB3--> ASSB3["ASSB"]
+ ASSB3--> LDAX3["LDAX"]
ASCB3--> OUCB3["OUCB"]
end