Using $ZF(-3) for Simple Library Function Calls

Using $ZF(-3) for Simple Library Function Calls

The $ZF(-3) function is used to load a Callout library and execute a specified function from that library. $ZF(-3) is most useful if you are only using one library, or aren’t making enough calls to worry about the overhead of loading libraries. It allows you to call any available library function by specifying the library name, the function name, and a comma-separated list of function arguments:

   result = $ZF(-3, library_name[, function_name[, arguments]])

The specified library is loaded if it hasn’t already been loaded by a previous call to $ZF(-3). Only one library can be loaded at a time. When a subsequent $ZF(-3) call specifies a different library, the old library is unloaded and the new one replaces it. The library stays loaded as long as subsequent $ZF(-3) calls specify the same library. After a library has been loaded, the library name can be specified as a null string ("") in subsequent calls.

You can load or unload a library without calling a function. To load a new library, specify only the library name. To unload the current library without loading a new one, specify only a null string. In either case, $ZF(-3) returns a status code indicating whether the load or unload was successful.

The following ObjectScript code calls two different functions from each of two different libraries, and then unloads the current library:

Using $ZF(-3) to load libraries and call functions

   // define Callout library paths
   set libOne = "c:\intersystems\iris\bin\myfirstlibrary.dll"
   set libTwo = "c:\intersystems\iris\bin\anotherlibrary.dll"

   //load and call
   SET result1=$ZF(-3,libOne,"FuncA",123)   // loads libOne and calls FuncA
   SET result2=$ZF(-3,"","FuncB","xyz")   // calls FuncB from same library

   //load, then call with null name
   SET status=$ZF(-3,libTwo)   // unloads libOne, loads libTwo
   SET result1=$ZF(-3,"","FunctionOne","arg1")
   SET result2=$ZF(-3,"","FunctionTwo","argA", "argB")

   //unload
   SET status=$ZF(-3,"")   // unloads libTwo

• For convenience, the library names are assigned to strings libOne and libTwo.

• The first call to $ZF(-3) loads Callout library libOne and invokes function FuncA from that library.

• The second call specifies a null string for the library name, indicating that currently loaded libOne should be used again, and invokes function FuncB from that library.

• The third call to $ZF(-3) specifies only library name libTwo. This unloads libOne and loads libTwo, but does not invoke any library functions. The call returns a status code indicating whether libTwo was successfully loaded.

• The fourth and fifth calls invoke library functions FunctionOne and FunctionTwo from currently loaded libTwo.

• The final $ZF(-3) call does not invoke a library function, and specifies a null string for the library name. This unloads libTwo and does not load a new library. The call returns a status code indicating whether libTwo was successfully unloaded.

The following sections of this chapter describe $ZF functions that can load more than one library at a time. These functions will not conflict with $ZF(-3). You can always use $ZF(-3) as if it were loading and unloading its own private copy of a library.