Functions
Databases
kvaDbLib

Initialization, setting protocols and flags. More...

## Functions
KvaDbStatus | kvaDbOpen (KvaDbHnd *dh)
KvaDbStatus | kvaDbAddFile (KvaDbHnd dh, const char *filename)
KvaDbStatus | kvaDbSetDummyFileName (KvaDbHnd dh, const char *filename)
KvaDbStatus | kvaDbCreate (KvaDbHnd dh, const char *localName, const char *filename)
KvaDbStatus | kvaDbGetDatabaseName (KvaDbHnd dh, char *buf, size_t buflen)
KvaDbStatus | kvaDbGetVersion (int *major, int *minor, int *build)
KvaDbStatus | kvaDbGetErrorText (KvaDbStatus error, char *buf, size_t buflen)
KvaDbStatus | kvaDbClose (KvaDbHnd dh)
KvaDbStatus | kvaDbWriteFile (KvaDbHnd dh, char *filename)
KvaDbStatus | kvaDbReadFile (KvaDbHnd dh, char *filename)
KvaDbStatus | kvaDbGetFlags (KvaDbHnd dh, unsigned int *flags)
KvaDbStatus | kvaDbGetProtocol (KvaDbHnd dh, KvaDbProtocolType *prot)
KvaDbStatus | kvaDbGetProtocolProperties (KvaDbProtocolType prot, KvaDbProtocolProperties *prop)
KvaDbStatus | kvaDbSetFlags (KvaDbHnd dh, unsigned int flags)
KvaDbStatus | kvaDbSetProtocol (KvaDbHnd dh, KvaDbProtocolType prot)

## Detailed Description

Initialization, setting protocols and flags.

## Function Documentation

## ◆ kvaDbAddFile()

KvaDbStatus kvaDbAddFile | ( | KvaDbHnd | dh,
|  | const char * | filename
| ) |  |

This loads a database file into a handle created with kvaDbOpen().

Note
  This function is deprecated and will be replaced by kvaDbCreate()

Parameters

  [in] | dh | A handle database handle
  [in] | filename | A database file

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbCreate()

## ◆ kvaDbClose()

KvaDbStatus kvaDbClose | ( | KvaDbHnd | dh | ) |

This function closes an open database handle.

Parameters

  [in] | dh | A handle to a database

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbOpen()

Examples:
  candb_sample.c.

## ◆ kvaDbCreate()

KvaDbStatus kvaDbCreate | ( | KvaDbHnd | dh,
|  | const char * | localName,
|  | const char * | filename
| ) |  |

This function creates a new database in a handle created with kvaDbOpen(). There are three ways to call this function:

- To load data from an existing database file, set localName to `NULL` and set filename to the database file.

- To add an empty database, set localName to any name and set filename to `NULL`.

- To load data from an existing database file and give it a new name, set localName to the new name and set filename to the database file. In this case, it will attempt to use period as decimal separator by setting an appropriate locale. Note that setting locale is not thread safe.

Parameters

  [in] | dh | A database handle
  [in] | localName | The name of the database or `NULL`. The database name is used to create qualified names for messages and signals.
  [in] | filename | The database file or `NULL`

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbOpen(), kvaDbGetMsgQualifiedName(), kvaDbGetSignalQualifiedName()

Examples:
  candb_sample.c.

## ◆ kvaDbGetDatabaseName()

KvaDbStatus kvaDbGetDatabaseName | ( | KvaDbHnd | dh,
|  | char * | buf,
|  | size_t | buflen
| ) |  |

This function gets an existing database's name.

Parameters

  [in] | dh | A database handle
  [out] | buf | Buffer to receive database name. The database name is used to create qualified names for messages and signals.
  [in] | buflen | Buffer size in bytes.

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbOpen(), kvaDbGetMsgQualifiedName(), kvaDbGetSignalQualifiedName()

## ◆ kvaDbGetErrorText()

KvaDbStatus kvaDbGetErrorText | ( | KvaDbStatus | error,
|  | char * | buf,
|  | size_t | buflen
| ) |  |

This function converts error code to its written description

Parameters

  [in] | error | The error code to convert.
  [out] | buf | Buffer to receive error text.
  [in] | buflen | Buffer size in bytes.

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

## ◆ kvaDbGetFlags()

KvaDbStatus kvaDbGetFlags | ( | KvaDbHnd | dh,
|  | unsigned int * | flags
| ) |  |

Get the database flags.

Parameters

  [in] | dh | A handle to a database
  [out] | flags | The database flags, KVADB_DATABASE_xxx

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbReadFile()

Examples:
  candb_sample.c.

## ◆ kvaDbGetProtocol()

KvaDbStatus kvaDbGetProtocol | ( | KvaDbHnd | dh,
|  | KvaDbProtocolType * | prot
| ) |  |

Reads the protocol attribute value of a database

Parameters

  [in] | dh | A handle to a database
  [out] | prot | A handle to protocol type, KvaDbProtocolType

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbSetProtocol(), kvaDbGetProtocolProperties

## ◆ kvaDbGetProtocolProperties()

KvaDbStatus kvaDbGetProtocolProperties | ( | KvaDbProtocolType | prot,
|  | KvaDbProtocolProperties * | prop
| ) |  |

Returns properties of a given protocol, see KvaDbProtocolProperties

Parameters

  [in] | prot | Protocol type, KvaDbProtocolType
  [out] | prop | A handle to protocol properties, KvaDbProtocolProperties

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbGetProtocol()

## ◆ kvaDbGetVersion()

KvaDbStatus kvaDbGetVersion | ( | int * | major,
|  | int * | minor,
|  | int * | build
| ) |  |

This function gets the version of the KVADBLIB API DLL (kvadblib.dll).

Parameters

  [out] | major | Major version number.
  [out] | minor | Minor version number.
  [out] | build | Build number.

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

## ◆ kvaDbOpen()

KvaDbStatus kvaDbOpen | ( | KvaDbHnd * | dh | ) |

This function creates a new database handle.

Parameters

  [out] | dh | A handle to a new database

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbClose()

Examples:
  candb_sample.c.

## ◆ kvaDbReadFile()

KvaDbStatus kvaDbReadFile | ( | KvaDbHnd | dh,
|  | char * | filename
| ) |  |

Load a database from file into a handle created with kvaDbOpen(). This function will attempt to use period as decimal separator by setting an appropriate locale. Note that setting locale is not thread safe.

Parameters

  [out] | dh | A handle to a database
  [in] | filename | The name of the database file.

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbCreate()

Examples:
  candb_sample.c.

## ◆ kvaDbSetDummyFileName()

KvaDbStatus kvaDbSetDummyFileName | ( | KvaDbHnd | dh,
|  | const char * | filename
| ) |  |

This function creates a new database in a handle created with kvaDbOpen(). It is used when there is no file to read data from.

Note
  This function is deprecated and will be replaced by kvaDbCreate().

Parameters

  [in] | dh | A database handle
  [in] | filename | The the dummy filename to use for this database

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbCreate()

## ◆ kvaDbSetFlags()

KvaDbStatus kvaDbSetFlags | ( | KvaDbHnd | dh,
|  | unsigned int | flags
| ) |  |

Set the database flags.

Note
  This feature is currently not enabled.

Parameters

  [in] | dh | A database handle
  [in] | flags | The flags to set, KVADB_DATABASE_xxx

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbGetFlags()

## ◆ kvaDbSetProtocol()

KvaDbStatus kvaDbSetProtocol | ( | KvaDbHnd | dh,
|  | KvaDbProtocolType | prot
| ) |  |

Writes the protocol attribute value of a database

Parameters

  [in] | dh | A handle to a database
  [in] | prot | Protocol type value, KvaDbProtocolType

## ◆ kvaDbWriteFile()

KvaDbStatus kvaDbWriteFile | ( | KvaDbHnd | dh,
|  | char * | filename
| ) |  |

Write a database to file. This function will attempt to use period as decimal separator by setting an appropriate locale. Note that setting locale is not thread safe.

Parameters

  [in] | dh | A handle to a database
  [in] | filename | The name of the database file

Returns
  kvaDbOK (zero) if success
  kvaDbErr_xxx (negative) if failure

See also
  kvaDbReadFile()

Examples:
  candb_sample.c.