IARRAY_GET_FROM_MULTI_ARRAY(3)

FUNCTION
iarray_get_from_multi_array - Create an Intelligent Array from a Karma data structure.

SYNOPSIS
#include <karma_iarray.h>

iarray iarray_get_from_multi_array

(multi_array *multi_desc, CONST char *arrayname, unsigned int num_dim, CONST char **dim_names, CONST char *elem_name)

DESCRIPTION
This routine will yield an "Intelligent Array" from a multi array Karma general data structure. The routine searches for a n-dimensional array with a single atomic element at each point in multi-dimensional space

multi_desc
    The multi array header pointer. The attachment count is incremented on successful completion of this routine.

arrayname
    The name of the general data structure in the arrayfile to search for. If this is NULL, the routine searches for the default name "Intelligent Array", and if that is not found, the first general data structure is used. If the arrayfile has only one general data structure, then this parameter is ignored.

num_dim
    If greater than 0, the routine will only return an array with this many dimensions. If 0, then the routine will return an n-dimensional array.

dim_names
    If <<num_dim>> is not 0, then if this NULL, the routine will search for and return an array with the default dimension names (see <<iarray_create>> for a list of these) if more than one n-dimensional, single element array exists in the general data structure, or the only n-dimensional array with the specified number of dimensions. If the routine can't find an adequate default, it will not return an array. If <<num_dim>> is not 0, and this points to an array of strings, then the routine will only return an array which matches the specified dimension names. The first name in the array of strings must be the highest order dimension.

elem_name
    If NULL, the routine will ignore the element name of the array which is located, else it will insist on the array element name matching this name.

RETURN VALUE
A dynamically allocated intelligent array on success, else an error message is printed to the standard output and NULL is returned.

Multi-threading Level
Unsafe.

AUTHOR
Richard Gooch (rgooch@atnf.csiro.au)

AVAILABLITY
The Karma Distribution is available for anonymous ftp from: ftp://ftp.atnf.csiro.au/pub/software/karma/ ftp://wuarchive.wustl.edu/graphics/graphics/packages/karma/ ftp://ftp.pwr.wroc.pl/pub/karma/ The Karma Home Page is: http://www.atnf.csiro.au/karma/