LocalDBStartInstance Function

Starts the specified SQL Server Express LocalDB instance.

Header file: sqlncli.h

Syntax

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

Parameters

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

• 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_UNKNOWN_INSTANCE
  The instance does not 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 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_CANNOT_CREATE_SQL_PROCESS
  A process for SQL Server cannot 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
  Cannot 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 is 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.

See Also

Concepts

SQL Server Express LocalDB Header and Version Information