Products Support Documentation Download
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, RDM_TCHAR_T *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 fuctions 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
sOKAYNormal, successful return.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eNOCURRENTROWThe cursor is not positioned to a valid row.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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
rdmcompile
Parameters
[in]cursorThe cursor to get the blob size from
[in]columnIdThe column identifier of the blob column to get the size of
[out]sizeA pointer to the returned size (in bytes) of the blob

◆ 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
sOKAYNormal, successful return.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eDBNOTOPENDatabase not open.
eNOCURRENTROWThe cursor is not positioned to a valid row.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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
rdmcompile
Parameters
[in]cursorThe cursor to get the clob size from
[in]columnIdThe column identifier of the clob column to get the size of
[out]numCharactersA 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
sOKAYNormal, successful return.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eDBNOTOPENDatabase not open.
eNOCURRENTROWThe cursor is not positioned to a valid row.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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
rdmcompile
Parameters
[in]cursorThe cursor to read data from
[in]columnIdThe column identifier of the clob column to read
[in]offsetOffset (in characters) into the blob to begin reading
[in]valueA pointer to the buffer where the column data will be placed
[in]bytesInThe length the value buffer (in bytes)
[out]bytesOutA pointer to the number of bytes (as UTF-8) actually read
[out]charactersOutA 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
sOKAYNormal, successful return.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eDBNOTOPENDatabase not open.
sNULLVALThe specified column is NULL. The column is NULL.
eNOCURRENTROWThe cursor is not positioned to a valid row.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe row for a singleton cursor has been deleted.
See also
rdm_dbStartRead
rdm_dbGetRows
rdm_cursorMoveToNext
rdm_cursorReadColumnIntoString
rdm_cursorReadRow
rdm_cursorReadBlob
rdm_cursorReadColumn
rdm_cursorReadKey
rdm_dbInsertRow
rdm_cursorUpdateRow
rdm_cursorDeleteRow
rdm_cursorLinkRow
rdm_dbEnd
rdmcompile
Parameters
[in]cursorThe cursor to read data from
[in]columnIdThe column identifier of the column to read
[in]columnValueA pointer to the buffer where the column value will be read
[in]bytesInThe length of the columnValue buffer (in bytes)
[out]bytesOutA pointer to the number of bytes/characters actually read (can be NULL)

◆ rdm_cursorReadColumnIntoString()

RDM_RETCODE rdm_cursorReadColumnIntoString ( RDM_CURSOR  cursor,
RDM_COLUMN_ID  columnId,
RDM_TCHAR_T 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
sOKAYNormal, successful return.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eDBNOTOPENDatabase not open.
sNULLVALThe specified column is NULL. The column is NULL.
eNOCURRENTROWThe cursor is not positioned to a valid row.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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
rdmcompile
Parameters
[in]cursorThe cursor to read data from
[in]columnIdThe column identifier of the column to read
[in]columnValueA pointer to the buffer where the converted column value will be read
[in]inBytesThe length of the columnValue buffer in bytes
[out]bytesOutA 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
sOKAYNormal, successful return.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eDBNOTOPENDatabase not open.
sNULLVALThe specified column is NULL. The column is NULL.
eNOCURRENTROWThe cursor is not positioned to a valid row.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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
rdmcompile
Parameters
[in]cursorThe cursor to read data from
[in]keyIdThe key identifier of the key to read
[in]keyValueA pointer to the buffer where the key value will be read
[in]bytesInThe length of the keyValue buffer (in bytes)
[out]bytesOutA pointer to the number of bytes/characters actually read (can be NULL)

◆ 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
sOKAYNormal, successful return.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eDBNOTOPENDatabase not open.
eCATMISMATCHCatalog in memory does not match Catalog on disk. The database definition does not match what is expected for this application.
eNOCURRENTROWThe cursor is not positioned to a valid row.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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
rdmcompile
Parameters
[in]cursorThe cursor to read data from
[in]colValuesA pointer to the buffer where row values will be read
[in]bytesInThe length of the colValues buffer (in bytes)
[out]bytesOutA pointer to the number of bytes actually read (can be NULL)
Examples:
tutorials/HelloWorld/hello_worldTutorial_main.c.