//----------------------------------------------------------------------- // // Copyright (c) Microsoft Corporation. // //----------------------------------------------------------------------- namespace Microsoft.Isam.Esent.Interop { using System; using Microsoft.Isam.Esent.Interop.Vista; using Microsoft.Isam.Esent.Interop.Windows7; using Microsoft.Isam.Esent.Interop.Windows8; /// /// ESENT system parameters. This list is not extensive. Some parameters introduced later /// are in different classes, such as , , /// or . /// /// is usually used with , /// , /// , and /// . /// Some of these parameters are exposed with the helper classes /// and . /// /// /// /// /// public enum JET_param { /// /// This parameter indicates the relative or absolute file system path of the /// folder that will contain the checkpoint file for the instance. The path /// must be terminated with a backslash character, which indicates that the /// target path is a folder. /// SystemPath = 0, /// /// This parameter indicates the relative or absolute file system path of /// the folder or file that will contain the temporary database for the instance. /// If the path is to a folder that will contain the temporary database then it /// must be terminated with a backslash character. /// TempPath = 1, /// /// This parameter indicates the relative or absolute file system path of the /// folder that will contain the transaction logs for the instance. The path must /// be terminated with a backslash character, which indicates that the target path /// is a folder. /// LogFilePath = 2, /// /// This parameter sets the three letter prefix used for many of the files used by /// the database engine. For example, the checkpoint file is called EDB.CHK by /// default because EDB is the default base name. /// BaseName = 3, /// /// This parameter supplies an application specific string that will be added to /// any event log messages that are emitted by the database engine. This allows /// easy correlation of event log messages with the source application. By default /// the host application executable name will be used. /// EventSource = 4, /// /// This parameter reserves the requested number of session resources for use by an /// instance. A session resource directly corresponds to a JET_SESID data type. /// This setting will affect how many sessions can be used at the same time. /// MaxSessions = 5, /// /// This parameter reserves the requested number of B+ Tree resources for use by /// an instance. This setting will affect how many tables can be used at the same time. /// MaxOpenTables = 6, // PreferredMaxOpenTables(7) is obsolete /// /// This parameter reserves the requested number of cursor resources for use by an /// instance. A cursor resource directly corresponds to a JET_TABLEID data type. /// This setting will affect how many cursors can be used at the same time. A cursor /// resource cannot be shared by different sessions so this parameter must be set to /// a large enough value so that each session can use as many cursors as are required. /// MaxCursors = 8, /// /// This parameter reserves the requested number of version store pages for use by an instance. /// MaxVerPages = 9, /// /// This parameter reserves the requested number of temporary table resources for use /// by an instance. This setting will affect how many temporary tables can be used at /// the same time. If this system parameter is set to zero then no temporary database /// will be created and any activity that requires use of the temporary database will /// fail. This setting can be useful to avoid the I/O required to create the temporary /// database if it is known that it will not be used. /// /// /// The use of a temporary table also requires a cursor resource. /// MaxTemporaryTables = 10, /// /// This parameter will configure the size of the transaction log files. Each /// transaction log file is a fixed size. The size is equal to the setting of /// this system parameter in units of 1024 bytes. /// LogFileSize = 11, /// /// This parameter will configure the amount of memory used to cache log records /// before they are written to the transaction log file. The unit for this /// parameter is the sector size of the volume that holds the transaction log files. /// The sector size is almost always 512 bytes, so it is safe to assume that size /// for the unit. This parameter has an impact on performance. When the database /// engine is under heavy update load, this buffer can become full very rapidly. /// A larger cache size for the transaction log file is critical for good update /// performance under such a high load condition. The default is known to be too small /// for this case. /// Do not set this parameter to a number of buffers that is larger (in bytes) than /// half the size of a transaction log file. /// LogBuffers = 12, /// /// This parameter configures how transaction log files are managed by the database /// engine. When circular logging is off, all transaction log files that are generated /// are retained on disk until they are no longer needed because a full backup of the /// database has been performed. When circular logging is on, only transaction log files /// that are younger than the current checkpoint are retained on disk. The benefit of /// this mode is that backups are not required to retire old transaction log files. /// CircularLog = 17, /// /// This parameter controls the amount of space that is added to a database file each /// time it needs to grow to accommodate more data. The size is in database pages. /// DbExtensionSize = 18, /// /// This parameter controls the initial size of the temporary database. The size is in /// database pages. A size of zero indicates that the default size of an ordinary /// database should be used. It is often desirable for small applications to configure /// the temporary database to be as small as possible. Setting this parameter to /// SystemParameters.PageTempDBSmallest will achieve the smallest temporary database possible. /// PageTempDBMin = 19, /// /// This parameter configures 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. /// CacheSizeMax = 23, /// /// This parameter controls how aggressively database pages are flushed from the /// database page cache to minimize the amount of time it will take to recover from a /// crash. The parameter is a threshold in bytes for about how many transaction log /// files will need to be replayed after a crash. If circular logging is enabled using /// JET_param.CircularLog then this parameter will also control the approximate amount /// of transaction log files that will be retained on disk. /// CheckpointDepthMax = 24, /// /// This parameter controls the correlation interval of ESE's LRU-K page replacement /// algorithm. /// LrukCorrInterval = 25, /// /// This parameter controls the timeout interval of ESE's LRU-K page replacement /// algorithm. /// LrukTimeout = 28, /// /// This parameter controls 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. /// OutstandingIOMax = 30, /// /// This parameter controls when 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 for modified pages (Windows 2000) or for all pages (Windows XP and later). /// /// StartFlushThreshold = 31, /// /// This parameter controls when 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 for modified /// pages (Windows 2000) or for all pages (Windows XP and later). /// /// StopFlushThreshold = 32, /// /// This parameter is the master switch that controls crash recovery for an instance. /// If this parameter is set to "On" then ARIES style recovery will be used to bring all /// databases in the instance to a consistent state in the event of a process or machine /// crash. If this parameter is set to "Off" then all databases in the instance will be /// managed without the benefit of crash recovery. That is to say, that if the instance /// is not shut down cleanly using JetTerm prior to the process exiting or machine shutdown /// then the contents of all databases in that instance will be corrupted. /// Recovery = 34, /// /// This parameter controls the behavior of online defragmentation when initiated using /// and . /// EnableOnlineDefrag = 35, /// /// This parameter can be used to control the size of the database page cache at run time. /// Ordinarily, the cache will automatically tune its size as a function of database and /// machine activity levels. If the application sets this parameter to zero, then the cache /// will tune its own size in this manner. However, if the application sets this parameter /// to a non-zero value then the cache will adjust itself to that target size. /// CacheSize = 41, /// /// When this parameter is true, every database is checked at JetAttachDatabase time for /// indexes over Unicode key columns that were built using an older version of the NLS /// library in the operating system. This must be done because the database engine persists /// the sort keys generated by LCMapStringW and the value of these sort keys change from release to release. /// If a primary index is detected to be in this state then JetAttachDatabase will always fail with /// JET_err.PrimaryIndexCorrupted. /// If any secondary indexes are detected to be in this state then there are two possible outcomes. /// If AttachDatabaseGrbit.DeleteCorruptIndexes was passed to JetAttachDatabase then these indexes /// will be deleted and JET_wrnCorruptIndexDeleted will be returned from JetAttachDatabase. These /// indexes will need to be recreated by your application. If AttachDatabaseGrbit.DeleteCorruptIndexes /// was not passed to JetAttachDatabase then the call will fail with JET_errSecondaryIndexCorrupted. /// EnableIndexChecking = 45, /// /// This parameter can be used to control which event log the database engine uses for its event log /// messages. By default, all event log messages will go to the Application event log. If the registry /// key name for another event log is configured then the event log messages will go there instead. /// EventSourceKey = 49, /// /// When this parameter is true, informational event log messages that would ordinarily be generated by /// the database engine will be suppressed. /// NoInformationEvent = 50, /// /// Configures 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. /// EventLoggingLevel = 51, /// /// Delete the log files that are not matching (generation wise) during soft recovery. /// DeleteOutOfRangeLogs = 52, /// /// /// After Windows 7, it was discovered that JET_paramEnableIndexCleanup had some implementation limitations, reducing its effectiveness. /// Rather than update it to work with locale names, the functionality is removed altogether. /// /// /// Unfortunately JET_paramEnableIndexCleanup can not be ignored altogether. JET_paramEnableIndexChecking defaults to false, so if /// JET_paramEnableIndexCleanup were to be removed entirely, then by default there were would be no checks for NLS changes! /// /// /// The current behavious (when enabled) is to track the language sort versions for the indices, and when the sort version for that /// particular locale changes, the engine knows which indices are now invalid. For example, if the sort version for only "de-de" changes, /// then the "de-de" indices are invalid, but the "en-us" indices will be fine. /// /// /// Post-Windows 8: /// JET_paramEnableIndexChecking accepts JET_INDEXCHECKING (which is an enum). The values of '0' and '1' have the same meaning as before, /// but '2' is JET_IndexCheckingDeferToOpenTable, which means that the NLS up-to-date-ness is NOT checked when the database is attached. /// It is deferred to JetOpenTable(), which may now fail with JET_errPrimaryIndexCorrupted or JET_errSecondaryIndexCorrupted (which /// are NOT actual corruptions, but instead reflect an NLS sort change). /// /// /// IN SUMMARY: /// New code should explicitly set both IndexChecking and IndexCleanup to the same value. /// /// EnableIndexCleanup = 54, /// /// This parameter configures the minimum size of the database page cache. The size is in database pages. /// CacheSizeMin = 60, /// /// This parameter represents a threshold relative to that controls /// the discretionary use of version pages by the database engine. If the size of the version store exceeds /// this threshold then any information that is only used for optional background tasks, such as reclaiming /// deleted space in the database, is instead sacrificed to preserve room for transactional information. /// PreferredVerPages = 63, /// /// This parameter configures the page size for the database. The page /// size is the smallest unit of space allocation possible for a database /// file. The database page size is also very important because it sets /// the upper limit on the size of an individual record in the database. /// /// /// Only one database page size is supported per process at this time. /// This means that if you are in a single process that contains different /// applications that use the database engine then they must all agree on /// a database page size. /// DatabasePageSize = 64, /// /// This parameter disables all database engine callbacks to application provided functions. /// It is primarily intended to support the database engine utilities and is not intended to be used in your application. /// DisableCallbacks = 65, /// /// This parameter can be used to convert a JET_ERR into a string. /// This should only be used with JetGetSystemParameter. /// ErrorToString = 70, #if !MANAGEDESENT_ON_WSA // Not exposed in MSDK /// /// Configures the engine with a delegate. /// This callback may be called for the following reasons: /// , /// or . See /// for more information. This parameter cannot currently be retrieved. /// RuntimeCallback = 73, #endif /// /// This parameter controls the outcome of JetInit when the database /// engine is configured to start using transaction log files on disk /// that are of a different size than what is configured. Normally, /// will successfully recover the databases /// but will fail with /// to indicate that the log file size is misconfigured. However, when /// this parameter is set to true then the database engine will silently /// delete all the old log files, start a new set of transaction log files /// using the configured log file size. This parameter is useful when the /// application wishes to transparently change its transaction log file /// size yet still work transparently in upgrade and restore scenarios. /// CleanupMismatchedLogFiles = 77, /// /// This parameter controls what happens when an exception is thrown by the /// database engine or code that is called by the database engine. When set /// to JET_ExceptionMsgBox, any exception will be thrown to the Windows unhandled /// exception filter. This will result in the exception being handled as an /// application failure. The intent is to prevent application code from erroneously /// trying to catch and ignore an exception generated by the database engine. /// This cannot be allowed because database corruption could occur. If the application /// wishes to properly handle these exceptions then the protection can be disabled /// by setting this parameter to JET_ExceptionNone. /// ExceptionAction = 98, /// /// When this parameter is set to true then any folder that is missing in a file system path in use by /// the database engine will be silently created. Otherwise, the operation that uses the missing file system /// path will fail with JET_err.InvalidPath. /// CreatePathIfNotExist = 100, /// /// When this parameter is true then only one database is allowed to /// be opened using JetOpenDatabase by a given session at one time. /// The temporary database is excluded from this restriction. /// OneDatabasePerSession = 102, /// /// This parameter controls the maximum number of instances that can be created in a single process. /// MaxInstances = 104, /// /// This parameter controls the number of background cleanup work items that /// can be queued to the database engine thread pool at any one time. /// VersionStoreTaskQueueMax = 105, /// /// This parameter controls whether perfmon counters should be enabled or not. /// By default, perfmon counters are enabled, but there is memory overhead for enabling /// them. /// DisablePerfmon = 107, // If you can not find the parameter you are expecting here, then perhaps it is // in a later version of the API, in VistaParam, Windows7Param, etc. } }