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_dbCompileCatalog (RDM_DB db, const RDM_TCHAR_T *schema)
 Associate a schema with an allocated database. More...
 
RDM_RETCODE rdm_dbCompileCatalogFromFile (RDM_DB db, const RDM_TCHAR_T *schemafile)
 Associate a catalog with an allocated database. More...
 
RDM_RETCODE rdm_dbLoadCatalog (RDM_DB db, const RDM_TCHAR_T *catalog)
 Associate a catalog with an allocated database. More...
 
RDM_RETCODE rdm_dbLoadCatalogFromFile (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_dbCompileCatalog()

RDM_RETCODE rdm_dbCompileCatalog ( RDM_DB  db,
const RDM_TCHAR_T schema 
)

#include <rdmdbapi.h>

Associate a schema with an allocated database.

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

The format of the schema is 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_dbLoadCatalogFromFile
rdm_dbAlterCatalog
rdm_dbOpen
ddl_ug
Parameters
[in]dbThe allocated, but unopened RDM_DB the catalog will be associated with
[in]schemaThe schema definition to be associated with db

◆ rdm_dbCompileCatalogFromFile()

RDM_RETCODE rdm_dbCompileCatalogFromFile ( RDM_DB  db,
const RDM_TCHAR_T schemafile 
)

#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 specified schema is compiled the resulting catalog is associated with the database handle and will be used in a subsequent call to rdm_dbOpen(). If a catalog is found on disk then the resulting catalog and stored catalog will be compared to ensure that they are compatible.

Schemafile must 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_dbLoadCatalogFromFile
rdm_dbAlterCatalog
rdm_dbOpen
rdm_dbFree
rdm_dbOpen
rdm_dbSetCatalog
rdm_dbLoadCatalog
rdm_dbAlterCatalog
ddl_ug
Parameters
[in]dbThe allocated, but unopened RDM_DB the catalog will be associated with
[in]schemafileThe name of the file containing the catalog

◆ 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 keyword argument accepts the "key" for the function to retreive into the buffer supplied by the optValue argument.

The bytesIn argument is the length of the optValue buffer.

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 optValue
[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 keyword/value pairs for all available options into the optSting buffer.

Note
If the optString argument is NULL, the function returns the required size in bytes of the destination string in bytesOut.

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

RDM_RETCODE rdm_dbLoadCatalog ( 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 must be in the compiled format.

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_dbLoadCatalogFromFile
rdm_dbSetCatalogFromFile
rdm_dbCompileCatalogFromFile
rdm_dbSetCatalog
rdm_dbCompileCatalog
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

◆ rdm_dbLoadCatalogFromFile()

RDM_RETCODE rdm_dbLoadCatalogFromFile ( 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.

catfile can must be a catalog compiled RDM catalog file (.cat). 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_dbCompileCatalogFromFile
rdm_dbAlterCatalog
rdm_dbOpen
rdm_dbFree
rdm_dbOpen
rdm_dbLoadCatalog
rdm_dbCompileCatalog
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_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_dbLoadCatalog
rdm_dbCompileCatalog
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_dbLoadCatalogFromFile
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
Examples:
tutorials/HelloWorld/hello_worldTutorial_main.c.

◆ 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