mirror of
https://github.com/MichaelGrafnetter/DSInternals
synced 2024-12-11 08:57:17 +00:00
441 lines
23 KiB
C#
Vendored
441 lines
23 KiB
C#
Vendored
//-----------------------------------------------------------------------
|
|
// <copyright file="jet_param.cs" company="Microsoft Corporation">
|
|
// Copyright (c) Microsoft Corporation.
|
|
// </copyright>
|
|
//-----------------------------------------------------------------------
|
|
|
|
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;
|
|
|
|
/// <summary>
|
|
/// ESENT system parameters. This list is not extensive. Some parameters introduced later
|
|
/// are in different classes, such as <see cref="VistaParam"/>, <see cref="Windows7Param"/>,
|
|
/// or <see cref="Windows8Param"/>.
|
|
/// <para>
|
|
/// <see cref="JET_param"/> is usually used with <see cref="Api.JetSetSystemParameter(JET_INSTANCE,JET_SESID,JET_param,int,string)"/>,
|
|
/// <see cref="Api.JetSetSystemParameter(JET_INSTANCE,JET_SESID,JET_param,IntPtr,string)"/>,
|
|
/// <see cref="Api.JetGetSystemParameter(JET_INSTANCE,JET_SESID,JET_param,ref int, out string, int)"/>, and
|
|
/// <see cref="Api.JetGetSystemParameter(JET_INSTANCE,JET_SESID,JET_param,ref IntPtr, out string, int)"/>.
|
|
/// Some of these parameters are exposed with the helper classes <see cref="SystemParameters"/>
|
|
/// and <see cref="InstanceParameters"/>.
|
|
/// </para>
|
|
/// </summary>
|
|
/// <seealso cref="VistaParam"/>
|
|
/// <seealso cref="Windows7Param"/>
|
|
/// <seealso cref="Windows8Param"/>
|
|
public enum JET_param
|
|
{
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
SystemPath = 0,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
TempPath = 1,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
LogFilePath = 2,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
BaseName = 3,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
EventSource = 4,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
MaxSessions = 5,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
MaxOpenTables = 6,
|
|
|
|
// PreferredMaxOpenTables(7) is obsolete
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
MaxCursors = 8,
|
|
|
|
/// <summary>
|
|
/// This parameter reserves the requested number of version store pages for use by an instance.
|
|
/// </summary>
|
|
MaxVerPages = 9,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The use of a temporary table also requires a cursor resource.
|
|
/// </remarks>
|
|
MaxTemporaryTables = 10,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
LogFileSize = 11,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
LogBuffers = 12,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
CircularLog = 17,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
DbExtensionSize = 18,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
PageTempDBMin = 19,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
CacheSizeMax = 23,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
CheckpointDepthMax = 24,
|
|
|
|
/// <summary>
|
|
/// This parameter controls the correlation interval of ESE's LRU-K page replacement
|
|
/// algorithm.
|
|
/// </summary>
|
|
LrukCorrInterval = 25,
|
|
|
|
/// <summary>
|
|
/// This parameter controls the timeout interval of ESE's LRU-K page replacement
|
|
/// algorithm.
|
|
/// </summary>
|
|
LrukTimeout = 28,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
OutstandingIOMax = 30,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// <para>
|
|
/// 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).
|
|
/// </para>
|
|
/// </summary>
|
|
StartFlushThreshold = 31,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// <para>
|
|
/// 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).
|
|
/// </para>
|
|
/// </summary>
|
|
StopFlushThreshold = 32,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
Recovery = 34,
|
|
|
|
/// <summary>
|
|
/// This parameter controls the behavior of online defragmentation when initiated using
|
|
/// <see cref="Api.JetDefragment"/> and <see cref="Api.JetDefragment2"/>.
|
|
/// </summary>
|
|
EnableOnlineDefrag = 35,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
CacheSize = 41,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
EnableIndexChecking = 45,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
EventSourceKey = 49,
|
|
|
|
/// <summary>
|
|
/// When this parameter is true, informational event log messages that would ordinarily be generated by
|
|
/// the database engine will be suppressed.
|
|
/// </summary>
|
|
NoInformationEvent = 50,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
EventLoggingLevel = 51,
|
|
|
|
/// <summary>
|
|
/// Delete the log files that are not matching (generation wise) during soft recovery.
|
|
/// </summary>
|
|
DeleteOutOfRangeLogs = 52,
|
|
|
|
/// <summary>
|
|
/// <para>
|
|
/// 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.
|
|
/// </para>
|
|
/// <para>
|
|
/// 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!
|
|
/// </para>
|
|
/// <para>
|
|
/// 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.
|
|
/// </para>
|
|
/// <para>
|
|
/// 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).
|
|
/// </para>
|
|
/// <para>
|
|
/// IN SUMMARY:
|
|
/// New code should explicitly set both IndexChecking and IndexCleanup to the same value.
|
|
/// </para>
|
|
/// </summary>
|
|
EnableIndexCleanup = 54,
|
|
|
|
/// <summary>
|
|
/// This parameter configures the minimum size of the database page cache. The size is in database pages.
|
|
/// </summary>
|
|
CacheSizeMin = 60,
|
|
|
|
/// <summary>
|
|
/// This parameter represents a threshold relative to <see cref="JET_param.MaxVerPages"/> 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.
|
|
/// </summary>
|
|
PreferredVerPages = 63,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// 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.
|
|
/// </remarks>
|
|
DatabasePageSize = 64,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
DisableCallbacks = 65,
|
|
|
|
/// <summary>
|
|
/// This parameter can be used to convert a JET_ERR into a string.
|
|
/// This should only be used with JetGetSystemParameter.
|
|
/// </summary>
|
|
ErrorToString = 70,
|
|
|
|
#if !MANAGEDESENT_ON_WSA // Not exposed in MSDK
|
|
/// <summary>
|
|
/// Configures the engine with a <see cref="JET_CALLBACK"/> delegate.
|
|
/// This callback may be called for the following reasons:
|
|
/// <see cref="JET_cbtyp.FreeCursorLS"/>, <see cref="JET_cbtyp.FreeTableLS"/>
|
|
/// or <see cref="JET_cbtyp.Null"/>. See <see cref="Api.JetSetLS"/>
|
|
/// for more information. This parameter cannot currently be retrieved.
|
|
/// </summary>
|
|
RuntimeCallback = 73,
|
|
#endif
|
|
|
|
/// <summary>
|
|
/// 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,
|
|
/// <see cref="Api.JetInit"/> will successfully recover the databases
|
|
/// but will fail with <see cref="JET_err.LogFileSizeMismatchDatabasesConsistent"/>
|
|
/// 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.
|
|
/// </summary>
|
|
CleanupMismatchedLogFiles = 77,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
ExceptionAction = 98,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
CreatePathIfNotExist = 100,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
OneDatabasePerSession = 102,
|
|
|
|
/// <summary>
|
|
/// This parameter controls the maximum number of instances that can be created in a single process.
|
|
/// </summary>
|
|
MaxInstances = 104,
|
|
|
|
/// <summary>
|
|
/// This parameter controls the number of background cleanup work items that
|
|
/// can be queued to the database engine thread pool at any one time.
|
|
/// </summary>
|
|
VersionStoreTaskQueueMax = 105,
|
|
|
|
/// <summary>
|
|
/// 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.
|
|
/// </summary>
|
|
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.
|
|
}
|
|
}
|