Edit

Share via

LocalDBStartInstance function

Applies to: SQL Server

Starts the specified SQL Server Express LocalDB instance.

Header file: msoledbsql.h

Syntax

HRESULT LocalDBStartInstance(
           PCWSTR pInstanceName ,
           DWORD dwFlags ,
           LPWSTR wszSqlConnection ,
           LPDWORD lpcchSqlConnection
);

Arguments

pInstanceName

[Input] The name of the LocalDB instance to start.

dwFlags

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

wszSqlConnection

[Output] The buffer to store the connection string to the LocalDB instance.

lpcchSqlConnection

[Input/Output] On input contains the size of the wszSqlConnection buffer in characters, including any trailing nulls. On output, if the given buffer size is too small, contains the required buffer size in characters, including any trailing nulls.

Returns

S_OK: The function succeeded.

Error Description
LOCALDB_ERROR_NOT_INSTALLED SQL Server Express LocalDB isn't 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_UNKNOWN_INSTANCE The instance doesn't exist.
LOCALDB_ERROR_INSUFFICIENT_BUFFER The specified buffer wszSqlConnection is too small.
LOCALDB_ERROR_WAIT_TIMEOUT A time-out occurred while trying to acquire the synchronization locks.
LOCALDB_ERROR_INSTANCE_FOLDER_PATH_TOO_LONG The path where the instance should be stored is longer than MAX_PATH.
LOCALDB_ERROR_CANNOT_GET_USER_PROFILE_FOLDER A user profile folder can't be retrieved.
LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_FOLDER An instance folder can't be accessed.
LOCALDB_ERROR_CANNOT_ACCESS_INSTANCE_REGISTRY An instance registry can't be accessed.
LOCALDB_ERROR_CANNOT_MODIFY_INSTANCE_REGISTRY An instance registry can't be modified.
LOCALDB_ERROR_CANNOT_CREATE_SQL_PROCESS A process for SQL Server can't be created.
LOCALDB_ERROR_SQL_SERVER_STARTUP_FAILED A SQL Server process was started, but SQL Server startup failed.
LOCALDB_ERROR_INSTANCE_CONFIGURATION_CORRUPT An instance configuration was corrupted.
LOCALDB_ERROR_AUTO_INSTANCE_CREATE_FAILED Can't create an automatic instance. See the Windows Application event log for error details.
LOCALDB_ERROR_INTERNAL_ERROR An unexpected error occurred. See the event log for details.

Details

Both the connection buffer argument (wszSqlConnection) and the connection buffer size argument (lpcchSqlConnection) are optional. The following table shows options for using these arguments and their results.

Buffer Buffer size Rationale Action
NULL NULL User wants to start the instance and doesn't need a pipe name. Starts an instance (no pipe return and no required buffer size return).
NULL Present User asks for the output buffer size. (In the next call the user will probably ask for an actual start.) Returns a required buffer size (no start and no pipe return). Result is S_OK.
Present NULL Not allowed; incorrect input. Returned result is LOCALDB_ERROR_INVALID_PARAMETER.
Present Present User wants to start the instance and needs the pipe name to connect to it after it's started. Checks the buffer size, starts the instance, and returns the pipe name in the buffer.
The buffer size argument returns the length of the "server=" string, not including terminating nulls.

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

Related content