Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.