The InterSystems $ZF Callout Interface
See the Table of Contents for a detailed listing of the subjects covered in this document.
The InterSystems $ZF Callout Interface is a set of ObjectScript functions that provide several ways to integrate external system and function calls into InterSystems IRIS:
The $ZF(-100) function provides an easy way to call operating system commands and run external programs as you would from a command line interface.
The other $ZF functions provide various options (described below) for giving ObjectScript applications access to your frequently used C functions.
The $ZF Callout Interface is an older InterSystems technology designed primarily to give ObjectScript applications access to C function libraries. For embedded language access to external languages such as Java, .NET, Python, and Node.js, InterSystems External Servers provide an easier and more powerful alternative.
The $ZF Callout Interface can be used for many purposes, from making simple OS command line calls to creating a function library that provides access to hundreds of functions. The following options are available:
Access to operating system calls, including calls that start external programs:
Callout library access. A Callout library is a user-written shared library (a DLL or SO file) that includes hooks to the $ZF Callout Interface, allowing various $ZF functions to load it at runtime and invoke its functions. Callout libraries are usually written in C, but languages with compatible calling conventions could also be used (see “Compatible Languages and Compilers”). The various $ZF functions differ mainly in how the libraries are identified and loaded into memory:
Using $ZF() to Access the iriszf Callout Library
Create a special shared library named iriszf. When this library is available, its functions can be accessed without previously loading the library or specifying the library name.
Using $ZF(-3) for Simple Library Function Calls
Load a library and invoke a function by specifying the library file path and function name. It is simple to use, but can only have one library at a time in virtual memory. Unlike the other interfaces, it does not require any initialization before a library function can be invoked.
Using $ZF(-5) to Access Libraries by System ID
Create an interface that can be used to efficiently maintain and access more than one library at a time. Several libraries can be loaded and used simultaneously, each requiring significantly less processing overhead than $ZF(-3).
Using $ZF(-6) to Access Libraries by User Index
Create the most efficient interface for handling a large set of Callout libraries. Libraries are accessed through a globally defined index table. The index is available to all processes in an instance of InterSystems IRIS, and several libraries can be in memory at the same time.
Also see “Overview of $ZF Interfaces” for a quick summary of $ZF functions, and the “InterSystems Callout Quick Reference” for a description of all $ZF functions, information on usage, and links to details and examples.