Wrapper Routines

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 directory.

.

Table 3-3: Wrapper Routine — simple_vars.pro

IDL 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 

PRO SIMPLE_VARS, b, i, l, f, d, AUTO_GLUE=auto_glue, DEBUG=debug, $ 
        VERBOSE=verbose 
  if ~ (KEYWORD_SET(debug)) THEN ON_ERROR,2 
  
  ; Type checking: Any missing (undefined) arguments will be set 
  ; to a default value. All arguments will be forced to a scalar 
  ; of the appropriate type, which may cause errors to be thrown 
  ; if structures are passed in. Local variables are used so that 
  ; the values and types of the user supplied arguments don't change. 
  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.

Note
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.