BEAT-II Record

Typedefs
typedef enum beatl2_BasicType_enum	beatl2_BasicType
typedef struct beatl2_Record_struct	beatl2_Record
Enumerations
enum	beatl2_BasicType_enum {   beatl2_uint8,   beatl2_int32,   beatl2_double,   beatl2_string_ptr }
Functions
beatl2_Record *	beatl2_record_create (void)
void	beatl2_record_remove (beatl2_Record *record)
int	beatl2_record_get_num_fields (const beatl2_Record *record)
int	beatl2_record_get_field_index_from_name (const beatl2_Record *record, const char *field_name)
int	beatl2_record_add_field (beatl2_Record *record, const char *field_name, beatl2_BasicType type, int num_dims, long dim[])
int	beatl2_record_add_string_field (beatl2_Record *record, const char *field_name, const char *str)
int	beatl2_record_remove_field (beatl2_Record *record, int index)
int	beatl2_record_attach_field (beatl2_Record *record, const char *field_name, beatl2_BasicType type, int num_dims, long dim[], beatl2_DataType field_data)
int	beatl2_record_detach_field (beatl2_Record *record, int index, beatl2_DataType *field_data)
int	beatl2_record_get_field_name (const beatl2_Record *record, int index, const char **field_name)
int	beatl2_record_get_field_type (const beatl2_Record *record, int index, beatl2_BasicType *type)
int	beatl2_record_get_field_dim (const beatl2_Record *record, int index, int *num_dims, long dim[])
int	beatl2_record_get_field_num_elements (const beatl2_Record *record, int index, long *num_elements)
int	beatl2_record_get_field_data (const beatl2_Record *record, int index, beatl2_DataType *field_data)
int	beatl2_record_set_string_data_element (beatl2_DataType field_data, long array_index, const char *str)
int	beatl2_record_change_field_name (beatl2_Record *record, int index, const char *field_name)
int	beatl2_record_append_data_to_field (beatl2_Record *record, int index, int num_dims, long dim[], beatl2_DataType data)
int	beatl2_record_append_field_to_field_by_index (beatl2_Record *record_1, int index_1, const beatl2_Record *record_2, int index_2)
int	beatl2_record_append_field_to_field_by_name (beatl2_Record *record_1, const char *field_name_1, const beatl2_Record *record_2, const char *field_name_2)
int	beatl2_record_reshape_field_data (beatl2_Record *record, int index, int dim_id, long num_dim_elements, const long *dim_element_id)
int	beatl2_record_filter_field_data (beatl2_Record *record, int index, const uint8_t *dim_filter)

---

Detailed Description

BEAT-II records are generic records that can be dynamically changed. Although this type of record was made for BEAT-II its genericity allows for a much wider use. Each BEAT-II record consists of a dynamically growable/shrinkable list of fields. Each record field can hold a multidimensional array of data of a certain basic type. The basic types that are supported by BEAT-II are beatl2_uint8 (an 8 bits unsigned integer), beatl2_int32 (a 32 bits signed integer), beatl2_double (a double precision floating point), and beatl2_string_ptr (a null terminated 'char *'). Each field in a record can be identified by either its unique name, or its unique index (this is a sequence number, which means that the first field will allways have index 0, the second index 1, etc.). Most functions require the index as input parameter, so if you have a field name you will first have to convert it to an index with the beatl2_record_get_field_index_from_name() function.

Field names have to follow a certain format in order to be valid. They should start with an alphabetical character ('a'-'z', 'A'-'Z') and be followed by a combination of zero or more alphanumerical characters ('a'-'z', 'A'-'Z', '0'-'9') and underscore characters ('_'). The length of a fieldname is in principle unlimited, but if it is long you may encounter problems when using the BEAT-II record from IDL or MATLAB or when trying to export the record to HDF4/HDF5/netCDF.

When you first create a record with beatl2_record_create() the list of fields will be empty. You can expand the number of fields by calling beatl2_record_add_field(). You should provide a field name, a basic type and the array dimensions (you can use a number of dimensions of 0 for scalar data) as arguments to this function. The field creation function will automatically allocate a large enough data block for you to hold the field data. You can retrieve a pointer to this data block with the beatl2_record_get_field_data() function which you can then use to fill the data block with the appropriate data.

When you are finished you can either remove the complete record and all its fields with the beatl2_record_remove() function or just remove specific fields with beatl2_record_remove_field(). An important thing to notice is that fields with a basic data type of beatl2_string_ptr use dynamically allocatable data as a basic type. This means that beatl2_string_ptr array elements need to be allocated and freed (something that is not necessary for data of type beatl2_uint8, beatl2_int32 or beatl2_double). The memory handling scheme that was chosen for this data type is that you as user are responsible for allocating memory for the beatl2_string_ptr data elements and that BEAT-II will take care of freeing the char * data when you remove a field or the complete record. This means that you should take care that you do not free the char * data you put in a field, or that you put constant string values (which can not be freed) in the fields data block.

---

Typedef Documentation

beatl2_BasicType

BEAT-II Basic Type

beatl2_Record

BEAT-II Generic Record Type

---

Enumeration Type Documentation

enum beatl2_BasicType_enum

BEAT-II Basic Type

Enumerator:

beatl2_uint8	unsigned integer (8 bit)
beatl2_int32	signed integer (32 bit)
beatl2_double	double precision floating point
beatl2_string_ptr	string (null terminated 'char *')

---

Function Documentation

int beatl2_record_add_field	(	beatl2_Record *	record,
		const char *	field_name,
		beatl2_BasicType	type,
		int	num_dims,
		long	dim[]
	)

Add a field to an existing BEAT-II record. This function will automatically allocate a data block for this field that can hold the total amount of elements. The data block will also be zeroed (each byte will be set to 0). The string value of field_name will be duplicated and the duplicate will be made lower case. This function will return an error if you try to add a field with a fieldname that already exists in the record. It is not allowed to create a field with 0 elements.

Parameters:

record	Pointer to a valid BEAT-II record.
field_name	Null terminated string containing the field name.
type	Basic data type for the field.
num_dims	Number of dimensions of the field (0 <= num_dims < BEATL2_MAX_NUM_DIMS).
dim	Dimensions of the field.

Returns:

• >=0, Field index of the newly created field.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_add_string_field	(	beatl2_Record *	record,
		const char *	field_name,
		const char *	str
	)

Add a field containing a single string_ptr element to an existing BEAT-II record . This function will automatically call beatl2_record_add_field() to add a field with one string_ptr element to the record. The string str will then be duplicated and this duplicate is used to initialize the data block of the newly created field.

Parameters:

record	Pointer to a valid BEAT-II record.
field_name	Null terminated string containing the field name.
str	Null terminated string containing the value for the sole data element of the field.

Returns:

• >=0, Field index of the newly created field.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_append_data_to_field	(	beatl2_Record *	record,
		int	index,
		int	num_dims,
		long	dim[],
		beatl2_DataType	data
	)

Append data to a record field. This function will enlarge the field data of the current field so that it can also hold the new data. Appending can only be done in the 'main' (i.e. first) dimension. The dimension will be enlarged and the previous field data and the new data will be concatenated. The num_dims and the dimensions other than the first dimension need to be the same for the field and the appended data. Also the basic data types of the data in data and the data of the field of record need to be the same.

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index (0 <= index < number of fields).
num_dims	Number of dimensions of the data to be appended.
dim	Dimensions of the data to be appended.
data	Pointer to the data block of the data to be appended.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_append_field_to_field_by_index	(	beatl2_Record *	record_1,
		int	index_1,
		const beatl2_Record *	record_2,
		int	index_2
	)

Append data of one record field to the data block of another a record field. This function will call beatl2_record_append_data_to_field() with record_1 and the data of the field of record_2.

Parameters:

record_1	Pointer to the BEAT-II record for the field should be appended.
index_1	Field index for record_1 (0 <= index < number of fields).
record_2	Pointer to the BEAT-II record where the data to be appended comes from.
index_2	Field index for record_2 (0 <= index < number of fields).

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_append_field_to_field_by_name	(	beatl2_Record *	record_1,
		const char *	field_name_1,
		const beatl2_Record *	record_2,
		const char *	field_name_2
	)

Append data of one record field to the data block of another a record field. This function will call beatl2_record_append_data_to_field() with record_1 and the data of the field of record_2.

Parameters:

record_1	Pointer to the BEAT-II record with the field that should get the appended data.
field_name_1	Field name of the field in record_1.
record_2	Pointer to the BEAT-II record where the data to be appended comes from.
field_name_2	Field name of the field in record_2.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_attach_field	(	beatl2_Record *	record,
		const char *	field_name,
		beatl2_BasicType	type,
		int	num_dims,
		long	dim[],
		beatl2_DataType	field_data
	)

Add a field to an existing BEAT-II record and provide its field data. This function will add a field to the record, but will not allocate a data block for this field. Instead, it will use the field_data data block for the field data. The record will automatically free this data block (and its string contents in case of a beatl2_string_ptr data type) when the field or record is removed. The data block that is pointed to by field_data should therefore contain data that can be removed with the free() function. The string value of field_name will be duplicated and the duplicate will be made lower case. This function will return an error if you try to add a field with a fieldname that already exists in the record. It is not allowed to create a field with 0 elements.

Parameters:

record	Pointer to a valid BEAT-II record.
field_name	Null terminated string containing the field name.
type	Basic data type for the field.
num_dims	Number of dimensions of the field (0 <= num_dims < BEATL2_MAX_NUM_DIMS).
dim	Dimensions of the field.
field_data	The field data pointer containing the data for this field.

Returns:

• >=0, Field index of the newly created field.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_change_field_name	(	beatl2_Record *	record,
		int	index,
		const char *	field_name
	)

Change the field name of a BEAT-II record field. Just as with beatl2_record_add_field() a duplicate of the string value of field_name will be stored for the field. The new field name will be made all lower case.

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index (0 <= index < number of fields).
field_name	The new field name of the field.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

beatl2_Record* beatl2_record_create

(

void

)

Create a new BEAT-II record. The new record won't contain any fields. You can add fields with beatl2_record_add_field().

Returns:

• >0, Pointer to a BEAT-II record.
• 0, Error occurred (check beatl2_errno).

int beatl2_record_detach_field	(	beatl2_Record *	record,
		int	index,
		beatl2_DataType *	field_data
	)

Remove a field from an existing BEAT-II record without removing its field data. This function will remove the field with field index index from the record, but it will not clean up the contents of the field data pointer. After a successfull detach the user is responsible for cleaning op the field data block (this includes freeing all string elements in a beatl2_string_ptr data block). When you remove a field that was not at the end of the field list all fields that came after the removed field will have their field index reduced by 1. If field_data is NULL this function will ignore the parameter (only use this option if you already have a reference to the field data).

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index of the field to be detached (0 <= index < number of fields).
field_data	Optional pointer to the variable where the field data pointer will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_filter_field_data	(	beatl2_Record *	record,
		int	index,
		const uint8_t *	dim_filter
	)

Filter field data in the first dimension. This function reduces data of a field in the first dimension according to the provided filter. The filter array should be the same length as the first dimension of the field data and contain only 0 (exclude) or 1 (include) values.

Parameters:

record	Pointer to the BEAT-II record with the field that should have its data filtered.
index	Field index for record (0 <= index < number of fields).
dim_filter	An array containing 0 (exclude) and 1 (include) values to indicate which elements should be filtered out.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_get_field_data	(	const beatl2_Record *	record,
		int	index,
		beatl2_DataType *	field_data
	)

Retrieve the field data pointer of a BEAT-II record field. The field_data parameter is a union of differently typed pointers in which a reference to the field data block will be stored. Use the proper union element to access the field data (e.g. use field_data.int32_data[0] to access the first element of a field containing int32 data). Multidimensional data is stored using C ordering (last dimension is the fastest running) inside the field data pointer. The retrieved data pointer will only be valid as long as the field exists. If either the field or the record is removed then the field data will also be removed and the pointer stored in the field_data union will become invalid.

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index (0 <= index < number of fields).
field_data	Pointer to the variable where the field data pointer will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_get_field_dim	(	const beatl2_Record *	record,
		int	index,
		int *	num_dims,
		long	dim[]
	)

Retrieve the dimensions of a BEAT-II record field. The dim array parameter should be large enough to contain at least BEATL2_MAX_NUM_DIMS elements.

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index (0 <= index < number of fields).
num_dims	Pointer to the variable where the number of dimensions will be stored.
dim	Dimension array into which the dimension sizes will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_get_field_index_from_name	(	const beatl2_Record *	record,
		const char *	field_name
	)

Find the field with the given field name in the record and return the field index. Comparison will be case insensitive.

Parameters:

record	Pointer to a valid BEAT-II record.
field_name	Null terminated string containing the field name.

Returns:

• >=0, Field index of the field.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_get_field_name	(	const beatl2_Record *	record,
		int	index,
		const char **	field_name
	)

Retrieve the field name of a BEAT-II record field. The pointer to the field name will only be valid as long as the field exists. If either the field or the record is removed then the field name will also be removed and the pointer will become invalid.

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index (0 <= index < number of fields).
field_name	Pointer to the variable where the field_name will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_get_field_num_elements	(	const beatl2_Record *	record,
		int	index,
		long *	num_elements
	)

Retrieve the number of elements of a BEAT-II record field.

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index (0 <= index < number of fields).
num_elements	Pointer to the variable where the total number of elements will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_get_field_type	(	const beatl2_Record *	record,
		int	index,
		beatl2_BasicType *	type
	)

Retrieve the basic data type of a BEAT-II record field.

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index (0 <= index < number of fields).
type	Pointer to the variable where the basic data type will be stored.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_get_num_fields

(

const beatl2_Record *

record

)

Get the number of fields of a BEAT-II record.

Parameters:

record

Pointer to a valid BEAT-II record.

Returns:

• >=0, Number of fields of the record.
• -1, Error occurred (check beatl2_errno).

void beatl2_record_remove

(

beatl2_Record *

record

)

Remove a BEAT-II record. This function will first remove all fields from the record (similar to calling beatl2_record_remove_field()) and then remove the record from memory.

Parameters:

record

Pointer to a valid BEAT-II record.

int beatl2_record_remove_field	(	beatl2_Record *	record,
		int	index
	)

Remove a field from an existing BEAT-II record. This function will remove the field with field index index from the record. It will automatically clean up any resources that were used by the field. Most importantly if the basic data type of the field was beatl2_string_ptr then for each data element that is not a NULL pointer a free() will be called to remove the char * data element from memory. When you remove a field that was not at the end of the field list all fields that came after the removed field will have their field index reduced by 1.

Parameters:

record	Pointer to a valid BEAT-II record.
index	Field index of the field to be removed (0 <= index < number of fields).

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_reshape_field_data	(	beatl2_Record *	record,
		int	index,
		int	dim_id,
		long	num_dim_elements,
		const long *	dim_element_id
	)

Rearrange field data in one dimension. This function allows data of a field to be rearranged according to the order of the indices in dim_element_id. The number of indices (num_dim_elements) in dim_element_id does not have to correspond to the number of elements in the specified (dim_id) dimension. This means that the data block will grow/shrink when the amount of elements in dim_element_id is larger/smaller (note that the amount of elements can only become larger if elements are duplicated).

Parameters:

record	Pointer to the BEAT-II record with the field that should have its data rearranged.
index	Field index for record (0 <= index < number of fields).
dim_id	The id of the dimension in which the rearrangement should take place.
num_dim_elements	Number of elements in dim_element_id.
dim_element_id	An array containing the ids in dimension dim_id in the new arrangement (ids may occur more than once and the number of ids may be smaller or larger than the length of dimension dim_id).

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).

int beatl2_record_set_string_data_element	(	beatl2_DataType	field_data,
		long	array_index,
		const char *	str
	)

Store a copy of a string at a given position in the field data. Use this function to store a copy of str in the field data for a field. The field data field_data can be retrieved using beatl2_record_get_field_data().

Warning:

This function does not perform any boundary checks on array_index.

Parameters:

field_data	Field data for a field that contains string data.
array_index	Index in the flattened array of strings for the field (use 0 if the field is a zero dimensional array)
str	The string for which a copy should be stored in the field data.

Returns:

• 0, Success.
• -1, Error occurred (check beatl2_errno).