ZOSLIB - A z/OS C/C++ Library

Table of Contents

• Overview
• System Requirements
• Build and Install
• Quick Start
• API Documentation
• Legalities

Overview

ZOSLIB is a z/OS C/C++ library. It is an extended implementation of the z/OS LE C Runtime Library.

ZOSLIB implements the following:

• A subset of POSIX APIs that are not available in the LE C Runtime Library
• EBCDIC <-> ASCII conversion C APIs
• APIs for improved diagnostic reporting
• and more!

System Requirements

ZOSLIB is supported on the following z/OS operating systems with z/OS UNIX System Services enabled:

• z/OS V2R4 with the following PTFs installed:
  • UI64830
  • UI64837
  • UI64839
  • UI64940
  • UI65567
• z/OS V2R5
  • UI78912
  • UI81095
  • UI80156
  • UI83424
• z/OS V3R1

ZOSLIB is supported on the following hardware:

• IBM z16
• IBM z15
• IBM z14/z14 Model ZR1
• IBM z13/z13s
• IBM zEnterprise EC12/BC12

Build and Install

Build tool prerequisites

• CMake 3.24.2-zos+
• GNU Make 4.3+
• IBM XL C/C++ V2.3.1 for z/OS V2.3 web deliverable (xlclang/xlcang++) or IBM Open XL C/C++ 2.0 (clang/clang++)
• Git
• Ninja (optional)

Clone the ZOSLIB source code using Git into a newly created zoslib directory:

$ git clone [email protected]:ibmruntimes/zoslib.git zoslib

After obtaining the source, cd to the zoslib directory and follow one of the following options to build zoslib and run its tests.

1. Use the included build.sh to build and optionally run the zoslib tests:

$ ./build.sh -h

which displays flags that you can pass to build.sh to specify a Release build (default is Debug) and whether to build and run the zoslib tests.

Example:

$ ./build.sh -c -r -t

performs a Clean (-c) Release (-r) build that creates both static library libzoslib.a and shared library libzoslib.so and its sidedeck libzoslib.x, then builds and runs the zoslib tests (-t).

build.sh creates directory ./build to hold the build files, and then places the target files under ./install directory.

2. Use the steps below to build and optionally run the zoslib tests:

Create a build directory to hold your build files and cd to it:

$ mkdir build && cd build

Next, we will configure our build with CMake.

Make sure to export the CC and CXX environment variables to point to the supported C/C++ build compiler, or pass in the CMake options -DCMAKE_C_COMPILER and -DCMAKE_CXX_COMPILER.

From the directory build, enter the following CMake command (here, .. refers to the ZOSLIB source directory)

$ cmake ..

By default CMake will configure your build as a Debug build. You can configure your build as a Release build with the -DCMAKE_BUILD_TYPE=Release option.

CMake will detect your development environment, perform a series of tests, and generate the files required for building ZOSLIB.

To build the zoslib tests, pass -DBUILD_TESTING=ON to cmake, which creates build/test/cctest that links with libzoslib.a, and also build/test/cctest that links with libzoslib.x. Before running the latter, set your LIBPATH to include the directory containing libzoslib.so, which should be under install/lib.

By default, CMake will generate Makefiles. If you prefer to use Ninja, you can specify -GNinja as an option to CMake.

After CMake has finished with the configuration, start the build from build using CMake:

$ cmake --build .

After ZOSLIB has finished building, install it from build:

$ cmake --build . --target install

Quick Start

Once we have ZOSLIB built and installed, let's attempt to build our first ZOSLIB C++ application. The application will generate a series of random numbers, leveraging the getentropy C API in ZOSLIB.

1. Create a file named random.cc containing the following contents:

// random.cc

// Include zos.h ZOSLIB header
#include <zos.h>
#include <stdio.h>

// Initialize ZOSLIB class
__init_zoslib __nodezoslib;

int main(int argc, char** argv) {
  printf("ZOSLIB version: %s\n", __zoslib_version);
  if (argc < 1) {
    printf("An argument specifying the number of random "
           " numbers is required\n");
    return 1;
  }

  int num = atoi(argv[1]);
  if (num < 0) {
    printf("The argument should be positive (>0)\n");
    return 2;
  }
  printf("Generating %d random values\n", num);

  char buffer[10];
  for (int i = 0; i < num; i++) {
    printf("Random index: %d\n", i);
    // Call ZOSLIB getentropy C API
    if (!getentropy(buffer, 10)) {
      for (int j = 0; j < 10; j++)
        printf("%2X ", buffer[j]);
      printf("\n");
    }
  }
  return 0;
}

This example will first include the main ZOSLIB header file, zos.h, which subsequently includes all of the ZOSLIB header files. Alternatively, we could have just included zos-base.h, since the prototype for getentropy is defined in zos-base.h.

2. In order to initialize ZOSLIB, we need to create a static instance of the __init_zoslib class: __init_zoslib zoslib_init;. This initializes the Enhanced ASCII runtime environment, among other things. If your application is C only, you can make use of the init_zoslib function instead.

In the main function, we make use of two ZOSLIB definitions, __zoslib_version to obtain the ZOSLIB version, and getentropy to generate a list of random values.

3. To compile and link the application, enter the following command:

xlclang++ -qascii -I path/to/zoslib/include -L path/to/build/lib -lzoslib random.cc -o random

or:

clang++ -fzos-le-char-mode=ascii -I path/to/zoslib/include -L path/to/build/lib -lzoslib random.cc -o random

4. To run the application, enter the following command:

./random 2

You should get an output similar to the following:

ZOSLIB version: v4.0.0
Generating 2 random values
Random index: 0
BC DE CF DE  7 E3 58 3A 4F 22
Random index: 1
5B 30 5A 9C C4 70 94 A6 B6 E5

API Documentation

The ZOSLIB API documentation is available here.

Legalities

ZOSLIB is available under the Apache 2.0 license. See the LICENSE file for details

Copyright

Licensed Materials - Property of IBM
ZOSLIB
(C) Copyright IBM Corp. 2020. All Rights Reserved.
US Government Users Restricted Rights - Use, duplication
or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.