LocalDBCreateInstance Function

Applies to: SQL Server

Creates a new SQL Server Express LocalDB instance.

Header file: msoledbsql.h

Syntax

HRESULT LocalDBCreateInstance(  
           PCWSTR wszVersion,  
           PCWSTR pInstanceName,   
           DWORD dwFlags   
);  

Parameters

wszVersion
[Input] The LocalDB version, for example 11.0 or 11.0.1094.2.

pInstanceName
[Input] The name for the LocalDB instance to create.

dwFlags
[Input] Reserved for future use. Currently should be set to 0.

Returns

S_OK
The function succeeded.

LOCALDB_ERROR_NOT_INSTALLED
SQL Server Express LocalDB is not installed on the computer.

LOCALDB_ERROR_INVALID_PARAMETER
One or more specified input parameters are invalid.

LOCALDB_ERROR_INVALID_INSTANCE_NAME
The specified instance name is invalid.

LOCALDB_ERROR_INSTANCE_FOLDER_PATH_TOO_LONG
The path where the instance should be stored is longer than MAX_PATH.

LOCALDB_ERROR_INSTANCE_EXISTS_WITH_LOWER_VERSION
The specified instance already exists but its version is lower than requested.

LOCALDB_ERROR_UNKNOWN_VERSION
The specified version is not available.

LOCALDB_ERROR_VERSION_REQUESTED_NOT_INSTALLED
The specified patch level is not installed.

LOCALDB_ERROR_CANNOT_CREATE_INSTANCE_FOLDER
A folder cannot be created under %userprofile%.

LOCALDB_ERROR_CANNOT_GET_USER_PROFILE_FOLDER
A user profile folder cannot be retrieved.

LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_FOLDER
An instance folder cannot be accessed.

LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_REGISTRY
An instance registry cannot be accessed.

LOCALDB_ERROR_CANNOT_MODIFY_INSTANCE_REGISTRY
An instance registry cannot be modified.

LOCALDB_ERROR_SQL_SERVER_STARTUP_FAILED
A SQL Server process is started but SQL Server startup failed.

LOCALDB_ERROR_INSTANCE_CONFIGURATION_CORRUPT
An instance configuration is corrupted.

LOCALDB_ERROR_INTERNAL_ERROR
An unexpected error occurred. See the event log for details.

Remarks

If a fully functional LocalDB instance with the specified name already exists and its version is equal to or higher than requested, the result is S_OK.

In cases when an existing instance becomes corrupted, subsequent calls to the LocalDBCreateInstance API method will fail. Corrupted instances must be fixed manually or explicitly deleted before they can be used again.

For a code sample that uses LocalDB API, see SQL Server Express LocalDB Reference.

See Also

SQL Server Express LocalDB Header and Version Information