Result Sets

ctdbAddCriteria

Adds a new criteria to the given CTResultSet handle

Declaration

CTHANDLE ctdbAddCriteria(CTHANDLE Handle, CTHANDLE FieldHandle,
pTEXT LowValue, pTEXT HighValue, NINT CriteriaOp)

Parameters:

  • Handle [IN] - Result Set handle.
  • FieldHandle [IN] - Field handle.
  • LowValue [IN] - Low Criteria Value.
  • HighValue [IN] - High Criteria Value. If operator requires only one criteria value, only the LowValue will be used (this one will be ignored).
  • CriteriaOp [IN] - Criteria Operator. Can be CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE, or CTIX_NOTBET.

Description

The result set handle is allocated with ctdbAllocateResultSet() for a specific table handle, and then it is possible to add one or more criteria with ctdbAddCriteria(). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

A CTResultSetCri handle. NULL otherwise.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

 

ctdbAllocateResultSet

 

Declaration

CTHANDLE ctdbAllocateResultSet(CTHANDLE Handle, pTEXT ResSetName);

Parameters:

  • Handle [IN] - Table handle
  • ResSetName [IN] - Result Set name

Description

Allocates a result set for a specific table handle. It is also added to the table result set list for later searching.

After allocating, it is then possible to add one or more criteria using ctdbAddCriteria(). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off with ctdbResultSetOnOff() for any record handle that is allocated for the same table handle that owns the result set.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect.

Returns

Return a CTResultSet handle on success, or NULL on error.

Example

   CTHANDLE hResSet;

   CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

    Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

    Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

    Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

 

ctdbFreeResultSet

Releases resources associated with the result set handle.

Declaration

VOID ctdbFreeResultSet(CTHANDLE Handle);

Parameters:

  • Handle [IN] - Result Set handle

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

None.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

 

ctdbGetActiveResultSet

Declaration

CTHANDLE ctdbGetActiveResultSet(CTHANDLE Handle);

Description

Retrieves the Result Set handle active for the given Record handle.

Parameters:

  • Handle [IN] - Record handle

Return Values

Returns a Result Set handle if any is active, or NULL on error.

Value

Symbolic Constant

Explanation

0

CTDBRET_OK

Successful operation.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

See Also

 

ctdbGetResultSetByName

Retrieves the CTResultSet handle for a given name.

Declaration

CTHANDLE ctdbGetResultSetByName(CTHANDLE Handle, pTEXT ResSetName)

Parameters:

  • Handle [IN] - Table handle
  • ResSetName [IN] - Result Set name

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

A CTResultSet handle. NULL otherwise.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

ctdbGetResultSetCriHandle

Retrieves the CTResultSetCri handle for a given name.

Declaration

CTHANDLE ctdbGetResultSetCriHandle(CTHANDLE Handle)

Parameter:

  • Handle [IN] - Result Set Criteria handle.

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

A CTResultSetCri handle. NULL otherwise.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

ctdbGetResultSetHandle

Retrieves the Result Set handle based on a CTResultSet or CTResultSetCri handle.

Declaration

CTHANDLE ctdbGetResultSetHandle(CTHANDLE Handle);

Parameter:

  • Handle [IN] - Result Set or Result Set Criteria handle.

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect.

Returns

A handle to a result set type. NULL on error.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

 

ctdbRemoveCriteria

Removes a criteria from the given CTResultSet handle.

Declaration

ctdbRemoveCriteria(CTHANDLE Handle, CTHANDLE CriteriaHandle)

Parameters:

  • Handle [IN] - Result Set handle
  • CriteriaHandle [IN] - Result Set Criteria Handle

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

CTDBRET_OK on success. CTDBRET error code on failure.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

 

ctdbResultSetOnOff

Attaches or detaches a result set from a record handle.

Declaration

CTDBRET ctdbResultSetOnOff(CTHANDLE Handle, CTHANDLE RecordHandle,
CTBOOL OnOffFlag, CTBOOL AutoSortFlag, CTLOC_MODE LocateMode)

Parameters:

  • Handle [IN] - Result Set handle.
  • RecordHandle [IN] - Record handle.
  • OnOffFlag [IN] - YES, if it is turning ON; or NO, if it is turning OFF.
  • AutoSortFlag [IN] - YES, if FairCom DB API can choose the best index, or NO, if the current index must be kept.
  • LocateMode [IN] - The find modes are: CTLOC_NONE, CTLOC_CASEIN, CTLOC_PARTIAL, and CTLOC_CASEIN_PARTIAL.

Description

ctdbResultSetOnOff() attaches or detaches a given CTResultSet handle to a given record handle. It checks if the result set's table is the of the record and also checks if there isn't any existing filter applied to the record. If there is any, it is not possible to set the result set ON.

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

Return CTDBRET_OK on success. CTDBRET code for failure.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

 

ctdbUpdateCriteria

Updates the criteria from the given CTResultSet handle.

Declaration

ctdbUpdateCriteria(CTHANDLE Handle, pTEXT LowValue, pTEXT HighValue)

Parameters:

  • Handle [IN] - Result Set Criteria handle
  • LowValue [IN] - New criteria low value
  • HighValue [IN] - New criteria high value

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

It is not possible to change the field nor operator as it may be required to change the index used.

Limitations

  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

CTDBRET_OK on success. CTDBRET error code on failure.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

 

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");


/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");


/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");


/* Display records on the Result Set */

Display_Records(hRecord);


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

data outcomes

Was this article helpful?

Give feedback about this article

Related Articles