C/C++

The following C/C++ interface is provided to facilitate exploitation of CBXP by C/C++ callers.

 

The C/C++ interface for CBXP downloaded from GitHub.

 

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.

 

When compiling and linking C/C++ code with /lib/libcbxp.a, it is recommended to use IBM Open XL C/C++ 2.2 or newer. See Binary Compatibility for more details.

 

cbxp()

cbxp_result_t* cbxp(const char* control_block, const char* includes_string,
                    const char* filters_string, bool debug);

📄 Description

 

includes_string and filters_string 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.

📥 Parameters

• control_block
  A NULL-Terminated ISO8859-1 Encoded String that contains name of the Control Block to extract.

• includes_string
  A NULL-Terminated ISO8859-1 Encoded String that contains a Comma Delimited List of Include Patterns that describe Additional Control Blocks to include that are accessible from the Root Control Block being extracted.

• filters_string
  A NULL-Terminated ISO8859-1 Encoded String that contains a Comma Delimited List of Filters that are used to filter the entries returned in Repeated control block 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*
  A pointer to a cbxp_result_t C Struct.

cbxp_free()

void cbxp_free(cbxp_result_t* cbxp_result, bool debug);

📄 Description

 

The cbxp_result_t pointer and the result_json pointer within the cbxp_result_t C Struct it points to are no longer valid after calling cbxp_free(). Using these pointers after calling cbxp_free() will result in Undefined Behavior since cbxp_free() frees the memory that both of these pointer point to.

 

Free all Dynamically Allocated Memory associated with a cbxp_result_t pointer returned by cbxp().

📥 Parameters

• cbxp_result
  A pointer to a 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.

📤 Returns

• void
  This function does not return anything.

cbxp_result_t

typedef struct {
  char* result_json;
  int result_json_length;
  int return_code;
} cbxp_result_t;

📄 Description

The C Struct that is used to store all Result Information returned by CBXP.

📋 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.

• 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.

• return_code
  This field will be set by cbxp() to one of the following values:

  • ✅ 0
    The call to cbxp() was Successful.
  • ❌ 1
    The call to cbxp() was Unsuccessful due to an Unknown Control Block being specified with the control_block parameter.
  • ❌ 2
    The call to cbxp() was Unsuccessful due to a bad Include Pattern being specified within the includes_string parameter.
  • ❌ 3
    The call to cbxp() was Unsuccessful due to a bad Filter being specified within the filters_string parameter.

💻 Examples

 

The following examples assume that the CBXP PAX is extracted in the Current Working Directory.

.
|-- cbxp-0.0.3
|   |-- LICENSE
|   |-- NOTICES
|   |-- bin
|   |   `-- cbxp
|   |-- include
|   |   `-- cbxp.h
|   `-- lib
|       `-- libcbxp.a
|-- cbxp-0.0.3.pax.Z
|-- main.c
|-- main.cpp

 

The following C example extracts the PSA control block and prints the returned JSON String.

C

#include <cbxp.h>
#include <stdbool.h>
#include <stdio.h>

int main() {
  // Call CBXP
  puts("Calling CBXP from C...");
  cbxp_result_t* cbxp_result = cbxp("psa", NULL, NULL, 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);
  // Print Result JSON
  } else {
    puts(cbxp_result->result_json);
  }

  // Cleanup
  cbxp_free(cbxp_result, false);

  return 0;
}

Shell

# Compile
ibm-clang64 -c -fzos-le-char-mode=ascii -I./cbxp-0.0.3/include -o main.o main.c
# Link
ibm-clang++64 -fzos-le-char-mode=ascii -o main ./cbxp-0.0.3/lib/libcbxp.a main.o
# Run
./main

 

The following C++ example extracts the PSA control block and prints the returned JSON String.

C++

#include <iostream>

#include <cbxp.h>

int main() {
  // Call CBXP
  std::cout << "Calling CBXP from C++..." << std::endl;
  cbxp_result_t * cbxp_result = cbxp("psa", nullptr, nullptr, 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;
  // Print result JSON
  } else {
    std::cout << cbxp_result->result_json << std::endl;
  }

  // Cleanup
  cbxp_free(cbxp_result, false);

  return 0;
}

Shell

# Compile
ibm-clang++64 -c -fzos-le-char-mode=ascii -I./cbxp-0.0.3/include -o main.o main.cpp
# Link
ibm-clang++64 -fzos-le-char-mode=ascii -o main ./cbxp-0.0.3/lib/libcbxp.a main.o
# Run
./main