AdomdConnection.ConnectionString AdomdConnection.ConnectionString AdomdConnection.ConnectionString Property

Definition

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

public:
 property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };
public string ConnectionString { get; set; }
Public Property ConnectionString As String
Property Value

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

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.

Note

Applications should use caution when constructing a connection string based on user input (for example, when retrieving user ID and password information from a dialog box, and appending this information to the connection string). The application should ensure that a user cannot embed extra connection string parameters in these values (for example, a user that is trying to connect to a different database might enter a password as validpassword;database=somedb).

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.

Setting name Property name
ConnectionTimeout ConnectionTimeout
Catalog Database

Note

Properties that are Initialization Properties cannot be changed after a connection has been opened. The set of available initialization properties can be queried through IDBProperties::GetPropertyInfo.

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.

Value Description
0 For connections to a local cube, or by an Internet Information Services (IIS) server, this value is the same as DBPROPVAL_MSMD_SAFETY_OPTIONS_ALLOW_SAFE.

For all other connections, this value is the same as DBPROPVAL_MSMD_SAFETY_OPTIONS_ALLOW_ALL.
1 This value enables all user-defined function libraries without verifying that the libraries are safe for initialization and scripting, and also allows usage of the PASSTHROUGH keyword in local cubes.

MDSCHEMA_ACTIONS results are unfiltered. Note: We do not recommend this option.
2 This value ensures that all classes for a particular user-defined function library are checked to ensure that they are safe for initialization and scripting, and also prevents usage of the PASSTHROUGH keyword in local cubes.

MDSCHEMA_ACTIONS results of type HTML and command line are filtered out. MDSCHEMA_ACTIONS results of type URL are filtered out unless the CONTENT column begins with HTTP:// or HTTPS://.
3 This value prevents user-defined functions from being used during the session and prevents usage of the PASSTHROUGH keyword in local cubes.

MDSCHEMA_ACTIONS results are empty.

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.

Value Description
0 Not Isolated
1 Isolated Note: Use this value with caution, and only use it when no cells in the UPDATE CUBE statement overlap.

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

Name Gender State ProjectedSales
Alice Female OR Null
Betty Female WA Null
Charles Male WA Null
Diego Male CA Null
Edward Male CA Null

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.

Applies to