C API Functions L

ctdbLastRecord

Get the last record on a table.

Declaration

CTDBRET ctdbLastRecord(CTHANDLE Handle)

Description

ctdbLastRecord() retrieves the last record on a table and copies the record data from disk into the specified record handle’s record buffer, and sets the current record to that last record.

  • Handle [in] the record handle.

If sets are enabled by ctdbRecordSetOn(), ctdbLastRecord() will retrieve the last record in the set. Use ctdbFirstRecord() to retrieve the first record on a table, ctdbNextRecord() to retrieve the next record on a table, and ctdbPrevRecord() to retrieve the previous 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

ctdbLastRecord() returns CTDBRET_OK on success, or INOT_ERR (101) if the table is empty, or a FairCom DB API error on failure.

See also

ctdbAllocRecord(), ctdbFirstRecord(), ctdbNextRecord(), ctdbPrevRecord(), ctdbFindRecord(), ctdbRecordSetOn()

ctdbLock

Turn the automatic session-wide record locking mechanism on or off.

Declaration

CTDBRET ctdbLock(CTHANDLE Handle, CTLOCK_MODE mode)

Description

ctdbLock adjusts the current session-wide record lock mode used by the lock manager. Session-wide record locking is one of the two methods provided by the FairCom DB API API to lock records. This method (session-wide locking) is the recommended method of locking records, because this method automatically locks the record as it is read from the table file, as opposed to manually locking the record AFTER it has been read, which leaves a window of opportunity for another thread to modify or delete the record after you read it and before you locked it. This function is used to turn the session-wide locking system on and off, suspend and un-suspend it, etc. This function is NOT used to manipulate the lock status of individual records.

After a call to ctdbLock with a mode other than CTLOCK_FREE or CTLOCK_SUSPEND, all operations involving file reads will be automatically locked. For example, all records read (ctdbFirstRecord, ctdbNextRecord, ctdbLastRecord, ctdbFindRecord, etc.) after a call to ctdbLock, will be automatically locked as they are read in from the table file on disk.

To manually lock only the current record using the other record locking mechanism provided by the FairCom DB API API, use ctdbLockRecord.

Note: Calling ctdbLock() does not actually lock any files or records. Instead, it sets an internal flag to indicate that all new record reads will automatically lock the records with the given lock mode.

  • Handle [in] the Session or other internal Handle.
  • mode [in] one of the valid FairCom DB API session-wide lock modes. The valid lock modes are listed in Session-Wide Lock Modes.

A READ lock (also called a "shared" lock) on a record allows an unlimited number of READ locks on that record, but prevents WRITE locks. A WRITE lock (also called an "exclusive" lock) prevents any other locks on that record.

Note that if the specified lock (READ or WRITE) cannot be obtained (because another client application or thread already has a conflicting lock on that record, for example), then the record read will either block (the "_BLOCK" locking modes), or fail with an error (the locking modes that do not end with the word "_BLOCK").

To turn off session-wide record locking and release the locks on some records, call ctdbUnlock(), or call ctdbLock() with the mode set to CTLOCK_FREE. There are various subtlties about how this works and which locks get released and which do not. For the details, please see the writeup for the ctdbUnlock() function. For more details about how session-wide locking is used, see the section titled Locking.

Note: Mixing ctdbLockRecord() and ctdbLock() may result in DLOK_ERR (42) returns when an automatic lock is attempted on a manually locked record, or vice versa. DLOK_ERR (42) simply means a lock could not be obtained. Check sysiocod for the system-level error to determine why the record could not be locked. In the example above, a locked record cannot be re-locked.

Returns

ctdbLock() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure. Related common errors to are:

  • CTDBRET_INVLOCKMODE (4055): Invalid lock mode.
  • CTDBRET_NOTSESSION (4003): Invalid handle - use a Session handle.

See Also

ctdbCommit(), ctdbAbort(), ctdbIsLockActive(), ctdbUnlock(), ctdbGetLockMode(), ctdbLockRecord(), ctdbSetKeepLock(), ctdbUnlockTable(), Session-Wide Lock Modes, Locking

ctdbLockRecord

Lock the current record using the manual record locking system.

Declaration

CTDBRET ctdbLockRecord(CTHANDLE Handle, CTLOCK_MODE Mode)

Description

ctdbLockRecord() manually locks the current record with the specified record lock mode.

This function can also be used to demote a WRITE lock currently held by a record (as long as that record has not been modified) by specifying one of the READ lock modes.

This function can also be used to release a lock currently held by a record by specifying the CTLOCK_FREE lock mode. Doing this is equivalent to calling ctdbUnlockRecord(), and since certain exceptions apply to record unlocking, the documentation for ctdbUnlockRecord() should be consulted. A list of the available record lock modes is in Record Lock Modes.

When using ctdbLockRecord() to demote or release a record lock, it does not matter if the record lock was originally acquired manually (by calling ctdbLockRecord()) or acquired automatically (via the session-wide record locking mechanism).

  • Handle [in] the record handle.

Mode [in] the new locking mode for the record.

A READ lock (also called a "shared" lock) on a record allows an unlimited number of READ locks on that record, but prevents WRITE locks. A WRITE lock (also called an "exclusive" lock) prevents any other locks on that record.

Note that if the specified lock (READ or WRITE) cannot be obtained (because another client application or thread already has a conflicting lock on that record, for example), then the record read will either block (the "_BLOCK" locking modes), or fail with an error (the locking modes that do not end with the word "_BLOCK").

Usage Note:

Although the current record is locked after calling ctdbLockRecord(), the buffered record data could have been modified by another user before the ctdbLockRecord() call was made. Call ctdbReadRecord() to re-read the locked record to avoid this potential for stale data.

In most cases it is more efficient to use the other record locking mechanism provided by the FairCom DB API API (session-wide record locking), which is not subject to this problem. With session-wide record locking, you first call ctdbLock() to turn on session-wide record locking, and then, each time you make a call that reads, writes, or deletes a record, the record is automatically locked before it is read from disk / written to disk. See the ctdbLock() function for more details.

Note: Manual record locking should NOT be used in situations where a given table is open / active more than once at the same time, in the same session, using two different table handles, because unexpected locking / unlocking behavior can result. For more details, in client/server situations, see FairCom Server enhanced locking control for files opened multiple times in the same connection. If you need to have the same table open more than once at the same time, please use session-wide record locking (see ctdbLock()).

Returns

ctdbLockRecord() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure. If there is no current record, ctdbLockRecord() returns CTDBRET_NOTACTIVE (4012).

See also

ctdbUnlockRecord(), ctdbLock(), ctdbBegin(), ctdbSetKeepLock(), ctdbUnlockTable(), Record Lock Modes, Locking, Record Lock Modes

ctdbLogon

Log on to FairCom Server or FairCom DB instance session.

Declaration

CTDBRET ctdbLogon(CTHANDLE Handle, pTEXT dbengine, pTEXT userid,

pTEXT password)

Description

ctdbLogon() logs on to the c-tree Server or FairCom DB instance. Before any database operation can take place, initiate a session with ctdbAllocSession() and then logon to the c-tree Server or c-tree Plus instance using ctdbLogon() before calling ctdbAllocDatabase().

Before logon to the c-tree Server or a FairCom DB instance, it is necessary to have a session dictionary. To create a session dictionary, use the function ctdbCreateSession().

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

To logout from the c-tree Server or FairCom DB instance, use the ctdbLogout() function.

Returns

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

Example


CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTDBRET err;

err = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

err = ctdbCreateDatabase(hSession, "MyDatabase", "");

err = ctdbLogout(hSession);

ctdbFreeSession(hSession);


See also

ctdbLogout(), ctdbAllocDatabase(), ctdbCreateSession(), ctdbIsActiveSession()

ctdbLogout

Logout from a FairCom Server session or from a FairCom DB instance.

Declaration

CTDBRET ctdbLogout(CTHANDLE Handle)

Description

ctdbLogout() logs out from the c-tree Server or FairCom DB instance.

  • Handle [in] the session handle.

Returns

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

Example


CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTDBRET err;

err = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

err = ctdbCreateDatabase(hSession, "MyDatabase", "");

err = ctdbLogout(hSession);

ctdbFreeSession(hSession);


See also

ctdbLogon(), ctdbAllocSession()

 

ctdbLongToBigInt

Convert a LONG value to a big integer.

Declaration

CTDBRET ctdbLongToBigInt(LONG value, pCTBIGINT pBigInt)

Description

ctdbLongToBigInt() converts a LONG value to a big integer value. A big integer is an 8 bytes integer value. Use ctdbBigIntToLong() to convert from a big integer to a LONG.

  • value [in] the CTSIGNED LONG value (4 bytes signed integer).
  • pBigInt [out] the big integer value (8 bytes signed integer).

Returns

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

The possible error associated with ctdbLongToBigInt() is:

  • CTDBRET_NULARG (4007): Null argument not valid in pStr

See also

ctdbBigIntToLong()

 

ctdbLongToCurrency

Convert a LONG value to a CTCURRENCY value.

Declaration

CTDBRET ctdbLongToCurrency(CTSIGNED value, pCTCURRENCY pCurrency)

Description

ctdbLongToCurrency() converts a CTSIGNED (4 bytes signed integer) value to a CTCURRENCY (8 bytes signed integer) value. Use ctdbCurrencyToLong() to convert from a CTCURRENCY value to a LONG value.

  • value [in] the CTSIGNED value (4 bytes integer).
  • pCurrency [out] the CTCURRENCY value (8 bytes integer).

Returns

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

The possible error associated with ctdbLongToCurrency() is:

  • CTDBRET_NULARG (4007): Null argument not valid in pStr

See also

ctdbCurrencyToLong()

 

ctdbLongToMoney

Convert a LONG value to a CTMONEY.

Declaration

CTDBRET ctdbLongToMoney(CTSIGNED value, pCTMONEY pMoney)

Description

ctdbLongToMoney() converts a LONG value to a CTMONEY value. The long value is multiplied by 100 before the conversion. Use ctdbMoneyToLong() to convert from a LONG to CTMONEY.

  • value [in] the CTSIGNED LONG value.
  • pMoney [out] the CTMONEY value.

Returns

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

The possible error associated with ctdbLongToMoney() is:

  • CTDBRET_NULARG (4007): Null argument not valid in pStr

See also

ctdbMoneyToLong()

 

ctdbLongToNumber

Convert a LONG to a CTNUMBER value.

Declaration

CTDBRET ctdbLongToNumber(LONG value, pCTNUMBER pNumber)

Description

ctdbLongToNumber() converts a LONG to a CTNUMBER value. Use ctdbNumberToLong() to convert from CTNUMBER to a LONG.

  • value [in] the LONG value.
  • pNumber [out] pointer to CTNUMBER.

Returns

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

The possible error associated with ctdbLongToNumber() is:

  • CTDBRET_NULARG (4007): Null argument not valid in pValue

See also

ctdbNumberToLong()

interface library

Was this article helpful?

Give feedback about this article

Related Articles