2.4.80 BrtBeginExtConnection
The BrtBeginExtConnection record specifies the properties of an external connection (section 2.2.8) and specifies the beginning of a collection of records as defined by the External Data Connections (section 2.1.7.24) part ABNF. The collection of records specifies properties of an external connection; the records that this collection contains are specified by the connection type, as specified in section 2.2.8.
|
|
|
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
|
|
3 |
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
bVerRefreshed |
bVerRefreshableMin |
pc |
reserved1 |
||||||||||||||||||||||||||||
|
wInterval |
A |
B |
C |
D |
E |
F |
G |
reserved2 |
|||||||||||||||||||||||
|
H |
I |
J |
K |
L |
reserved4 |
idbtype |
|||||||||||||||||||||||||
|
... |
irecontype |
||||||||||||||||||||||||||||||
|
... |
dwConnID |
||||||||||||||||||||||||||||||
|
... |
iCredMethod |
stDataFile (variable) |
|||||||||||||||||||||||||||||
|
... |
|||||||||||||||||||||||||||||||
|
stConnectionFile (variable) |
|||||||||||||||||||||||||||||||
|
... |
|||||||||||||||||||||||||||||||
|
stConnDesc (variable) |
|||||||||||||||||||||||||||||||
|
... |
|||||||||||||||||||||||||||||||
|
stConnName (variable) |
|||||||||||||||||||||||||||||||
|
... |
|||||||||||||||||||||||||||||||
|
stSso (variable) |
|||||||||||||||||||||||||||||||
|
... |
|||||||||||||||||||||||||||||||
bVerRefreshed (1 byte): A DataFunctionalityLevel (section 2.5.29) structure that specifies the data functionality level (section 2.2.5.1) that the external connection was last refreshed with.
bVerRefreshableMin (1 byte): A DataFunctionalityLevel (section 2.5.29) structure that specifies the minimum data functionality level (section 2.2.5.1) that the application is required to support to correctly refresh the external connection.
pc (8 bits): An unsigned integer that specifies whether the password is saved as part of the connection string. This value MUST be ignored if the value of the idbtype field is not DBTOLEDB (section 2.5.31) or DBTODBC (section 2.5.31); otherwise this value MUST be one of the values in the following table.
-
Value
Meaning
0x01
The password is saved in the connection string.
0x02
The password is not saved in the connection string.
reserved1 (8 bits): This value MUST be 0, and MUST be ignored.
wInterval (16 bits): An unsigned integer that specifies the number of minutes between automatic refreshes of the external connection. This value MUST be less than 32768. If the value is 0, the external connection is not automatically refreshed.
A - fMaintain (1 bit): A bit that specifies whether the external connection is maintained after the refresh. This value MUST be ignored if the value of idbtype is not DBTOLEDB (section 2.5.31).
B - fNewQuery (1 bit): A bit that specifies whether the external connection has been refreshed for the first time. The following table specifies the meaning of each value.
-
Value
Meaning
0
The external connection has been refreshed at least once.
1
The external connection has not been refreshed for the first time.
C - fDeleted (1 bit): A bit that specifies whether the external connection has been deleted. A deleted external connection MUST contain stConnName.
D - fAlwaysUseConnectionFile (1 bit): A bit that specifies whether the external connection information in the external connection file (section 2.2.8.2) specified in the stConnectionFile field is used when the external connection is refreshed. This value MUST be ignored if idbtype is not DBTOLEDB (section 2.5.31) or DBTODBC (section 2.5.31). The following table specifies the meaning of each value.
-
Value
Meaning
0
The procedure specified by the irecontype field is used.
1
The connection information in the external connection file specified by the stConnectionFile field is used.
E - fBackgroundQuery (1 bit): A bit that specifies whether the preferred usage of the external connection is to refresh asynchronously in the background. The following table specifies the meaning of each value.
-
Value
Meaning
0
The preferred usage of the external connection is to refresh synchronously in the foreground.
1
The preferred usage of the external connection is to refresh asynchronously in the background.
-
If this external connection is associated with a PivotCache (section 2.2.5.2), this value MUST be equal to the fBackgroundQuery field in the BrtBeginPivotCacheDef (section 2.4.168) record. If this external connection is associated with a query table, this value MUST be equal to the value in the fAsync field in the BrtBeginQSI (section 2.4.187) record.
F - fRefreshOnLoad (1 bit): A bit that specifies whether this external connection is refreshed when the workbook is opened.
G - fSaveData (1 bit): A bit that specifies whether the data retrieved from the external connection is saved within the workbook. If this external connection is associated with a query table, this value MUST be equal to the value in the fSaveData field in the BrtBeginQSI (section 2.4.187) record.
reserved2 (9 bits): This value MUST be 0, and MUST be ignored.
H - fLoadSourceDataFile (1 bit): A bit that specifies whether stDataFile exists after the fixed-size portion of the record.
I - fLoadSourceConnectionFile (1 bit): A bit that specifies whether stConnectionFile exists after the fixed-size portion of the record.
J - fLoadConnectionDesc (1 bit): A bit that specifies whether stConnDesc exists after the fixed-size portion of the record.
K - reserved3 (1 bit): A bit that MUST have a value of 1, and MUST be ignored.
L - fLoadSSOApplicationID (1 bit): A bit that specifies whether stSso exists after the fixed-size portion of the record. This value MUST be 0 if idbtype is not DBTOLEDB (section 2.5.31) or DBTODBC (section 2.5.31).
reserved4 (11 bits): This value MUST be 0, and MUST be ignored.
idbtype (4 bytes): A DBType (section 2.5.31) that specifies the data source type.
irecontype (4 bytes): An unsigned integer that specifies when external connection information is retrieved from the external connection file (section 2.2.8.2). This value MUST be ignored when the value for fAlwaysUseConnectionFile is 1 and MUST be ignored if idbtype is not DBTOLEDB (section 2.5.31); otherwise the value in this field MUST be one of the values in the following table.
-
Value
Meaning
0x00000001
Retrieve external connection information as required. When external data has to be refreshed from the external connection, use the existing external connection information; otherwise if the external data refresh from the external connection fails then retrieve updated external connection information, if available, from the external connection file.
0x00000002
Retrieve external connection information. When external data has to be refreshed from the external connection, retrieve updated external connection information from the external connection file, if available, and use that instead of the existing external connection information. In this case the external data refresh will fail if the external connection file is unavailable.
0x00000003
Never retrieve external connection information. Never get updated external connection information from the external connection file even if it is available and even if the existing external connection information is invalid.
dwConnID (4 bytes): An unsigned integer that specifies the unique identifier of this external connection. This value MUST be greater than 0.
iCredMethod (1 byte): An unsigned integer that specifies the authentication method that is used when establishing or reestablishing the external connection. This value MUST be 0 and MUST be ignored if idbtype is not DBTOLEDB (section 2.5.31) or DBTODBC (section 2.5.31); otherwise this value MUST be one of the values listed in the following table.
-
Value
Meaning
0x00
Integrated authentication.
0x01
No credentials.
0x02
Use credentials that are stored as part of a single sign-on (SSO) repository.
stDataFile (variable): An optional XLWideString (section 2.5.169) value that specifies the path to the file containing the data to import. The length of the string MUST be less than 256 characters. This field MUST exist if and only if fLoadSourceDataFile is 1.
stConnectionFile (variable): An optional XLWideString value that specifies the path to the external connection file (section 2.2.8.2) from which this external connection was created. As specified by fAlwaysUseConnectionFile and irecontype, the information in the external connection file can be used in place of information specified by this collection of records. The length of the string MUST be less than 256 characters. This field MUST exist if and only if fLoadSourceConnectionFile is 1.
stConnDesc (variable): An optional XLWideString value that specifies the description for this external connection. The length of the string MUST be less than 256 characters. This field MUST exist if and only if fLoadConnectionDesc is 1.
stConnName (variable): An XLWideString value that specifies the name of the external connection. The external connection name MUST be unique within a workbook. The length of the string MUST be greater than 0 and less than 256 characters.
stSso (variable): An optional XLWideString value that specifies the identifier for single sign-on (SSO) used for authentication between a multi-tier application and the external data. The length of the string MUST be less than 256 characters. This field MUST exist if and only if fLoadSSOApplicationID is 1.