Running zlib

To compress data with zEDC, your installation must meet the system requirements.

To use the IBM-provided zlib compatible C library for data compression or data expansion services, follow these steps:
  1. Link or re-link applications to use the IBM-provided zlib.
    The IBM-provided zlib is an archive file in the z/OS UNIX System Services file system and can be statically or dynamically linked into your applications. The paths for the zlib archive file and the zlib header files are:
    Path for the zlib archive file:
    /lib/libzz.a
    Path for 31-bit non-xplink dynamic library files:
    /lib/libzz.so
    /lib/libzz.x
    Path for 31-bit xplink dynamic library files:
    /lib/libzzX.so
    /lib/libzzX.x
    Path for 64-bit dynamic library files:
    /lib/libzz64.so
    /lib/libzz64.x
    Path for the zlib header files:
    /usr/include/
    Note: When a new IBM service is provided for zlib, all applications that statically or dynamically link zlib must re-link in order to use the updated IBM-provided zlib and take advantage of the new function.
  2. Provide System Authorization Facility (SAF) Access:
    • Access to zEDC Express is protected by the SAF FACILITY resource class for installations running IBM zEnterprise z14 and below processors (IBM zEnterprise z15 and above processor will no longer have this requirement): FPZ.ACCELERATOR.COMPRESSION.
    • Give READ access to FPZ.ACCELERATOR.COMPRESSION to the identity of the address space that the zlib task will run in.
    Note: The access check is performed during the first call in a given task. The results of that first check are cached for the duration of the task.
  3. Use the z/OS UNIX environmental variable, _HZC_COMPRESSION_METHOD, to control if zEDC is used for data compression.
    Note: If the value of software is set, software-based compression services are used. All other values result in the default behavior of attempting to use zEDC for data compression.
  4. Ensure that adequately sized input buffers are available. If the input buffer size falls below the minimum threshold, data compression occurs using zlib software compression and not zEDC.
    Note: IBM zEnterprise z15 and above processor thresholds will no longer be tunable through parmlib. The IQPPRMxx will still be allowed in the configuration, but the values will no longer be accepted.

    The environment variables _HZC_DEFLATE_THRESHOLD and _HZC_INFLATE_THRESHOLD can also be used to control the threshold for going to zEDC. The valid values are in the range 1-9999999.

    For example:

    _HZC_DEFLATE_THRESHOLD=1 would force all deflate requests with an initial input size of 1 byte or larger to use zEDC.

    This threshold can be controlled at a system level using the PARMLIB member IQPPRM<varname>xx</varname>.
  5. Start of change Use the z/OS UNIX environmental variable, _HZC_CHECKSUM_METHOD, to control if SIMD acceleration is used in checksum verification.
    Note: If the value of software is set, software-based checksum verification is used. All other values result in the default behavior, which means if hardware supported SIMD, then SIMD acceleration is used.
    End of change
  6. Allocate the correct amount of storage for I/O buffers. The zEDC requests generated by zlib use predefined I/O buffer pools. The size of these I/O buffer pools can be set using PARMLIB member IQPPRMxx.
    Note: For IBM z15 and above processors these buffers are no longer applicable. The IQPPRMxx will still be allowed in the configuration, but the values will no longer be accepted.
When zlib is statically linked into an application that runs on software or hardware that is not compatible with zEDC, zlib uses the following compression and decompression:
Table 1. Compression and decompression with zlib
Hardware level z/OS level zEDC Express Description
zEC12 (with GA2 level microcode) z/OS V2R1 Active zEDC is used for both data compression and decompression.
zEC12 (with GA2 level microcode) z/OS V2R1 Not Active Requirements are not met for zEDC. When zEDC Express is not available, traditional software zlib is used for compression and decompression.
Pre-zEC12 (with GA2 level microcode) z/OS V2R1 or pre-z/OS V2R1 N/A Requirements are not met for zEDC. When zEDC Express is not available, traditional software zlib is used for compression and decompression.
zEDC error handling:
  • If a System z compression accelerator is unavailable, data compression requests transfer to another System z compression accelerator configured to the same partition. These request transfers are transparent to the application.
  • If all System z compression accelerators are unavailable, an error message is sent to the application.