//----------------------------------------------------------------------- // // Copyright (c) Microsoft Corporation. // //----------------------------------------------------------------------- namespace Microsoft.Isam.Esent.Interop { using Microsoft.Isam.Esent.Interop.Vista; using Microsoft.Isam.Esent.Interop.Windows7; /// /// This class provides static properties to set and get /// global ESENT system parameters. /// public static partial class SystemParameters { /// /// Gets or sets the maximum size of the database page cache. The size /// is in database pages. If this parameter is left to its default value, then the /// maximum size of the cache will be set to the size of physical memory when JetInit /// is called. /// public static int CacheSizeMax { get { return GetIntegerParameter(JET_param.CacheSizeMax); } set { SetIntegerParameter(JET_param.CacheSizeMax, value); } } /// /// Gets or sets the size of the database cache in pages. By default the /// database cache will automatically tune its size, setting this property /// to a non-zero value will cause the cache to adjust itself to the target /// size. /// public static int CacheSize { get { return GetIntegerParameter(JET_param.CacheSize); } set { SetIntegerParameter(JET_param.CacheSize, value); } } /// /// Gets or sets the size of the database pages, in bytes. /// public static int DatabasePageSize { get { return GetIntegerParameter(JET_param.DatabasePageSize); } set { SetIntegerParameter(JET_param.DatabasePageSize, value); } } /// /// Gets or sets the minimum size of the database page cache, in database pages. /// public static int CacheSizeMin { get { return GetIntegerParameter(JET_param.CacheSizeMin); } set { SetIntegerParameter(JET_param.CacheSizeMin, value); } } /// /// Gets or sets how many database file I/Os can be queued /// per-disk in the host operating system at one time. A larger value /// for this parameter can significantly help the performance of a large /// database application. /// public static int OutstandingIOMax { get { return GetIntegerParameter(JET_param.OutstandingIOMax); } set { SetIntegerParameter(JET_param.OutstandingIOMax, value); } } /// /// Gets or sets the threshold at which the database page cache begins evicting pages from the /// cache to make room for pages that are not cached. When the number of page buffers in the cache /// drops below this threshold then a background process will be started to replenish that pool /// of available buffers. This threshold is always relative to the maximum cache size as set by /// JET_paramCacheSizeMax. This threshold must also always be less than the stop threshold as /// set by JET_paramStopFlushThreshold. /// /// The distance height of the start threshold will determine the response time that the database /// page cache must have to produce available buffers before the application needs them. A high /// start threshold will give the background process more time to react. However, a high start /// threshold implies a higher stop threshold and that will reduce the effective size of the /// database page cache. /// /// public static int StartFlushThreshold { get { return GetIntegerParameter(JET_param.StartFlushThreshold); } set { SetIntegerParameter(JET_param.StartFlushThreshold, value); } } /// /// Gets or sets the threshold at which the database page cache ends evicting pages from the cache to make /// room for pages that are not cached. When the number of page buffers in the cache rises above /// this threshold then the background process that was started to replenish that pool of available /// buffers is stopped. This threshold is always relative to the maximum cache size as set by /// JET_paramCacheSizeMax. This threshold must also always be greater than the start threshold /// as set by JET_paramStartFlushThreshold. /// /// The distance between the start threshold and the stop threshold affects the efficiency with /// which database pages are flushed by the background process. A larger gap will make it /// more likely that writes to neighboring pages may be combined. However, a high stop /// threshold will reduce the effective size of the database page cache. /// /// public static int StopFlushThreshold { get { return GetIntegerParameter(JET_param.StopFlushThreshold); } set { SetIntegerParameter(JET_param.StopFlushThreshold, value); } } /// /// Gets or sets the maximum number of instances that can be created. /// public static int MaxInstances { get { return GetIntegerParameter(JET_param.MaxInstances); } set { SetIntegerParameter(JET_param.MaxInstances, value); } } /// /// Gets or sets the detail level of eventlog messages that are emitted /// to the eventlog by the database engine. Higher numbers will result /// in more detailed eventlog messages. /// public static int EventLoggingLevel { get { return GetIntegerParameter(JET_param.EventLoggingLevel); } set { SetIntegerParameter(JET_param.EventLoggingLevel, value); } } /// /// Gets the maximum key size. This depends on the Esent version and database /// page size. /// public static int KeyMost { get { if (EsentVersion.SupportsVistaFeatures) { return GetIntegerParameter(VistaParam.KeyMost); } // All pre-Vista versions of Esent have 255 byte keys return 255; } } /// /// Gets the maximum number of components in a sort or index key. /// public static int ColumnsKeyMost { get { return Api.Impl.Capabilities.ColumnsKeyMost; } } /// /// Gets the maximum size of a bookmark. . /// public static int BookmarkMost { get { // This correctly returns 256 on pre-Vista systems return KeyMost + 1; } } /// /// Gets the lv chunks size. This depends on the database page size. /// public static int LVChunkSizeMost { get { if (EsentVersion.SupportsWindows7Features) { return GetIntegerParameter(Windows7Param.LVChunkSizeMost); } // Can't retrieve the size directly, determine it from the database page size const int ColumnLvPageOverhead = 82; return GetIntegerParameter(JET_param.DatabasePageSize) - ColumnLvPageOverhead; } } /// /// Gets or sets a value specifying the default values for the /// entire set of system parameters. When this parameter is set to /// a specific configuration, all system parameter values are reset /// to their default values for that configuration. If the /// configuration is set for a specific instance then global system /// parameters will not be reset to their default values. /// Small Configuration (0): The database engine is optimized for memory use. /// Legacy Configuration (1): The database engine has its traditional defaults. /// /// Supported on Windows Vista and up. Ignored on Windows XP and /// Windows Server 2003. /// /// public static int Configuration { get { if (EsentVersion.SupportsVistaFeatures) { return GetIntegerParameter(VistaParam.Configuration); } // return the legacy configuration value return 1; } set { if (EsentVersion.SupportsVistaFeatures) { SetIntegerParameter(VistaParam.Configuration, value); } } } /// /// Gets or sets a value indicating whether the database engine accepts /// or rejects changes to a subset of the system parameters. This /// parameter is used in conjunction with to /// prevent some system parameters from being set away from the selected /// configuration's defaults. /// /// Supported on Windows Vista and up. Ignored on Windows XP and /// Windows Server 2003. /// /// public static bool EnableAdvanced { get { if (EsentVersion.SupportsVistaFeatures) { return GetBoolParameter(VistaParam.EnableAdvanced); } // older versions always allow advanced settings return true; } set { if (EsentVersion.SupportsVistaFeatures) { SetBoolParameter(VistaParam.EnableAdvanced, value); } } } /// /// Gets or sets backwards compatibility with the file naming conventions of earlier releases of the database engine. /// public static int LegacyFileNames { get { if (EsentVersion.SupportsVistaFeatures) { return GetIntegerParameter(VistaParam.LegacyFileNames); } // return the legacy LegacyFileNames value return 1; } set { if (EsentVersion.SupportsVistaFeatures) { SetIntegerParameter(VistaParam.LegacyFileNames, value); } } } /// /// Gets or sets the value encoding what to do with exceptions generated within JET. /// public static JET_ExceptionAction ExceptionAction { get { return (JET_ExceptionAction)GetIntegerParameter(JET_param.ExceptionAction); } set { SetIntegerParameter(JET_param.ExceptionAction, (int)value); } } /// /// Gets or sets a value indicating whether the database engine should /// use the OS file cache for all managed files. /// public static bool EnableFileCache { get { if (EsentVersion.SupportsVistaFeatures) { return GetBoolParameter(VistaParam.EnableFileCache); } // Pre-Vista versions of do not implement this. return false; } set { if (EsentVersion.SupportsVistaFeatures) { SetBoolParameter(VistaParam.EnableFileCache, value); } } } /// /// Gets or sets a value indicating whether the database engine should /// use memory mapped file I/O for database files. /// public static bool EnableViewCache { get { if (EsentVersion.SupportsVistaFeatures) { return GetBoolParameter(VistaParam.EnableViewCache); } // Pre-Vista versions of do not implement this. return false; } set { if (EsentVersion.SupportsVistaFeatures) { SetBoolParameter(VistaParam.EnableViewCache, value); } } } /// /// Set a system parameter which is a string. /// /// The parameter to set. /// The value to set. private static void SetStringParameter(JET_param param, string value) { Api.JetSetSystemParameter(JET_INSTANCE.Nil, JET_SESID.Nil, param, 0, value); } /// /// Get a system parameter which is a string. /// /// The parameter to get. /// The value of the parameter. private static string GetStringParameter(JET_param param) { int ignored = 0; string value; Api.JetGetSystemParameter(JET_INSTANCE.Nil, JET_SESID.Nil, param, ref ignored, out value, 1024); return value; } /// /// Set a system parameter which is an integer. /// /// The parameter to set. /// The value to set. private static void SetIntegerParameter(JET_param param, int value) { Api.JetSetSystemParameter(JET_INSTANCE.Nil, JET_SESID.Nil, param, value, null); } /// /// Get a system parameter which is an integer. /// /// The parameter to get. /// The value of the parameter. private static int GetIntegerParameter(JET_param param) { int value = 0; string ignored; Api.JetGetSystemParameter(JET_INSTANCE.Nil, JET_SESID.Nil, param, ref value, out ignored, 0); return value; } /// /// Set a system parameter which is a boolean. /// /// The parameter to set. /// The value to set. private static void SetBoolParameter(JET_param param, bool value) { int setting = value ? 1 : 0; Api.JetSetSystemParameter(JET_INSTANCE.Nil, JET_SESID.Nil, param, setting, null); } /// /// Get a system parameter which is a boolean. /// /// The parameter to get. /// The value of the parameter. private static bool GetBoolParameter(JET_param param) { int value = 0; string ignored; Api.JetGetSystemParameter(JET_INSTANCE.Nil, JET_SESID.Nil, param, ref value, out ignored, 0); return value != 0; } } }