The InterSystems Callout Gateway allows Caché applications to invoke shell or operating system commands, run external programs in spawned processes, and call functions from specially written shared libraries. The Callout Gateway is implemented as a suite of related functions contained in the Caché $ZF system function.
This chapter discusses the following topics:
Callout Gateway Concepts and Terminology — is a list of things you should know before reading the rest of this book.
Overview of $ZF Functions — is a quick summary of the capabilities provided by the Callout Gateway.
Compatible Languages and Compilers — discusses some of the software required to take full advantage of the Callout Gateway.
Callout Gateway Concepts and Terminology
Here are some important concepts that you should understand before reading the rest of this book:
Individual functions in the $ZF suite are identified by the first argument of the function call, which will be a negative number, -100 or -3 through -6. For example, the function that calls an operating system command has the form $ZF(-100, <oscommand>), where <oscommand> is a string containing the command to be executed. When this function is discussed, it will be referred to as $ZF(-100). In the same way, the other functions will be referred to as $ZF(-3) through $ZF(-6), using only the first parameter of the actual function call.
The $ZF(-4) function is a special case, since it is actually just a container for eight utility functions that are identified by the first two parameters: $ZF(-4,1) through $ZF(-4,8).
For a brief summary of these functions, see “Overview of $ZF Functions” later in this chapter. See the “InterSystems Callout Quick Reference” for a complete list of all $ZF functions, information on how they are used, and links to more detailed information and examples.
In this book, the term shared library refers to a dynamically linked file (a DLL file on Windows or an SO file on UNIX® and related operating systems). A Callout library is a shared library that includes hooks to the Callout Gateway, allowing various $ZF functions to load it at runtime and invoke its functions. Callout libraries are usually written in C (see“Compatible Languages and Compilers”), but could potentially be written in any other compiled language that uses a calling convention understood by your C compiler.
See “Creating an InterSystems Callout Library” for details about how to write a Callout library.
All of the $ZF functions except $ZF(-100) are used to provide some form of access to Callout libraries. The $ZF(-3), $ZF(-5), and $ZF(-6) functions provide three different interfaces for invoking Callout library functions, and $ZF(-4) is a container for various utility functions used with the $ZF(-5) and $ZF(-6) interfaces.
See “Invoking Callout Library Functions” for a details of the various ways to access a Callout library.
Overview of $ZF Functions
The $ZF function suite includes the following functions:
The $ZF(-100) function is used to run shell commands and operating system service calls. It is not used to access Callout libraries, and can be called without any previous setup.
See “Running Programs or System Commands with $ZF(-100)” for details.
The $ZF(-3) function is a simple way to load a Callout library and invoke a library function with a single statement. Both the library and its functions are specified by name, and the library remains in memory until replaced by a call to a different library.
See “Using $ZF(-3) for Simple Library Function Calls” for details.
The $ZF(-4) function just is a container for a set of eight utility functions. The $ZF(-5) function interface uses functions $ZF(-4,1) through $ZF(-4,3), and the $ZF(-6) function interface uses functions $ZF(-4,5) through $ZF(-4,8). See the following descriptions for more details.
The $ZF(-5) function and its utility functions allow multiple libraries to be handled efficiently. Both the library and its functions are identified by system-defined ID values. Several libraries can be in virtual memory at the same time. The following $ZF(-4) functions are used to load and unload libraries, and to obtain library and function ID values:
$ZF(-4,1) loads a library specified by name, and returns a library ID.
$ZF(-4,2) unloads a library.
$ZF(-4,3) returns a function ID for a specified library ID and function name.
See “Using $ZF(-5) to Access Libraries by System ID” for details.
The $ZF(-6) function and its utility functions provide a way to write Callout applications that do not require hard-coded library names. Instead, the actual library filenames are contained in a separate index table, where each library is associated with a unique, user-defined index number. Once the index table is defined, it is available to all processes in an instance of Caché. Callout applications identify a library by index number and load it by reading the index table. Several libraries can be in memory at the same time. The following functions are used to manage indexes and load or unload libraries:
$ZF(-6) invokes a library function, and loads the library if it is not already in memory.
$ZF(-4,4) unloads a library.
See “Using $ZF(-6) to Access Libraries by User Index” for details.
Although your C function code will usually be used to generate a Callout library, it could also be directly linked into a custom version of the Caché executable. The $ZF() function (with no negative number argument) is the interface for invoking statically linked Callout functions. Unlike $ZF(-3), $ZF(-5), or $ZF(-6), it does not need to specify an external library identifier, so statically linked functions can be called by just specifying the function name and arguments.
See “Statically Linked Callout Functions” for details.
Compatible Languages and Compilers
Using the Callout Gateway you can call routines written in languages other than ObjectScript. On all platforms that support Caché you can call routines written in the C language. In theory you should be able to call routines written in any compiled language that is compatible with C. Two compatibility issues arise. First, the compiler must use an Application Binary Interface (ABI) that is compatible with C. Second, the compiler must generate code that does not rely on any runtime library features that are not compatible with Caché.
InterSystems supports using the same C compiler that we use to generate Caché on all platforms:
|IBM AIX||IBM XL C for AIX|
|Mac OS X (Darwin)||Xcode|
|Microsoft Windows||Microsoft Visual Studio|
|Linux (all variants)||GNU Project GCC C|
Most platforms have a standardized Application Binary Interface (ABI), making most compilers compatible. The Intel x86-32 and x86-64 platforms are major exceptions, Multiple calling conventions exist for these platforms. See (https://en.wikipedia.org/wiki/X86_calling_conventions) for a discussion of calling conventions on these platforms.
Microsoft Windows uses the cdecl interface on x86-32 platforms and a calling convention that it documents in (http://msdn.microsoft.com/en-us/library/9b372w95%28v=VS.80%29.aspx) for x86-64.
Calling languages that use different calling conventions may be possible, as many C compilers allow declaring an external routine to have another calling convention. Therefore is it often possible to call routines written in other languages if one is willing to write a C wrapper routine.