$ZF(-3) (ObjectScript)

Loads a Dynamic-Link Library (DLL) and executes a library function. This function is a component of the Callout SDK.

Synopsis

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

Arguments

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, 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()Opens in a new tab method of the %SYSTEM.UtilOpens in a new tab class. For further details, refer to the InterSystems Class Reference.

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 InterSystems 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, InterSystems IRIS issues a <DYNAMIC LIBRARY LOAD> error.

However, if a dependent DLL is loaded using $ZF(-4), InterSystems IRIS first searches the directory from which the DLL is being loaded for dependent DLLs. The InterSystems 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.