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