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
}
 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 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...
 

Detailed Description

Row objects contain columns with values.

Macro Definition Documentation

#define TIBDG_COLUMN_TYPESTR_DATETIME   "datetime"

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

#define TIBDG_COLUMN_TYPESTR_DOUBLE   "double"

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

#define TIBDG_COLUMN_TYPESTR_INVALID   "invalid"

The string constant used for invalid column types.

#define TIBDG_COLUMN_TYPESTR_LONG   "long"

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

#define TIBDG_COLUMN_TYPESTR_OPAQUE   "opaque"

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

#define TIBDG_COLUMN_TYPESTR_STRING   "string"

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

#define TIBDG_COLUMN_TYPESTR_UNKNOWN   "unknown"

The string constant used for unknown column types.

Enumeration Type Documentation

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

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

Get the column type object from a string representation.

Parameters
eThe exception object captures information about failures.
columnTypeStringThe string type name to convert.
Returns
a column type object
TIBDG_API const char* tibdgColumnType_ToString ( tibEx  e,
tibdgColumnType  columnType 
)

Get the string representation of the column type object.

Parameters
eThe exception object captures information about failures.
columnTypeThe type to convert
Returns
On success, this call returns the corresponding string name for the column type.
On failure, this call returns NULL.
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
eThe exception object captures information about failures.
rowThe call clears all fields in this row.
Returns
void
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
eThe exception object captures information about failures.
rowThe row to copy
Returns
tibdgTable
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
eThe exception object captures information about failures.
tableThe table which creates this row
Returns
tibdgRow
TIBDG_API void tibdgRow_Destroy ( tibEx  e,
tibdgRow  row 
)

Destroy a row object.

Release all the resources allocated by the tibdgRow_Create function.

Parameters
eThe exception object captures information about failures.
rowThe row object to be destroyed.
Returns
void
TIBDG_API tibdgColumnType tibdgRow_GetColumnType ( tibEx  e,
tibdgRow  row,
const char *  columnName 
)

Get the type of the column.

Parameters
eThe exception object captures information about failures.
rowThe call get the type of the column in this row.
columnNameThe call gets the type of this column
Returns
the column type
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
eThe exception object captures information about failures.
rowThe call gets the value from this row.
columnNameThe call gets the value from this column.
Returns
tibDateTime
TIBDG_API tibdouble_t tibdgRow_GetDouble ( tibEx  e,
tibdgRow  row,
const char *  columnName 
)

Get the value of a double column from a row.

Parameters
eThe exception object captures information about failures.
rowThe call gets the value from this row.
columnNameThe call gets the value from this column.
Returns
tibdouble_t
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
eThe exception object captures information about failures.
rowThe 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.
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
eThe exception object captures information about failures.
rowThe call gets the value from this row.
columnNameThe call gets the value from this column.
Returns
a 64-bit integer value
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
eThe exception object captures information about failures.
rowThe call gets the value from this row.
columnNameThe call gets the value from this column.
sizeThe call returns the length (in bytes) of the opaque field.
Returns
a pointer to the string field
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
eThe exception object captures information about failures.
rowThe call gets the value from this row.
columnNameThe call gets the value from this column.
Returns
a pointer to the string field
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
eThe exception object captures information about failures.
rowThe row of which to get the table
Returns
tibdgTable if a row is associated with a single table. NULL otherwise
TIBDG_API tibbool_t tibdgRow_IsColumnSet ( tibEx  e,
tibdgRow  row,
const char *  columnName 
)

Determine whether a column is set in a row.

Parameters
eThe exception object captures information about failures.
rowThe call checks in this row.
columnNameThe call checks for a column with this name.
Returns
tibbool_t
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
eThe exception object captures information about failures.
rowThe call sets the field in this row.
columnNameThe call sets the value of the column with this name.
dateTimeThe call sets this DateTime as the column value.
Returns
void
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
eThe exception object captures information about failures.
rowThe call sets the column in this row.
columnNameThe call sets the value of the field with this name.
valueThe call sets this double as the column value.
Returns
void
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
eThe exception object captures information about failures.
rowThe call sets the column in this row.
columnNameThe call sets this column.
valueThe call sets this long integer as the value.
Returns
void
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
eThe exception object captures information about failures.
rowThe call sets the column in this row.
columnNameThe call sets the value of the column with this name.
valueThe call copies this byte-array into the column.
sizeSupply the length (in bytes) of the opaque value.
Returns
void
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
eThe exception object captures information about failures.
rowThe call sets the column in this row.
columnNameThe call sets this column.
valueThe call sets this string as the value.
Returns
void
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
eThe exception object captures information about failures.
rowThe call sets the column in this row.
valueThe number of seconds before the row becomes available for expiration.
Returns
void
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
eThe exception object captures information about failures.
rowThe call produces a string description of this row.
bufferThe call stores the description in this string buffer.
sizeThe program supplies the length of buffer (in bytes).
Returns
the actual length of the description string, including terminating NULL character (in btyes)