Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

LocalDBStartInstance Function

Starts the specified SQL Server Express LocalDB instance.

Header file: sqlncli.h

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

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.

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.

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.

Community Additions

ADD
Show:
© 2015 Microsoft