Overview of the $ZF Callout Functions
The InterSystems IRIS® $ZF system function is a container for a suite of related functions. Most functions in the $ZF suite are identified by the first argument of the function call, which will be a negative number, -100 or -3 through -6. For example, the function that calls an operating system command has the form $ZF(-100, <oscommand>), where <oscommand> is a string containing the command to be executed. When this function is discussed, it will be referred to as $ZF(-100). In the same way, the other functions will be referred to as $ZF(-3) through $ZF(-6), using only the first parameter of the actual function call. The $ZF() function can also be called without a negative number parameter, in which case it invokes functions from a special Callout library named iriszf.
A shared library is a dynamically linked file (a DLL file on Windows or an SO file on UNIX® and related operating systems). A Callout library is a shared library that includes hooks to the $ZF Callout Interface, allowing various $ZF functions to load it at runtime and invoke library functions. See “Creating an InterSystems Callout Library” for details about how to write a Callout library.
The $ZF function suite includes the following interfaces:
The $ZF() function (with no negative number argument)
The main $ZF() function provides direct access to functions from a special Callout library named iriszf. When you have defined and compiled this custom library, its functions can be invoked by specifying just the function name and arguments (for example, $ZF("myFunction",arg1)). Unlike $ZF(-3), $ZF(-5), or $ZF(-6), there is no need to load the library or specify a library identifier.
See “Using $ZF() to Access the iriszf Callout Library” for details.
The $ZF(-3) function
The $ZF(-3) function is a simple way to load a Callout library and invoke a library function with a single statement. Both the library and its functions are specified by name, and the library remains in memory until replaced by a call to a different library.
See “Using $ZF(-3) for Simple Library Function Calls” for details.
The $ZF(-4) function
The $ZF(-4) function provides a set of services for $ZF(-5) and $ZF(-6). It is a container for eight utility functions identified by the first two parameters: $ZF(-4,1) through $ZF(-4,8). The $ZF(-5) function interface uses functions $ZF(-4,1) through $ZF(-4,3), and the $ZF(-6) function interface uses functions $ZF(-4,5) through $ZF(-4,8). See the following descriptions for more details.
The $ZF(-5) function interface
The $ZF(-5) function and its utility functions allow multiple libraries to be handled efficiently. Both the library and its functions are identified by system-defined ID values. Several libraries can be in virtual memory at the same time. The following $ZF(-4) functions are used to load and unload libraries, and to obtain library and function ID values:
$ZF(-4,1) loads a library specified by name, and returns a library ID.
$ZF(-4,2) unloads a library.
$ZF(-4,3) returns a function ID for a specified library ID and function name.
See “Using $ZF(-5) to Access Libraries by System ID” for details.
The $ZF(-6) function interface
The $ZF(-6) function and its utility functions provide a way to write Callout applications that do not require hard-coded library names. Instead, the actual library filenames are contained in a separate index table, where each library is associated with a unique, user-defined index number. Once the index table is defined, it is available to all processes in an instance of InterSystems IRIS. Callout applications identify a library by index number and load it by reading the index table. Several libraries can be in memory at the same time. The following functions are used to manage indexes and load or unload libraries:
$ZF(-6) invokes a library function, and loads the library if it is not already in memory.
$ZF(-4,4) unloads a library.
$ZF(-4,5) and $ZF(-4,6) are used to create and maintain the system index table, which can be accessed by all processes in an instance of InterSystems IRIS.
$ZF(-4,7) and $ZF(-4,8) are used to create and maintain a process index table, which can be used to override the system index within a single process.
See “Using $ZF(-6) to Access Libraries by User Index” for details.
See the “InterSystems Callout Quick Reference” for a complete list of all $ZF functions, information on how they are used, and links to more detailed information and examples.