Functions
CDSVar *	dsproc_clone_var (CDSVar src_var, CDSGroup dataset, const char var_name, CDSDataType data_type, const char *dim_names, int copy_data)
	Create a clone of an existing variable.
CDSVar *	dsproc_define_var (CDSGroup dataset, const char name, CDSDataType type, int ndims, const char *dim_names, const char long_name, const char standard_name, const char units, void valid_min, void valid_max, void missing_value, void fill_value)
	Define a new variable in an existing dataset.
int	dsproc_delete_var (CDSVar *var)
	Delete a variable from a dataset.
CDSVar *	dsproc_get_bounds_var (CDSVar *coord_var)
	Get the boundary variable for a coordinate variable.
CDSVar *	dsproc_get_coord_var (CDSVar *var, int dim_index)
	Get the coordinate variable for a variable's dimension.
int	dsproc_get_dataset_vars (CDSGroup dataset, const char var_names, int required, CDSVar vars, CDSVar qc_vars, CDSVar **aqc_vars)
	Get variables and companion QC variables from a dataset.
CDSVar *	dsproc_get_metric_var (CDSVar var, const char metric)
	Get a companion metric variable for a variable.
CDSVar *	dsproc_get_output_var (int ds_id, const char *var_name, int obs_index)
	Get a variable from an output dataset.
CDSVar *	dsproc_get_qc_var (CDSVar *var)
	Get the companion QC variable for a variable.
CDSVar *	dsproc_get_retrieved_var (const char *var_name, int obs_index)
	Get a primary variable from the retrieved data.
CDSVar *	dsproc_get_transformed_var (const char *var_name, int obs_index)
	Get a primary variable from the transformed data.
CDSVar *	dsproc_get_trans_coordsys_var (const char coordsys_name, const char var_name, int obs_index)
	Get a variable from a transformation coordinate system.
CDSVar *	dsproc_get_var (CDSGroup dataset, const char name)
	Get a variable from a dataset.
const char *	dsproc_var_name (CDSVar *var)
	Returns the variable name.
size_t	dsproc_var_sample_count (CDSVar *var)
	Returns the number of samples in a variable's data array.
size_t	dsproc_var_sample_size (CDSVar *var)
	Returns the sample size of a variable.

Detailed Description

Function Documentation

CDSVar* dsproc_clone_var	(	CDSVar *	src_var,
		CDSGroup *	dataset,
		const char *	var_name,
		CDSDataType	data_type,
		const char **	dim_names,
		int	copy_data
	)

Create a clone of an existing 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:

src_var	- pointer to the source variable to clone
dataset	- dataset to create the new variable in, or NULL to create the variable in the same dataset the source variable belongs to.
var_name	- name to use for the new variable, or NULL to use the source variable name.
data_type	- data type to use for the new variable, or CDS_NAT to use the same data type as the source variable.
dim_names	- pointer to the list of corresponding dimension names in the dataset the new variable will be created in, or NULL if the dimension names are the same.
copy_data	- flag indicating if the data should be copied, (1 == TRUE, 0 == FALSE)

Returns:

pointer to the new variable
NULL if:
- the variable already exists in the dataset
- a memory allocation error occurred

Definition at line 288 of file dsproc_dataset_vars.c.

CDSVar* dsproc_define_var	(	CDSGroup *	dataset,
		const char *	name,
		CDSDataType	type,
		int	ndims,
		const char **	dim_names,
		const char *	long_name,
		const char *	standard_name,
		const char *	units,
		void *	valid_min,
		void *	valid_max,
		void *	missing_value,
		void *	fill_value
	)

Define a new variable in an existing dataset.

This function will define a new variable with all standard attributes. Any of the attribute values can be NULL to indicate that the attribute should not be created.

Description of Attributes:

long_name: This is a one line description of the variable and should be suitable to use as a plot title for the variable.

standard_name: This is defined in the CF Convention and describes the physical quantities being represented by the variable. Please refer to the "CF Standard Names" section of the CF Convention for the table of standard names.

units: This is the units string to use for the variable and must be recognized by the UDUNITS-2 libary.

valid_min: The smallest value that should be considered to be a valid data value. The specified value must be the same data type as the variable.

valid_max: The largest value that should be considered to be a valid data value. The specified value must be the same data type as the variable.

missing_value: This comes from an older NetCDF convention and has been used by ARM for almost 2 decades. The specified value must be the same data type as the variable.

_FillValue: Most newer conventions specify the use of _FillValue over missing_value. The value of this attribute is also recognized by the NetCDF library and will be used to initialize the data values on disk when the variable is created. Tools like ncdump will also display fill values as _ so they can be easily identified in a text dump. The libdsproc3 library allows you to use both missing_value and _FillValue and they do not need to be the same. The specified value must be the same data type as 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:

dataset	- pointer to the dataset
name	- name of the variable
type	- data type of the variable
ndims	- number of variable dimensions
dim_names	- array of pointers to the dimension names
long_name	- string to use for the long_name attribute
standard_name	- string to use for the standard_name attribute
units	- string to use for the units attribute
valid_min	- void pointer to the valid_min
valid_max	- void pointer to the valid_max
missing_value	- void pointer to the missing_value
fill_value	- void pointer to the _FillValue

Returns:

pointer to the new variable
NULL if an error occurred

Definition at line 443 of file dsproc_dataset_vars.c.

int dsproc_delete_var ( CDSVar * var )

Delete a variable from a dataset.

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:

1 if the variable was deleted (or the input var was NULL)
0 if:
- the variable is locked
- the group is locked

Definition at line 500 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_bounds_var ( CDSVar * coord_var )

Get the boundary variable for a coordinate variable.

Parameters:

coord_var - pointer to the coordinate variable

Returns:

pointer to the boundary variable
NULL if not found

Definition at line 521 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_coord_var	(	CDSVar *	var,
		int	dim_index
	)

Get the coordinate variable for a variable's dimension.

Parameters:

var	- pointer to the variable
dim_index	- index of the dimension

Returns:

pointer to the coordinate variable
NULL if not found

Definition at line 538 of file dsproc_dataset_vars.c.

int dsproc_get_dataset_vars	(	CDSGroup *	dataset,
		const char **	var_names,
		int	required,
		CDSVar ***	vars,
		CDSVar ***	qc_vars,
		CDSVar ***	aqc_vars
	)

Get variables and companion QC variables from a dataset.

If nvars is 0 or var_names is NULL, the output vars array will contain the pointers to the variables that are not companion QC variables. In this case the variables in the vars array will be in the same order they appear in the dataset. The following time and location variables will be excluded from this array:

base_time
time_offset
time
time_bounds
lat
lon
alt

If nvars and var_names are specified, the output vars array will contain an entry for every variable in the var_names list, and will be in the specified order. Variables that are not found in the dataset will have a NULL value if the required flag is set to 0. If the required flag is set to 1 and a variable does not exist, an error will be generated.

If the qc_vars argument is not NULL it will contain the pointers to the companion qc_ variables. Likewise, if the aqc_vars argument is not NULL it will contain the pointers to the companion aqc_ variables. If a companion QC variable does not exist for a variable, the corresponding entry in the QC array will be NULL.

The memory used by the returned arrays belongs to a 'dsproc_user_...' CDSVarGroup defined in the dataset and must NOT be freed by the calling process.

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 dataset
var_names	- NULL terminated list of variable names
required	- specifies if all variables in the names list are required
vars	- output: pointer to the array of variables
qc_vars	- output: pointer to the array of companion qc_ variables
aqc_vars	- output: pointer to the array of companion aqc_ variables

Returns:

length of the output arrays
-1 if an error occurred

Definition at line 594 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_metric_var	(	CDSVar *	var,
		const char *	metric
	)

Get a companion metric variable for a variable.

Known metrics at the time of this writing (so there may be others):

"frac": the fraction of available input values used
"std": the standard deviation of the calculated value

Parameters:

var	- pointer to the variable
metric	- name of the metric

Returns:

pointer to the metric variable
NULL if not found

Definition at line 847 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_output_var	(	int	ds_id,
		const char *	var_name,
		int	obs_index
	)

Get a variable from an output dataset.

The obs_index should always be zero unless observation based processing is being used. This is because all input observations should have been merged into a single observation in the output datasets.

Parameters:

ds_id	- output datastream ID
var_name	- variable name
obs_index	- the index of the obervation to get the dataset for

Returns:

pointer to the output variable
NULL if it does not exist

Definition at line 873 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_qc_var ( CDSVar * var )

Get the companion QC variable for a variable.

Parameters:

var	- pointer to the variable

Returns:

pointer to the QC variable
NULL if not found

Definition at line 896 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_retrieved_var	(	const char *	var_name,
		int	obs_index
	)

Get a primary variable from the retrieved data.

This function will find a variable in the retrieved data that was explicitly requested by the user in the retriever definition.

The obs_index is used to specify which observation to pull the variable from. This value will typically be zero unless this function is called from a post_retrieval_hook() function, or the process is using observation based processing. In either of these cases the retrieved data will contain one "observation" for every file the data was read from on disk.

It is also possible to have multiple observations in the retrieved data when a pre_transform_hook() is called if a dimensionality conflict prevented all observations from being merged.

Parameters:

var_name	- variable name
obs_index	- the index of the obervation to get the variable from

Returns:

pointer to the retrieved variable
NULL if not found

Definition at line 930 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_trans_coordsys_var	(	const char *	coordsys_name,
		const char *	var_name,
		int	obs_index
	)

Get a variable from a transformation coordinate system.

Unlike the dsproc_get_transformed_var() function, this function will find any variable in the specified transformation coordinate system.

The obs_index is used to specify which observation to pull the variable from. This value will typically be zero unless the process is using observation based processing. If this is the case the transformed data will contain one "observation" for every file the data was read from on disk.

Parameters:

coordsys_name	- coordinate system name
var_name	- variable name
obs_index	- the index of the obervation to get the variable from

Returns:

pointer to the transformed variable
NULL if not found

Definition at line 1046 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_transformed_var	(	const char *	var_name,
		int	obs_index
	)

Get a primary variable from the transformed data.

This function will find a variable in the transformed data that was explicitly requested by the user in the retriever definition.

The obs_index is used to specify which observation to pull the variable from. This value will typically be zero unless the process is using observation based processing. If this is the case the transformed data will contain one "observation" for every file the data was read from on disk.

Parameters:

var_name	- variable name
obs_index	- the index of the obervation to get the variable from

Returns:

pointer to the transformed variable
NULL if not found

Definition at line 981 of file dsproc_dataset_vars.c.

CDSVar* dsproc_get_var	(	CDSGroup *	dataset,
		const char *	name
	)

Get a variable from a dataset.

Parameters:

dataset	- pointer to the dataset
name	- name of the variable

Returns:

pointer to the variable
NULL if the variable does not exist

Definition at line 1112 of file dsproc_dataset_vars.c.

const char* dsproc_var_name ( CDSVar * var )

Returns the variable name.

The returned name belongs to the variable structure and must not be freed or altered by the calling process.

Parameters:

var	- pointer to the variable

Returns:

pointer to the variable name
NULL if the specified variable is NULL

Definition at line 1564 of file dsproc_dataset_vars.c.

size_t dsproc_var_sample_count ( CDSVar * var )

Returns the number of samples in a variable's data array.

The sample_count for a variable is the number of samples stored along the variable's first dimension.

Parameters:

var	- pointer to the variable

Returns:: number of samples in the variable's data array

Definition at line 1583 of file dsproc_dataset_vars.c.

size_t dsproc_var_sample_size ( CDSVar * var )

Returns the sample size of a variable.

Variables with less than 2 dimensions will always have a sample_size of 1. The sample_size for variables with 2 or more dimensions is the product of all the dimension lengths starting with the 2nd dimension.

Parameters:

var	- pointer to the variable

Returns:: sample size of the variable

Definition at line 1603 of file dsproc_dataset_vars.c.

Functions

Detailed Description

Function Documentation