Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

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

}

See also

RebuildIFile()

RebuildIFileXtd()

CompactIFile()

CompactIFileXtd()

GETCBRBLST

TOCIndex