grib_api.h File Reference

Copyright 2005-2013 ECMWF. More...

Defines
#define	GRIB_KEYS_ITERATOR_ALL_KEYS   0
#define	GRIB_KEYS_ITERATOR_SKIP_READ_ONLY   (1<<0)
#define	GRIB_KEYS_ITERATOR_SKIP_OPTIONAL   (1<<1)
#define	GRIB_KEYS_ITERATOR_SKIP_EDITION_SPECIFIC   (1<<2)
#define	GRIB_KEYS_ITERATOR_SKIP_CODED   (1<<3)
#define	GRIB_KEYS_ITERATOR_SKIP_COMPUTED   (1<<4)
#define	GRIB_KEYS_ITERATOR_SKIP_DUPLICATES   (1<<5)
#define	GRIB_KEYS_ITERATOR_SKIP_FUNCTION   (1<<6)
#define	GRIB_SUCCESS   0
	No error.
#define	GRIB_END_OF_FILE   -1
	End of ressource reached.
#define	GRIB_INTERNAL_ERROR   -2
	Internal error.
#define	GRIB_BUFFER_TOO_SMALL   -3
	Passed buffer is too small.
#define	GRIB_NOT_IMPLEMENTED   -4
	Function not yet implemented.
#define	GRIB_7777_NOT_FOUND   -5
	Missing 7777 at end of message.
#define	GRIB_ARRAY_TOO_SMALL   -6
	Passed array is too small.
#define	GRIB_FILE_NOT_FOUND   -7
	File not found.
#define	GRIB_CODE_NOT_FOUND_IN_TABLE   -8
	Code not found in code table.
#define	GRIB_STRING_TOO_SMALL_FOR_CODE_NAME   -9
	Code cannot unpack because of string too small.
#define	GRIB_WRONG_ARRAY_SIZE   -10
	Array size mismatch.
#define	GRIB_NOT_FOUND   -11
	Key/value not found.
#define	GRIB_IO_PROBLEM   -12
	Input output problem.
#define	GRIB_INVALID_MESSAGE   -13
	Message invalid.
#define	GRIB_DECODING_ERROR   -14
	Decoding invalid.
#define	GRIB_ENCODING_ERROR   -15
	Encoding invalid.
#define	GRIB_NO_MORE_IN_SET   -16
	Code cannot unpack because of string too small.
#define	GRIB_GEOCALCULUS_PROBLEM   -17
	Problem with calculation of geographic attributes.
#define	GRIB_OUT_OF_MEMORY   -18
	Out of memory.
#define	GRIB_READ_ONLY   -19
	Value is read only.
#define	GRIB_INVALID_ARGUMENT   -20
	Invalid argument.
#define	GRIB_NULL_HANDLE   -21
	Null handle.
#define	GRIB_INVALID_SECTION_NUMBER   -22
	Invalid section number.
#define	GRIB_VALUE_CANNOT_BE_MISSING   -23
	Value cannot be missing.
#define	GRIB_WRONG_LENGTH   -24
	Wrong message length.
#define	GRIB_INVALID_TYPE   -25
	Invalid key type.
#define	GRIB_WRONG_STEP   -26
	Unable to set step.
#define	GRIB_WRONG_STEP_UNIT   -27
	Wrong units for step (step must be integer).
#define	GRIB_INVALID_FILE   -28
	Invalid file id.
#define	GRIB_INVALID_GRIB   -29
	Invalid grib id.
#define	GRIB_INVALID_INDEX   -30
	Invalid index id.
#define	GRIB_INVALID_ITERATOR   -31
	Invalid iterator id.
#define	GRIB_INVALID_KEYS_ITERATOR   -32
	Invalid keys iterator id.
#define	GRIB_INVALID_NEAREST   -33
	Invalid nearest id.
#define	GRIB_INVALID_ORDERBY   -34
	Invalid order by.
#define	GRIB_MISSING_KEY   -35
	Missing a key from the fieldset.
#define	GRIB_OUT_OF_AREA   -36
	The point is out of the grid area.
#define	GRIB_CONCEPT_NO_MATCH   -37
	Concept no match.
#define	GRIB_NO_DEFINITIONS   -38
	Definitions files not found.
#define	GRIB_WRONG_TYPE   -39
	Wrong type while packing.
#define	GRIB_END   -40
	End of resource.
#define	GRIB_NO_VALUES   -41
	Unable to code a field without values.
#define	GRIB_WRONG_GRID   -42
	Grid description is wrong or inconsistent.
#define	GRIB_END_OF_INDEX   -43
	End of index reached.
#define	GRIB_NULL_INDEX   -44
	Null index.
#define	GRIB_PREMATURE_END_OF_FILE   -45
	End of ressource reached when reading message.
#define	GRIB_INTERNAL_ARRAY_TOO_SMALL   -46
	An internal array is too small.
#define	GRIB_MESSAGE_TOO_LARGE   -47
	Message is too large for the current architecture.
#define	GRIB_CONSTANT_FIELD   -48
	Constant field.
#define	GRIB_SWITCH_NO_MATCH   -49
	Switch unable to find a matching case.
Typedefs
typedef struct grib_handle	grib_handle
typedef struct grib_multi_handle	grib_multi_handle
typedef struct grib_context	grib_context
typedef struct grib_iterator	grib_iterator
typedef struct grib_nearest	grib_nearest
typedef struct grib_keys_iterator	grib_keys_iterator
typedef struct grib_index	grib_index
typedef void(*	grib_free_proc )(const grib_context *c, void *data)
	Grib free procedure, format of a procedure referenced in the context that is used to free memory.
typedef void *(*	grib_malloc_proc )(const grib_context *c, size_t length)
	Grib malloc procedure, format of a procedure referenced in the context that is used to allocate memory.
typedef void *(*	grib_realloc_proc )(const grib_context *c, void *data, size_t length)
	Grib realloc procedure, format of a procedure referenced in the context that is used to reallocate memory.
typedef void(*	grib_log_proc )(const grib_context *c, int level, const char *mesg)
	Grib loc proc, format of a procedure referenced in the context that is used to log internal messages.
typedef void(*	grib_print_proc )(const grib_context *c, void *descriptor, const char *mesg)
	Grib print proc, format of a procedure referenced in the context that is used to print external messages.
typedef size_t(*	grib_data_read_proc )(const grib_context *c, void *ptr, size_t size, void *stream)
	Grib data read proc, format of a procedure referenced in the context that is used to read from a stream in a resource.
typedef size_t(*	grib_data_write_proc )(const grib_context *c, const void *ptr, size_t size, void *stream)
	Grib data read write, format of a procedure referenced in the context that is used to write to a stream from a resource.
typedef off_t(*	grib_data_tell_proc )(const grib_context *c, void *stream)
	Grib data tell, format of a procedure referenced in the context that is used to tell the current position in a stream.
typedef off_t(*	grib_data_seek_proc )(const grib_context *c, off_t offset, int whence, void *stream)
	Grib data seek, format of a procedure referenced in the context that is used to seek the current position in a stream.
typedef int(*	grib_data_eof_proc )(const grib_context *c, void *stream)
	Grib data eof, format of a procedure referenced in the context that is used to test end of file.
Functions
grib_index *	grib_index_new_from_file (grib_context *c, char *filename, const char *keys, int *err)
	Create a new index form a file.
int	grib_index_get_size (grib_index *index, const char *key, size_t *size)
	Get the number of distinct values of the key in argument contained in the index.
int	grib_index_get_long (grib_index *index, const char *key, long *values, size_t *size)
	Get the distinct values of the key in argument contained in the index.
int	grib_index_get_double (grib_index *index, const char *key, double *values, size_t *size)
	Get the distinct values of the key in argument contained in the index.
int	grib_index_get_string (grib_index *index, const char *key, char **values, size_t *size)
	Get the distinct values of the key in argument contained in the index.
int	grib_index_select_long (grib_index *index, const char *key, long value)
	Select the message subset with key==value.
int	grib_index_select_double (grib_index *index, const char *key, double value)
	Select the message subset with key==value.
int	grib_index_select_string (grib_index *index, const char *key, char *value)
	Select the message subset with key==value.
grib_handle *	grib_handle_new_from_index (grib_index *index, int *err)
	Create a new handle from an index after having selected the key values.
void	grib_index_delete (grib_index *index)
	Delete the index.
int	grib_count_in_file (grib_context *c, FILE *f, int *n)
	Counts the messages contained in a file resource.
grib_handle *	grib_handle_new_from_file (grib_context *c, FILE *f, int *error)
	Create a handle from a file resource.
grib_handle *	grib_handle_new_from_message (grib_context *c, void *data, size_t data_len)
	Create a handle from a user message in memory.
grib_handle *	grib_handle_new_from_multi_message (grib_context *c, void **data, size_t *data_len, int *error)
	Create a handle from a user message in memory.
grib_handle *	grib_handle_new_from_message_copy (grib_context *c, const void *data, size_t data_len)
	Create a handle from a user message.
grib_handle *	grib_handle_new_from_template (grib_context *c, const char *res_name)
	Create a handle from a read_only template resource.
grib_handle *	grib_handle_new_from_samples (grib_context *c, const char *res_name)
	Create a handle from a message contained in a samples directory.
grib_handle *	grib_handle_clone (grib_handle *h)
	Clone an existing handle using the context of the original handle, The message is copied and reparsed.
int	grib_handle_delete (grib_handle *h)
	Frees a handle, also frees the message if it is not a user message.
grib_multi_handle *	grib_multi_handle_new (grib_context *c)
	Create an empty multi field handle.
int	grib_multi_handle_append (grib_handle *h, int start_section, grib_multi_handle *mh)
	Append the sections starting with start_section of the message pointed by h at the end of the multi field handle mh.
int	grib_multi_handle_delete (grib_multi_handle *mh)
	Delete multi field handle.
int	grib_multi_handle_write (grib_multi_handle *mh, FILE *f)
	Write a multi field handle in a file.
int	grib_get_message (grib_handle *h, const void **message, size_t *message_length)
	getting the message attached to a handle
int	grib_get_message_copy (grib_handle *h, void *message, size_t *message_length)
	getting a copy of the message attached to a handle
grib_iterator *	grib_iterator_new (grib_handle *h, unsigned long flags, int *error)
	Create a new iterator from a handle, using current geometry and values.
int	grib_iterator_next (grib_iterator *i, double *lat, double *lon, double *value)
	Get the next value from an iterator.
int	grib_iterator_previous (grib_iterator *i, double *lat, double *lon, double *value)
	Get the previous value from an iterator.
int	grib_iterator_has_next (grib_iterator *i)
	Test procedure for values in an iterator.
int	grib_iterator_reset (grib_iterator *i)
	Test procedure for values in an iterator.
int	grib_iterator_delete (grib_iterator *i)
	Frees an iterator from memory.
grib_nearest *	grib_nearest_new (grib_handle *h, int *error)
	Create a new nearest from a handle, using current geometry .
int	grib_nearest_find (grib_nearest *nearest, grib_handle *h, double inlat, double inlon, unsigned long flags, double *outlats, double *outlons, double *values, double *distances, int *indexes, size_t *len)
	Find the 4 nearest points of a latitude longitude point.
int	grib_nearest_delete (grib_nearest *nearest)
	Frees an nearest from memory.
int	grib_nearest_find_multiple (grib_handle *h, int is_lsm, double *inlats, double *inlons, long npoints, double *outlats, double *outlons, double *values, double *distances, int *indexes)
	Find the nearest point of a set of points whose latitudes and longitudes are given in the inlats, inlons arrays respectively.
int	grib_get_offset (grib_handle *h, const char *key, size_t *offset)
	Get the number offset of a key, in a message if several keys of the same name are present, the offset of the last one is returned.
int	grib_get_size (grib_handle *h, const char *key, size_t *size)
	Get the number of coded value from a key, if several keys of the same name are present, the total sum is returned.
int	grib_get_long (grib_handle *h, const char *key, long *value)
	Get a long value from a key, if several keys of the same name are present, the last one is returned.
int	grib_get_double (grib_handle *h, const char *key, double *value)
	Get a double value from a key, if several keys of the same name are present, the last one is returned.
int	grib_get_double_element (grib_handle *h, const char *key, int i, double *value)
	Get as double the i-th element of the "key" array.
int	grib_get_double_elements (grib_handle *h, const char *key, int *i, long size, double *value)
	Get as double array the elements of the "key" array whose indexes are listed in the input array i.
int	grib_get_string (grib_handle *h, const char *key, char *mesg, size_t *length)
	Get a string value from a key, if several keys of the same name are present, the last one is returned.
int	grib_get_bytes (grib_handle *h, const char *key, unsigned char *bytes, size_t *length)
	Get raw bytes values from a key.
int	grib_get_double_array (grib_handle *h, const char *key, double *vals, size_t *length)
	Get double array values from a key.
int	grib_get_long_array (grib_handle *h, const char *key, long *vals, size_t *length)
	Get long array values from a key.
int	grib_copy_namespace (grib_handle *dest, const char *name, grib_handle *src)
	Copy the keys belonging to a given namespace from a source handle to a destination handle.
int	grib_set_long (grib_handle *h, const char *key, long val)
	Set a long value from a key.
int	grib_set_double (grib_handle *h, const char *key, double val)
	Set a double value from a key.
int	grib_set_string (grib_handle *h, const char *key, const char *mesg, size_t *length)
	Set a string value from a key.
int	grib_set_bytes (grib_handle *h, const char *key, const unsigned char *bytes, size_t *length)
	Set a bytes array from a key.
int	grib_set_double_array (grib_handle *h, const char *key, const double *vals, size_t length)
	Set a double array from a key.
int	grib_set_long_array (grib_handle *h, const char *key, const long *vals, size_t length)
	Set a long array from a key.
void	grib_dump_content (grib_handle *h, FILE *out, const char *mode, unsigned long option_flags, void *arg)
	Print all keys, with the context print procedure and dump mode to a resource.
void	grib_get_all_names (grib_handle *h, char *names)
	Gather all names available in a handle to a string, using a space as separator.
void	grib_dump_action_tree (grib_context *c, FILE *f)
	Print all keys from the parsed definition files available in a context.
grib_context *	grib_get_context (grib_handle *h)
	Retreive the context from a handle.
grib_context *	grib_context_get_default (void)
	Get the static default context.
grib_context *	grib_context_new (grib_context *c)
	Create and allocate a new context from a parent context.
void	grib_context_delete (grib_context *c)
	Frees the cached definition files of the context.
void	grib_gts_header_on (grib_context *c)
	Set the gts header mode on.
void	grib_gts_header_off (grib_context *c)
	Set the gts header mode off.
void	grib_gribex_mode_on (grib_context *c)
	Set the gribex mode on.
void	grib_gribex_mode_off (grib_context *c)
	Set the gribex mode off.
void	grib_context_set_user_data (grib_context *c, void *udata)
	Sets user data in a context.
void *	grib_context_get_user_data (grib_context *c)
	get userData from a context
void	grib_context_set_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree, grib_realloc_proc gribrealloc)
	Sets memory procedures of the context.
void	grib_context_set_persistent_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree)
	Sets memory procedures of the context for persistent data.
void	grib_context_set_buffer_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree, grib_realloc_proc gribrealloc)
	Sets memory procedures of the context for large buffers.
void	grib_context_set_path (grib_context *c, const char *path)
	Sets the context search path for definition files.
void	grib_context_set_dump_mode (grib_context *c, int mode)
	Sets context dump mode.
void	grib_context_set_print_proc (grib_context *c, grib_print_proc printp)
	Sets the context printing procedure used for user interaction.
void	grib_context_set_logging_proc (grib_context *c, grib_log_proc logp)
	Sets the context logging procedure used for system (warning, errors, infos .
void	grib_multi_support_on (grib_context *c)
	Turn on support for multiple fields in single grib messages.
void	grib_multi_support_off (grib_context *c)
	Turn off support for multiple fields in single grib messages.
long	grib_get_api_version (void)
	Get the api version.
void	grib_print_api_version (FILE *out)
	Prints the api version.
grib_keys_iterator *	grib_keys_iterator_new (grib_handle *h, unsigned long filter_flags, char *name_space)
int	grib_keys_iterator_next (grib_keys_iterator *kiter)
const char *	grib_keys_iterator_get_name (grib_keys_iterator *kiter)
int	grib_keys_iterator_delete (grib_keys_iterator *kiter)
int	grib_keys_iterator_rewind (grib_keys_iterator *kiter)
const char *	grib_get_error_message (int code)
	Convert an error code into a string.

---

Detailed Description

Copyright 2005-2013 ECMWF.

This software is licensed under the terms of the Apache Licence Version 2.0 which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
In applying this licence, ECMWF does not waive the privileges and immunities granted to it by virtue of its status as an intergovernmental organisation nor does it submit to any jurisdiction.

grib_api C header file

This is the only file that must be included to use the grib_api library from C.

---

Define Documentation

#define GRIB_7777_NOT_FOUND   -5

Missing 7777 at end of message.

#define GRIB_ARRAY_TOO_SMALL   -6

Passed array is too small.

#define GRIB_BUFFER_TOO_SMALL   -3

Passed buffer is too small.

#define GRIB_CODE_NOT_FOUND_IN_TABLE   -8

Code not found in code table.

#define GRIB_CONCEPT_NO_MATCH   -37

Concept no match.

#define GRIB_CONSTANT_FIELD   -48

Constant field.

#define GRIB_DECODING_ERROR   -14

Decoding invalid.

#define GRIB_ENCODING_ERROR   -15

Encoding invalid.

#define GRIB_END   -40

End of resource.

#define GRIB_END_OF_FILE   -1

End of ressource reached.

Examples:

get.f90, get_data.f90, keys_iterator.f90, multi.f90, and samples.f90.

#define GRIB_END_OF_INDEX   -43

End of index reached.

Examples:

index.f90.

#define GRIB_FILE_NOT_FOUND   -7

File not found.

#define GRIB_GEOCALCULUS_PROBLEM   -17

Problem with calculation of geographic attributes.

#define GRIB_INTERNAL_ARRAY_TOO_SMALL   -46

An internal array is too small.

#define GRIB_INTERNAL_ERROR   -2

Internal error.

#define GRIB_INVALID_ARGUMENT   -20

Invalid argument.

#define GRIB_INVALID_FILE   -28

Invalid file id.

#define GRIB_INVALID_GRIB   -29

Invalid grib id.

#define GRIB_INVALID_INDEX   -30

Invalid index id.

#define GRIB_INVALID_ITERATOR   -31

Invalid iterator id.

#define GRIB_INVALID_KEYS_ITERATOR   -32

Invalid keys iterator id.

#define GRIB_INVALID_MESSAGE   -13

Message invalid.

#define GRIB_INVALID_NEAREST   -33

Invalid nearest id.

#define GRIB_INVALID_ORDERBY   -34

Invalid order by.

#define GRIB_INVALID_SECTION_NUMBER   -22

Invalid section number.

#define GRIB_INVALID_TYPE   -25

Invalid key type.

#define GRIB_IO_PROBLEM   -12

Input output problem.

#define GRIB_MESSAGE_TOO_LARGE   -47

Message is too large for the current architecture.

#define GRIB_MISSING_KEY   -35

Missing a key from the fieldset.

#define GRIB_NO_DEFINITIONS   -38

Definitions files not found.

#define GRIB_NO_MORE_IN_SET   -16

Code cannot unpack because of string too small.

#define GRIB_NO_VALUES   -41

Unable to code a field without values.

#define GRIB_NOT_FOUND   -11

Key/value not found.

#define GRIB_NOT_IMPLEMENTED   -4

Function not yet implemented.

#define GRIB_NULL_HANDLE   -21

Null handle.

#define GRIB_NULL_INDEX   -44

Null index.

#define GRIB_OUT_OF_AREA   -36

The point is out of the grid area.

#define GRIB_OUT_OF_MEMORY   -18

Out of memory.

#define GRIB_PREMATURE_END_OF_FILE   -45

End of ressource reached when reading message.

#define GRIB_READ_ONLY   -19

Value is read only.

#define GRIB_STRING_TOO_SMALL_FOR_CODE_NAME   -9

Code cannot unpack because of string too small.

#define GRIB_SUCCESS   0

No error.

Examples:

iterator.c.

#define GRIB_SWITCH_NO_MATCH   -49

Switch unable to find a matching case.

#define GRIB_VALUE_CANNOT_BE_MISSING   -23

Value cannot be missing.

#define GRIB_WRONG_ARRAY_SIZE   -10

Array size mismatch.

#define GRIB_WRONG_GRID   -42

Grid description is wrong or inconsistent.

#define GRIB_WRONG_LENGTH   -24

Wrong message length.

#define GRIB_WRONG_STEP   -26

Unable to set step.

#define GRIB_WRONG_STEP_UNIT   -27

Wrong units for step (step must be integer).

#define GRIB_WRONG_TYPE   -39

Wrong type while packing.

---

Typedef Documentation

typedef struct grib_context grib_context

Grib context, structure containing the memory methods, the parsers and the formats.

typedef struct grib_iterator grib_iterator

Grib iterator, structure supporting a geographic iteration of values on a grib message.

Examples:

iterator.c.

typedef struct grib_nearest grib_nearest

Grib nearest, structure used to find the nearest points of a latitude longitude point.

Examples:

nearest.c.

---

Function Documentation

void grib_dump_action_tree	(	grib_context *	c,
		FILE *	f
	)

Print all keys from the parsed definition files available in a context.

Parameters:

	f	: the File used to print the keys on
	c	: the context that containd the cached definition files to be printed

void grib_dump_content	(	grib_handle *	h,
		FILE *	out,
		const char *	mode,
		unsigned long	option_flags,
		void *	arg
	)

Print all keys, with the context print procedure and dump mode to a resource.

Parameters:

	h	: the handle to be printed
	out	: output file handle
	mode	: available dump modes are: debug wmo c_code
	option_flags	: all the GRIB_DUMP_FLAG_x flags can be used
	arg	: used to provide a format to output data (experimental)

void grib_get_all_names	(	grib_handle *	h,
		char *	names
	)

Gather all names available in a handle to a string, using a space as separator.

Parameters:

	h	: the handle used to gather the keys
	names	: the sting to be filled with the names

long grib_get_api_version

(

void

)

Get the api version.

Returns:

api version

const char* grib_get_error_message

(

int

code

)

Convert an error code into a string.

Parameters:

code

: the error code

Returns:

the error message

void grib_print_api_version

(

FILE *

out

)

Prints the api version.

---