Product

group harp_product

The HARP Products module contains everything related to HARP products.

Typedefs

typedef struct harp_product_struct harp_product

HARP Product typedef

Functions

int harp_product_get_derived_variable(const harp_product *product, const char *name, const char *unit, int num_dimensions, const harp_dimension_type *dimension_type, harp_variable **variable)

Retrieve a new variable based on the set of automatic conversions that are supported by HARP.

If the product already contained a variable with the given name, you will get a copy of that variable (and converted to the specified data type and unit). Otherwise the function will try to create a new variable based on the data found in the product or on available auxiliary data (e.g. built-in climatology). The caller of this function will be responsible for the memory management of the returned variable.

Note
setting unit to NULL returns a variable in the original unit
Note
pointers to axis variables are passed through unmodified.
Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product from which to derive the new variable.

  • name -

    Name of the variable that should be created.

  • unit -

    Unit (optional) of the variable that should be created.

  • num_dimensions -

    Number of dimensions of the variable that should be created.

  • dimension_type -

    Type of dimension for each of the dimensions of the variable that should be created.

  • variable -

    Pointer to the C variable where the derived HARP variable will be stored.

int harp_product_add_derived_variable(harp_product *product, const char *name, const char *unit, int num_dimensions, const harp_dimension_type *dimension_type)

Create a derived variable and add it to the product.

If a similar named variable with the right dimensions was already in the product then that variable will be modified to match the given unit (and in case unit is NULL, then the function will just leave the product unmodified). Otherwise the function will call harp_product_get_derived_variable() and add the new variable using harp_product_add_variable() (removing any existing variable with the same name, but different dimensions)

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product from which to derive the new variable and into which the derived variable should be placed.

  • name -

    Name of the variable that should be added.

  • unit -

    Unit (optional) of the variable that should be added.

  • num_dimensions -

    Number of dimensions of the variable that should be created.

  • dimension_type -

    Type of dimension for each of the dimensions of the variable that should be created.

int harp_product_new(harp_product **new_product)

Create new product. The product will be intialized with 0 variables and 0 attributes.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • new_product -

    Pointer to the C variable where the new HARP product will be stored.

void harp_product_delete(harp_product *product)

Delete product. Remove product and all attached variables and attributes.

Parameters
  • product -

    HARP product.

int harp_product_copy(const harp_product *other_product, harp_product **new_product)

Create a copy of a product. The function will create a deep-copy of the given product, also creating copyies of all attributes and variables.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • other_product -

    Product that should be copied.

  • new_product -

    Pointer to the variable where the new HARP product will be stored.

int harp_product_add_variable(harp_product *product, harp_variable *variable)

Add a variable to a product.

Note
The memory management of the variable will be handled via the product after you have added the variable.
Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product to which the variable should be added.

  • variable -

    Variable that should be added to the product.

int harp_product_detach_variable(harp_product *product, const harp_variable *variable)

Detach a variable from a product. Removes a variable from a product without deleting the variable itself. After detaching, the caller of the function will be responsible for the further memory management of the variable.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product from which the variable should be detached.

  • variable -

    Variable that should be detached.

int harp_product_remove_variable(harp_product *product, harp_variable *variable)

Remove a variable from a product. If it serves as an axis variable for other variables, remove the variables that depend on it as well. This function removes any link to the specified variable from the product and then removes the variable itself.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product from which the variable should be removed.

  • variable -

    Variable that should be removed.

int harp_product_replace_variable(harp_product *product, harp_variable *variable)

Replaces an existing variable with the one provided. The product should already contain a variable with the same name as variable. This function searches in the list of variables in the product for one with the same name, removes this variable and then adds the given variable in its place. Note that if you try to replace a variable with itself the function does nothing (and returns success). If the variable is an axis variable then the axis_variable property of all other variables (and of the new variable) will be updated to point to the new variable.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product in which the variable should be replaced.

  • variable -

    Variable that should be used to replace an existing variable.

int harp_product_has_variable(const harp_product *product, const char *name)

Test if product contains a variable with the specified name.

Return
  • 0, Product does not contain a variable of the specified name.
  • 1, Product contains a variable of the specified name.
Parameters
  • product -

    Product to search.

  • name -

    Name of the variable to search for.

int harp_product_get_variable_by_name(const harp_product *product, const char *name, harp_variable **variable)

Find variable with a given name for a product. If no variable with the given name can be found an error is returned.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product in which the find the variable.

  • name -

    Name of the variable.

  • variable -

    Pointer to the C variable where the found HARP variable will be stored.

int harp_product_get_variable_id_by_name(const harp_product *product, const char *name, int *variable_id)

Find index of variable with a given name for a product. If no variable with the given name can be found an error is returned.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product in which the find the variable.

  • name -

    Name of the variable.

  • variable_id -

    Pointer to the C variable where the index in the HARP variables list for the product is returned.

int harp_product_is_empty(const harp_product *product)

Determine whether all variables in a product have at least one element. If at least one variable has 0 elements or if the product has 0 variables the function returns 1, and 0 otherwise.

Return
  • 0, The product does not contain empty data.
  • 1, The product contains 0 variables or at least one variable has 0 elements.
Parameters
  • product -

    Product to check for empty data.

int harp_product_update_history(harp_product *product, const char *executable, int argc, char *argv[])

Update the history attribute in the product based on the command line parameters. This function will extend the existing product history metadata element with a line containing the call that was used to run this program. This command line execution call is constructed based on the argc and argv arguments.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • product -

    Product for which the history metada should be extended.

  • executable -

    Name of the command line executable (this value is used instead of argv[0]).

  • argc -

    Variable as passed by main().

  • argv -

    Variable as passed by main().

int harp_import(const char *filename, harp_product **product)

Import HARP product from file.

Try to import an HDF4, HDF5, or netCDF file that complies to the HARP Data Format. You should pass a variable to product that was initialized with harp_product_new().

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • filename -

    Path to the file that is to be imported.

  • product -

    Empty product that is to be filled with information from the imported file.

int harp_import_global_attributes(const char *filename, double *datetime_start, double *datetime_stop, char **source_product)

Retrieve global attributes from a HARP product file.

This function retrieves the datetime range covered by the a HARP product, as well as the name of the source product without performing a full import. This function is only supported for netCDF files.

Return
  • 0, Succes.
  • -1, Error occurred (check harp_errno).
Parameters
  • filename -

    Path to the file for which to retrieve global attributes.

  • datetime_start -

    Optional pointer to the variable where the start time of the product should be stored (use NULL if you are not interested in this value).

  • datetime_stop -

    Optional pointer to the variable where the stop time of the porduct should be stored (use NULL if you are not interested in this value).

  • source_product -

    Optional pointer to the variable where the name of the source product should be stored (use NULL if you are not interested in this value).

int harp_export(const char *filename, const char *export_format, const harp_product *product)

Export HARP product to a file.

Export product to an HDF4, HDF5, or netCDF file that complies to the HARP Data Format.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • filename -

    Path to the file to which the product is to be exported.

  • export_format -

    Either “HDF4”, “HDF5”, or “netCDF”.

  • product -

    Product that should be exported to file.

struct harp_product_struct
#include <harp.h>

HARP Product struct

Public Members

long dimension[HARP_NUM_DIM_TYPES]

length of each dimension (0 for unused dimensions)

int num_variables

number of variables in this product

harp_variable **variable

pointers to the variables

char *source_product

identifier of the product the HARP product originates from

char *history

value for the ‘history’ global attribute