ctdbEndBatch

Terminates or cancels a batch operation.

DECLARATION

CTDBRET ctdbDECL ctdbEndBatch(CTHANDLE Handle);

DESCRIPTION

A batch operation must be terminated by calling the ctdbEndBatch() function. Once a batch operation is started with ctdbSetBatch(), no other batch operation is allowed to start until the current batch operation is terminated.

When performing batch retrieval operations, you may cancel the batch operation before retrieving all the records by calling ctdbEndBatch().

If the batch operation is a CTBATCH_RANGE then you must also call ctdbRecordRangeOff() function to terminate the index range used for the batch operation.

Handle must be a FairCom DB API record handle associated with an opened table.

RETURNS

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

EXAMPLE

/* set the partial target key */
ctdbClearRecord(hRecord);
ctdbSetFieldAsSigned(hRecord, 0, Invoice);

/* set the batch operation */
if (ctdbSetBatch(hRecord, CTBATCH_DEL, sizeof(Invoice), 0) != CTDBRET_OK)
    printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));

/* end the batch operation */
if (ctdbEndBatch(hRecord) != CTDBRET_OK)
    printf("ctdbEndBatch failed with error %d\n", ctdbGetError(hRecord));

SEE ALSO

ctdbBatchLoaded(), ctdbBatchLocked(), ctdbBatchMode(), ctdbBatchTotal(), ctdbInsertBatch(),
ctdbIsBatchActive(), ctdbNextBatch(), ctdbSetBatch()

ctdbEndImpersonation

Disables the ability of the thread to support impersonation by another thread.

Declaration

CTDBRET ctdbEndImpersonation(CTHANDLE Handle)

Description

Finishes current impersonation (ctImpersonateTask()) and updates the "lock mode" on the server side with the lock mode stored before the impersonation in the prelockmode session property.

Note This function is not supported by the FairCom Server by default. It requires a custom build of the server available by special request.

Returns

CTDBRET_OK on success.

See Also

ctdbBeginImpersonation()

ctdbEstimateSpan

Estimate an approximate number of records between two key target values.

Declaration

LONG ctdbEstimateSpan(CTHANDLE Handle, pVOID key1, pVOID key2);

Description

• Handle is a record handle.
• key1 and key2 are two key target values used to obtain the estimated number of records.

If ctdbEstimateSpan() returns 0, use ctdbGetError() function to retrieve the error code. If ctdbEstimateSpan() returns 0 and ctdbGetError() returns CTDBRET_OK then there are no records between the two key values supplied.

The estimation is based on the record handle current index. The current index may be changed by calling ctdbSetDefaultIndex(). The table must have at least one index to be able to use this function.

ctdbEstimateSpan(), which is based on c-tree low level function EstimateKeySpan(), does not traverse the index to compute the values. Instead, it makes about ten calls to the c-tree low level function KeyAtPercentile() to determine the relative location of the target values.

The key target values used by ctdbEstimateSpan() can be created using ctdbBuildTargetKey().

Return

ctdbEstimateSpan() returns an estimate of the number of records between key1 and key2. Call ctdbGetError() to retrieve the error code.

See FairCom DB API Errors and Return Values for a complete listing of valid FairCom DB API error codes and return values.

Example

Suppose that a student table has two fields (Name - CT_FSTRING and Age - CT_INT2) and one index on field Age. The sample function estimate the number of students with ages between 10 and 12:

LONG EstimateStudents(CTHANDLE hRecord)
{
   TEXT key1[32];
   TEXT key2[32];
   VRLEN key1Len = 32;
   VRLEN key2Len = 32;
 
   /* build the first key for age = 10 years */
   ctdbClearRecord(hRecord);
   ctdbSetFieldAsSigned(hRecord, 1, 10);
   if (ctdbBuildTargetKey(hRecord, CTFIND_EQ, key1, &key1Len))
      return 0;
 
 /* build the second key for age = 12 years */
   ctdbClearRecord(hRecord);
   ctdbSetFieldAsSigned(hRecord, 1, 12);
   if (ctdbBuildTargetKey(hRecord, CTFIND_EQ, key2, &key2Len))
      return 0;
 
   /* estimate the number of students */
   return ctdbEstimateSpan(hRecord, key1, key2);
}
 

See also

ctdbSetDefaultIndex(), ctdbBuildTargetKey()

ctdbExecJsonAction

ctdbExecJsonAction() executes the JSON Action request with the user-defined JSON string and returns the JSON string with the JSON Action response. If the provided buffer is not large enough, error VBSZ_ERR is returned, and the required buffer size is populated in the outputSize parameter.

Declaration

CTDBRET ctdbExecJsonAction(CTHANDLE Handle,const char *input, char *output, size_t *outputSize);

Description

• Handle - Active ctdb Handle.
• input - specifies the JSON string being sent in the request.
• output - specifies the JSON string once it has been returned in the response.
• outputSize - specifies the size of the JSON string that was returned.

For best performance, the caller should avoid providing output buffers that are too small.

Return Values

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