H4CF Conversion Library Reference Manual
****************************************

Name: 
        h4cf_open
Signature: 
        void h4cf_open(char *name)
Purpose:
	Opens an existing HDF-EOS2 or HDF4 file.
Description:
	h4cf_open opens the "name" file and initializes the library.
Parameters:
	char *name: IN: name of the file to be opened.
Returns:
	None


Name: 
	h4cf_get_file_attrs
Signature:
        const list<attr*> h4cf_get_file_attrs()
Purpose:
	Retrieves file attributes.
Description:
        h4cf_get_file_attrs returns the list of file attributes.
Parameters:
	None
Returns:
        a list of attributes.

Name:
	h4cf_get_dims
Signature:
	const map<string, int> h4cf_get_dims()
Purpose:
	Retrieves pairs of name and size of dimension in the file.
Description:
        h4cf_get_dims retrieves the dimension information and returns the pairs 
         of name and size of dimension in map. The name of dimension follows 
        the CF conventions.
        For example, if the opening file has two dimensions  XDim and  YDim
        with their size 360 and 180 respectively, the returned map will be
        
        map[XDim] = 360
        map[YDim] = 180
Parameters:
	None
Returns:
	a map containing dimension definitions. The key value in map is the 
        name of the dimension and the mapped value is the size of the dimension.


Name:
	h4cf_get_vars
Signature:
	const list<var*> h4cf_get_vars()
Purpose:
	Retrieves variables in the file.
Description:
	h4cf_get_vars returns a list of pointers of all variables in the file.
Parameters:
	None
Returns:
	a list containing variable pointers


Name:
	h4cf_get_var_name
Signature:
	const string h4cf_get_var_name(var *v)
Purpose:
	Retrieves the name of a variable pointed by "v".
Description:
        h4cf_get_var_name returns the name of a variable pointed by "v".
        The variable name follows the CF conventions.
Parameters:
	var* v: IN:a pointer to a variable
Returns:
	a string describing the variable name


Name:
	h4cf_get_var_dims
Signature:
	const vector< map<string name, int size> > h4cf_get_var_dims(var *v)
Purpose:
	Retrieves the dimensions of a variable pointed by "v".
Description:
	h4cf_get_var_dims retrieves the dimensions of a given variable and 
	returns them in a C++ vector. Each dimension is a pair of name and size.
	The name of dimension follows the CF conventions. 

        For example, for a variable with two dimensions XDim and YDim with 
        their size 360 and 180 respectively, the returned vector will be:

	vector[0] = <XDim, 360>
	vector[1] = <YDim, 180>.
Parameters:
	var *v: IN: a pointer to a variable
Returns:
        a vector of maps that have dimension name and size


Name:
	h4cf_get_var_type
Signature:
	const h4cf_data_type h4cf_get_var_type(var *v)
Purpose:
	Retrieves the variable type of a variable pointed by "v".
Description:
	h4cf_get_var_type returns the data type of a variable pointed by "v".
	The data type can be one of CHAR8, INT8, INT16, INT32, 
	UCHAR8, UINT8, UINT16, UINT32, FLOAT, or DOUBLE.
Parameters:
	var *v: IN: a pointer to a variable
Returns:
	a data type


Name:
	h4cf_get_var_rank
Signature:
	const int h4cf_get_var_rank(var *v)
Purpose:
	Retrieves the rank of a variable pointed by "v".
Description:
        h4cf_get_var_rank returns the number of dimensions of a variable pointed
        by "v".
        For example, if "v" is an array v[10][20][30], this function will 
        return 3.
Parameters:
	var *v: IN: a pointer to a variable
Returns:
	the rank of variable 


Name:
	h4cf_get_var_value
Signature:
	void h4cf_get_var_value(vector<char> *buf, var *v)
Purpose:
        Retrieves data values of a variable pointed by "v" and stores them into "buf".
Description:
        h4cf_get_var_value reads the data values stored in a variable pointed
        by "v" and saves them into the "buf" vector.
Remark:
        For the first parameter "buf", a user does not need to 
        specify its capacity. The storage of vector will be allocated by the 
        library, and the actual size of vector is equal to the number of bytes
        the variable holds.        
Parameters:
	vector<char *> *buf: OUT: a pointer to store values
	var *v: IN: a pointer to a variable
Returns:
	None


Name:
	h4cf_get_var_value
Signature:
	void h4cf_get_var_value(vector<char> *buf, var *v, int32 *start, 
                                int32 *stride, int32 *edge);
Purpose: 
	Retrieves subset data values of a variable pointed by "v" and stores them into
        "buf".
Description:
        h4cf_get_var_value returns the subset data values stored in a variable pointed by 
        "v" and saves them into the "buf" vector. The subsetting is controlled by
        the parameters stored in "start", "stride", and "edge". 

        For example, if "v" has values like:

        o v[0] = 0
        o v[1] = 1
        o v[2] = 2
        o v[3] = 3

        specifying start[0] = 1, stride[0] = 2, and edge[0] = 2 to this function
        will return

        * buf[0] = 1 
        * buf[1] = 3. 
Remark:
        For the first parameter "buf", user does not need to 
        specify its capacity. The storage of vector will be allocated by the 
        library, and the actual size of vector is equal to the number of bytes
        the variable holds.        
Parameters:
	vector<char *> *buf: OUT: a pointer to store values
        var *v: IN: a pointer to a variable
        int32 *start: IN: a pointer to array containing the position at which
                          this function will start for each dimension
	int32 *stride: IN: a pointer to array specifying the interval between 
                          the data values that will be read along each dimension
	int32 *edge: IN: a pointer to array containing the number of data 
                         elements along each dimension
Returns:
	None


Name:
	h4cf_get_var_attrs
Signature:
	const list<attr*> h4cf_get_var_attrs(var *v)
Purpose:
	Retrieves the attributes of a variable pointed by "v".
Description:
        h4cf_get_var_attrs returns the list of attributes in a variable
        pointed by "v".
Parameters:
	var *v: IN: a pointer to a variable
Returns:
	a list of attributes.


Name:
	h4cf_get_attr_value
Signature:
	void h4cf_get_attr_value(vector<char> *buf, attr *a)
Purpose:
	Retrieves the data values of an attribute pointed by "a".
Description:
        h4cf_get_var_attr_value reads the data values stored in an attribute
        pointed by "a" and saves them into "buf" vector.
Remark:
        For the first parameter "buf", user does not need to 
        specify its capacity. The storage of vector will be allocated by the 
        library, and the actual size of vector is equal to the number of bytes
        the attribute holds.        

Parameters:
	vector<char *> *buf: OUT: a pointer to store values
	attr *a: IN: a pointer to an attribute
Returns:
	None


Name:
	h4cf_get_attr_name
Signature:
	const string h4cf_get_attr_name(attr *a)
Purpose:
        Retrieves the name of an attribute pointed by "a".
Description:
	h4cf_get_attr_name returns the name of an attribute pointed by "a".
        The attribute name follows the CF conventions.
Parameters:
	attr *a: IN: a pointer to an attribute
Returns:
	a string of attribute name


Name:
	h4cf_get_attr_type
Signature:
	const h4cf_data_type h4cf_get_attr_type(attr *a)
Purpose:
        Retrieves the attribute type of an attribute pointed by "a".
Description:
	h4cf_get_var_attr_type returns the data type of an attribute pointed 
        pointed by "a".
	The data type can be one of CHAR8, INT8, INT16, INT32, 
	UCHAR8, UINT8, UINT16, UINT32, FLOAT, or DOUBLE.
Parameters:
	attr *a: IN: a pointer to an attribute
Returns:
	a data type


Name:
	h4cf_get_attr_count
Signature:
	const int h4cf_get_attr_count(attr *a)
Purpose:
	Retrieves the number of elements stored in an attribute pointed by "a".
Description:
	h4cf_get_var_attr_count returns the number of elements stored in an 
        attribute "a". For example, if "coordsys" attribute has type CHAR8 
	and value "Cartesian", the count will be 9. If "valid_range" attribute
	has type INT8 and value "0, -2", the count will be 2.
Parameters:
	attr *a: IN: a pointer to an attribute
Returns:
	a number of elements.


Name:
	h4cf_get_var_attr_by_name
Signature:
	const attr* h4cf_get_var_attr_by_name(string str, var *v)
Purpose:
	Retrieves the attribute that has a "str" name from a variable pointed 
        by "v".
Description:
        h4cf_get_var_attr_by_name returns the pointer to the attribute 
        in a variable pointed by "v" if the attribute's name matches the "str" 
        parameter.
Parameters:
	string str: IN: an attribute name to be searched for
	var *v: IN: a pointer to a variable
Returns:
        a pointer to the matching attribute if present, otherwise NULL.


Name:
	h4cf_close
Signature:
	void h4cf_close()
Purpose:
	Closes the access to the opened file.
Description:
	h4cf_close terminates the access to the opened file by releasing the 
        resources held by the library. The opened file should be closed by 
        calling this function when it is no longer needed.
Parameters:
	None
Returns:
	None

