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