Caché ObjectScript Reference
$ZF(-3)
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Loads a Dynamic-Link Library (DLL) and executes a library function.
Synopsis
$ZF(-3,dll_name,func_name,args)
Parameters
dll_name The name of the dynamic-link library (DLL) to load, specified as a quoted string. When a DLL is already loaded, dll_name can be specified as a null string ("").
func_name Optional — The name of the function to execute within the DLL, specified as a quoted string.
args Optional — A comma-separated list of arguments to pass to the function.
Description
Use $ZF(-3) to load a Dynamic-Link Library (DLL) and execute the specified function from that DLL. $ZF(-3) returns the function’s return value.
$ZF(-3) can be invoked in any of the following ways:
To just load a DLL:
   SET x=$ZF(-3,"mydll")
To load a DLL and execute a function located in that DLL:
   SET x=$ZF(-3,"mydll","$$myfunc",1)
Loading a DLL using $ZF(-3) makes it the current DLL, and automatically unloads the DLL loaded by a previous invocation of $ZF(-3).
To execute a function located in a DLL loaded by a previous $ZF(-3), you can speed execution by specifying the current DLL using the null string, as follows:
   SET x=$ZF(-3,"","$$myfunc2",1)
To explicitly unload the current DLL (loaded by a previous $ZF(-3) call):
   SET x=$ZF(-3,"")
$ZF(-3) can load only one DLL. Loading a DLL unloads the previous DLL. You can also explicitly unload the currently loaded DLL, which would result in no currently loaded DLL. (However, note that $ZF(-3) loads and unloads do not affect loads and unloads for use with $ZF(-5) or $ZF(-6), as described below.)
The DLL name specified can be a full pathname, or a partial pathname. If you specify a partial pathname, Caché canonicalizes it to the current directory. Generally, DLLs are stored in the binary directory (“bindir”). To locate the binary directory, call the BinaryDirectory() method of the %SYSTEM.Util class. For further details, refer to the InterSystems Class Reference.
Notes
Dynamic-Link Libraries
A DLL is a binary library that contains routines that can be loaded and called at runtime. When a DLL is loaded, Caché finds a function named GetZFTable() within it. If GetZFTable() is present, it returns a pointer to a table of the functions located in the DLL. Using this table, $ZF(-3) calls the specified function from the DLL.
Loading Multiple DLLs
Calls to $ZF(-3) can only load one DLL at a time; loading a DLL unloads the previous DLL. To load multiple DLLs concurrently, execute DLL functions with $ZF(-5) or $ZF(-6). Loading or unloading a DLL using $ZF(-3) has no effect on DLLs loaded for use with $ZF(-5) or $ZF(-6).
See Also