UltraLite User's Guide
  Designing UltraLite Applications
    Configuring and managing database storage

Defragmenting UltraLite databases

The UltraLite store is designed to efficiently reuse free space, so explicit defragmentation is not required under normal circumstances. This section describes a technique to explicitly defragment UltraLite databases, for use by applications with extremely strict space requirements.

UltraLite provides a defragmentation step function, which defragments a small part of the database. To defragment the entire database at once, call the defragmentation step function in a loop until it returns ul_true. This can be an expensive operation, and SQLCODE must also be checked to detect errors (an error here usually indicates a file I/O error).

Explicit defragmentation occurs incrementally under application control during idle time. Each step is a small operation.

For embedded SQL reference information, see ULStoreDefragFini function, ULStoreDefragInit function, and ULStoreDefragStep function. The embedded SQL functions can also be called from the C++ API.

For the Java interface to this feature, see Class JdbcDefragIterator.

To defragment UltraLite databases (C/C++)

1. Obtain a p_ul_store_defrag_info information block. For example,

   p_ul_store_defrag_info     DefragInfo;
   //...
   db_init( &sqlca );
   DefragInfo = ULStoreDefragInit( &sqlca );

2. During idle time, call UlStoreDefragStep to defragment a piece of the database. For example,

   ULStoreDefragStep( &sqlca, DefragInfo );

3. When complete, dispose of the defragmentation block. For example,

   ULStoreDefragFini( &sqlca, DefragInfo );

To defragment UltraLite databases (Java)

1. Cast a Connection to a JdbcConnection object. For example,

   ...
   Connection conn = db.connect();
   JdbcConnection jconn = (JdbcConnection)conn ;

2. Call getDefragIterator() to obtain a JdbcDefragIterator object. Foe example:

   JdbcDefragIterator defrag = jconn.getDefragIterator();

3. During idle time, call ulStoreDefragStep() to defragment a piece of the database.

   defrag.ulStoreDefragStep();

Example 

In this embedded SQL sample, defragmentation occurs incrementally under application control during idle time. Each defragmentation step is a small operation.

p_ul_store_defrag_info     DefragInfo;

idle()
{
   for( i = 0; i < DEFRAG_IDLE_STEPS; i++ ){
      ULStoreDefragStep( &sqlca, DefragInfo );
      if( SQLCODE != SQLE_NOERROR ) break;
   }
}

main()
{
   db_init( &sqlca );
   DefragInfo = ULStoreDefragInit( &sqlca );
   //
   // main application code,
   // calls idle() when appropriate...
   //
   ULStoreDefragFini( &sqlca, DefragInfo );
   db_fini( &sqlca );
}

To defragment the entire store at once, you can call ULStoreDefragStepin a loop until it returns ul_true. This can be an expensive operation, and you must check SQLCODE to detect errors such as file I/O errors.