Dataset Variable Data

Functions
void *	dsproc_alloc_var_data (CDSVar *var, size_t sample_start, size_t sample_count)
	Allocate memory for a variable's data array.
void *	dsproc_alloc_var_data_index (CDSVar *var, size_t sample_start, size_t sample_count)
	Allocate memory for a variable's data array.
void *	dsproc_get_var_data_index (CDSVar *var)
	Get a data index for a multi-dimensional variable.
void *	dsproc_get_var_data (CDSVar *var, CDSDataType type, size_t sample_start, size_t *sample_count, void *missing_value, void *data)
	Get a copy of the data from a dataset variable.
int	dsproc_get_var_missing_values (CDSVar *var, void **values)
	Get the missing values for a CDS Variable.
void *	dsproc_init_var_data (CDSVar *var, size_t sample_start, size_t sample_count, int use_missing)
	Initialize the data values for a dataset variable.
void *	dsproc_init_var_data_index (CDSVar *var, size_t sample_start, size_t sample_count, int use_missing)
	Initialize the data values for a dataset variable.
int	dsproc_set_bounds_data (CDSGroup *dataset, size_t sample_start, size_t sample_count)
	Set cell boundary data for all coordinate variables in a dataset.
int	dsproc_set_bounds_var_data (CDSVar *coord_var, size_t sample_start, size_t sample_count)
	Set cell boundary data values for a dataset variable.
void *	dsproc_set_var_data (CDSVar *var, CDSDataType type, size_t sample_start, size_t sample_count, void *missing_value, void *data)
	Set the data values for a dataset variable.

---

Detailed Description

---

Function Documentation

void* dsproc_alloc_var_data	(	CDSVar *	var,
		size_t	sample_start,
		size_t	sample_count
	)

Allocate memory for a variable's data array.

This function will allocate memory as necessary to ensure that the variable's data array is large enough to store another sample_count samples starting from sample_start.

The data type of the returned array will be the same as the variable’s data type. It is the responsibility of the calling process to cast the returned array into the proper data type. If the calling process does not know the data type of the variable, it can store the data in an array of a known type and then use the dsproc_set_var_data() function to cast this data into the variables data array. In this case the memory does not need to be preallocated and this function is not needed.

The data array returned by this function belongs to the variable and will be freed when the variable is destroyed. The calling process must not attempt to free this memory.

For multi-dimensional variables the data array is stored linearly in memory with the last dimension varying the fastest. See the dsproc_alloc_var_data_index() and/or dsproc_get_var_data_index() functions to get a "data index" into this array.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

var	- pointer to the variable
sample_start	- start sample (0 based indexing)
sample_count	- number of new samples

Returns:

• pointer to the specifed start sample in the variable's data array
• NULL if:
  • one of the variable's static dimensions has 0 length
  • the variable has no dimensions, and sample_start is not equal to 0 or sample_count is not equal to 1.
  • the first variable dimension is not unlimited, and sample_start + sample_count would exceed the dimension length.
  • a memory allocation error occurred

Definition at line 197 of file dsproc_dataset_vars.c.

void* dsproc_alloc_var_data_index	(	CDSVar *	var,
		size_t	sample_start,
		size_t	sample_count
	)

Allocate memory for a variable's data array.

This function is the same as dsproc_alloc_var_data() except that it returns a data index starting at the specified start sample (see dsproc_get_var_data_index()). For variables that have less than two dimensions this function is identical to dsproc_alloc_var_data(). It is up to the calling process to cast the return value of this function into the proper data type.

The data index returned by this function belongs to the variable and will be freed when the variable is destroyed. The calling process must not attempt to free this memory.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

var	- pointer to the variable
sample_start	- start sample (0 based indexing)
sample_count	- number of new samples

Returns:

• the data index into the variable's data array starting at the specified start sample
• NULL if:
  • one of the variable's static dimensions has 0 length
  • the variable has no dimensions, and sample_start is not equal to 0 or sample_count is not equal to 1.
  • the first variable dimension is not unlimited, and sample_start + sample_count would exceed the dimension length.
  • a memory allocation error occurred

Definition at line 245 of file dsproc_dataset_vars.c.

void* dsproc_get_var_data	(	CDSVar *	var,
		CDSDataType	type,
		size_t	sample_start,
		size_t *	sample_count,
		void *	missing_value,
		void *	data
	)

Get a copy of the data from a dataset variable.

This function will get the data from a variable casted into the specified data type. All missing values used in the data will be converted to a single missing value appropriate for the requested data type. The missing value used will be the first value returned by cds_get_var_missing_values() if that value is within the range of the requested data type, otherwise, the default fill value for the requested data type will be used.

Memory will be allocated for the returned data array if the output array is NULL. In this case the calling process is responsible for freeing the allocated memory. If an output data array is specified it must be large enough to hold (sample_count * cds_var_sample_size(var)) elements.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

var	- pointer to the variable
type	- data type of the output missing_value and data array
sample_start	- start sample (0 based indexing)
sample_count	- pointer to the sample_count input: length of the output array ignored if the output array is NULL output: number of samples returned 0 if no data for sample_start (size_t)-1 if a memory allocation error occurs
missing_value	- output: missing value
data	- pointer to the output data array or NULL to dynamically allocate the memory needed.

Returns:

• pointer to the output data array
• NULL if:
  • the pointer to the variable was NULL
  • the variable has no data for sample_start (sample_count == 0)
  • a memory allocation error occurs (sample_count == (size_t)-1)

Definition at line 1203 of file dsproc_dataset_vars.c.

void* dsproc_get_var_data_index

(

CDSVar *

var

)

Get a data index for a multi-dimensional variable.

This function will return a data index that can be used to access the data in a variable using the traditional x[i][j][k] syntax. It is up to the calling process to cast the return value of this function into the proper data type.

Note: If the variable has less than 2 dimensions, the pointer to the variable’s data array will be returned.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

var	- pointer to the variable

Returns:

• the data index into the variable’s data array
• NULL if:
  • the pointer to the variable was NULL
  • no data has been stored in the variable (var->sample_count == 0)
  • a memory allocation error occurs

Definition at line 1144 of file dsproc_dataset_vars.c.

int dsproc_get_var_missing_values	(	CDSVar *	var,
		void **	values
	)

Get the missing values for a CDS Variable.

This function will return an array containing all values specified by the missing_value and _FillValue attributes (in that order), and will be the same data type as the variable. If the _FillValue attribute does not exist but a default fill value has been defined, it will be used instead.

The memory used by the output array of missing values is dynamically allocated. It is the responsibility of the calling process to free this memory when it is no longer needed.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

var	- pointer to the variable
values	- output: pointer to the array of missing values, the data type of this array will be the same as the variable

Returns:

• number of missing values
• 0 if there are no missing or fill values
• -1 if a memory allocation error occurs

Definition at line 1254 of file dsproc_dataset_vars.c.

void* dsproc_init_var_data	(	CDSVar *	var,
		size_t	sample_start,
		size_t	sample_count,
		int	use_missing
	)

Initialize the data values for a dataset variable.

This function will make sure enough memory is allocated for the specified samples and initializing the data values to either the variable's missing value (use_missing == 1), or 0 (use_missing == 0).

The search order for missing values is:

• missing_value attribute
• _FillValue attribute
• variable's default missing value

If the variable does not have any missing or fill values defined the default fill value for the variable's data type will be used and the default fill value for the variable will be set.

If the specified start sample is greater than the variable's current sample count, the hole between the two will be filled with the first missing or fill value defined for the variable.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

var	- pointer to the variable
sample_start	- start sample of the data to initialize (0 based indexing)
sample_count	- number of samples to initialize
use_missing	- flag indicating if the variables missing value should be used (1 == TRUE, 0 == fill with zeros)

Returns:

• pointer to the specifed start sample in the variable's data array
• NULL if:
  • the specified sample count is zero
  • one of the variable's static dimensions has 0 length
  • the variable has no dimensions, and sample_start is not equal to 0 or sample_count is not equal to 1.
  • the first variable dimension is not unlimited, and sample_start + sample_count would exceed the dimension length.
  • a memory allocation error occurred

Definition at line 1311 of file dsproc_dataset_vars.c.

void* dsproc_init_var_data_index	(	CDSVar *	var,
		size_t	sample_start,
		size_t	sample_count,
		int	use_missing
	)

Initialize the data values for a dataset variable.

This function behaves the same as dsproc_init_var_data() except that it returns a data index starting at the specified start sample, see dsproc_get_var_data_index() for details. For variables that have less than two dimensions this function is identical to dsproc_init_var_data().

The data index returned by this function belongs to the CDS variable and will be freed when the variable is destroyed. The calling process must not attempt to free this memory.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

var	- pointer to the variable
sample_start	- start sample of the data to initialize (0 based indexing)
sample_count	- number of samples to initialize
use_missing	- flag indicating if the variables missing value should be used (1 == TRUE, 0 == fill with zeros)

Returns:

• the data index into the variables data array starting at the specified start sample.
• NULL if:
  • the specified sample count is zero
  • one of the variable's static dimensions has 0 length
  • the variable has no dimensions, and sample_start is not equal to 0 or sample_count is not equal to 1.
  • the first variable dimension is not unlimited, and sample_start + sample_count would exceed the dimension length.
  • a memory allocation error occurred

Definition at line 1362 of file dsproc_dataset_vars.c.

int dsproc_set_bounds_data	(	CDSGroup *	dataset,
		size_t	sample_start,
		size_t	sample_count
	)

Set cell boundary data for all coordinate variables in a dataset.

This function will call dsproc_set_bounds_var_data() for all variables in the specified dataset that have a bounds attribute defined.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

dataset	- pointer to the CDS variable
sample_start	- start sample along the unlimited dimension (0 based indexing)
sample_count	- number of samples along the unlimited dimension (0 for all available samples)

Returns:

• 1 if successful
• 0 if an error occurred.

Definition at line 1399 of file dsproc_dataset_vars.c.

int dsproc_set_bounds_var_data	(	CDSVar *	coord_var,
		size_t	sample_start,
		size_t	sample_count
	)

Set cell boundary data values for a dataset variable.

This function can only be used to create the cell boundary data values for regular grids and requires:

• The variable has a bounds attribute defined that specifies the name of the boundary variable.

• The boundary variable has a bound_offsets attribute defined that specifies the cell boundary offsets from the data values.

• The number of boundary variable dimensions is one greater than than the number of variable dimensions.

• The boundary variable and bound_offsets attribute have the same data type as the variable.

• The bound_offsets attribute has the same length as the last dimension of the boundary variable.

Parameters:

coord_var	- pointer to the coordinate variable
sample_start	- start sample (0 based indexing)
sample_count	- number of samples (0 for all available samples)

Returns:

• 1 if successful
• 0 if the bounds and/or bound_offsets attributes are not defined, or the variable does not have any data for the specified sample_start.
• -1 if an error occurred.

Definition at line 1468 of file dsproc_dataset_vars.c.

void* dsproc_set_var_data	(	CDSVar *	var,
		CDSDataType	type,
		size_t	sample_start,
		size_t	sample_count,
		void *	missing_value,
		void *	data
	)

Set the data values for a dataset variable.

This function will set the data values of a variable by casting the values in the input data array into the data type of the variable. All missing values in the input data array will be converted to the first missing value used by the variable as returned by cds_get_var_missing_values(). If the variable does not have a missing_value or _FillValue attribute defined, the default fill value for the variable's data type will be used.

For multi-dimensional variables, the specified data array must be stored linearly in memory with the last dimension varying the fastest.

If an error occurs in this function it will be appended to the log and error mail messages, and the process status will be set appropriately.

Parameters:

var	- pointer to the variable
type	- data type of the input missing_value and data array
sample_start	- start sample of the new data (0 based indexing)
sample_count	- number of new samples
missing_value	- pointer to the missing value used in the data array, or NULL if the data does not contain any missing values
data	- pointer to the input data array

Returns:

• pointer to the specifed start sample in the variable's data array
• NULL if:
  • one of the variable's static dimensions has 0 length
  • the variable has no dimensions, and sample_start is not equal to 0 or sample_count is not equal to 1.
  • the first variable dimension is not unlimited, and sample_start + sample_count would exceed the dimension length.
  • a memory allocation error occurred

Definition at line 1516 of file dsproc_dataset_vars.c.