Collaboration diagram for Update Functions:

Functions
RDM_RETCODE	rdm_cursorBufferedUpdateBlob (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t offset, const void *value, size_t bytesIn)
	Buffered update of a blob column. More...

RDM_RETCODE	rdm_cursorSetBlobSize (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t size)
	Set the size of a blob column. More...

RDM_RETCODE	rdm_cursorSetClobSize (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t size)
	Set the size of a clob column. More...

RDM_RETCODE	rdm_cursorUpdateBlob (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t offset, const void *value, size_t bytesIn)
	Update a blob column. More...

RDM_RETCODE	rdm_cursorUpdateClob (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t offset, const char *value, size_t charactersIn)
	Update a clob column. More...

RDM_RETCODE	rdm_cursorUpdateColumn (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, const void *columnValue, size_t bytesIn)
	Update a single column in a row. More...

RDM_RETCODE	rdm_cursorUpdateColumnByString (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, const char *columnValue, size_t bytesIn)
	Update a single column in a row from a string. More...

RDM_RETCODE	rdm_cursorUpdateRow (RDM_CURSOR cursor, const void *colValues, size_t bytesIn)
	Update all columns in a row. More...

Detailed Description

API for updating data for a row identified by a core cursor. All the functions here are located in RDM DB Engine Library. Linker option:

    -lrdmrdm

See cursor for a more detailed description of a cursor.

Function Documentation

rdm_cursorBufferedUpdateBlob()

RDM_RETCODE rdm_cursorBufferedUpdateBlob	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t	offset,
		const void *	value,
		size_t	bytesIn
	)

#include <rdmcursorapi.h>

Buffered update of a blob column.

This function updates the value of a blob column in current row of cursor similar to rdm_cursorUpdateBlob() except that this function relays on buffering where this function have been optimized for updating the data in smaller chunks. Call this function repeatedly and when done rdm_cursorBufferedFlushBlob() must be called. To interleave other call in between these calls is an error. If this function reports an error, rdm_cursorBufferedFlushBlob() should not be called.

Locking Requirements: Write lock on the table associated with the cursor

Return values

sOKAY	Normal, successful return.
eREADONLY	Database is read-only and cannot be updated.
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.
eDBNOTOPEN	Database not open.
eNOCURRENTROW	The cursor is not positioned to a valid row.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.

See also: rdm_cursorBufferedFlushBlob; rdm_cursorBufferedReadBlob; rdm_cursorReadBlob; rdm_cursorGetBlobSize

Parameters

[in]	cursor	The cursor containing the row with the blob column to be updated
[in]	columnId	The column identifier of the blob column to be updated
[in]	offset	The offset into the blob to write the updated content (in bytes)
[in]	value	A pointer to the content to be written to the blob column
[in]	bytesIn	The length of the value buffer

rdm_cursorSetBlobSize()

RDM_RETCODE rdm_cursorSetBlobSize	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t	size
	)

#include <rdmcursorapi.h>

Set the size of a blob column.

This function updates the size of a blob column in current row of cursor.

If size is smaller than the current size of the blob existing data will be truncated.

If size is larger than the current size of the blob the blob will be padded with NULL bytes to extend the size of the blob.

Locking Requirements: Write lock on the table associated with the cursor

Return values

sOKAY	Normal, successful return.
eREADONLY	Database is read-only and cannot be updated.
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.
eDBNOTOPEN	Database not open.
eNOCURRENTROW	The cursor is not positioned to a valid row.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.

See also: rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorUpdateBlob; rdm_cursorSetClobSize; rdm_cursorUpdateRow; rdm_cursorUpdateBlob; rdm_cursorUpdateColumn; rdm_cursorLinkRow; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor containing the row with the blob to change the size of
[in]	columnId	The column identifier of the blob column to change the size of
[in]	size	The new size of the blob column (in bytes)

Examples: cursor/storeDNA.c.

rdm_cursorSetClobSize()

RDM_RETCODE rdm_cursorSetClobSize	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t	size
	)

#include <rdmcursorapi.h>

Set the size of a clob column.

This function updates the size of a clob column in current row of cursor.

The size of a clob is specified in characters.

If size is smaller than the current size of the clob existing data will be truncated.

If size is larger than the current size of the clob the clob will be padded with NULL characters to extend the size of the clob.

Locking Requirements: Write lock on the table associated with the cursor

Return values

sOKAY	Normal, successful return.
eREADONLY	Database is read-only and cannot be updated.
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.
eDBNOTOPEN	Database not open.
eNOCURRENTROW	The cursor is not positioned to a valid row.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.

See also: rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorUpdateClob; rdm_cursorSetBlobSize; rdm_cursorUpdateRow; rdm_cursorUpdateBlob; rdm_cursorUpdateColumn; rdm_cursorLinkRow; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor containing the row with the clob to change the size of
[in]	columnId	The column identifier of the clob column to change the size of
[in]	size	The new size of the clob column (in characters)

rdm_cursorUpdateBlob()

RDM_RETCODE rdm_cursorUpdateBlob	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t	offset,
		const void *	value,
		size_t	bytesIn
	)

#include <rdmcursorapi.h>

Update a blob column.

This function updates the value of a blob column in current row of cursor.

If offset is smaller than the current size of the blob existing data will be overwritten.

If offset is larger than the current size of the blob the blob will be padded with NULL bytes to extend the size of the blob to offset.

Locking Requirements: Write lock on the table associated with the cursor

Return values

sOKAY	Normal, successful return.
eREADONLY	Database is read-only and cannot be updated.
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.
eDBNOTOPEN	Database not open.
eNOCURRENTROW	The cursor is not positioned to a valid row.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.

See also: rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorUpdateRow; rdm_cursorUpdateClob; rdm_cursorUpdateColumn; rdm_cursorLinkRow; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor containing the row with the blob column to be updated
[in]	columnId	The column identifier of the blob column to be updated
[in]	offset	The offset into the blob to write the updated content (in bytes)
[in]	value	A pointer to the content to be written to the blob column
[in]	bytesIn	The length of the value buffer

Examples: cursor/storeDNA.c.

rdm_cursorUpdateClob()

RDM_RETCODE rdm_cursorUpdateClob	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t	offset,
		const char *	value,
		size_t	charactersIn
	)

#include <rdmcursorapi.h>

Update a clob column.

This function updates the value of a clob column in current row of cursor.

If offset is smaller than the current size of the clob existing data will be overwritten.

If offset is larger than the current size of the clob the clob will be padded with NULL characters to extend the size of the clob to offset.

Locking Requirements: Write lock on the table associated with the cursor

Return values

sOKAY	Normal, successful return.
eREADONLY	Database is read-only and cannot be updated.
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.
eDBNOTOPEN	Database not open.
eNOCURRENTROW	The cursor is not positioned to a valid row.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.

See also: rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorUpdateRow; rdm_cursorUpdateBlob; rdm_cursorUpdateColumn; rdm_cursorLinkRow; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor containing the row with the clob column to be updated
[in]	columnId	The column identifier of the clob column to be updated
[in]	offset	The character offset into the clob to write the updated content
[in]	value	A pointer to the content to be written to the clob column
[in]	charactersIn	The number of characters in the value buffer

rdm_cursorUpdateColumn()

RDM_RETCODE rdm_cursorUpdateColumn	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		const void *	columnValue,
		size_t	bytesIn
	)

#include <rdmcursorapi.h>

Update a single column in a row.

This function updates the value of a single column in the current row of cursor.

If columnValue is NULL then bytesIn will be ignored and the engine will attempt to set the specified column to the NULL value.

If the cursor is a key scan cursor based on the column that is updated then the cursor will maintain the original position but current row is kept the same. Calling rdm_cursorMoveToNext() or rdm_cursorMoveToPrevious() will position the cursor relative to the original value and not the updated value. The updated value will be in the collection.

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

If the size of the columnValue buffer is smaller than the size required to fully define the column then the eBADDATALEN error code will be returned and no update will be made 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.

Locking Requirements: Write lock on the table associated with the cursor. A foreign key also require read lock on the referenced table.

Return values

sOKAY	Normal, successful return.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
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.
eDBNOTOPEN	Database not open.
eNOCURRENTROW	The cursor is not positioned to a valid row.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.

See also: rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorUpdateColumnByString; rdm_cursorUpdateRow; rdm_cursorUpdateBlob; rdm_cursorLinkRow; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor containing the row to be updated
[in]	columnId	The columns identifier of the column to be updated
[in]	columnValue	A pointer to the buffer containing the new column value
[in]	bytesIn	The length of the columnValue buffer (in bytes)

Examples: core28Example_main.c, core29Example_main.c, core30Example_main.c, and cursor/changeAdultName.c.

rdm_cursorUpdateColumnByString()

RDM_RETCODE rdm_cursorUpdateColumnByString	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		const char *	columnValue,
		size_t	bytesIn
	)

#include <rdmcursorapi.h>

Update a single column in a row from a string.

This function updates the value of a single column in the current row of cursor. This version will convert the value from a string to the schema type for the column.

If columnValue is NULL then the type and bytesIn will be ignored and the engine will attempt to set the specified column to the NULL value.

If the cursor is a key scan cursor based on the column that is updated then the cursor will maintain the original position but current row is kept the same. Calling rdm_cursorMoveToNext() or rdm_cursorMoveToPrevious() will position the cursor relative to the original value and not the updated value. The updated value will be in the collection.

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

If the size of the columnValue buffer is smaller than the size required for the specified type then the S_BUFFER_TOO_SMALL error code will be returned and no update will be made to the row.
If the size of the buffer is larger than the size required for the specified type then the extra bytes will be ignored and no status will be returned.

Locking Requirements: Write lock on the table associated with the cursor. A foreign key also require read lock on the referenced table.

Return values

sOKAY	Normal, successful return.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
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.
eDBNOTOPEN	Database not open.
eNOCURRENTROW	The cursor is not positioned to a valid row.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.

See also: rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorUpdateRow; rdm_cursorUpdateBlob; rdm_cursorUpdateColumn; rdm_cursorLinkRow; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor containing the row to be updated
[in]	columnId	The columns identifier of the column to be updated
[in]	columnValue	A pointer to the buffer containing the new column value
[in]	bytesIn	The length of the columnValue buffer

rdm_cursorUpdateRow()

RDM_RETCODE rdm_cursorUpdateRow	(	RDM_CURSOR	cursor,
		const void *	colValues,
		size_t	bytesIn
	)

#include <rdmcursorapi.h>

Update all columns in a row.

This function updates all column values, except for blobs, in current row of cursor.

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.

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

If the size of the columnValue buffer is smaller than the size required to fully define a row then the eBADDATALEN error code will be returned and no updates to the row will be made
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 the column values will be updated.

If the cursor is a key scan cursor then the cursor will maintain the original position but current row is kept the same. Calling rdm_cursorMoveToNext() or rdm_cursorMoveToPrevious() will position the cursor relative to the original position and not the updated position. The updated position will be in the collection.

Locking Requirements: Write lock on the table associated with the cursor. Foreign keys also require read locks on the referenced tables.

Return values

sOKAY	Normal, successful return.
eDUPLICATE	Attempt to insert a duplicate value as a unique/primary key.
eREADONLY	Database is read-only and cannot be updated.
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.
eDBNOTOPEN	Database not open.
eCATMISMATCH	Catalog in memory does not match Catalog on disk. The database definition does not match what is expected for this application.
eNOCURRENTROW	The cursor is not positioned to a valid row.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.

See also: rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorUpdateRow; rdm_cursorUpdateBlob; rdm_cursorUpdateColumn; rdm_cursorLinkRow; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor containing the row to be updated
[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.

Examples: core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, cursor/changeAdultIdentity.c, and rtree/updateZipcode.c.