ctdbFilterRecord

Set the filtering logic for the table.

Declaration

CTDBRET ctdbFilterRecord(CTHANDLE Handle, pTEXT expr)

Description

ctdbFilterRecord() sets the filtering for a table. When set, all records retrieved from the table are filtered against the expression and only records matching this criteria will be returned. This feature is temporary and the effect is limited to the user who sets the filter. The filter is turned off when the table is closed, or when ctdbFilterRecord() is called with the record or table handle and NULL in the parameter expr. If a new expression is set to a table with a current filter, the old filter is replaced with the new one. Just one filter may be active per table per user.

When used in the client/server model, this feature has the potential to increase the performance since only records matching the criteria will be returned, reducing the network traffic.

The first time you include a "tableFilter" string in a "getRecords..." action, the server processes the string to produce an optimized filter. The server automatically reuses the optimized filter in subsequent calls to eliminate the initial processing overhead.

ctdbGetFilter() may be used to retrieve the filter and ctdbIsFilteredRecord() to verify if there is a filter in the table.

Handle [in] the table or record handle.
expr [in] the filtering expression. The valid expressions are described in the section titled FairCom DB Conditional Expression Parser.

If the functionality described in the FairCom DB Conditional Expression Parser does not provide the necessary filtering logic, a user-defined expression may be used. This so-called "callback routine" is passed to the filter with an "at" sign (@) in the beginning of the expression. What follows the @ is going to be the identifier to the user to handle in the routine ctfiltercb() (located in ctclbk.c). Notice that this is considered an advanced feature because it requires editing a c-tree source file to insert the call to the user-defined routine(s).

Returns

ctdbFilterRecord() returns CTDBRET_OK on success, or the c-tree error code on failure.

See also

ctdbGetFilter(), ctdbIsFilteredRecord(), ctdbRecordSetOn()

ctdbFindActiveDatabase

Get the handle of an active/connected database by name.

Declaration

CTHANDLE ctdbFindActiveDatabase(CTHANDLE Handle, pTEXT Name)

Description

ctdbFindActiveDatabase() retrieves the handle of an active/connected database in the session by name.

To get the handle of an active/connected database by the Unique Identifier, use ctdbFindActiveDatabaseByUID(). A database is active if it is connected to the session handle via its database handle.

To get the path of any database in the session dictionary by name, use ctdbFindDatabase().

Handle [in] the session handle.
Name [in] the string with the database name to lookup in the session.

Returns

ctdbFindActiveDatabase() returns the database handle or NULL if the database is not in the session dictionary or is not active/connected.

See also:
ctdbFindActiveDatabaseByUID(), ctdbFindDatabase()

ctdbFindActiveDatabaseByUID

Get the handle of an active/connected database by its unique identifier.

Declaration

CTHANDLE ctdbFindActiveDatabaseByUID(CTHANDLE Handle, ULONG uid)

Description

ctdbFindActiveDatabaseByUID() retrieves the handle of an active/connected database in a session by its unique identifier. A database is considered "active" for a given client application if that client has connected that database to the session handle using the ctdbConnect() function.

Note that the UID of a database persists as long as that database remains in the session dictionary. Removing a database from a session dictionary and then re-adding it to the session dictionary is very likely to change that database’s UID.

Use ctdbFindActiveDatabase() to get the handle of an active database by name. Use ctdbGetDatabaseUID() or ctdbGetActiveDatabaseUID() to retrieve the database UID.

Handle [in] - handle of the session that will be searched.
uid [in] - the unique database identifier, used to locate the database. It is set automatically when the database is created and when the database is added to a session dictionary.

Returns

ctdbFindActiveDatabaseByUID() returns the database handle or NULL if the database is not in the session dictionary or is not active/connected. Note: If the specified database is not in the session dictionary, then the UID must be considered invalid.

See also:
ctdbFindDatabaseByUID(), ctdbFindActiveDatabase(), ctdbGetDatabaseUID(), ctdbGetActiveDatabaseUID()

ctdbFindActiveTable

Get the handle of an active table by name.

Declaration

CTHANDLE ctdbFindActiveTable(CTHANDLE Handle, pTEXT Name)

where:

Handle [in] - the handle of the database dictionary to search.
Name [in] - the string with the table name to lookup in the database dictionary.

Description

ctdbFindActiveTable() retrieves the table handle of an active/open table in the given database dictionary by name.

To get the handle of an active table by the Unique Identifier, use ctdbFindActiveTableByUID().

To retrieve the table handle of the first active table in the database dictionary, use ctdbGetFirstActiveTable().

To get the path of any table in the database dictionary by name, use ctdbFindTable().

Returns

ctdbFindActiveTable() returns the table handle or NULL if the table is not in the database dictionary or if the table is not active/open.

See also

ctdbFindActiveDatabaseByUID(), ctdbFindTable(), ctdbGetFirstActiveTable()

ctdbFindActiveTableByUID

Get the handle of an active/open table by its unique identifier.

Declaration

CTHANDLE ctdbFindActiveTableByUID(CTHANDLE Handle, ULONG uid)

Description

ctdbFindActiveTableByUID() retrieves the handle of an active/open a table in a database dictionary by the table’s unique identifier.

Use ctdbFindActiveTable() to get the handle of an active/open table by name.

Use ctdbFindTableByUID() to get the name and path of any table in the database dictionary by its Unique identifier.

Handle [in] - the handle of the database to be searched.
uid [in] - the unique table identifier, used to locate the table. It is set automatically when the table is created.

Returns

ctdbFindActiveTableByUID() returns the table handle or NULL if the specified table is not in the database dictionary or is not active/open.

See also

ctdbFindTableByUID(), ctdbFindActiveTable(), ctdbGetDatabaseUID()

ctdbFindDatabase

Get the path of a database by name.

Declaration

CTDBRET ctdbFindDatabase(CTHANDLE Handle, pTEXT Name, pTEXT Path, VRLEN PathSize)

Description

ctdbFindDatabase() retrieves the path of any database in the session dictionary by name.

Use ctdbFindDatabaseByUID() to get the name and path of a database by its unique identifier.

Use ctdbFindActiveDatabase() to get the session handle of an active/connected database by name.

Handle [in] - the handle of the session dictionary that will be searched.
Name [in] - the string with the database name to lookup in the session dictionary.
Path [out] - receives the database path, if the name is located and Path is large enough to hold the database path.
PathSize [in] - the size in bytes of Path. If Path is not large enough to receive the database path, ctdbFindDatabase() will return CTDBRET_ARGSMALL (4006).

Returns

ctdbFindDatabase() returns CTDBRET_OK on success, or INOT_ERR (101) if the database is not in the session dictionary, or a c-tree error code on failure.

Example

eRet = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");
eRet = ctdbFindDatabase(hSession, db_name, db_path, sizeof(db_path));

See also

ctdbFindDatabaseByUID(), ctdbFirstDatabase(), ctdbNextDatabase(), ctdbFindActiveDatabase()

ctdbFindDatabaseByUID

Get the name and path of a database by its unique identifier.

Declaration

CTDBRET ctdbFindDatabaseByUID(CTHANDLE Handle, ULONG uid, pTEXT Name, VRLEN NameSize, pTEXT Path, VRLEN PathSize)

Description

Handle [in] - the handle of the session dictionary that will be searched. If you specify a database handle, then the session dictionary which that database is currently connected to will be searched.
uid [in] - the unique database identifier, used to locate the database. It is set automatically when the database is created or added to the session dictionary.
Name [out] - the string with the database name.
NameSize [in] - the size in bytes of Name. If Name is not large enough to receive the database name, ctdbFindDatabaseByUID() will return CTDBRET_ARGSMALL (4006).
Path [out] - the database path, if the name is located in the session and Path is large enough to hold the database path. The path includes drive, directory, file name and file extension.
PathSize [in] - the size in bytes of Path. If Path is not large enough to receive the database path, ctdbFindDatabaseByUID() will return CTDBRET_ARGSMALL (4006).

Description

ctdbFindDatabaseByUID() retrieves the name and path of any database in a session dictionary by its unique identifier. It is important to remember that the UID of a database is set when the database is created (which automatically adds it to a session dictionary), and when an existing database is added to a session dictionary. Dropping a database from a session dictionary and then adding it again will likely result in the database being assigned a different UID.

Use ctdbFindDatabase() to get the path of a database by name.

Use ctdbGetDatabaseUID() or ctdbGetActiveDatabaseUID() to retrieve the database UID.

Returns

ctdbFindDatabaseByUID() returns CTDBRET_OK on success, or INOT_ERR (101) if the database is not in the session dictionary, or a c-tree error code on failure. Note: If the database is not found in the session dictionary, then the UID must be considered invalid.

See also
ctdbFindDatabase(), ctdbGetDatabaseUID(), ctdbGetActiveDatabaseUID()

ctdbFindRecord

Find a record using the FindMode as the find strategy.

Declaration

CTDBRET ctdbFindRecord(CTHANDLE Handle, CTFIND_MODE FindMode)

Description

ctdbFindRecord() finds a record in the table associated with the record handle, using the FindMode strategy. The record data is retrieved from disk into the record handle’s record buffer and the current record is set to that record. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves.

Handle [in] the record handle.
FindMode [in] the mode to use to look for the record in the table. The find modes are listed in FairCom DB API definitions.

Before using ctdbFindRecord(),

clear the record buffer with ctdbClearRecord()
select the index to search with ctdbSetDefaultIndex()
set search target values with one or more of the ctdbSetFieldAs...() functions
call ctdbFindRecord()

Note: The FindMode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Use ctdbFirstRecord() to retrieve the first record of a table, ctdbNextRecord() to retrieve the next record of a table, ctdbPrevRecord() to retrieve the previous record of a table, and ctdbLastRecord() to retrieve the last record of a table. Use ctdbFindTarget() to find a record using a given target key.

Returns

ctdbFindRecord() returns CTDBRET_OK if the record was found, or INOT_ERR (101) if no record was found. Any other return value indicates an error condition (FairCom DB API error).

Example

ctdbClearRecord(hRec);

ctdbSetDefaultIndex(hRec, 1);

ctdbSetFieldAsString(hRec, ctdbGetFieldNumberByName(hRec, "Name"), name);

ctdbFindRecord(hRec, CTFIND_EQ);

See also

ctdbAllocRecord(), ctdbFirstRecord(), ctdbNextRecord(), ctdbPrevRecord(), ctdbLastRecord(), ctdbFindTarget(), ctdbClearRecord(), ctdbSetDefaultIndex()

ctdbFindResource

Locate and retrieve a resource by type and number.

Declaration

CTDBRET ctdbDECL ctdbFindResource(CTHANDLE resource, ULONG type, ULONG number, CTBOOL lock)

Description

ctdbFindResource() locates and retrieves a resource in a table based on type and number. resource is a handle allocated with ctdbAllocHandle(). type and number identify the resource and lock is used to indicate if the resource should be locked, if it is found.

Return

ctdbFindResource() returns CTDBRET_OK on success. If the specified resource is not in the table, ctdbFindResource() returns RNOT_ERR (408).

Example

/* display a particular resource */

CTDBRET DisplayResource(CTHANDLE hTable, ULONG type, ULONG number)

{

CTDBRET eRet;

CTHANDLE hRes = ctdbAllocResource(hTable, 0, 0, NULL);

/* check if resource was allocated */

if (!hRes)

return ctdbGetError(hTable);

/* note that no resource locks are acquired since we are not changing the resources */

if ((eRet = ctdbFindResource(hRes, type, number, NO)) == CTDBRET_OK)

{

printf("Resource type: %u, number: %u", ctdbGetResourceType(hRes), ctdbGetResourceNumber(hRes));

if (ctdbGetResourceName(hRes) != NULL)

printf(", name: \"\"\n", ctdbGetResourceName(hRes));

else

printf(", name: NULL"\n");

}

ctdbFreeResource(hRes);

return eRet;

}

See also

ctdbAllocResource(), ctdbFreeResource(), ctdbAddResource(), ctdbFirstResource(), ctdbNextResource(), ctdbDeleteResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbSetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUpdateResource(), ctdbUnlockResource()

ctdbFindResourceByName

Locate and retrieve a resource by name.

Declaration

CTDBRET ctdbDECL ctdbFindResourceByName(CTHANDLE resource, pTEXT name, CTBOOL lock);

Description

ctdbFindResourceByName() locates and retrieves a resource by name. FairCom DB cannot guarantee unique resource names. resource is a handle allocated with ctdbAllocHandle(). name is the resource name and lock is used to indicate if the resource should locked, if it is found.

Return

ctdbFindResourceByName() returns CTDBRET_OK on success. If there are no resources for the table with the specified name, ctdbFindResourceByName() returns RNOT_ERR (408).

Example

/* display a particular resource */

CTDBRET DisplayResource(CTHANDLE hTable, pTEXT name)

{

CTDBRET eRet;

CTHANDLE hRes = ctdbAllocResource(hTable, 0, 0, NULL);

/* check if resource was allocated */

if (!hRes)

return ctdbGetError(hTable);

/* note that no resource locks are acquired since we are not changing the resources */

if ((eRet = ctdbFindResourceByName(hRes, name, NO)) == CTDBRET_OK)

{

printf("Resource type: %u, number: %u", ctdbGetResourceType(hRes), ctdbGetResourceNumber(hRes));

if (ctdbGetResourceName(hRes) != NULL)

printf(", name: \"\"\n", ctdbGetResourceName(hRes));

else

printf(", name: NULL"\n");

}

ctdbFreeResource(hRes);

return eRet;

}

See Also

ctdbAllocResource, ctdbFreeResource, ctdbAddResource, ctdbDeleteResource, ctdbUpdateResource, ctdbFirstResource, ctdbNextResource, ctdbFindResource, ctdbGetResourceType, ctdbSetResourceType, ctdbGetResourceNumber, ctdbSetResourceNumber, ctdbGetResourceName, ctdbSetResourceName, ctdbGetResourceDataLength, ctdbGetResourceData, ctdbSetResourceData, ctdbIsResourceLocked, ctdbUnlockResource

ctdbFindRowid

Find a record based on its rowid.

Declaration

CTDBRET ctdbFindRowid(CTHANDLE Handle, CTROWID rowid,

CTFIND_MODE FindMode)

Description

ctdbFindRowid() retrieves the record, given its rowid. The record data is retrieved from disk into the record handle’s record buffer and the current record is set to that record. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves.

Handle [in] the record handle.
rowid [in] the rowid value.
FindMode [in] the mode to use to look for the record in the table. The find modes are listed in FairCom DB API definitions.

Note: The FindMode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Returns

ctdbFindRowid() returns CTDBRET_OK on success, or INOT_ERR (101) if no record is found with the specified rowid. Any other return value indicates an error condition (FairCom DB API error).

See also

ctdbAllocRecord(), ctdbGetRowid(), ctdbHasRowid()

ctdbFindTable

Get the path of a table in a database dictionary.

Declaration

CTDBRET ctdbFindTable(CTHANDLE Handle, pTEXT Name, pTEXT Path,

VRLEN PathSize)

Description

ctdbFindTable() retrieves the path of a table in a database dictionary by name. Use ctdbFindTableByUID() to get the name and path of a table by its unique identifier. Use ctdbFindActiveTable() to get the handle of an active/connected table by name.

Handle [in] the handle of the database to search.
Name [in] the string with the table name to lookup in the database dictionary.
Path [out] receives the table path.
PathSize [in] the path size in bytes.

ctdbFirstTable() and ctdbNextTable() may be used to obtain the names and paths of all the tables in this database dictionary.

Returns

ctdbFindTable() returns CTDBRET_OK on success, or INOT_ERR (101) if the table cannot be found in the database dictionary, or a c-tree error code on failure.

Example

eRet=ctdbFindTable(hDbase, tb_name, tb_path, sizeof (tb_path));

See also

ctdbAllocDatabase(), ctdbFindTableByUID(), ctdbFirstTable(), ctdbNextTable()

ctdbFindTableByUID

Get the name and path of a table in a database dictionary by its unique identifier.

Declaration

CTDBRET ctdbFindTableByUID(CTHANDLE Handle, ULONG uid, pTEXT Name,

VRLEN NameSize, pTEXT Path, VRLEN PathSize)

Description

ctdbFindTableByUID() retrieves the name and path of a table in a database dictionary by its unique identifier. Use ctdbFindTable() to get the path of a table in the database dictionary by name. Use ctdbGetTableUID() to retrieve the table UID.

Handle [in] the handle of the database to be searched.
uid [in] the unique table identifier, used to find the table.
Name [out] the string with the table name.
NameSize [in] the name size in bytes. If Name is not large enough to receive the table name, ctdbFindTableByUID() will return CTDBRET_ARGSMALL (4006).
Path [out] the path of the table, if the table is located, and it is large enough to hold the path. The path includes drive, directory, name and extension.
PathSize [in] the path size in bytes. If Path is not large enough to receive the table path, ctdbFindTableByUID() will return CTDBRET_ARGSMALL (4006).

Returns

ctdbFindTableByUID() returns CTDBRET_OK on success, or INOT_ERR (101) if the table cannot be found in the database dictionary, or a c-tree error code on failure.

See also

ctdbFindTable(), ctdbFirstTable(), ctdbNextTable(), ctdbGetTableUID()

ctdbFindTableDictionaryMark

Find a table in a database dictionary and retrieve its dictionary attributes.

Declaration

CTDBRET ctdbDECL ctdbFindTableDictionaryMark(CTHANDLE Handle, pTEXT Name, pUCOUNT Dictmark)

Description

Handle [IN] - Database handle
Name [IN] - Table name
Dictmark [OUT] - Table mark. see _DICT_VERMARK_TBL_* in ctdbport.h

Returns

Returns CTDBRET_OK on success or the c-tree error code on failure.

See Also

ctdbSetDatabaseTableMarkFilter() (ctdbSetDatabaseTableMarkFilter, ctdbSetDatabaseTableMarkFilter)
ctdbSetTableDictionaryMark() (ctdbSetTableDictionaryMark, ctdbSetTableDictionaryMark)

ctdbFindTableXtd

Find a table in a database dictionary.

Declaration

CTDBRET ctdbDECL ctdbFindTableXtd(CTHANDLE Handle, pTEXT Name, pCTDBDICTDATA data)

Description

CTDB dictionary also stores the table owner while searching for a specific table.

Handle [IN] - Database handle

Name [IN] - Table name

data [OUT] - dictionary data for the table

At table open time, set the table owner in the CTHANDLE structure as defined in the dictionary so that this information is available in the table handle itself.

Return Values

Returns CTDBRET_OK on success or the c-tree error code on failure.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctdbFindTable

ctdbFindTarget

Find a record using a target key.

Declaration

CTDBRET ctdbFindTarget(CTHANDLE Handle, pVOID target,

CTFIND_MODE FindMode)

Description

ctdbFindTarget() finds a record with a given target key. The record data is retrieved from disk into the record handle’s record buffer and the current record is set to that record. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves. Use ctdbFindRecord() to find a record with the FindMode() strategy.

Handle [in] the record handle.
target [in] string with the key target to lookup in the table.
FindMode [in] the mode to use to look for the record in the table. The find modes are listed in FairCom DB API definitions.

The target key MUST be transformed (use ctdbBuildTargetKey() if necessary).

Note: The Find Mode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Note: Prior to FairCom DB V9.1, the key target in FindTarget() must NOT be transformed. When using functions such as TransformKey() or BuildTargetKey(), you must suppress the transformation of the already-transformed key. In order to do this, you may define a macro NOTRANSFORM with a value of 0x1000 and OR it into the mode passed to FindTarget().

Returns

ctdbFindTarget() returns CTDBRET_OK if the record was found, or INOT_ERR (101) if no record is found. Any other return value indicates an error condition (FairCom DB API error).

See also

ctdbAllocRecord(), ctdbFindRecord()

ctdbFirstDatabase

Get the name and path of the first database in a session dictionary.

Declaration

CTDBRET ctdbFirstDatabase(CTHANDLE Handle, pTEXT Name, VRLEN NameSize, pTEXT Path, VRLEN PathSize)

Description

ctdbFirstDatabase() gets the name and path of the first database in the specified session dictionary.

Handle [in] the a session handle.
Name [out] receives the database name.
NameSize [in] the name size in bytes. If Name is not large enough to receive the database name, ctdbFirstDatabase() will return CTDBRET_ARGSMALL (4006).
Path [out] receives the database path, if the name is located and it is large enough to hold the path, and is returned by the function ctdbFirstDatabase().
PathSize [in] the path size in bytes. If Path is not large enough to receive the database path, ctdbFirstDatabase() will return CTDBRET_ARGSMALL (4006).

ctdbFirstDatabase(), in conjunction with ctdbNextDatabase(), may be used to obtain the names and paths of all Databases in this session dictionary. ctdbGetDatabaseCount() may be used to retrieve the total number of databases in the session dictionary.

Returns

ctdbFirstDatabase() returns CTDBRET_OK on success, or INOT_ERR (101) if there are no databases in the session dictionary, or a c-tree error code on failure.

Example

ctdbFirstDatabase(hSession, name, sizeof(name), path, sizeof(path));
do {
       printf("\n\nDatabase: %s   (%s)\n", path, name);
   }
while (
   ctdbNextDatabase(hSession, name, sizeof(name), path, sizeof(path))
      ==  CTDBRET_OK   );

See also
ctdbNextDatabase(), ctdbGetDatabaseCount(), ctdbFindDatabase(), ctdbFirstTable()

ctdbFirstRecord

Get the first record of a table

Declaration

CTDBRET ctdbFirstRecord(CTHANDLE Handle)

Description

ctdbFirstRecord() retrieves the first record of a table and copies the record data from disk into the specified record handle’s record buffer, and sets the current record to that first record. The ordering of the records is done through one of the indexes that was defined during the table creation. To define which index is sorting the table, use ctdbSetDefaultIndex(). Initially, the default index is the first defined index during the table creation.

Handle [in] the record handle.

If sets are enabled by ctdbRecordSetOn(), ctdbFirstRecord() will retrieve the first record in the set. Use ctdbNextRecord() to retrieve the next record on a table, ctdbPrevRecord() to retrieve the previous record on a table, and ctdbLastRecord() to retrieve the last record on a table. Use ctdbFindRecord() to find a specific record on a table. Note that, if session-wide record locking is enabled, this function will also lock the record it retrieves.

Returns

ctdbFirstRecord() returns CTDBRET_OK on success, or INOT_ERR (101) if the table contains no records, or a FairCom DB API error on failure.

See also

ctdbAllocRecord(), ctdbNextRecord(), ctdbPrevRecord(), ctdbLastRecord(), ctdbFindRecord(), ctdbRecordSetOn(), ctdbSetDefaultIndex()

ctdbFirstResource

Locate and retrieve the first resource in a table.

DECLARATION

CTDBRET ctdbDECL ctdbFirstResource(CTHANDLE resource, CTBOOL lock);

DESCRIPTION

ctdbFirstResource() retrieve the first resource stored in a table.

resource is a handle allocated with ctdbAllocHandle().
lock is used to indicate if the resource should be locked, if it is found.

RETURN

ctdbFirstResource() returns CTDBRET_OK on success. If there are no resources for the table, ctdbFirstResource() return RNOT_ERR (408).

EXAMPLE

CTDBRET DisplayAllResources(CTHANDLE hTable)
{
	CTDBRET eRet;
	CTHANDLE hRes = ctdbAllocResource(hTable, 0, 0, NULL);
	
	/* check if resource was allocated */
	if (!hRes)
		return ctdbGetError(hTable);
 
	/* get the first resource */
	/* note that no resource locks are acquired since we are not changing the resources */
	if ((eRet = ctdbFirstResource(hRes, false)) != CTDBRET_OK)
	{
		ctdbFreeResource(hRes);
		return eRet;
	}
	/* get the other resources */
	do
	{
		/* display resource type, number and name */
		printf("Resource type: %u, number: %u", ctdbGetResourceType(hRes), ctdbGetResourceNumber(hRes));
		if (ctdbGetResourceName(hRes) != NULL)
			printf(", name: \"\"\n", ctdbGetResourceName(hRes));
		else
			printf(", name: NULL"\n");
	}
	while ((eRet = ctdbNextResource(hRes, false)) == CTDBRET_OK);
	ctdbFreeResource(hRes);
	return eRet;
}

SEE ALSO
ctdbFreeResource(), ctdbAddResource(), ctdbDeleteResource(), ctdbUpdateResource(), ctdbAllocResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbSetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUnlockResource()

ctdbFirstTable

Get the name and path of the first table in a database dictionary.

Declaration

CTDBRET ctdbFirstTable(CTHANDLE Handle, pTEXT Name, VRLEN NameSize,

pTEXT Path, VRLEN PathSize)

Description

ctdbFirstTable() gets the name and path of the first table in a database dictionary.

Handle [in] the database handle.
Name [out] receives the table name.
NameSize [in] the Name size in bytes.
Path [out] receives the table path.
PathSize [in] the Path size in bytes.

ctdbFirstTable(), in conjunction with ctdbNextTable(), may be used to obtain the names and paths of all the tables in this database dictionary. ctdbGetTableCount() may be used to retrieve the total number of tables in the database dictionary.

Returns

ctdbFirstTable() returns CTDBRET_OK on success, or INOT_ERR (101) if there are no tables in the database dictionary, or a c-tree error code on failure.

Example

ctdbFirstTable(hDB, t_name, sizeof(t_name), t_path, sizeof (t_path));

{ printf("\ntable name: %s", t_name); }

while (ctdbNextTable(hDB, t_name, sizeof(t_name), t_path,

sizeof(t_path)) == CTDBRET_OK);

See also

ctdbFirstDatabase(), ctdbNextTable(), ctdbFindTable(), ctdbGetTableCount()

ctdbFirstTableXtd

Get the first table in a database dictionary.

Declaration

CTDBRET ctdbDECL ctdbFirstTableXtd(CTHANDLE Handle, pCTDBDICTDATA data)

Description

Handle [IN] - Database handle.

data [OUT] - dictionary data for the table

CTDBRET_OK on success or the c-tree error code on failure.

Return Values

CTDBRET_OK on success or the c-tree error code on failure.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctdbFirstTable

ctdbFloatToBigInt

Convert a float to a big integer value.

Declaration

CTDBRET ctdbFloatToBigInt(CTFLOAT value, pCTBIGINT pBigInt)

Description

ctdbFloatToBigInt() converts a float to a big integer value. A big integer is an 8 bytes integer value. Use ctdbBigIntToFloat() to convert from a big integer to a float.

value [in] the float value.
pBigInt [out] the big integer value (8 bytes signed integer).

Returns

ctdbFloatToBigInt() returns CTDBRET_OK on success, or FairCom DB API error on failure.

The possible error associated with ctdbFloatToBigInt() is:

CTDBRET_NULARG (4007): Null argument not valid in pStr

See also

ctdbBigIntToFloat()

ctdbFloatToCurrency

Convert a float value to a CTCURRENCY value.

Declaration

CTDBRET ctdbFloatToCurrency(CTFLOAT value, pCTCURRENCY pCurrency)

Description

ctdbFloatToCurrency() converts a floating point value to a CTCURRENCY (8 bytes signed integer) value. Use ctdbCurrencyToFloat() to convert from a float to a CTCURRENCY value.

value [in] the CTFLOAT value.
pCurrency [out] the CTCURRENCY value (8 bytes integer).

Returns

ctdbFloatToCurrency() returns CTDBRET_OK on success, or FairCom DB API error on failure.

The possible error associated with ctdbFloatToCurrency() is:

CTDBRET_NULARG (4007): Null argument not valid in pStr

See also

ctdbCurrencyToFloat()

ctdbFloatToMoney

Converts a floating point value to a CTMONEY type

Declaration

CTDBRET ctdbFloatToMoney(CTFLOAT value, pCTMONEY pMoney)

Description

ctdbFloatToMoney() converts from a floating point number to CTMONEY. Use ctdbMoneyToFloat() to convert a CTMONEY value to a floating point number.

value [in] the floating point value to convert.
pMoney [out] the pointer to the CTMONEY value.

Returns

ctdbFloatToMoney() returns CTDBRET_OK on success, or FairCom DB API error on failure.

The possible errors associated with ctdbFloatToMoney() are:

CTDBRET_NULARG (4007): Null argument not valid in pStr
CTDBRET_OVERFLOW (4038): Operation caused overflow

See also

ctdbMoneyToFloat()

ctdbFloatToNumber

Convert a float to a CTNUMBER value.

Declaration

CTDBRET ctdbFloatToNumber(CTFLOAT value, pCTNUMBER pNumber)

Description

ctdbFloatToNumber() converts a floating point value to a CTNUMBER value. Use ctdbNumberToFloat() to convert a CTNUMBER to float.

value [in] the float value.
pNumber [out] pointer to CTNUMBER.

Returns

ctdbFloatToNumber() returns CTDBRET_OK on success, or FairCom DB API error on failure.

The possible error associated with ctdbFloatToNumber() is:

CTDBRET_NULARG (4007): Null argument not valid in pNumber

See also

ctdbNumberToFloat()

ctdbFreeDatabase

Release all resources associated with a database handle

Declaration

void ctdbFreeDatabase(CTHANDLE Handle)

Description

ctdbFreeDatabase() releases all resources associated with a database handle. After a call to ctdbFreeDatabase(), the database handle cannot be used for other operations. For each ctdbAllocDatabase() call, there must be a ctdbFreeDatabase() call. Note that if you free / release an active database handle (one that is currently connected to a database), this function will automatically close all tables associated with that database and disconnect that database from the handle before releasing the handle’s resources.

Handle [in] the database handle.

Returns

None.

Example

CTHANDLE hDatabase  = ctdbAllocDatabase(hSession);
ctdbCreateDatabase(hDatabase, "Database1", "");
ctdbFreeDatabase(hDatabase); // the handle cannot be used anymore
See also
ctdbAllocDatabase(), ctdbFreeSession()

See also
ctdbAllocDatabase(), ctdbFreeSession()

ctdbFreeFTI

Release all resources associated with a Full-Text Search handle.

ctdbFreeRecord

Release resources allocated for the record handle.

Declaration

void ctdbFreeRecord(CTHANDLE Handle)

Description

ctdbFreeRecord() releases resources allocated for the record handle. Any record handle allocated with ctdbAllocRecord() should be released with a call to ctdbFreeRecord(). After a call to ctdbFreeRecord(), the record handle cannot be used for other operations.

Handle [in] the record handle.

Returns

None.

See also

ctdbAllocRecord(), ctdbFreeTable()

ctdbFreeResource

Release memory and system resources allocated by ctdbAllocResource().

DECLARATION

CTDBRET ctdbDECL ctdbFreeResource(CTHANDLE resource)

DESCRIPTION

Release system resources allocated by ctdbAllocResource().

resource is a resource handle allocated by ctdbAllocResource().

RETURN

ctdbFreeResource() returns CTDBRET_OK on success or CTDBRET_NOTRESOURCE error if the handle passed to ctdbFreeResource() was not allocated by ctdbAllocResource() or is invalid.

EXAMPLE

CTDBRET DisplayAllResources(CTHANDLE hTable)
{
	CTDBRET eRet;
	CTHANDLE hRes = ctdbAllocResource(hTable, 0, 0, NULL);
	
	/* check if resource was allocated */
	if (!hRes)
		return ctdbGetError(hTable);
 
	/* get the first resource */
	/* note that no resource locks are acquired since we are not changing the resources */
	if ((eRet = ctdbFirstResource(hRes, false)) != CTDBRET_OK)
	{
		ctdbFreeResource(hRes);
		return eRet;
	}
	/* get the other resources */
	do
	{
		/* display resource type, number and name */
		printf("Resource type: %u, number: %u", ctdbGetResourceType(hRes), ctdbGetResourceNumber(hRes));
		if (ctdbGetResourceName(hRes) != NULL)
			printf(", name: \"\"\n", ctdbGetResourceName(hRes));
		else
			printf(", name: NULL"\n");
	}
	while ((eRet = ctdbNextResource(hRes, false)) != CTDBRET_OK);
	ctdbFreeResource(hRes);
	return eRet;
}

SEE ALSO
ctdbFirstResource(), ctdbAddResource(), ctdbDeleteResource(), ctdbUpdateResource(), ctdbAllocResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbSetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUnlockResource()

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

ctdbGetResultSetHandle, ctdbAllocateResultSet, ctdbFreeResultSet, ctdbResultSetOnOff, ctdbGetResultSetByName, ctdbGetResultSetCriHandle, ctdbAddCriteria, ctdbRemoveCriteria, ctdbUpdateCriteria, ctdbGetActiveResultSet

ctdbFreeSession

Release all resources associated with a session

Declaration

void ctdbFreeSession(CTHANDLE Handle)

Description

ctdbFreeSession() releases all resources associated with a session and must be called at application close to free all resources allocated with ctdbAllocSession().

After a call to ctdbFreeSession(), the session handle cannot be used for other operations.

For each ctdbAllocSession() call, there must be ctdbFreeSession().

Handle [in] the session handle.

Returns

None.

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;
CTHANDLE handle  = ctdbAllocSession(ctdbsess);
ctdbCreateSession(handle, "FAIRCOMS", "ADMIN", "ADMIN");
ctdbFreeSession(handle);

See also
ctdbAllocSession(), ctdbFreeDatabase()

ctdbFreeTable

Release resources allocated for the table handle.

Declaration

void ctdbFreeTable(CTHANDLE Handle)

Description

ctdbFreeTable() releases all resources associated with a table handle. After a call to ctdbFreeTable(), the table handle cannot be used for other operations. Note that if you release an active table’s handle (the handle of a table that is open), ctdbFreeTable() automatically closes the table and resets all record buffers associated with the table.

Handle [in] the Table Handle.

Returns

None.

Example

ctdbClose(hTable);

ctdbFreeTable(hTable);

See also

ctdbAllocTable(), ctdbFreeDatabase()

ctdbFTSearchOff

Disable and free an existing Full-Text Search.

ctdbFTSearchOn

Set up a new Full-Text Search.

C API Functions F

ctdbFilterRecord

ctdbFindActiveDatabase

ctdbFindActiveDatabaseByUID

ctdbFindActiveTable

ctdbFindActiveTableByUID

ctdbFindDatabase

ctdbFindDatabaseByUID

ctdbFindRecord

ctdbFindResource

ctdbFindResourceByName

ctdbFindRowid

ctdbFindTable

ctdbFindTableByUID

ctdbFindTableDictionaryMark

ctdbFindTableXtd

ctdbFindTarget

ctdbFirstDatabase

ctdbFirstRecord

ctdbFirstResource

ctdbFirstTable

ctdbFirstTableXtd

ctdbFloatToBigInt

ctdbFloatToCurrency

ctdbFloatToMoney

ctdbFloatToNumber

ctdbFreeDatabase

ctdbFreeFTI

ctdbFreeRecord

ctdbFreeResource

ctdbFreeResultSet

ctdbFreeSession

ctdbFreeTable

ctdbFTSearchOff

ctdbFTSearchOn

Was this article helpful?

C API Functions F

ctdbFilterRecord

ctdbFindActiveDatabase

ctdbFindActiveDatabaseByUID

ctdbFindActiveTable

ctdbFindActiveTableByUID

ctdbFindDatabase

ctdbFindDatabaseByUID

ctdbFindRecord

ctdbFindResource

ctdbFindResourceByName

ctdbFindRowid

ctdbFindTable

ctdbFindTableByUID

ctdbFindTableDictionaryMark

ctdbFindTableXtd

ctdbFindTarget

ctdbFirstDatabase

ctdbFirstRecord

ctdbFirstResource

ctdbFirstTable

ctdbFirstTableXtd

ctdbFloatToBigInt

ctdbFloatToCurrency

ctdbFloatToMoney

ctdbFloatToNumber

ctdbFreeDatabase

ctdbFreeFTI

ctdbFreeRecord

ctdbFreeResource

ctdbFreeResultSet

ctdbFreeSession

ctdbFreeTable

ctdbFTSearchOff

ctdbFTSearchOn

Was this article helpful?

Related Articles

FairCom ISAM API for C - Developers Guide Overview

ISAM for C Data Management

ISAM for C Operational Models