Export (0) Print
Expand All
Expand Minimize

JetCreateInstance Function

Windows

Last modified: January 09, 2012

Applies to: Windows | Windows Server

The JetCreateInstance function allocates a new instance of the database engine for use in a single process.

Windows XP:   JetCreateInstance is introduced in Windows XP.

JET_ERR JET_API JetCreateInstance(
  __out         JET_INSTANCE* pinstance,
  __in_opt      const tchar* szInstanceName
);

Parameters

pinstance

The output buffer that receives the newly-created instance.

szInstanceName

A unique string identifier for the instance to be created. This string must be unique within a given process hosting the database engine.

Note   A NULL value is treated as a valid string identifier for an instance. Only one instance may have a NULL string identifier.

Return Value

This function returns the JET_ERR datatype with one of the following return codes. 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_errInstanceNameInUse

The specified instance name is already in use for this process.

JET_errInvalidParameter

One of the parameters provided contained an unexpected value or contained a value that did not make sense when combined with the value of another parameter. This can happen for JetCreateInstance when pinstance is NULL.

JET_errRunningInOneInstanceMode

The operation failed because it cannot be used when the database engine is operating in single instance mode (Windows 2000 compatibility mode).

JET_errTooManyInstances

A new instance could not be created because the maximum number of instances has been reached. The maximum number of supported instances is configured using JetSetSystemParameter using JET_paramMaxInstances.

On success, a new instance will be allocated and the identifier for it will be returned. At this point, all system parameters for the instance will have the values of the global default system parameters. Once an instance will be allocated, it needs to be terminated and/or freed later on.

On failure, an error representing the cause of failure will be returned and no instance will be allocated.

Remarks

An instance must be initialized with a call to JetInit before it can be used by anything other than JetSetSystemParameter.

An instance is destroyed by a call to the JetTerm function, even if that instance was never initialized using JetInit. The maximum number of instances that may be created at any one time is controlled by JET_paramMaxInstances, which can be configured by a call to JetSetSystemParameter. An instance is the unit of recoverability for the database engine. It controls the life cycle of all the files used to protect the integrity of the data in a set of database files. These files include the checkpoint file and the transaction log files.

If the function succeeds, the database engine will automatically be changed to multi-instance mode as a side effect of this call. If the application desires to allow only one instance in the process then JetInit should be used to start the database engine in Windows 2000 compatibility mode.

If present, the szDisplayName will be used to identify the instance in places like Event Log or towards other callers like backup applications (through functions like JetGetInstanceInfo or JetOSSnapshotFreeze). If the display name is not provided, the unique szInstanceName will be used instead if present, otherwise an empty string will be returned. If the engine did not have the running mode set, after this call, it will be set to multi-instance mode.

The typical start-up sequence for a process potentially running multiple Jet instances would be:

If this is the first instance to be started, there are a number of additional steps which will be executed during this call in order to make basic system initialization and configuration. A number of those steps might result in specific errors starting with JET_errOutOfMemory but others as well (see errors above).

Requirements

Client

Requires Windows Vista or Windows XP.

Server

Requires Windows Server 2008 or Windows Server 2003.

Header

Declared in Esent.h.

Library

Use ESENT.lib.

DLL

Requires ESENT.dll.

Unicode

Implemented as JetCreateInstanceW (Unicode) and JetCreateInstanceA (ANSI).

See Also

Show:
© 2014 Microsoft