docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Using the Callout Gateway  /  InterSystems Callout Quick Reference


Using the Callout Gateway
InterSystems Callout Quick Reference
[Back] 
InterSystems: The power behind what matters   
Search:  


The $ZF() function provides a set of subordinate functions identified by one or two numeric arguments (for example, the $ZF(-100) 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:
$ZF(-100): Running Programs or System Commands
The $ZF(-100) function is used to run an external program or system command, or to launch an operating system shell. This is the only $ZF function that can be used without a Callout library (see Running Programs or System Commands with $ZF(-100) for more information and examples).
$ZF(-100)
Executes a program or an operating system command.
   $ZF(-100, keyword_flags, program, arguments )
parameters:
returns:
One of the following status codes:
Specifying Keywords
The following keywords control program execution and logging:
The following keywords and file specifiers control I/O redirection:
I/O redirection keywords are followed by an operator ( = or += ) and a filename or file path. Spaces are permitted around the operators. Standard input should point to an existing file. The standard output and standard error files are created if they don't exist and are truncated if they already exist. Use the = operator to create or truncate a file, or the += operator to append to an existing file. To make standard error and standard output to go to the same file, specify the same file for both keywords.
see also:
See Running Programs or System Commands with $ZF(-100) for more information and examples.
$ZF(-3) and $ZF(-5): Accessing Libraries by Name
The $ZF(-3) and $ZF(-5) functions allow an application to load InterSystems 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 ($ZF(-4,1) through $ZF(-4,3)) 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)
Utility function used with $ZF(-5). 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)
Utility function used with $ZF(-5). 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)
Utility function used with $ZF(-5). 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)
Utility function used with $ZF(-6). 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)
Utility function used with $ZF(-6). 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)
Utility function used with $ZF(-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)
Utility function used with $ZF(-6). 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)
Utility function used with $ZF(-6). 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.