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!
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
- 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 zoslibAfter obtaining the source, cd to the zoslib directory and follow one of the
following options to build zoslib and run its tests.
- Use the included
build.shto build and optionally run the zoslib tests:
$ ./build.sh -hwhich 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 -tperforms 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.
- 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 buildNext, 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 installOnce 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.
- Create a file named
random.cccontaining 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.
- In order to initialize ZOSLIB, we need to create a static instance of the
__init_zoslibclass:__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 theinit_zoslibfunction 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.
- 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 randomor:
clang++ -fzos-le-char-mode=ascii -I path/to/zoslib/include -L path/to/build/lib -lzoslib random.cc -o random- To run the application, enter the following command:
./random 2You 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
The ZOSLIB API documentation is available here.
ZOSLIB is available under the Apache 2.0 license. See the LICENSE file for details
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent