FairCom ISAM for C

SetCallbackOnRebuild

Sets up a callback function that file reconstruction functions call as progress is made during an operation.

Short Name

SETCBRBL()

Type

Low-Level function

Declaration

COUNT SetCallbackOnRebuild( pVOID funcptr, UCOUNT step )

Description

SetCallbackOnRebuild() sets a pointer to a callback function that is periodically called by the file reconstruction functions RebuildIFile(), RebuildIFileXtd(), CompactIFile(), and CompactIFileXtd(). The callback function can be used for progress notification and to implement a custom user interface for rebuild utility programs.

When the rebuild callback support is activated, an internal counter is incremented every time a record or key is processed during the reconstruction process. The callback function is called each time the internal counter reaches a value that is a multiple of step. If step is set to 1, the callback function is called once per record/key. The ability of setting the callback frequency, gives the user the ability to balance between speed and accuracy.

The funcptr must be a pointer to a callback function of type RBLCBFNC that accepts three parameters. The function prototype is shown below.

void (*pRBLCBFNC)(ULONG counter, TEXT event, pTEXT message);

counter is the current value of the internal counter.

event identifies the type of event that triggered the callback. event options are listed in the following table:

event	Interpretation
RBLCB_DAT	counter reached a multiple of step while processing data records.
RBLCB_IDX	counter reached a multiple of step while processing index keys.
RBLCB_MSG	A pointer to a NULL terminated string that contains information about the status of the rebuild process is passed to the message parameter.
RBLCB_LOG	Flag to write to a user defined log file. counter is 1 for error, 0 for informational.
RBLCB_CNT	return total number of records in file/index
RBLCB_MCT	return percentage complete * 10 (of current stage of rebuild)

message is a text string to be returned.

Return

Always returns NO_ERROR (0).

Example CTRBLEX.C in the ctree\samples directory

IFIL my_ifil = {...};

void CallbackProc( ULONG counter, TEXT event, TEXT* message )

{

switch(event)

{

case RBLCB_DAT:

putchar('d');

break;

case RBLCB_IDX:

putchar('i');

break;

case RBLCB_MSG:

printf("\n%s", message);

break;

case RBLDB_CNT:

printf("\n%s", counter);

break;

case RBLCB_LOG:

printf("\n%s", message);

break;

case RBLDB_MCT:

printf("\n%s", (double) counter / 10);

}

void main()

{

SetCallbackOnRebuild( CallbackProc, 1 );

RebuildIFile( &my_ifil );

}