Fortran dballe functions

Summary of routines

Error management routines

Session routines

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

Input/output routines

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

Input/output shortcuts

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

Action routines

Message routines

Pretty-printing routines

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.

return

The error code.

rtype

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)

arg message

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

arg message_len

The size of the string buffer passed as message

return

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)

arg message

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

arg message_len

The size of the string buffer passed as message

return

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)

arg message

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

arg message_len

The size of the string buffer passed as message

return

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.

arg 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.

arg func

The function to be called.

arg data

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

arg handle

A handle that can be used to remove the callback

return

The error indicator for the function

rtype

int

idba_error_remove_callback(handle)

Remove a previously set callback.

arg handle

The handle previously returned by idba_error_set_callback

return

The error indicator for the function

rtype

int

idba_default_error_handler

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.

arg url

The URL of the database to use

arg user

Used in the past, now it is ignored.

arg password

Used in the past, now it is ignored.

arg dbahandle

The database handle that can be passed to idba_begin to work with the database.

return

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.

arg dbahandle

The database handle to close.

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

Open a new session.

arg dbahandle

The main DB-ALLe connection handle

arg handle

The session handle created by the function

arg anaflag

station values access level

arg dataflag

data values access level

arg attrflag

attribute access level

return

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.

arg handle

The session handle returned by the function

arg filename

Name of the file to open

arg mode

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

arg type

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

return

The error indicator for the function

idba_commit(handle)

Close a session.

arg handle

Handle to the session to be closed.

Input/output routines

idba_seti(handle, parameter, value)

Set an integer value in input.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

The value to assign to the parameter

return

The error indicator for the function

idba_setb(handle, parameter, value)

Set a byte value in input.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

The value to assign to the parameter

return

The error indicator for the function

idba_setr(handle, parameter, value)

Set a real value in input.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

The value to assign to the parameter

return

The error indicator for the function

idba_setd(handle, parameter, value)

Set a real*8 value in input.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

The value to assign to the parameter

return

The error indicator for the function

idba_setc(handle, parameter, value)

Set a character value in input.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

The value to assign to the parameter

return

The error indicator for the function

idba_enqi(handle, parameter, value)

Read an integer value from the output.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

Where the value will be returned

return

The error indicator for the function

idba_enqb(handle, parameter, value)

Read a byte value from the output.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

Where the value will be returned

return

The error indicator for the function

idba_enqr(handle, parameter, value)

Read a real value from the output.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

Where the value will be returned

return

The error indicator for the function

idba_enqd(handle, parameter, value)

Read a real*8 value from the output.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

Where the value will be returned

return

The error indicator for the function

idba_enqc(handle, parameter, value, value_len)

Read a character value from the output.

arg handle

Handle to a DB-All.e session

arg 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.

arg value

Where the value will be returned

return

The error indicator for the function

idba_unset(handle, parameter)

Remove one value from the input.

arg handle

Handle to a DB-All.e session

arg 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.

return

The error indicator for the function

idba_unsetb(handle)

Remove all Bxxyyy values from the input.

arg handle

Handle to a DB-All.e session

idba_unsetall(handle)

Completely clear the input, removing all values.

arg 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.

arg handle

Handle to a DB-All.e session

return

The error indicator for the function

Input/output shortcuts

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

Set all level information.

arg handle

Handle to a DB-All.e session

arg ltype1

Level type to set in the input record

arg l1

L1 to set in the input record

arg ltype2

Level type to set in the input record

arg l2

L2 to set in the input record

return

The error indicator for the function

idba_settimerange(handle, ptype, p1, p2)

Set all time range information.

arg handle

Handle to a DB-All.e session

arg ptype

P indicator to set in the input record

arg p1

P1 to set in the input record

arg p2

P2 to set in the input record

return

The error indicator for the function

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

Set all date information.

arg handle

Handle to a DB-All.e session

arg year

Year to set in the input record

arg month

Month to set in the input

arg day

Day to set in the input

arg hour

Hour to set in the input

arg min

Minute to set in the input

arg sec

Second to set in the input

return

The error indicator for the function

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

Set the minimum date for a query.

arg handle

Handle to a DB-All.e session

arg year

Minimum year to set in the query

arg month

Minimum month to set in the query

arg day

Minimum day to set in the query

arg hour

Minimum hour to set in the query

arg min

Minimum minute to set in the query

arg sec

Minimum second to set in the query

return

The error indicator for the function

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

Set the maximum date for a query.

arg handle

Handle to a DB-All.e session

arg year

Maximum year to set in the query

arg month

Maximum month to set in the query

arg day

Maximum day to set in the query

arg hour

Maximum hour to set in the query

arg min

Maximum minute to set in the query

arg sec

Maximum second to set in the query

return

The error indicator for the function

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

Read all level information.

arg handle

Handle to a DB-All.e session

arg ltype1

Type of the first level from the output record

arg l1

L1 from the output record

arg ltype2

Type of the second level from the output record

arg l2

L2 from the output record

return

The error indicator for the function

idba_enqtimerange(handle, ptype, p1, p2)

Read all time range information.

arg handle

Handle to a DB-All.e session

arg ptype

P indicator from the output record

arg p1

P1 from the output record

arg p2

P2 from the output record

return

The error indicator for the function

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

Read all date information.

arg handle

Handle to a DB-All.e session

arg year

Year from the output record

arg month

Month from the output record

arg day

Day from the output record

arg hour

Hour from the output record

arg min

Minute from the output record

arg sec

Second from the output record

return

The error indicator for the function

Action routines

idba_reinit_db(handle, repinfofile)

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

arg handle

Handle to a DB-All.e session

arg repinfofile

CSV file with the default report informations. See idba_reset documentation for the format of the file.

return

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.

arg handle

Handle to a DB-All.e session

arg count

The count of elements

return

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.

arg handle

Handle to a DB-All.e session

return

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.

arg handle

Handle to a DB-All.e session

arg count

Number of values returned by the function

return

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.

arg handle

Handle to a DB-All.e session

arg parameter

Contains the variable code of the parameter retrieved by this fetch

return

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.

arg handle

Handle to a DB-All.e session

return

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.

arg handle

Handle to a DB-All.e session

return

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.

arg handle

Handle to a DB-All.e session

return

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.

arg handle

Handle to a DB-All.e session

arg count

Number of values returned by the function

return

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().

arg handle

Handle to a DB-All.e session

arg parameter

Contains the ID of the parameter retrieved by this fetch

return

The error indicator for the function

idba_insert_attributes(handle)

Insert new attributes for a variable.

arg handle

Handle to a DB-All.e session

return

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.

arg handle

Handle to a DB-All.e session

return

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.

arg handle

Handle to a DB-All.e session

arg filename

The file name

arg mode

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

arg format

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

arg 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.

return

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.

arg handle

Handle to a DB-All.e session

arg filename

The file name

arg mode

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

arg format

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

return

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_write_next(handle, template_name)

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

arg handle

Handle to a DB-All.e session

arg template_name

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

return

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.

arg handle

Handle to a DB-All.e session

arg ltype1

Level type to set in the input record

arg l1

L1 to set in the input record

arg ltype2

Level type to set in the input record

arg l2

L2 to set in the input record

arg result

The string with the description of the level.

return

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.

arg handle

Handle to a DB-All.e session

arg ptype

P indicator to set in the input record

arg p1

P1 to set in the input record

arg p2

P2 to set in the input record

arg result

The string with the description of the time range.

return

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.

arg handle

Handle to a DB-All.e session

arg varcode

B table code of the variable (“Bxxyyy”)

arg value

Value of the variable, as read with idba_enqc

arg result

The string with the description of the time range.

return

The error indicator for the function