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_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_find_1D_sum	Find the sum of a 1D array.
ds_find_1D_stats	Compute simple statistics for a 1D array.
ds_find_2D_stats	Compute simple statistics for a 2D array.
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_copy_unique_named_element	Copy a unique named element from one packet to another.
ds_get_fits_axis	Get the FITS axis number of a dimension.
ds_element_is_fits_compatible	Test if an element is FITS-compatible.
ds_get_data_scaling	Get the scale and offset for a data element in a packet.
ds_set_data_scaling	Set the data scale and offset for a data element in a packet.
ds_get_data_range	Get the data range for a data element in a packet.
ds_set_data_range	Set the data range for a data element in a packet.
ds_remove_unique_named_element	Remove a unique named element from a Karma general data structure
ds_find_centroid	Find the centroid inside an ellipse.
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_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_contour	Extract contours from a 2-dimensional array.
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_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_easy_alloc_array_from_array_desc	Wrap a data structure around an array.
ds_alloc_vm_array	Allocate storage for an array using ordinary virtual memory.
ds_alloc_shm_array	Allocate storage for an array using shared memory.
ds_alloc_mmap_array	Allocate storage for an array using shared anon mmap.
ds_event_register_func	Register a multi_array event function.
ds_event_dispatch	Dispatch a multi_array event.
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_f_dim_in_array	Find dimension in array.
ds_check_for_descriptor	Check if descriptor pointer lies in data structure.
ds_find_descriptor_parent	Find the index of the data structure containing a descriptor.
ds_fitgauss_list	Fit a gaussian to a list of points.
ds_fitgauss_profile	Fit a gaussian to a 1-dimensional profile.
ds_gausscurve	Write gaussian curve to an array.
ds_convert_atomic	Convert an atomic datum to a double precision value.
ds_get_coordinate	Get a co-ordinate along a dimension.
ds_convert_coordinates	Convert co-ordinate values for 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_check_array_can_fit	Check if the array data can fit in the machine.
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_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_history_append_string	Add a history string to a Karma data structure.
ds_history_copy	Copy history information.
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_format_unit	Format a unit string.
ds_format_value	Format a data value into a string.
ds_remove_named_elements	Remove a list of named elements from a packet.
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_autotile_array	Choose tiling scheme automatically.
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_func	Process an occurrence of a divergence between two data structures
ds_PROTO_event_func	Process an event.

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

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_find_1D_sum (CONST char *data, unsigned int elem_type, unsigned int num_values, CONST uaddr *offsets, unsigned int stride, double sum[2])

This routine will find the sum of a single trace (element versus a dimension). This routine may be called repeatedly with multiple traces in order to build an aggregate sum 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.
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.
sum : The sum is written here.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_find_1D_stats (CONST char *data, unsigned int num_values, uaddr *offsets, unsigned int elem_type, unsigned int conv_type, double *min, double *max, double *mean, double *stddev, double *sum, double *sumsq, unsigned long *npoints)

This routine will find the minimum, maximum, mean, rms, sum and sum-of-squares of a single trace (element versus a dimension). Blanked values are excluded.

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.
mean : The mean value will be written here.
stddev : The standard deviation will be written here.
sum : The total of all values will be written here.
sumsq : The total of the squares of all values will be written here.
npoints : The number of values used to compute statistics will be written here. This may differ from num_values if there are blanked pixels.

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.

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_find_2D_stats (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, double *mean, double *stddev, double *sum, double *sumsq, unsigned long *npoints)

This routine will find the minimum, maximum, mean, rms and sum 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.
mean : The mean value will be written here.
stddev : The standard deviation will be written here.
sum : The total of all values will be written here.
sumsq : The total of the squares of all values will be written here.
npoints : The number of values used to compute statistics will be written here. This will differ from num_values if there are blanked pixels.

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_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. On error, the type of the element is written here. The value NONE is written here if the element does not exist.
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

flag ds_copy_unique_named_element (packet_desc *out_desc, char **out_packet, CONST packet_desc *in_desc, CONST char *in_packet, CONST char *name, flag fail_if_not_found, flag fail_on_duplicate, flag replace)

Copy a unique named element from one packet to another.

Parameters:

out_desc : The packet descriptor to add the name to. This descriptor will be modified.
out_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.
in_desc : The input packet descriptor.
in_packet : The input packet.
name : The name of the element to copy.
fail_if_not_found : If TRUE, the routine will fail if the element does not exist in the input packet.
fail_on_duplicate : If TRUE, the routine will fail if the element already exists in the output packet.
replace : If TRUE and the element already exists in the output packet, it is replaced.

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

unsigned int ds_get_fits_axis (CONST packet_desc *top_pack_desc, CONST char *top_packet, CONST char *dim_name)

Get the FITS axis number of a dimension.

Parameters:

top_pack_desc : The top-level packet descriptor.
top_packet : The top-level packet.
dim_name : The name of the dimension.

Returns: The FITS axis number on success, else 0.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_element_is_fits_compatible (CONST char *elem_name, CONST packet_desc *pack_desc, CONST char *packet)

Test if an element is FITS-compatible.

Parameters:

elem_name : The name of the element.
pack_desc : The top-level packet descriptor.
packet : The top-level packet data.

Returns: TRUE if the element is FITS-compatible, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_get_data_scaling (CONST char *elem_name, CONST packet_desc *pack_desc, CONST char *packet, double *scale, double *offset)

This routine will determine the scale and offset for data in a packet. This may be important when a floating-point array has been converted to an integer array to save space. Scaling information should be attached to the array so that the original data values may be reconstructed (aside from quantisation effects). The following expression may be used to convert scaled values to real values: (output = input * scale + offset). The scaling and offset values should previously have been attached to the array using an appropriate routine. No low-level routine currently exists to do this, but higher-level support is given by the iarray_set_data_scaling routine.

Parameters:

elem_name : The name of the element.
pack_desc : The packet descriptor.
packet : The packet.
scale : The scaling value will be written here. The name of the scaling value is constructed by appending "__SCALE" to the element name. If no scaling value is found, 1.0 is written here. As a fallback, if the FITS-style "BSCALE" keyword is found and is appropriate, this is used.
offset : The offset value will be written here. The name of the offset value is constructed by appending "__OFFSET" to the element name. If no offset value is found, 0.0 is written here. As a fallback, if the FITS-style "BZERO" keyword is found and is appropriate, this is used.

Returns: TRUE if either the scaling or offset value were found, else FALSE
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_set_data_scaling (CONST char *elem_name, packet_desc *pack_desc, char **packet, double scale, double offset)

Set the data scale and offset for a data element in a packet.

Parameters:

elem_name : The name of the element.
pack_desc : The packet descriptor.
packet : The packet.
scale : The scale value. The name of the scale value is constructed by appending "__SCALE" to the element name. If appropriate, the FITS-style "BSCALE" keyword is written instead.
offset : The offset value. The name of the offset value is constructed by appending "__OFFSET" to the element name. If appropriate, the FITS-style "BZERO" keyword is written instead.

Returns: TRUE if the scale information is different from what was already attached to the array, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_get_data_range (CONST char *elem_name, CONST packet_desc *pack_desc, CONST char *packet, double *minimum, double *maximum)

This routine will determine the range of scaled data in a packet. Range information should be attached to the array. No low-level routine currently exists to do this.

Parameters:

elem_name : The name of the element.
pack_desc : The packet descriptor.
packet : The packet.
minimum : The minimum value will be written here. The name of the minimum value is constructed by appending "__MINIMUM" to the element name. If no minimum value is found, -TOOBIG is written here. As a fallback, if the FITS-style "DATAMIN" keyword is found and is appropriate, this is used.
maximum : The minimum value will be written here. The name of the minimum value is constructed by appending "__MINIMUM" to the element name. If no minimum value is found, TOOBIG is written here. As a fallback, if the FITS-style "DATAMAX" keyword is found and is appropriate, this is used.

Returns: TRUE if either the min. or max. value were found, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_set_data_range (CONST char *elem_name, packet_desc *pack_desc, char **packet, double minimum, double maximum)

Set the data range for a data element in a packet.

Parameters:

elem_name : The name of the element.
pack_desc : The packet descriptor.
packet : The packet.
minimum : The minimum value. The name of the minimum value is constructed by appending "__MINIMUM" to the element name. If appropriate, the FITS-style "DATAMIN" keyword is written instead.
maximum : The maximum value. The name of the maximum value is constructed by appending "__MAXIMUM" to the element name. If appropriate, the FITS-style "DATAMAX" keyword is written instead.

Returns: TRUE if the range information is different from what was already attached to the array, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_remove_unique_named_element (packet_desc *pack_desc, char **packet, CONST char *name, flag tolerant)

Remove a unique named element from a Karma general data structure

Parameters:

pack_desc : The packet descriptor to remove the name from. 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.
tolerant : If TRUE, no error is generated if the element is missing.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_find_centroid (CONST char *image, unsigned int type, double *background, flag *inverted, uaddr xlen, CONST uaddr *xoffsets, double *xpos, uaddr xradius, uaddr ylen, CONST uaddr *yoffsets, double *ypos, uaddr yradius)

This routine will search for the centroid of an object inside a specified ellipse. The background (median) value is computed for an annulus outside the ellipse. The annulus is 10% larger than the ellipse.

Parameters:

image : The image data.
type : The type of the image data.
background : The background value is written here. This may be NULL.
inverted : The value TRUE will be written here if the image values are inverted (i.e. the object of interested is in a local minimum rather than a maximum).
xlen : The horizontal image width.
xoffsets : The array of horizontal byte offsets
xpos : The horizontal data pixel position. The original value must be a reasonable approximation. This is modified to the centroid position.
xradius : The horizontal radius of the ellipse.
ylen : The vertical image width.
yoffsets : The array of vertical byte offsets
ypos : The vertical data pixel position. The original value must be a reasonable approximation. This is modified to the centroid position.
yradius : The vertical radius of the ellipse.

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

(0.0, 0.0) corresponds to the centre of the first pixel.

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_compare_packet_desc (CONST packet_desc *desc1,CONST 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 (CONST array_desc *desc1, CONST 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 (CONST dim_desc *desc1, CONST 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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_contour (CONST char *image, unsigned int elem_type, CONST dim_desc *hdim, CONST uaddr *hoffsets, CONST dim_desc *vdim, CONST uaddr *voffsets, unsigned int num_levels, CONST double *contour_levels, uaddr structure_size, uaddr *buffer_sizes, double **x0_arr, double **y0_arr, double **x1_arr, double **y1_arr, uaddr *num_segments)

This routine will extract contours from a 2-dimensional Intelligent Array, producing a list of line segments that approximate the countours. The co-ordinates of the line segments are in linear world co-ordinates.

Parameters:

image : The start of the image slice data.
elem_type : The type of the data.
hdim : The horizontal dimension descriptor.
hoffsets : The address offsets for data along the horizontal dimension.
vdim : The vertical dimension descriptor.
voffsets : The address offsets for data along the vertical dimension.
num_levels : The number of contour levels.
contour_levels : The array of contour levels.
structure_size : The size (in bytes) of the per-level data structure. The calling function is expected to pass pointers to various fields in the first structure. The fields are modified.
buffer_sizes : A pointer to the first co-ordinate buffer size field.
x0_arr : A pointer to the first x0 co-ordinate array field. The co-ordinate array may be internally reallocated.
y0_arr : A pointer to the first y0 co-ordinate array field. The co-ordinate array may be internally reallocated.
x1_arr : A pointer to the first x1 co-ordinate array field. The co-ordinate array may be internally reallocated.
y1_arr : A pointer to the first y1 co-ordinate array field. The co-ordinate array may be internally reallocated.
num_segments : A pointer to the first number of segments field.

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

flag ds_copy_packet (CONST packet_desc *pack_desc, char *dest_packet, CONST 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 (CONST 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 (CONST 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 (CONST 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 (CONST packet_desc *inp_desc, CONST 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, CONST 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 (CONST packet_desc *inp_desc, CONST 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, CONST 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

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. If this is 0, no packet descriptor is allocated.
data_types : The types of the elements in the array. See ds_KARMA_DATA_TYPES for a list of legal values. This may be NULL if num_elements is 0.
data_names : The array of element names. The name strings are copied, thus the memory used for the input strings may be subsequently deallocated. This may be NULL if num_elements is 0.

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

EXPERIMENTAL FUNCTION: subject to change without notice

multi_array * ds_easy_alloc_array_from_array_desc (CONST array_desc *arr_desc, CONST array_pointer *arrayp, flag clear)

Parameters:

arr_desc : The array descriptor describing the array data.
arrayp : The array data pointer. If this is NULL the array data is internally allocated.
clear : If TRUE, then the routine will initialise (set to zero) all the data, if that data is internally allocated.

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.

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_alloc_vm_array (array_pointer *arrayp, CONST array_desc *arr_desc, flag clear, flag warn)

Allocate storage for an array using ordinary virtual memory.

Parameters:

arrayp : Information describing the shared memory region is written here.
arr_desc : The array descriptor describing the array data. This is used to determine the amount of memory require to store the array.
clear : If TRUE the array data is initialised to zero.
warn : If TRUE, warning messages are displayed if there are any problems.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_alloc_shm_array (array_pointer *arrayp, CONST array_desc *arr_desc, flag clear, flag warn)

Allocate storage for an array using shared memory.

Parameters:

arrayp : Information describing the shared memory region is written here.
arr_desc : The array descriptor describing the array data. This is used to determine the amount of memory require to store the array.
clear : If TRUE the array data is initialised to zero.
warn : If TRUE, warning messages are displayed if there are any problems.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_alloc_mmap_array (int fd, uaddr offset, uaddr size, flag writable, array_pointer *arrayp, CONST array_desc *arr_desc, flag clear, flag warn)

Allocate storage for an array using shared anon mmap.

Parameters:

fd : The file descriptor to map. If this is less than zero, "/dev/zero" is mapped.
offset : The offset from the start of the file where the array data should reside.
size : The size of the region to map. If this is 0 the size is taken from the array size.
writable : If the mapped pages are to be writable, this must be TRUE. If this is FALSE and the memory pages are written to, a segmentation fault occurs.
arrayp : Information describing the shared memory region is written here.
arr_desc : The array descriptor describing the array data. This is used to determine the amount of memory require to store the array.
clear : If TRUE the array data is initialised to zero.
warn : If TRUE, warning messages are displayed if there are any problems.

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

The file is mapped from its start.

EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc ds_event_register_func (flag (*func) (), void *object)

Parameters:

func : The function which is called to process an event. The prototype function is ds_PROTO_event_func.
object : The object.

Returns: A KCallbackFunc object. On failure, the process aborts.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_event_dispatch (multi_array *multi_desc, CONST char *domain, CONST char *name)

Dispatch a multi_array event.

Parameters:

multi_desc : The multi_array descriptor.
domain : The domain from where the event was generated.
name : The name of the event in its domain.

Returns: TRUE if one of the callbacks quenched the further delivery of callbacks, else FALSE.
Multithreading Level: Unsafe

unsigned int ds_identify_name (CONST 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 (CONST 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 (CONST 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 (CONST 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

unsigned int ds_f_dim_in_array (CONST 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.

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_check_for_descriptor (CONST packet_desc *pack_desc, void *pointer)

Check if descriptor pointer lies in data structure.

Parameters:

pack_desc : The packet descriptor to search recursively.
pointer : The pointer to search for. This may be an array or packet descriptor.

Returns: TRUE if the descriptor pointer was found, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

unsigned int ds_find_descriptor_parent (CONST multi_array *multi_desc, void *pointer)

Find the index of the data structure containing a descriptor.

Parameters:

multi_desc : The multi_array descriptor to search.
pointer : The pointer to search for. This may be an array or packet descriptor.

Returns: The index of the top-level data structure if found, else the number of data structures.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_fitgauss_list (CONST double *x, CONST double *y, unsigned int num_points, double background, flag inverted, double xcentre, double *peak_height, double *fwhm, double *sum)

This routine will fit a gaussian to a 1-dimensional profile. The algorithm uses a non-linear least squares method.

Parameters:

x : The array of position (distance) values.
y : The array of values. These may be modified.
num_points : The number of points.
background : The background sky level.
inverted : If TRUE the object values are inverted (i.e. is negative) else the object is positive.
xcentre : The centre of the profile. If this is 0 it is assumed the profile is radial (i.e. the centre is at 0).
peak_height : The height of the fitted peak above the background is written here.
fwhm : The Full Width Half Maximum of the fit is written here.
sum : The sum of the fitted profile above the background is written here.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_fitgauss_profile (CONST float *array, CONST uaddr *offsets, unsigned int num_points, double background, flag inverted, double xcentre, double *peak_height, double *fwhm, double *sum)

This routine will fit a gaussian to a 1-dimensional profile. The algorithm uses a non-linear least squares method.

Parameters:

array : The 1-dimensional array of data.
offsets : The array of byte offsets for the array data.
num_points : The length of the array.
background : The background sky level.
inverted : If TRUE the object values are inverted (i.e. is negative) else the object is positive.
xcentre : The centre of the profile. If this is 0 it is assumed the profile is radial (i.e. the centre is at 0).
peak_height : The height of the fitted peak above the background is written here.
fwhm : The Full Width Half Maximum of the fit is written here.
sum : The sum of the fitted profile above the background is written here.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void ds_gausscurve (double *array, CONST uaddr *offsets, unsigned int num_points, double xcentre, double peak_height, double fwhm, double background, flag inverted)

This routine will a gaussian curve to a 1-dimensional array. This array may be used for plotting over real data to which a gaussian has been fitted with ds_fitgauss.

Parameters:

array : The 1-dimensional array of data.
offsets : The array of byte offsets for the array data. If this is NULL, the array is assumed to be contiguous.
num_points : The length of the array.
xcentre : The centre of the profile. If this is 0 it is assumed the profile is radial (i.e. the centre is at 0).
peak_height : The height of the fitted peak (without background subtraction).
fwhm : The Full Width Half Maximum of the fit.
background : The background level.
inverted : If TRUE the object values are inverted (i.e. is negative) else the object is positive.

Returns: Nothing.
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 (CONST dim_desc *dimension, double 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

EXPERIMENTAL FUNCTION: subject to change without notice

void ds_convert_coordinates (CONST dim_desc *dim, unsigned int num_coords, double *coords, flag to_indices, flag blank, flag add_half)

This function will convert between co-ordinates indices (index positions along a dimension) and co-ordinate values. The co-ordinate values may be regularly or irregularly spaced, either case is catered for. Note that for co-ordinate systems which have a dependency between different axes (such as RA-DEC co-ordinates used in astronomy), the co-ordinate values this function manipulates are linear co-ordinates. The wcs package provides for conversion between linear and non-linear co-ordinates (proper world co-ordinates).

Parameters:

dim : The dimension descriptor.
num_coords : The number of co-ordinate values to convert.
coords : The array of co-ordinate values to convert.
to_indices : If TRUE, the co-ordinate values are converted to index positions along the dimension, else they are converted to co-ordinate values.
blank : If TRUE, all out-of-bounds values are set to TOOBIG, else out-of-bounds values may or may not be set to TOOBIG. If you know all your values are within bounds, setting this to FALSE may save time.
add_half : If TRUE and to_indices is TRUE, the value 0.5 will be added to all in-bounds values as they are written.

Returns: Nothing.
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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_check_array_can_fit (CONST array_desc *arr_desc)

Check if the array data can fit in the machine.

Parameters:

arr_desc : The array descriptor.

Returns: TRUE if the array may fit, otherwise FALSE.
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 long ds_get_array_offset (CONST array_desc *arr_desc, CONST 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 (CONST 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: Safe.

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

double * ds_get_coordinate_array (CONST 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.

flag ds_history_append_string (multi_array *multi_desc, CONST char *string, flag new_alloc)

Add a history string to a Karma data structure.

Parameters:

multi_desc : The multi_array descriptor.
string : The history string to add.
new_alloc : If TRUE, the routine will allocate a new copy of the history string, else it will copy the pointer (in which case the string must never be externally deallocated or changed).

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

flag ds_history_copy (multi_array *out, CONST multi_array *in)

Copy history information.

Parameters:

out : The output multi_array descriptor to copy the history to.
in : The input multi_array descriptor to copy the history from.

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

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

EXPERIMENTAL FUNCTION: subject to change without notice

void ds_format_unit (char unit[STRING_LENGTH], char format[STRING_LENGTH], double *scale, CONST char *value_name, double value)

Format a unit string.

Parameters:

unit : The unit string will be written here.
format : The formatting string is written here.
scale : The scale value to apply to data to convert to displayed units will be written here. If this is NULL nothing is written here.
value_name : The name of the value to format.
value : The (scaled) value. Used for beautifying the unit name.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void ds_format_value (char string[STRING_LENGTH], double value, CONST char *value_name, double scale, double offset, double format_value, CONST packet_desc *pack_desc, CONST char *packet)

Format a data value into a string.

Parameters:

string : The string to write to.
value : The (raw) value to format.
value_name : The name of the value to format.
scale : The scale value to apply to the data. If this is TOOBIG and pack_desc and packet are non-NULL, the routine uses the scale and offset attached to the data. See ds_get_data_scaling for details.
offset : The offset to apply after scaling the data.
format_value : The (raw) value to use for beautifying the unit name.
pack_desc : The packet descriptor containing associated data scaling.
packet : The packet containing associated data scaling.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_remove_named_elements (packet_desc *pack_desc, char **packet, CONST char **element_names)

Remove a list of named elements from a packet.

Parameters:

pack_desc : The packet descriptor.
packet : A pointer to the packet pointer.
element_names : The NULL-terminated array of element names to be removed.

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

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ds_autotile_array (array_desc *arr_desc, flag allow_truncate)

This routine will choose an optimum tiling scheme for an array.

Parameters:

arr_desc : The array descriptor. This is modified.
allow_truncate : If TRUE, the routine will shorten the lengths of dimensions to allow tiling.

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 (CONST 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_func (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

flag ds_PROTO_event_func (void *object, multi_array *multi_desc, CONST char *domain, CONST char *name)

Process an event.

Parameters:

object : The object information pointer.
multi_desc : The multi_array descriptor.
domain : The domain from where the event was generated.
name : The name of the event in its domain.

Returns: TRUE if further callbacks should not be called, else FALSE.
Multithreading Level: Unsafe

Tables

ds_COMPLEX_CONVERSIONS List of complex conversion types

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 List of 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 List of identification codes

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 List of co-ordinate 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 List of 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 List of parent descriptor 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

Back to Karma Home Page

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.