Calling C Programs from IDL

Here are some general tips for using Call_External.

• All arrays which need to be passed between IDL and C must be allocated in IDL. This includes both arrays being passed from IDL to C and from C back to IDL. Sometimes this requires an initial call to the C code to return the array sizes which IDL will allocate, if the array sizes are not known to IDL beforehand.
• Don't deallocate any arrays which were passed from IDL.
• Don't pass strings, rather pass byte arrays. It is much simpler. Convert strings to byte arrays in IDL before or after the Call_External call.
• Convert all output variables to the data type which C is expecting in the Call_External call.

Question: What is the effect of the /CDECL keyword to Call_External?

Answer: This controls the calling convention. If your C function is being called then you probably have this set correctly.

Question: Is it possible that the C program "forgets" something between the IDL Call_External calls?

Answer: Yes, it will forget anything which is not global or static.

Question: How can I return an array via Call_External or have I always to loop over calls returning scalars ?

Answer: Here is a simple example. It is C code which computes the Mandelbrot set, and is called from IDL. The argv[7] argument is a 2-D array.

   void mandelbrot(int argc, void *argv[])
   {
    int nr = *(int *) argv[0];
    int ni = *(int *) argv[1];
    double rstart = *(double *) argv[2];
    double istart = *(double *) argv[3];
    double dr = *(double *) argv[4];
    double di = *(double *) argv[5];
    int max_iter = *(int *) argv[6];
    int *result =  argv[7];
   int i, j, count;
    double real, imag, rz, iz, sz2, rz2, iz2;
       for (i=0; i<ni; i++) {
         imag = istart + i*di;
         for (j=0; j<nr; j++) {
              real = rstart + j*dr;
              rz = 0.;
              iz = 0.;
              sz2 = 0.;

              count = 0;
              while ((count < max_iter) && (sz2 < 4.0)) {
                   rz2 = rz * rz;
                   iz2 = iz * iz;
                   iz = 2.0 * rz * iz + imag;
                   rz = rz2 - iz2 + real;
                   sz2 = rz2 + iz2;
                   count++;
              }
              *result++ = count;
         }
       }
   }

Here is the IDL code which calls the C code:

   function mandelbrot1, xcenter, ycenter, radius, size, max_iter, xout, yout
   if (n_elements(size) eq 0) then size=100
   if (n_elements(max_iter) eq 0) then max_iter=255
   dx = double(radius)*2/size
   xstart = double(xcenter - radius)
   xstop = double(xcenter + radius)
   ystart = double(ycenter - radius)
   ystop = double(ycenter + radius)
   result = lonarr(size, size)
   xout = xstart + findgen(size)*dx
   yout = ystart + findgen(size)*dx
   s = call_external('mandelbrot.dll', 'mandelbrot', $
                      long(size), $
                      long(size), $
                      double(xstart), $
                      double(ystart), $
                      double(dx), $
                      double(dx), $
                      long(max_iter), $
                      result)
   return, result
   end

Question: Can I pass IDL structures to my C program using Call_External?

Answer: [From 4 APRIL 1996] The last time I looked, the means by which structures are passed was intentionally not documented, presumably so that RSI would be free to change it in the future.

However, I know by experience that IDL presently passes structures just like you would expect (i.e. it passes the address of the start of the structure). All structure elements except strings are contained in the structure itself (i.e. the structure contains the value, not a pointer). Strings are different: the structure contains either the descriptor or the address of the descriptor (I forget).

I routinely pass structures to Call_External, but I do so at my own risk, since it is not guaranteed to be done the same way in future versions of IDL.

I have found that the structures will contain padding to keep the members aligned on natural boundaries. The C compiler will normally do this on the structures in yourCall_External code as well, so it has not been a problem.