AdomdConnection.ConnectionString Property

Gets or sets the string that the AdomdConnection uses to open an analytical data source.

Namespace:   Microsoft.AnalysisServices.AdomdClient
Assembly:  Microsoft.AnalysisServices.AdomdClient (in Microsoft.AnalysisServices.AdomdClient.dll)

Syntax

public string ConnectionString { get; set; }

public:
property String^ ConnectionString {
    virtual String^ get() sealed;
    virtual void set(String^ value) sealed;
}

abstract ConnectionString : string with get, set
override ConnectionString : string with get, set

Public Property ConnectionString As String

Property Value

Type: System.String

A string that contains the connection string that is used by the AdomdConnection.

Implements

IDbConnection.ConnectionString

Remarks

The ConnectionString property matches the OLE DB connection string format as closely as possible. You can use the ConnectionString property to connect to an analytical data source that supports the XML for Analysis 1.1 specification.

Many of the connection string values have corresponding read-only properties. When you set the connection string, all of these properties are updated, except when an error is detected. Detection of an error prevents all properties from being updated.

Resetting the ConnectionString property on a closed connection resets all connection string values (and related properties), including the password. For example, you set a connection string that includes Catalog= Adventure Works DW. You then reset the connection string to DataSource=localhost;Password=MyPassword. The Database property is now no longer set to the Adventure Works DW database. (The Catalog setting of the connection string corresponds to the Database property.)

A preliminary validation of the connection string is performed when the property is set. When an application calls the Open method, the connection string is parsed and individual properties are evaluated based on their level of support. If the AdomdConnection directly supports a property provided in the connection string, the value for that property is validated. If the value is not valid or is unsupported, an exception is thrown. If the property is not directly supported by the AdomdConnection, but the property can be used to construct a valid XML element, the property and its value are passed directly to the underlying provider. If such a property contains a value that is not valid or is unsupported, an exception is thrown at that time.

Values can be delimited by single or double quotes (for example, name='value' or name="value"). Either single or double quotes may be used within a connection string by using the other delimiter (for example, name="value's" or name= 'value"s', but not name='value's' or name= ""value""). All blank characters are ignored, except those placed within a value or within quotes. Keyword value pairs must be separated by a semicolon (;). If a semicolon is part of a value, it also must be delimited by quotes. No escape sequences are supported. The value type is irrelevant. Names are not case sensitive. If a property name occurs more than once in the connection string, the value associated with the last occurrence is used.

The following table describes the connection string settings directly supported by the AdomdConnection. Provider-specific connection strings settings may also be set, but are not listed here.

Several connection string settings map to a corresponding property in the AdomdConnection. The following table lists the connection string settings their corresponding AdomdConnection property.

Connecting to Local Cube Files

To connect to an existing local cube file, you must provide the full path and file name of a valid local cube file in the Data Source connection string setting and, if applicable, a valid password in the Password connection string setting. If the local cube file does not already exist, a new local cube file is created and protected by the password, provided that a password was specified. If a local cube is to be created, additional settings must be specified in the connection string, such as INSERTINTO or CREATECUBE.

Setting Safety Options

The value of the Safety Options property determines whether unsafe libraries can be registered and loaded by Microsoft PivotTable Service or the server. If an attempt is made to load an unsafe library or reference an unsafe user-defined function while safety checking is enabled, then PivotTable Service returns the following error:

User defined function <function name> cannot be used, because the class that implements it is not safe for initialization or scripting, which is required by client settings.

The value of the Safety Options property determines whether the PASSTHROUGH keyword is allowed in local cubes. If a client application tries to create a local cube with an INSERT INTO statement that contains the PASSTHROUGH keyword, or if a client application attempts to refresh a local cube that contains an INSERT INTO statement that uses the PASSTHROUGH keyword, an error is raised.

The following table lists the possible values for the Safety Options property.

Update Isolation Level

The value of the Update Isolation Level property affects how Analysis Services will evaluate each cell for update. Cells to be updated can overlap from one SET command to the next, in the same UPDATE statement. If updated cells do not overlap, you can improve performance by setting Update Isolate Level to Isolated (1). However, if updated cells do overlap and Update Isolate Level is set to Isolated (1), the outcome of the UPDATE statement will be erroneous.

The following table lists the possible values for the Update Isolate Level property.

To understand overlapping, review the following fact table of a simple Sales Forecasting cube with only five rows.

Suppose you want assign to Projected Sales a distributed value of 100 for all females and a distributed value of 200 for all salespeople from California (CA). In this case, your update cube statement would be as follows:

UPDATE CUBE SalesForcasting SET Female=100, CA=200 USE_EQUAL_INCREMENT

If you check the updated cells you will notice that they do not overlap. Female updated cells are Alice and Betty's cells and California cells are Diego and Edward.

Now, suppose you want to assign a distributed value of 100 to all males and a distributed value of 200 to all salespeople from Washington (WA). In this case, your update cube statement would be the following:

UPDATE CUBE SalesForcasting SET Male=100, WA=200 USE_EQUAL_INCREMENT

If you check the updated cells you will notice that they do overlap. Male updated cells are Charles, Diego, and Edwards' cells, and Washington cells are Betty and Charles. The cells overlap at Charles.

See Also

AdomdConnection Class
Microsoft.AnalysisServices.AdomdClient Namespace

Return to top