Creating an Array from Existing Data

There are two functions that allow you to create an IDL array variable whose data points at data you supply rather than having IDL allocate the data space. The routine IDL_ImportArray() returns a temporary variable, while IDL_ImportNamedArray() returns a named variable in the current execution scope, creating the new variable if necessary. Your data must already exist in memory. The data area, which can be quite large, is not copied. These functions create variable and array descriptors that point to the data you supply and return the pointer to the resulting variable. Their definitions are:

IDL_VPTR IDL_ImportArray(int n_dim, IDL_MEMINT dim[], int type,

      UCHAR *data, IDL_ARRAY_FREE_CB free_cb, void *s)

 

IDL_VPTR IDL_ImportNamedArray(char *name, int n_dim, IDL_MEMINT dim[],

      int type, UCHAR *data, IDL_ARRAY_FREE_CB free_cb, void *s)

 

typedef void (* IDL_ARRAY_FREE_CB) (UCHAR *);

where:

name

The name of the variable to be created or modified.

n_dim

The number of dimensions in the array.

dim

An array of IDL_MAX_ARRAY_DIM elements, containing the size of each dimension.

type

The IDL type code describing the data. See “Type Codes".

data

A pointer to your array data. Your data will not be modified unless the user explicitly modifies elements of the array using subscripts.

The temporary variable returned by IDL_ImportArray() can be used immediately in an expression, in which case the descriptors are freed immediately. It can also be assigned to a longer-lived variable using IDL_VarCopy().

Note: IDL frees only the memory that it allocates for the descriptors, not the memory that you supply containing your data. You can arrange to be notified when IDL is finished with your data by using the free_cb argument, described below.

free_cb

If non-NULL, free_cb is a pointer to a function that will be called when IDL frees the array. This feature gives the caller a sure way to know when IDL is no longer referencing data. Use the called function to perform any required cleanup such as freeing dynamic memory or releasing shared or mapped memory. The called function should have no return value and should accept as its argument a (uchar *), which is a pointer to the memory to be freed.

s

If the type of the variable is IDL_TYP_STRUCT, s points to the opaque structure definition, as returned by IDL_MakeStruct().