System.OleDbProbe

Article
12/21/2016

Applies To: Operations Manager 2007 R2

The System.OleDbProbe probe action module type is used to perform asynchronous queries against a database that supports OLE DB. This module returns the results as System.OleDbData data type.

Usage

Use this module to receive OLE DB data within a workflow such as a rule or monitor.

Type Definition

  
<ProbeActionModuleType ID="System.OleDbProbe" Accessibility="Public" PassThrough="false" Batching="false">  
  <Configuration>  
    <xsd:element name="ConnectionString" type="xsd:string"/>  
    <xsd:element name="Query" type="xsd:string" minOccurs="0" maxOccurs="1"/>  
    <xsd:element name="GetValue" type="xsd:boolean" minOccurs="0" maxOccurs="1"/>  
    <xsd:element name="IncludeOriginalItem" type="xsd:boolean" minOccurs="0" maxOccurs="1"/>  
    <xsd:element name="OneRowPerItem" type="xsd:boolean" minOccurs="0" maxOccurs="1"/>  
    <xsd:element name="DatabaseNameRegLocation" type="xsd:string" minOccurs="0" maxOccurs="1"/>  
    <xsd:element name="DatabaseServerNameRegLocation" type="xsd:string" minOccurs="0" maxOccurs="1"/>  
    <xsd:element name="QueryTimeout" type="xsd:integer" minOccurs="0" maxOccurs="1"/>  
    <xsd:element name="GetFetchTime" type="xsd:boolean" minOccurs="0" maxOccurs="1"/>  
  </Configuration>  
  <ModuleImplementation Isolation="Any">  
    <Native>  
      <ClassID>B5A35748-86F5-46A3-9BC2-F9A494E36B25</ClassID>  
    </Native>  
  </ModuleImplementation>  
  <OutputType>System.OleDbData</OutputType>  
  <InputType>System.BaseData</InputType>  
</ProbeActionModuleType>

Parameters

The System.OleDbProbe module supports the configuration parameters described in the following table.

Parameter	Type	Description
`ConnectionString`	`String`	Required parameter. Defines the connection string to the OLE DB database. On systems running Windows 2003 or later, the module encrypts the `ConnectionString` value.
`Query`	`String`	Required parameter. Defines the query to run against the OLE DB database.
`GetValue`	`Boolean`	Optional parameter. Determines whether or not the module will return the results of the query.
`IncludeOriginalItem`	`Boolean`	Optional parameter. Determines whether or not the item that triggered the module should be included in the result set.
`OneRowPerItem`	`Boolean`	Optional parameter. Determines whether or not the module should return a single data item per row of data. When set to `false`, all rows are returned as part of a single data item.
`DatabaseNameRegLocation`	`String`	Optional parameter. Represents a registry key where the name of the database can be found. The registry key must be found under the HKLM registry hive. For example, a valid value could be something like `SOFTWARE\Company\Product\1.0\DatabaseName`.
`DatabaseServerNameRegLocation`	`String`	Optional parameter. Represents a registry key where the name of the database server can be found. The registry key must be found under the HKLM registry hive. For example, a valid value could be something like `SOFTWARE\Company\Product\1.0\ServerName`.
`QueryTimeout`	`Integer`	R2 specific. Optional parameter. Represents the query time-out.
`GetFetchTime`	`Boolean`	R2 specific. Optional parameter. Defines whether or not to return the duration of fetching the result set.

Remarks

This module does not support blob data access. Any column that contains blob data will return as an empty value.

If you set GetValue to true to return the data from the query, certain datatypes such as decimal and datetime may not return expected data. A workaround is to use the CONVERT function in the Query to convert the data to another type such as varchar.

Composition

The System.OleDbProbe module is a native module.

To access the specified OLE DB database, the System.OleDbProbe module implements an OLE DB template. For information about these templates, see OLE DB Templates.

Errors

The errors described in the following table can occur from within the System.OleDbProbe module.

Exception	Reason
11851	The module failed to initialize.
11852	Logging failure of result data.
11853	The module failed to get the result data.
11854	The module failed to authenticate to the data source.
11855	Query execution failed due to a time-out.
11856	The module failed to encrypt the connection string.
11857	The module failed to decrypt the connection string.

None.

External Module References

None.

Sample

The following sample XML illustrates how to implement the System.OleDbProbe module in a rule. In this sample, the rule targets a fictional application that stores information about itself in a SQL database. The rule generates an alert for each row whose Status column equals “Error”. Before we can use the OLE DB probe in a rule, we have to define a custom DataSourceModuleType because rules do not directly contain probe action modules.

  
//First, the custom class definition. Discovery of this class is not included.  
<ClassType ID="Microsoft.Samples.MyApplication" Accessibility="Internal" Abstract="false" Base="Windows!Microsoft.Windows.LocalApplication" Hosted="true" Singleton="false" Extension="false" />

  
//Now we define the data source module type. The module will run the probe action every 3600 seconds.  
<DataSourceModuleType ID="Microsoft.Samples.OleDbGetErrorDS" Accessibility="Internal" Batching="false">  
  <Configuration />  
  <ModuleImplementation Isolation="Any">  
    <Composite>  
      <MemberModules>  
        <DataSource ID="Scheduler" TypeID="System!System.Scheduler">  
          <Scheduler>  
            <SimpleReccuringSchedule>  
              <Interval>3600</Interval>  
              <SyncTime />  
            </SimpleReccuringSchedule>  
            <ExcludeDates />  
          </Scheduler>  
        </DataSource>  
        <ProbeAction ID="OleDb" TypeID="System!System.OleDbProbe">  
          <ConnectionString>Provider=SQLOLEDB;Data Source=(local);Integrated Security=SSPy=SSPI"</ConnectionString>  
          <Query>SELECT * WHERE Status='Error'</Query>  
          <OneRowPerItem>true</OneRowPerItem>  
        </ProbeAction>  
      </MemberModules>  
      <Composition>  
        <Node ID="OleDb">  
          <Node ID="Scheduler" />  
        </Node>  
      </Composition>  
    </Composite>  
  </ModuleImplementation>  
  <OutputType>System!System.OleDbData</OutputType>  
</DataSourceModuleType>

  
//Now the actual rule.  
<Rule ID="Microsoft.Samples.OleDbRuleGenerateAlertOnError" Enabled="true" Target="Microsoft.Samples.MyApplication" ConfirmDelivery="true" Remotable="true" Priority="Normal" DiscardLevel="100">  
  <Category>Custom</Category>  
  <DataSources>  
    <DataSource ID="DS" TypeID="Microsoft.Samples.OleDbGetErrorDS" />  
  </DataSources>  
  <WriteActions>  
    <WriteAction ID="Alert" TypeID="Health!System.Health.GenerateAlert">  
      <Priority>1</Priority>  
      <Severity>1</Severity>  
    </WriteAction>  
  </WriteActions>  
</Rule>

The System.OleDbData data output of the Microsoft.Samples.OleDbGetErrorDS module in the above rule would look something like the following:

  
<DataItem type="System.OleDbData" time="2010-03-10T10:19:00.4146189-08:00" sourceHealthServiceId="88015514-C091-36AE-D102-A0A6AD267C7C">  
  <HRResult>0</HRResult>   
  <ResultLength>8</ResultLength>   
  <Result>Success</Result>   
  <InitializationTime>213</InitializationTime>   
  <OpenTime>0</OpenTime>   
  <ExecutionTime>32</ExecutionTime>   
  <FetchTime>0</FetchTime>   
  <RowLength>1</RowLength>   
   <Columns>  
   <Column VariantType="3">1</Column>   
  </Columns>  
  <OriginalDataLength>0</OriginalDataLength>   
  <ErrorDescriptionLength>0</ErrorDescriptionLength>   
  <ResultCode>0</ResultCode>   
</DataItem>

For information on the meaning of the elements of the System.OleDbData data type, see System.OleDbData.

Information

Module Type	ProbeActionModuleType
Input Type	System.BaseData
Output Type	System.OleDbData
Implementation	Native
Library	`System. Library`