Extending ZOAU to other languages

IBM® Z Open Automation Utilities provides a shared library interface that can be used for creating libraries in other languages, such as Node.js. The shared library interface is written in C as a 64-bit DLL that can function in both ASCII and EBCDIC modes.

The following files are included in the shared library.

File name Usage Directory
zoautil.h C header file. Provides prototypes and vector of function pointers include
zoautil.x Definition sidedeck lib
zoautil.so DLL, which is similar to a shared library lib

How to use the shared library

  • Compiling: Include zoautil.h in your 64-bit C code.
  • Linking: Include zoautil.x when binding your 64-bit C code.
  • Running: Include lib directory in your LIBPATH when running your 64-bit C code.

Exported functions in the shared library

  • version: You should call this function first. It takes no parameters and returns the version of the services in this shared library. The version returned is of the form 0xVVRRMM, where VV is the version, RR is the release and MM is the modification level.

  • init: Next, call this function. It initializes the environment and returns the vector for the version supplied. The format of the vector is as follows:

unsigned int version;
ZOAUtil_Fn4 ...
/* List of function pointers */


Each function pointer has the same name as its corresponding shell utility. For example, mvscmd is the function pointer that performs the same function as the mvscmd utility.

  • free_response: Call this function to free the storage used by the zoau_response structure returned by vector functions.
  • term: Call this function when you have finished using the shared library. It frees the environment that is established for the shared library services.

Calling a function in the vector

typedef int ZOAUtil_Fn4(const char* parms, size_t lparms, zoau_response **response, zoautil_options_t options);


Not all languages guarantee NULL terminated strings, so the interface requires that you provide a string and string length for each parameter. This ensures that languages that do not naturally provide NULL terminated strings do not have to make copies of parameters to call the shared library services.


Arguments

Arguments Description
parms The parameters to pass to the utility being called.
lparms The length of the parms string.
zoau_response The address of a pointer to a structure containing invocation results. See the zoautil.h file for structure format.
options Options structure. Used to set options for how the shared library behaves. Currently used for toggling text/binary output modes.

Return code

The return code is always an integer. The value of the return code is consistent with the corresponding shell utility.

Example

/*******************************************************************************
*
* Copyright IBM Corp. 2023.
*
* Sample Material
*
* Licensee may copy and modify Source Components and Sample Materials for
* internal use only within the limits of the license rights under the Agreement
* for IBM Z Open Automation Utilities provided, however, that Licensee may not
* alter or delete any copyright information or notices contained in the Source
* Components or Sample Materials. IBM provides the Source Components and Sample
* Materials without obligation of support and "AS IS", WITH NO WARRANTY OF ANY
* KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTY OF TITLE,
* NON-INFRINGEMENT OR NON-INTERFERENCE AND THE IMPLIED WARRANTIES AND
* CONDITIONS OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
*
*******************************************************************************/

/**
 * This sample program illustrates how to use the ZOAU shared library.
 * It opens a connection to the ZOAU DLL, sets some options, runs a command,
 * obtains the results, and closes the connection.
 *
 * This can be used as a template when building a new ZOAU
 * language binding.
 */

#include <stdio.h>
#include <string.h>

#include "zoautil.h"

int main(int argc, char *argv[])
{
 /* Version nzumber of the ZOAU shared library. */
 unsigned int vrm;

 /* Vector table to ZOAU commands. */
 zoautil_vector4_t *vector = NULL;

 /* ZOAU command response structure.*/
 zoau_response *response = NULL;

 /* ZOAU shared library options structure. */
 zoautil_options_t options = {
         ZOAUTIL_EYECATCHER,
         VERSION_CURRENT,
         FORMAT_TEXT
        };

 int zoau_rc = 0, termrc;
 const int failure = 16;

 printf("Getting ZOAU shared library version.\n");
 vrm = version();
 if (vrm < VERSION_CURRENT) {
  fprintf(stderr, "Wrong version returned from shared library: 0x%0x (expected 0x%0x)\n",
    vrm, VERSION_CURRENT);
  return failure;
 }

 printf("Getting ZOAU shared library vector table.\n");
 vector = init(vrm);
 if (vector == NULL) {
  fprintf(stderr, "Unable to get vector table from shared library.\n");
  return failure;
 }

 printf("Validating ZOAU shared library vector table version.\n");
 if (vector->version < VERSION_CURRENT) {
  fprintf(stderr, "Vector version is too old: 0x%x\n", vector->version);
  return failure;
 }

 /* Arguments passed to the ZOAU command. */
 const char cmd_args[] = "";
 /* Length of the argument string. */
 const size_t args_len = strlen(cmd_args);

 printf("Calling zoaversion command via ZOAU shared library.\n");
 zoau_rc = vector->zoaversion(cmd_args, args_len, &response, options);

 printf("Validating ZOAU shared library response structure version.\n");
 if (response->response_version != VERSION_CURRENT) {
  fprintf(stderr, "Wrong response structure version: 0x%0x (expected 0x%0x)\n",
    response->response_version, VERSION_CURRENT);
  return failure;
 }

 printf("Printing stdout stream from ZOAU shared library response.\n");
 if (response->stdout_len > 0 && response->stdout_response[0] != '\0') {
  printf("%s\n", response->stdout_response);
 }

 printf("Printing stderr stream from ZOAU shared library response.\n");
 if (response->stderr_len > 0 && response->stderr_response[0] != '\0') {
  fprintf(stderr, "%s\n", response->stderr_response);
 }

 printf("Cleaning up memory from ZOAU response structure.\n");
 free_response(response);

 printf("Tearing down the connection to the ZOAU shared library.\n");
 termrc = term(vector);
 if (termrc) {
  fprintf(stderr, "Unable to terminate shared library connection: rc = %d\n",
    termrc);
  return failure;
 }

 printf("Exiting ZOAU shared library sample program.\n");
 return zoau_rc;
}



Possible interface change

To provide future performance enhancements to ZOAU, portions of the shared library will be changed in an upcoming release. This change will not impact the current shell or Python interfaces, but will introduce changes to the shared library interface used for creating libraries in other languages.