Functions
Insert Functions
RDM C API Reference » RDM TFS APIs » RDM Database APIs

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

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 fuctions 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 [in] A valid RDM database handle
[in] tableId [in] The table identifier for table to insert the row into
[in] colValues [in] 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 [in] The length of the colValues buffer. If colValues is NULL this value should be 0.
[out] pCursor [out] A optional pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

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 [in] A valid RDM database handle
[in] tableId [in] The table identifier for table to insert the row into
[in] colValues [in] 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 [in] The size of the colValues buffer (in bytes)
[in] num [in] The number of array entries (the number of row to be added to the table
[out] pCursorStatus [out] 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 [out] 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.

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 [in] A valid RDM database handle
[in] tableId [in] The table identifier for table to insert the row into
[in] rowId [in] The rowid to be assigned to the row
[in] colValues [in] 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 [in] The length of the colValues buffer. If colValues is NULL this value should be 0.
[out] pCursor [out] A optional pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)