ctdbAttachSession

Attaches an already initialized c-tree session to a FairCom DB API session handle.

DECLARATION

CTDBRET ctdbDECL ctdbAttachSession(CTHANDLE Handle, pVOID source, CTATTACH_MODE mode, CTBOOL isTransactionActive);

DESCRIPTION

ctdbAttachSession() attaches an already initialized c-tree ISAM or low-level session to a FairCom DB API session handle. Attached sessions have no information about the server, user name or user password, and these values are set to NULL.

• Handle is a Session handle allocated by ctdbAllocSession().
• source is a parameter that points to the session handle or the instance ID string depending on the mode parameter (see mode below).
• mode is one of the following:

CTATTACH_SESSION - Attach to a FairCom DB API session whose session handle is pointed by the source parameter.

CTATTACH_CTREEID - Attach to a c-tree session whose instance ID string is pointed by the source parameter.

CTATTACH_CURRENT - Attach to the current c-tree instance. Contents of the source parameter is ignored, as the c-tree instance ID is obtained by calling the WCHCTREE() function.

• isTransactionActive should indicate if a transaction is active or not. Acceptable values are TRUE or FALSE. 

Returns

See Errors for a complete listing of valid c-tree error values.

EXAMPLE

/* logon to c-tree using ISAM function */
INTISAMX(10, 32, 32, 10, (USERPRF_NTKEY | USERPRF_CLRCHK),"admin","ADMIN","FAIRCOMS");
 
/* attach session to server handle */
if (ctdbAttachSession(hSession,NULL,CTATTACH_CURRENT,FALSE) != CTDBRET_OK)
    printf("ctdbAttachSession failed\n");
 
/*
... do something useful ...
*/
 
/* detach from session */
if (ctdbDetachSession(hSession) != CTDBRET_OK)
    printf("ctdbDetachSession failed\n");
 
/* perform an ISAM logout */
CLISAM();

See Also:
ctdbDetachSession()

ctdbCloseAll

Close all open tables associated with a given database.

Declaration

CTDBRET ctdbCloseAll(CTHANDLE Handle)

Description

ctdbCloseAll() closes all open tables associated with a given database. When the tables are closed, all resources associated with the table fields, indexes, and segments are freed, and the table handles are reset to all default initial parameters. The table handles are not deallocated, though. All locks associated with the tables are released. All of the record handles associated with the tables are reset (but not deallocated/freed). This means that all of the "Current Record" pointers in those record handles are also reset. All of the field handles, index handles, and segment handles associated with the tables are deallocated and their structures in memory are freed up. Closing the tables makes them "non-active". To close a specific table, use ctdbCloseTable().

• Handle [in] the database handle

Returns

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

Example

ctdbCloseAll(hDatabase);   
ctdbDisconnectAll(hSession);
ctdbLogout(hSession);
ctdbFreeTable(hTable);
ctdbFreeDatabase(hDatabase);
ctdbFreeSession(hSession);

See also:
ctdbCloseTable()

ctdbCloseTable

Close an open table.

Declaration

CTDBRET ctdbCloseTable(CTHANDLE Handle)

Description

ctdbCloseTable() closes an open table. When the table is closed, all resources associated with the table fields, indexes, and segments are freed, and the table handle is reset to all default initial parameters.

Notice that the table handle is not deallocated. All locks associated with the table are released. All of the record handles associated with the table are reset (but not deallocated/freed). This means that the "Current Record" pointers in those handles are also reset. All of the field handles, index handles, and segment handles associated with the table are deallocated and their structures in memory are freed up.

Closing the table makes it "non-active." To open a table, use ctdbOpenTable().

• Handle [in] the table handle

Returns

ctdbCloseTable returns CTDBRET_OK on success, or FairCom DB API error code on failure.

Example

eRet = ctdbCloseTable(hTable);
eRet = ctdbFreeTable(hTable);

See also:
ctdbAllocTable(), ctdbOpenTable()

ctdbConnect

Connect to a database.

Declaration

CTDBRET ctdbConnect(CTHANDLE Handle, pTEXT Name)

Description

ctdbConnect() connects a database handle to a database. Connecting to a database makes that database "active." Before using this function to connect to a particular database, you must first allocate the database handle and associate it with a session by calling the ctdbAllocDatabase() function. In other words, after allocating a database handle and associating it with a session, use this function to select which database in the session the database handle manipulates. The application must connect a database before doing any operation with that database's tables.

• Handle [in] the database handle, previously allocated with ctdbAllocDatabase().
• Name [in] the database name. This database must have been previously added to the session with ctdbAddDatabase().

To disconnect a database from session, use the functions ctdbDisconnect() or ctdbDisconnectAll().

Returns

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

Example

CTHANDLE hMyDatabase;
hMyDatabase = ctdbAllocDatabase(hMySession);
eRet = ctdbConnect(hMyDatabase, database_name);

See also
ctdbAllocDatabase(), ctdbDisconnect(), ctdbDisconnectAll(), ctdbCreateDatabase()

ctdbCreateDatabase

Create a new database.

Declaration

CTDBRET ctdbCreateDatabase(CTHANDLE Handle, cpTEXT Name, cpTEXT Path)

Description

ctdbCreateDatabase() creates a new database. This causes a database dictionary file (which maintains information about the tables in the database) to be created on disk, in the specified Path. If Path is left empty, the dictionary will be created by default in the Server directory (client/server applications) or in the execution directory (standalone applications). (Note that the LOCAL_DIRECTORY item in the server config file controls where in the server directory the file will appear.) The new database dictionary file will be named with the database name and the extension. FDD (FairCom Database Dictionary).

To create a Session, use ctdbCreateSession().

To create a table, use ctdbCreateTable(). The unique database identifier, UID, is associated with the database at the time of its creation. Generally, the UID is associated with the database when the database is added to the session dictionary using ctdbAddDatabase(), but since ctdbCreateDatabase() automatically adds the new database to the session dictionary, the UID is associated with the database at this time.

To create a database, first initiate a session with ctdbAllocSession() and then logon to the c-tree Server or c-tree instance using ctdbLogon(). Once created, the database is automatically added to the session specified by Handle.

• Handle [in] the session handle.
• Name [in] the database name.
• Path [in] the database path.

Returns

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

Example

CTHANDLE hDatabase;
hDatabase = ctdbAllocDatabase(hSession);
eRet = ctdbCreateDatabase(hSession, database_name, database_path);
eRet = ctdbConnect(hDatabase, database_name);

See also:
ctdbAllocDatabase(), ctdbAddDatabase(), ctdbCreateSession(), ctdbCreateTable(), ctdbLogon()

ctdbCreateSession

Create a new session table.

Declaration

CTDBRET ctdbCreateSession(CTHANDLE Handle, pTEXT dbengine, pTEXT userid, pTEXT password)

Description

ctdbCreateSession() creates a new session and session dictionary. The session dictionary file will be created by default in the Server directory (client/server) or in the execution directory (standalone). To change the directory to locate the session dictionary, use ctdbSetSessionPath() before calling ctdbCreateSession(). To create a database, use ctdbCreateDatabase(). To create a table, use ctdbCreateTable().

A session dictionary is required to perform any task with a database, or to logon to a c-tree Server or FairCom DB instance with ctdbLogon(). There must not be more than one session dictionary in a c-tree Server or FairCom DB environment.

• Handle [in] the session handle.
• dbengine [in] the string with the c-tree Server name or FairCom DB instance name. If dbengine is NULL, ctdbCreateSession() uses the string "FAIRCOMS" as the default server name or FairCom DB instance.
• userid [in] the string with the user name. If userid is NULL, ctdbCreateSession() uses the string "ADMIN" as the default user name.
• password [in] the string with the user password. If password is NULL, ctdbCreateSession() uses the string "ADMIN" as the default user password.

Returns

ctdbCreateSession() returns CTDBRET_OK on success, or FairCom DB API error code on failure. If the error code is 19, the session dictionary already exists.

Example

err = ctdbLogon(handle);
if (err == FNOP_ERR)  /* Session dictionary doesn't exist*/
     err = ctdbCreateSession(handle, "FAIRCOMS", "ADMIN", "ADMIN");

See also:
ctdbAllocSession(), ctdbCreateDatabase(), ctdbCreateTable(), ctdbLogon()

ctdbDeleteDatabase

Drop the database from session and delete database file and index.

Declaration

CTDBRET ctdbDeleteDatabase(CTHANDLE Handle, cpTEXT Name)

Description

ctdbDeleteDatabase() drops the database from the session dictionary and deletes the database file and index.

• Handle [in] - the handle of the session that contains the database to be dropped.
• Name [in] - the database name.

Use ctdbAddDatabase() to add a database to a session. Use ctdbDropDatabase() to drop the database from the session dictionary without deleting the database files.

Returns

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

Example

eRet = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");
eRet = ctdbDeleteDatabase(hSession, database_name);

See also:
ctdbAllocSession(), ctdbAddDatabase(), ctdbDropDatabase()

ctdbDetachSession

Detaches a FairCom DB API session handle from an existing c-tree connection.

Declaration

CTDBRET ctdbDECL ctdbDetachSession(CTHANDLE Handle);

Description

ctdbDetachSession() detaches a FairCom DB API session handle. The c-tree ISAM or low-level un-initialization is not called, but the session handle control structures are released and re- initialized. Handle is a session handle allocated by ctdbAllocSesison().

Return

See Errors for a complete listing of valid c-tree error values.

Example

/* logon to c-tree using ISAM function */
INTISAMX(10, 32, 32, 10, (USERPRF_NTKEY | USERPRF_CLRCHK));

/* attach session to server handle */
if (ctdbAttachSession(hSession, NO) != CTDBRET_OK)
    printf("ctdbAttachSession failed\n");

/*
... do something useful ...
*/

/* detach from session */
if (ctdbDetachSession(hSession) != CTDBRET_OK)
    printf("ctdbDetachSession failed\n");

/* perform an ISAM logout */
CLISAM();

See Also: 
ctdbAttachSession()

ctdbDisconnect

Disconnect a database.

Declaration

CTDBRET ctdbDisconnect(CTHANDLE Handle)

Description

ctdbDisconnect() disconnects a database from a database handle. Once a database has been disconnected from a database handle, that database is no longer considered "active."

• Handle [in] the database handle.

Use ctdbConnect() to connect a database to a database handle.

Use ctdbDisconnectAll() to disconnect all databases associated with a Session.

Returns

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

Example

ctdbDisconnect(hDatabase);
ctdbLogout(hSession);
ctdbFreeDatabase(hDatabase);
ctdbFreeSession(hSession);

See also:
ctdbAllocDatabase(), ctdbConnect(), ctdbDisconnectAll(), ctdbCreateDatabase()

ctdbDisconnectAll

Disconnect all databases.

Declaration

CTDBRET ctdbDisconnectAll(CTHANDLE Handle)

Description

ctdbDisconnectAll() disconnects all connected databases. Once a database has been disconnected from a database handle, that database is no longer considered "active."

• Handle [in] the session handle.

Use ctdbConnect() to connect a database to a session via a database handle.

Use ctdbDisconnect() to disconnect just one database.

A database created with ctdbCreateDatabase() is automatically connected to the present session.

Returns

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

Example

ctdbCloseAll(hDatabase);   
ctdbDisconnectAll(hSession);
ctdbLogout(hSession);
ctdbFreeTable(hTable);
ctdbFreeDatabase(hDatabase);
ctdbFreeSession(hSession);

See also:
ctdbAllocSession(), ctdbConnect(), ctdbDisconnect(), ctdbCreateDatabase()

ctdbDropDatabase

Drop a database from a session dictionary. The data and index files are not deleted from disk.

Declaration

CTDBRET ctdbDropDatabase(CTHANDLE Handle, cpTEXT Name)

Description

ctdbDropDatabase() drops the database from the session dictionary, but does not delete the database file and index file.

• Handle [in] - the handle of the session that contains the database to be dropped.
• Name [in] - the database name.

Use ctdbAddDatabase() to add a database to a session. Use ctdbDeleteDatabase() to drop the database from the session and delete the database file and index file.

Returns

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

Example

eRet = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");
eRet = ctdbDropDatabase(hSession, database_name);

See also: 
ctdbAllocSession(), ctdbAddDatabase(), ctdbDeleteDatabase()

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()

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()

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()

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()

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()

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);

Description

• Handle [IN] - Result Set handle

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()

ctdbGetActiveDatabaseUID

Retrieve the database UID, given the handle of an "active" (connected) database.

Declaration

CTDBRET ctdbGetActiveDatabaseUID(CTHANDLE Handle, pULONG puid)

Description

ctdbGetActiveDatabaseUID() retrieves the database Unique Identifier, UID, given the Database Handle. 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 ctdbGetDatabaseUID() to retrieve the database UID, given the database name. Use ctdbFindDatabaseByUID() to locate a database in a session by its unique identifier.

• Handle [in] the Database Handle.
• puid [out] the database UID.

Returns

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

See also
ctdbAllocDatabase(), ctdbFindDatabaseByUID(), ctdbGetDatabaseUID()

ctdbGetActiveResultSet

Declaration

CTHANDLE ctdbGetActiveResultSet(CTHANDLE Handle);

Description

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

• Handle [IN] - Record handle

Returns

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

See Errors for a complete listing of valid c-tree error values.

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

ctdbGetAttachMode

Declaration

CTATTACH_MODE ctdbDECL ctdbGetAttachMode(CTHANDLE Handle);

Description

Retrieve the current session attach mode. ctdbGetAttachMode() will not execute a c-tree instance switch.

• Handle is a session handle.

Returns

One of the following values is returned:

See Also
ctdbAttachSession(), ctdbDetachSession()

ctdbGetDatabaseCount

Retrieve the number of databases in the session dictionary.

Declaration

NINT ctdbGetDatabaseCount(CTHANDLE Handle)

Description

ctdbGetDatabaseCount() returns the number of databases in the session dictionary.

• Handle [in] the session handle.

Returns

ctdbGetDatabaseCount() returns the number of databases in the session dictionary, or -1 on error.

See also
ctdbGetTableCount()

ctdbGetDatabaseHandle

Return the database handle.

Declaration

CTHANDLE ctdbGetDatabaseHandle(CTHANDLE Handle)

Description

ctdbGetDatabaseHandle() returns the database handle. To allocate a database handle, use ctdbAllocDatabase().

• Handle [in] may be a table handle, a record handle, a field handle, an index handle, or a segment handle.

Returns

ctdbGetDatabaseHandle() returns the database handle or NULL on failure.

Example

db_name = ctdbGetDatabaseName(ctdbGetDatabaseHandle(hTable));

See also
ctdbAllocDatabase(), ctdbGetSessionHandle(), ctdbGetTableHandle()

ctdbGetDatabaseName

Return the database name.

Declaration

pTEXT ctdbGetDatabaseName(CTHANDLE Handle)

Description

ctdbGetDatabaseName() returns the database name.

• Handle [in] the Database Handle.

Returns

ctdbGetDatabaseName() returns the database name, or NULL on error.

Example

db_name = ctdbGetDatabaseName(ctdbGetDatabaseHandle(hTable));

See also
ctdbAllocDatabase(), ctdbGetDatabasePath()

ctdbGetDatabasePath

Return the database path.

Declaration

pTEXT ctdbGetDatabasePath(CTHANDLE Handle)

Description

ctdbGetDatabasePath() returns the database path. Note that the database path is set with ctdbCreateDatabase() as part of the database creation process. If no path was specified when the database was created (so the database was created in the default location), then ctdbGetDatabasePath() is likely to return an empty string.

• Handle [in] the Database Handle.

Records

ctdbGetDatabasePath() returns the database path, or NULL if no database path is available.

Example

eRet=ctdbConnect(hDatabase, "myDatabase", "");
db_path=ctdbGetDatabasePath(hDatabase);

See also
ctdbAllocDatabase(), ctdbGetDatabaseName()

ctdbGetDatabaseUID

Return the database UID, given a session handle and database name.

Declaration

CTDBRET ctdbGetDatabaseUID(CTHANDLE Handle, pTEXT Name, pULONG puid)

Description

ctdbGetDatabaseUID() retrieves the database unique identifier, UID, given the database name. 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 ctdbGetActiveDatabaseUID() to retrieve the database UID, given the Database Handle. Use ctdbFindDatabaseByUID() to locate a database in a session by its unique identifier.

• Handle [in] - the session handle.
• Name [in] - the database name.
• pUid [out] - the database unique identifier.

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

See also
ctdbAllocSession(), ctdbFindDatabaseByUID(), ctdbGetActiveDatabaseUID()

ctdbGetHandleType

See Data Structures.

ctdbGetLastPartition

Retrieves the last partition number of the table.

Declaration

LONG ctdbGetLastPartition(CTHANDLE Handle)

Description

ctdbGetLastPartition() returns the last raw partition number for the file if partitions exist. If -1 is returned, call ctdbGetError() to retrieve the ISAM error code. If this value is zero, the file has no active partitions. If uerr_cod is non-zero, an error occurred. For example, if the specified file number does not correspond to a partition host file, ctdbGetLastPartition() returns -1 and ctdbGetError() returns PHST_ERR. ctdbGetError() will return CTDBRET_NOTACTIVE, or CTDBRET_NOTTABLE, if an invalid table handle is passed in.

Returns
ctdbGetLastPartition() returns the last raw partition number or -1 if not found.

See also
ctdbGetFirstPartition()

ctdbGetLockMode

Retrieve the current session-wide lock mode.

Declaration

CTLOCK_MODE ctdbGetLockMode(CTHANDLE Handle)

Description

ctdbGetLockMode() retrieves the current session-wide lock mode. Valid lock modes are presented in Session-Wide Lock Modes. Note that this function does not give the lock status of an individual record. Instead, it tells you if session-wide record locking is turned on or off, suspended or not, etc., so you know if a record will be automatically locked the next time you read it from disk.

• Handle [in] the Session or any other FairCom DB API .NET Handle.

Returns
ctdbGetLockMode() returns the session-wide lock mode.

See also
ctdbLock(), ctdbIsLockActive(), Locking, Session-Wide Lock Modes

ctdbGetOperationState

Declaration

CTOPS_MODE ctdbDECL ctdbGetOperationState(CTHANDLE Handle);

Description

Retrieve the c-tree operation modes for special performance-related functionality and test operational states for critical events.

• Handle is a session handle.

Returns

ctdbGetOperationState() returns a combination of the following CTOPS_MODE codes on success:

See Also
ctdbGetOperationState() ctdbGetAutoCommit() ctdbSetAutoCommit()

ctdbGetTableKSeg

Retrieves the current table-wide extended key segment definition.

DECLARATION

CTDBRET ctdbGetTableKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbGetTableKSeg() retrieves the current table-wide extended key segment definition. Handle must be a FairCom DB API table handle and pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

Note: The kseg_type member of the extended key segment definition structure must be set on input to the type of segment to be retrieved.

RETURN

See Errors for a complete listing of valid c-tree error values.

EXAMPLE

ctKSEGDEF kseg;

if ((eRet = ctdbGetTableKSeg(hTable, &kseg)) != CTDBRET_OK)
    printf("ctdbGetTableKSeg failed with error %d\n", eRet);

SEE ALSO
ctdbSetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(), ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

ctdbIsSessionExclusive

Retrieves the status of the session exclusive flag.

DECLARATION

CTBOOL ctdbIsSessionExclusive(CTHANDLE Handle);

DESCRIPTION

ctdbIsSessionExclusive() retrieves the status of the session exclusive flag.

• Handle is a session handle.

RETURN

See Errors for a complete listing of valid c-tree error values.

EXAMPLE

/* verify an exclusive logon */
CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTDB);
 
if (hSession)
{
	ctdbSetSessionExclusive(hSession, YES);
    if (ctdbLogon(hSession, "FAIRCOM", "ADMIN", "ADMIN") != CTDBRET_OK)
        printf("ctdbLogon failed\n");
}
if (ctdbIsSessionExclusive(hSession))
    printf("Session is exclusive\n");
else
    printf("Session is shared\n");
ctdbFreeSession(hSession);

SEE ALSO
ctdbSetSessionExclusive(), ctdbSetDatabaseExclusive(), ctdbIsDatabaseExclusive()

ctdbJumpToRecord

See Data Manipulation.

ctdbSetSessionExclusive

Sets or clears the session exclusive flag.

DECLARATION

CTDBRET ctdbSetSessionExclusive(CTHANDLE Handle, CTBOOL flag);

DESCRIPTION

ctdbSetSessionExclusive() sets or clears the session exclusive flag. If a session exclusive flag is set, only one CTSESSION_CTDB or CTSESSION_SQL session will be allowed. Set the session exclusive flag after allocating the session handle, but before performing a logon. Setting the session exclusive flag after a session logon is performed will not have any effect during the current session. Handle is a session handle. If flag is YES, this will set the exclusive flag, while NO will clear the exclusive flag.

RETURN

See Errors for a complete listing of valid c-tree error values.

EXAMPLE

/* perform an exclusive logon */
CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTDB);
 
if (hSession)
{
	ctdbSetSessionExclusive(hSession, YES);
    if (ctdbLogon(hSession, "FAIRCOM", "ADMIN", "ADMIN") != CTDBRET_OK)
        printf("ctdbLogon failed\n");
}
ctdbFreeSession(hSession);

SEE ALSO
ctdbIsSessionExclusive(), ctdbSetDatabaseExclusive(), ctdbIsDatabaseExclusives()

ctdbSwitchContext

Force an ISAM context switch.

Declaration

CTDBRET ctdbSwitchContext(CTHANDLE Handle)

Description

Force a switch to the FairCom DB ISAM context indicated by the record handle. Each record handle has its own c-tree ISAM context id.

When most FairCom DB API record handling functions are called, they automatically perform a c-tree ISAM context switch. ctdbSwitchContext() may be useful before calling specific c-tree ISAM or low level calls to make sure the correct ISAM context is active before making those calls.

Handle is a record handle. The handle must be a record handle. No other type of FairCom DB API handle is acceptable.

Returns

See Errors for a complete listing of valid c-tree error values.

Example

/* force a context switch */
if (ctdbSwitchContext(hRecord) != CTDBRET_OK)
    printf("ctdbSwitchContext failed\n");
/* call ResetRecord */
if (ResetRecord((COUNT)ctdbGetDatno(hRecord), SWTCURI))
    printf("ResetRecord failed\n");

See also
ctdbSwitchInstance(), ctdbGetDatno(), ctdbGetIdxno(), ctdbGetIdxnoByName(), ctdbGetIdxnoByNumber()

ctdbSwitchInstance

Force a c-tree instance switch.

Declaration

CTDBRET ctdbSwitchInstance(CTHANDLE Handle)

Description

Force a switch to the c-tree instance indicated by the Session handle. Each session handle has its unique c-tree instance ID.

When most FairCom DB API C functions are called, they automatically perform a c-tree instance switch. ctdbSwitchInstance() may be useful before calling specific c-tree ISAM or low level calls to make sure the correct instance is active before making those calls.

Handle is a Session handle. You can pass any FairCom DB API handle to ctdbSwitchInstance().

Return

See Errors for a complete listing of valid c-tree error values.

Example

/* declare and allocate the remote and local session handles */
CTHANDLE hRemote = ctdbAllocSession(CTSESSION_CTREE);
CTHANDLE hLocal = ctdbAllocSession(CTSESSION_CTREE);

/* logon to c-tree server using the remote session handle */
if (ctdbLogon(hRemove, "FAIRCOMS", "ADMIN", "ADMIN") !=  CTDBRET_OK)
    printf("Remote ctdbLogon failed\n");
/* logon to local session using the local session handle */
if (ctdbLogon(hLocal, "local", "ADMIN", "ADMIN) != CTDBRET_OK)
    printf("Local ctdbLogon failed\n");
/* perform a c-tree instance switch and call CtreeUserOperation function */
if (ctdbSwitchInstance(hRemote) != CTDBRET_OK)
    printf("ctdbSwitchInstance failed\n");
CtreeUserOperation("!mkdir faircom", buffer, sizeof(buffer);

See also
ctdbSwitchContext(), ctdbGetDatno(), ctdbGetIdxno(), ctdbGetIdxnoByName(), ctdbGetIdxnoByNumber()