Caché ObjectScript Reference
$ZF(-4)
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
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, Caché supports a reference count on each DLL. Caché 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).
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 Caché 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 Caché Callout Gateway.
See Also