Using the Caché Callout Gateway
Statically Linked Callout Functions
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
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 a Caché 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 a Caché 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.
Creating a Custom CZF.EXE File in OpenVMS
By default, Caché for OpenVMS includes an image named CZF.EXE that already contains some Callout functions (see $ZF Function Calls for DSM for a description of the standard CZF.EXE functions).
Under OpenVMS (unlike the other operating systems discussed in this chapter) your Callout library will not be statically linked into a custom version of cache.exe. Instead, you simply replace the standard version of CZF.EXE with your custom version (see Creating a Caché Callout Library). The source code for the standard version is provided so that your custom version can include it.
Compile CZF.C
To prepare an CZF.OBJ file that you link with the external functions and Caché, compile CZF.C by issuing the following command from the DCL prompt:
$ CC CZF.C
Note:
OpenVMS only: Assemble CZF.M64
If using a CZF.M64 file, assemble it at this point (as described in Using CZF.M64) to create CZF.OBJ.
Link the object files to create CZF.EXE.
Use the CZFBUILD.com file to link in the external functions. You edit CZFBUILD.com to add the files you will link. CZFBUILD.com looks like this before you edit it:
LINK/NOTRACE/MAP=CZF/SHAREABLE=CZF SYS$INPUT:/OPTIONS
        CLUSTER=CZF,,,CZF
        GSMATCH=ALWAYS,0,0
        SYMBOL_VECTOR=(ZFE=DATA)
  1. Edit CZFBUILD.COM to include CZF.OBJ and each of the external object files. Add each filename containing external functions for which you defined in the CZF file to the second line in CZFBUILD.COM. For instance, if the functions are in two files named abc.obj and xyz.obj, the second line will look like this after you edit it:
    CLUSTER=CZF,,,CZF,ABC,XYZ
  2. Run CZFBUILD.COM at the DCL prompt. This creates the file, CZF.EXE.
Note:
If your code does a #include "callin.h" and makes calls back into Caché, you must also link to the Caché sharable image.
The command must be issued in an options file, not at the command line.
Shut Down Caché and Install CZF.EXE
Issue the following command:
CCONTROL STOP <configname>
where <configname> is the installation of Caché to shut down.
You might need to unload the Caché executables from shared memory in order to replace CZF.EXE. Use:
CCONTROL UNLOAD <configname>
where <configname> is the installation of Caché to unload.
Then, copy CZF.EXE from your private directory to the <install-dir>:[bin] subdirectory, for example:
COPY CZF.EXE DKA0:[CACHESYS.BIN]
Restart Caché
To restart Caché, issue the following command:
CCONTROL START <configname>
where <configname> is the installation of Caché to start.