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_multiAllocate a multi_array descriptor.
ds_alloc_packet_descAllocate a packet descriptor.
ds_alloc_dataAllocate packet data recursively.
ds_alloc_packet_subdataAllocate packet sub-data.
ds_alloc_packetAllocate packet.
ds_alloc_array_descAllocate array descriptor.
ds_alloc_tiling_infoAllocate array tiling information.
ds_alloc_dim_descAllocate a dimension descriptor.
ds_alloc_list_headAllocate a linked list header.
ds_alloc_list_entryAllocate a linked list entry.
ds_alloc_arrayAllocate an array.
ds_alloc_contiguous_listAllocate a contiguous list of linked list entries.
ds_find_1D_extremesFind the minimum and maximum of a 1D array.
ds_find_2D_extremesFind the minimum and maximum of a 2D array.
ds_find_contiguous_extremesFind the minimum and maximum of a contiguous array.
ds_find_single_histogramFind the histogram of a 1D array.
ds_complex_to_real_1DConvert a 1 dimensional array of complex values to real values.
ds_find_1D_sumFind the sum of a 1D array.
ds_find_1D_statsCompute simple statistics for a 1D array.
ds_find_2D_statsCompute simple statistics for a 2D array.
ds_put_unique_named_valueAdd a unique named value to a Karma general data structure.
ds_put_unique_named_stringAdd a unique named string to a Karma general data structure.
ds_get_unique_named_valueGet a unique named value from a Karma general data structure.
ds_get_unique_named_stringGet a unique named string from a Karma general data structure.
ds_copy_unique_named_elementCopy a unique named element from one packet to another.
ds_get_fits_axisGet the FITS axis number of a dimension.
ds_element_is_fits_compatibleTest if an element is FITS-compatible.
ds_get_data_scalingGet the scale and offset for a data element in a packet.
ds_set_data_scalingSet the data scale and offset for a data element in a packet.
ds_get_data_rangeGet the data range for a data element in a packet.
ds_set_data_rangeSet the data range for a data element in a packet.
ds_remove_unique_named_elementRemove a unique named element from a Karma general data structure
ds_find_centroidFind the centroid inside an ellipse.
ds_cmap_alloc_colourmapAllocate a Karma data structure to hold a colourmap.
ds_cmap_find_colourmapSearch a Karma data structure for an instance of a colourmap.
ds_cmap_get_all_colourmapsSearch an array of Karma data structures for colourmaps.
ds_compare_packet_descRecursively compare two packet descriptors.
ds_compare_array_descRecursively compare two array descriptors.
ds_compare_dim_descCompare two dimension descriptors.
ds_contourExtract contours from a 2-dimensional array.
ds_copy_packetCopy a packet.
ds_copy_desc_untilRecursively copy a packet descriptor.
ds_copy_array_desc_untilRecursively copy an array descriptor.
ds_copy_dim_descCopy a dimension descriptor.
ds_copy_dataCopy data between Karma data structures.
ds_copy_arrayRecursively copy array data.
ds_copy_listRecursively copy linked lists.
ds_select_arraysSelect data structures in a multi_array descriptor.
ds_dealloc_multiDeallocate a multi_array data structure.
ds_dealloc_packetRecursively deallocate a packet.
ds_dealloc_dataRecursively deallocate packet data.
ds_dealloc_packet_subdataRecursively deallocate packet data.
ds_dealloc_array_descRecursively deallocate an array.
ds_dealloc_listRecursively deallocate a linked list.
ds_dealloc_list_entriesRecursively deallocate list entries.
ds_dealloc2_listDeallocate linked list entries.
ds_dealloc_arrayRecursively deallocate array.
ds_draw_ellipseDraw an ellipse into a 2 dimensional Karma array.
ds_draw_polygonDraw a polygon into a 2 dimensional array.
ds_easy_alloc_arrayAllocate a data structure with a simple array.
ds_easy_alloc_n_element_arrayAllocate a data structure with a simple, multi element array.
ds_wrap_preallocated_n_element_arrayWrap a data structure around an array.
ds_easy_alloc_array_descAllocate a simple array descriptor.
ds_easy_alloc_array_from_array_descWrap a data structure around an array.
ds_alloc_vm_arrayAllocate storage for an array using ordinary virtual memory.
ds_alloc_shm_arrayAllocate storage for an array using shared memory.
ds_alloc_mmap_arrayAllocate storage for an array using shared anon mmap.
ds_event_register_funcRegister a multi_array event function.
ds_event_dispatchDispatch a multi_array event.
ds_identify_nameSearch a data structure for a name.
ds_f_array_nameSearch a the top level of a data structure for a name.
ds_f_name_in_packetRecursively search for named item under a packet.
ds_f_name_in_arrayRecursively search for named item under an array.
ds_f_elem_in_packetSearch for a named element in a packet, without recursion.
ds_find_holeRecursively search packet for a hole.
ds_f_dim_in_arrayFind dimension in array.
ds_fitgaussFit a gaussian to a profile.
ds_gausscurveWrite gaussian curve to an array.
ds_convert_atomicConvert an atomic datum to a double precision value.
ds_get_coordinateGet a co-ordinate along a dimension.
ds_convert_coordinatesConvert co-ordinate values for a dimension.
ds_get_element_offsetCalculate the offset of the start of a data element in a packet.
ds_get_packet_sizeCalculate size in bytes of a packet.
ds_get_array_sizeCalculate the number of co-ordinate points in an array.
ds_packet_all_dataTest if packet contains only atomic data elements.
ds_element_is_atomicTest if an element is atomic.
ds_element_is_namedTest if an element is a named data type.
ds_element_is_legalTest if an element is legal.
ds_get_array_offsetCompute offset of a co-ordinate in an array.
ds_get_coord_numGet index of a co-ordinate along a dimension.
ds_get_elementConvert an atomic datum to a double precision complex value.
ds_get_elementsConvert atomic data values to double precision complex values.
ds_get_coordinate_arrayGet co-ordinate array for a dimension.
ds_element_is_complexTest if the type of an element is complex or not.
ds_get_scattered_elementsConvert scattered atomic data to double precision complex values.
ds_can_transfer_element_as_blockTest if an element can be transferred in one block.
ds_can_transfer_packet_as_blockTest if a packet can be transferred in one block.
ds_can_swaptransfer_elementTest if an element can be swapped and transferred in one block.
ds_get_handle_in_packetFind sub-structure in a general data structure.
ds_get_handle_in_arrayFind sub-structure in a multi-dimensional array.
ds_get_handle_in_listFind sub-structure in a linked list.
ds_history_append_stringAdd a history string to a Karma data structure.
ds_history_copyCopy history information.
ds_list_insertInsert an entry into the fragmented section of a linked list.
ds_list_appendAppend an entry to a linked list.
ds_list_deleteDelete an entry from the fragmented section of a linked list.
ds_list_unfragmentUnfragment a linked list.
ds_list_fragmentFragment a linked list.
ds_format_unitFormat a unit string.
ds_format_valueFormat a data value into a string.
ds_remove_named_elementsRemove a list of named elements from a packet.
ds_remove_dim_descRemove dimension from an array.
ds_append_dim_descAppend a dimension to an array.
ds_prepend_dim_descPrepend a dimension to an array.
ds_compute_array_offsetsCompute array address offsets for each dimension in an array.
ds_remove_tiling_infoRemove any tiling information from an array descriptor.
ds_append_gen_structAppend a general data structure to a multi_array structure.
ds_autotile_arrayChoose tiling scheme automatically.
ds_put_elementWrite out an element of data.
ds_put_elementsConvert array of double precision complex data to atomic data.
ds_put_element_many_timesWrite a double precision complex value to atomic data many times.
ds_put_named_elementUpdate a named element in a specified packet.
ds_reorder_arrayRe-order a multi-dimensional array.
ds_foreach_occurrenceRecursively traverse a data structure, searching for an item.
ds_foreach_in_arrayRecursively traverse an array, searching for an item.
ds_foreach_in_listRecursively traverse a linked list, searching for an item.
ds_traverse_and_processRecursively traverse a pair of data structures.
ds_traverse_arrayRecursively traverse a pair of arrays.
ds_traverse_listRecursively traverse a pair of linked lists.

Prototype Functions

ds_PROTO_foreach_funcProcess an occurrence of an item in a data structure.
ds_PROTO_traverse_functionProcess an occurrence of a divergence between two data structures
ds_PROTO_event_funcProcess an event.

Tables

ds_COMPLEX_CONVERSIONSList of complex conversion types
ds_KARMA_DATA_TYPESList of Karma data types
ds_IDENT_TABLEList of identification codes
ds_SEARCH_BIASESList of co-ordinate search biases
ds_HANDLE_TYPESList of handle types
ds_PARENT_TYPESList 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:

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:

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:

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:

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:

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:

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


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:

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:

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:

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:

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:

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


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:

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


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:

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


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:

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


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:

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:

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:

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:

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


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:

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


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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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


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:

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:

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:


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:

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:


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

Recursively compare two packet descriptors.

Parameters:

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:

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:

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


EXPERIMENTAL FUNCTION: subject to change without notice

void 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 *buffer_sizes, uaddr size_stride, double **x0_arr, double **y0_arr, double **x1_arr, double **y1_arr, uaddr *num_segments, uaddr seg_stride)

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:

Returns: Nothing.
Multithreading Level: Unsafe


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

Copy a packet.

Parameters:

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


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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

Returns: Nothing.
Multithreading Level: Unsafe


void ds_dealloc_list_entries (CONST 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 NOT deallocated.

Parameters:

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:

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:

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:

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:

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:

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


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)

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 contains many atomic data.

Parameters:

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


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:

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


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:

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)

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:

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


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:

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:

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:

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


EXPERIMENTAL FUNCTION: subject to change without notice

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

Register a multi_array event function.

Parameters:

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:

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:

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:

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


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:

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:

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:

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:


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:

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:

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:


EXPERIMENTAL FUNCTION: subject to change without notice

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

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

Parameters:

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


EXPERIMENTAL FUNCTION: subject to change without notice

void ds_gausscurve (CONST 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:

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:

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:

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:

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:

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:

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:

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


flag ds_packet_all_data (CONST packet_desc *pack_desc)

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

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:


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:

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:


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:

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:


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:

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


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

Copy history information.

Parameters:

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:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


void ds_list_append (list_header *list_head, list_entry *entry)

Append an entry to a linked list.

Parameters:

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:

Returns: Nothing.
Multithreading Level: Unsafe


flag ds_list_unfragment (packet_desc *list_desc, list_header *list_head)

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

Parameters:

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


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:

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


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)

Format a unit string.

Parameters:

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, CONST packet_desc *pack_desc, CONST char *packet)

Format a data value into a string.

Parameters:

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:

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:

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:

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:

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:

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:

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:

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 opimum tiling scheme for an array.

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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


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

Process an occurrence of a divergence between two data structures

Parameters:

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:

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


Tables


ds_COMPLEX_CONVERSIONS

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


ds_KARMA_DATA_TYPES

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


ds_IDENT_TABLE

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


ds_SEARCH_BIASES

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


ds_HANDLE_TYPES

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


ds_PARENT_TYPES

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


Back to Karma Home Page
Contact: Richard Gooch
Web Development: Ariel Internet Services