TIBCO ActiveSpaces®

Macros | Enumerations | Functions
row.h File Reference

Row objects contain columns with values. More...

## Macros
#define | TIBDG_COLUMN_TYPESTR_DATETIME "datetime"
| The string constant used for column types of 'datetime' type. More...
#define | TIBDG_COLUMN_TYPESTR_DOUBLE "double"
| The string constant used for column types of 'double' type. More...
#define | TIBDG_COLUMN_TYPESTR_INVALID "invalid"
| The string constant used for invalid column types. More...
#define | TIBDG_COLUMN_TYPESTR_LONG "long"
| The string constant used for column types of 'long' type. More...
#define | TIBDG_COLUMN_TYPESTR_OPAQUE "opaque"
| The string constant used for column types of 'opaque' type. More...
#define | TIBDG_COLUMN_TYPESTR_STRING "string"
| The string constant used for column types of 'string' type. More...
#define | TIBDG_COLUMN_TYPESTR_UNKNOWN "unknown"
| The string constant used for unknown column types. More...

## Enumerations
enum | tibdgColumnType { TIBDG_COLUMN_TYPE_INVALID = 0 , TIBDG_COLUMN_TYPE_LONG = 1 , TIBDG_COLUMN_TYPE_STRING = 2 , TIBDG_COLUMN_TYPE_OPAQUE = 3 , TIBDG_COLUMN_TYPE_DATETIME = 4 , TIBDG_COLUMN_TYPE_DOUBLE = 5 , TIBDG_COLUMN_TYPE_UNKNOWN = 6 }
| The enum representing a column type from a row or table. More...

## Functions
TIBDG_API tibdgColumnType | tibdgColumnType_FromString (tibEx e, const char *columnTypeString)
| Get the column type object from a string representation. More...
TIBDG_API const char * | tibdgColumnType_ToString (tibEx e, tibdgColumnType columnType)
| Get the string representation of the column type object. More...
TIBDG_API void | tibdgRow_Clear (tibEx e, tibdgRow row)
| Clear all columns in a row object. More...
TIBDG_API tibdgRow | tibdgRow_Copy (tibEx e, tibdgRow row)
| Make a copy of a row. More...
TIBDG_API tibdgRow | tibdgRow_Create (tibEx e, tibdgTable table)
| Create an empty row object. More...
TIBDG_API tibdgRowIterator | tibdgRow_CreateIterator (tibEx e, tibdgRow row)
| Create an iterator that can be used to iterate over the columns of a row. More...
TIBDG_API void | tibdgRow_Destroy (tibEx e, tibdgRow row)
| Destroy a row object. More...
TIBDG_API tibdgColumnType | tibdgRow_GetColumnType (tibEx e, tibdgRow row, const char *columnName)
| Get the type of the column. More...
TIBDG_API tibDateTime * | tibdgRow_GetDateTime (tibEx e, tibdgRow row, const char *columnName)
| Get the value of a DateTime column from a row. More...
TIBDG_API tibdouble_t | tibdgRow_GetDouble (tibEx e, tibdgRow row, const char *columnName)
| Get the value of a double column from a row. More...
TIBDG_API tibint64_t | tibdgRow_GetExpiration (tibEx e, tibdgRow row)
| Get the expiration time for the row. More...
TIBDG_API tibint64_t | tibdgRow_GetLong (tibEx e, tibdgRow row, const char *columnName)
| Get the value of a long integer column from a row. More...
TIBDG_API const void * | tibdgRow_GetOpaque (tibEx e, tibdgRow row, const char *columnName, tibint32_t *size)
| Get the value of a blob from a row. More...
TIBDG_API const char * | tibdgRow_GetString (tibEx e, tibdgRow row, const char *columnName)
| Get the value of a string column from a row. More...
TIBDG_API tibdgTable | tibdgRow_GetTable (tibEx e, tibdgRow row)
| Get the table associated with a row. More...
TIBDG_API tibbool_t | tibdgRow_IsColumnSet (tibEx e, tibdgRow row, const char *columnName)
| Determine whether a column is set in a row. More...
TIBDG_API void | tibdgRow_SetDateTime (tibEx e, tibdgRow row, const char *columnName, const tibDateTime *dateTime)
| Set a DateTime field in a column for this row. More...
TIBDG_API void | tibdgRow_SetDouble (tibEx e, tibdgRow row, const char *columnName, tibdouble_t value)
| Set a double floating-point in a column for this row. More...
TIBDG_API void | tibdgRow_SetLong (tibEx e, tibdgRow row, const char *columnName, tibint64_t value)
| Set a long integer in a column for this row. More...
TIBDG_API void | tibdgRow_SetOpaque (tibEx e, tibdgRow row, const char *columnName, const void *value, tibint32_t size)
| Set an opaque (byte-array) column in this row. More...
TIBDG_API void | tibdgRow_SetString (tibEx e, tibdgRow row, const char *columnName, const char *value)
| Set a string in a column for this row. More...
TIBDG_API void | tibdgRow_SetTTL (tibEx e, tibdgRow row, tibint64_t value)
| Set the time-to-live for this row, overriding the table's default value. More...
TIBDG_API tibint32_t | tibdgRow_ToString (tibEx e, tibdgRow row, char *buffer, tibint32_t size)
| Get a printable string that describes the contents of a row. More...
TIBDG_API void | tibdgRowIterator_Destroy (tibEx e, tibdgRowIterator rowIterator)
| Destroy a row iterator object. More...
TIBDG_API const char * | tibdgRowIterator_GetNext (tibEx e, tibdgRowIterator rowIterator, tibdgColumnType *columnType)
| Returns the name of the next column and its column type. More...
TIBDG_API tibbool_t | tibdgRowIterator_HasNext (tibEx e, tibdgRowIterator rowIterator)
| Determine whether a row iterator object can present another column. More...

## Detailed Description

Row objects contain columns with values.

## Macro Definition Documentation

## ◆ TIBDG_COLUMN_TYPESTR_DATETIME

#define TIBDG_COLUMN_TYPESTR_DATETIME "datetime"

The string constant used for column types of 'datetime' type.

## ◆ TIBDG_COLUMN_TYPESTR_DOUBLE

#define TIBDG_COLUMN_TYPESTR_DOUBLE "double"

The string constant used for column types of 'double' type.

## ◆ TIBDG_COLUMN_TYPESTR_INVALID

#define TIBDG_COLUMN_TYPESTR_INVALID "invalid"

The string constant used for invalid column types.

## ◆ TIBDG_COLUMN_TYPESTR_LONG

#define TIBDG_COLUMN_TYPESTR_LONG "long"

The string constant used for column types of 'long' type.

## ◆ TIBDG_COLUMN_TYPESTR_OPAQUE

#define TIBDG_COLUMN_TYPESTR_OPAQUE "opaque"

The string constant used for column types of 'opaque' type.

## ◆ TIBDG_COLUMN_TYPESTR_STRING

#define TIBDG_COLUMN_TYPESTR_STRING "string"

The string constant used for column types of 'string' type.

## ◆ TIBDG_COLUMN_TYPESTR_UNKNOWN

#define TIBDG_COLUMN_TYPESTR_UNKNOWN "unknown"

The string constant used for unknown column types.

## Enumeration Type Documentation

## ◆ tibdgColumnType

enum tibdgColumnType

The enum representing a column type from a row or table.

Enumerator
TIBDG_COLUMN_TYPE_INVALID |
TIBDG_COLUMN_TYPE_LONG |
TIBDG_COLUMN_TYPE_STRING |
TIBDG_COLUMN_TYPE_OPAQUE |
TIBDG_COLUMN_TYPE_DATETIME |
TIBDG_COLUMN_TYPE_DOUBLE |
TIBDG_COLUMN_TYPE_UNKNOWN |

## Function Documentation

## ◆ tibdgColumnType_FromString()

TIBDG_API tibdgColumnType tibdgColumnType_FromString | ( | tibEx | e,
|  | const char * | columnTypeString
| ) |  |

Get the column type object from a string representation.

Parameters

  e | The exception object captures information about failures.
  columnTypeString | The string type name to convert.

Returns
  a column type object

## ◆ tibdgColumnType_ToString()

TIBDG_API const char * tibdgColumnType_ToString | ( | tibEx | e,
|  | tibdgColumnType | columnType
| ) |  |

Get the string representation of the column type object.

Parameters

  e | The exception object captures information about failures.
  columnType | The type to convert

Returns
  On success, this call returns the corresponding string name for the column type.
  On failure, this call returns `NULL`.

## ◆ tibdgRow_Clear()

TIBDG_API void tibdgRow_Clear | ( | tibEx | e,
|  | tibdgRow | row
| ) |  |

Clear all columns in a row object.

After clearing all fields, you can re-use the row object. The schema does not change.

Parameters

  e | The exception object captures information about failures.
  row | The call clears all fields in this row.

Returns
  void

## ◆ tibdgRow_Copy()

TIBDG_API tibdgRow tibdgRow_Copy | ( | tibEx | e,
|  | tibdgRow | row
| ) |  |

Make a copy of a row.

Copied rows are owned by the caller and must be freed with tibdgRow_Destroy

Parameters

  e | The exception object captures information about failures.
  row | The row to copy

Returns
  tibdgTable

## ◆ tibdgRow_Create()

TIBDG_API tibdgRow tibdgRow_Create | ( | tibEx | e,
|  | tibdgTable | table
| ) |  |

Create an empty row object.

This function returns an empty row object. The application can set columns in the empty row object and use the object as a keyValue for tibdgTable_Put or as a key for tibdgTable_Get or tibdgTable_Delete.

Parameters

  e | The exception object captures information about failures.
  table | The table which creates this row

Returns
  tibdgRow

## ◆ tibdgRow_CreateIterator()

TIBDG_API tibdgRowIterator tibdgRow_CreateIterator | ( | tibEx | e,
|  | tibdgRow | row
| ) |  |

Create an iterator that can be used to iterate over the columns of a row.

The iterator is only valid as long as the row object is valid and it must be freed with tibdgRowIterator_Destroy.

Parameters

  e | The exception object captures information about failures.
  row | The row to iterate over.

Returns
  tibdgRowIterator.

## ◆ tibdgRow_Destroy()

TIBDG_API void tibdgRow_Destroy | ( | tibEx | e,
|  | tibdgRow | row
| ) |  |

Destroy a row object.

Release all the resources allocated by the tibdgRow_Create function.

Parameters

  e | The exception object captures information about failures.
  row | The row object to be destroyed.

Returns
  void

## ◆ tibdgRow_GetColumnType()

TIBDG_API tibdgColumnType tibdgRow_GetColumnType | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName
| ) |  |

Get the type of the column.

Parameters

  e | The exception object captures information about failures.
  row | The call get the type of the column in this row.
  columnName | The call gets the type of this column

Returns
  the column type

## ◆ tibdgRow_GetDateTime()

TIBDG_API tibDateTime * tibdgRow_GetDateTime | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName
| ) |  |

Get the value of a DateTime column from a row.

The program must not destroy the `tibDateTime` struct because the row owns it.

Parameters

  e | The exception object captures information about failures.
  row | The call gets the value from this row.
  columnName | The call gets the value from this column.

Returns
  tibDateTime

## ◆ tibdgRow_GetDouble()

TIBDG_API tibdouble_t tibdgRow_GetDouble | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName
| ) |  |

Get the value of a double column from a row.

Parameters

  e | The exception object captures information about failures.
  row | The call gets the value from this row.
  columnName | The call gets the value from this column.

Returns
  tibdouble_t

## ◆ tibdgRow_GetExpiration()

TIBDG_API tibint64_t tibdgRow_GetExpiration | ( | tibEx | e,
|  | tibdgRow | row
| ) |  |

Get the expiration time for the row.

It is an error to call this on a row if the row's table does not have expiration enabled or if the row was not retrieved from a table or iterator.

Parameters

  e | The exception object captures information about failures.
  row | The call sets the column in this row.

Returns
  The time, expressed as seconds since January 1st, 1970 (UTC), that the row becomes available for expiration.

## ◆ tibdgRow_GetLong()

TIBDG_API tibint64_t tibdgRow_GetLong | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName
| ) |  |

Get the value of a long integer column from a row.

Parameters

  e | The exception object captures information about failures.
  row | The call gets the value from this row.
  columnName | The call gets the value from this column.

Returns
  a 64-bit integer value

## ◆ tibdgRow_GetOpaque()

TIBDG_API const void * tibdgRow_GetOpaque | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName,
|  | tibint32_t * | size
| ) |  |

Get the value of a blob from a row.

The data pointer is valid only for the lifetime of the row. The data bytes are part of the row object; the program must neither modify nor free them.

The data pointer is not necessarily aligned to a word boundary. Before casting the opaque data to a struct, you must either verify that it is properly aligned (that is, the data pointer is divisible by 8), or copy the data to an aligned location.

Parameters

  e | The exception object captures information about failures.
  row | The call gets the value from this row.
  columnName | The call gets the value from this column.
  size | The call returns the length (in bytes) of the opaque field.

Returns
  a pointer to the string field

## ◆ tibdgRow_GetString()

TIBDG_API const char * tibdgRow_GetString | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName
| ) |  |

Get the value of a string column from a row.

The string is part of the row object and is valid only for the lifetime of the row or until the row is cleared. The program must neither modify nor free it. A `NULL` character terminates the string.

Parameters

  e | The exception object captures information about failures.
  row | The call gets the value from this row.
  columnName | The call gets the value from this column.

Returns
  a pointer to the string field

## ◆ tibdgRow_GetTable()

TIBDG_API tibdgTable tibdgRow_GetTable | ( | tibEx | e,
|  | tibdgRow | row
| ) |  |

Get the table associated with a row.

Note: Specific APIs may return rows not associated with a single table.

Parameters

  e | The exception object captures information about failures.
  row | The row of which to get the table

Returns
  tibdgTable if a row is associated with a single table. NULL otherwise

## ◆ tibdgRow_IsColumnSet()

TIBDG_API tibbool_t tibdgRow_IsColumnSet | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName
| ) |  |

Determine whether a column is set in a row.

Parameters

  e | The exception object captures information about failures.
  row | The call checks in this row.
  columnName | The call checks for a column with this name.

Returns
  tibbool_t

## ◆ tibdgRow_SetDateTime()

TIBDG_API void tibdgRow_SetDateTime | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName,
|  | const tibDateTime * | dateTime
| ) |  |

Set a DateTime field in a column for this row.

Parameters

  e | The exception object captures information about failures.
  row | The call sets the field in this row.
  columnName | The call sets the value of the column with this name.
  dateTime | The call sets this DateTime as the column value.

Returns
  void

## ◆ tibdgRow_SetDouble()

TIBDG_API void tibdgRow_SetDouble | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName,
|  | tibdouble_t | value
| ) |  |

Set a double floating-point in a column for this row.

Parameters

  e | The exception object captures information about failures.
  row | The call sets the column in this row.
  columnName | The call sets the value of the field with this name.
  value | The call sets this double as the column value.

Returns
  void

## ◆ tibdgRow_SetLong()

TIBDG_API void tibdgRow_SetLong | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName,
|  | tibint64_t | value
| ) |  |

Set a long integer in a column for this row.

Parameters

  e | The exception object captures information about failures.
  row | The call sets the column in this row.
  columnName | The call sets this column.
  value | The call sets this long integer as the value.

Returns
  void

## ◆ tibdgRow_SetOpaque()

TIBDG_API void tibdgRow_SetOpaque | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName,
|  | const void * | value,
|  | tibint32_t | size
| ) |  |

Set an opaque (byte-array) column in this row.

Parameters

  e | The exception object captures information about failures.
  row | The call sets the column in this row.
  columnName | The call sets the value of the column with this name.
  value | The call copies this byte-array into the column.
  size | Supply the length (in bytes) of the opaque value.

Returns
  void

## ◆ tibdgRow_SetString()

TIBDG_API void tibdgRow_SetString | ( | tibEx | e,
|  | tibdgRow | row,
|  | const char * | columnName,
|  | const char * | value
| ) |  |

Set a string in a column for this row.

Parameters

  e | The exception object captures information about failures.
  row | The call sets the column in this row.
  columnName | The call sets this column.
  value | The call sets this string as the value.

Returns
  void

## ◆ tibdgRow_SetTTL()

TIBDG_API void tibdgRow_SetTTL | ( | tibEx | e,
|  | tibdgRow | row,
|  | tibint64_t | value
| ) |  |

Set the time-to-live for this row, overriding the table's default value.

An application can set this on a row before storing it in the table to override the table's default TTL value.

It is an error to set this column on a row if the row's table does not have expiration enabled.

Parameters

  e | The exception object captures information about failures.
  row | The call sets the column in this row.
  value | The number of seconds before the row becomes available for expiration.

Returns
  void

## ◆ tibdgRow_ToString()

TIBDG_API tibint32_t tibdgRow_ToString | ( | tibEx | e,
|  | tibdgRow | row,
|  | char * | buffer,
|  | tibint32_t | size
| ) |  |

Get a printable string that describes the contents of a row.

Programmers estimate the required size of the string buffer. If the buffer is too small (or `NULL`), the call fails, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

Parameters

  e | The exception object captures information about failures.
  row | The call produces a string description of this row.
  buffer | The call stores the description in this string buffer.
  size | The program supplies the length of buffer (in bytes).

Returns
  the actual length of the description string, including terminating `NULL` character (in bytes)

## ◆ tibdgRowIterator_Destroy()

TIBDG_API void tibdgRowIterator_Destroy | ( | tibEx | e,
|  | tibdgRowIterator | rowIterator
| ) |  |

Destroy a row iterator object.

Release all the resources allocated by the tibdgRow_CreateIterator function.

Parameters

  e | The exception object captures information about failures.
  rowIterator | The row iterator object to destroy.

## ◆ tibdgRowIterator_GetNext()

TIBDG_API const char * tibdgRowIterator_GetNext | ( | tibEx | e,
|  | tibdgRowIterator | rowIterator,
|  | tibdgColumnType * | columnType
| ) |  |

Returns the name of the next column and its column type.

This call advances the iterator to the next column and returns the name and type of the column.

If the iterator has already presented the last column of the row, then this call throws the exception TIB_NOT_FOUND.

Parameters

  e | The exception object captures information about failures.
  rowIterator | The row iterator object.
  columnType | The call returns the type of the column. Can be NULL if this is not necessary.

Returns
  The name of the next column.

## ◆ tibdgRowIterator_HasNext()

TIBDG_API tibbool_t tibdgRowIterator_HasNext | ( | tibEx | e,
|  | tibdgRowIterator | rowIterator
| ) |  |

Determine whether a row iterator object can present another column.

This call returns true if the row iterator is ready to present another field. This call returns false if the iterator has presented the last column.

Parameters

  e | The exception object captures information about failures.
  rowIterator | The row iterator object.

Returns
  tibbool_t