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.
db_size	Specify the maximum database size allocation.
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.
db_size	Specify the maximum database size allocation.
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:

db-uri[ | db-uri]...

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

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, 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.
db_size	Specify the maximum database size allocation.
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, 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.
db_size	Specify the maximum database size allocation.
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