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_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 RDM 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

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

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)
[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, core28Example_main.c, core29Example_main.c, core30Example_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)
[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)
[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, 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: