InterSystems $ZF Callout Quick Reference
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): Run Programs or System Commands
-
$ZF(-100) — executes a program or system command. Also see $ZF(-100) (ObjectScript) in the ObjectScript Reference.
-
-
$ZF(): Call the iriszf Library
-
$ZF() (no subordinate function arguments) — attempts to invoke a function from a custom Callout library named iriszf located in the bin directory of the current instance. Also see $ZF() (ObjectScript) in the ObjectScript Reference.
-
-
-
$ZF(-3) — loads a Callout library and invokes a library function. Also see $ZF(-3) (ObjectScript) in the ObjectScript Reference.
-
-
-
$ZF(-5) — invokes a function from a Callout library referenced by system-defined ID number.
-
$ZF(-4,1) — loads a Callout library specified by name, and returns an ID number for it.
-
$ZF(-4,2) — unloads a Callout library specified by ID number, or unloads all libraries.
-
$ZF(-4,3) — returns an ID number for a function in the specified library.
Also see $ZF(-5) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
-
-
-
-
$ZF(-6) — invokes a function from a Callout library referenced by user-specified index number.
-
$ZF(-4,4) — unloads a Callout library specified by index number.
-
$ZF(-4,5) — creates an entry in the Callout system index table
-
$ZF(-4,6) — deletes an entry in the Callout system index table
-
$ZF(-4,7) — creates an entry in the Callout process index table
-
$ZF(-4,8) — deletes an entry in the Callout process index table
-
Also see $ZF(-6) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
-
$ZF(-100): Run 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).
Executes a program or an operating system command.
$ZF(-100, keyword_flags, program, arguments )
parameters:
-
keyword_flags — (optional) A string expression consisting of a sequence of flags of the form /keyword. Keywords can be in upper or lowercase, and blanks are allowed between flags. I/O redirection keywords are followed by an operator and a path string (/keyword=path or /keyword+=path) as described below (see “Specifying Keywords”).
-
program — Specifies the program to be executed. It can be a full path or simply a name, in which case the usual operating system search path rules are followed.
-
arguments — (optional) A comma-delimited list of program arguments. A variable number of parameters can be also be specified with arg... syntax (see “Variable Number of Parameters” in Using ObjectScript).
returns:
One of the following status codes:
-
-1 — An operating system error occurred and the details are logged in SYSLOG.
-
0 — If /ASYNCH is specified, indicates that the program was successfully started.
-
status — If /ASYNCH is not specified, status is the exit code (0 or a positive number) returned by the program when it ends.
The following keywords control program execution and logging:
-
/SHELL — Indicates that the program should be invoked within an operating system shell. The default is to not use a shell.
-
/ASYNC — Indicates that the program should run asynchronously, allowing the $ZF(-100) call to return without waiting for it to complete.
-
/LOGCMD — Causes the program command line to be logged in messages.log. This is a debugging tool that provides a way to view the arguments exactly as they are received by the program.
The following keywords and file specifiers control I/O redirection:
-
/STDIN=input-file
-
/STDOUT=output-file or /STDOUT+=output-file
-
/STDERR=error-file or /STDERR+=error-file
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. Also see $ZF(-100) (ObjectScript) in the ObjectScript Reference.
$ZF(): Call the iriszf Library
If $ZF() is called without a negative number argument (for example, $ZF("myFunction",arg)), it attempts to invoke a function from a custom Callout library named iriszf (see “Using $ZF() to Access the iriszf Callout Library”).
Trys to invoke a function from a custom Callout library named iriszf. Once you have created and installed this library, its functions are immediately available to $ZF() without the need to load the library or specify a library identifier.
retval = $ZF(func_name[, arg1[, ...argN]])
parameters:
-
func_name — The name of the library function as specified in the ZFEntry table (see “Creating a ZFEntry Table”).
-
args — (optional) a comma-delimited list containing any arguments required by the library function.
returns:
-
retval — the output value of the library function, or NULL if the library function does not set an output value.
see also:
See “Creating an InterSystems Callout Library” and “Using $ZF() to Access the iriszf Callout Library” for details and examples. Also see $ZF() (ObjectScript) in the ObjectScript Reference.
$ZF(-3): Call 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 known 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.
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:
-
lib_name — The name of the Callout library as specified in the ZFEntry table (see “Creating a ZFEntry Table”). If a library has already been loaded by a previous call to $ZF(-3), an empty string ("") can be used to specify the current library.
-
func_name — The name of the function to look up within the Callout library.
-
func_id — sequence number of the library function within the ZFEntry table. If this number is known, it may be used instead of the function name for faster access (entries are numbered consecutively from 1).
-
args — (optional) a comma-delimited list containing any arguments required by the library function.
returns:
-
retval — the output value of the library function, or NULL if the library function does not set an output value.
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. Also see $ZF(-3) (ObjectScript) in the ObjectScript Reference.
$ZF(-5): Call by System ID
The $ZF(-5) function allows an application to load InterSystems Callout shared libraries and invoke library functions at runtime. Library paths and library function names must be known by the calling application. Libraries and functions are specified by system-defined ID numbers.
Utility functions $ZF(-4,1), $ZF(-4,2), and $ZF(-4,3) are used only with $ZF(-5). They provide services to acquire library ID numbers and to load or unload libraries.
Calls a function from a Callout library referenced by system-defined ID number.
retval = $ZF(-5,lib_id,func_id,args)
parameters:
-
lib_id — The Callout library ID number supplied by $ZF(-4,1).
-
func_id — The library function ID number supplied by $ZF(-4,3).
-
args — (optional) a comma-delimited list containing any arguments required by the library function.
returns:
-
retval — The output value of the library function, or NULL if the library function does not set an output value.
see also:
See “Using $ZF(-5) to Access Libraries by System ID” for details and examples. Also see $ZF(-5) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
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:
-
lib_name — The name of the Callout library to be loaded.
returns:
-
lib_id — A system-defined identifier used to reference lib_name.
see also:
See “Using $ZF(-5) to Access Libraries by System ID” for details and examples. Also see $ZF(-5) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
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:
-
lib_id — The system-defined identifier returned by $ZF(-4,1). If not specified, all libraries loaded by $ZF(-4,1) or $ZF(6) are unloaded.
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 Also see $ZF(-5) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
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 the ZFEntry table (see “Creating a ZFEntry Table”).
func_id = $ZF(-4,3, lib_id, func_name)
parameters:
-
lib_id — The system-defined library identifier returned by $ZF(-4,1).
-
func_name — The name of the function to look up within the Callout library.
returns:
-
func_id — The returned ID number for the specified library function.
see also:
See “Using $ZF(-5) to Access Libraries by System ID” for details and examples. Also see $ZF(-5) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
For utility functions $ZF(-4, 4) through $ZF(-4, 8), see the next section (“$ZF(-6): Call by User Index”)
$ZF(-6): Call 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 only by $ZF(-6). They provide services to unload libraries and to create or maintain indexes.
Look up and execute a function in an indexed Callout library.
retval = $ZF(-6,lib_index,func_id,args)
parameters:
-
lib_index — A user-specified index to a Callout library (created by $ZF(-4,5) or $ZF(-4,7))
-
func_id — (optional) The ID number of the function within the Callout library, which is the function index in the library's ZFEntry table. If omitted, call verifies the validity of lib_index, loads the library, and returns the full library filename.
-
args — (optional) a comma-delimited list containing any arguments required by the library function.
returns:
-
retval — The output value of the library function, or NULL if the library function does not set an output value.
see also:
See “Using $ZF(-6) to Access Libraries by User Index” for details and examples. Also see $ZF(-6) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
For utility finctions $ZF(-4, 1), $ZF(-4, 2), and $ZF(-4, 3), see the previous section (“$ZF(-5): Call by System ID”)
Utility function used with $ZF(-6). Unloads a Callout library specified by index number.
$ZF(-4,4,lib_index)
parameter:
-
lib_index — A user-specified Callout library index number (created by $ZF(-4,5) or $ZF(-4,7))
see also:
See “Using $ZF(-6) to Access Libraries by User Index” for details and examples. Also see $ZF(-6) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
Utility function used with $ZF(-6). Creates an entry in the Callout system index table.
$ZF(-4,5,lib_index,lib_name)
parameters:
-
lib_index — A unique user-specified number that will be used to reference the Callout library.
-
lib_name — The name of the Callout library to be indexed.
see also:
Details and examples in “Using $ZF(-6) to Access Libraries by User Index”. Also see $ZF(-6) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
Utility function used with $ZF(-6). Deletes an entry in the Callout system index table.
$ZF(-4,6,lib_index)
parameters:
-
lib_index — An index number previously defined by a call to $ZF(-4,5). This argument is required (unlike $ZF(-4,8), where it can be omitted).
see also:
See “Using $ZF(-6) to Access Libraries by User Index” for details and examples. Also see $ZF(-6) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
Utility function used with $ZF(-6). Creates an entry in the Callout process index table.
$ZF(-4,7,lib_index,lib_name)
parameters:
-
lib_index — A unique user-specified number that will be used to reference the Callout library.
-
lib_name — The name of the Callout library to be indexed.
see also:
See “Using $ZF(-6) to Access Libraries by User Index” for details and examples. Also see $ZF(-6) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.
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:
-
lib_index — (optional) An index number previously defined by a call to $ZF(-4,7). If not specified, all index entries are deleted.
see also:
See “Using $ZF(-6) to Access Libraries by User Index” for details and examples. Also see $ZF(-6) (ObjectScript) and $ZF(-4) (ObjectScript) in the ObjectScript Reference.