JetCreateInstance2 Function

Applies to: Windows | Windows Server

JetCreateInstance2 Function

The JetCreateInstance2 function is used to allocate a new instance of the database engine for use in a single process, with a display name specified.

Windows XP:  JetCreateInstance2 is introduced in Windows XP.

    JET_ERR JET_API JetCreateInstance2(
      __out         JET_INSTANCE* pinstance,
      __in_opt      const tchar* szInstanceName,
      __in_opt      const tchar* szDisplayName,
      __in          JET_GRBIT grbit
    );

Parameters

pinstance

The output buffer that will receive the newly created instance.

szInstanceName

Specifies 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.

szDisplayName

A display name for the instance to be created. When this parameter is not present, its value is presumed to be NULL.

grbit

Reserved for future use. When this parameter is not present, its value is presumed to be zero.

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 parameter 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 parameter 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 for each instance (like JET_paramSystemPath or JET_paramLogFilePath) so most likely, each of these will need to be set.

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

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 Return Values for more information).

Requirements

See Also

JET_ERR
JET_INSTANCE
JetCreateInstance
JetEnableMultiInstance
JetGetInstanceInfo
JetInit
JetInit2
JetOSSnapshotFreeze
JetSetSystemParameter
JetTerm
JetTerm2