DB Initialization Functions
Collaboration diagram for DB Initialization Functions:

Functions

RDM_RETCODE rdm_dbGetOption (RDM_DB db, const char *keyword, char *optValue, size_t bytesIn, size_t *bytesOut)
Get a single database option into a string. More...
RDM_RETCODE rdm_dbGetOptions (RDM_DB db, char *optString, size_t bytesIn, size_t *bytesOut)
Get RDM database specific options. More...
RDM_RETCODE rdm_dbOpen (RDM_DB db, const char *dbNameSpec, RDM_OPEN_MODE mode)
Open an existing RDM database using the specified database handle. More...
RDM_RETCODE rdm_dbSetCatalog (RDM_DB db, const char *catalog)
Associate a catalog with an allocated database. More...
RDM_RETCODE rdm_dbSetCatalogFromFile (RDM_DB db, const char *catfile)
Associate a catalog with an allocated database. More...
RDM_RETCODE rdm_dbCompileCatalog (RDM_DB db, const char *schema)
Associate a schema with an allocated database. More...
RDM_RETCODE rdm_dbCompileCatalogFromFile (RDM_DB db, const char *schemafile)
Associate a catalog with an allocated database. More...
RDM_RETCODE rdm_dbLoadCatalog (RDM_DB db, const char *catalog)
Associate a catalog with an allocated database. More...
RDM_RETCODE rdm_dbLoadCatalogFromFile (RDM_DB db, const char *catfile)
Associate a catalog with an allocated database. More...
RDM_RETCODE rdm_dbSetOption (RDM_DB db, const char *keyword, const char *strValue)
Set a single RDM option from a string. More...
RDM_RETCODE rdm_dbSetOptions (RDM_DB db, const char *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 functions 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 char * 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
sOKAY Normal, successful return.
eDBOPEN Database already opened in this task.
eBADCAT Bad catalog (error trying to read catalog file).
eSYNTAX Syntax error.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eLOCALEMISMATCH Attempt to open database with incorrect (or no) locale.
See also
rdm_tfsAllocDatabase
rdm_dbSetCatalogFromFile
rdm_dbLoadCatalogFromFile
rdm_dbAlterCatalog
rdm_dbOpen
DDL User Guide
Parameters
[in] db The allocated, but unopened RDM_DB the catalog will be associated with
[in] schema The schema definition to be associated with db

rdm_dbCompileCatalogFromFile()

RDM_RETCODE rdm_dbCompileCatalogFromFile ( RDM_DB db,
const char * 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
sOKAY Normal, successful return.
eDBOPEN Database already opened in this task.
eBADCAT Bad catalog (error trying to read catalog file).
eSYNTAX Syntax error.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eLOCALEMISMATCH Attempt to open database with incorrect (or no) locale.
eFILEOPEN Unable 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 User Guide
Parameters
[in] db The allocated, but unopened RDM_DB the catalog will be associated with
[in] schemafile The name of the file containing the catalog

rdm_dbGetOption()

RDM_RETCODE rdm_dbGetOption ( RDM_DB db,
const char * keyword,
char * 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
api_encoding Specify string encoding for data retrieval.
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
collate Specify database UTF8 collation.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_chunk_size Specify the vacuum write size for pack files.
Return values
sOKAY Normal, successful return.
eINVOPTION Invalid option identifier is specified.
eINVOPTIONVALUE Invalid option value.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbGetOptions
rdm_dbSetOption
rdm_dbFree
Parameters
[in] db A valid RDM database handle
[in] keyword single option keyword
[out] optValue option 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,
char * 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
api_encoding Specify string encoding for data retrieval.
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
collate Specify database UTF8 collation.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_chunk_size Specify the vacuum write size for pack files.
Return values
sOKAY Normal, successful return.
eINVOPTION Invalid option identifier is specified.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbGetOption
rdm_dbSetOptions
rdm_dbFree
Parameters
[in] db A valid RDM database handle
[out] optString option string
[in] bytesIn # of bytes for optString
[out] bytesOut result # of bytes

rdm_dbLoadCatalog()

RDM_RETCODE rdm_dbLoadCatalog ( RDM_DB db,
const char * 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
sOKAY Normal, successful return.
eDBOPEN Database already opened in this task.
eBADCAT Bad catalog (error trying to read catalog file).
eSYNTAX Syntax error.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eLOCALEMISMATCH Attempt 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 User Guide
Parameters
[in] db The allocated, but unopened RDM_DB the catalog will be associated with
[in] catalog The catalog definition to be associated with db

rdm_dbLoadCatalogFromFile()

RDM_RETCODE rdm_dbLoadCatalogFromFile ( RDM_DB db,
const char * 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
sOKAY Normal, successful return.
eDBOPEN Database already opened in this task.
eBADCAT Bad catalog (error trying to read catalog file).
eSYNTAX Syntax error.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eLOCALEMISMATCH Attempt to open database with incorrect (or no) locale.
eFILEOPEN Unable 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 User Guide
Parameters
[in] db The allocated, but unopened RDM_DB the catalog will be associated with
[in] catfile The name of the file containing the catalog

rdm_dbOpen()

RDM_RETCODE rdm_dbOpen ( RDM_DB db,
const char * 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:

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
sOKAY Normal, successful return.
eINVDBNAMESPEC Invalid database name specification.
eINVENCRYPT Invalid encryption key.
eLOCALEMISMATCH Attempt to open database with incorrect (or no) locale.
eNODB Database not found.
eUNAVAIL Requested resource not available.
eOPENMODE Invalid db open mode.
sTRIGGERSREADONLY The database contains triggers and rdm_dbTriggersOn() or rdm_dbTriggersOff() has not been called so the database is in read-only mode.
See also
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
Database Uniform Resource Identifier (db-uri)
Parameters
[in] db An allocated RDM_DB
[in] dbNameSpec The database name specification (db-uri)
[in] mode The database open mode
Examples
core01Example_main.c, core09Example_main.c, core12Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core19Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core34Example_main.c, core35Example_main.c, core36Example_main.c, core37Example_main.c, cpp50Example_main.cpp, cpp55Example_main.cpp, cpp70Example_main.cpp, learn/bookStore_client.c, learn/bookStore_embed.c, learn/bookStore_vxWorks7.c, tfs/rdmAllocDatabase.c, and tfs/rdmAllocTFS.c.

rdm_dbSetCatalog()

RDM_RETCODE rdm_dbSetCatalog ( RDM_DB db,
const char * 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
sOKAY Normal, successful return.
eDBOPEN Database already opened in this task.
eBADCAT Bad catalog (error trying to read catalog file).
eSYNTAX Syntax error.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eLOCALEMISMATCH Attempt to open database with incorrect (or no) locale.
See also
rdm_tfsAllocDatabase
rdm_dbSetCatalogFromFile
rdm_dbLoadCatalogFromFile
rdm_dbSetCatalogFromFile
rdm_dbAlterCatalog
rdm_dbOpen
DDL User Guide
Parameters
[in] db The allocated, but unopened RDM_DB the catalog will be associated with
[in] catalog The catalog definition to be associated with db
Examples
core01Example_main.c, core12Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core19Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core34Example_main.c, core35Example_main.c, core36Example_main.c, core37Example_main.c, cpp50Example_main.cpp, cpp55Example_main.cpp, cpp70Example_main.cpp, and learn/bookStore_vxWorks7.c.

rdm_dbSetCatalogFromFile()

RDM_RETCODE rdm_dbSetCatalogFromFile ( RDM_DB db,
const char * 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
sOKAY Normal, successful return.
eDBOPEN Database already opened in this task.
eBADCAT Bad catalog (error trying to read catalog file).
eSYNTAX Syntax error.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eLOCALEMISMATCH Attempt to open database with incorrect (or no) locale.
eFILEOPEN Unable to open file.
See also
rdm_tfsAllocDatabase
rdm_dbSetCatalogFromFile
rdm_dbAlterCatalog
rdm_dbOpen
rdm_dbFree
rdm_dbOpen
rdm_dbSetCatalog
rdm_dbAlterCatalog
DDL User Guide
Parameters
[in] db The allocated, but unopened RDM_DB the catalog will be associated with
[in] catfile The name of the file containing the catalog

rdm_dbSetOption()

RDM_RETCODE rdm_dbSetOption ( RDM_DB db,
const char * keyword,
const char * 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
api_encoding Specify string encoding for data retrieval.
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
collate Specify database UTF8 collation.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_chunk_size Specify the vacuum write size for pack files.
Locking Requirements
None
Return values
sOKAY Normal, successful return.
eDBOPEN Database already opened in this task.
eINVOPTION Invalid option identifier is specified.
eINVOPTIONVALUE Invalid option value.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbSetOptions
rdm_dbGetOption
rdm_dbSetErrorHandler
rdm_dbFree
Parameters
[in] db A valid RDM database handle
[in] keyword Single option keyword
[in] strValue option value in string
Examples
core13Example_main.c, core28Example_main.c, core30Example_main.c, core38Example_main.c, cpp50Example_main.cpp, and cpp55Example_main.cpp.

rdm_dbSetOptions()

RDM_RETCODE rdm_dbSetOptions ( RDM_DB db,
const char * 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
api_encoding Specify string encoding for data retrieval.
timeout Specify default lock timeout in seconds.
time_zone Specify current time zone.
storage Specify database storage mode.
cache_size Specify cache size.
collate Specify database UTF8 collation.
error_format Specify error message format.
durability Specify database transaction safety level.
pack_file_size Specify pack file maximum size.
vacuum_percentage Specify the vacuum trigger level for pack files.
vacuum_chunk_size Specify the vacuum write size for pack files.
Locking Requirements
None.
Return values
sOKAY Normal, successful return.
eDBOPEN Database already opened in this task.
eINVOPTION Invalid option identifier is specified.
eINVOPTIONVALUE Invalid option value.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbSetOption
rdm_dbGetOptions
rdm_dbSetErrorHandler
rdm_dbFree
rdm_dbCreateNewPackFile
rdm_dbVacuum
Parameters
[in] db A valid RDM database handle
[in] optString The option string
Examples
core01Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core19Example_main.c, core30Example_main.c, core31Example_main.c, core32Example_main.c, and core33Example_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
sOKAY Normal, successful return.
eDBNOTOPEN Database not open.
See also
rdm_dbTriggersOn
rdm_dbTriggersStatus
Parameters
[in] db A 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
sOKAY Normal, successful return.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbTriggersOff
rdm_dbTriggersStatus
rdm_dbSetOptions
Parameters
[in] db A 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
sOKAY Normal, successful return.
eDBNOTOPEN Database not open.
See also
rdm_tfsAllocDatabase
rdm_dbOpen
rdm_dbTriggersOn
rdm_dbTriggersOff
rdm_dbSetOptions
Parameters
[in] db A valid RDM database handle
[out] pStat Pointer to triggers status result variable