CALL_EXTERNAL routines are very sensitive to the number and type of the arguments they receive. Calling a CALL_EXTERNAL routine with the wrong number of arguments or with arguments of the wrong type can cause IDL to crash. For this reason, it is a good practice to provide an IDL wrapper routine that is used to make the actual CALL_EXTERNAL call. The job of this wrapper, which is written in the IDL language, is to ensure that the arguments that are passed to the external code are always of the correct number and type. The following IDL procedure is the wrapper used in the simple_vars() example of the previous section (Example: Passing Parameters by Reference to IDL).
Example Code
This file, simple_vars.pro, is located in the external/call_external/C
subdirectory of the IDL installation.
PRO SIMPLE_VARS, b, i, l, f, d, AUTO_GLUE=auto_glue, DEBUG=debug, $
VERBOSE=verbose
if ~ (KEYWORD_SET(debug)) THEN ON_ERROR,2
b_l = (SIZE(b,/TYPE) EQ 0) ? 2b : byte(b[0])
i_l = (SIZE(i,/TYPE) EQ 0) ? 3 : fix(i[0])
l_l = (SIZE(l,/TYPE) EQ 0) ? 4L : long(l[0])
f_l = (SIZE(f,/TYPE) EQ 0) ? 5.0 : float(f[0])
d_l = (SIZE(d,/TYPE) EQ 0) ? 6.0D : double(d[0])
PRINT, ’Calling simple_vars with the following arguments:’
HELP, b_l, i_l, l_l, f_l, d_l
func = keyword_set(auto_glue) ? ’simple_vars_natural’ : ’simple_vars’
IF (CALL_EXTERNAL(GET_CALLEXT_EXLIB(VERBOSE=verbose), func, $
b_l, i_l, l_l, f_l, d_l, /CDECL, $
AUTO_GLUE=auto_glue, VERBOSE=verbose, $
SHOW_ALL_OUTPUT=verbose) EQ 1) then BEGIN
PRINT,’After calling simple_vars:’
HELP, b_l, i_l, l_l, f_l, d_l
ENDIF ELSE MESSAGE,’External call to simple_vars failed’
END
The routine simple_vars.pro uses the system routine SIZE() to examine the arguments that are passed in by the user to the simple_vars routine. If one of the arguments is undefined, a default value will be used in the call to the external routine. Otherwise, the argument will be converted to a scalar of the appropriate type.
GET_CALLEXT_EXLIB() is a function provided with the CALL_EXTERNAL examples; it builds the necessary sharable library of external C code and returns the path to the library as its result.