Passing String Data

To pass a string by reference, IDL passes the address of its IDL_STRING descriptor. To pass a string by value the string pointer (the s field of the descriptor) is passed. Programmers should be aware of the following when manipulating IDL strings:

Called code should treat the information in the passed IDL_STRING descriptor and the string itself as read-only, and should not modify these values.

The slen field contains the length of the string without including the NULL termination that is required at the end of all C strings.

The stype field is used internally by IDL to keep track of how the memory for the string was obtained, and should be ignored by CALL_EXTERNAL users.

s is the pointer to the actual C string represented by the descriptor. If the string is NULL, IDL represents it as a NULL (0) pointer, not as a pointer to an empty null terminated string. Hence, called code that expects a string pointer should check for a NULL pointer before dereferencing it.

You must use the functions discussed in IDL Internals: String Processing to allocate the memory for an IDL_STRING. Attempting to do this directly by allocating dynamic memory and assigning it to the IDL_STRING descriptor is a common pitfall, as discussed in Common CALL_EXTERNAL Pitfalls.

Returning a String Value

When returning a string value, a function must allocate the memory used to hold it. On return, IDL will copy this string. You can use a static buffer or dynamic memory, but do not return the address of an automatic (stack-based) variable.

Example

The following routine, found in string_array.c, demonstrates how to handle string variables in external code. This routine takes a string or array of strings as input and returns a copy of the longest string that it received. It is important to note that this routine uses a static char array as its return value, which avoids the possibility of a memory leak, but which must be long enough to handle the longest string required by the application. This is implemented as a function with a natural C interface, and a second glue routine that implements the IDL portable convention, using the one with the natural interface to do the actual work:

Figure 3-1: Handling String Variables in External Code — string_array.c

Figure 3-1: Handling String Variables in External Code — string_array.c
C	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 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41	#include <stdio.h> #include <string.h> #include "idl_export.h" /* * IDL_STRING is declared in idl_export.h like this: * typedef struct { * IDL_STRING_SLEN_T slen; Length of string, 0 for null * short stype; Type of string, static or dynamic * char s; Address of string } IDL_STRING; * However, you should rely on the definition in idl_export.h instead * of declaring your own string structure. / char string_array_natural(IDL_STRING str_descr, IDL_LONG n) { / * IDL will make a copy of the string that is returned (if it is * not NULL). One way to avoid a memory leak is therefore to return * a pointer to a static buffer containing a null terminated string. * IDL will copy the contents of the buffer and drop the reference * to our buffer immediately on return. / #define MAX_OUT_LEN 511 / truncate any string longer than this / static char result[MAX_OUT_LEN+1]; / leave a space for a '\0' on the longest string / int max_index; / index of longest string / int max_sofar; / length of longest string/ int i; / Check the size of the array passed in. n should be > 0./ if (n < 1) return (char ) 0; max_index = 0; max_sofar = 0; for(i=0; i < n; i++) { if (str_descr[i].slen > max_sofar) { max_index = i; max_sofar = str_descr[i].slen; } }
C	42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69	/* * If all strings in the array are empty, the longest * will still be a NULL string. / if (str_descr[max_index].s == NULL) return (char ) 0; /* * Copy the longest string into the buffer, up to MAX_OUT_LEN * characters. * Explicitly store a NULL byte in the last byte of the buffer, * because strncpy() does not NULL terminate if the string copied * is truncated. / strncpy(result, str_descr[max_index].s, MAX_OUT_LEN); result[sizeof(result)-1] = '\0'; return(result); #undef MAX_OUT_LEN } char string_array(int argc, void* argv[]) { /* * Make sure there are the correct # of arguments. * IDL will convert the NULL into an empty string (''). / if (argc != 2) return (char ) NULL; return string_array_natural((IDL_STRING *) argv[0], (IDL_LONG) argv[1]); }

Figure 3-1: Handling String Variables in External Code — string_array.c

#include <stdio.h>  
#include <string.h>  
#include "idl_export.h"  
/*  
 * IDL_STRING is declared in idl_export.h like this:  
 *   typedef struct {  
 *   IDL_STRING_SLEN_T slen;        Length of string, 0 for null  
 *   short stype;                   Type of string, static or dynamic  
 *   char *s;                       Address of string  
 * } IDL_STRING;  
 * However, you should rely on the definition in idl_export.h instead  
 * of declaring your own string structure.  
*/  
   
char* string_array_natural(IDL_STRING *str_descr, IDL_LONG n)  
{  
  /*  
  * IDL will make a copy of the string that is returned (if it is   
  * not NULL). One way to avoid a memory leak is therefore to return   
  * a pointer to a static buffer containing a null terminated string.  
  * IDL will copy the contents of the buffer and drop the reference  
  * to our buffer immediately on return.  
  */  
#define MAX_OUT_LEN 511                 /* truncate any string   
                                           longer than this */  
  static char result[MAX_OUT_LEN+1];   /* leave a space for a '\0'   
                                          on the longest string */  
  int max_index;                /* index of longest string */  
  int max_sofar;                /* length of longest string*/  
  int i;  
   
  /*  Check the size of the array passed in. n should be > 0.*/  
  if (n < 1) return (char *) 0;  
  max_index = 0;  
  max_sofar = 0;  
  for(i=0; i < n; i++) {  
    if (str_descr[i].slen > max_sofar) {  
      max_index = i;  
      max_sofar = str_descr[i].slen;  
    }  
  }

 /*  
  * If all strings in the array are empty, the longest  
  * will still be a NULL string.  
  */  
  if (str_descr[max_index].s == NULL) return (char *) 0;  
   
  /*  
  * Copy the longest string into the buffer, up to MAX_OUT_LEN  
  * characters.  
  * Explicitly store a NULL byte in the last byte of the buffer,  
  * because strncpy() does not NULL terminate if the string copied  
  * is truncated.  
  */  
  strncpy(result, str_descr[max_index].s, MAX_OUT_LEN);  
  result[sizeof(result)-1] = '\0';  
  return(result);  
#undef MAX_OUT_LEN  
}  
   
char* string_array(int argc, void* argv[])  
{  
  /*  
  * Make sure there are the correct  # of arguments.  
  * IDL will convert the NULL into an empty string ('').  
  */  
  if (argc != 2) return (char *) NULL;  
  return string_array_natural((IDL_STRING *) argv[0], (IDL_LONG) argv[1]);  
}

IDL Online Help (March 06, 2007)