$ZF(-3)

Loads a Dynamic-Link Library (DLL) and executes a library function.

Synopsis

$ZF(-3,dll_name,func_name,args)

Parameters

Argument	Description
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()Opens in a new tab method of the %SYSTEM.UtilOpens in a new tab 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).