Extending ZOAU to other languages

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(): Frees 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.

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;
}

Potential interface changes

To provide performance and feature enhancements to ZOAU, portions of the shared library may be changed in future releases.