次の方法で共有

JET_ERRINFOBASIC_W API

  • [アーティクル]

UPDATE: 8 November 2011, Thom Randolph - MSFT.

The following API reference information in this post applies to the Windows Extensible Storage Engine (ESE) APIs, that are available on MSDN at the following URL:

https://msdn.microsoft.com/en-us/library/windows/desktop/gg269259(v=EXCHG.10).aspx

The ESE APIs that ship in Windows should not be used with Exchange mailbox or public folder databases.

 

The JET_ERRINFOBASIC_W API includes a group of constants, a structure, and a function, as defined in the header file Esent.h. These are described in this blog post.

Note: This documentation is based on a preliminary release of the Extensible Storage Engine. This information is subject to change.

JET_ERRCAT Constants

The JET_ERRCAT group of constants describes higher-level classifications or categories of errors. This group of constants enables applications to define default treatment for a classification of errors, rather than handling each error case individually. It also ensures that the application does not have to handle new error conditions that are included in existing classifications.

The JET_ERRCAT constants are arranged in a specific hierarchy of conditions and subconditions, as follows:

|--- Error
|--- Operation(al)
| |--- Fatal
| |--- IO
| |--- Resource
| |--- Memory
| |--- Quota
| |--- Disk
|
|--- Data
| |--- Corruption
| |--- Inconsistent
| |--- Fragmentation
|
|--- Api
|--- Usage
|--- State

The following table lists the JET_ERRCAT constants and provides a description and recovery information, as applicable.

Constant/value

Description

Recovery

JET_errcatUnknown 0

An invalid error category.

N/A.

JET_errcatError 1

The top level category (no errors should be of this class).

See the specific error constants.

JET_errcatOperation 2

Represents errors that can happen at any time due to uncontrollable conditions and are often temporary. See subcategories if specified

Retry and if the error continues, inform the operator.

JET_errcatFatal 3

Represents fatal errors that, when they occur, create a risk that ESE cannot continue in a safe (often transactional) way , and data may become corrupted.

Restart the instance or process. If the problem persists, inform the operator.

JET_errcatIO 4

Represents IO errors, which come from the operating system, and are out of ESE's control. This type of error may be temporary.

Retry, and if the error continues, ask the operator to check the disk.

JET_errcatResource 5

Represents a category of errors related to lack of resource conditions.

See subcategories.

JET_errcatMemory 6

Represents an error caused by lack of memory.

Retry after a period of time, free up memory, or quit.

JET_errcatQuota 7

Certain "specialty" resources are in pools of a certain size, making it easier to detect leaks of these resources.

The application should Assert() to detect these issues during development . However, in retail code , the application should treat this as a memory error.

JET_errcatDisk 8

Represents an error caused by lack of disk space.

Retry later to determine whether more disk space is available, or ask the operator to free some disk space.

JET_errcatData 9

Represents a top-level category for errors related to data.

See subcategories.

JET_errcatCorruption 10

Represents a corruption issue, which is often permanent without corrective action.

Restore from backup by using the ESE utilities repair operation (this operation restores only the data that is left/lossy). Also when the recovery(JetInit) method is used, recovery can be performed by allowing data loss (for more information, see JET_bitReplayIgnoreLostLogs.

JET_errcatInconsistent 11

Represents an error in which the database and/or log files are in a state that is inconsistent and cannot be reconciled. This error might be caused by application/administrator mishandling.

Restore from backup by using the ESE utilities repair operation (which only restores the data that is left/lossy). Also in the case of the recovery(JetInit) operation, recovery can be performed by allowing data loss (for more information, see JET_bitReplayIgnoreLostLogs.

JET_errcatFragmentation 12

Represents a class of errors in which some persisted internal resource ran out.

For database errors, offline defragmentation will fix the problem. For the log files, first recover all attached databases to a clean shutdown , and then delete all the log files and the checkpoint.

JET_errcatApi 13

See subcategories.

See subcategories.

JET_errcatUsage 14

Represents a usage error. The client code did not pass the correct arguments to the JET API. This error will persist with retry.

Client code should use the Assert() method to ensure that this class of errors is not returned. so issues can be caught during development. In retail , the application should notify the operator about the error.

JET_errcatState 15

Represents a class of messages that the API can return to describe the state of the database. For example, the JetSeek() method might return JET_errRecordNotFound when the requested record was not found.

Varies based on the API.

JET_errcatObsolete 16

Represents errors that are from a previous version of the engine. These errors should not be returned by the current engine.

Unknown.

JET_errcatMax 17

A constant that indicates the end of the enumeration.

N/A.

Requirements

Client

Requires Windows 8.

Server

Requires Windows 8 Server.

Header

Declared in Esent.h.

JET_ERRINFOBASIC_W Structure

The JET_ERRINFOBASIC_W structure defines the data that is returned from the JetGetErrorInfo() method when the JET_ErrorInfoSpecificErr InfoLevel [LG1] is passed in.

typedef struct {
unsigned long cbStruct;
JET_ERR errValue;
JET_ERRCAT errcatMostSpecific;
unsigned char rgCategoricalHierarchy[8];
unsigned long lSourceLine;
WCHAR rgszSourceFile[64];
} JET_ERRINFOBASIC_W;

Members

cbStructThe size of the structure, in bytes. It must be set to sizeof( JET_ERRINFOBASIC ) .

errValueThe error value that was evaluated, as passed in for the pvResult argument to JetGetErrorInfo() .

errcatMostSpecificThe lowest-level JET_errcat constant that is associated with the error; that is, the leaf-level category in the category hierarchy documented in JET_ERRCAT.

rgCategoricalHierarchy[8] The hierarchy of error categories that is associated with the error. Position 0 is the highest level in the hierarchy of JET_ERRCAT, and the rest are subcategories until the most specific category is set, after which all categories are JET_errcatUnknown.

lSourceLineReserved.

rgszSourceFile[64] Reserved.

Requirements

Client

Requires 8.

Server

Requires 8 Server.

Header

Declared in Esent.h.

JetGetErrorInfoW Function

The JetGetErrorInfoW function BAS_ of the database engine.

JET_ERR JET_API JetGetErrorInfoW(
_In_opt_ void * pvContext,
_Out_writes_bytes_( cbMax ) void * pvResult,
_In_ unsigned long cbMax,
_In_ unsigned long InfoLevel,
_In_ JET_GRBIT grbit );

Parameters

pvContextThe context or error value for which the extended error information is needed. The value passed in depends on the InfoLevel parameter value.

pvResultA pointer to a buffer that will receive the information. The type of the buffer depends on the InfoLevel parameter value. The caller must be configured to align the buffer appropriately.

cbMaxThe maximum size of the pvResult structure that is passed in.

InfoLevelThe type of information that will be retrieved for the error info/context is specified by the pvContext parameter. The format of the data that is stored in pvResult is dependent on InfoLevel.

The following table lists the possible values for this parameter.

Value

Meaning

JET_ErrorInfoSpecificErr

pvContext is interpreted as a JET_ERR/error code, pvResult is interpreted as a JET_ERRINFOBASIC_W, and the fields of the JET_ERRINFOBASIC_W structure are filled in appropriately.

grbit
Reserved.

Return Value

This function returns the JET_ERR data type with one of the return codes listed in the following table. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.

Return code

Description

JET_errSuccess

The operation completed successfully.

JET_errInvalidParameter

One of the parameters provided contains an unexpected value or contains a value that does not make sense when combined with the value of another parameter.

This can happen for JetGetErrorInfo when the following occurs:

  • The specified InfoLevel parameter value is invalid.
  • The specified grbit value is invalid.
  • The specified pvResult parameter buffer’s cbMax value is less than the required size for output of this InfoLevel parameter.
  • For InfoLevel = JET_ErrorInfoSpecificErr, the JET_ERR value passed in is unknown to the engine.

JET_errDisabledFunctionality

If this SKU of windows doesn’t support this function, this error will be returned.

On success, the output buffer that is appropriate for the requested error context/value will be set to the extended error info requested.

On failure, the state of the output buffers will be undefined.

Remarks

The JET_ERRINFOBASIC_W function and JET_ERRCAT group of constants contain documentation about the extended error information that is returned for InfoLevel = JET_ErrorInfoSpecificErr.

Requirements

Client

Requires Windows 8.

Server

Requires Windows 8 Server.

Header

Declared in Esent.h.

Library

Use ESENT.lib.

DLL

Requires ESENT.dll.

Unicode

Note: Only the JetGetErrorInfoW (Unicode) is implemented. This API does not have an A (ANSI) version.

Comments

  • Anonymous
    November 08, 2011
    Please note that this material concerns the Extensible Storage Engine (ESE) that ships as part of Windows. The above APIs are not for use with Exchange mailbox or public folder databases.