Transaction Logging Parameters

The eXtremeDB Transaction Logging feature (TL) is configured by specifying the parameters and bit mask values described below.

TL Params

The following structure is initialized and passed to function mco_translog_start():

 
    typedef struct mco_TL_start_data
    {
        uint2               flags;          /* MCO_TL_FLAGS - transaction log flags  */
        uint2               disk_page_size; /* size of single disk page              */
        uint2               flush_depth;    /* maximum count of not flushed records  */
        timer_unit          flush_time;     /* time lag between flushed records      */
        mco_TL_timer_proc   timer_proc;     /* user defined external timer procedure.*/
        /* (MUST signal when the specified amount*/
        /* of time has elapsed)                  */
        mco_size_t          max_size;       /* max size of log (warn when reached)   */
        mco_TL_warn_sz_proc warn_sz_proc;   /* user defined procedure that warns     */
        /* when maximum size is reached (MUST NOT*/
        /* call any eXtremeDB functions)         */
        char const          *dual_log_path; /* path to log file in dual out mode     */
        mco_event_mask_t    event_mask;     /* mask of logged events
        * MCO_LOG_MASK_ALL_CHANGES: all transaction changes will be logged
        * MCO_LOG_MASK_ALL_EVENTS: then only changes cause triggering of any of declared events will be logged
        * otherwise mask of logged event identifiers (MCO_EVENT_*)
        */
     
    } mco_TL_start_data_t, *mco_TL_start_data_h;
 

The structure elements for structure mco_TL_start_data are defined as follows:

flags	The TL flags combination (possible values for these flags are explained below).
disk_page_size	The size of a single disk page.
flush_depth	The number of transactions to accumulate before flushing to disk.
flush_time	The number of timer “ticks” to wait before flushing to disk.
timer_proc	The user-defined external timer procedure. It must signal when the time specified in flush_time has elapsed. (Note: The timer procedure will be invoked only in the process which started logging in the case of a shared memory application.)
max_size	The log file size to activate a warning call to the user-defined procedure warn_sz_proc.
warn_sz_proc	The user-defined procedure that warns when the maximum log file size has been reached. (Note: This function must NOT call any eXtremeDB functions.)
dual_log_path	The path to the log file in dual out mode.
event_mask	The bit mask of logged events: MCO_LOG_MASK_ALL_CHANGES: all transaction changes will be logged. MCO_LOG_MASK_ALL_EVENTS: only changes that cause the triggering of any of the declared events will be logged (i.e. mask all logged event identifiers MCO_EVENT_* generated by the schema compiler).

TL Flags

The flags element in structure mco_TL_start_data is specified as a combination of one or more of the following bit mask values:

 
    enum MCO_TL_FLAGS
    {
        MCO_TRANSLOG_ALIGNED                = 0x01,   /* start each record with new disk page     */
        MCO_TRANSLOG_APPEND                 = 0x02,   /* append to an existing log file           */
        MCO_TRANSLOG_CRC                    = 0x04,   /* cover transaction data with CRC32        */
        MCO_TRANSLOG_SIZE_CLBK              = 0x08,   /* user call-back function to limit size    */
        MCO_TRANSLOG_SYNC_INSTANTLY         = 0x10,   /* do disk flush on each record             */
        MCO_TRANSLOG_SYNC_TIMER             = 0x20,   /* do disk flush by timer                   */
        MCO_TRANSLOG_SYNC_COUNT             = 0x40,   /* do disk flush by record count            */
        MCO_TRANSLOG_ITERABLE               = 0x80,   /* make log applicable for synchronization  */
                    /* with external database by function       */
                    /* mco_translog_iterate (will increase size */
                    /* of log file)                             */
        MCO_TRANSLOG_RESTART                = 0x100,  /* stop previous log at once                */
        MCO_TRANSLOG_PIPE                   = 0x200,  /* use pipe interface instead of file       */
        MCO_TRANSLOG_DUAL_OUT               = 0x400,  /* duplicate data into a local file if pipe */
        /* interface used                           */
        MCO_TRANSLOG_EVENT_MASK             = 0x800,  /* take event_mask field into account       */
        MCO_TRANSLOG_DYNAMIC_PIPE           = 0x1000, /* use dynamic pipes                        */
        MCO_TRANSLOG_PREREAD_PIPE           = 0x2000  /* pre-read pipe to internal buffer to      */
        /* reduce count of blocking operations      */
    };
 

The possible values for the flags element of the mco_TL_start_data structure are defined as follows (see enum MCO_TL_FLAGS in mcolog.h):

MCO_TRANSLOG_ALIGNED	Each new data block of a stored transaction begins on a new file page
MCO_TRANSLOG_APPEND	Append transactions to an earlier saved log file. The number of the latest transaction in the log file must be the same as the current transaction number of the database.
MCO_TRANSLOG_CRC	Cover the body of the transaction's record with CRC32 for strong safety. This integrity verification automatically enabled for log-to-file modes (which is also true for other disk manager storage operation such as mco_db_save() and mco_db_load()). In pipe modes (i.e. when MCO_TRANSLOG_PIPE , MCO_TRANSLOG_DYNAMIC_PIPE or MCO_TRANSLOG_DUAL_OUT are specified) this integrity check is disabled by default for improved performance. If CRC32 verification is desired for pipe modes it is necessary to specify flag MCO_TRANSLOG_CRC.
MCO_TRANSLOG_SIZE_CLBK	Call the user-defined procedure warn_sz_proc if the specified size of the log file is reached (element max_size must be greater than 0).
MCO_TRANSLOG_SYNC_INSTANTLY	Flush the file system buffers each time a transaction record is written. If the flag is not specified, the runtime buffers transaction in an intermediate buffer.
MCO_TRANSLOG_SYNC_TIMER	Flush to disk every flush_time timer ticks (element flush_time must be greater than 0) as controlled by the user-defined call-back procedure timer_proc (element timer_proc must not be NULL).
MCO_TRANSLOG_SYNC_COUNT	Flush to disk after every flush_depth transactions.
MCO_TRANSLOG_RESTART	Instant restart of a previously started logging session with a new file (without causing freezing of transactions).
MCO_TRANSLOG_ITERABLE	Force the logging engine to write the bodies of deleted objects. This flag is required for creating a log file usable for reading by the function mco_translog_iterate() regardless of which method (file or pipe) is used.
MCO_TRANSLOG_PIPE	Write the log into the pipe specified in mco_device_t with assignment MCO_MEMORY_ASSIGN_PIPE_BUF. The argument file_path specifies an optional overflow file if necessary, or 0.
MCO_TRANSLOG_DUALOUT	Duplicate the data into a local log file if pipe interface is used. Element dual_log_path specifies the file. The dual out option requires that flag MCO_TRANSLOG_PIPE also be specified.
MCO_TRANSLOG_EVENT_MASK	Enable filtering of data stored in the log by events mask. Element event_mask specifies the desired filter.

Implementation notes

Note that the flag values MCO_TRANSLOG_SYNC_TIMER and MCO_TRANSLOG_SYNC_COUNT are compatible with each other, but not with MCO_TRANSLOG_SYNC_INSTANTLY.

The flag value MCO_TRANSLOG_ITERABLE should be used if the log is expected to be read by the function mco_translog_iterate(). It is extremely important that it be specified in conjunction with the flag value MCO_TRANSLOG_PIPE.

Only the MVCC transaction manager is supported for producing an iterable log when using Persistent databases.

If mode MCO_TRANSLOG_PIPE is used, then at least one connection to a pipe must be kept open until mco_translog_stop() is called. The simplest way to satisfy this requirement is to use the same connection that calls the function mco_translog_start() to call the function mco_translog_stop(). It is possible to call mco_translog_stop() from another connection, but in this case be sure to keep the original connection open, otherwise data in the pipe may be lost, in which case the error MCO_E_TL_PIPE_LOST will be returned by mco_trans_commit() or any of mco_translog_*() functions depending on the moment the pipe was lost. This is a guard feature and should never happen. But if it occurs, then logging should be stopped and started again.

The two user-defined callback procedure elements of the mco_TL_start_data structure have the following prototypes:

 
    typedef mco_bool(*mco_TL_timer_proc)(mco_TL_flush_timer_h timer);
     
    typedef void (*mco_TL_warn_sz_proc)(mco_size_t log_size);
     

where the mco_TL_flush_timer structure is defined as follows:

 
    typedef struct mco_TL_flush_timer_
    {
        timer_unit flush_time;   /* time of most recent flush */
        timer_unit time_elapsed; /* elapsed time since last flush */
     
    } mco_TL_flush_timer_t, *mco_TL_flush_timer_h;
     

Translog Play Params

The following structure is initialized by mco_translog_play_params_init() and passed to function mco_translog_play_ex():

 
    typedef struct mco_TL_play_params_
    {
        char const                             *src_file_path;
        mco_db_h                                pipe_db;
        mco_device_t                           *pipe_device;
        mco_trans_iterator_callback_t           iteration_proc;
        void                                   *iterproc_user_ctx;
        mco_dictionary_h                        dict;
        void                                   *mem_ptr;
        mco_size_t                              mem_size;
        mco_translog_register_event_handlers_t  register_callback;
        void                                   *regevent_user_ctx;
        mco_size_t                              ddl_dict_size;
        int                                     ddl_dict_flags;
        int                                     max_classes;
        int                                     max_indexes;
     
    } mco_TL_play_params_t, *mco_TL_play_params_h;