Collaboration diagram for Read Functions:

Functions
RDM_RETCODE	rdm_cursorGetBlobSize (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t *size)
	Get the current size of a blob column. More...

RDM_RETCODE	rdm_cursorGetClobSize (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t *numCharacters)
	Get the current size of a clob column. More...

RDM_RETCODE	rdm_cursorReadBlob (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t offset, void value, size_t bytesIn, size_t bytesOut)
	Read data from a blob column. More...

RDM_RETCODE	rdm_cursorReadClob (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, uint64_t offset, char value, size_t bytesIn, size_t bytesOut, size_t *charactersOut)
	Read data from a clob column as UTF-8. More...

RDM_RETCODE	rdm_cursorReadColumn (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, void columnValue, size_t bytesIn, size_t bytesOut)
	Read a single column from a table row. More...

RDM_RETCODE	rdm_cursorReadColumnIntoString (RDM_CURSOR cursor, RDM_COLUMN_ID columnId, char columnValue, size_t inBytes, size_t bytesOut)
	Read and convert a single column to a string. More...

RDM_RETCODE	rdm_cursorReadKey (RDM_CURSOR cursor, RDM_KEY_ID keyId, void keyValue, size_t bytesIn, size_t bytesOut)
	Read the columns for a key from a table row. More...

RDM_RETCODE	rdm_cursorReadRow (RDM_CURSOR cursor, void colValues, size_t bytesIn, size_t bytesOut)
	Read all columns from a row. More...

Detailed Description

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

    -lrdmrdm

See cursor for a more detailed description of a cursor.

Function Documentation

rdm_cursorGetBlobSize()

RDM_RETCODE rdm_cursorGetBlobSize	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t *	size
	)

#include <rdmcursorapi.h>

Get the current size of a blob column.

This function retrieves the current size of a blob column from the current row of cursor.

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

Return values

sOKAY	Normal, successful return.
eNOSTARTREAD	A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
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_dbStartRead; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor to get the blob size from
[in]	columnId	The column identifier of the blob column to get the size of
[out]	size	A pointer to the returned size (in bytes) of the blob

Examples: cursor/storeDNA.c.

rdm_cursorGetClobSize()

RDM_RETCODE rdm_cursorGetClobSize	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t *	numCharacters
	)

#include <rdmcursorapi.h>

Get the current size of a clob column.

This function retrieves the current size of a clob column from the current row of cursor.

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

Return values

sOKAY	Normal, successful return.
eNOSTARTREAD	A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or 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_dbStartRead; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadClob; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor to get the clob size from
[in]	columnId	The column identifier of the clob column to get the size of
[out]	numCharacters	A pointer to the number of characters in the clob

Examples: core37Example_main.c.

rdm_cursorReadBlob()

RDM_RETCODE rdm_cursorReadBlob	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t	offset,
		void *	value,
		size_t	bytesIn,
		size_t *	bytesOut
	)

#include <rdmcursorapi.h>

Read data from a blob column.

This function reads contents of a blob column from the current row of cursor.

The read will start from the offset position and will attempt to read up to bytesIn bytes. If there are not bytesIn bytes left to read and the bytesOut parameter is NULL then the function will return the eBLOBBADSIZE error code.

If bytesOut is not NULL then the number of bytes actually read into value will be put into that parameter.

If value is NULL and bytesOut is not NULL then bytesOut will have the remaining number of bytes to be read from the offset position.

Locking Requirements: Read lock on the tables associated with the cursor.

Return values

sOKAY	Normal, successful return.
eNOSTARTREAD	A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or 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_dbStartRead; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorGetBlobSize; rdm_cursorReadClob; rdm_cursorReadRow; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor to read data from
[in]	columnId	The column identifier of the blob column to read
[in]	offset	Offset into the blob to begin reading
[in]	value	A pointer to the buffer where the the column data will be placed
[in]	bytesIn	The length the the value buffer (in bytes for both CLOB and BLOB columns)
[out]	bytesOut	A pointer to the number of bytes actually read

Examples: cursor/retrieveDNA.c.

rdm_cursorReadClob()

RDM_RETCODE rdm_cursorReadClob	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		uint64_t	offset,
		char *	value,
		size_t	bytesIn,
		size_t *	bytesOut,
		size_t *	charactersOut
	)

#include <rdmcursorapi.h>

Read data from a clob column as UTF-8.

This function reads contents of a clob column from the current row of cursor.

The read will start from the offset position (in characters) and will attempt to read up to bytesIn bytes. If there are not bytesIn bytes left to read and the bytesOut parameter is NULL then the function will return the eBLOBBADSIZE error code.

If bytesOut is not NULL then the number of bytes (as UTF-8) actually read into value will be put into that parameter.

If charactersOut is not NULL then the number of characters actually read into value will be put into that parameter.

If value is NULL and bytesOut is not NULL then bytesOut will have the remaining number of bytes (as UTF-8) to be read from the offset position.

For a CLOB column you cannot assume that you have reached the end of the column if bytesOut != bytesIn. It is possible that there were not enough bytes left in value for a complete character. A CLOB column should not be considered completely read until the bytesOut or charactersOut parameter returns 0. An error will be returned if the size of value is not large enough to hold a single character from a CLOB column.

Locking Requirements: Read lock on the tables associated with the cursor

Return values

sOKAY	Normal, successful return.
eNOSTARTREAD	A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or 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_dbStartRead; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor to read data from
[in]	columnId	The column identifier of the clob column to read
[in]	offset	Offset (in characters) into the blob to begin reading
[in]	value	A pointer to the buffer where the column data will be placed
[in]	bytesIn	The length the value buffer (in bytes)
[out]	bytesOut	A pointer to the number of bytes (as UTF-8) actually read
[out]	charactersOut	A pointer to the number of characters actually read

Examples: core37Example_main.c.

rdm_cursorReadColumn()

RDM_RETCODE rdm_cursorReadColumn	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		void *	columnValue,
		size_t	bytesIn,
		size_t *	bytesOut
	)

#include <rdmcursorapi.h>

Read a single column from a table row.

This function reads the value of a single column from the current row of cursor into the columnValue buffer in the format specified by the schema.

If the column is NULL the status code sNULLVAL will be returned.

If columnValue is NULL, bytesIn is 0, and bytesOut is not NULL then the size of the column will be put into bytesOut. This will allow the application to allocate a buffer large enough to read the column value.

If the column is a blob an attempt to read the entire blob into the specified buffer will be made. If bytesIn is not large enough to hold the entire blob column a status code (sTRUNCATE) will be returned. If you want to read a portion of the blob then use rdm_cursorReadBlob() or rdm_cursorReadClob() as these will allow for specifying the offset to start reading.

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

If the size of the columnValue buffer is smaller than the size of the column then the function will write as much column data as possible into the buffer and return a sTRUNCATE status code. There is no guarantee the contents of a truncated column will have valid/useful data (or be NULL terminiated if the column is a string).
If the size of the columnValue buffer is larger than the column size then the function will write the full column value and return sOKAY.

The bytesOut parameter can be used to determine how much data was read into the buffer.

Locking Requirements: Read 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.
eNOSTARTREAD	A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eDBNOTOPEN	Database not open.
sNULLVAL	The specified column is NULL. The column is NULL.
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_dbStartRead; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadColumnIntoString; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadKey; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor to read data from
[in]	columnId	The column identifier of the column to read
[in]	columnValue	A pointer to the buffer where the column value will be read
[in]	bytesIn	The length of the columnValue buffer (in bytes) unless 0 is specified
[out]	bytesOut	A pointer to the number of bytes/characters actually read (can be NULL)

Examples: core03Example_main.c, core04Example_main.c, core06Example_main.c, core10Example_main.c, core31Example_main.c, cursor/changeAdultName.c, cursor/printChildNamesForMother.c, cursor/printChildrenNamesWithUnknownFather.c, cursor/printOurCommonChildrenNames.c, cursor/printParentNames.c, and cursor/printSiblingNamesOnMothersSide.c.

rdm_cursorReadColumnIntoString()

RDM_RETCODE rdm_cursorReadColumnIntoString	(	RDM_CURSOR	cursor,
		RDM_COLUMN_ID	columnId,
		char *	columnValue,
		size_t	inBytes,
		size_t *	bytesOut
	)

#include <rdmcursorapi.h>

Read and convert a single column to a string.

This function reads the value of a single column from the current row of cursor and converts it into a string.

If the column is NULL the status code sNULLVAL will be returned.

If columnValue is NULL, inBytes is 0, and bytesOut is not NULL then the size of the column will be put into bytesOut. This will allow the application to allocate a buffer large enough to read the column value.

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

If the size of the columnValue buffer is smaller than the size of the type specified required when doing the conversion then the function will place as much data as possible into the buffer and return a sTRUNCATE status code. The returned string will be NULL terminated.
If the size of the columnValue buffer is larger than the size required for the conversion the function will write the full column value and return sOKAY.

The bytesOut parameter can be used to determine how much data could be read into the buffer.

Locking Requirements: Read 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.
eNOSTARTREAD	A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eDBNOTOPEN	Database not open.
sNULLVAL	The specified column is NULL. The column is NULL.
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_dbStartRead; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadColumn; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor to read data from
[in]	columnId	The column identifier of the column to read
[in]	columnValue	A pointer to the buffer where the converted column value will be read
[in]	inBytes	The length of the columnValue buffer in bytes
[out]	bytesOut	A pointer to the number of bytes actually read (can be NULL)

rdm_cursorReadKey()

RDM_RETCODE rdm_cursorReadKey	(	RDM_CURSOR	cursor,
		RDM_KEY_ID	keyId,
		void *	keyValue,
		size_t	bytesIn,
		size_t *	bytesOut
	)

#include <rdmcursorapi.h>

Read the columns for a key from a table row.

This function reads the value of all columns in a key the current row of cursor into the keyValue buffer in the format specified by the schema.

If the key is NULL the status code sNULLVAL will be returned.

If keyValue is NULL, bytesIn is 0, and bytesOut is not NULL then the size of the key will be put into bytesOut. This will allow the application to allocate a buffer large enough to read the key value.

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

If the size of the keyValue buffer is smaller than the size of the key then the function will write as much key data as possible into the buffer and return a sTRUNCATE status code. There is no guarantee the contents of a truncated column will have valid/useful data (or be NULL terminiated if the column is a string).
If the size of the keyValue buffer is larger than the key size then the function will write the full key value and return sOKAY.

The bytesOut parameter can be used to determine how much data was read into the buffer.

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

Return values

sOKAY	Normal, successful return.
eNOSTARTREAD	A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKED	Attempt to access a table for reading or update without proper locks.
eDBNOTOPEN	Database not open.
sNULLVAL	The specified column is NULL. The column is NULL.
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_dbStartRead; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor to read data from
[in]	keyId	The key identifier of the key to read
[in]	keyValue	A pointer to the buffer where the key value will be read
[in]	bytesIn	The length of the keyValue buffer (in bytes) unless 0 is specified
[out]	bytesOut	A pointer to the number of bytes/characters actually read (can be NULL)

Referenced by RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_range(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_stats(), and RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_value().

Here is the caller graph for this function:

rdm_cursorReadRow()

RDM_RETCODE rdm_cursorReadRow	(	RDM_CURSOR	cursor,
		void *	colValues,
		size_t	bytesIn,
		size_t *	bytesOut
	)

#include <rdmcursorapi.h>

Read all columns from a row.

This function reads all the (non blob) column values from the 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 colValues buffer is smaller than the row size of the table then the function will place as much data as possible into the buffer and return a sTRUNCATE status code. There is no guarantee the contents of a truncated row will have valid/useful data (or be NULL terminiated if the column is a string).
If the size of the colValues buffer is larger than the size required for the row the function will write the full column value and return sOKAY.

The bytesOut parameter can be used to determine how many bytes were actually read into the buffer.

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

Return values

sOKAY	Normal, successful return.
eNOSTARTREAD	A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or 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_dbStartRead; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow; rdm_dbEnd; rdm-compile

Parameters

[in]	cursor	The cursor to read data from
[in]	colValues	A pointer to the buffer where row values will be read
[in]	bytesIn	The length of the colValues buffer (in bytes) unless 0 is specified
[out]	bytesOut	A pointer to the number of bytes actually read (can be NULL)

Examples: core01Example_main.c, core02Example_main.c, core05Example_main.c, core07Example_main.c, core08Example_main.c, core09Example_main.c, core10Example_main.c, core11Example_main.c, core12Example_main.c, core13Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core19Example_main.c, core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core35Example_main.c, core36Example_main.c, core37Example_main.c, core38Example_main.c, cpp50Example_main.cpp, cpp51example_main.cpp, cpp55Example_main.cpp, cpp70Example_main.cpp, cursor/printAdults.c, cursor/printAdultsInReverseSortedOrder.c, cursor/printANumberOfAdultsArroundRecord.c, cursor/printANumberOfAdultsArroundRecordInSortedOrder.c, cursor/printMembers.c, learn/bookStore_client.c, learn/bookStore_embed.c, learn/bookStore_vxWorks7.c, rtree/retrieveAllZipcode.c, rtree/retrieveContainedZipcode.c, rtree/retrieveExactZipcode.c, rtree/retrieveOverlapZipcode.c, and rtree/updateZipcode.c.

Referenced by RDM::DB::read_row< table_id >::fetch_first(), RDM::DB::read_row< table_id >::fetch_last(), RDM::DB::read_row< table_id >::fetch_next(), RDM::DB::read_row< table_id >::fetch_prev(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_range(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_stats(), and RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_value().

Here is the caller graph for this function: