Skip to main content
Previous section   

InterSystems 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(): Using the iriszf Callout 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”).

$ZF()

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]])
Copy code to clipboard

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.

$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 )
Copy code to clipboard

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.

Specifying Keywords

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.

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

$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]])
Copy code to clipboard

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.

$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)
Copy code to clipboard

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.

$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])
Copy code to clipboard

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

$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 the ZFEntry table (see “Creating a ZFEntry Table”).

  func_id = $ZF(-4,3, lib_id, func_name)
Copy code to clipboard

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.

Note:

For $ZF(-4, 4) through $ZF(-4, 8), see the next section (“$ZF(-6): Accessing Libraries by User Index”)

$ZF(-5)

Calls a function from a Callout library referenced by system-defined ID number.

   retval = $ZF(-5,lib_id,func_id,args)
Copy code to clipboard

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.

$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)
Copy code to clipboard

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.

$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)
Copy code to clipboard

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

$ZF(-4, 6)

Utility function used with $ZF(-6). Deletes an entry in the Callout system index table.

   $ZF(-4,6,lib_index)
Copy code to clipboard

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.

$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)
Copy code to clipboard

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.

$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)
Copy code to clipboard

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.

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)
Copy code to clipboard

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.

Previous section