Fortran dballe functions

Summary of routines

Error management routines

Name	Description
idba_error_code()	Return the error code for the last function that was called.
idba_error_message()	Return the error message for the last function that was called.
idba_error_context()	Return a string describing the error context description for the last function that was called.
idba_error_details()	Return a string with additional details about the error for the last function that was called.
idba_error_set_callback()	Set a callback to be invoked when an error of a specific kind happens.
idba_error_remove_callback()	Remove a previously set callback.
idba_default_error_handler()	Predefined error callback that prints a message and exits.
idba_error_handle_tolerating_overflows()	Predefined error callback that prints a message and exists, except in case of overflow errors.

Session routines

These routines are used to begin and end working sessions with DB-All.e.

Name	Description
idba_connect()	Connect to the database.
idba_disconnect()	Disconnect from the database.
idba_begin()	Open a new session.
idba_begin_messages()	Start working with a message file.
idba_commit()	Close a session.

Input/output routines

These routines are used to set the input and read the output of action routines.

Name	Description
idba_seti()	Set an integer value in input.
idba_setb()	Set a byte value in input.
idba_setr()	Set a real value in input.
idba_setd()	Set a real*8 value in input.
idba_setc()	Set a character value in input.
idba_enqi()	Read an integer value from the output.
idba_enqb()	Read a byte value from the output.
idba_enqr()	Read a real value from the output.
idba_enqd()	Read a real*8 value from the output.
idba_enqc()	Read a character value from the output.
idba_unset()	Remove one value from the input.
idba_unsetb()	Remove all Bxxyyy values from the input.
idba_unsetall()	Completely clear the input, removing all values.
idba_set_station_context()	Signal that the input values that are set are related to station values instead of normal variables.

Input/output shortcuts

The following routines are shortcuts for common combinations of Input/Output routines.

Name	Description
idba_setlevel()	Set all level information.
idba_settimerange()	Set all time range information.
idba_setdate()	Set all date information.
idba_setdatemin()	Set the minimum date for a query.
idba_setdatemax()	Set the maximum date for a query.
idba_enqlevel()	Read all level information.
idba_enqtimerange()	Read all time range information.
idba_enqdate()	Read all date information.

Action routines

Name	Description
idba_reinit_db()	Reinitialize the database, removing all data and loading report information.
idba_query_stations()	Query the stations in the database.
idba_next_station()	Retrieve the data about one station.
idba_query_data()	Query the data in the database.
idba_next_data()	Retrieve the data about one value.
idba_insert_data()	Insert a new value in the database.
idba_remove_data()	Remove from the database all values that match the query.
idba_remove_all()	Remove all values from the database.
idba_query_attributes()	Query attributes about a variable.
idba_next_attribute()	Retrieve one attribute from the result of idba_query_attributes().
idba_insert_attributes()	Insert new attributes for a variable.
idba_remove_attributes()	Remove attribute information for a variable.

Message routines

Name	Description
idba_messages_open_input()	Open a BUFR, or CREX file for reading.
idba_messages_open_output()	Open a BUFR, or CREX file for writing.
idba_messages_read_next()	Read the next message and import it in the database.
idba_messages_write_next()	Export the data from the database that match the current query and add them to the current message.

Pretty-printing routines

Name	Description
idba_describe_level()	Format the description of a level given its value.
idba_describe_timerange()	Format the description of a time range given its value.
idba_describe_var()	Format the description of a variable given its varcode and its value.

Deprecated aliases

The following routines are deprecated compatibility aliases for other API functions.

Old name	New name
idba_presentati	idba_connect()
idba_arrivederci	idba_disconnect()
idba_preparati	idba_begin()
idba_messaggi	idba_begin_messages()
idba_fatto	idba_commit()
idba_setcontextana	idba_set_station_context()
idba_scopa	idba_reinit_db()
idba_quantesono	idba_query_stations()
idba_elencamele	idba_next_station()
idba_voglioquesto	idba_query_data()
idba_dammelo	idba_next_data()
idba_prendilo	idba_insert_data()
idba_dimenticami	idba_remove_data()
idba_voglioancora	idba_query_attributes()
idba_ancora	idba_next_attribute()
idba_critica	idba_insert_attributes()
idba_scusa	idba_remove_attributes()
idba_spiegal	idba_describe_level()
idba_spiegat	idba_describe_timerange()
idba_spiegab	idba_describe_var()

Reference of routines

Error management routines

idba_error_code()

Return the error code for the last function that was called.

Returns

The error code.

Return type

int

This is a list of known codes:

• 0: No error

• 1: Item not found

• 2: Wrong variable type

• 3: Cannot allocate memory

• 4: Database error

• 5: Handle management error

• 6: Buffer is too short to fit data

• 7: Error reported by the system

• 8: Consistency check failed

• 9: Parse error

• 10: Write error

• 11: Regular expression error

• 12: Feature not implemented

• 13: Value outside acceptable domain

idba_error_message(message, message_len)

Parameters

• message – The string where the error message will be written. If the string is not long enough, it will be truncated.

• message_len – The size of the string buffer passed as message

Returns

The error message for the last function that was called.

The error message is just a description of the error code. To see more details of the specific condition that caused the error, use idba_error_context() and idba_error_details().

idba_error_context(message, message_len)

Parameters

• message – The string where the error context will be written. If the string is not long enough, it will be truncated.

• message_len – The size of the string buffer passed as message

Returns

A string describing the error context description for the last function that was called.

This string describes what the code that failed was trying to do.

idba_error_details(message, message_len)

Parameters

• message – The string where the error details will be written. If the string is not long enough, it will be truncated.

• message_len – The size of the string buffer passed as message

Returns

The string holding the error details. If the string is not long enough, it will be truncated.

Return a string with additional details about the error for the last function that was called.

This string contains additional details about the error in case the code was able to get extra informations about it, for example by querying the error functions of an underlying module.

idba_error_set_callback(code, func, data, handle)

Set a callback to be invoked when an error of a specific kind happens.

Parameters

• code – The error code of the error that triggers this callback. If DBA_ERR_NONE is used, then the callback is invoked on all errors.

• func – The function to be called.

• data – An arbitrary integer data that is passed verbatim to the callback function when invoked.

• handle – A handle that can be used to remove the callback

Returns

The error indicator for the function

Return type

int

idba_error_remove_callback(handle)

Remove a previously set callback.

Parameters

• handle – The handle previously returned by idba_error_set_callback()

Returns

The error indicator for the function

Return type

int

idba_default_error_handler(debug)

Predefined error callback that prints a message and exits.

The message is printed only if a non-zero value is supplied as user data

idba_error_handle_tolerating_overflows(debug)

Predefined error callback that prints a message and exists, except in case of overflow errors.

In case of overflows it prints a warning and continues execution

Session routines

idba_connect(dbahandle, url)

Connect to the database.

Parameters

• url – The URL of the database to use

• user – Used in the past, now it is ignored.

• password – Used in the past, now it is ignored.

• dbahandle – The database handle that can be passed to idba_begin() to work with the database.

Returns

The error indicator for the function

This function can be called more than once to connect to different databases at the same time.

The function expects to find a properly initialised DB-All.e database. Append &wipe=true to the end of the url to wipe any existing DB-All.e information from the database if it exists, then recreate it from scratch.

idba_disconnect(dbahandle)

Disconnect from the database.

Parameters

• dbahandle – The database handle to close.

idba_begin(dbahandle, handle, anaflag, dataflag, attrflag)

Open a new session.

Parameters

• dbahandle – The main DB-ALLe connection handle

• handle – The session handle created by the function

• anaflag – station values access level

• dataflag – data values access level

• attrflag – attribute access level

Returns

The error indicator for the function

You can call idba_begin() many times and get more handles. This allows to perform many operations on the database at the same time.

idba_begin() has three extra parameters that can be used to limit write operations on the database, as a limited protection against programming errors:

anaflag controls access to station value records and can have these values:

• "read" station records cannot be inserted.

• "write" it is possible to insert and delete pseudoana records.

dataflag controls access to observed data and can have these values:

• "read" data cannot be modified in any way.

• "add" data can be added to the database, but existing data cannot be modified. Deletions are disabled. This is used to insert new data in the database while preserving the data that was already present in it.

• "write" data can freely be added, overwritten and deleted.

attrflag controls access to data attributes and can have these values:

• "read" attributes cannot be modified in any way.

• "write" attributes can freely be added, overwritten and deleted.

Note that some combinations of parameters are illegal, such as anaflag=read and dataflag=add (when adding a new data, it’s sometimes necessary to insert new pseudoana records), or dataflag=rewrite and attrflag=read (when deleting data, their attributes are deleted as well).

idba_begin_messages(handle, filename, mode, type)

Start working with a message file.

Parameters

• handle – The session handle returned by the function

• filename – Name of the file to open

• mode – File open mode. It can be "r" for read, "w" for write (the old file is deleted), "a" for append

• type – Format of the data in the file. It can be: "BUFR", "CREX", "AUTO" (autodetect, read only)

Returns

The error indicator for the function

idba_commit(handle)

Close a session.

Parameters

• handle – Handle to the session to be closed.

Input/output routines

idba_seti(handle, parameter, value)

Set an integer value in input.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – The value to assign to the parameter

Returns

The error indicator for the function

idba_setb(handle, parameter, value)

Set a byte value in input.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – The value to assign to the parameter

Returns

The error indicator for the function

idba_setr(handle, parameter, value)

Set a real value in input.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – The value to assign to the parameter

Returns

The error indicator for the function

idba_setd(handle, parameter, value)

Set a real*8 value in input.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – The value to assign to the parameter

Returns

The error indicator for the function

idba_setc(handle, parameter, value)

Set a character value in input.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – The value to assign to the parameter

Returns

The error indicator for the function

idba_enqi(handle, parameter, value)

Read an integer value from the output.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – Where the value will be returned

Returns

The error indicator for the function

idba_enqb(handle, parameter, value)

Read a byte value from the output.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – Where the value will be returned

Returns

The error indicator for the function

idba_enqr(handle, parameter, value)

Read a real value from the output.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – Where the value will be returned

Returns

The error indicator for the function

idba_enqd(handle, parameter, value)

Read a real*8 value from the output.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – Where the value will be returned

Returns

The error indicator for the function

idba_enqc(handle, parameter, value, value_len)

Read a character value from the output.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

• value – Where the value will be returned

Returns

The error indicator for the function

idba_unset(handle, parameter)

Remove one value from the input.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Parameter to remove. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in Input/output/query parameters.

Returns

The error indicator for the function

idba_unsetb(handle)

Remove all Bxxyyy values from the input.

Parameters

• handle – Handle to a DB-All.e session

idba_unsetall(handle)

Completely clear the input, removing all values.

Parameters

• handle – Handle to a DB-All.e session

idba_set_station_context(handle)

Signal that the input values that are set are related to station values instead of normal variables.

Parameters

• handle – Handle to a DB-All.e session

Returns

The error indicator for the function

Input/output shortcuts

idba_setlevel(handle, ltype1, l1, ltype2, l2)

Set all level information.

Parameters

• handle – Handle to a DB-All.e session

• ltype1 – Level type to set in the input record

• l1 – L1 to set in the input record

• ltype2 – Level type to set in the input record

• l2 – L2 to set in the input record

Returns

The error indicator for the function

idba_settimerange(handle, ptype, p1, p2)

Set all time range information.

Parameters

• handle – Handle to a DB-All.e session

• ptype – P indicator to set in the input record

• p1 – P1 to set in the input record

• p2 – P2 to set in the input record

Returns

The error indicator for the function

idba_setdate(handle, year, month, day, hour, min, sec)

Set all date information.

Parameters

• handle – Handle to a DB-All.e session

• year – Year to set in the input record

• month – Month to set in the input

• day – Day to set in the input

• hour – Hour to set in the input

• min – Minute to set in the input

• sec – Second to set in the input

Returns

The error indicator for the function

idba_setdatemin(handle, year, month, day, hour, min, sec)

Set the minimum date for a query.

Parameters

• handle – Handle to a DB-All.e session

• year – Minimum year to set in the query

• month – Minimum month to set in the query

• day – Minimum day to set in the query

• hour – Minimum hour to set in the query

• min – Minimum minute to set in the query

• sec – Minimum second to set in the query

Returns

The error indicator for the function

idba_setdatemax(handle, year, month, day, hour, min, sec)

Set the maximum date for a query.

Parameters

• handle – Handle to a DB-All.e session

• year – Maximum year to set in the query

• month – Maximum month to set in the query

• day – Maximum day to set in the query

• hour – Maximum hour to set in the query

• min – Maximum minute to set in the query

• sec – Maximum second to set in the query

Returns

The error indicator for the function

idba_enqlevel(handle, ltype1, l1, ltype2, l2)

Read all level information.

Parameters

• handle – Handle to a DB-All.e session

• ltype1 – Type of the first level from the output record

• l1 – L1 from the output record

• ltype2 – Type of the second level from the output record

• l2 – L2 from the output record

Returns

The error indicator for the function

idba_enqtimerange(handle, ptype, p1, p2)

Read all time range information.

Parameters

• handle – Handle to a DB-All.e session

• ptype – P indicator from the output record

• p1 – P1 from the output record

• p2 – P2 from the output record

Returns

The error indicator for the function

idba_enqdate(handle, year, month, day, hour, min, sec)

Read all date information.

Parameters

• handle – Handle to a DB-All.e session

• year – Year from the output record

• month – Month from the output record

• day – Day from the output record

• hour – Hour from the output record

• min – Minute from the output record

• sec – Second from the output record

Returns

The error indicator for the function

Action routines

idba_reinit_db(handle, repinfofile)

Reinitialize the database, removing all data and loading report information.

Parameters

• handle – Handle to a DB-All.e session

• repinfofile – CSV file with the default report informations. See idba_reset() documentation for the format of the file.

Returns

The error indicator for the function

It requires the database to be opened in rewrite mode.

idba_query_stations(handle, count)

Query the stations in the database.

Parameters

• handle – Handle to a DB-All.e session

• count – The count of elements

Returns

The error indicator for the function

Results are retrieved using idba_next_station().

There is no guarantee on the ordering of results of idba_query_stations()/idba_next_station().

idba_next_station(handle)

Retrieve the data about one station.

Parameters

• handle – Handle to a DB-All.e session

Returns

The error indicator for the function

After invocation, the output record is filled with information about the station and its station values.

If there are no more stations to read, the function will fail with DBA_ERR_NOTFOUND.

idba_query_data(handle, count)

Query the data in the database.

Parameters

• handle – Handle to a DB-All.e session

• count – Number of values returned by the function

Returns

The error indicator for the function

Results are retrieved using idba_next_data().

Results are sorted by (in order): ana_id, datetime, level, time range, varcode. The ana_id changes slowest, and the varcode changes fastest.

Ordering by ana_id effectively does grouping by station rather than ordering.

Sort order can change in the future, with the invariant that the slowest to change remains ana_id, followed by datetime, and the fastest to change remains the varcode.

idba_next_data(handle, parameter, parameter_len)

Retrieve the data about one value.

Parameters

• handle – Handle to a DB-All.e session

• parameter – Contains the variable code of the parameter retrieved by this fetch

Returns

The error indicator for the function

After invocation, the output record is filled with information about the value.

If there are no more values to read, the function will fail with DBA_ERR_NOTFOUND.

idba_insert_data(handle)

Insert a new value in the database.

Parameters

• handle – Handle to a DB-All.e session

Returns

The error indicator for the function

This function will fail if the database is open in data readonly mode, and it will refuse to overwrite existing values if the database is open in data add mode.

If the database is open in station reuse mode, the station values provided on input will be used to create a station record if it is missing, but will be ignored if it is already present. If it is open in station rewrite mode instead, the station values on input will be used to replace all the existing station values.

idba_remove_data(handle)

Remove from the database all values that match the query.

Parameters

• handle – Handle to a DB-All.e session

Returns

The error indicator for the function

This function will fail unless the database is open in data rewrite mode.

idba_remove_all(handle)

Remove all values from the database.

Parameters

• handle – Handle to a DB-All.e session

Returns

The error indicator for the function

The difference with idba_reinit_db() is that it preserves the existing report information.

idba_query_attributes(handle, count)

Query attributes about a variable.

Parameters

• handle – Handle to a DB-All.e session

• count – Number of values returned by the function

Returns

The error indicator for the function

The variable queried is either:

• the last variable returned by idba_next_data()

• the last variable inserted by idba_insert_data()

• the variable selected by settings *context_id and *var_related.

Results are retrieved using idba_next_attribute().

idba_next_attribute(handle, parameter, parameter_len)

Retrieve one attribute from the result of idba_query_attributes().

Parameters

• handle – Handle to a DB-All.e session

• parameter – Contains the ID of the parameter retrieved by this fetch

Returns

The error indicator for the function

idba_insert_attributes(handle)

Insert new attributes for a variable.

Parameters

• handle – Handle to a DB-All.e session

Returns

The error indicator for the function

The variable is either:

• the last variable returned by idba_next_data()

• the last variable inserted by idba_insert_data()

• the variable selected by settings *context_id and *var_related.

The attributes that will be inserted are all those set by the functions idba_seti(), idba_setc(), idba_setr(), idba_setd(), using an asterisk in front of the variable name.

Contrarily to idba_insert_data(), this function resets all the attribute information (and only attribute information) previously set in input, so the values to be inserted need to be explicitly set every time.

This function will fail if the database is open in attribute readonly mode, and it will refuse to overwrite existing values if the database is open in attribute add mode.

idba_remove_attributes(handle)

Remove attribute information for a variable.

Parameters

• handle – Handle to a DB-All.e session

Returns

The error indicator for the function

The variable is either:

• the last variable returned by idba_next_data()

• the last variable inserted by idba_insert_data()

• the variable selected by settings *context_id and *var_related.

The attribute informations to be removed are selected with:

idba_setc(handle, "*varlist", "*B33021,*B33003");

Message routines

idba_messages_open_input(handle, filename, mode, format, simplified)

Open a BUFR, or CREX, file for reading.

Parameters

• handle – Handle to a DB-All.e session

• filename – The file name

• mode – The opening mode. See the mode parameter of libc’s fopen() call for details.

• format – The file format ("BUFR", or "CREX")

• simplified – true if the file is imported in simplified mode, false if it is imported in precise mode. This controls approximating levels and time ranges to standard values.

Returns

The error indicator for the function

Each session can only have one open input file: if one was previously open, it is closed before opening the new one.

idba_messages_open_output(handle, filename, mode, format)

Open a BUFR, or CREX file for writing.

Parameters

• handle – Handle to a DB-All.e session

• filename – The file name

• mode – The opening mode. See the mode parameter of libc’s fopen() call for details.

• format – The file format ("BUFR", or "CREX")

Returns

The error indicator for the function

Each session can only have one open output file: if one was previously open, it is closed before opening the new one.

idba_messages_read_next(handle, found)

Read the next message and import it in the database.

Parameters

• handle – Handle to a DB-All.e session

• found – True if a message has been imported, false if we are at the end of the input file.

Returns

The error indicator for the function

The access mode of the session controls how data is imported:

• station and data mode cannot be "read".

• if data mode is "add", existing data will not be overwritten.

• if attribute mode is "read", attributes will not be imported.

idba_messages_write_next(handle, template_name)

Export the data from the database that match the current query and add them to the current message.

Parameters

• handle – Handle to a DB-All.e session

• template_name – The template name used to decide the layout of variables in the messages that are exported.

Returns

The error indicator for the function

Pretty-printing routines

idba_describe_level(handle, ltype1, l1, ltype2, l2, result, result_len)

Format the description of a level given its value.

Parameters

• handle – Handle to a DB-All.e session

• ltype1 – Level type to set in the input record

• l1 – L1 to set in the input record

• ltype2 – Level type to set in the input record

• l2 – L2 to set in the input record

• result – The string with the description of the level.

Returns

The error indicator for the function

idba_describe_timerange(handle, ptype, p1, p2, result, result_len)

Format the description of a time range given its value.

Parameters

• handle – Handle to a DB-All.e session

• ptype – P indicator to set in the input record

• p1 – P1 to set in the input record

• p2 – P2 to set in the input record

• result – The string with the description of the time range.

Returns

The error indicator for the function

idba_describe_var(handle, varcode, value, result, result_len)

Format the description of a variable given its varcode and its value.

Parameters

• handle – Handle to a DB-All.e session

• varcode – B table code of the variable (“Bxxyyy”)

• value – Value of the variable, as read with idba_enqc()

• result – The string with the description of the time range.

Returns

The error indicator for the function