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

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 *db_namespec, 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_size	Specify 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

sOKAY	Normal, successful return.
eINVOPTION	Invalid option is specified.
eINVOPTIONVALUE	Invalid option value.

See also: rdm_tfsAllocDatabase; rdm_dbOpen; rdm_dbGetOptions; rdm_dbSetOption; rdm_dbFree

Parameters

[in]	db	[in] A valid RDM database handle
[in]	keyword	[in] single option keyword
[out]	optValue	[out] option value in string
[in]	bytesIn	[in] # of bytes for pszValue
[out]	bytesOut	[out] # 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_size	Specify 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

sOKAY	Normal, successful return.
eINVOPTION	Invalid option is specified.

See also: rdm_tfsAllocDatabase; rdm_dbOpen; rdm_dbGetOption; rdm_dbSetOptions; rdm_dbFree

Parameters

[in]	db	[in] A valid RDM database handle
[out]	optString	[out] option string
[in]	bytesIn	[in] # of bytes for optString
[out]	bytesOut	[out] result # of bytes

rdm_dbOpen()

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

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_rdmAllocDatabase; rdm_dbSetOptions; rdm_dbSetEncrypt; rdm_dbEncrypt; rdm_dbTriggersOn; rdm_dbSetCatalog; rdm_dbGetRows; rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbClose; rdm_dbFree; Database Name Specification (db_namespec)

Parameters

[in]	db	[in] An allocated RDM_DB
[in]	db_namespec	[in] The database name specification
[in]	mode	[in] The database open mode

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

sOKAY	Normal, successful return.
eDBOPEN	Database already opened in this task.
eBADCAT	Bad catalog (error trying to read catalog file).
eDDL_SYNTAX	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_dbAlterCatalog; rdm_dbOpen; ddl_ug

Parameters

[in]	db	[in] The allocated, but unopened RDM_DB the catalog will be associated with
[in]	catalog	[in] The catalog definition to be associated with db

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

sOKAY	Normal, successful return.
eDBOPEN	Database already opened in this task.
eBADCAT	Bad catalog (error trying to read catalog file).
eDDL_SYNTAX	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_ug

Parameters

[in]	db	[in] The allocated, but unopened RDM_DB the catalog will be associated with
[in]	catfile	[in] The 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_size	Specify 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

sOKAY	Normal, successful return.
eDBOPEN	Database already opened in this task.
eINVOPTION	Invalid option is specified.
eINVOPTIONVALUE	Invalid option value.

See also: rdm_tfsAllocDatabase; rdm_dbOpen; rdm_dbSetOptions; rdm_dbGetOption; rdm_dbSetErrorHandler; rdm_dbFree

Parameters

[in]	db	[in] A valid RDM database handle
[in]	keyword	[in] Single option keyword
[in]	strValue	[in] option 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_size	Specify 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

sOKAY	Normal, successful return.
eDBOPEN	Database already opened in this task.
eINVOPTION	Invalid option is specified.
eINVOPTIONVALUE	Invalid option value.

See also: rdm_tfsAllocDatabase; rdm_dbOpen; rdm_dbSetOption; rdm_dbGetOptions; rdm_dbSetErrorHandler; rdm_dbFree; rdm_dbFlushIdIndex; rdm_dbCreateNewPackFile; rdm_dbVacuum

Parameters

[in]	db	[in] A valid RDM database handle
[in]	optString	[in] The 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

sOKAY	Normal, successful return.
eDBNOTOPEN	Database not open.

See also: rdm_dbTriggersOn; rdm_dbTriggersStatus

Parameters

[in] db [in] 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 [in] 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	[in] A valid RDM database handle
[out]	pStat	[out] Pointer to triggers status result variable