docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Using the Callout Gateway  /  Statically Linked Callout Functions


Using the Callout Gateway
Statically Linked Callout Functions
[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 InterSystems IRIS™ so that they are always available. Since the functions are linked into InterSystems IRIS, 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 InterSystems IRIS.
Link the object file and InterSystems IRIS object files into a new version of InterSystems IRIS
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 InterSystems IRIS and replace the InterSystems IRIS executable with the new file
To reinstall InterSystems IRIS for Windows:
  1. Stop InterSystems IRIS using the Stop InterSystems IRIS 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 InterSystems IRIS, the functions are available.
Restart InterSystems IRIS
On Windows, start InterSystems IRIS from the InterSystems IRIS launcher.
You now have a version of InterSystems IRIS that includes your C functions.
To return to the original version of InterSystems IRIS in the manager's directory (on Windows):
  1. Shut down InterSystems IRIS.
  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 InterSystems IRIS object files into a new version of InterSystems IRIS
To link the C functions for use with $ZF:
  1. Either perform your build in the <install-dir>/dev/cache/callin 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 InterSystems IRIS distribution kit)
    • main.o (provided with the InterSystems IRIS 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 InterSystems IRIS that is in /cachesys/bin/ (or wherever your installation directory may be) so that you can restore it, if necessary.
Shut down InterSystems IRIS and replace the InterSystems IRIS executable with the new file
To replace the InterSystems IRIS executable:
  1. Shut down InterSystems IRIS by calling
    ccontrol stop <configname>
    where <configname> is the name of the InterSystems IRIS 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 InterSystems IRIS
Start up InterSystems IRIS with the cstart script or by calling:
ccontrol start <configname>
where <configname> is the installation of InterSystems IRIS to start.
To return to the original version of InterSystems IRIS in the InterSystems IRIS system manager's directory:
  1. Shut down InterSystems IRIS.
  2. Copy the original saved cache back into <install-dir>/bin, where <install-dir> is the root directory for your configuration.