$ZF(-4)

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

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, 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:

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).

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.