IDL represents strings internally as IDL_STRING descriptors. For more information about IDL_STRING, see IDL Internals: Variables and IDL Internals: String Processing. These descriptors are defined in the C language as:

typedef struct { IDL_STRING_SLEN_T slen; 
   unsigned short stype; 
   char *s;
} IDL_STRING;

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

Note: IDL will not free dynamically-allocated memory for this use.

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:

 

 #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]);
}