$ZF(-4) (ObjectScript)
Synopsis
$ZF(-4,1,dll_name)
$ZF(-4,n,dll_id,func_name)
$ZF(-4,n,dll_id,decr_flag)
$ZF(-4,n,dll_index,dll_name)
$ZF(-4,n,dll_index,decr_flag)
Arguments
Argument | Description |
---|---|
n | A code for the type of operation to perform: 1=load DLL by name. 2=unload DLL by id. 3=look up function in DLL by id. 4=unload DLL by index. 5=create an entry in the system DLL index table. 6=delete an entry in the system DLL index table. 7=create an entry in the process DLL index table. 8=delete an entry in the process DLL index table. |
dll_name | The name of the dynamic-link library (DLL). Used with n=1, 5, or 7. |
dll_id | The id value of a loaded dynamic-link library (DLL). Used with n=2, or 3. |
dll_index | A user-defined index to a dynamic-link library (DLL) in a DLL index table. Must be a unique, positive, nonzero integer. The numbers 1024 through 2047 are reserved for system use. Used with n=4, 5, 6, 7, or 8. |
func_name | The name of the function to look up within the DLL. Used only when n=3. |
decr_flag | Optional — A flag for decrementing the DLL reference count. Used with n=2 or 4. |
Description
$ZF(-4) can be used to establish an ID value for a DLL or for a function within a DLL. These ID values are used by $ZF(-5) to execute a function.
$ZF(-4) can be used to establish an index to a DLL index table. These index values are used by $ZF(-6) to execute a function.
-
You can explicitly load shared libraries using $ZF(-4,1), which loads a library and returns a handle that can be used to access library functions with $ZF(-5).
-
You can explicitly load a single shared library using $ZF(-3), which loads a single active library and invokes its methods.
-
You can implicitly load shared libraries using $ZF(-6), after indexing a library with $ZF(-4,5) or $ZF(-4,7).
Establishing ID Values
To load a DLL and return its ID, use the following syntax:
dll_id=$ZF(-4,1,dll_name)
To look up a function from a DLL loaded by $ZF(-4,1), and return an ID for that function, use the following syntax:
func_id=$ZF(-4,3,dll_id,func_name)
To execute a function located by $ZF(-4,3), use $ZF(-5).
To unload a specific DLL loaded by $ZF(-4,1), use the following syntax:
$ZF(-4,2,dll_id)
To unload all DLLs loaded by $ZF(-4,1), use the following syntax:
$ZF(-4,2)
Increment and Decrement DLL Loads
When two classes have loaded the same library, the library will be unloaded by the first call to $ZF(-4,2,dll_id) or $ZF(-4,4,dll_index). This can leave the other class stranded without access to the library. For this reason, InterSystems IRIS supports a reference count on each DLL. InterSystems IRIS maintains a reference count of the number of times a library is loaded with $ZF(-4,1,dll_name). Each call to $ZF(-4,1,dll_name) increases the reference count.
$ZF(-4,2) provides an optional decrement flag argument, decr_flag. Each call to $ZF(-4,2,dll_id,1) decrements the reference count by 1. A call to $ZF(-4,2,dll_id,1) unloads the library if the reference count goes to zero. A call to $ZF(-4,2,dll_id) (or $ZF(-4,2,dll_id,0)) ignores the reference count and unloads the library immediately.
A call to $ZF(-4,5) or $ZF(-4,7) establishes a library index. Subsequent calls to $ZF(-6) to execute a function implicitly loads the library and increment the reference count. Each call to $ZF(-4,4,dll_index,1) decrements this reference count by 1.
The reference count interactions between reference counts established by dll_name and dll_index are as follows:
-
Libraries loaded with $ZF(-4,1,dll_name) are not unloaded by a call to $ZF(-4,4,dll_index,1) unless the reference count is zero.
-
Libraries loaded with $ZF(-4,1,dll_name) are immediately unloaded by either $ZF(-4,2,dll_id) or $ZF(-4,4,dll_index) (with no decrement flag argument) with no regard to the reference count.
-
Libraries loaded implicitly with $ZF(-6) are not unloaded by $ZF(-4,2,dll_id,1), even if the reference count goes to zero; they can only be unloaded by $ZF(-4,4,dll_index,1).
-
Libraries loaded implicitly with $ZF(-6) are immediately unloaded by either $ZF(-4,2,dll_id) or $ZF(-4,4,dll_index) (with no decrement flag argument) with no regard to the reference count.
$ZF(-4,2) with no dll_id argument unloads all libraries immediately, without regard to the reference count, or whether they were loaded with $ZF(-4,1,dll_name) or implicitly with $ZF(-6).
Loading a DLL Dependent on Another DLL
On Windows, some 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. However, if one of these DLLs is invoked using $ZF(-4) or $ZF(-6), InterSystems IRIS first searches the directory from which the DLL is being loaded for dependent DLLs; if the dependent DLLs are not found there, the default search PATH is used. InterSystems IRIS does this by using a Windows load operation that temporarily adds the originating directory to the PATH while the DLL is loaded. This temporary PATH addition is used when the DLL is loaded by $ZF(-4) or $ZF(-6). This temporary PATH addition is not used when the DLL is loaded by $ZF(-3).
If a DLL dependency cannot be resolved, InterSystems IRIS issues a <DYNAMIC LIBRARY LOAD> error.
Establishing Index Values
To index a DLL in the system DLL index table, use the following syntax:
$ZF(-4,5,dll_index,dll_name)
To index a DLL in the process DLL index table, use the following syntax:
$ZF(-4,7,dll_index,dll_name)
To look up and execute a function indexed by $ZF(-4,5) or $ZF(-4,7), use $ZF(-6).
To unload an indexed DLL, use the following syntax:
$ZF(-4,4,dll_index)
To delete an index entry in the system DLL index table, use the following syntax:
$ZF(-4,6,dll_index)
To delete an index entry in the process DLL index table, use the following syntax:
$ZF(-4,8,dll_index)
To delete all index entries in the process DLL index table, use the following syntax:
$ZF(-4,8)
For a detailed description of how to use $ZF(-4) and $ZF(-5), refer to Using $ZF(-5) to Access Libraries by System ID.
For a detailed description of how to use $ZF(-4) and $ZF(-6), refer to Using $ZF(-6) to Access Libraries by User Index.