IDSSDBConnection Interface Reference

Inherited by IDSSDBConnection2.

List of all members.

---

Detailed Description

DSSDBConnection is a first class object that records how to make a physical connection to a DB.

It can be browsed/saved through DSS Object Server. It describes the properties of an ODBC connection. DBConnection is different from a connection instance. DSSDBConnection is the definition of a database connection, from which one can create multiple instances of database connections.

Public Member Functions
HRESULT	CacheOption ([in] EnumDSSDBConnectionCache CacheOption)
	Whether physical connections are cached.
HRESULT	CacheOption ([out, retval] EnumDSSDBConnectionCache *pCacheOption)
	Whether physical connections are cached.
HRESULT	CacheSize ([in] Int32 CacheSize)
	Maximum number of cached physical connections.
HRESULT	CacheSize ([out, retval] Int32 *pCacheSize)
	Maximum number of cached physical connections.
HRESULT	CacheTimeOut ([in] Int32 CacheTimeOut)
	How long before idle connections are removed from cache.
HRESULT	CacheTimeOut ([out, retval] Int32 *pCacheTimeOut)
	How long before idle connections are removed from cache.
HRESULT	ConnectionString ([in] BSTR ConnectionString)
	String used to define the connection.
HRESULT	ConnectionString ([out, retval] BSTR *pConnectionString)
	String used to define the connection.
HRESULT	ConnectionTimeOut ([in] Int32 ConnectionTimeOut)
	How long before requests on connection are timed out.
HRESULT	ConnectionTimeOut ([out, retval] Int32 *pConnectionTimeOut)
	How long before requests on connection are timed out.
HRESULT	DatabaseName ([in] BSTR DatabaseName)
	Not used.
HRESULT	DatabaseName ([out, retval] BSTR *pDatabaseName)
	Not used.
HRESULT	DatabaseType ([in] EnumDSSDatabaseType DatabaseType)
	Not used.
HRESULT	DatabaseType ([out, retval] EnumDSSDatabaseType *pDatabaseType)
	Not used.
HRESULT	DatabaseVersion ([in] EnumDSSDatabaseVersion DatabaseVersion)
	Not used.
HRESULT	DatabaseVersion ([out, retval] EnumDSSDatabaseVersion *pDatabaseVersion)
	Not used.
HRESULT	DBCPrefixString ([in] BSTR ConnectionString)
	Not used.
HRESULT	DBCPrefixString ([out, retval] BSTR *pConnectionString)
	Not used.
HRESULT	DefaultDBLogin ([in] IDSSDBLogin *pDefaultDBLogin)
	Default user name and password for connection.
HRESULT	DefaultDBLogin ([out, retval] IDSSDBLogin ppDefaultDBLogin)
	Default user name and password for connection.
HRESULT	DefaultMaxDBConnection ([in] Int32 DefaultMaxDBConnection)
	DefaultMaxDBConnection is a numeric property.
HRESULT	DefaultMaxDBConnection ([out, retval] Int32 *pDefaultMaxDBConnection)
	DefaultMaxDBConnection is a numeric property.
HRESULT	DefaultMaxDBCost ([in] Int32 DefaultMaxDBCost)
	DefaultMaxDBCost is a numeric property.
HRESULT	DefaultMaxDBCost ([out, retval] Int32 *pDefaultMaxDBCost)
	DefaultMaxDBCost is a numeric property.
HRESULT	DriverType ([in] EnumDSSDBConnectionDriver DriverType)
	Whether ODBC driver or native driver.
HRESULT	DriverType ([out, retval] EnumDSSDBConnectionDriver *pDriverType)
	Whether ODBC driver or native driver DriverType is an enumeration property.
HRESULT	ExecutionMode ([in] EnumDSSDBConnectionExecutionMode ExecutionMode)
	Whether synchronous or asynchronous.
HRESULT	ExecutionMode ([out, retval] EnumDSSDBConnectionExecutionMode *pExecutionMode)
	Whether synchronous or asynchronous.
HRESULT	Info ([out, retval] IDSSObjectInfo ppInfo)
	Usual information about a DSS Object.
HRESULT	LoadDSNDefinition ([in] BSTR DSN)
	Assign ConnectionString from a DSN using local registry.
HRESULT	MultiProcessOption ([in] EnumDSSDBConnectionMultiProcessOption MultiProcessOption)
	Whether connection is in same process or separate process.
HRESULT	MultiProcessOption ([out, retval] EnumDSSDBConnectionMultiProcessOption *pMultiProcessOption)
	Whether connection is in same process or separate process.
HRESULT	Populate ([in] IDSSDBConnection *pOriginal)
	Populate properties of connection from an existing one.
HRESULT	TablePrefixString ([in] BSTR ConnectionString)
	Prefix added to temporary tables made on this connection.
HRESULT	TablePrefixString ([out, retval] BSTR *pConnectionString)
	Prefix added to temporary tables made on this connection.
HRESULT	TableSpaceName ([in] BSTR TableSpaceName)
	Not used.
HRESULT	TableSpaceName ([out, retval] BSTR *pTableSpaceName)
	Not used.
HRESULT	TraceFlag ([in] VARIANT_BOOL TraceFlag)
	Whether requests on this connection should be traced.
HRESULT	TraceFlag ([out, retval] VARIANT_BOOL *pTraceFlag)
	Whether requests on this connection should be traced.
HRESULT	UseExtendedFetch ([in] VARIANT_BOOL UseExtendedFetch)
	Whether ODBS's extended fetch should be used.
HRESULT	UseExtendedFetch ([out, retval] VARIANT_BOOL *pUseExtendedFetch)
	Whether ODBS's extended fetch should be used.

---

Member Function Documentation

HRESULT IDSSDBConnection::CacheOption (  [in] EnumDSSDBConnectionCache  CacheOption  )

Whether physical connections are cached. CacheOption is an enumeration property. It specifies the degree to which the intelligence server will attempt to reuse physical connections made using the specification contained in this DBConnection object. The default value for this property is DssDBConnectionCacheSerialReuse. The enumeration EnumDSSDBConnectionCache contains the following values. Name Value Meaning DssDBConnectionCacheReserved 0 No not use DssDBConnectionCacheNone 1 Physical connection is not reused. DssDBConnectionCacheReuse 2 Several consumers can use connection at the same time. (This option is not currently supported.) DssDBConnectionCacheSerialReuse 3 Physical connection is reused, but only one consumer at a time is permitted to use it. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::CacheOption (  [out, retval] EnumDSSDBConnectionCache *  pCacheOption  )

Whether physical connections are cached. CacheOption is an enumeration property. It specifies the degree to which the intelligence server will attempt to reuse physical connections made using the specification contained in this DBConnection object. The default value for this property is DssDBConnectionCacheSerialReuse. The enumeration EnumDSSDBConnectionCache contains the following values. Name Value Meaning DssDBConnectionCacheReserved 0 No not use DssDBConnectionCacheNone 1 Physical connection is not reused. DssDBConnectionCacheReuse 2 Several consumers can use connection at the same time. (This option is not currently supported.) DssDBConnectionCacheSerialReuse 3 Physical connection is reused, but only one consumer at a time is permitted to use it. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::CacheSize (  [in] Int32  CacheSize  )

Maximum number of cached physical connections. CacheSize is a numeric property. It contains the maximum number of physical connections made using the specifications in this object that may be opened simultaneously. Thus it is the maximum size of the connection pool. The default value for this property is 0. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::CacheSize (  [out, retval] Int32 *  pCacheSize  )

Maximum number of cached physical connections. CacheSize is a numeric property. It contains the maximum number of physical connections made using the specifications in this object that may be opened simultaneously. Thus it is the maximum size of the connection pool. The default value for this property is 0. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::CacheTimeOut (  [in] Int32  CacheTimeOut  )

How long before idle connections are removed from cache. CacheTimeOut is a numeric property. When use connection pooling, the connection is not disconnected when it is released. Instead, it is kept open until it idles for ConnectionCacheTimeOut seconds. If a connection is open and released frequently, connection pooling reduces the cost associated with creating a new connection. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::CacheTimeOut (  [out, retval] Int32 *  pCacheTimeOut  )

How long before idle connections are removed from cache. CacheTimeOut is a numeric property. When use connection pooling, the connection is not disconnected when it is released. Instead, it is kept open until it idles for ConnectionCacheTimeOut seconds. If a connection is open and released frequently, connection pooling reduces the cost associated with creating a new connection. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::ConnectionString (  [in] BSTR  ConnectionString  )

String used to define the connection. ConnectionString is a text property. Its value is the whole ODBC connection definition string. In order to create a database one connection one needs to know only the value of this string and a user name and password. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::ConnectionString (  [out, retval] BSTR *  pConnectionString  )

String used to define the connection. ConnectionString is a text property. Its value is the whole ODBC connection definition string. In order to create a database one connection one needs to know only the value of this string and a user name and password. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::ConnectionTimeOut (  [in] Int32  ConnectionTimeOut  )

How long before requests on connection are timed out. ConnectionTimeOut is a numeric property. It specifies the time in seconds to wait for a connection request comes back. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::ConnectionTimeOut (  [out, retval] Int32 *  pConnectionTimeOut  )

How long before requests on connection are timed out. ConnectionTimeOut is a numeric property. It specifies the time in seconds to wait for a connection request comes back. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DatabaseName (  [in] BSTR  DatabaseName  )

Not used. DatabaseName is a text property. This property is not used. It should be left as the empty string. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DatabaseName (  [out, retval] BSTR *  pDatabaseName  )

Not used. DatabaseName is a text property. This property is not used. It should be left as the empty string. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DatabaseType (  [in] EnumDSSDatabaseType  DatabaseType  )

Not used. DatabaseType is an enumeration property. It represents the type (typically the vendor) of the database used by this connection. Currently however this property is not used. Instead the DatabaseType property of the DBRole object is used to determine the type of the connection. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DatabaseType (  [out, retval] EnumDSSDatabaseType *  pDatabaseType  )

Not used. DatabaseType is an enumeration property. It represents the type (typically the vendor) of the database used by this connection. Currently however this property is not used. Instead the DatabaseType property of the DBRole object is used to determine the type of the connection. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DatabaseVersion (  [in] EnumDSSDatabaseVersion  DatabaseVersion  )

Not used. DatabaseVersion is an enumeration property. It is intended to provide a fine distinction between different versions of relational databases. Currently however the property is not used. Instead the DatabaseVersion property of the DBRole object is used to determine the version of the database to which a connection is desired. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DatabaseVersion (  [out, retval] EnumDSSDatabaseVersion *  pDatabaseVersion  )

Not used. DatabaseVersion is an enumeration property. It is intended to provide a fine distinction between different versions of relational databases. Currently however the property is not used. Instead the DatabaseVersion property of the DBRole object is used to determine the version of the database to which a connection is desired. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DBCPrefixString (  [in] BSTR  ConnectionString  )

Not used. DBCPrefixString is a text property. This property is not used. It should be left as the empty string. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DBCPrefixString (  [out, retval] BSTR *  pConnectionString  )

Not used. DBCPrefixString is a text property. This property is not used. It should be left as the empty string. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DefaultDBLogin (  [in] IDSSDBLogin *  pDefaultDBLogin  )

Default user name and password for connection. DefaultDBLogin is an object-valued property. A DBLogin object is the metadata object that holds a user name and password. So this property holds the DBLogin object that will be used to make this connection in the absence of some other DBLogin object. The DBConnectionMaps property on the IDSSProject interface can be used to override the default DBLogin object for a specific user and DBRole in the project. This allows the system administrator to specify that different users connect to a database using a different connection. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DefaultDBLogin (  [out, retval] IDSSDBLogin   ppDefaultDBLogin  )

Default user name and password for connection. DefaultDBLogin is an object-valued property. A DBLogin object is the metadata object that holds a user name and password. So this property holds the DBLogin object that will be used to make this connection in the absence of some other DBLogin object. The DBConnectionMaps property on the IDSSProject interface can be used to override the default DBLogin object for a specific user and DBRole in the project. This allows the system administrator to specify that different users connect to a database using a different connection. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DefaultMaxDBConnection (  [in] Int32  DefaultMaxDBConnection  )

DefaultMaxDBConnection is a numeric property. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DefaultMaxDBConnection (  [out, retval] Int32 *  pDefaultMaxDBConnection  )

DefaultMaxDBConnection is a numeric property. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DefaultMaxDBCost (  [in] Int32  DefaultMaxDBCost  )

DefaultMaxDBCost is a numeric property. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DefaultMaxDBCost (  [out, retval] Int32 *  pDefaultMaxDBCost  )

DefaultMaxDBCost is a numeric property. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DriverType (  [in] EnumDSSDBConnectionDriver  DriverType  )

Whether ODBC driver or native driver. DriverType is an enumeration property. It specifies the connection driver type. It specifies whether the connection is made using ODBC or some native database driver. The default value for this property is DssDBConnectionDriverODBC. The enumeration EnumDSSDBConnectionDriver contains the following values. Name Value Meaning DssDBConnectionDriverReserved 0 No not use DssDBConnectionDriverODBC 1 ODBC driver DssDBConnectionDriverNativeDBAPI 2 Native database driver (This option is not currently supported) Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::DriverType (  [out, retval] EnumDSSDBConnectionDriver *  pDriverType  )

Whether ODBC driver or native driver DriverType is an enumeration property. It specifies the connection driver type. It specifies whether the connection is made using ODBC or some native database driver. The default value for this property is DssDBConnectionDriverODBC. The enumeration EnumDSSDBConnectionDriver contains the following values. Name Value Meaning DssDBConnectionDriverReserved 0 No not use DssDBConnectionDriverODBC 1 ODBC driver DssDBConnectionDriverNativeDBAPI 2 Native database driver (This option is not currently supported) Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::ExecutionMode (  [in] EnumDSSDBConnectionExecutionMode  ExecutionMode  )

Whether synchronous or asynchronous. ExecutionMode is an enumeration property. It specifies the manner in SQL statements will be executed on a physical connection made using this object. In particular it indicates if the statement is executed synchronously or asynchronously. The default value is to use a synchronous connection (DssDBConnectionExecutionSynchronous). The enumeration EnumDSSDBConnectionExecutionMode contains the following values. Name Value Meaning DssDBConnectionExecutionReserved 0 No not use DssDBConnectionExecutionAsynchConnection 1 Create the ODBC connection as an asynchronous connection. All statement handles created in this connection are automatically made asynchronous. DssDBConnectionExecutionAsynchStatement 2 Set the Asynchronous option on each time we create statement handle in this connection. DssDBConnectionExecutionSynchronous 3 Synchronous connection. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::ExecutionMode (  [out, retval] EnumDSSDBConnectionExecutionMode *  pExecutionMode  )

Whether synchronous or asynchronous. ExecutionMode is an enumeration property. It specifies the manner in SQL statements will be executed on a physical connection made using this object. In particular it indicates if the statement is executed synchronously or asynchronously. The default value is to use a synchronous connection (DssDBConnectionExecutionSynchronous). The enumeration EnumDSSDBConnectionExecutionMode contains the following values. Name Value Meaning DssDBConnectionExecutionReserved 0 No not use DssDBConnectionExecutionAsynchConnection 1 Create the ODBC connection as an asynchronous connection. All statement handles created in this connection are automatically made asynchronous. DssDBConnectionExecutionAsynchStatement 2 Set the Asynchronous option on each time we create statement handle in this connection. DssDBConnectionExecutionSynchronous 3 Synchronous connection. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::Info (  [out, retval] IDSSObjectInfo   ppInfo  )

Usual information about a DSS Object. This property returns the IDSSObjectInfo interface associated with the current object. This interface contains many standard properties and methods. For example it contains a Name property and a Comments property. It contains methods to Save the object and so on. It is up to the implementation to decide whether the same interface could be obtained by calling QueryInterface(IID_IDSSObjectInfo, ...). Parameters: ppInfo  The standard Info interface on the current object. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::LoadDSNDefinition (  [in] BSTR  DSN  )

Assign ConnectionString from a DSN using local registry. LoadDSNDefinition is a method. This methods sets the ConnectionString property of the DBConnection object to the whole ODBC connection definition string needed to access a given DSN. In order to do this, this method needs to access the registry on the local machine to look up the DSN name. Parameters: DSN  The name of the DSN Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::MultiProcessOption (  [in] EnumDSSDBConnectionMultiProcessOption  MultiProcessOption  )

Whether connection is in same process or separate process. MultiProcessOption is an enumeration valued constant. It specifies if the connection is created in the same process as the caller or in a different process. It is more efficient to create the connection in the same process as the caller is. However using a different process protects the caller from problems of thread safety and memory leaks in the ODBC driver. Many ODBC drivers cannot be safely used in the same process as the intelligence server. The default value for this property is to create the connection in the same process as the caller. The enumeration EnumDSSDBConnectionMultiProcessOption contains the following values. Name Value Meaning DssDBConnectionMultiProcessReserved 0 No not use DssDBConnectionMultiProcessMultiThreadMode 1 Connection is created in same process as the caller. DssDBConnectionMultiProcessMultiProcessMode 2 Connection is created in different process to the caller. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::MultiProcessOption (  [out, retval] EnumDSSDBConnectionMultiProcessOption *  pMultiProcessOption  )

Whether connection is in same process or separate process. MultiProcessOption is an enumeration valued constant. It specifies if the connection is created in the same process as the caller or in a different process. It is more efficient to create the connection in the same process as the caller is. However using a different process protects the caller from problems of thread safety and memory leaks in the ODBC driver. Many ODBC drivers cannot be safely used in the same process as the intelligence server. The default value for this property is to create the connection in the same process as the caller. The enumeration EnumDSSDBConnectionMultiProcessOption contains the following values. Name Value Meaning DssDBConnectionMultiProcessReserved 0 No not use DssDBConnectionMultiProcessMultiThreadMode 1 Connection is created in same process as the caller. DssDBConnectionMultiProcessMultiProcessMode 2 Connection is created in different process to the caller. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::Populate (  [in] IDSSDBConnection *  pOriginal  )

Populate properties of connection from an existing one. Populate is a method. It assigns all of the properties of this DBConnection object to whatever values they have in a given DBConnection object. It is used to implement copying of DBConnection objects. Parameters: pOriginal  The original object. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::TablePrefixString (  [in] BSTR  ConnectionString  )

Prefix added to temporary tables made on this connection. TablePrefixString is a text property. The QueryEngine prefixed the names of all temporary tables that it creates during report execution with this string. The default value for this property is "zz". This property may not be an empty string. Attempting to set it to the empty string will reset it to "zz". Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::TablePrefixString (  [out, retval] BSTR *  pConnectionString  )

Prefix added to temporary tables made on this connection. TablePrefixString is a text property. The QueryEngine prefixed the names of all temporary tables that it creates during report execution with this string. The default value for this property is "zz". This property may not be an empty string. Attempting to set it to the empty string will reset it to "zz". Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::TableSpaceName (  [in] BSTR  TableSpaceName  )

Not used. TableSpaceName is a text property. This property is not used. It should be left as the empty string. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::TableSpaceName (  [out, retval] BSTR *  pTableSpaceName  )

Not used. TableSpaceName is a text property. This property is not used. It should be left as the empty string. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::TraceFlag (  [in] VARIANT_BOOL  TraceFlag  )

Whether requests on this connection should be traced. TraceFlag is a Boolean property. It specifies whether or not to turn on tracing when making calls on this connection. The default value is for the trace flag to be turned off. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::TraceFlag (  [out, retval] VARIANT_BOOL *  pTraceFlag  )

Whether requests on this connection should be traced. TraceFlag is a Boolean property. It specifies whether or not to turn on tracing when making calls on this connection. The default value is for the trace flag to be turned off. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::UseExtendedFetch (  [in] VARIANT_BOOL  UseExtendedFetch  )

Whether ODBS's extended fetch should be used. UseExtendedFetch is a Boolean property. It specifies whether or not to use the extended fetch ODBC call to retrieve data from the connection. The default value is to not use extended fetch. Returns: Usual COM result code: S_OK

HRESULT IDSSDBConnection::UseExtendedFetch (  [out, retval] VARIANT_BOOL *  pUseExtendedFetch  )

Whether ODBS's extended fetch should be used. UseExtendedFetch is a Boolean property. It specifies whether or not to use the extended fetch ODBC call to retrieve data from the connection. The default value is to not use extended fetch. Returns: Usual COM result code: S_OK

---