docs.intersystems.com
Home / ObjectScript Reference / ObjectScript Functions / $ZF(-4)

ObjectScript Reference
$ZF(-4)
Previous section           Next section
InterSystems: The power behind what matters   
Search:  


Provides utility functions used with $ZF(-5) and $ZF(-6).
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)
Parameters
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.
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:
$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 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. However, if one of these DLLs is invoked using $ZF(-4) or $ZF(-6), 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. 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. 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, 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 in Using the Callout Gateway.
For a detailed description of how to use $ZF(-4) and $ZF(-6), refer to Using $ZF(-6) to Access Libraries by User Index in Using the Callout Gateway.
See Also


Previous section           Next section
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-05-14 12:01:32