Insert Functions

Collaboration diagram for Insert Functions:

Functions
RDM_RETCODE	rdm_dbInsertRow (RDM_DB db, RDM_TABLE_ID tableId, const void *colValues, size_t bytesIn, RDM_CURSOR *pCursor)
	Insert a new row into a table at the specified rowId. More...
RDM_RETCODE	rdm_dbInsertRows (RDM_DB db, RDM_TABLE_ID tableId, const void *colValues, size_t bytesIn, uint32_t num, RDM_CURSOR *pCursorStatus, RDM_CURSOR *pCursor)
	Insert rows into a table. More...
RDM_RETCODE	rdm_dbReinsertRow (RDM_DB db, RDM_TABLE_ID tableId, RDM_ROWID_T rowId, const void *colValues, size_t bytesIn, RDM_CURSOR *pCursor)
	Insert a new row into a table. More...

Detailed Description

Cursor association API for inserting rows. All the functions here are located in RDM DB Engine Library. Linker option:

    -lrdmrdm

Function Documentation

rdm_dbInsertRow()

RDM_RETCODE rdm_dbInsertRow	(	RDM_DB	db,
		RDM_TABLE_ID	tableId,
		const void *	colValues,
		size_t	bytesIn,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Insert a new row into a table at the specified rowId.

This function adds a new row to the table specified by tableId. It can optionally associate the RDM_CURSOR pointed to by pCursor with a singleton containing the inserted row.

The row will be created in the table specified by tableId.

The engine validates the size of the buffers prior to accessing them.

• If the size of the colValues buffer is smaller than the size required to fully define a row then the eBADDATALEN error code will be returned and no row will be added to the table.
• If the size of the buffer is larger than the size required to fully define a row then the extra bytes will be ignored and no status will be returned.

For each column that is not designated as NOT NULL a _has_value field is added to the structure. If the _has_value field for a column is not set (RDM_COL_IS_NULL), then the value for the column will be considered NULL and anything in the structure value field for the column will be ignored. If the column has data, the _has_value field should be set to RDM_COL_HAS_VALUE.

Cursor Association Rules

• If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
• If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
• If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
• If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements

Write lock on the table specified by tableId. Foreign keys also require read locks on the referenced tables.

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
eREFINTEGRITY	Integrity constraint violation.
eROWLIMIT	Table row limit reached.

See also

rdm_dbStartUpdate

rdm_dbInsertRows

rdm_dbReinsertRow

rdm_cursorUpdateRow

rdm_cursorDeleteRow

rdm_dbAlterCatalog

rdm_dbEnd

rdm-compile

Parameters

[in]	db	A valid RDM database handle
[in]	tableId	The table identifier for table to insert the row into
[in]	colValues	A buffer that contains the column values of the row to be inserted formatted as the table structure generated when the database schema was compiled. If the table definition has changed since the schema was first compiled a new header file will need to be generated.
[in]	bytesIn	The length of the colValues buffer. If colValues is NULL this value should be 0.
[out]	pCursor	A optional pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples

c-core/01_helloworld_c/core01Example_main.c, c-core/02_core/core02Example_main.c, c-core/03_core/core03Example_main.c, c-core/04_core/core04Example_main.c, c-core/05_core/core05Example_main.c, c-core/06_core/core06Example_main.c, c-core/07_core/core07Example_main.c, c-core/08_core/core08Example_main.c, c-core/09_core/core09Example_main.c, c-core/10_core/core10Example_main.c, c-core/11_core/core11Example_main.c, c-core/12_core/core12Example_main.c, c-core/13_core/core13Example_main.c, c-core/15_core/core15Example_main.c, c-core/16_core/core16Example_main.c, c-core/17_core/core17Example_main.c, c-core/18_core/core18Example_main.c, c-core/19_core/core19Example_main.c, c-core/20_core/core20Example_main.c, c-core/21_core/core21Example_main.c, c-core/22_core/core22Example_main.c, c-core/23_core/core23Example_main.c, c-core/24_core/core24Example_main.c, c-core/25_core/core25Example_main.c, c-core/28_core/core28Example_main.c, c-core/29_core/core29Example_main.c, c-core/30_core/core30Example_main.c, c-core/31_core/core31Example_main.c, c-core/32_core/core32Example_main.c, c-core/33_core/core33Example_main.c, cursor/insertAdults.c, cursor/insertChildren.c, cursor/insertChildrenWithSiblings.c, and rtree/insertZipcode.c.

Referenced by RDM::TIME_SERIES::insert_row< table_id >::put_value().

Here is the caller graph for this function:

rdm_dbInsertRows()

RDM_RETCODE rdm_dbInsertRows	(	RDM_DB	db,
		RDM_TABLE_ID	tableId,
		const void *	colValues,
		size_t	bytesIn,
		uint32_t	num,
		RDM_CURSOR *	pCursorStatus,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Insert rows into a table.

This function inserts rows to the table specified by tableId.

If pCursor is not NULL the RDM_CURSOR pointed to by pCursor will be associated with the collection of inserted rows. In the case that there are errors inserting there may be fewer rows in the resulting RDM_CURSOR than num.

If pCursorStatus is not NULL the RDM_CURSOR pointed to by pCursorStatus will be associated with a set of RDM_RETCODE values pertaining to the status of each row that was to be inserted into the table.

For each column that is not designated as NOT NULL a _has_value field is added to the table structure. If the _has_value field for a column is not set the value for the column will be considered NULL and anything in the structure value field for the column will be ignored.

Cursor Association Rules

• If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
• If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
• If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
• If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements

Write lock on the table specified by tableId. Foreign keys also require read locks on the referenced tables.

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREFINTEGRITY	Integrity constraint violation.
eREADONLY	Database is read-only and cannot be updated.
eROWLIMIT	Table row limit reached.
sOKAYWITHINFO	Successful return with info. One or more of the inserted rows failed to be inserted. Iterate pCursorStatus to retreve the individual statuses by calling rdm_cursorGetRowStatus

See also

rdm_dbStartUpdate

rdm_dbInsertRow

rdm_cursorUpdateRow

rdm_cursorDeleteRow

rdm_dbAlterCatalog

rdm_dbEnd

rdm-compile

Parameters

[in]	db	A valid RDM database handle
[in]	tableId	The table identifier for table to insert the row into
[in]	colValues	An array that contains the column values of the rows to be inserted formatted as an array of the table structure generated when the database schema was compiled. If the table definition has changed since the schema was first compiled a new header file will need to be generated.
[in]	bytesIn	The size of the colValues buffer (in bytes)
[in]	num	The number of array entries (the number of row to be added to the table
[out]	pCursorStatus	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL). There will be one RDM_RETCODE value for each row that was attempted to be added to the table. This parameter can be NULL
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL). This will contain a collection of all the rows that were inserted. This parameter can be NULL.

Examples

c-core/14_core/core14Example_main.c.

rdm_dbReinsertRow()

RDM_RETCODE rdm_dbReinsertRow	(	RDM_DB	db,
		RDM_TABLE_ID	tableId,
		RDM_ROWID_T	rowId,
		const void *	colValues,
		size_t	bytesIn,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Insert a new row into a table.

This function adds a new row to the table specified by tableId at the specified rowId. It can optionally associate the RDM_CURSOR pointed to by pCursor with a singleton containing the inserted row.

The row will be created in the table specified by tableId.

The row will be placed in the specified rowId location. An error will be returned if that rowId already as a row associated with it or if the rowId is greater than the total number of rows currently in the table.

The engine validates the size of the buffers prior to accessing them.

• If the size of the colValues buffer is smaller than the size required to fully define a row then the eBADDATALEN error code will be returned and no row will be added to the table.
• If the size of the buffer is larger than the size required to fully define a row then the extra bytes will be ignored and no status will be returned.

For each column that is not designated as NOT NULL a _has_value field is added to the structure. If the _has_value field for a column is not set (RDM_COL_IS_NULL), then the value for the column will be considered NULL and anything in the structure value field for the column will be ignored. If the column has data, the _has_value field should be set to RDM_COL_HAS_VALUE.

Cursor Association Rules

• If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
• If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
• If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
• If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements

Write lock on the table specified by tableId.

Return values

sOKAY	Normal, successful return.
eNOSTARTUPDATE	An update operation was attempted when no rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
eREFINTEGRITY	Integrity constraint violation.
eROWLIMIT	Table row limit reached.

See also

rdm_dbStartUpdate

rdm_dbInsertRow

rdm_cursorUpdateRow

rdm_cursorDeleteRow

rdm_dbAlterCatalog

rdm_dbEnd

rdm-compile

Parameters

[in]	db	A valid RDM database handle
[in]	tableId	The table identifier for table to insert the row into
[in]	rowId	The rowid to be assigned to the row
[in]	colValues	A buffer that contains the column values of the row to be inserted formatted as the table structure generated when the database schema was compiled. If the table definition has changed since the schema was first compiled a new header file will need to be generated.
[in]	bytesIn	The length of the colValues buffer. If colValues is NULL this value should be 0.
[out]	pCursor	A optional pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)