Using Auto Glue

Users of CALL_EXTERNAL frequently write small functions with the sole purpose of matching the CALL_EXTERNAL portable calling convention with its (argc, argv) interface to the actual interface presented by some existing function that they wish to call. Such functions are often called glue functions.

It quickly becomes obvious to anyone who has written a few glue functions that there isn’t much to them, and that producing such functions is a purely mechanical operation. As you read the examples in this section, you will see many such functions, and will notice that they are all essentially the same. Further examination should serve to convince you that IDL already has all of the information, in the form of the arguments and keywords specified to the CALL_EXTERNAL function, to generate such functions without requiring human intervention. Examining the CALL_EXTERNAL routine’s interface, we see that:

• the number and types of arguments to the CALL_EXTERNAL function provide the same information about the arguments for the target external function;
• the VALUE keyword, and CALL_EXTERNAL’s built in rules for deciding whether or not to pass arguments by value or by reference determine how the arguments should be passed;
• in the case of Microsoft Windows, the CDECL keyword tells it which system calling convention to employ;
• keywords to CALL_EXTERNAL determine the result type.

Furthermore, other than the actual name of the user function being called, these glue functions are generic in the sense that they could be used to call any function that accepted arguments of the same types and produce a result of the same type.

The AUTO_GLUE keyword to CALL_EXTERNAL exploits these facts to allow you to call functions with natural interfaces, without the need to write, compile, and load a glue function to do the job. The sole requirement is that your system must have a C compiler installed that is compatible with the compiler described by the IDL !MAKE_DLL system variable. This is almost always the case if you are interested in calling external code, since a compiler is necessary to compile such code.

AUTO_GLUE automatically writes the C code for the glue function, uses the MAKE_DLL procedure to build a sharable library containing it, loads that library, and then calls the glue function, passing it a pointer to the target function and all of its arguments. It maintains a cache of glue functions that have been built previously, and never builds the same glue function more than once. From the user perspective, there is a slight pause the first time a given glue function is used. In that brief moment, AUTO_GLUE performs the steps described above, and then makes the call to the user function. All of this happens transparently to the IDL user; no user interaction is required, and no output is produced by the process. Subsequent calls to the same glue function happen instantaneously, as IDL loads the existing glue function from the MAKE_DLL cache without rebuilding it. In principle, it is similar to the way IDL automatically compiles IDL language programs on demand, only with C code instead of IDL code.

See CALL_EXTERNAL for additional details about how AUTO_GLUE works, and the options for controlling its use.

Generating Glue Without Executing It

AUTO_GLUE is the preferred option for most calls to functions with natural interfaces, due to it’s simplicity and ease of use. However, you might find yourself in a situation where you would like your glue functions to be automatically generated, but wish to get the resulting C code so that you can modify it or incorporate it into a larger library. For example, you might have a large library of IDL specific code, and wish to give it all IDL callable interfaces without requiring the overhead of AUTO_GLUE for all of them.

The WRITE_WRAPPER keyword to CALL_EXTERNAL can be used to produce such code without compiling or using the results. See CALL_EXTERNAL for additional information on this keyword.