<connection> (Connection)

This element contains both the definition of how to get at an external data source as well as information describing how the connection is used within the workbook. Specific constructs in a worksheet, such as OLAP formulas, QueryTables, or PivotTables make use of information in the connection to retrieve or refresh data based on default events or the user's explicit request.

Parent Elements

<connections>3.13.2)

Child Elements

Subclause

<dbPr> (Database Properties)

§3.13.3

<extLst> (Future Feature Data Storage Area)

§3.2.10

<olapPr> (OLAP Properties)

§3.13.5

<parameters> (Query Parameters)

§3.13.7

<textPr> (Text Import Settings)

§3.13.12

<webPr> (Web Query Properties)

§3.13.13

Attributes

Description

<background> (Background Refresh)

Indicates whether the connection can be refreshed in the background (asynchronously). true if preferred usage of the connection is to refresh asynchronously in the background; false if preferred usage of the connection is to refresh synchronously in the foreground.

This flag should be intentionally ignored in specific cases.

example:

The possible values for this attribute are defined by the XML Schema boolean datatype.

<credentials> (Reconnection Method)

Specifies the authentication method to be used when establishing (or re-establishing) the connection.

The possible values for this attribute are defined by the ST_CredMethod simple type (§3.18.17).

<deleted> (Deleted Connection)

Indicates whether the associated workbook <connection> has been deleted. true if the <connection> has been deleted; otherwise, false.

Deleted <connections> contain only the attributes @name and @deleted=true, all other information is removed from the SpreadsheetML file.

If a new <connection> is created with the same name as a deleted <connection>, then the deleted <connection> is overwritten by the new connection.

The possible values for this attribute are defined by the XML Schema boolean datatype.

<description> (Connection Description)

Specifies the user description for this connection.

The possible values for this attribute are defined by the ST_Xstring simple type (§3.18.96).

<id> (Connection Id)

Specifies The unique identifier of this connection.

The possible values for this attribute are defined by the XML Schema unsignedInt datatype.

<interval> (Automatic Refresh Interval)

Specifies the number of minutes between automatic refreshes of the connection. When this attribute is not present, the connection is not automatically refreshed.

The possible values for this attribute are defined by the XML Schema unsignedInt datatype.

<keepAlive> (Keep Connection Open)

true when the spreadsheet application should make efforts to keep the connection open. When false, the application should close the connection after retrieving the information. This corresponds to the MaintainConnection property of a PivotCache object.

The possible values for this attribute are defined by the XML Schema boolean datatype.

<minRefreshableVersion> (Minimum Version Required for Refresh)

For compatibility with legacy spreadsheet applications. This represents the minimum version # that is required to be able to correctly refresh the data connection. This attribute applies to connections that are used by a QueryTable.

The possible values for this attribute are defined by the XML Schema unsignedByte datatype.

<name> (Connection Name)

Specifies the name of the <connection>. Each connection must have a unique name.

When a <connection> has been marked as deleted and then a new <connection> is added with the same name, the deleted <connection> is replaced with the new <connection>.

The possible values for this attribute are defined by the ST_Xstring simple type (§3.18.96).

<new> (New Connection)

true if the <connection> has not been refreshed for the first time; otherwise, false. This state can happen when the user saves the file before a query has finished returning.

The possible values for this attribute are defined by the XML Schema boolean datatype.

<odcFile> (Connection File)

Specifies the full path to external connection file from which this <connection> was created. If a connection fails during an attempt to refresh data, and @reconnectionMethod=1@, then the spreadsheet application will try again using information from the external connection file instead of the connection object embedded within the workbook.

This is a benefit for data source and spreadsheetML document manageability. If the definition in the external connection file is changed (e.g., because of a database server name change), then the workbooks that made use of that connection will fail to connect with their internal connection information, and reload the new connection information from this file.

This attribute is cleared by the spreadsheet application when the user manually edits the connection definition within the workbook. May be expressed in URI or system-specific file path notation.

Note:

The possible values for this attribute are defined by the ST_Xstring simple type (§3.18.96).

<onlyUseConnectionFile> (Only Use Connection File)

Indicates whether the spreadsheet application should always and only use the connection information in the external connection file indicated by the @odcFile attribute when the connection is refreshed.

If false, then the spreadsheet application should follow the procedure indicated by the @reconnectionMethod attribute described below.

Applies only to OLE DB and ODBC connections, this attribute is ignored for other types of connections.

The possible values for this attribute are defined by the XML Schema boolean datatype.

<reconnectionMethod> (Reconnection Method)

Specifies what the spreadsheet application should do when a connection fails.

The values are as follows:

1 = As required: On refresh use the existing connection information and if it ends up being invalid then get updated connection information, if available from the external connection file.

2 = Always: On every refresh get updated connection information from the external connection file, if available, and use that instead of the existing connection information. In this case the data refresh will fail if the external connection file is unavailable.

3 = Never: Never get updated connection information from the external connection file even if it is available and even if the existing connection information is invalid.

The possible values for this attribute are defined by the XML Schema unsignedInt datatype.

<refreshedVersion> (Last Refresh Version)

For backward compatibility purposes, this attribute indicates the version of the spreadsheet application that last refreshed the connection.

This attribute applies to connections that are used by a query table.

The possible values for this attribute are defined by the XML Schema unsignedByte datatype.

<refreshOnLoad> (Refresh on Open)

true if this connection should be refreshed when opening the file; otherwise, false.

The possible values for this attribute are defined by the XML Schema boolean datatype.

<saveData> (Save Data)

true if the external data fetched over the connection to populate a table is to be saved with the workbook; otherwise, false.

This exists for data security purposes - if no external data is saved in (or "cached") in the workbook, then current user credentials can be required every time to retrieve the relevant data, and people won't see the data the workbook author had last been using before saving the file.

The possible values for this attribute are defined by the XML Schema boolean datatype.

<savePassword> (Save Password)

true if the password is to be saved as part of the connection string; otherwise, False.

The possible values for this attribute are defined by the XML Schema boolean datatype.

<singleSignOnId> (SSO Id)

Identifier for Single Sign On (SSO) used for authentication between an intermediate spreadsheetML server and the external data source.

Note:

The possible values for this attribute are defined by the ST_Xstring simple type (§3.18.96).

<sourceFile> (Source Database File)

Used when the external data source is file-based. When a connection to such a data source fails, the spreadsheet application attempts to connect directly to this file. May be expressed in URI or system-specific file path notation.

Note:

The possible values for this attribute are defined by the ST_Xstring simple type (§3.18.96).

<type> (Database Source Type)

Specifies the data source type.

Values are as follows:

1. ODBC-based source

2. DAO-based source

3. File based database source

4. Web query

5. OLE DB-based source

6. Text-based source

7. ADO record set

8. DSP

The possible values for this attribute are defined by the XML Schema unsignedInt datatype.

The following XML Schema fragment defines the contents of this element:

<complexType name="CT_Connection">
	<sequence>
	<element name="dbPr" minOccurs="0" maxOccurs="1" type="CT_DbPr"/>
	<element name="olapPr" minOccurs="0" maxOccurs="1" type="CT_OlapPr"/>
	<element name="webPr" minOccurs="0" maxOccurs="1" type="CT_WebPr"/>
	<element name="textPr" minOccurs="0" maxOccurs="1" type="CT_TextPr"/>
	<element name="parameters" minOccurs="0" maxOccurs="1" type="CT_Parameters"/>
	<element name="extLst" minOccurs="0" maxOccurs="1" type="CT_ExtensionList"/>
	</sequence>
	<attribute name="id" use="required" type="xsd:unsignedInt"/>
	<attribute name="sourceFile" use="optional" type="ST_Xstring"/>
	<attribute name="odcFile" use="optional" type="ST_Xstring"/>
	<attribute name="keepAlive" use="optional" type="xsd:boolean" default="false"/>
	<attribute name="interval" use="optional" type="xsd:unsignedInt" default="0"/>
	<attribute name="name" use="optional" type="ST_Xstring"/>
	<attribute name="description" use="optional" type="ST_Xstring"/>
	<attribute name="type" use="optional" type="xsd:unsignedInt"/>
	<attribute name="reconnectionMethod" use="optional" type="xsd:unsignedInt" default="1"/>
	<attribute name="refreshedVersion" use="required" type="xsd:unsignedByte"/>
	<attribute name="minRefreshableVersion" use="optional" type="xsd:unsignedByte" default="0"/>
	<attribute name="savePassword" use="optional" type="xsd:boolean" default="false"/>
	<attribute name="new" use="optional" type="xsd:boolean" default="false"/>
	<attribute name="deleted" use="optional" type="xsd:boolean" default="false"/>
	<attribute name="onlyUseConnectionFile" use="optional" type="xsd:boolean" default="false"/>
	<attribute name="background" use="optional" type="xsd:boolean" default="false"/>
	<attribute name="refreshOnLoad" use="optional" type="xsd:boolean" default="false"/>
	<attribute name="saveData" use="optional" type="xsd:boolean" default="false"/>
	<attribute name="credentials" use="optional" type="ST_CredMethod" default="integrated"/>
	<attribute name="singleSignOnId" use="optional" type="ST_Xstring"/>
</complexType>