Skip to main content
Previous sectionNext section

$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")
Copy code to clipboard

To load a DLL and execute a function located in that DLL:

   SET x=$ZF(-3,"mydll","$$myfunc",1)
Copy code to clipboard

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)
Copy code to clipboard

To explicitly unload the current DLL (loaded by a previous $ZF(-3) call):

   SET x=$ZF(-3,"")
Copy code to clipboard

$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, InterSystems IRIS canonicalizes it to the current directory. Generally, DLLs are stored in the binary directory ("bin"). 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, InterSystems IRIS 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).

Loading a DLL Dependent on Another DLL

On Windows, some IRIS system DLLs that are installed in the bin directory are dependent on other DLLs in the bin directory. Windows search rules do not find the dependencies in the bin directory unless bin is added to the process's PATH. From $ZF(-3) if a DLL dependency cannot be resolved using the process’s PATH, IRIS issues a <DYNAMIC LIBRARY LOAD> error.

However, if a dependent DLL is loaded using $ZF(-4), IRIS first searches the directory from which the DLL is being loaded for dependent DLLs. The IRIS system does this by using a Windows load operation that temporarily adds the originating directory to the PATH while the DLL is loaded. After being loaded by $ZF(-4), this dependent DLL can be used by $ZF(-3) without changing the PATH.

See Also