ctdbCheckFTIBackgroundLoad

Check the status of the background index loader for the Full-Text Index (FTI).

See ctdbCheckFTIBackgroundLoad

ctdbCheckIndexBackgroundLoad

Check the status of the background index loader for the specified table.

Declaration

CTDBRET ctdbDECL ctdbCheckIndexBackgroundLoad(CTHANDLE Handle, pBGLDINF status)

Description

This function can be used to monitor the status of the index loading on tables. See CTINDEX_BCKLOAD.

• Handle [IN] - Table handle.
• status [OUT] - status information.

Background key loading can improve performance when adding new indexes. A new background loading mode can be OR-d in with an existing key mode from a ctdbAddIndex (ctdbAddIndex, ctdbAddIndex)() call indicating initial index loading must be done in the background.

Once ctdbAddIndex() is called, ctdbAlterTable() initiates the changes to the file and begins the load once the new index is successfully created.

Check the status of index loading with the new ctdbCheckIndexBackgroundLoad() (ctdbCheckIndexBackgroundLoad, ctdbCheckIndexBackgroundLoad) API, useful for monitoring index loading on tables.

Returns

Returns CTDBRET_OK on success.

ctdbCheckIndexBackgroundLoad

Check the status of the background index loader for the specified table.

Declaration

CTDBRET ctdbDECL ctdbCheckIndexBackgroundLoad(CTHANDLE Handle, pBGLDINF status)

Description

This function can be used to monitor the status of the index loading on tables. See CTINDEX_BCKLOAD.

• Handle [IN] - Table handle.
• status [OUT] - status information.

Background key loading can improve performance when adding new indexes. A new background loading mode can be OR-d in with an existing key mode from a ctdbAddIndex (ctdbAddIndex, ctdbAddIndex)() call indicating initial index loading must be done in the background.

Once ctdbAddIndex() is called, ctdbAlterTable() initiates the changes to the file and begins the load once the new index is successfully created.

Check the status of index loading with the new ctdbCheckIndexBackgroundLoad() (ctdbCheckIndexBackgroundLoad, ctdbCheckIndexBackgroundLoad) API, useful for monitoring index loading on tables.

Returns

Returns CTDBRET_OK on success.

ctdbClearAllCallback

Clears all callbacks associated with any FairCom DB API handle.

DECLARATION

CTDBRET ctdbClearAllCallback(CTHANDLE Handle);

DESCRIPTION

ctdbClearAllCallback() clears all callbacks associated with a handle. Handle can be a session, database, table or record handle.

RETURN

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* allocate a record handle */
CTHANDLE hRecord = ctdbAllocRecord(hTable);

/* make sure there are no callbacks */
if (ctdbClearAllCallback(hRecord))
    printf("ctdbClearAllCallback failed\n");

SEE ALSO

ctdbClearCallback(), ctdbGetCallback(), ctdbSetCallback()

ctdbClearAllFieldDefaultValue

Clear the default value associated with all fields in a table.

DECLARATION

CTDBRET ctdbClearAllFieldDefaultValue(CTHANDLE Handle);

DESCRIPTION

ctdbClearAllFieldDefaultValue() clears the default value associated with all fields in a table. The default date and time types for each field are also reset to the default values of CTDATE_MDCY and CTIME_HMS respectively. Handle must be a table handle.

RETURN

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* clear all default field values *.
if (ctdbClearAllFieldDefaultValue(hTable) != CTDBRET_OK)
    printf("ctdbClearAllFieldDefaultValue failed\n");

SEE ALSO

ctdbSetFieldDefaultValue(), ctdbGetFieldDefaultValue(), ctdbClearFieldDefaultValue(), ctdbIsFieldDefaultValueSet(), ctdbSetFieldDefaultDateTimeType(), ctdbGetFieldDefaultDateType(), ctdbGetFieldDefaultTimeType()

ctdbClearCallback

Clears a particular callback associated with a FairCom DB API handle.

DECLARATION

CTDBRET ctdbClearCallback(CTHANDLE Handle, CTDB_CALLBACK_TYPE CallBackType);

DESCRIPTION

You can clear a particular callback associated with a handle. Handle can be a session, database, table or record handle. CallBackType is one of the valid callback types.

RETURN

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* allocate a record handle */
CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

/* make sure there are no CTDB_ON_TABLE_OPEN callbacks */
if (ctdbClearCallback(hSession, CTDB_ON_TABLE_OPEN))
    printf("ctdbClearCallback failed\n");

SEE ALSO

ctdbClearAllCallback(), ctdbGetCallback(), ctdbSetCallback()

ctdbClearError

Clear the error code.

Declaration

void ctdbClearError(CTHANDLE Handle)

Description

ctdbClearError() clears the error code set by ctdbSetError().

• Handle [in] any handle inside the session (session handle, database handle, table handle, record handle, index handle, field handle or segment handle).

Returns

None.

See also

ctdbSetError(), ctdbGetError()

ctdbClearField

Clear the field data and set the field's NULL flag.

Declaration

CTDBRET ctdbClearField(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbClearField() clears the field data and sets the field's NULL flag.

• Handle [in] the record handle.
• FieldNbr [in] the field number.

Note this function only edits a single field in a single record/row.

Additionally, ctdbClearField() also sets the NULL flag. To clear the NULL flag, write a value to the field in its relevant record, even if it is a zero-length string.

Returns

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

See also

ctdbClearRecord, ctdbIsNullField

To read/write the "NOT NULL" attribute of a column in the SQL layer, see ctdbGetFieldNullFlag and ctdbSetFieldNullFlag

ctdbClearFieldDefaultValue

Clears the default value associated with a FairCom DB API field.

DECLARATION

CTDBRET ctdbClearFieldDefaultValue(CTHANDLE Handle)

DESCRIPTION

Clears the default value associated with a field. The default date and time types are also reset to their default values of CTDATE_MDCY and CTTIME_HMS respectively. Handle must be a field handle.

RETURN

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* clear the default field value */
hField = ctdbGetField(hTable, 5);
if (hField)
    if (ctdbClearField(hField) != CTDBRET_OK)
        printf("ctdbClearField failed\n");

SEE ALSO

ctdbSetFieldDefaultValue(), ctdbGetFieldDefaultValue(), ctdbIsFieldDefaultValueSet(),
ctdbClearAllFieldDefaultValue(), ctdbSetFieldDefaultDateTimeType(),
ctdbGetFieldDefaultDateType(), ctdbGetFieldDefaultTimeType()

ctdbClearRecord

Clear the record buffer.

Declaration

CTDBRET ctdbClearRecord(CTHANDLE Handle)

Description

ctdbClearRecord() clears the record buffer that is part of the record handle. Before clearing a record, the record handle should be active (associated with a table). After the call to ctdbClearRecord(), functions that depend on the "current record" (like ctdbNextRecord() and ctdbPrevRecord()) will return an error (CTDBRET_NOTACTIVE), because the specified record handle is no longer associated with a particular record in the table. This function also resets the padding, zeroes out all of the number fields, and sets all of the bits of the NULL flag, meaning "all of the fields in this record handle are NULL (not set to anything yet)."

Note that this function does NOT break the record handle’s association with its table. After calling this function, the record handle is still associated with the table that was specified when the handle was allocated by calling ctdbAllocRecord().

It is very important to clear the record buffer BEFORE using this record handle to add a new record to a table. If the user tries to add a new record, and the buffer is not cleared by calling this function first, the new record will replace (rewrite) the active record (whatever record the specified record handle is currently associated with), or return an error ICUR_ERR (100) in the event the record handle has been instantiated, but not cleared.

• Handle [in] the record handle.

Returns

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

See also

ctdbAllocRecord(), ctdbResetRecord()

ctdbClearSavePoint

Clears the last transaction save point.

Declaration

NINT ctdbClearSavePoint(CTHANDLE Handle)

Description

• Handle [in] the session handle.

Returns

ctdbClearSavePoint() returns CTDBRET_OK on success and a c-tree error code to indicate failure. uerr_cod contains the c-tree error code.

ctdbClearSavePoint() cannot clear a special save point returns a SPCL_ERR (753) error in this case.

See also

ctdbAbort(), ctdbBegin(), ctdbCommit(), ctdbRestoreSavePoint(), ctdbSetSingleSavePoint()

ctdbCommit

Commit a transaction.

Declaration

CTDBRET ctdbCommit(CTHANDLE Handle)

• Handle [in] the session handle. Any handle will work, but you save a tiny bit of CPU by using the session handle.

Description

ctdbCommit() commits a transaction initiated with ctdbBegin() and releases all locks — both session-wide record locks (automatically acquired as a result of calling ctdbLock() and then reading a record from a table file), and manually-locked records (acquired by calling ctdbLockRecord() on an individual record).

Locks acquired both inside and outside the transaction are released. This function also disables (turns off) session-wide record locking. Note that these lock-related behaviors can be changed from the default by calling ctdbSetKeepLock().

Returns

ctdbCommit() returns CTDBRET_OK if successful, or the c-tree error code on failure. Common causes of commit errors are calling ctdbCommit() twice in a row, or calling ctdbCommit() without calling ctdbBegin() first to start a transaction. Note that if ctdbCommit() fails (and there is an open transaction), then the transaction can be rolled back to a previous set point, if any were saved, by calling ctdbRestoreSavePoint(); or the transaction can be aborted (rolled back to the beginning) by calling ctdbAbort(). Extreme circumstances, like the failure of computer hardware, can cause calls to ctdbCommit() and ctdbAbort() to fail. In situations like this, a common approach is to log an error and exit.

Example

ctdbBegin(pSession);

if (ctdbCreateTable(tHandle1,"table1",CTCREATE_NORMAL) == CTDBRET_OK)

       ctdbCommit(pSession);

else

       ctdbAbort(pSession);

See also

ctdbAbort(), ctdbBegin(), ctdbClearSavePoint(), ctdbRestoreSavePoint(), ctdbSetSingleSavePoint()

ctdbCloneTable

Creates a new clone based on an existing table.

Declaration

CTDBRET ctdbCloneTable( CTHANDLE tarTableHandle, pTEXT tarTableName, CTHANDLE srcTableHandle )

Description

ctdbCloneTable() creates a new table with the attributes from an existing source table. This does NOT create a duplicate table -- records are not copied.

Note: This function is only for a CTSESSION_CTREE session or for cloning tables from/into different databases.

• tarTableHandle [in] - The new table handle
• tarTableName [in] - The new table name
• srcTableHandle [out] - The source table handle

Returns

ctdbCloneTable() returns CTDBRET_OK on success, or FairCom DB API error code on failure. Typical ctdbCreateTable() errors are possible.

Example

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);
 

CTHANDLE custmast = ctdbAllocTable( hSession );

CTHANDLE custmast_clone = ctdbAllocTable( hSession );

ctdbOpenTable( custmast, "custmast", CTOPEN_NORMAL );

ctdbCloneTable( custmast_clone, "custmast_clone", custmast );

See also

ctdbCreateTable()

ctdbCreateTable

Create a new table.

Declaration

CTDBRET ctdbCreateTable(CTHANDLE Handle, pTEXT TableName,

                        CTCREATE_MODE CreateMode)

Description

ctdbCreateTable() creates a new table.

To give the new table a password, call ctdbSetTablePassword() with Handle before calling this function.

To create a session, use ctdbCreateSession().

To create a database, use ctdbCreateDatabase().

To retrieve the table create mode, use ctdbGetTableCreateMode().

To open an existing table, use ctdbOpenTable().

The default directory for the table creation is the server directory (client/server applications) or the execution directory (standalone applications). To change the directory, call ctdbSetTablePath() to set the new directory before creating the table. In order to create the table, its fields, indexes and segments must be created first using, for instance, ctdbAddField(), ctdbAddIndex(), ctdbAddSegment().

Note that the create table process does not leave the table open after the table is created. The new table must be explicitly opened before it is used; see ctdbOpenTable().

Care should be exercised when selecting the table create mode. For example, if you wish to use transaction processing (the ctdbBegin(), ctdbCommit(), and ctdbAbort() functions) to ensure atomicity, then it is important to create the table using the CTCREATE_PREIMG or the CTCREATE_TRNLOG mode, and not the CTCREATE_NORMAL mode. See the Transactions section in Data Integrity for more details.

• Handle [in] the table handle.
• TableName [in] the table name.
• CreateMode [in] the table create mode. The valid values for the table create mode are listed in FairCom DB API Table Create Modes.

Mirrored Files

The FairCom mirroring feature makes it possible to store important files on different drive volumes, partitions or physical drives. If the primary storage location is damaged or lost, the mirroring logic will automatically detect the situation and switch to the secondary or "mirrored" storage area.

The mirrored file is easily specified by appending a vertical bar ( | ) after the table name followed by the table mirror name. For example, to mirror a table named "customer" to "mirror", specify the table name as "customer|mirror". If no path is specified for the mirrored table, both tables will be located in the same directory. If the primary table and the mirrored table are to be located in different directories, then the path names must be specified the same way as the table names: "primary-path|mirrored-path".To create a mirrored table, use the ctdbCreateTable() function passing as the table name a proper mirrored naming convention:

if (ctdbCreateTable(hTable, "customer|mirror", CTCREATE_TRNLOG) )

    printf("Create table failed\n");

If you need to specify different locations for the mirrored tables, use ctdbSetTablePath() to specify the mirrored paths:

if (ctdbSetTablePath(hTable, "primary_path|mirrored_path"))

   printf("ctdbSetTablePath failed\n");

Under c-tree Server operation, all mirroring can be suspended by adding the following entry to the server configuration file (ctsrvr.cfg):

MIRRORS NO

This may be useful when the mirroring hardware is not operational and the use of the primary data is necessary. By default, read and write operations on mirrored tables will continue without returning an error if either one of the files fail, but the other succeeds. When this happens, the failed file is shut down and subsequent I/O operations continue only with the remaining "good" file. If mirroring is used in the client/server model, the SystemMonitor() function receives an event when one of the files succeed and the other fails.

Note: The FairCom DB API alter table function will not operate on mirrored tables. If ctdbAlterTable() is called for a mirrored table, nothing is done and it returns error CTDBRET_NOTSUPPORTED.

Mirroring is supplied for c-tree Server and single-user operations. It applies to all c-tree file modes including transaction processing. Once a table is created and opened with mirroring, all subsequent table opens must be mirrored (ctdbOpenTable() called with two table names separated by the vertical bar ( | )), except when the table is opened in exclusive mode (ctdbOpenTable()’s third parameter).

Returns

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

Example

pMyTable = ctdbAllocTable(pMySession);

pMyField = ctdbAddField(pMyTable, "Name", CT_FSTRING,32);

pMyIndex = ctdbAddIndex(pMyTable, "iName", CTINDEX_FIXED,NO,NO);

pMyIseg = ctdbAddSegment(pMyIndex, pMyField, 2);

RetVal = ctdbCreateTable(pMyTable,"Table1",CTCREATE_NORMAL);

See also

ctdbCreateSession(), ctdbCreateSession(), ctdbCreateDatabase(), ctdbGetTableCreateMode(), ctdbOpenTable(), ctdbSetTablePath(), ctdbAddField(), ctdbAddIndex(), ctdbAddSegment(), ctdbSetIndexFilename(), ctdbGetIndexFileName()

ctdbDeleteTable

Drop a table from a database and delete its data and index files from disk.

Declaration

CTDBRET ctdbDeleteTable(CTHANDLE Handle, pTEXT TableName, pTEXT Password)

Description

ctdbDeleteTable() drops the table from the database and deletes the table data and index files from disk. This function should be used with care, since it will remove from disk the data and index file(s) associated with the specified table. Note that active/open tables must be closed before they can be deleted with this function (see ctdbCloseTable()).

• Handle [in] the handle of the database that contains the table to be deleted.
• TableName [in] the name of the table to be deleted.
• Password [in] the table password. NULL if the table was created w/o a password.

Use ctdbAddTable() to add a table to a database. Use ctdbDropTable() to drop the table from the database but not delete the table files from disk.

Note: ctdbDeleteTable() is for use within a CTDB or SQL session. For a CTREE session, you must use ctdbRemoveTable(). See also Allocating a Session Handle.

Returns

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

Example

eRet=ctdbConnect(hDatabase, database_name);

eRet = ctdbDeleteTable(hDatabase, table_name, NULL);

See also

ctdbAddTable(), ctdbDropTable(), ctdbAllocDatabase()

ctdbDelField

Delete the field indicated by the field number index from a table.

Declaration

CTDBRET ctdbDelField(CTHANDLE Handle, NINT Index)

Description

ctdbDelField() deletes the field indicated by the field number Index from a table. Note that any fields with higher field numbers than the one you deleted will have one subtracted from their field numbers in order to fill the gap left by the field you deleted. Use ctdbDelFieldByName() to delete a field by name. Use ctdbAddField(), ctdbInsField() and ctdbInsFieldByName() to add fields to a table.

• Handle [in] the Table handle.
• Index [in] the field number to be deleted.

Returns

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

See also

ctdbAllocTable(), ctdbAddField(), ctdbInsField(), ctdbInsFieldByName(), ctdbDelFieldByName(), ctdbMoveField()

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

ctdbCurrencyAbs

Return the absolute value of a CTCURRENCY type value.

Declaration

CTCURRENCY ctdbCurrencyAbs(CTCURRENCY left)

Description

ctdbCurrencyAbs() returns the absolute value of a CTCURRENCY type value.

• left [in] the value to be converted to absolute.

Returns

ctdbCurrencyAbs() returns the absolute value.

See also

ctdbCurrencyAdd(), ctdbCurrencySub(), ctdbCurrencyMul(), ctdbCurrencyDiv(), ctdbCurrencyCmp(), ctdbCurrencyRound()

ctdbCurrencyAdd

Add two currency values. pResult = left + right

Declaration

CTDBRET ctdbCurrencyAdd(CTCURRENCY left, CTCURRENCY right, pCTCURRENCY pResult)

Description

ctdbCurrencyAdd() adds two currency values. pResult = left + right. Do not make regular additions with CTCURRENCY values.

• left [in] the first value to be added.
• right [in] the second value to be added.
• pResult [out] the result of the add operation.

Returns

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

The possible errors associated with ctdbCurrencyAdd() are:

• CTDBRET_NULARG (4007): Null argument not valid in any operand
• CTDBRET_UNDERFLOW (4039): Operation caused underflow
• CTDBRET_OVERFLOW (4038): Operation caused overflow

See also

ctdbCurrencySub(), ctdbCurrencyMul(), ctdbCurrencyDiv()

ctdbCurrencyCmp

Compare two CTCURRENCY type values.

Declaration

NINT ctdbCurrencyCmp(CTCURRENCY left, CTCURRENCY right)

Description

ctdbCurrencyCmp() compares two CTCURRENCY values.

• left [in] the first value to be compared.
• right [in] the second value to be compared.

Returns

ctdbCurrencyCmp() returns a negative value if left < right, positive value if left > right, and zero if left == right

See also

ctdbCurrencyAdd(), ctdbCurrencySub(), ctdbCurrencyMul(), ctdbCurrencyDiv(), ctdbCurrencyAbs(), ctdbCurrencyRound()

ctdbCurrencyDiv

Divide a currency value by another currency value. pResult = left / right.

Declaration

CTDBRET ctdbCurrencyDiv(CTCURRENCY left, CTCURRENCY right,
                        pCTCURRENCY pResult)

Description

ctdbCurrencyDiv() divides the left currency value by the right currency value (e.g., pResult = left / right). Do not make regular division with CTCURRENCY values. Use regular division between a CTCURRENCY value and a numeric value (int, COUNT, FLOAT, etc.).

• left [in] the value to be divided (divisor).
• right [in] the value to divide (dividend).
• pResult [out] the result of the Div operation.

Returns

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

The possible errors associated with ctdbCurrencyDiv() are:

• CTDBRET_NULARG (4007): Null argument not valid in any operand
• CTDBRET_DIVBYZERO (4040): Division by zero error

See also

ctdbCurrencyAdd(), ctdbCurrencySub(), ctdbCurrencyMul()

ctdbCurrencyMul

Multiply two CTCURRENCY values.

Declaration

CTDBRET ctdbCurrencyMul(CTCURRENCY left, CTCURRENCY right,
                        pCTCURRENCY pResult)

Description

ctdbCurrencyMul() multiplies two currency values. pResult = left * right. Do not use regular multiplication with CTCURRENCY values. Use regular multiplication with a combination of a CTCURRENCY value and a numeric value (int, COUNT, FLOAT, etc.).

• left [in] the first value to be multiplied.
• right [in] the second value to be multiplied.
• pResult [out] the result of the multiplication operation.

Returns

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

The possible errors associated with ctdbCurrencyMul() are:

• CTDBRET_NULARG (4007): Null argument not valid in any operand
• CTDBRET_OVERFLOW (4038): Operation caused overflow

See also

ctdbCurrencyAdd(), ctdbCurrencySub(), ctdbCurrencyDiv()

ctdbCurrencyRound

Round a currency value to a given number of decimal places.

Declaration

CTDBRET ctdbCurrencyRound(pCTCURRENCY value, NINT scale)

Description

ctdbCurrencyRound() rounds a currency value to a given number of decimal places.

• value [in/out] the value to be converted to absolute.
• scale [in] the number of decimal digits.

Returns

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

The possible error associated with ctdbCurrencyMu()l is:

• CTDBRET_NULARG (4007): Null argument not valid in any operand

See also

ctdbCurrencyAdd(), ctdbCurrencySub(), ctdbCurrencyMul(), ctdbCurrencyDiv(), ctdbCurrencyCmp(), ctdbCurrencyAbs()

ctdbCurrencySub

Subtract two currency values. pResult = left - right.

Declaration

CTDBRET ctdbCurrencySub(CTCURRENCY left, CTCURRENCY right,
                        pCTCURRENCY pResult)

Description

ctdbCurrencySub() subtracts two currency values. pResult = left - right. Do not make regular subtractions with CTCURRENCY values.

• left [in] the first value, to be subtracted by right.
• right [in] the second value, to subtract from left.
• pResult [out] the result of the subtraction operation.

Returns

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

The possible errors associated with ctdbCurrencySub() are:

• CTDBRET_NULARG (4007): Null argument not valid in any operand
• CTDBRET_UNDERFLOW (4039): Operation caused underflow
• CTDBRET_OVERFLOW (4038): Operation caused overflow

See also

ctdbCurrencyAdd(), ctdbCurrencyMul(), ctdbCurrencyDiv()

ctdbCurrencyToBigInt

Convert a CTCURRENCY value to a big integer value.

Declaration

CTDBRET ctdbCurrencyToBigInt(CTCURRENCY currency, pCTBIGIND pValue)

Description

ctdbCurrencyToBigInt() converts a CTCURRENCY (8 bytes signed integer) value to a big integer (8 bytes signed integer) value. Use ctdbBigIntToCurrency() to convert from a big integer (CTBIGINT) value to a CTCURRENCY value. Use ctdbCurrencyToLong() to convert from CTCURRENCY to a CTSIGNED (4 bytes signed integer).

• currency [in] the CTCURRENCY value (8 bytes integer).
• pValue [out] the CTBIGINT value (8 bytes integer).

Returns

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

The possible error associated with ctdbCurrencyToBigInt() is:

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

See also

ctdbBigIntToCurrency()

ctdbCurrencyToFloat

Convert a CTCURRENCY value to a float value.

Declaration

CTDBRET ctdbCurrencyToFloat(CTCURRENCY currency, pCTFLOAT pValue)

Description

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

• currency [in] the CTCURRENCY value (8 bytes integer).
• pValue [out] the CTFLOAT value.

Returns

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

The possible error associated with ctdbCurrencyToFloat() is:

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

See also

ctdbFloatToCurrency()

ctdbCurrencyToLong

Convert a CTCURRENCY value to a LONG value.

Declaration

CTDBRET ctdbCurrencyToLong(CTCURRENCY currency, pCTSIGNED pValue)

Description

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

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

Returns

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

The possible error associated with ctdbCurrencyToLong() is:

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

See also

ctdbLongToCurrency()

ctdbCurrencyToMoney

Convert a CTCURRENCY value to a CTMONEY value.

Declaration

CTDBRET ctdbCurrencyMoney(CTCURRENCY currency, pCTMONEY pMoney)

Description

ctdbCurrencyToMoney() converts a CTCURRENCY value to a CTMONEY value. A currency value is an 8 bytes integer. Use ctdbMoneyToCurrency() to convert from a CTMONEY value to a CTCURRENCY value.

• currency [in] the CTCURRENCY value (8 bytes integer).
• pMoney [out] the CTMONEY value.

Returns

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

The possible error associated with ctdbCurrencyToMoney() is:

• CTDBRET_NULARG (4007): Null argument not valid in pMoney
• CTDBRET_OVERFLOW (4038): Operation caused overflow
• CTDVRET_UNDERFLOW (4039): Operation caused underflow

See also

ctdbMoneyToCurrency()

ctdbCurrencyToNumber

Convert a CTCURRENCY value to a CTNUMBER value.

Declaration

CTDBRET ctdbCurrencyToNumber(CTCURRENCY value, pCTNUMBER pNumber)

Description

ctdbCurrencyToNumber() converts a CTCURRENCY value to a CTNUMBER value. Use ctdbNumberToCurrency() to convert from a CTNUMBER to CTCURRENCY.

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

Returns

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

The possible error associated with ctdbCurrencyToNumber() is:

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

See also

ctdbNumberToCurrency(), ctdbNumberToLong()

ctdbCurrencyToString

Convert a CTCURRENCY value to a string value.

Declaration

CTDBRET ctdbCurrencyToString(CTCURRENCY currency, pTEXT pStr, VRLEN size)

Description

ctdbCurrencyToString() converts a CTCURRENCY (8 bytes signed integer) value to a string value. Use ctdbStringToCurrency() to convert from a string to a CTCURRENCY value.

• currency [in] the CTCURRENCY value (8 bytes integer).
• pStr [out] the string value.
• size [in] the string size in bytes.

Returns

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

The possible error associated with ctdbCurrencyToString() is:

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

See also

ctdbStringToCurrency()

ctdbCurrentDate

Retrieve the current system date.

Declaration

CTDBRET ctdbCurrentDate(pCTDATE pDate)

Description

ctdbCurrentDate() retrieves the current system date. ctdbCurrentDateTime() retrieves the current date and time.

• pDate [out] pointer to a CTDATE value to receive the current date.

Returns

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

See also

ctdbCurrentTime(), ctdbCurrentDateTime()

ctdbCurrentDateTime

Retrieve the current system date and time, excluding milliseconds.

Declaration

CTDBRET ctdbCurrentDateTime(pCTDATETIME pDateTime)

Description

ctdbCurrentDateTime() retrieves the current system date and time.

• pDateTime [out] pointer to a CTDATETIME value to receive the current date and time.

Returns

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

Note Although CTDATETIME includes milliseconds, this function truncates them to 0. Use ctdbCurrentDateTimeUTC() if you need millisecond support.

See also

ctdbCurrentDate(), ctdbCurrentTime(), ctdbCurrentDateTimeUTC()

ctdbCurrentDateTimeUTC

Set a DATETIME field with the current UTC time with millisecond precision.

Declaration

CTDBRET ctdbDECL ctdbCurrentDateTimeUTC(pCTDATETIME pDateTime)

Description

• pCTDATETIME pDateTime the DATETIME field.

This function relies on the system, and makes no guarantees for accuracy or monotonic behavior.

Returns

Returns NO_ERROR on success.

ctdbCurrentTime

Retrieve the current system time with whole second precision.

Declaration

CTDBRET ctdbCurrentTime(pCTTIME pTime)

Description

ctdbCurrentTime() retrieves the current system time. ctdbCurrentDateTime() retrieves the current date and time.

• pTime [out] pointer to a CTTIME value to receive the current time.

Note See CTTIMEMS if you need millisecond precision.

Returns

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

See also

ctdbCurrentDate(), ctdbCurrentDateTime()

ctdbCurrentTimestamp

Returns the number of microseconds since January 1, 1970 (which is incompatible with all other ctdb DateTime function calls).

Declaration

CTDBRET ctdbDECL ctdbCurrentTimestamp(ULONG8 * pTimestamp)

Description

• ULONG8 pTimestamp unsigned 8-byte integer representing current timestamp as the number of microseconds since January 1, 1970 UTC (excluding leap seconds).

This function relies on the system, and makes no guarantees for accuracy or monotonic behavior.

Returns

Returns NO_ERROR on success.