docs.intersystems.com
Using the Callout Gateway
Statically Linked Callout Functions
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Search:    

Previous chapters in this book have discussed how to create a stand-alone Callout library that can be loaded at runtime. However, it is also possible to statically link your Callout functions into a custom version of Caché so that they are always available. Since the functions are linked into Caché, there is no need to explicitly load a Callout library or to specify a library when invoking a function.

This chapter discusses the following topics:
Invoking Statically Linked Callout Functions
The calling convention for a statically linked Callout function is different than that of a dynamic library. For example:
   $ZF(-3,"mylibrary","MYFUNC",args...)
would become:
   $ZF("MYFUNC",args...)
Since your functions are statically linked, there is no need to specify a subfunction number and library name (such as -3,"mylibrary" in this example).
Creating a Custom CACHE.EXE File in Windows
It is assumed that you have a file named mycallouts.c that contains code identical to the code for a Callout library (see Creating an InterSystems Callout Library) except that it does not contain a #define ZF_DLL directive. The steps to compile and link it are as follows:
Compile or assemble the external functions
To compile mycallouts.c on Windows, use the command:
cl -c mycallouts.c
This produces an output file called mycallouts.obj that you can link to Caché.
Link the object file and Caché object files into a new version of Caché
To link the C functions for use with $ZF:
  1. Either perform your build in the <install-dir>/Dev/Cache/callin directory (where <install-dir> is the root directory for your configuration), or make a private directory of your own with a copy of the required files. You are linking together the following files:
    You link them with the file mycallouts.obj that you created by compiling mycallouts.c in your private directory.
  2. Replace the file czf.obj with mycallouts.obj.
  3. Build the project. This produces the file cache.exe in your private directory. If you keep the C functions in separate files, you need to compile them separately and declare them in mycallouts.c, but not include them there. If you get the message “Unresolved externals...,” you may need to include other libraries. Call InterSystems Worldwide Response Center if you need help in determining which files to include.
  4. Save the current installed version of cache.exe that is in <install-dir>/bin (where <install-dir> is the root directory for your configuration), so you can restore it.
Shut down Caché and replace the Caché executable with the new file
To reinstall Caché for Windows:
  1. Stop Caché using the Stop Caché choice from the cube menu.
  2. Copy the cache.exe file from your private directory to <install-dir>/bin, where <install-dir> is the root directory for your configuration.
When you restart Caché, the functions are available.
Restart Caché
On Windows, start Caché from the Caché Cube.
You now have a version of Caché that includes your C functions.
To return to the original version of Caché in the Caché manager's directory (on Windows):
  1. Shut down Caché.
  2. Copy the original saved cache.exe into <install-dir>/bin, where <install-dir> is the root directory for your configuration.
Creating a Custom CACHE.EXE File in UNIX®, Linux, or OS-X
It is assumed that you have a file named mycallouts.c that contains code identical to the code for a Callout library (see Creating an InterSystems Callout Library) except that it does not contain a #define ZF_DLL directive. The steps to compile and link it are as follows:
Compile or assemble the external functions
To compile mycallouts.c, use the command:
cc -c mycallouts.c
Link the object file and Caché object files into a new version of Caché
To link the C functions for use with $ZF:
  1. Either perform your build in the <install-dir>/dev/cache/callin/samples directory, or make a private directory of your own with a copy of the required files. You are linking together the following files:
    • cache.o (provided with the Caché distribution kit)
    • main.o (provided with the Caché distribution kit)
    • shdir.o (shdir.c must be compiled manually)
    • mycallouts.o (created by you in your private namespace)
  2. Build the project. If you get the message “Unresolved externals,” you may need to include other libraries; call InterSystems if you need help in determining which files to include. Note that if you place the C functions in separate files, you need to compile them separately and declare them in mycallouts.c, but not include them there.
  3. Save the version of Caché that is in /cachesys/bin/ (or wherever your installation directory may be) so that you can restore it, if necessary.
Shut down Caché and replace the Caché executable with the new file
To replace the Caché executable:
  1. Shut down Caché by calling
    ccontrol stop <configname>
    where <configname> is the name of the Caché installation.
  2. Copy the file cache from the private directory to <install-dir>/bin/, where <install-dir> is the root directory for your configuration.
Restart Caché
Start up Caché with the cstart script or by calling:
ccontrol start <configname>
where <configname> is the installation of Caché to start.
To return to the original version of Caché in the Caché system manager's directory:
  1. Shut down Caché.
  2. Copy the original saved cache back into <install-dir>/bin, where <install-dir> is the root directory for your configuration.