JetCreateInstance Function

Applies to: Windows | Windows Server

JetCreateInstance Function

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.

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:

• A call to JetCreateInstance2 which will allocate and name the instance.

• Multiple calls to JetSetSystemParameter for that instance in order to set different system parameters. Note that some system parameters need to be unique per instance (like JET_paramSystemPath or JET_paramLogFilePath) so most likely one will need to set each of those.

• Start the instance using JetInit or JetInit2. In order to terminate and/or free an instance, JetTerm, JetTerm2 needs to be used.

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

See Also

Extensible Storage Engine Files
JET_ERR
JET_INSTANCE
JetCreateInstance2
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2