The "ds" Package

These routines provide the base functionality for the recursive, heirarchical data structure supported in Karma. This package both defines the (transparent) data structure and the various allocation, deallocation and manipulation routines. Transfer of data structures to/ from disc/ connections is supplied by the dsxfr routines.

Library: karma
Link With: -lkarma

Functions

ds_alloc_multi	Allocate a multi_array descriptor.
ds_alloc_packet_desc	Allocate a packet descriptor.
ds_alloc_data	Allocate packet data recursively.
ds_alloc_packet_subdata	Allocate packet sub-data.
ds_alloc_packet	Allocate packet.
ds_alloc_array_desc	Allocate array descriptor.
ds_alloc_tiling_info	Allocate array tiling information.
ds_alloc_dim_desc	Allocate a dimension descriptor.
ds_alloc_list_head	Allocate a linked list header.
ds_alloc_list_entry	Allocate a linked list entry.
ds_alloc_array	Allocate an array.
ds_easy_alloc_array	Allocate a data structure with a simple array.
ds_easy_alloc_n_element_array	Allocate a data structure with a simple, multi element array.
ds_wrap_preallocated_n_element_array	Wrap a data structure around an array.
ds_easy_alloc_array_desc	Allocate a simple array descriptor.
ds_alloc_contiguous_list	Allocate a contiguous list of linked list entries.
ds_find_1D_extremes	Find the minimum and maximum of a 1D array.
ds_find_2D_extremes	Find the minimum and maximum of a 2D array.
ds_find_contiguous_extremes	Find the minimum and maximum of a contiguous array.
ds_find_single_histogram	Find the histogram of a 1D array.
ds_complex_to_real_1D	Convert a 1 dimensional array of complex values to real values.
ds_put_unique_named_value	Add a unique named value to a Karma general data structure.
ds_put_unique_named_string	Add a unique named string to a Karma general data structure.
ds_get_unique_named_value	Get a unique named value from a Karma general data structure.
ds_get_unique_named_string	Get a unique named string from a Karma general data structure.
ds_cmap_alloc_colourmap	Allocate a Karma data structure to hold a colourmap.
ds_cmap_find_colourmap	Search a Karma data structure for an instance of a colourmap.
ds_cmap_get_all_colourmaps	Search an array of Karma data structures for colourmaps.
ds_copy_packet	Copy a packet.
ds_copy_desc_until	Recursively copy a packet descriptor.
ds_copy_array_desc_until	Recursively copy an array descriptor.
ds_copy_dim_desc	Copy a dimension descriptor.
ds_copy_data	Copy data between Karma data structures.
ds_copy_array	Recursively copy array data.
ds_copy_list	Recursively copy linked lists.
ds_select_arrays	Select data structures in a multi_array descriptor.
ds_dealloc_multi	Deallocate a multi_array data structure.
ds_dealloc_packet	Recursively deallocate a packet.
ds_dealloc_data	Recursively deallocate packet data.
ds_dealloc_packet_subdata	Recursively deallocate packet data.
ds_dealloc_array_desc	Recursively deallocate an array.
ds_dealloc_list	Recursively deallocate a linked list.
ds_dealloc_list_entries	Recursively deallocate list entries.
ds_dealloc2_list	Deallocate linked list entries.
ds_dealloc_array	Recursively deallocate array.
ds_draw_ellipse	Draw an ellipse into a 2 dimensional Karma array.
ds_draw_polygon	Draw a polygon into a 2 dimensional array.
ds_convert_atomic	Convert an atomic datum to a double precision value.
ds_get_coordinate	Get a co-ordinate along a dimension.
ds_get_element_offset	Calculate the offset of the start of a data element in a packet.
ds_get_packet_size	Calculate size in bytes of a packet.
ds_get_array_size	Calculate the number of co-ordinate points in an array.
ds_packet_all_data	Test if packet contains only atomic data elements.
ds_element_is_atomic	Test if an element is atomic.
ds_element_is_named	Test if an element is a named data type.
ds_element_is_legal	Test if an element is legal.
ds_identify_name	Search a data structure for a name.
ds_f_array_name	Search a the top level of a data structure for a name.
ds_f_name_in_packet	Recursively search for named item under a packet.
ds_f_name_in_array	Recursively search for named item under an array.
ds_f_elem_in_packet	Search for a named element in a packet, without recursion.
ds_find_hole	Recursively search packet for a hole.
ds_compare_packet_desc	Recursively compare two packet descriptors.
ds_compare_array_desc	Recursively compare two array descriptors.
ds_compare_dim_desc	Compare two dimension descriptors.
ds_f_dim_in_array	Find dimension in array.
ds_get_array_offset	Compute offset of a co-ordinate in an array.
ds_get_coord_num	Get index of a co-ordinate along a dimension.
ds_get_element	Convert an atomic datum to a double precision complex value.
ds_get_elements	Convert atomic data values to double precision complex values.
ds_get_coordinate_array	Get co-ordinate array for a dimension.
ds_element_is_complex	Test if the type of an element is complex or not.
ds_get_scattered_elements	Convert scattered atomic data to double precision complex values.
ds_can_transfer_element_as_block	Test if an element can be transferred in one block.
ds_can_transfer_packet_as_block	Test if a packet can be transferred in one block.
ds_can_swaptransfer_element	Test if an element can be swapped and transferred in one block.
ds_get_handle_in_packet	Find sub-structure in a general data structure.
ds_get_handle_in_array	Find sub-structure in a multi-dimensional array.
ds_get_handle_in_list	Find sub-structure in a linked list.
ds_list_insert	Insert an entry into the fragmented section of a linked list.
ds_list_append	Append an entry to a linked list.
ds_list_delete	Delete an entry from the fragmented section of a linked list.
ds_list_unfragment	Unfragment a linked list.
ds_list_fragment	Fragment a linked list.
ds_remove_dim_desc	Remove dimension from an array.
ds_append_dim_desc	Append a dimension to an array.
ds_prepend_dim_desc	Prepend a dimension to an array.
ds_compute_array_offsets	Compute array address offsets for each dimension in an array.
ds_remove_tiling_info	Remove any tiling information from an array descriptor.
ds_append_gen_struct	Append a general data structure to a multi_array structure.
ds_put_element	Write out an element of data.
ds_put_elements	Convert array of double precision complex data to atomic data.
ds_put_element_many_times	Write a double precision complex value to atomic data many times.
ds_put_named_element	Update a named element in a specified packet.
ds_reorder_array	Re-order a multi-dimensional array.
ds_foreach_occurrence	Recursively traverse a data structure, searching for an item.
ds_foreach_in_array	Recursively traverse an array, searching for an item.
ds_foreach_in_list	Recursively traverse a linked list, searching for an item.
ds_traverse_and_process	Recursively traverse a pair of data structures.
ds_traverse_array	Recursively traverse a pair of arrays.
ds_traverse_list	Recursively traverse a pair of linked lists.

Prototype Functions

DS_PROTO_foreach_func	Process an occurrence of an item in a data structure.
DS_PROTO_traverse_function	Process an occurrence of a divergence between two data structures

Tables

DS_COMPLEX_CONVERSIONS	List of complex conversion types
DS_KARMA_DATA_TYPES	List of Karma data types
DS_IDENT_TABLE	List of identification codes
DS_SEARCH_BIASES	List of co-ordinate search biases
DS_HANDLE_TYPES	List of handle types
DS_PARENT_TYPES	List of parent descriptor types

Functions

multi_array * ds_alloc_multi (unsigned int num_arrays)

This routine will allocate a multi_array descriptor. The memory for the array of pointers to the array names, headers and data arrays is also allocated.

Parameters:

num_arrays : The number of independent general data structures arrays.

Returns: A pointer to the header on success, else NULL.
Multithreading Level: Unsafe

packet_desc * ds_alloc_packet_desc (unsigned int num_elem)

This routine will allocate a packet descriptor. The memory for the array of element types and descriptors is also allocated.

Parameters:

num_elem : The number of elements to allocate.

Returns: A pointer to the descriptor on success, else NULL.
Multithreading Level: Unsafe

char * ds_alloc_data (packet_desc *pack_desc, flag clear, flag array_alloc)

This routine will allocate all memory required to store data in a packet. The routine will recursively allocate space for packets, sub arrays of packets and linked list headers. The routine is quite robust, cleanly bypassing missing sections of the descriptor hierarchy, and deallocating any memory allocated after an error occurs.

Parameters:

pack_desc : The packet descriptor.
clear : If TRUE, then the routine will initialise (set to zero) all the data.
array_alloc : If FALSE, and an array is an atomic array, then instances of that array will NOT be allocated, and a NULL pointer will be written into the parent element, else the array will be allocated.

Returns: A pointer to the data memory if all memory could be allocated, else NULL.
Multithreading Level: Unsafe

flag ds_alloc_packet_subdata (CONST packet_desc *pack_desc, char *packet, flag clear, flag array_alloc)

This routine will recursively allocate space for sub arrays of packets and linked list headers for a packet. The data space for the packet is NOT allocated, it must be supplied. The routine is quite robust, cleanly bypassing missing sections of the descriptor hierarchy, and deallocating any memory allocated after an error occurs.

Parameters:

pack_desc : The packet descriptor.
packet : The packet data.
clear : If TRUE, then the routine will initialise (set to zero) all the sub-structure data.
array_alloc : If FALSE, and an array is an atomic array, then instances of that array will NOT be allocated, and a NULL pointer will be written into the parent element, else the array will be allocated.

Returns: TRUE if all memory could be allocated, else FALSE.
Multithreading Level: Unsafe

char * ds_alloc_packet (packet_desc *pack_desc)

This routine will allocate memory for a packet. This routine is NOT recursive (i.e. sub arrays and linked lists are not allocated). The elements of the packet will be set to zero (for all types).

Parameters:

pack_desc : The packet descriptor.

Returns: A pointer to the packet on success, else NULL.
Multithreading Level: Unsafe

array_desc * ds_alloc_array_desc (unsigned int num_dimensions, unsigned int num_levels)

This function will allocate a header for a multi-dimensional tiled array of data packets.

Parameters:

num_dimensions : The number of dimensions in the array.
num_levels : The number of levels of tiling. If this is 0, the array is not tiled.

Returns: A pointer to the descriptor on success, else NULL.
Multithreading Level: Unsafe
Note:

Note that the dimension descriptors are not allocated, however, the array of pointers for them is allocated.

flag ds_alloc_tiling_info (array_desc *arr_desc, unsigned int num_levels)

This routine will allocate tiling information for an array descriptor which does not have any existing tiling information.

Parameters:

arr_desc : The array descriptor.
num_levels : The number of levels of tiling. If this is 0, the array is not tiled.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

dim_desc * ds_alloc_dim_desc (CONST char *dim_name, uaddr length, double first, double last, flag regular)

Allocate a dimension descriptor.

Parameters:

dim_name : The name of the dimension. The name is copied, thus the input character string may be subsequently deallocated.
length : The length (number of co-ordinates) of the dimension.
first : The first dimension co-ordinate.
last : The last dimension co-ordinate.
regular : If TRUE the co-ordinates of the dimension are regularly spaced, else the co-ordinates are not regularly spaced. If the co-ordinates are regularly spaced the coordinates field of the array descriptor will be set to NULL, else it will point to an array of doubles of length length These co-ordinates will be set to 0.0.

Returns: A pointer to the descriptor on success, else NULL.
Multithreading Level: Unsafe

list_header * ds_alloc_list_head ()

This routine will allocate a linked list header. The length of the linked list specified in the header will be 0, and the contiguous_until entry will be set to 0. The sort_type field in the header will be set to SORT_UNDEF. This MUST be set to some other value (i.e. SORT_RANDOM) prior to use with other library routines. The list_start and list_end pointers will be set to NULL.

Parameters:

Returns: A pointer to the header on success, else NULL.
Multithreading Level: Unsafe

list_entry * ds_alloc_list_entry (packet_desc *list_desc, flag array_alloc)

This routine will allocate an entry in a linked list (it will NOT insert it in the list: see ds_list_insert). The list pointers will be set to NULL. The routine will initialise (set to zero) the data in the entry. The routine will recursively allocate memory for sub arrays and linked lists.

Parameters:

list_desc : The descriptor for the linked list.
array_alloc : If FALSE, and an array is an atomic array, then instances of that array will NOT be allocated, and a NULL pointer will be written into the parent element, else the array will be allocated.

Returns: A pointer to the entry on success, else NULL.
Multithreading Level: Unsafe

flag ds_alloc_array (CONST array_desc *arr_desc, char *element, flag clear, flag array_alloc)

This routine will allocate memory for an array. The routine will recursively allocate sub arrays and linked lists. Any memory which is allocated will be deallocated if an error occurs.

Parameters:

arr_desc : The array descriptor.
element : The element to write the array pointer.
clear : If TRUE, then the routine will initialise (set to zero) all the data.
array_alloc : If FALSE, and an array is an atomic array, then instances of that array will NOT be allocated, and a NULL pointer will be written into the parent element, else the array will be allocated.

Returns: A pointer to the array on success, else NULL.
Multithreading Level: Unsafe

char * ds_easy_alloc_array (multi_array **multi_desc, unsigned int num_dim, CONST uaddr *lengths, CONST double *first_arr, CONST double *last_arr, CONST char **names, unsigned int data_type, CONST char *data_name)

This routine will allocate memory for a multi-dimensional, regular array, and the required headers and the multi-array header. The array is NOT tiled nor are any address offsets computed. The data packet that may be stored in the array is a single, atomic datum.

Parameters:

multi_desc : The multi-array structure pointer to the created structure is written here.
num_dim : The number of dimensions of the array.
lengths : The array of dimension lengths.
first_arr : An array of first co-ordinate values for each dimension.
last_arr : An array of last co-ordinate values for each dimension.
names : The array of dimension names. If this is NULL, the names "Axis 0", "Axis 1", ...etc will be used. The character arrays are copied, so the arrays of characters and the array of pointers may be subsequently deallocated.
data_type : The type of the elements in the array. See DS_KARMA_DATA_TYPES for a list of legal values.
data_name : The name of the data type. If this is NULL, then the name "Data Value" will be used. The name string is copied, thus the memory used for the input string may be subsequently deallocated.

Returns: A pointer to the start of the array on success, else NULL.
Multithreading Level: Unsafe
Note:

This routine does NOT create a Karma arrayfile. This must be done with a call to dsxfr_put_multi.
If either of first_arr or last_arr is NULL, the range of the co-ordinates will be the lengths of the dimensions minus 1. If one of the pointers is NULL, the other array is used to tie one end of the range for each dimension. If both pointers are NULL,the minima are 0.0 and the maxima are the lengths minus 1.

char * ds_easy_alloc_n_element_array (multi_array **multi_desc, unsigned int num_dim, CONST uaddr *lengths, CONST double *first_arr, CONST double *last_arr, CONST char **names, unsigned int num_elements, CONST unsigned int *data_types, CONST char **data_names)

Parameters:

multi_desc : The multi-array structure pointer to the created structure is written here.
num_dim : The number of dimensions of the array.
lengths : The array of dimension lengths.
first_arr : An array of first co-ordinate values for each dimension.
last_arr : An array of last co-ordinate values for each dimension.
names : The array of dimension names. If this is NULL, the names "Axis 0", "Axis 1", ...etc will be used. The character arrays are copied, so the arrays of characters and the array of pointers may be subsequently deallocated.
num_elements : The number of elements in the array packets.
data_types : The types of the elements in the array. See DS_KARMA_DATA_TYPES for a list of legal values.
data_names : The names of the data type. The name strings are copied, thus the memory used for the input string may be subsequently deallocated.

Returns: A pointer to the start of the array on success, else NULL.
Multithreading Level: Unsafe
Note:

This routine does NOT create a Karma arrayfile. This must be done with a call to dsxfr_put_multi.
If either of first_arr or last_arr is NULL, the range of the co-ordinates will be the lengths of the dimensions minus 1. If one of the pointers is NULL, the other array is used to tie one end of the range for each dimension. If both pointers are NULL,the minima are 0.0 and the maxima are the lengths minus 1.

multi_array * ds_wrap_preallocated_n_element_array (char *array, unsigned int num_dim, CONST uaddr *lengths, CONST double *first_arr, CONST double *last_arr, CONST double **coordinates, CONST char **names, unsigned int num_elements, CONST unsigned int *data_types, CONST char **data_names)

This routine will "wrap" an externally allocated array by allocating the required descriptors. The array is NOT tiled nor are any address offsets computed. The data packet that may be stored in the array contains many atomic data.

Parameters:

array : The externally allocated array. This data must be externally deallocated when no longer needed. If this is NULL, then the array data is internally allocated (and should not be externally deallocated).
num_dim : The number of dimensions of the array.
lengths : The array of dimension lengths.
first_arr : An array of first co-ordinate values for each dimension.
last_arr : An array of last co-ordinate values for each dimension.
coordinates : The array of co-ordinate array pointers. If this is NULL, all dimensions are assumed to be regularly spaced. If any co-ordinate array pointer is NULL, the corresponding dimension is assumed to be regularly spaced.
names : The array of dimension names. If this is NULL, the names "Axis 0", "Axis 1", ...etc will be used. The character arrays are copied, so the arrays of characters and the array of pointers may be subsequently deallocated.
num_elements : The number of elements in the array packets.
data_types : The types of the elements in the array. See DS_KARMA_DATA_TYPES for a list of legal values.
data_names : The names of the data type. The name strings are copied, thus the memory used for the input string may be subsequently deallocated.

Returns: A pointer the multi_array descriptor on success, else NULL.
Multithreading Level: Unsafe
Note:

This routine does NOT create a Karma arrayfile. This must be done with a call to dsxfr_put_multi.
If either of first_arr or last_arr is NULL, the range of the co-ordinates will be the lengths of the dimensions minus 1. If one of the pointers is NULL, the other array is used to tie one end of the range for each dimension. If both pointers are NULL,the minima are 0.0 and the maxima are the lengths minus 1.

array_desc * ds_easy_alloc_array_desc (unsigned int num_dim, CONST uaddr *lengths, CONST double *first_arr, CONST double *last_arr, CONST double **coordinates, CONST char **names, unsigned int num_elements, CONST unsigned int *data_types, CONST char **data_names)

This routine will allocate an array descriptor and its associated packet descriptor.

Parameters:

num_dim : The number of dimensions in the array.
lengths : An array of lengths for each dimension (axis).
first_arr : An array of first co-ordinate values for each dimension.
last_arr : An array of last co-ordinate values for each dimension. If either of these pointers is NULL, the range of the co-ordinates will be the lengths of the dimensions minus 1. If one of the pointers is NULL, the other array is used to tie one end of the range for each dimension. If both pointers are NULL,the minima are 0.0 and the maxima are the lengths minus 1
coordinates : The array of co-ordinate array pointers. If this is NULL, all dimensions are assumed to be regularly spaced. If any co-ordinate array pointer is NULL, the corresponding dimension is assumed to be regularly spaced.
names : An array of string pointers to the names of each dimension. If this is NULL, the names "Axis 0", "Axis 1", ...etc will be used. Note: the character arrays are copied, so the arrays of characters and the array of pointers may be subsequently deallocated.
num_elements : The number of atomic elements in the array packet.
data_types : The types of the elements in the array. See DS_KARMA_DATA_TYPES for a list of legal values.
data_names : The array of element names. The name strings are copied, thus the memory used for the input strings may be subsequently deallocated.

Returns: An array descriptor pointer on success, else NULL.
Multithreading Level: Unsafe

flag ds_alloc_contiguous_list (CONST packet_desc *list_desc, list_header *list_head, unsigned int length, flag clear, flag array_alloc)

This routine will allocate a contiguous block of linked list entry data packets. No list_entry structures are allocated, they are implied. The routine will recursively allocate memory for sub arrays and linked lists. The list must be empty. The contiguous_length value in the list header will be set to the list length.

Parameters:

list_desc : The packet descriptor for the linked list.
list_head : The list header.
length : The number of list entries to allocate.
clear : If TRUE, then the routine will initialise (set to zero) all the data.
array_alloc : If FALSE, and an array is an atomic array, then instances of that array will NOT be allocated, and a NULL pointer will be written into the parent element, else the array will be allocated.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

On failure, the list header is deallocated.

flag ds_find_1D_extremes (CONST char *data, unsigned int num_values, uaddr *offsets, unsigned int elem_type, unsigned int conv_type, double *min, double *max)

This routine will find the extremes (minimum and maximum) of a single trace (element versus a dimension).

Parameters:

data : A pointer to the data. Misaligned data will cause bus errors on some platforms.
num_values : The number of values to process.
offsets : The address offsets for data along the dimension.
elem_type : The type of the element.
conv_type : The type of conversion to use for complex numbers.
min : The minimum value will be written here.
max : The maximum value will be written here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Safe.
Note:

The minimum and maximum value must be initialised to a very large positive number and a very large negative number, respectively, outside of the routine. In other words, the routine does not initialise these values prior to testing for the minimum and maximum.

flag ds_find_2D_extremes (CONST char *data, unsigned int length1, uaddr *offsets1, unsigned int length2, uaddr *offsets2, unsigned int elem_type, unsigned int conv_type, double *min, double *max)

This routine will find the extremes (minimum and maximum) of a single plane (element versus two dimensions).

Parameters:

data : A pointer to the data.
length1 : The number of values to process along one of the dimensions. For efficiency this should be the more significant dimension.
offsets1 : The address offsets for data along the corresponding dimension.
length2 : The number of values to process along the other of the dimensions
offsets2 : The address offsets for data along the corresponding dimension.
elem_type : The type of the element.
conv_type : The type of conversion to use for complex numbers.
min : The minimum value will be written here.
max : The maximum value will be written here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Safe.
Note:

The minimum and maximum value must be initialised to a very large positive number and a very large negative number, respectively, outside of the routine. In other words, the routine does not initialise these values prior to testing for the minimum and maximum.

flag ds_find_contiguous_extremes (CONST char *data, unsigned int num_values, uaddr stride, unsigned int elem_type, unsigned int conv_type, double *min, double *max)

This routine will find the extremes (minimum and maximum) of a single trace (element versus a dimension).

Parameters:

data : A pointer to the data. Misaligned data will cause bus errors on some platforms.
num_values : The number of values to process.
stride : The stride (in bytes) between consecutive data values.
elem_type : The type of the element.
conv_type : The type of conversion to use for complex numbers.
min : The minimum value will be written here.
max : The maximum value will be written here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Safe.
Note:

The minimum and maximum value must be initialised to a very large positive number and a very large negative number, respectively, outside of the routine. In other words, the routine does not initialise these values prior to testing for the minimum and maximum.

flag ds_find_single_histogram (CONST char *data, unsigned int elem_type, unsigned int conv_type, unsigned int num_values, CONST uaddr *offsets, unsigned int stride, double min, double max, unsigned long num_bins, unsigned long *histogram_array, unsigned long *histogram_peak, unsigned long *histogram_mode)

This routine will find the histogram of a single trace (element versus a dimension). This routine may be called repeatedly with multiple traces in order to build an aggregate histogram of all traces.

Parameters:

data : A pointer to the data. Misaligned data will cause bus errors on some platforms.
elem_type : The type of the element.
conv_type : The type of conversion to use for complex numbers. Legal value for this include: CONV_CtoR_REAL CONV_CtoR_IMAG CONV_CtoR_ABS CONV_CtoR_SQUARE_ABS CONV_CtoR_PHASE CONV_CtoR_CONT_PHASE
num_values : The length of the dimension.
offsets : The address offsets for data along the dimension.
stride : If the value of offsets is NULL, this gives the stride (in bytes) between consecutive values along the dimension.
min : Data values below this will be ignored.
max : Data values above this will be ignored.
num_bins : The number of histogram bins.
histogram_array : The histogram array. The values in this array are updated and hence must be initialised externally.
histogram_peak : The peak of the histogram is written here. This value is updated, and hence must be externally initialised to 0.
histogram_mode : The mode of the histogram (index value of the peak) will be written here. This value is updated, and hence must be externally initialised to 0.

Returns: TRUE on success, else FALSE.
Multithreading Level: Safe.

void ds_complex_to_real_1D (double *out, unsigned int out_stride, double *inp, unsigned int num_values, unsigned int conv_type)

Convert a 1 dimensional array of complex values to real values.

Parameters:

out : A pointer to the output array.
out_stride : The stride (in doubles) of the output array.
inp : The array of input complex values.
num_values : The number of values to convert.
conv_type : The conversion type to apply.

Returns: Nothing.
Multithreading Level: Safe.

flag ds_put_unique_named_value (packet_desc *pack_desc, char **packet, CONST char *name, unsigned int type, double value[2], flag update)

Add a unique named value to a Karma general data structure.

Parameters:

pack_desc : The packet descriptor to add the name to. This descriptor will be modified.
packet : The pointer to the unique packet. Note that the existing packet data is copied to a new packet, and a pointer to this packet is written back here.
name : The name of the element.
type : The type of the data which is to be written.
value : The value of the data.
update : If TRUE, then the routine will allow an existing named value to be updated, otherwise the routine will fail if an update (rather than a create) is attempted. The type parameter is ignored for updates (i.e. you can't change the type).

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ds_put_unique_named_string (packet_desc *pack_desc, char **packet, CONST char *name, CONST char *string, flag update)

Add a unique named string to a Karma general data structure.

Parameters:

pack_desc : The packet descriptor to add the name to. This descriptor will be modified.
packet : The pointer to the unique packet. Note that the existing packet data is copied to a new packet, and a pointer to this packet is written back here.
name : The name of the element.
string : The string value.
update : If TRUE, then the routine will allow an existing named string to be updated, otherwise the routine will fail if an update (rather than a create) is attempted.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ds_get_unique_named_value (CONST packet_desc *pack_desc, CONST char *packet, CONST char *name, unsigned int *type, double value[2])

Get a unique named value from a Karma general data structure.

Parameters:

pack_desc : A pointer to the packet descriptor.
packet : A pointer to the packet containing the named value.
name : The name of the value.
type : The type of the element found will be written here. If this is NULL, nothing is written here.
value : The value of the element data will be written here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

char * ds_get_unique_named_string (CONST packet_desc *pack_desc, CONST char *packet, CONST char *name)

Get a unique named string from a Karma general data structure.

Parameters:

pack_desc : The packet descriptor.
packet : The packet containing the named string.
name : The element name.

Returns: A pointer to a dynamically allocated copy of the string on success, else NULL.
Multithreading Level: Unsafe

unsigned short * ds_cmap_alloc_colourmap (unsigned int size, multi_array **multi_desc, packet_desc **pack_desc,char **packet)

This routine will allocate a colourmap which comforms to the Karma general data structure format. Note that this does NOT allocate a colourmap on an X Windows server. This routine is intended to enable an application to write colourmap data to a file, maintaining a flexible format. The general data structure that is created will contain a 1 dimensional array with dimension name "Colour Number" and length equal to size . The array will contain packets with 3 elements, each of type K_USHORT and with the names "Red Intensity", "Green Intensity" and "Blue Intensity", in that order. For compatibility with the X Window system, it is recommended that these values lie in the range 0 to 65535.

Parameters:

size : The size (number of colours) of the colourmap to allocate.
multi_desc : The pointer to the multi array header which is allocated will be written here. If this is NULL, then no multi array header is allocated and nothing is written here.
pack_desc : The pointer to the top level packet descriptor of the general data structure which contains the colourmap will be written here. If this is NULL, nothing is written here. Note, however, that the top level packet descriptor is nevertheless allocated.
packet : The pointer to the top level packet of the general data structure which contains the colourmap will be written here. If this is NULL, nothing is written here. Note, however, that the top level packet is nevertheless allocated.

Returns: A pointer to the allocated colourmap on success, else NULL.
Multithreading Level: Unsafe

unsigned short * ds_cmap_find_colourmap (packet_desc *top_pack_desc, char *top_packet, unsigned int *size, flag *reordering_done, CONST char *restr_names[], double *restr_values, unsigned int num_restr)

Search a Karma data structure for an instance of a colourmap.

Parameters:

top_pack_desc : The top level packet descriptor.
top_packet : The top level packet data.
size : The size of the colourmap (number of colours) in the colourmap will be here.
reordering_done : The routine is tolerant of incorrect ordering of the intensity elements. If they are ordered incorrectly, the data will be re-ordered, and the value TRUE will be written here. If the data is not re-ordered, the value FALSE is written here. If this is NULL, then nothing is written here.
restr_names : The array of pointers to restrictions names.
restr_values : The array of restriction values.
num_restr : The number of restriction values.

Returns: A pointer to a colourmap on success, else NULL. The returned colourmap will contain *size contiguous packets which each contain first a red intensity, then a green and then a blue.
Multithreading Level: Unsafe
Note:

NULL pointers may be passed for restr_names and restr_values and num_restr set to zero. In this case, the routine will only return a colourmap if there is only one instance of a colourmap in the entire data structure.

unsigned int * ds_cmap_get_all_colourmaps (multi_array *multi_desc, unsigned int *num_found, flag *reordering_done, CONST char *restr_names[], double *restr_values, unsigned int num_restr)

This routine will search an array of Karma general data structures for instances of a colourmap.

Parameters:

multi_desc : The multi_array descriptor.
num_found : The number of general data structures which contain a colourmap will be written here.
reordering_done : The routine is tolerant of incorrect ordering of the intensity elements. If they are ordered incorrectly, the data will be re-ordered, and the value TRUE will be written here, else the value FALSE will be written here. If this is NULL, nothing is written here.
restr_names : The array of pointers to restrictions names.
restr_values : The array of restriction values.
num_restr : The number of restriction values.

Returns: A pointer to an array of general data structure indices on success, else NULL. This array is dynamically allocated, and should be freed when no longer needed.
Multithreading Level: Unsafe
Note:

NULL pointers may be passed for restr_names and restr_values and num_restr set to zero. In this case, the routine will only return a colourmap if there is only one instance of a colourmap in the entire data structure.

flag ds_copy_packet (packet_desc *pack_desc, char *dest_packet, char *source_packet)

Copy a packet.

Parameters:

pack_desc : The packet descriptor.
dest_packet : The destination packet data will be written here.
source_packet : The source packet data.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

The routine will copy only the data and pointers to arrays and linked lists in the packet, not the arrays and linked lists which may be pointed to.

packet_desc * ds_copy_desc_until (packet_desc *inp_desc, CONST char *name)

This routine will recursively copy a packet descriptor until an element with a specified name is found, at which time the copying process stops. The routine will trap such errors as multiple occurences of the element name. This routine is useful to duplicate a data structure above a certain element or dimension. This simplifies the processing of data which is sitting near the bottom of a complex data structure. If an array or linked list pointer is one of the elements, and it is not successfully copied, the routine will set the output element type to NONE and the descriptor pointer for that element will be NULL.

Parameters:

inp_desc : The input packet descriptor.
name : The name of the element at which the copying process should stop. If this is NULL, then the entire data structure descriptor is copied.

Returns: A pointer to the new packet descriptor on success, else NULL.
Multithreading Level: Unsafe

array_desc * ds_copy_array_desc_until (array_desc *inp_desc, CONST char *name)

This routine will make a copy of an array descriptor and all sub-descriptors until a specified name is encountered. All tiling information is copied, but address offset arrays are NOT copied.

Parameters:

inp_desc : The input array descriptor.
name : The name specifying where the copying should stop. If this is NULL, the entire data structure descriptor is copied.

Returns: A pointer to the array descriptor created on success, else NULL.
Multithreading Level: Unsafe

dim_desc * ds_copy_dim_desc (dim_desc *inp_desc)

Copy a dimension descriptor.

Parameters:

inp_desc : The input

Returns: A pointer to a freshly allocated dimension descriptor on success, else NULL.
Multithreading Level: Unsafe

flag ds_copy_data (packet_desc *inp_desc, char *inp_data, packet_desc *out_desc, char *out_data)

This routine will copy data from one data structure to another, provided the two data structures have the same format. If there are any variations in the two formats, the copying process is stopped at that level If one or more elements are different, they are not copied, however, the other elements are copied. This also applies to array and linked list pointer elements. This condition only holds for packets with the same number of elements, otherwise no elements are copied. The ordering of elements must also be the same. The names of elements and dimensions must be the same, as well as the data types. For information on array and linked list copying, see The routine recursively copies data in arrays and linked lists. ds_copy_array and ds_copy_list.

Parameters:

inp_desc : The input data structure descriptor.
inp_data : The input data.
out_desc : The output data structure descriptor.
out_data : The output data memory allocation.

Returns: TRUE if the two packet descriptors are identical, else FALSE.
Multithreading Level: Unsafe

flag ds_copy_array (array_desc *inp_desc, char *inp_data, array_desc *out_desc, char *out_data)

This routine will copy data from one array to another. The two arrays must be the same, else the copying process will stop. The routine recursively copies data in the array packets. For information on the copying rules when the two list descriptors differ, see the routine ds_copy_data.

Parameters:

inp_desc : The input array descriptor.
inp_data : The input array data.
out_desc : The output array descriptor.
out_data : The output data memory allocation.

Returns: TRUE if the two array descriptors are identical, else FALSE.
Multithreading Level: Unsafe

flag ds_copy_list (packet_desc *inp_desc, list_header *inp_head, packet_desc *out_desc, list_header *out_head)

This routine will copy a linked list to another. The routine will recursively copy sub arrays and linked lists. The linked list entries and data fields will be allocated. The entries will be contiguous in memory. For information on the copying rules when the two list descriptors differ, see the routine ds_copy_data.

Parameters:

inp_desc : The input data structure descriptor.
inp_head : The input linked list header.
out_desc : The output data structure descriptor.
out_head : The output linked list header.

Returns: TRUE if the two packet descriptors are identical, else FALSE.
Multithreading Level: Unsafe

multi_array * ds_select_arrays (char **array_list, unsigned int num_in_list, multi_array *multi_desc, flag save_unproc, unsigned int **index_list)

This routine will create a multi array descriptor which contains a selected number of array names.

Parameters:

array_list : The array of array names that are to be copied.
num_in_list : The number of array names in array_list. If this is 0, all array names are copied.
multi_desc : The input data structure.
save_unproc : If TRUE, all array names are copied.
index_list : An array of unsigned ints will be allocated by the routine and the pointer written here. The length of this array is equal to the number of arrays in the input multi_array descriptor. This array contains the index of the array name in the input multi array descriptor for each array name in the output multi_array descriptor. If there is no name match for an array, the index value is equal to the number of arrays in the input multi_array descriptor.

Returns: A pointer to the created multi array descriptor on success, else NULL.
Multithreading Level: Unsafe

void ds_dealloc_multi (multi_array *multi_desc)

This routine will deallocate all memory associated with a multi_array header. This includes all the descriptors and data arrays and lists in the hierarchy below. The routine will only deallocate the data structure when it's attachment count is zero, else it decrements the attachment count and returns. The routine is quite robust, deallocating in the correct order and cleanly bypassing missing sections in the hierarchy.

Parameters:

multi_desc : The descriptor.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_dealloc_packet (packet_desc *pack_desc, char *data)

This routine will deallocate all memory associated with a data packet. This includes all the descriptors and data arrays and lists associated with the packet. The routine is quite robust, deallocating in the correct order and cleanly bypassing missing sections in the hierarchy.

Parameters:

pack_desc : The descriptor for the packet.
data : The data for the packet.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_dealloc_data (packet_desc *pack_desc, char *packet)

This routine will deallocate all memory associated with the storage of data in a packet. Any sub-arrays or linked lists are recursively deallocated. The routine is quite robust, deallocating in the correct order and cleanly bypassing missing sections in the hierarchy.

Parameters:

pack_desc : The descriptor for the packet.
data : The data for the packet.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_dealloc_packet_subdata (CONST packet_desc *pack_desc, char *packet)

This routine will recursively deallocate all memory associated with the storage of sub-arrays or linked lists. The packet itself is not deallocated. The routine is quite robust, deallocating in the correct order and cleanly bypassing missing sections in the hierarchy.

Parameters:

pack_desc : The descriptor for the packet.
data : The data for the packet.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_dealloc_array_desc (array_desc *arr_desc)

This routine will deallocate all descriptor information associated with a tiled array. This includes all descriptors for sub-arrays and linked lists. The routine is quite robust, deallocating in the correct order and cleanly bypassing missing sections in the hierarchy.

Parameters:

arr_desc : The array descriptor.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_dealloc_list (packet_desc *list_desc, list_header *list_head)

This routine will deallocate all memory associated with the storage of data in a linked list. Any sub-arrays or linked lists are recursively deallocated. The routine is quite robust, deallocating in the correct order and cleanly bypassing missing sections in the hierarchy. The list header is also deallocated.

Parameters:

list_desc : The descriptor for the list.
list_head : The linked list header.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_dealloc_list_entries (CONST packet_desc *list_desc, list_header *list_head)

Parameters:

list_desc : The descriptor for the list.
list_head : The linked list header.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_dealloc2_list (list_header *list_head)

This routine will deallocate the data and the list entries in a linked list. This routine does not recursively deallocate sub-arrays or linked lists: it will only remove the list. The list header is NOT deallocated.

Parameters:

list_head : The list header.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_dealloc_array (array_desc *arr_desc, char *arr_element)

This routine will deallocate all memory associated with the storage of data for an array. Any sub-arrays or linked lists are recursively deallocated. The routine is quite robust, deallocating in the correct order and cleanly bypassing missing sections in the hierarchy.

Parameters:

arr_desc : The array descriptor.
arr_element : The element containing the array pointer.

Returns: Nothing.
Multithreading Level: Unsafe

flag ds_draw_ellipse (char *array, unsigned int elem_type, dim_desc *abs_dim_desc, unsigned int abs_stride, dim_desc *ord_dim_desc, unsigned int ord_stride, double centre_abs, double centre_ord, double radius_abs, double radius_ord, double value[2])

Draw an ellipse into a 2 dimensional Karma array.

Parameters:

array : The start of the array (plane) data.
elem_type : The type of the element to draw.
abs_dim_desc : The abscissa dimension descriptor.
abs_stride : The stride of abscissa co-ordinates in memory (in bytes).
ord_dim_desc : The ordinate dimension descriptor.
ord_stride : The stride of ordinate co-ordinates in memory (in bytes).
centre_abs : The centre of the ellipse in abscissa real-world co-ordinates.
centre_ord : The centre of the ellipse in ordinate real-world co-ordinates.
radius_abs : The abscissa radius. This must be greater than 0.0.
radius_ord : The ordinate radius. This must be greater than 0.0.
value : The value to write the ellipse into the array.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ds_draw_polygon (char *array, unsigned int elem_type, dim_desc *abs_dim_desc, unsigned int abs_stride, dim_desc *ord_dim_desc, unsigned int ord_stride, edit_coord *coords, unsigned int num_points, double value[2])

This routine will draw a concave non-simple polygon into a 2 dimensional Karma array. The polygon can be clockwise or anti-clockwise. Inside-outside test done by Jordan's rule: a point is considered inside if an emanating ray intersects the polygon an odd number of times. The algorithm is modified from the Concave Polygon Scan Conversion by Paul Heckbert from "Graphics Gems", Academic Press, 1990.

Parameters:

array : The start of the array (plane) data.
elem_type : The type of the element to draw.
abs_dim_desc : The abscissa dimension descriptor.
abs_stride : The stride of abscissa co-ordinates in memory (in bytes).
ord_dim_desc : The ordinate dimension descriptor.
ord_stride : The stride of ordinate co-ordinates in memory (in bytes).
coords : The co-ordinate array for the vertices. The co-ordinates must be stored in clockwise rotation order (any point to start).
num_points : The number of vertices.
value : The value to write the polygon into the array.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

double ds_convert_atomic (CONST char *datum, unsigned int datum_type, double *real_out, double *imag_out)

Convert an atomic datum to a double precision value.

Parameters:

datum : The datum to be converted.
datum_type : The type of the datum. See DS_KARMA_DATA_TYPES for a list of legal values. The following data types are not convertible, and the routine will return the value TOOBIG: NONE, K_ARRAY, LISTP, MULTI_ARRAY.
real_out : The real component of the data is written here. If this is NULL, nothing is written here. This must lie on a double boundary.
imag_out : The imaginary component of the data is written here. If this is NULL, nothing is written here. This must lie on a double boundary. For a real value, 0.0 is written.

Returns: The absolute magnitude of the converted value on success, else TOOBIG.
Multithreading Level: Unsafe

double ds_get_coordinate (dim_desc *dimension, unsigned long coord_num)

Get a co-ordinate along a dimension.

Parameters:

dimension : The dimension descriptor.
coord_num : The co-ordinate index.

Returns: The co-ordinate on success, else TOOBIG.
Multithreading Level: Unsafe

unsigned int ds_get_element_offset (CONST packet_desc *pack_desc, unsigned int elem_num)

Calculate the offset of the start of a data element in a packet.

Parameters:

pack_desc : The descriptor for the data packet.
elem_num : The number of the element.

Returns: The byte offset of the element in the packet on success, else the length of the packet is returned.
Multithreading Level: Unsafe

unsigned int ds_get_packet_size (CONST packet_desc *pack_desc)

Calculate size in bytes of a packet.

Parameters:

pack_desc : The packet descriptor.

Returns: The size in bytes.
Multithreading Level: Unsafe

unsigned long ds_get_array_size (CONST array_desc *arr_desc)

Calculate the number of co-ordinate points in an array.

Parameters:

arr_desc : The array descriptor.

Returns: The size of the array (in co-ordinate points).
Multithreading Level: Unsafe

flag ds_packet_all_data (CONST packet_desc *pack_desc)

This routine will determine if all the elements in a packet are atomic (i.e. no sub-arrays, linked lists or strings). All element types in the packet descriptor must be legal, else the routine will print an error message and abort processing.

Parameters:

pack_desc : The packet descriptor.

Returns: TRUE if the data elements are all atomic, else FALSE.
Multithreading Level: Unsafe

flag ds_element_is_atomic (unsigned int element_type)

This routine will determine if an element is atomic (i.e. not a sub-array, linked list or string). The element type must be legal, else the routine will print an error message and abort processing.

Parameters:

element_type : The type of the element.

Returns: TRUE if the element is atomic, else FALSE.
Multithreading Level: Unsafe

flag ds_element_is_named (unsigned int element_type)

This routine will determine if an element is a named data type (i.e. not a sub-array or linked list). The element type must be legal, else the routine will print an error message and abort processing.

Parameters:

element_type : The type of the element.

Returns: TRUE if the element is a named type, else FALSE.
Multithreading Level: Unsafe

flag ds_element_is_legal (unsigned int element_type)

Test if an element is legal.

Parameters:

element_type : The type of the element.

Returns: TRUE if the element type is legal, else FALSE.
Multithreading Level: Unsafe

unsigned int ds_identify_name (multi_array *multi_desc, CONST char *name, char **encls_desc, unsigned int *index)

Search a data structure for a name.

Parameters:

multi_desc : The multi_array descriptor.
name : The name of the item to search for.
encls_desc : A pointer to the enclosing descriptor of the item is written here. If this is NULL, nothing is written here.
index : The index (general data structure number, dimension number or element number) of the item in the enclosing structure will be written here. If this is NULL, nothing is written here.

Returns: A code based on the type of the item with the same name. See DS_IDENT_TABLE for a list of possible values.
Multithreading Level: Unsafe

unsigned int ds_f_array_name (multi_array *multi_desc, CONST char *name, char **encls_desc, unsigned int *index)

This routine will search a multi array general data structure header for an occurrence of an array name.

Parameters:

multi_desc : The multi_array data structure.
name : The array name.
encls_desc : If the array name is found, the pointer to the multi array header will be written here. If this is NULL, nothing is written here.
index : The index number of the general data structure with will be written here. If this is NULL, nothing is written here.

Returns: A code based on the number of matches found. See DS_IDENT_TABLE for a list of possible values.
Multithreading Level: Unsafe
Note:

The routine will not search the packet descriptors for name matches.

unsigned int ds_f_name_in_packet (CONST packet_desc *pack_desc, CONST char *name, char **encls_desc, unsigned int *index)

Recursively search for named item under a packet.

Parameters:

pack_desc : The packet descriptor.
name : The name of the item to search form. If NULL, then the routine will not find anything.
encls_desc : The pointer to the enclosing structure of the named item will be written here. If this is NULL, nothing is written here.
index : The index (dimension number or element number) of the item will be written here. If this is NULL, nothing is written here.

Returns: A code based on the type of the item with the same name. See DS_IDENT_TABLE for a list of possible values.
Multithreading Level: Unsafe

unsigned int ds_f_name_in_array (array_desc *arr_desc, CONST char *name, char **encls_desc, unsigned int *index)

This routine will search an array descriptor for occurrences of a named item. The routine searches both the dimension names and the packet associated with the array. The routine recursively searches the array packet descriptor.

Parameters:

arr_desc : The array descriptor.
name : The name of the item to search form. If NULL, then the routine will not find anything.
encls_desc : The pointer to the enclosing structure of the named item will be written here. If this is NULL, nothing is written here.
index : The index (dimension number or element number) of the item will be written here. If this is NULL, nothing is written here.

Returns: A code based on the type of the item with the same name. See DS_IDENT_TABLE for a list of possible values.
Multithreading Level: Unsafe

unsigned int ds_f_elem_in_packet (CONST packet_desc *pack_desc, CONST char *name)

Search for a named element in a packet, without recursion.

Parameters:

pack_desc : The packet descriptor.
name : The element name to search for. If this is NULL, then the routine will not find anything.

Returns: The number of the element in the packet if it was found, else the number of elements in the packet.
Multithreading Level: Unsafe
Note:

If the specified name occurs twice, the program aborts.

unsigned int ds_find_hole (packet_desc *inp_desc, packet_desc **out_desc, unsigned int *elem_num)

This routine will recursively search a packet descriptor for a hole (element type NONE or element descriptor pointer NULL).

Parameters:

inp_desc : The packet descriptor to search.
out_desc : A pointer to the packet descriptor which contains the hole is written here. If this is NULL, nothing is written here.
elem_num : The element number in that packet which corresponds to the hole is written here. If this is NULL, nothing is written here.

Returns: A code indicating the status of the search. See DS_IDENT_TABLE for a list of possible values.
Multithreading Level: Unsafe

flag ds_compare_packet_desc (packet_desc *desc1, packet_desc *desc2, flag recursive)

Recursively compare two packet descriptors.

Parameters:

desc1 : One of the packet descriptors.
desc2 : The other packet descriptor.
recursive : If TRUE the routine will perform a recursive comparison of sub-arrays and linked list descriptors.

Returns: TRUE if the two packet descriptors are equal, else FALSE.
Multithreading Level: Unsafe

flag ds_compare_array_desc (array_desc *desc1, array_desc *desc2, flag recursive)

Recursively compare two array descriptors.

Parameters:

desc1 : One of the array descriptors.
desc2 : The other array descriptor.
recursive : If TRUE the routine will perform a recursive comparison of the array packet descriptors.

Returns: TRUE if the two array descriptors are equal, else FALSE.
Multithreading Level: Unsafe

flag ds_compare_dim_desc (dim_desc *desc1, dim_desc *desc2)

Compare two dimension descriptors.

Parameters:

desc1 : One of the dimension descriptors.
desc2 : The other dimension descriptor.

Returns: TRUE if the two dimension descriptors are equal, else FALSE.
Multithreading Level: Unsafe

unsigned int ds_f_dim_in_array (array_desc *arr_desc, CONST char *name)

Find dimension in array.

Parameters:

arr_desc : The array descriptor.
name : The name of the dimension to find. If this is NULL, then the routine will not find anything.

Returns: The number of the dimension in the array if it was found, else the number of dimensions in the array.
Multithreading Level: Unsafe
Note:

If the specified name occurs twice, the program aborts.

unsigned long ds_get_array_offset (array_desc *arr_desc, unsigned long *coordinates)

Compute offset of a co-ordinate in an array.

Parameters:

arr_desc : The array descriptor.
coordinates : The array of dimension co-ordinates which specifies the co-ordinate.

Returns: The offset of the co-ordinate in packets.
Multithreading Level: Unsafe

unsigned long ds_get_coord_num (dim_desc *dimension, double coordinate, unsigned int bias)

Get index of a co-ordinate along a dimension.

Parameters:

dimension : The dimension descriptor.
coordinate : The co-ordinate to find.
bias : This specifies which co-ordinate index to pick when the co-ordinate lies between two dimension co-ordinates. See DS_SEARCH_BIASES for legal values.

Returns: The index number of the co-ordinate found.
Multithreading Level: Unsafe

flag ds_get_element (CONST char *datum, unsigned int datum_type, double value[2], flag *complex)

Convert an atomic datum to a double precision complex value.

Parameters:

datum : A pointer to the datum to be converted.
datum_type : The type of the datum.
value : The data value will be written here.
complex : If the datum is a complex type, then the value of TRUE is written here, else the value FALSE is written here. If this is NULL, nothing is written here.

Returns: TRUE if the data was successfully converted, else FALSE.
Multithreading Level: Unsafe

flag ds_get_elements (CONST char *data, unsigned int data_type, unsigned int data_stride, double *values, flag *complex, unsigned int num_values)

Convert atomic data values to double precision complex values.

Parameters:

data : The data to be converted.
data_type : The type of the data.
data_stride : The stride of data elements in memory (in bytes).
values : The data values will be written here. This MUST lie on a double boundary.
complex : TRUE is written here if the data are a complex type, else FALSE is written here. If this is NULL, nothing is written here.
num_values : The number of data values to convert.

Returns: TRUE if the data was successfully converted, else FALSE.
Multithreading Level: Unsafe

double * ds_get_coordinate_array (dim_desc *dimension)

This routine will get a co-ordinate array for a dimension. If the dimension is regularly spaced, then the co-ordinate array is computed, else if it is irregularly spaced, it is copied from the dimension descriptor.

Parameters:

dimension : The dimension descriptor.

Returns: A pointer to a co-ordinate array on success, else NULL.
Multithreading Level: Unsafe

flag ds_element_is_complex (unsigned int element_type)

Test if the type of an element is complex or not.

Parameters:

element_type : The element type. If this is not atomic the routine will print an error message and abort processing.

Returns: TRUE if the element type is complex, else FALSE.
Multithreading Level: Unsafe

flag ds_get_scattered_elements (CONST char *data, unsigned int data_type, CONST uaddr *offsets, double *values, flag *complex, unsigned int num_values)

This routine will convert many atomic data to an array of double precision complex values. The data values may be scattered randomly (an offset array is used to index to the actual data).

Parameters:

data : The data to be converted. Misaligned data will cause bus errors on some platforms.
data_type : The type of the data.
offsets : The offset array (in bytes).
values : The data values will be written here. Must be a double boundary.
complex : If the data are a complex type, then the value of TRUE is written here, else the value FALSE is written here. If this is NULL, nothing is written here.
num_values : The number of data values to convert.

Returns: TRUE if the data was successfully converted, else FALSE.
Multithreading Level: Safe.

flag ds_can_transfer_element_as_block (unsigned int type)

This routine will determine if an element can be transferred as a single block of data (i.e. no conversion between host and network format is needed).

Parameters:

type : The type of the element.

Returns: TRUE if the element may be transferred as a single block, else FALSE.
Multithreading Level: Unsafe

flag ds_can_transfer_packet_as_block (CONST packet_desc *pack_desc)

This routine will determine if a packet can be transferred as a single block of data (i.e. no conversion between host and network format is needed).

Parameters:

pack_desc : A pointer to the packet descriptor.

Returns: TRUE if the packet may be transferred as a single block, else FALSE.
Multithreading Level: Unsafe

flag ds_can_swaptransfer_element (unsigned int type)

This routine will determine if an element can be transferred as a single block of data with swapping (i.e. no extra conversion other than byte-swapping between host and network format is needed).

Parameters:

type : The type of the element.

Returns: TRUE if the element may be byteswapped and transferred in a single block, else FALSE.
Multithreading Level: Unsafe

unsigned int ds_get_handle_in_packet (packet_desc *pack_desc, char *packet, CONST char *item_name, CONST char *restr_names[], double *restr_values, unsigned int num_restr, char **parent_desc, char **parent, unsigned int *parent_type, unsigned int *index)

This routine will find a unique occurrence of an object (sub-structure) within a specified general data structure.

Parameters:

pack_desc : The general data structure packet descriptor.
packet : The general data structure packet.
item_name : The name of the object that the handle is desired for.
restr_names : The array of pointers to restrictions names.
restr_values : The array of restriction values.
num_restr : The number of restriction values.
parent_desc : A pointer to the item's parent descriptor is written here.
parent : A pointer to the item's parent is written here.
parent_type : The type of the parent is written here. See DS_HANDLE_TYPES for a list of possible values.
index : The index number of the item in its parent descriptor is written here.

Returns: A code based on the type of the sub-structure found. See DS_IDENT_TABLE for a list of possible values.
Multithreading Level: Unsafe
Note:

The following rules apply to items: If the item is an atomic element, the parent is a packet. If the item is a dimension, the parent is an array. If the item is an atomic element in a linked list, the parent is a list header.

unsigned int ds_get_handle_in_array (array_desc *arr_desc, char *array, CONST char *item_name, CONST char *restr_names[], double *restr_values, unsigned int num_restr, char **parent_desc, char **parent, unsigned int *parent_type, unsigned int *index)

This routine will find a unique occurrence of an object (sub-structure) within a specified multi-dimensional array.

Parameters:

arr_desc : The array descriptor.
array : The array.
item_name : The name of the object that the handle is desired for.
restr_names : The array of pointers to restrictions names.
restr_values : The array of restriction values.
num_restr : The number of restriction values.
parent_desc : A pointer to the item's parent descriptor is written here.
parent : A pointer to the item's parent is written here.
parent_type : The type of the parent is written here. See DS_HANDLE_TYPES for a list of possible values.
index : The index number of the item in its parent descriptor is written here.

Returns: A code based on the type of the sub-structure found. See DS_IDENT_TABLE for a list of possible values.
Multithreading Level: Unsafe
Note:

The following rules apply to items: If the item is an atomic element, the parent is a packet. If the item is a dimension, the parent is an array. If the item is an atomic element in a linked list, the parent is a list header.

unsigned int ds_get_handle_in_list (packet_desc *list_desc, list_header *list_head, CONST char *item_name, CONST char *restr_names[], double *restr_values, unsigned int num_restr, char **parent_desc, char **parent, unsigned int *parent_type, unsigned int *index)

This routine will find a unique occurrence of an object (sub-structure) within a specified linked list.

Parameters:

list_desc : The linked list descriptor.
list_head : The list header.
item_name : The name of the object that the handle is desired for.
restr_names : The array of pointers to restrictions names.
restr_values : The array of restriction values.
num_restr : The number of restriction values.
parent_desc : A pointer to the item's parent descriptor is written here.
parent : A pointer to the item's parent is written here.
parent_type : The type of the parent is written here. See DS_HANDLE_TYPES for a list of possible values.
index : The index number of the item in its parent descriptor is written here.

Returns: A code based on the type of the sub-structure found. See DS_IDENT_TABLE for a list of possible values.
Multithreading Level: Unsafe
Note:

The following rules apply to items: If the item is an atomic element, the parent is a packet. If the item is a dimension, the parent is an array. If the item is an atomic element in a linked list, the parent is a list header.

void ds_list_insert (list_header *list_head, list_entry *new_entry, list_entry *entry)

Insert an entry into the fragmented section of a linked list.

Parameters:

list_head : The list header.
new_entry : The entry to be inserted.
entry : The list entry which is to be moved beyond the new entry. If this is NULL, the new entry is inserted at the start of the fragmented section of the list.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

Inserting an entry into a list with no entries in the fragmented section is safe (however, in this case entry must be NULL).

void ds_list_append (list_header *list_head, list_entry *entry)

Append an entry to a linked list.

Parameters:

list_head : The list header.
entry : The new list entry.

Returns: Nothing.
Multithreading Level: Unsafe

void ds_list_delete (packet_desc *list_desc, list_header *list_head, list_entry *entry)

Delete an entry from the fragmented section of a linked list.

Parameters:

list_desc : The packet descriptor for the list entry data. If this is not NULL, the routine will recursively deallocate the packet data.
list_head : The list header.
entry : The entry to be deleted. The entry and it's data packet are deallocated.

Returns: Nothing.
Multithreading Level: Unsafe

flag ds_list_unfragment (packet_desc *list_desc, list_header *list_head)

This routine will unfragment a linked list (i.e. all the entries and data packets in the linked list will be made contiguous in memory). This increases the storage efficiency (no list_entry structures are needed to link the data packets) as well as arbitrary indexing. This routine, used with a sorting routine (in either order of execution), can be used to speed up searching algorithms, such as ds_list_search. If the routine is not successful in allocating the required memory, then no change is effected (and the contiguous_length value in the list header is not changed). I.e. data is not lost.

Parameters:

list_desc : The packet descriptor for the list.
list_head : The linked list header.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

The contiguous_length value in the linked list header will be set to the length of the list.

flag ds_list_fragment (packet_desc *list_desc, list_header *list_head)

This routine will fragment a linked list (i.e. all the contiguous data packets in the linked list will be separately allocated and linked together by new list_entry structures. This decreases the storage efficiency (now list_entry structures are needed to link the data packets) rather than arbitrary indexing. However, it does provide for easy insertion of new entries into any part of the list. If the routine is not successful in allocating the required memory, then no change is effected (and the contiguous_length value in the list header is not changed). I.e. data is not lost.

Parameters:

list_desc : The packet descriptor for the list.
list_head : The list header.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

The contiguous_length value in the linked list header will be set to 0.

flag ds_remove_dim_desc (array_desc *arr_desc, CONST char *dim_name)

This routine will remove a dimension descriptor from an array descriptor. Tiling information is preserved, however, any address offset information is removed. With the exception of the dimension to be removed, the order of the dimensions is unaffected.

Parameters:

arr_desc : The array descriptor.
name : The name of the dimension to be removed.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ds_append_dim_desc (array_desc *arr_desc, dim_desc *dimension)

This routine will append a dimension descriptor to the list of dimensions attached to an array descriptor. The appended dimension will be the LEAST significant dimension (co-ordinates have lowest stride). Tiling information is preserved, however, any address offset information is removed. If the array is NOT tiled, the dimension length will be copied into the array of bottom tile lengths.

Parameters:

arr_desc : The array descriptor.
dimension : The dimension descriptor.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ds_prepend_dim_desc (array_desc *arr_desc, dim_desc *dimension)

This routine will prepend a dimension descriptor to the list of dimensions attached to an array descriptor. The prepended dimension will be the MOST significant dimension (co-ordinates have greatest stride). Tiling information is preserved, however, any address offset information is removed. If the array is NOT tiled, the dimension length will be copied into the array of bottom tile lengths.

Parameters:

arr_desc : The array descriptor.
dimension : The dimension descriptor to prepend.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ds_compute_array_offsets (array_desc *arr_desc)

Compute array address offsets for each dimension in an array.

Parameters:

arr_desc : The array descriptor. This descriptor is modified.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

void ds_remove_tiling_info (array_desc *arr_desc)

This routine will remove any tiling information from an array descriptor. The routine will NOT remove (or change) any offset information.

Parameters:

arr_desc : The array descriptor.

Returns: Nothing.
Multithreading Level: Unsafe

flag ds_append_gen_struct (multi_array *multi_desc, packet_desc *pack_desc, char *packet, char *existing_arrayname, char *append_arrayname)

This routine will append a general data structure to a multi_array general data structure.

Parameters:

multi_desc : The multi-array general data structure to append to.
pack_desc : The top level packet descriptor of the general data structure to append.
packet : The corresponding data for the general data structure.
existing_arrayname : If the multi-array data structure previously had only one general data structure, then this name will become the arrayname for that data structure.
append_arrayname : The name of the appended data structure.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

char * ds_put_element (char *output, unsigned int type, double input[2])

Write out an element of data.

Parameters:

output : A pointer to the output storage.
type : The type of the element to be written.
input : The input data.

Returns: The address of the next element on success, else NULL.
Multithreading Level: Unsafe

flag ds_put_elements (char *data, unsigned int data_type, unsigned int data_stride, double *values, unsigned int num_values)

This routine will convert an array of double precision complex values to an array of atomic data.

Parameters:

data : The array of output data.
data_type : The type of the data.
data_stride : The stride of data elements in memory (in bytes).
values : The data values will be read from here.
num_values : The number of data values to convert.

Returns: TRUE if the data was successfully converted, else FALSE.
Multithreading Level: Unsafe

flag ds_put_element_many_times (char *data, unsigned int data_type, unsigned int data_stride, double value[2], unsigned int num_elem)

This routine will convert and write a double precision complex value to an array of atomic data elements.

Parameters:

data : The array of output data.
data_type : The type of the data.
data_stride : The stride of data elements in memory (in bytes).
value : The data value will be read from here.
num_elem : The number of data elements to write.

Returns: TRUE if the data was successfully converted, else FALSE.
Multithreading Level: Unsafe

flag ds_put_named_element (packet_desc *pack_desc, char *packet, CONST char *name, double value[2])

Update a named element in a specified packet.

Parameters:

pack_desc : The packet descriptor.
packet : The packet.
name : The name of the element to update.
value : The value of the data.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ds_reorder_array (array_desc *arr_desc, unsigned int order_list[], char *array, flag mod_desc)

Re-order a multi-dimensional array.

Parameters:

arr_desc : The array descriptor.
order_list : This specifies the ordering of the dimensions. The first entry in the order list contains the number of the dimension, in the old order, which is to become the most significant dimension in the new ordering.
array : The array. If this is NULL, only the array descriptor can be re-ordered (no data can be re-ordered).
mod_desc : If TRUE the array descriptor will have its dimension descriptors re-ordered, else they will not be. This is useful to traverse a data structure, re-ordering the data, and then finally re-ordering the array descriptor to match.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ds_foreach_occurrence ( packet_desc *pack_desc, char *packet, CONST char *item, flag as_whole, flag (*func) () )

Recursively traverse a data structure, searching for an item.

Parameters:

pack_desc : The packet descriptor of the structure.
packet : The packet for the structure.
item : The name of the item to search for.
as_whole : If FALSE: If the item pointed to is the name of a dimension, then function will be called for each occurrence of that dimension (ie. the other dimensions will be iterated through). If the item pointed to is the name of an element, then function will be called for each occurrence of the element in the array or linked list which it is in. If TRUE: If the item pointed to is the name of a dimension or an element within a packet within an array, function is called once for each occurrence of the entire array. If the item pointed to is the name of an element in a linked list, then function will be called once for each occurrence of the linked list
func : The function to call for each occurrence. The prototype function is DS_PROTO_foreach_func. If this returns FALSE, iterations are stopped.

Returns: TRUE if all iterations completed successfully, else FALSE.
Multithreading Level: Unsafe

flag ds_foreach_in_array ( array_desc *arr_desc, char *array, CONST char *item, flag as_whole, flag (*func) () )

Recursively traverse an array, searching for an item.

Parameters:

arr_desc : The array descriptor.
array : The array data.
item : The name of the item to search for.
as_whole : If FALSE: If the item pointed to is the name of a dimension, then func will be called for each occurrence of that dimension (ie. the other dimensions will be iterated through). If the item pointed to is the name of an element, then func will be called for each occurrence of the element in the array or linked list which it is in. If TRUE: If the item pointed to is the name of a dimension or an element within a packet within an array, func is called once for each occurrence of the entire array. If the item pointed to is the name of an element in a linked list, then func will be called once for each occurrence of the linked list
func : The function to call for each occurrence. The prototype function is DS_PROTO_foreach_func. If this returns FALSE, iterations are stopped.

Returns: TRUE if all iterations completed successfully, else FALSE.
Multithreading Level: Unsafe

flag ds_foreach_in_list ( packet_desc *list_desc, list_header *list_head, CONST char *item, flag as_whole, flag (*func) () )

Recursively traverse a linked list, searching for an item.

Parameters:

list_desc : The packet descriptor for the linked list.
list_head : The linked list header.
item : The name of the item to search for.
as_whole : If FALSE: If the item pointed to is the name of a dimension, then func will be called for each occurrence of that dimension (ie. the other dimensions will be iterated through). If the item pointed to is the name of an element, then func will be called for each occurrence of the element in the array or linked list which it is in. If TRUE: If the item pointed to is the name of a dimension or an element within a packet within an array, func is called once for each occurrence of the entire array. If the item pointed to is the name of an element in a linked list, then func will be called once for each occurrence of the linked list
func : The function to call for each occurrence. The prototype function is DS_PROTO_foreach_func. If this returns FALSE, iterations are stopped.

Returns: TRUE if all iterations completed successfully, else FALSE.
Multithreading Level: Unsafe

flag ds_traverse_and_process ( packet_desc *desc1, char *data1, packet_desc *desc2, char *data2, flag as_whole, flag (*func) () )

This routine will traverse a pair of general data structures and will process a sub structure for every occurence wherever there is a difference in the two data structures' descriptors.

Parameters:

desc1 : One of the structures packet descriptor.
data1 : One of the structures data.
desc2 : The other structures packet descriptor.
data2 : The other structures data.
as_whole : If FALSE: If the type or name of any element in the two packet descriptors are different, the packets are deemed divergent and they are passed to func. If any aspect of the two array's dimension descriptors are different, then the arrays are deemed divergent and their descriptors are passed to func. If TRUE: If the type or name of any element in the two packet descriptors are different, the packets are deemed divergent and they are passed to func. If any aspect of the two array's dimension descriptors are different, or their packet descriptors are divergent, then the arrays are deemed divergent and the array descriptors are passed to func. If the packet descriptors for linked lists are divergent, then the two lists are deemed divergent and their descriptors and headers are passed to func.
func : The function to call for each divergence. The prototype function is DS_PROTO_traverse_func. If this returns FALSE, iterations are stopped.

Returns: TRUE if all iterations completed successfully, else FALSE.
Multithreading Level: Unsafe

flag ds_traverse_array ( array_desc *desc1, char *data1, array_desc *desc2, char *data2, flag as_whole, flag (*func) () )

This routine will traverse a pair of multi-dimensional arrays will process a sub structure for every occurence wherever there is a difference in the two data structures' descriptors.

Parameters:

desc1 : One of the array descriptors.
data1 : One of the arrays.
desc2 : The other array descriptor.
data2 : The other array.
as_whole : If FALSE: If the type or name of any element in the two packet descriptors are different, the packets are deemed divergent and they are passed to func. If any aspect of the two array's dimension descriptors are different, then the arrays are deemed divergent and their descriptors are passed to func. If TRUE: If the type or name of any element in the two packet descriptors are different, the packets are deemed divergent and they are passed to func. If any aspect of the two array's dimension descriptors are different, or their packet descriptors are divergent, then the arrays are deemed divergent and the array descriptors are passed to func. If the packet descriptors for linked lists are divergent, then the two lists are deemed divergent and their descriptors and headers are passed to func.
func : The function to call for each divergence. The prototype function is DS_PROTO_traverse_func. If this returns FALSE, iterations are stopped.

Returns: TRUE if all iterations completed successfully, else FALSE.
Multithreading Level: Unsafe

flag ds_traverse_list ( packet_desc *desc1, list_header *head1, packet_desc *desc2, list_header *head2, flag as_whole, flag (*func) () )

This routine will traverse a pair of linked lists and will process a sub structure for every occurence wherever there is a difference in the two data structures' descriptors.

Parameters:

desc1 : One of lists descriptor.
data1 : One of the lists header.
desc2 : The other lists descriptor.
data2 : The other lists header.
as_whole : If FALSE: If the type or name of any element in the two packet descriptors are different, the packets are deemed divergent and they are passed to func. If any aspect of the two array's dimension descriptors are different, then the arrays are deemed divergent and their descriptors are passed to func. If TRUE: If the type or name of any element in the two packet descriptors are different, the packets are deemed divergent and they are passed to func. If any aspect of the two array's dimension descriptors are different, or their packet descriptors are divergent, then the arrays are deemed divergent and the array descriptors are passed to func. If the packet descriptors for linked lists are divergent, then the two lists are deemed divergent and their descriptors and headers are passed to func.
func : The function to call for each divergence. The prototype function is DS_PROTO_traverse_func. If this returns FALSE, iterations are stopped.

Returns: TRUE if all iterations completed successfully, else FALSE.
Multithreading Level: Unsafe

Prototype Functions

flag DS_PROTO_foreach_func (char *encls_desc, unsigned int type, char *data, unsigned int index)

Process an occurrence of an item in a data structure.

Parameters:

encls_desc : The enclosing descriptor.
type : The type of the enclosing descriptor. See DS_PARENT_TYPES for a list of possible values.
data : A pointer to the item data. This is: A pointer to the first element (for a packet descriptor) A pointer to a portion of the array (for an array or dimension descriptor) A pointer to the linked list header (for a linked list descriptor)
index : The index number of the item in the enclosing descriptor, for the cases where the enclosing descriptor is a packet, array or linked list descriptor. For the case where the enclosing descriptor is a dimension descriptor, this carries the stride (in bytes) between consecutive co-ordinates in the dimension.

Returns: TRUE on success, else FALSE
Multithreading Level: Unsafe

flag DS_PROTO_traverse_function (char *desc1, unsigned int type1, char *data1, char *desc2, unsigned int type2, char *data2)

Process an occurrence of a divergence between two data structures

Parameters:

desc1 : One of the descriptors where the divergence occurred.
type1 : The type of the first descriptor. See DS_PARENT_TYPES for a list of possible values. The value IDENT_DIMENSION is not possible.
data : The data for the first descriptor.
desc2 : The other descriptor where the divergence occurred.
type2 : The type of the other descriptor. See DS_PARENT_TYPES for a list of possible values. The value IDENT_DIMENSION is not possible.
data2 : The data for the other descriptor.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

Tables

DS_COMPLEX_CONVERSIONS

Name Meaning

CONV_CtoR_REAL Take the real component
CONV_CtoR_IMAG Take the imaginary component
CONV_CtoR_ABS Take the absolute value
CONV_CtoR_SQUARE_ABS Take the square of the absolute value
CONV_CtoR_PHASE Take the phase
CONV_CtoR_CONT_PHASE Take the continuous phase
CONV_CtoR_ENVELOPE Use the positive and negative of the absolute value

DS_KARMA_DATA_TYPES

Name Meaning C data type

K_FLOAT Single precision floating point float
K_DOUBLE Double precision floating point double
K_BYTE Signed byte (character) signed char
K_INT Signed integer signed int
K_SHORT Signed short integer signed short
K_COMPLEX Complex float float[2]
K_DCOMPLEX Complex double double[2]
K_BCOMPLEX Complex signed byte signed char[2]
K_ICOMPLEX Complex signed integer signed int[2]
K_SCOMPLEX Complex signed short integer signed short[2]
K_LONG Signed long integer signed long
K_LCOMPLEX Complex signed long integer signed long[2]
K_UBYTE Unsigned byte unsigned char
K_UINT Unsigned integer unsigned int
K_USHORT Unsigned short integer unsigned short
K_ULONG Unsigned long integer unsigned long
K_UBCOMPLEX Complex unsigned byte unsigned char[2]
K_UICOMPLEX Complex unsigned integer unsigned int[2]
K_USCOMPLEX Complex unsigned short integer unsigned short[2]
K_ULCOMPLEX Complex unsigned long integer unsigned long[2]

DS_IDENT_TABLE

Name Meaning

IDENT_NOT_FOUND Name not found
IDENT_GEN_STRUCT Name of general data structure
IDENT_DIMENSION Name of dimension
IDENT_ELEMENT Name of atomic data element
IDENT_MULTIPLE Name has multiple occurrences

DS_SEARCH_BIASES

Name Meaning

SEARCH_BIAS_LOWER Pick lower co-ordinate
SEARCH_BIAS_CLOSEST Pick closest co-ordinate
SEARCH_BIAS_UPPER Pick upper co-ordinate

DS_HANDLE_TYPES

Name Meaning

NONE if the item's parent is a packet.
K_ARRAY if the item's parent is an array.
LISTP if the item's parent is a linked list header.

DS_PARENT_TYPES

Name Meaning

NONE parent is a packet descriptor
IDENT_DIMENSION parent is a dimension descriptor
K_ARRAY parent is an array descriptor
LISTP parent is a linked list descriptor

Contact: Richard Gooch
Web Development: Ariel Internet Services

Name	Meaning

CONV_CtoR_REAL	Take the real component
CONV_CtoR_IMAG	Take the imaginary component
CONV_CtoR_ABS	Take the absolute value
CONV_CtoR_SQUARE_ABS	Take the square of the absolute value
CONV_CtoR_PHASE	Take the phase
CONV_CtoR_CONT_PHASE	Take the continuous phase
CONV_CtoR_ENVELOPE	Use the positive and negative of the absolute value

Name	Meaning	C data type

K_FLOAT	Single precision floating point	float
K_DOUBLE	Double precision floating point	double
K_BYTE	Signed byte (character)	signed char
K_INT	Signed integer	signed int
K_SHORT	Signed short integer	signed short
K_COMPLEX	Complex float	float[2]
K_DCOMPLEX	Complex double	double[2]
K_BCOMPLEX	Complex signed byte	signed char[2]
K_ICOMPLEX	Complex signed integer	signed int[2]
K_SCOMPLEX	Complex signed short integer	signed short[2]
K_LONG	Signed long integer	signed long
K_LCOMPLEX	Complex signed long integer	signed long[2]
K_UBYTE	Unsigned byte	unsigned char
K_UINT	Unsigned integer	unsigned int
K_USHORT	Unsigned short integer	unsigned short
K_ULONG	Unsigned long integer	unsigned long
K_UBCOMPLEX	Complex unsigned byte	unsigned char[2]
K_UICOMPLEX	Complex unsigned integer	unsigned int[2]
K_USCOMPLEX	Complex unsigned short integer	unsigned short[2]
K_ULCOMPLEX	Complex unsigned long integer	unsigned long[2]

Name	Meaning

IDENT_NOT_FOUND	Name not found
IDENT_GEN_STRUCT	Name of general data structure
IDENT_DIMENSION	Name of dimension
IDENT_ELEMENT	Name of atomic data element
IDENT_MULTIPLE	Name has multiple occurrences

Name	Meaning

SEARCH_BIAS_LOWER	Pick lower co-ordinate
SEARCH_BIAS_CLOSEST	Pick closest co-ordinate
SEARCH_BIAS_UPPER	Pick upper co-ordinate

Name	Meaning

NONE	if the item's parent is a packet.
K_ARRAY	if the item's parent is an array.
LISTP	if the item's parent is a linked list header.