Using the Caché Callout Gateway
Caché Callout Quick Reference
[Back] 
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

The Caché $ZF() function provides a set of subordinate functions identified by one or two numeric arguments (for example, the $ZF(-1) subordinate function runs an external program or system command, and the $ZF(-4,1) subordinate function loads a Callout library). The following list shows only the arguments that identify a specific $ZF() subordinate function. Most of these functions also take additional arguments, as described in the detailed entry for each function.

Detailed function descriptions are organized under the following headings:
Using Statically Linked Functions
When a function is statically linked with Caché (as described in Statically Linked Callout Functions), it is immediately available to $ZF() without the need to load a Callout library or specify a library name or identifier.
$ZF()
Calls a statically linked function. No subordinate $ZF function calls are required, since there is no need to load and identify a separate Callout library.
  retval = $ZF(func_name[, arg1[, ...argN]])
  retval = $ZF(func_id[, arg1[, ...argN]])
parameters:
returns:
see also:
See Creating a Caché Callout Library and Statically Linked Callout Functions for details and examples. For DSM VMS only, $ZF Function Calls for DSM describes a set of Caché-supplied $ZF functions that emulate System Service Zcall functions.
Running Programs or System Commands
The $ZF functions in this section are used to run an external program or system command in a child process, or to launch an operating system shell. These are the only $ZF functions that can be used without a Callout library (see Creating a Caché Callout Library).
$ZF(-1)
Executes a program or operating system command as a spawned child process, and suspends execution of the current process while waiting for the child process to return.
   status = $ZF(-1, oscommand)
The following additional signatures are valid only in OpenVMS:
   status = $ZF(-1, oscommand, outdev)
   status = $ZF(-1, oscommand, , indev)
   status = $ZF(-1, oscommand, outdev, indev)
parameters:
returns:
see also:
See Issuing System Commands with $ZF(-1) for details and examples.
$ZF(-2)
Executes a program or command as a spawned child process and returns immediately. Because it does not await completion of the spawned child process, it cannot receive status information from that process, but it does return a status code indicating whether the child process was successfully spawned.
   status = $ZF(-2, oscommand)
parameters:
returns:
see also:
See Spawning Concurrent Child Processes with $ZF(-2) for details and examples.
$ZF(-3) and $ZF(-5): Accessing Libraries by Name
The $ZF(-3) and $ZF(-5) functions allow an application to load Caché Callout shared libraries and invoke library functions at runtime. Library paths and library function names must be know by the calling application. $ZF(-3) specifies library and function names as arguments. $ZF(-5) specifies libraries and functions by system-defined ID numbers. Before $ZF(-5) can be used, the ID numbers must be obtained by calling utility functions that take library and function names as arguments.
$ZF(-3)
Loads a Callout library and executes a library function. Only one $ZF(-3) library may be loaded at a time. If a call to $ZF(-3) specifies a different library from the previous call, the previous library is unloaded and replaced.
   retval = $ZF(-3, lib_name, func_name[, arg1[, ...argN]])
   retval = $ZF(-3, lib_name, func_id[, arg1[, ...argN]])
parameters:
returns:
see also:
See Using $ZF(-3) for Simple Library Function Calls for details and examples. See $ZF(-4,3) for another way to obtain the ZFEntry table sequence number.
$ZF(-4, 1)
Loads a Callout library specified by name, and returns an ID number for it.
  lib_id = $ZF(-4,1, lib_name)
parameter:
returns:
see also:
See Using $ZF(-5) to Access Libraries by System ID for details and examples.
$ZF(-4, 2)
Unloads a Callout library specified by ID number. If no ID is specified, it unloads all libraries in the process that were loaded by either $ZF(-4,1) or $ZF(6). Does not unload the library loaded by $ZF(-3).
  $ZF(-4,2[,lib_id])
parameter:
see also:
See Using $ZF(-5) to Access Libraries by System ID for details and examples. Also see Using a Process Index for Testing for an example using $ZF(-4,2) without a library ID parameter
$ZF(-4, 3)
Returns an ID number for a function with the specified library ID and function name. This number is actually the sequence number of the function within ZFEntry table (see Creating a ZFEntry Table).
  func_id = $ZF(-4,3, lib_id, func_name)
parameters:
returns:
see also:
See Using $ZF(-5) to Access Libraries by System ID for details and examples.
Note:
For $ZF(-4, 4) through $ZF(-4, 8), see the next section (Using Indexed Callout Libraries)
$ZF(-5)
Calls a function from a Callout library referenced by system-defined ID number.
   retval = $ZF(-5,lib_id,func_id,args)
parameters:
returns:
see also:
See Using $ZF(-5) to Access Libraries by System ID for details and examples.
$ZF(-6): Accessing Libraries by User Index
The $ZF(-6) interface provides access to Callout libraries through a user-defined index table, usable even by applications that do not know the location of the shared library files. Utility functions $ZF(-4, 4) through $ZF(-4, 8) are used to create and maintain indexes.
Note:
For information on $ZF(-4, 1), $ZF(-4, 2), and $ZF(-4, 3), see the previous section ($ZF(-3) and $ZF(-5): Accessing Libraries by Name)
$ZF(-4, 4)
Unloads a Callout library specified by index number.
   $ZF(-4,4,lib_index)
parameter:
see also:
See Using $ZF(-6) to Access Libraries by User Index for details and examples.
$ZF(-4, 5)
Creates an entry in the Callout system index table.
   $ZF(-4,5,lib_index,lib_name)
parameters:
see also:
Details and examples in Using $ZF(-6) to Access Libraries by User Index.
$ZF(-4, 6)
Deletes an entry in the Callout system index table.
   $ZF(-4,6,lib_index)
parameters:
see also:
See Using $ZF(-6) to Access Libraries by User Index for details and examples.
$ZF(-4,7)
Creates an entry in the Callout process index table.
   $ZF(-4,7,lib_index,lib_name)
parameters:
see also:
See Using $ZF(-6) to Access Libraries by User Index for details and examples.
$ZF(-4,8)
Deletes an entry from the Callout process index table. If no index number is specified, all index entries are deleted.
   $ZF(-4,8,lib_index)
parameters:
see also:
See Using $ZF(-6) to Access Libraries by User Index for details and examples.
Note:
For $ZF(-5), see the previous section ($ZF(-3) and $ZF(-5): Accessing Libraries by Name)
$ZF(-6)
Look up and execute a function in an indexed Callout library.
   retval = $ZF(-6,lib_index,func_id,args)
parameters:
returns:
see also:
See Using $ZF(-6) to Access Libraries by User Index for details and examples.