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	In which directory
`zoautil.h`	C header file that provides the prototypes for the functions in the DLL	`include`
`vector.h`	C header file that defines the vector of function pointers for all functions available to be called	`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 and vector.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. In this release, the supported version is 0x020000.
init: Next, call this function. It initializes the environment and returns the vector for the version supplied. The layout of the vector returned is described in vector.h. The format of the vector is as follows:

  version number (unsigned int)
  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

All functions in version 0x020000 have the same interface:

typedef int ZOAUtil_Fn3(const char* parms, size_t lparms, zoau_response ** response);

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 and lparms	The parameters to pass to the utility being called
zoau_response	The address of a pointer to a structure containing invocation results. See the `zoautil.h` file for structure format.

Return code

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

Example

The following example calls mvscmd to run the ISRSUPC program, reading input from stdin, writing output to /tmp/out, and writing errors to stderr.

unsigned int vrm = version();
vector = init(vrm);
zoau_response * response;
parms = "--pgm=isrsupc --args='DELTAL,LINECMP' --newdd='tst.in(new)' --olddd='tst.in(old)' --sysin=stdin --outdd=*";
rc = vector->mvscmd(parms, strlen(parms), &response);
if (!rc && response->stdout_response[0] != '\0' ) { 
  printf("%s\n", response->stdout_response); 
}
free_response(response);
termrc = term(vector);

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.