Products Support Documentation Download
Initialization Functions
Collaboration diagram for Initialization Functions:

Functions

RDM_RETCODE rdm_dbGetOption (RDM_DB db, const RDM_TCHAR_T *keyword, RDM_TCHAR_T *optValue, size_t bytesIn, size_t *bytesOut)
 Get a single database option into a string. More...
 
RDM_RETCODE rdm_dbGetOptions (RDM_DB db, RDM_TCHAR_T *optString, size_t bytesIn, size_t *bytesOut)
 Get RDM database specific options. More...
 
RDM_RETCODE rdm_dbOpen (RDM_DB db, const RDM_TCHAR_T *dbNameSpec, RDM_OPEN_MODE mode)
 Open an existing RDM database using the specified database handle. More...
 
RDM_RETCODE rdm_dbSetCatalog (RDM_DB db, const RDM_TCHAR_T *catalog)
 Associate a catalog with an allocated database. More...
 
RDM_RETCODE rdm_dbSetCatalogFromFile (RDM_DB db, const RDM_TCHAR_T *catfile)
 Associate a catalog with an allocated database. More...
 
RDM_RETCODE rdm_dbSetOption (RDM_DB db, const RDM_TCHAR_T *keyword, const RDM_TCHAR_T *strValue)
 Set a single RDM option from a string. More...
 
RDM_RETCODE rdm_dbSetOptions (RDM_DB db, const RDM_TCHAR_T *optString)
 Set RDM options. More...
 
RDM_RETCODE rdm_dbTriggersOff (RDM_DB db)
 Disable use of triggers for an open database. More...
 
RDM_RETCODE rdm_dbTriggersOn (RDM_DB db)
 Enable use of triggers for an open database. More...
 
RDM_RETCODE rdm_dbTriggersStatus (RDM_DB db, RDM_TRIGGERS_STATUS *pStat)
 Check the triggers use status for a database. More...
 

Detailed Description

Initialization functions for the core database API. All the fuctions here except for rdm_dbTriggersOn() are located in RDM DB Engine Library. Linker option:

    -lrdmrdm

Function Documentation

◆ rdm_dbGetOption()

RDM_RETCODE rdm_dbGetOption ( RDM_DB  db,
const RDM_TCHAR_T keyword,
RDM_TCHAR_T optValue,
size_t  bytesIn,
size_t *  bytesOut 
)

#include <rdmdbapi.h>

Get a single database option into a string.

This function retrieves a single database option into a string value. The key parameter accepts the key for the option to get.

Options are defined using keys or properties. Every key has a name and a value, delimited by an equals sign (=). The key name appears to the left of the equals sign. Key names are not case-sensitive. Unless otherwise noted, values are not case-sensitive.

Key Value Description
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
item_format Specify row storage form.
locale Specify database locale.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
db_size Specify the maximum database size allocation.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_write_chunk_sizeSpecify the vacuum scan size for pack files.
vacuum_read_chunk_size Specify the vacuum write size for pack files.
idindex_flush_threshold_on_close Specify the threshold for flushing the ID-index when the last database user closes the database.
idindex_flush_threshold Specify the threshold for flushing the ID-index.
idindex_cache_size Specify the size of the ID-index cache in byte.

Return values
sOKAYNormal, successful return.
eINVOPTIONInvalid option is specified.
eINVOPTIONVALUEInvalid option value.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbGetOptions
rdm_dbSetOption
rdm_dbFree
Parameters
[in]dbA valid RDM database handle
[in]keywordsingle option keyword
[out]optValueoption value in string
[in]bytesIn# of bytes for pszValue
[out]bytesOut# of bytes needed/used for output

◆ rdm_dbGetOptions()

RDM_RETCODE rdm_dbGetOptions ( RDM_DB  db,
RDM_TCHAR_T optString,
size_t  bytesIn,
size_t *  bytesOut 
)

#include <rdmdbapi.h>

Get RDM database specific options.

The function returns a semicolon-delimited list of options in the pair of keyword and value for the options specified in 'keywords.'

key should be a list of option values. If key is NULL, the function returns the pairs for all available options. If key is an empty string, the function returns an empty string.

Options are defined using keys or properties. Every key has a name and a value, delimited by an equals sign (=). The key name appears to the left of the equals sign. Key names are not case-sensitive. Unless otherwise noted, values are not case-sensitive.

Key Value Description
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
item_format Specify row storage form.
locale Specify database locale.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
db_size Specify the maximum database size allocation.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_write_chunk_sizeSpecify the vacuum scan size for pack files.
vacuum_read_chunk_size Specify the vacuum write size for pack files.
idindex_flush_threshold_on_close Specify the threshold for flushing the ID-index when the last database user closes the database.
idindex_flush_threshold Specify the threshold for flushing the ID-index.
idindex_cache_size Specify the size of the ID-index cache in byte.

Return values
sOKAYNormal, successful return.
eINVOPTIONInvalid option is specified.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbGetOption
rdm_dbSetOptions
rdm_dbFree
Parameters
[in]dbA valid RDM database handle
[out]optStringoption string
[in]bytesIn# of bytes for optString
[out]bytesOutresult # of bytes

◆ rdm_dbOpen()

RDM_RETCODE rdm_dbOpen ( RDM_DB  db,
const RDM_TCHAR_T dbNameSpec,
RDM_OPEN_MODE  mode 
)

#include <rdmdbapi.h>

Open an existing RDM database using the specified database handle.

This function opens a database for access in a shared, read-only, or exclusive mode.

If the specified handle already has an open database associate with it that database will be closed.

Database Unions

A database union is a unified view of the data in more than one identically structured database. It makes the multiple databases appear as one. A union of multiple databases differs from having multiple databases open in that:

  • unioned databases must have identical structures
  • the union is viewed as one database, using one database handle
  • it is read-only

Database unions are intended to be used with distributed databases or database mirrors to create a single, merged view of data that is owned and updated in separate locations by separate entities.

A complete database specification can be a union of 2 or more databases, which is represented by database names separated by "|" symbols:

  • db_namespec[ | db_namespec]...

Each database included in a union must have an identical table definition. When opened as a union, the data will appear to come from one database, whether it is read through record or key scanning.

A union is read only, and an error will be returned if a union is specified but the open mode is not RDM_OPEN_READONLY.

Locking Requirements
None.
Return values
sOKAYNormal, successful return.
eINVDBNAMESPECInvalid database name specification.
eINVENCRYPTInvalid encryption key.
eLOCALEMISMATCHAttempt to open database with incorrect (or no) locale.
eNODBDatabase not found.
eUNAVAILRequested resource not available.
eOPENMODEInvalid db open mode.
sTRIGGERSREADONLYThe database contains triggers and rdm_dbTriggersOn() or rdm_dbTriggersOff() has not been called so the database is in read-only mode.
See also
rdm_rdmAllocDatabase
rdm_dbSetOptions
rdm_dbSetEncrypt
rdm_dbEncrypt
rdm_dbTriggersOn
rdm_dbSetCatalog
rdm_dbGetRows
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbClose
rdm_dbFree
Parameters
[in]dbAn allocated RDM_DB
[in]dbNameSpecThe database name specification
[in]modeThe database open mode
Examples:
tutorials/HelloWorld/hello_worldTutorial_main.c.

◆ rdm_dbSetCatalog()

RDM_RETCODE rdm_dbSetCatalog ( RDM_DB  db,
const RDM_TCHAR_T catalog 
)

#include <rdmdbapi.h>

Associate a catalog with an allocated database.

This function associates a catalog with an allocated database. The RDM_DB must not have a database open. When the database is opened with rdm_dbOpen() the associated catalog will be used. If a catalog is found on disk then the specified catalog and stored catalog will be compared to ensure that they are compatible.

Catalog can either be in the compiled format or can be a series of SQL statements.

Locking Requirements
None
Return values
sOKAYNormal, successful return.
eDBOPENDatabase already opened in this task.
eBADCATBad catalog (error trying to read catalog file).
eDDL_SYNTAXSyntax error.
ePRECOMMITTEDA precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eLOCALEMISMATCHAttempt to open database with incorrect (or no) locale.
See also
rdm_tfsAllocDatabase
rdm_dbSetCatalogFromFile
rdm_dbAlterCatalog
rdm_dbOpen
ddl_ug
Parameters
[in]dbThe allocated, but unopened RDM_DB the catalog will be associated with
[in]catalogThe catalog definition to be associated with db
Examples:
tutorials/HelloWorld/hello_worldTutorial_main.c.

◆ rdm_dbSetCatalogFromFile()

RDM_RETCODE rdm_dbSetCatalogFromFile ( RDM_DB  db,
const RDM_TCHAR_T catfile 
)

#include <rdmdbapi.h>

Associate a catalog with an allocated database.

This function associates a catalog with an allocated database. The RDM_DB must not have a database open. When the database is opened with rdm_dbOpen() the associated catalog will be used. If a catalog is found on disk then the specified catalog and stored catalog will be compared to ensure that they are compatible.

Catalog can either be a catalog compiled RDM catalog file (.cat) or it can be a file containing a series for SQL DDL commands (.sdl). An error will be returned if a file with any other extension is specified.

Locking Requirements
None.
Return values
sOKAYNormal, successful return.
eDBOPENDatabase already opened in this task.
eBADCATBad catalog (error trying to read catalog file).
eDDL_SYNTAXSyntax error.
ePRECOMMITTEDA precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eLOCALEMISMATCHAttempt to open database with incorrect (or no) locale.
eFILEOPENUnable to open file.
See also
rdm_tfsAllocDatabase
rdm_dbSetCatalogFromFile
rdm_dbAlterCatalog
rdm_dbOpen
rdm_dbFree
rdm_dbOpen
rdm_dbSetCatalog
rdm_dbAlterCatalog
ddl_ug
Parameters
[in]dbThe allocated, but unopened RDM_DB the catalog will be associated with
[in]catfileThe name of the file containing the catalog

◆ rdm_dbSetOption()

RDM_RETCODE rdm_dbSetOption ( RDM_DB  db,
const RDM_TCHAR_T keyword,
const RDM_TCHAR_T strValue 
)

#include <rdmdbapi.h>

Set a single RDM option from a string.

This function is used to set a single RDM database option from a string value. The key parameter accepts the key for the option to set.

Options are defined using keys or properties. Every key has a name and a value, delimited by an equals sign (=). The key name appears to the left of the equals sign. Key names are not case-sensitive. Unless otherwise noted, values are not case-sensitive.

Key Value Description
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
item_format Specify row storage form.
locale Specify database locale.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
db_size Specify the maximum database size allocation.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_write_chunk_sizeSpecify the vacuum scan size for pack files.
vacuum_read_chunk_size Specify the vacuum write size for pack files.
idindex_flush_threshold_on_close Specify the threshold for flushing the ID-index when the last database user closes the database.
idindex_flush_threshold Specify the threshold for flushing the ID-index.
idindex_cache_size Specify the size of the ID-index cache in byte.

Locking Requirements
None
Return values
sOKAYNormal, successful return.
eDBOPENDatabase already opened in this task.
eINVOPTIONInvalid option is specified.
eINVOPTIONVALUEInvalid option value.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbSetOptions
rdm_dbGetOption
rdm_dbSetErrorHandler
rdm_dbFree
Parameters
[in]dbA valid RDM database handle
[in]keywordSingle option keyword
[in]strValueoption value in string

◆ rdm_dbSetOptions()

RDM_RETCODE rdm_dbSetOptions ( RDM_DB  db,
const RDM_TCHAR_T optString 
)

#include <rdmdbapi.h>

Set RDM options.

This function is used to set any RDM database options.

The optString is a key value pair in the form of "key=value".

The options will be inherited from the option values stored in the TFS handle when the database handle is created. Changes to the option values stored in the TFS handle will not affect those of the database handles that have already been allocated except for the Timeout option, which changes the timeout value of the database that's already opened.

The options set with this function will not affect the parent TFS handle.

The keys supported are

Options are defined using keys or properties. Every key has a name and a value, delimited by an equals sign (=). The key name appears to the left of the equals sign. Key names are not case-sensitive. Unless otherwise noted, values are not case-sensitive.

Key Value Description
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
item_format Specify row storage form.
locale Specify database locale.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
db_size Specify the maximum database size allocation.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_write_chunk_sizeSpecify the vacuum scan size for pack files.
vacuum_read_chunk_size Specify the vacuum write size for pack files.
idindex_flush_threshold_on_close Specify the threshold for flushing the ID-index when the last database user closes the database.
idindex_flush_threshold Specify the threshold for flushing the ID-index.
idindex_cache_size Specify the size of the ID-index cache in byte.

Locking Requirements
None.
Return values
sOKAYNormal, successful return.
eDBOPENDatabase already opened in this task.
eINVOPTIONInvalid option is specified.
eINVOPTIONVALUEInvalid option value.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbSetOption
rdm_dbGetOptions
rdm_dbSetErrorHandler
rdm_dbFree
rdm_dbFlushIdIndex
rdm_dbCreateNewPackFile
rdm_dbVacuum
Parameters
[in]dbA valid RDM database handle
[in]optStringThe option string

◆ rdm_dbTriggersOff()

RDM_RETCODE rdm_dbTriggersOff ( RDM_DB  db)

#include <rdmdbapi.h>

Disable use of triggers for an open database.

This function turns off the use of triggers on the opened database specified by the RDM_DB handle. This allows non-SQL applications to make changes to database tables on which triggers are defined without executing those triggers.

Locking Requirements
None.
Return values
sOKAYNormal, successful return.
eDBNOTOPENDatabase not open.
See also
rdm_dbTriggersOn
rdm_dbTriggersStatus
Parameters
[in]dbA valid RDM database handle

◆ rdm_dbTriggersOn()

RDM_RETCODE rdm_dbTriggersOn ( RDM_DB  db)

#include <rdmdbapi.h>

Enable use of triggers for an open database.

This function turns on the use of triggers on the database specified by the RDM_DB handle. This is intended to be called by non-SQL applications so that SQL is linked with the application in order to control the execution of triggers.

This function is located in RDM SQL Engine Library. Linker option:

    -lrdmrsql
Locking Requirements
None.
Return values
sOKAYNormal, successful return.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbTriggersOff
rdm_dbTriggersStatus
rdm_dbSetOptions
Parameters
[in]dbA valid RDM database handle

◆ rdm_dbTriggersStatus()

RDM_RETCODE rdm_dbTriggersStatus ( RDM_DB  db,
RDM_TRIGGERS_STATUS pStat 
)

#include <rdmdbapi.h>

Check the triggers use status for a database.

This function sets pStat to indicate the triggers status for the database specified by db as follows:

Status Description
RDM_TRIGGERS_UNDEFINED rdm_dbTriggersOn() not (yet) called.
RDM_TRIGGERS_ON rdm_dbTriggersOn() has been called.
RDM_TRIGGERS_OFF rdm_dbTriggersOff() has been called.
Locking Requirements
None.
Return values
sOKAYNormal, successful return.
eDBNOTOPENDatabase not open.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbTriggersOn
rdm_dbTriggersOff
rdm_dbSetOptions
Parameters
[in]dbA valid RDM database handle
[out]pStatPointer to triggers status result variable