# stores.conf

This file defines the locations, either store files, mstore, or a database, where the EMS server will store messages or metadata (if the default `$sys.meta` definition is overridden). You can configure one or many stores in the `stores.conf` file.

Each store configured is either a file-based store, mstore, or a database store. File-based store and mstore parameters are described here. Database store parameters are described in Database Stores.

The format of the file is:

    [store_name] # mandatory -- square brackets included
      type=file
      file=name
      file_destination_defrag=size
      [file_crc=true|false]
      [file_minimum=value]
      [file_truncate=value]
      [mode=async|sync]
      [processor_id=processor id]
    [store_name]
      type=mstore
      file=name
      [mode=async|sync]
      [mstore_truncate=value]
      [processor_id=processor-id]
      [scan_iter_interval=time msec|sec|min|hour|day]
      [scan_target_interval=time msec|sec|min|hour|day]

Parameter Name | Description
--- | ---
`[``store_name``]` | [store_name] is the name that identifies this store file configuration. Note that the square brackets [ ] DO NOT indicate that the store_name is an option; they must be included around the name.
`type` | Identifies the store type. This parameter is required for all store types. The type can be: `file` — for file-based stores. `mstore` — for mstores. `dbstore` — for database stores. For information about the parameters used to configure database stores, see Configuration in stores.conf.
`file` | The filename that will be used when creating this store file. This parameter is required for both `file` and `mstore` types. For example, `mystore.db`. The location for this file can be specified using absolute or relative path names. If no path separators are present, the file will be saved in the location specified by the `store` parameter in the `tibemsd.conf` file, if any is specified there.
`mode` | The mode determines whether messages will be written to the store synchronously or asynchronously. Mode is either: `async` — the server stores messages in this file using asynchronous I/O calls. `sync` — the server stores messages in this file using synchronous I/O calls. When absent, the default for file-based stores is `async`. The default mode for mstores is `sync`.
`processor_id` | When specified, the EMS Server binds the storage thread of this store to the specified processor. Do not use this parameter if the default behavior provides sufficient throughput. If no processor ID is specified for a store, the store is not bound to a specific processor. Specify the processor-id as an integer. This parameter has similar requirements, limitations, and benefits as the `processor_ids` parameter in `tibemsd.conf`. For use guidelines, see Performance Tuning.
File-Based Store Parameters
`file_destination_defrag` | This parameter specifies a maximum batch size used by the destination defrag feature. Destination defrag improves store file performance by maintaining contiguous space for new messages, while improving server read performance. When persistent pending messages begin to accumulate in a queue, messages are grouped into a batch that is re-written to disk. Messages are written close together, allowing the server to read them more efficiently when later delivering the messages to consumers. Specify size in `bytes`, `KB`, `MB` or `GB`. The size should be set to a size that is known to be acceptable for the disk where the store points to. For instance, if it is set to 2MB, your disk must be able to write a 2MB batch efficiently. If `file_destination_defrag` is zero or absent, the destination defrag feature is disabled.
`file_crc` | This parameter specifies whether the EMS server uses CRC to validate data integrity when reading the store files. When this parameter is absent, the default is `true`.
`file_minimum` | This parameter preallocates disk space for the store file. Preallocation occurs when the server first creates the store file. You can specify units of `MB` or `GB`. Zero is a special value, which specifies no minimum preallocation. Otherwise, the value specified must be greater than `4MB`. For example:
      file_minimum = 32MB
If `file_truncate` is set to true, the `file_minimum` parameter prevents the EMS server from truncating the file below the set size. When this parameter is absent, there is no default minimum preallocation.
`file_truncate` | Determines whether the EMS server will occasionally attempt to truncate the store file, relinquishing unused disk space. When `file_truncate` is `true`, the store file can be truncated, but not below the size set in `file_minimum`. When this parameter is absent, the default is `true`, and the server will periodically attempt to truncate the store file.
mstore Parameters
`scan_iter_interval` | Determines the length of time between each interval of the store scan. The EMS server begins scanning a new section of the mstore at the time interval specified here. Specify time in units of `msec`, `sec`, `min`, `hour` or `day` to describe the time value as being in milliseconds, seconds, minutes, hours, or days, respectively. For example:
      scan_iter_interval=100msec
By default, the mstore examines stores every 10 seconds. For more information, see Understanding mstore Intervals.
`scan_target_interval` | Controls the approximate length of time taken to complete a full scan of the mstore. Specify time in units of msec, sec, min, hour or day to describe the time value as being in milliseconds, seconds, minutes, hours, or days, respectively. For example:
      scan_target_interval=12hour
By default, the scan interval is 24 hours. For more information, see Understanding mstore Intervals.
`mstore_truncate` | When `mstore_truncate` is `true`, the EMS server occasionally attempts to truncate the mstore files, relinquishing unused disk space. Enabling `mstore_truncate` may increase the fragmentation of the store files. When this parameter is absent, the default is `false`. This feature is not available by default. Before using it, you must run the `tibemsdbconvert` tool with option `-version` `8.3` on the required mstore files.

## Example

    [my_sync]
      type = file
      file = /var/local/tibems/my_sync.db
      file_destination_defrag=2MB
      file_crc = true
      file_minimum = 10MB
      file_truncate = true
      mode = sync

## Example

    [mstore1]
      type = mstore
      file = /var/local/tibems/mstore1.db
      mode = async
      mstore_truncate = true
      scan_iter_interval=100msec
      scan_target_interval=12hour

Copyright © Cloud Software Group, Inc. All rights reserved.