ctdb_u16TOu8

Converts a UTF-16 string to a UTF-8 encoding.

DECLARATION

NINT ctu16TOu8(pWCHAR u16str, pTEXT u8str, NINT u8size);

DESCRIPTION

ctdb_u16TOu8() converts a UTF-16 encoded string to a UTF-8 Unicode string. The input strings are assumed to be terminated by the nul character. All output buffer sizes are specified in bytes.

RETURN

See Appendix "c-tree Plus Error Codes" in the c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.

EXAMPLE

TEXT buffer[512];
switch (ctdb_u16TOu8(tableName, buffer, sizeof(buffer))
{
    case CTDBRET_OK:
    {
        printf("UTF-16 to UTF-8 conversion ok\n");
        break;
    }
    case VBSZ_ERR:
    {
        printf("Conversion buffer is too small\n");
        break;
    }
    case BMOD_ERR:
    {
        printf("Problem occurred during conversion\n");
        break;
    }
    default:
    {
        printf("Unknown error code\n");
        break;
    }
}

SEE ALSO

ctdb_u8TOu16

ctdb_u8TOu16

Converts an ASCII or UTF-8 encoded string to a UTF-16 string.

DECLARATION

NINT ctdb_u8TOu16(pTEXT u8str, pWCHAR u16str, NINT u16size);

DESCRIPTION

ctdb_u8TOu16() converts an ASCII or UTF-8 encoded string to a UTF-16 Unicode string. The input strings are assumed to be terminated by a NULL character. All output buffer sizes are specified in bytes.

RETURN

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

EXAMPLE

WCHAR buffer[256];
switch (ctdb_u8TOu16("tablename", buffer, sizeof(buffer))
{
    case CTDBRET_OK:
    {
        printf("UTF-8 to UTF-16 conversion ok\n");
        break;
    }
    case VBSZ_ERR:
    {
        printf("Conversion buffer is too small\n");
        break;
    }
    case BMOD_ERR:
    {
        printf("Problem occurred during conversion\n");
        break;
    }
    default:
    {
        printf("Unknown error code\n");
        break;
    }
}

SEE ALSO

ctdb_u16TOu8()

ctdbUnixTimeGetDate

Retrieve a CTDATE type value from a unix time type value

Declaration

CTDBRET ctdbDECL ctdbUnixTimeGetDate(time_t DateTime, pCTDATE pDate)

Description

ctdbUnixTimeGetDate() retrieves a CTDATE type value from a unix time type value

Parameters:

• DateTime [IN] - unix time time_t type value
• pDate [OUT] - Packed CTDATE type value

Return Values

Return CTDBRET_OK on success

ctdbUnixTimeGetTime

Retrieve a CTTIME type value from a unix time type value

Declaration

CTDBRET ctdbDECL ctdbUnixTimeGetTime(time_t DateTime, pCTTIME pTime)

Description

ctdbUnixTimeGetTime() retrieves a CTTIME type value from a unix time type value

Parameters:

• DateTime [IN] - unix time time_t type value
• pTime [OUT] - Packed TIME type value

Return Values

Return CTDBRET_OK on success

ctdbUnixTimeToDateTime

Converts a unix time epoch (time_t) into a CTDATETIME type value.

Declaration

CTDBRET ctdbDECL ctdbUnixTimeToDateTime(time_t time, pCTDATETIME pDateTime, CTBOOL tolocaltime)

Description

ctdbUnixTimeToDateTime() converts a unix time_t value into a CTDATETIME type value.

Parameters:

• time [IN] time_t
• pDateTime [OUT] - CTDATETIME value
• tolocaltime [IN] convert to localtime before packing

Return Values

Returns: Return CTDBRET_OK on success

ctdbUnixTimeToString

Convert a Unix time_t type value to string

Declaration

CTDBRET ctdbDECL ctdbUnixTimeToString(time_t time, CTDATE_TYPE DateType, CTTIME_TYPE TimeType, pTEXT pStr, VRLEN size)

Description

ctdbUnixTimeToString() converts a Unix time_t type value to string

Parameters:

• time [IN] - Unix time_t type value.
• DateType [IN] - One of the the date types.
• TimeType [IN] - One of the time types.
• pStr [OUT] - Pointer to a string buffer to received the converted date and time.
• size [IN] - size in bytes of the memory area pointed by pStr.

Return Values

Return CTDBRET_OK on success

ctdbUnlock

Disables or suspends session-wide record locking and releases some record locks.

Declaration

CTDBRET ctdbUnlock(CTHANDLE Handle)

Description

ctdbUnlock() disables or suspends session-wide record locking, so any records read after calling this function will NOT be automatically locked. Also, ctdbUnlock() releases some (but not all) of the record locks, as described below. Calling this function is the same as calling ctdbLock() with the lock mode CTLOCK_FREE.

• Handle [in] a Session or any other Handle.

This function behaves differently if called inside or outside of a transaction. ("Inside a transaction" means that ctdbBegin() was called, but ctdbCommit() / ctdbAbort() was NOT called.)

Inside a Transaction - Session-wide record locking is suspended. All currently-locked records remain locked. This means both records automatically locked via the session-wide record locking mechanism (call ctdbLock() and then read a record), and records manually locked by calling ctdbLockRecord() on an individual record. Later, when the transaction is finished (by calling ctdbCommit() or ctdbAbort()), the locks on these records will be released. To restore session-wide locking (un-suspend it), call ctdbLock() with one of the READ or WRITE lock modes (or one of the RESTORE options).

Outside a Transaction - Session-wide record locking is turned off. All records that were automatically locked via the session-wide record locking mechanism (call ctdbLock() and then read a record) are unlocked. All records that were manually locked by calling ctdbLockRecord() on an individual record remain locked, EXCEPT for records from a CTCREATE_NORMAL table that were modified and then written before this function was called; those records are unlocked.

To release record locks that were manually obtained with ctdbLockRecord(), use ctdbUnlockRecord().

If the unused locks from a particular table must be released inside a transaction, ctdbUnlockTable() may be used. Unused locks are records that where locked but not updated/deleted/added.

Returns

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

Example

if (ctdbIsLockActive(pSession))

ctdbUnlock(pSession);

See also

ctdbLock(), ctdbIsLockActive(), ctdbGetLockMode(), ctdbUnlockRecord(), ctdbUnlockTable(), Locking

ctdbUnlockRecord

Unlock the current record.

Declaration

CTDBRET ctdbUnlockRecord(CTHANDLE Handle)

Description

ctdbUnlockRecord() unlocks the current record, regardless of whether the record was automatically locked via the session-wide record locking mechanism (call ctdbLock() and then read a record), or manually locked by calling ctdbLockRecord() on an individual record. There is one exception to this - any new/modified/deleted records that were locked (via either of the locking methods) in a transaction, in a CTCREATE_TRNLOG / CTCREATE_PREIMG table, are NOT unlocked by this function. (But locks on records in a CTCREATE_NORMAL table ARE unlocked.) Later, when the transaction is finished (by calling ctdbCommit() or ctdbAbort()), the locks on those still-locked records will be released. This function has no effect on the session-wide record locking mode (it does not turn it on or off, or suspend it, etc.) Use ctdbUnlockTable() to unlock ALL the locked records (with certain exceptions) in a given table.

• Handle [in] the record handle.

Returns

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

See also

ctdbLockRecord(), ctdbUnlock(), Locking

ctdbUnlockResource

Release any locks held by resource.

DECLARATION

CTDBRET ctdbDECL ctdbUnlockResource(CTHANDLE resource);

DESCRIPTION

Unlocks a resource. The resource is only unlocked if it was previously locked by ctdbFirstResource(), ctdbNextResource(), ctdbFindResource() or ctdbFindResourceByName().

• resource is a handle allocated by ctdbAllocHandle().

RETURN

ctdbUlnlockResource() returns CTDBRET_OK on success.

EXAMPLE

if (ctdbIsResourceLocked(hRes))

ctdbUnlockResource(hRes);

SEE ALSO

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

ctdbUnlockTable

Releases all record locks associated with a table.

Declaration

CTDBRET ctdbUnlockTable(CTHANDLE Handle)

Description

ctdbUnlockTable() releases all record locks associated with the specified table, regardless of whether the records were automatically locked via the session-wide record locking mechanism (call ctdbLock() and then read a record), or manually locked by calling ctdbLockRecord() on an individual record. There is one exception to this - any new/modified/deleted records that were locked (via either of the locking methods) in a transaction, in a CTCREATE_TRNLOG / CTCREATE_PREIMG table, are NOT unlocked by this function. (But locks on records in a CTCREATE_NORMAL table ARE unlocked.) Later, when the transaction is finished (by calling ctdbCommit() or ctdbAbort()), the locks on those still-locked records will be released. This function has no effect on the session-wide record locking mode (it does not turn it on or off, or suspend it, etc.) Use ctdbUnlockRecord() to unlock just one record (with certain exceptions).

• Handle [in] the Table, Record, Field, Index or Segment Handle.

Returns

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

See also

ctdbLockRecord(), ctdbUnlockRecord(), Locking

ctdbUpdateCndxIndex

Add, change or delete the conditional expression associated with an index, given by number.

Declaration

CTDBRET ctdbUpdateCndxIndex(CTHANDLE Handle, NINT indexnbr,

pTEXT cndexpr)

Description

ctdbUpdateCndxIndex() adds, changes or deletes the conditional expression associated with an index. After the conditional expression is successfully associated with the index, the index data is automatically rebuilt. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName().

• Handle [in] the Table Handle.
• indexnbr [in] the index number.
• cndexpr [in] string containing the conditional expression.

Returns

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

See also

ctdbUpdateCndxIndexByName(), ctdbGetCndxIndex(), ctdbGetCndxIndexByName(), ctdbGetCndxIndexLength(), ctdbGetCndxIndexLengthByName()

ctdbUpdateCndxIndexByName

Add, change or delete the conditional expression associated with an index, given by name.

Declaration

CTDBRET ctdbUpdateCndxIndexByName(CTHANDLE Handle, pTEXT indexname,

pTEXT cndexpr)

Description

ctdbUpdateCndxIndexByName() adds, changes or deletes the conditional expression associated with an index, given by name. After the conditional expression is successfully associated with the index, the index data is automatically rebuilt. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName().

• Handle [in] the Table Handle.
• indexname [in] the index name.
• cndexpr [in] string containing the conditional expression.

Returns

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

See also

ctdbUpdateCndxIndex(), ctdbGetCndxIndex(), ctdbGetCndxIndexByName(), ctdbGetCndxIndexLength(), ctdbGetCndxIndexLengthByName()

ctdbUpdateCreateMode

Update the table create mode.

Declaration

CTDBRET ctdbUpdateCreateMode(CTHANDLE Handle, CTCREATE_MODE mode)

Description

ctdbUpdateCreateMode() updates the table create mode (which was specified when the table was created with the ctdbCreateTable() function). ctdbUpdateCreateMode() changes critical file mode attributes, such as the level of transaction control. This function is intended for use by experts, and should not be used unless you really understand all the implications. Since calling this function can cause the settings stored in the table handle to get out of sync with the table dictionary, the programmer should close and then re-open the table after using this function (see ctdbCloseTable(), ctdbOpenTable()).

No check is made to determine if the mode change will damage data. No check is made if the new mode is valid.

Note: Use this function with caution, as data may be lost. For example, changing a data file from transaction processing to no transaction processing makes automatic recovery unavailable.

• Handle [in] the Table Handle.
• mode [in] the new table create mode. It must be perfectly formed, as it will replace the current table create mode. Use the function ctdbGetTableCreateMode() to retrieve the current create mode and apply the changes on a fully qualified create mode. Update only the following create table modes:
  • CTCREATE_PREIMG
  • CTCREATE_TRNLOG
  • CTCREATE_WRITETHRU
  • CTCREATE_CHECKLOCK
  • CTCREATE_CHECKREAD
  • CTCREATE_HUGEFILE

Returns

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

See also

ctdbCreateTable()

ctdbUpdateCriteria

Updates the criteria from the given CTResultSet handle.

Declaration

ctdbUpdateCriteria(CTHANDLE Handle, pTEXT LowValue, pTEXT HighValue)

Parameters:

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

Description

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

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

Limitations

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

Returns

CTDBRET_OK on success. CTDBRET error code on failure.

Example

   CTHANDLE hResSet;
   CTHANDLE hResSetCri;
 
/* Allocate a Result Set for Table */
if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))
    Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");

/* Add a new criteria for the Result Set just allocated */
if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))
    Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");

/* Turn on the Result Set for the current record handle */
if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)
    Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");

/* Display records on the Result Set */
Display_Records(hRecord);

/* Release Result Set handle */
ctdbFreeResultSet( hResSet );

See also

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

ctdbUpdateFixedStringPadding

Update the table pad, delimiter character resource, and fixed string termination strategy. The table must be opened in exclusive mode to update the resource.

Declaration

CTDBRET ctdbDECL ctdbUpdateFixedStringPadding(CTHANDLE Handle, NINT padchar, NINT dlmchar, CTBOOL fstringterm)

Parameters

• Handle [in] the Table Handle.
• padchar [in] the pad character
• dmlchar [in] the field delimiter character.
• fstringterm [in] if YES, fixed string fields will be terminated with dmlchar in the defined len. If NO, fixed string fields will be terminated only if they do not already consume the entire defined len.

Returns

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

See also

ctdbUpdatePadChar(), ctdbSetPadChar(), ctdbGetPadChar()

ctdbUpdatePadChar

Update the table pad and delimiter character resource.

Declaration

CTDBRET ctdbUpdatePadChar(CTHANDLE Handle, NINT padchar, NINT dmlchar,

CTBOOL rebuild)

Description

ctdbUpdatePadChar() updates the table pad and delimiter character resource. The table must be opened exclusive to allow update of the resource.

• Handle [in] the Table Handle.
• padchar [in] the pad character
• dmlchar [in] the field delimiter character.
• rebuild [in] indicate if the table should be rebuilt. If rebuild is set to YES, every record is read and the fixed string fields (CT_FSTRING) are padded according to new padding strategy. Notice that this feature is not implemented yet, and no rebuild is done.

Returns

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

See also

ctdbSetPadChar(), ctdbGetPadChar()

ctdbUpdateResource

Update the contents of an existing resource.

DECLARATION

CTDBRET ctdbDECL ctdbUpdateResource(CTHANDLE resource, cpVOID data, VRLEN size);

DESCRIPTION

ctdbUpdateResource() update an existing resource. You must call ctdbAllocResource() with specific resource type and number that will uniquely identify the resource being updated. resource is a handle allocated by ctdbAllocResource(). The Resource data is any collection of data that you wish to store as a Resource. It can be a character string, a structure, or any variable type. size indicate the number of bytes occupied by data.

RETURN

ctdbUpdateResource() returns CTDBRET_OK on success.

EXAMPLE

CTDBRET UpdateMyResource(CTHANDLE Handle, ULONG type, ULONG number, pTEXT name, pVOID data, VRLEN size)

{

CTDBRET Retval;

CTHANDLE hRes = ctdbAllocResource(Handle, type, number, name);

if (hRes)

{

if ((Retval = ctdbUpdateResource(hRes, data, size)) != CTDBRET_OK)

printf("ctdbUpdateResource failed with error %d\n", Retval);

ctdbFreeResource(hRes);

}

else

{

printf("Failed to allocate resource handle\n");

Retval = CTDBRET_NOMEMORY;

}

return Retval;

}

SEE ALSO

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