Data Connections

Addon data connections allow addon developers to create connections to different types of data sources so that addons can retrieve additional data other than that provided by individual host forms. The addon system allows individual addons to access data in a number of ways. The primary method of data access is via the data objects provided by individual forms.  This, however, is limited and is often not sufficient to meet the needs of a particular addon. In addition to the data exposed by individual forms, it is also possible to access data stored either in the host application's database or in a separate data source altogether. To allow this level of data access, two objects exist in the addon system specifically for allowing access to different types of data sources. The two objects, the DatabaseConnection object and the ManagedDatabaseConnection object work in exactly the same manner with two exceptions. The first exception is the manner in which they are created. Both objects are created via global method calls, but each has its own method (CreateDatabaseConnection and CreateManagedDatabaseConnection) and the two methods require different parameters. The second exception is that ManagedDatabaseConnection objects have heavy restrictions placed on the types of operations they can perform, since only read operations are allowed to be executed against the host application's data tables. Other than the read-only limitations, once a database connection is created via the required global method call, the functionality - specifically the properties and methods available, as well as how they are used - are exactly the same.

Properties

  • QueryString: A string representing the query that is to be executed the next time one of the execute methods is called.  This property must be set to a valid query before calling one of the execute methods.

Methods

  • Connect(): Opens a connection to the data source associated with the connection object.
  • AddParameter(string name, object value, object type): Adds a parameter that can be used in queries executed using the connection object.

    DirectionNameDescription
    InputnameThe name of the parameter. This is used when referencing the parameter in the query string.
    InputvalueThe value of the parameter.
    InputtypeAn SqlDbType or OleDbType enumeration value corresponding to the data type of the 'value' parameter.
  • ClearParameters(): Clears the list of parameters.

  • Execute(): Executes the currently assigned query string and uses the results to construct either a DataSet object if multiple result sets are returned or a DataTable if one or no result sets are returned.

    DirectionNameDescription
    OutputobjectThe DataTable or DataSet created using the result sets returned by the query.
  • ExecuteScalar(): Executes the currently assigned query string and returns the value held in first column of the first row of the first result set returned by the query.

    DirectionNameDescription
    OutputobjectThe value of the first column of the first row of the first result set returned by the query.
  • ExecuteNonQuery(): Executes the currently assigned query string and returns the number of rows affected.

    DirectionNameDescription
    OutputintThe number of rows effected.
  • Disconnect(): Closes the connection to the data source.

  • Dispose(): Closes the connection to the data source and disposes of the connection.