C API Functions M

ctdbMergeDatabaseDictionary

Compare and merge FairCom DB API database dictionaries.

Declaration

ctdbEXPORT CTDBRET ctdbDECL ctdbMergeDatabaseDictionary (CTHANDLE src, CTHANDLE dst, mergeFunPtr mrgfun, logFunPtr logfun);

Description

Parameters

  • src: handle of an exclusively open session where the database dictionary is the dictionary containing the entry to be merged.
  • dst: handle of an exclusively open session where the database dictionary is the target dictionary for the merge.
  • mrgfun: function that the FairCom DB API engine calls to perform the comparison and set the actions on the compared items.

The function prototype is:

CTDBRET (ctdbDECL *mergeFunPtr) (pCTDBLIST src_list, pCTDBLIST dst_list);

mrgfun must return either an error code (in which case the ctdbMergeSessionDictionary () function will fail with that error code) or CTDBRET_OK if no error occurred.

The FairCom DB API engine will pass two lists (CTDBLIST) containing items of type MERGEINFO. One per each dictionary entry.

The MERGEINFO structure is defined as follows:

struct tagMERGEINFO

{

DICTDATA info;

NINT todo;

};

  • info contains the dictionary record.
  • todo must be set to the action to perform on that entry.
  • src_list contains the elements from the source dictionary
  • dst_list contains the elements from the target dictionary.

The function must set for each entry the action to be performed on that entry as follows:

Source List Actions

Description

DIFF_SRC_IGNORE

Ignore the record in the source list and do not copy it on the target dictionary

DIFF_SRC_COPY2DST

Copy the record to the target dictionary for entries on the dst_list.

Destination List Actions

Description

DIFF_DST_KEEP

Keep the entry as it is.

DIFF_DST_REMOVE

Remove the entry.

DIFF_DST_REWRITE

Replace the dest record on disk with the one in the list (in case we merge only some information).
Note: This cannot change the UID.

For example, to replace an entry on the target dictionary with one from the source dictionary, the todo of the item in dsl_list must be set to DIFF_DST_REMOVE, the todo of the item in src_list to DIFF_SRC_COPY2DST.

  • logfun: the function called to return additional information about errors.

The function prototype is:

VOID (ctdbDECL*logFunPtr) (NINT lvl, pTEXT mesg, CTDBRET error, pTEXT extra);

  • lvl: number indication the error message level. (1 indicating fewer and higher level messages to 3 indicating more numerous detailed messages.)
  • mesg: the error message
  • error: the error code
  • extra: extra information such as the table or database name.

Note: Depending on where an error occurred, this function could be called multiple times with different lvl and mesg.

Return Values

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

Example

Please review the source code for ctsqlmdd.c, FairCom DB SQL Database Move Utility, for a complete implementation using this FairCom DB API function.

See Also

ctrdbMergeSessionDictionary()

 

ctdbMergeSessionDictionary

Compare and merge FairCom DB API session dictionaries.

Declaration

ctdbEXPORT CTDBRET ctdbDECL ctdbMergeSessionDictionary (CTHANDLE src, CTHANDLE dst, mergeFunPtr mrgfun, logFunPtr logfun);

Description

Parameters

  • src: handle of an exclusively open session where the session dictionary is the dictionary containing the entry to be merged.
  • dst: handle of an exclusively open session where the session dictionary is the target dictionary for the merge.
  • mrgfun: function that the FairCom DB API engine calls to perform the comparison and set the actions on the compared items.

The function prototype is:

CTDBRET (ctdbDECL *mergeFunPtr) (pCTDBLIST src_list, pCTDBLIST dst_list);

mrgfun must return either an error code (in which case the ctdbMergeSessionDictionary () function will fail with that error code) or CTDBRET_OK if no error occurred.

The FairCom DB API engine will pass two lists (CTDBLIST) containing items of type MERGEINFO. One per each dictionary entry.

The MERGEINFO structure is defined as follows:

struct tagMERGEINFO

{

DICTDATA info;

NINT todo;

};

  • info contains the dictionary record.
  • todo must be set to the action to perform on that entry.
  • src_list contains the elements from the source dictionary
  • dst_list contains the elements from the target dictionary.

The function must set for each entry the action to be performed on that entry as follows:

Source List Actions

Description

DIFF_SRC_IGNORE

Ignore the record in the source list and do not copy it on the target dictionary

DIFF_SRC_COPY2DST

Copy the record to the target dictionary for entries on the dst_list.

Destination List Actions

Description

DIFF_DST_KEEP

Keep the entry as it is.

DIFF_DST_REMOVE

Remove the entry.

DIFF_DST_REWRITE

Replace the dest record on disk with the one in the list (in case we merge only some information).
Note: This cannot change the UID.

For example, to replace an entry on the target dictionary with one from the source dictionary, the todo of the item in dsl_list must be set to DIFF_DST_REMOVE, the todo of the item in src_list to DIFF_SRC_COPY2DST.

  • logfun: the function called to return additional information about errors.

The function prototype is:

VOID (ctdbDECL*logFunPtr) (NINT lvl, pTEXT mesg, CTDBRET error, pTEXT extra);

  • lvl: number indication the error message level. (1 indicating fewer and higher level messages to 3 indicating more numerous detailed messages.)
  • mesg: the error message
  • error: the error code
  • extra: extra information such as the table or database name.

Note: Depending on where an error occurred, this function could be called multiple times with different lvl and mesg.

Return Values

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

Example

Please review the source code for ctsqlmdd.c, FairCom DB SQL Database Move Utility, for a complete implementation using this FairCom DB API function.

See Also

ctrdbMergeDatabaseDictionary()

 

ctdbMoneyAbs

Return the absolute value of a CTMONEY type value.

Declaration

CTMONEY ctdbMoneyAbs(CTMONEY left)

Description

ctdbMoneyAbs() returns the absolute value of a CTMONEY type value.

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

Returns

ctdbMoneyAbs() returns the absolute value.

See also

ctdbMoneyAdd(), ctdbMoneySub(), ctdbMoneyMul(), ctdbMoneyDiv(), ctdbMoneyCmp()

 

ctdbMoneyAdd

Add two money values. pResult = left + right

Declaration

CTDBRET ctdbMoneyAdd(CTMONEY left, CTMONEY right, pCTMONEY pResult)

Description

ctdbMoneyAdd() add two money values. pResult = left + right. Do not make regular additions with CTMONEY 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

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

The possible errors associated with ctdbMoneyAdd() 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

ctdbMoneySub(), ctdbMoneyMul(), ctdbMoneyDiv()

 

ctdbMoneyCmp

Compare two CTMONEY type values.

Declaration

NINT ctdbMoneyCmp(CTMONEY left, CTMONEY right)

Description

ctdbMoneyCmp() compares two CTMONEY values.

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

Returns

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

See also

ctdbMoneyAdd(), ctdbMoneySub(), ctdbMoneyMul(), ctdbMoneyDiv(), ctdbMoneyAbs()

 

ctdbMoneyDiv

Divide one money value by another money value. pResult = left / right.

Declaration

CTDBRET ctdbMoneyDiv(CTMONEY left, CTMONEY right, pCTMONEY pResult)

Description

ctdbMoneyDiv() divide one money value by another money value. pResult = left / right. Do not make regular division with CTMONEY values. You may user regular division between a CTMONEY 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

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

The possible errors associated with ctdbMoneyDiv() are:

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

See also

ctdbMoneyAdd(), ctdbMoneySub(), ctdbMoneyMul()

 

ctdbMoneyMul

Multiply two CTMONEY values.

Declaration

CTDBRET ctdbMoneyMul(CTMONEY left, CTMONEY right, pCTMONEY pResult)

Description

ctdbMoneyMul() multiplies two money values. pResult = left * right. Do not make regular multiplication with CTMONEY values. It is possible to use regular multiplication with a CTMONEY 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

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

The possible errors associated with ctdbMoneyMul() are:

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

See also

ctdbMoneyAdd(), ctdbMoneySub(), ctdbMoneyDiv()

 

ctdbMoneySub

Subtract two money values. pResult = left - right.

Declaration

CTDBRET ctdbMoneySub(CTMONEY left, CTMONEY right, pCTMONEY pResult)

Description

ctdbMoneySub() subtracts two money values. pResult = left - right. Do not make regular subtractions with CTMONEY 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

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

The possible errors associated with ctdbMoneySub() 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

ctdbMoneyAdd(), ctdbMoneyMul(), ctdbMoneyDiv()

 

ctdbMoneyToCurrency

Convert a CTMONEY value to a CTCURRENCY value.

Declaration

CTDBRET ctdbMoneyToCurrency(CTMONEY money, pCTCURRENCY pCurrency)

Description

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

  • money [in] the CTMONEY value.
  • pCurrency [out] the CTCURRENCY value (8 bytes integer).

Returns

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

The possible error associated with ctdbMoneyToCurrency() is:

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

See also

ctdbCurrencyToMoney()

 

ctdbMoneyToFloat

Convert a CTMONEY value to a floating point number

Declaration

CTDBRET ctdbMoneyToFloat(CTMONEY money, pCTFLOAT pValue)

Description

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

  • money [in] the CTMONEY type value.
  • pValue [out] the floating point value.

Returns

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

The possible error associated with ctdbMoneyToFloat() is:

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

See also

ctdbFloatToMoney()

 

ctdbMoneyToLong

Convert a CTMONEY value to a LONG.

Declaration

CTDBRET ctdbMoneyToLong(CTMONEY money, pLONG pValue)

Description

ctdbMoneyToLong() converts a CTMONEY value to a LONG. The Fraction part of CTMONEY is discarded and only the integer part is assigned. Use ctdbLongToMoney() to convert from a LONG to CTMONEY.

  • money [in] the CTMONEY value.
  • pValue [out] the LONG value representing the integer part of the monetary value.

Returns

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

The possible error associated with ctdbMoneyToLong() is:

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

See also

ctdbLongToMoney()

 

ctdbMoneyToNumber

Convert a CTMONEY value to a CTNUMBER.

Declaration

CTDBRET ctdbMoneyToNumber(CTMONEY money, pCTNUMBER pNumber)

Description

ctdbMoneyToNumber() converts a CTMONEY value to a CTNUMBER. Use ctdbNumberToMoney() to convert from a CTNUMBER to CTMONEY.

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

Returns

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

The possible error associated with ctdbMoneyToLong() is:

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

See also

ctdbNumberToMoney()

 

ctdbMoneyToString

Convert a CTMONEY type value to a string.

Declaration

CTDBRET ctdbMoneyToString(CTMONEY money, pTEXT pStr, VRLEN size)

Description

ctdbMoneyToString() converts a CTMONEY value to a string. Use ctdbStringToMoney() to convert from a string to CTMONEY.

  • money [in] the CTMONEY value.
  • pStr [out] the pointer to the string that will result from the conversion.
  • size [in] the buffer size of the string.

Returns

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

The possible errors associated with ctdbMoneyToString() are:

  • CTDBRET_NULARG (4007): Null argument not valid in pStr
  • CTDBRET_ARGSMALL (4006): Argument is too small - increase size

See also

ctdbStringToMoney()

 

ctdbMoveField

Move a field to another location.

Declaration

CTDBRET ctdbMoveField(CTHANDLE Handle, NINT newIndex)

Description

ctdbMoveField() moves the field to a new location.

  • Handle [in] the field handle of the field that is being moved.
  • newIndex [in] Index of the new location of the field.

Returns

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

See also

ctdbAllocTable(), ctdbAddField(), ctdbInsField(), ctdbDelField()

 

ctdbMoveSegment

Moves a key segment to a location indicated by newIndex.

DECLARATION

CTDBRET ctdbDECL ctdbMoveSegment(CTHANDLE Handle, NINT newIndex);

DESCRIPTION

ctdbMoveSegment() moves a key segment to a location indicated by newIndex. Handle is a segment handle and newIndex indicates the relative position were the key segment should be moved to.

RETURN

Value

Symbolic Constant

Explanation

0

CTDBRET_OK

No error occurred.

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

EXAMPLE

/* move the last segment to first */

NINT count = ctdbGetIndexSegmentCount(hIndex);

if (count > 0)

{

CTHANDLE hSeg = ctdbGetSegment(hIndex, (count - 1));

 

if (ctdbMoveSegment(hSeg, 0) != CTDBRET_OK)

printf("ctdbMoveSegment failed\n");

}

SEE ALSO

ctdbAddSegment(), ctdbInsSegment(), ctdbDelSegment()

ctdbMoveTable

Move a table and its associated index files.

Declaration

CTDBRET ctdbDECL ctdbMoveTable(CTHANDLE Handle, pTEXT oldname, pTEXT newpath, pTEXT newname);

Description

Allows renaming a table and/or "renaming" the path (i.e., using "rename" to move the file to a different location, as is common in Operating System commands and c-tree RENIFIL).

  • Handle [IN] - Database handle
  • oldname [IN] - Old table name
  • newpath [IN] - New table path
  • newname [IN] - New table name

Setting newname or newpath to NULL indicates that the name or the path respectively do not change.

Returns

Return CTDBRET_OK on success.

c api m functions

Was this article helpful?

Give feedback about this article

Related Articles