1 out of 1 rated this helpful - Rate this topic

IDataCollectorSet interface

Applies to: desktop apps only

Manages the configuration information that is common to all data collector objects in the set; adds and removes data collectors from the set; and starts data collection. This is the primary PLA interface that you use.

To get this interface, call the CoCreateInstance function, passing __uuidof(DataCollectorSet) as the class identifier and __uuidof(IDataCollectorSet) as the interface identifier.

Members

The IDataCollectorSet interface inherits from the IDispatch interface. IDataCollectorSet also has these types of members:

Methods
Properties

Methods

The IDataCollectorSet interface has these methods.

Method	Description
Commit	Saves, updates, or validates the data collector set. You can also use this method to flush a trace session.
Delete	Deletes the persisted copy of the data collector set if the set is not running.
GetValue	Retrieves a user-defined value.
Query	Retrieves the specified data collector set from the hard disk and overwrites this object with the contents of the set.
SetCredentials	Specifies the user account under which the data collector set runs.
SetValue	Sets a user-defined value.
SetXml	Sets the property values of those properties included in the XML.
Start	Manually starts the data collector set.
Stop	Manually stops the data collector set.

Properties

The IDataCollectorSet interface has these properties.

Property	Description
DataCollectors	Retrieves the list of data collectors in this set.
DataManager	Retrieves the data manager associated with this data collector set.
Description	Retrieves or sets the description of the data collector set.
DescriptionUnresolved	Retrieves the description of the data collector set in its original form.
DisplayName	Retrieves or sets the display name of the data collector set.
DisplayNameUnresolved	Retrieves the display name of the data collector set in its original form.
Duration	Retrieves and sets the duration that the data collector set runs.
Keywords	Retrieves or sets keywords that describe the data collector set.
LatestOutputLocation	Retrieves or sets the fully decorated folder name that PLA used the last time logs were written.
Name	Retrieves the unique name used to identify the data collector set.
OutputLocation	Retrieves the decorated folder name if PLA were to create it now.
RootPath	Retrieves or sets the base path where the subdirectories are created.
Schedules	Retrieves the list of schedules that determine when the data collector set runs.
SchedulesEnabled	Retrieves or sets a value that indicates whether the schedules are enabled.
Security	Retrieves or sets access control information that determines who can access this data collector set.
Segment	Retrieves or sets a value that indicates whether PLA creates new logs if the maximum size or segment duration is reached before the data collector set is stopped.
SegmentMaxDuration	Retrieves or sets the duration that the data collector set can run before it begins writing to new log files.
SegmentMaxSize	Retrieves or sets the maximum size of any log file in the data collector set.
SerialNumber	Retrieves or sets the number of times that this data collector set has been started, including segments.
Server	Retrieves the name of the server where the data collector set is run.
Status	Retrieves the status of the data collector set.
StopOnCompletion	Retrieves or sets a value that determines whether the data collector set stops when all the data collectors in the set are in a completed state.
Subdirectory	Retrieves or sets a base subdirectory of the root path where the next instance of the data collector set will write its logs.
SubdirectoryFormat	Retrieves or sets flags that describe how to decorate the subdirectory name.
SubdirectoryFormatPattern	Retrieves or sets a format pattern to use when decorating the folder name.
Task	Retrieves or sets the name of a Task Scheduler job to start each time the data collector set stops, including between segments.
TaskArguments	Retrieves or sets the command-line arguments to pass to the Task Scheduler job specified in the IDataCollectorSet::Task property.
TaskRunAsSelf	Retrieves or sets a value that determines whether the task runs as the data collector set user or as the user specified in the task.
TaskUserTextArguments	Retrieves or sets the command-line arguments that are substituted for the {usertext} substitution variable in the IDataCollectorSet::TaskArguments property.
UserAccount	Retrieves the user account under which the data collector set will run.
Xml	Retrieves an XML string that describes the values of the data collector set properties, including those of the data collectors contained in the set.

Remarks

To create the object from a script, use the "Pla.DataCollectorSet" program identifier.

To retrieve an existing data collector set, create an instance of the data collector set object and then call the IDataCollectorSet::Query method to query the properties of a previously persisted data collector set.

To create a set, create an instance of the data collector set object and set the properties as appropriate. You can set the properties individually or pass XML that contains the property values to the IDataCollectorSet::SetXml method.

To add new data collector objects to the set, retrieve the collection from the IDataCollectorSet::DataCollectors property. To persist the data collector set, call the IDataCollectorSet::Commit method.

You can start the data collectors manually using the IDataCollectorSet::Start method or automatically using the IDataCollectorSet::Schedules property. Alternatively, an alert can trigger a collection to run if the IAlertDataCollector::TriggerDataCollectorSet property is set.

If you want to manage the collected data, retrieve an IDataManager interface from the IDataCollectorSet::DataManager property.

The following example shows the XML elements for a data collector set. For details, see the corresponding property.

XML

Copy


<DataCollectorSet>
    <DataManager>
        <Enabled/>              <!-- 0 (false), nonzero (true) -->
        <CheckBeforeRunning/>   <!-- 0 (false), nonzero (true) -->
        <MinFreeDisk/>
        <MaxSize/>
        <MaxFolderCount/>
        <ResourcePolicy/>
        <ReportFileName/>
        <RuleTargetFileName/>
        <EventsFileName/>
        <FolderAction>          <!-- Include a <FolderAction> element for -->
            <Actions/>          <!-- each action to take. -->
            <Age/>
            <SendCabTo/>
            <Size/>
        </FolderAction>
    </DataManager>
    <Description/>
    <DescriptionUnresolved/>    <!-- Output only -->
    <DisplayName/>
    <DisplayNameUnresolved/>    <!-- Output only -->
    <Duration/>  
    <Keyword/>                  <!-- Specify for each keyword -->
    <LatestOutputLocation/>     
    <Name/>                     <!-- Output only -->
    <OutputLocation/>           <!-- Output only -->
    <RootPath/>
    <Segment/>
    <SegmentMaxDuration/> 
    <SegmentMaxSize/> 
    <SerialNumber/>
    <Server/>                   <!-- Output only -->
    <Status/>                   <!-- Output only -->
    <Subdirectory/>
    <SubdirectoryFormat/>
    <SubdirectoryFormatPattern/>
    <Task/>
    <TaskArguments/>
    <TaskRunAsSelf/>            <!-- 0 (false), -1 (true) -->
    <TaskUserTextArguments/>
    <Schedule>
        <Days/>
        <EndDate/>              <!-- mm/dd/yyyy -->
        <StartDate/>            <!-- mm/dd/yyyy -->
        <StartTime/>            <!-- hh:mm:ss (use 24-hour clock) -->
    </Schedule>
    <SchedulesEnabled/>         <!-- 0 (false), nonzero (true) -->
    <Security/>                 <!-- Security Descriptor Definition Language -->
    <StopOnCompletion/>         <!-- 0 (false), nonzero (true) -->
    <UserAccount/>              <!-- Output only. Set using SetCredentials --></DataCollectorSet>

If you call IDataCollectorSet::Xml to retrieve the XML for a set and the set includes data collectors, the XML will also contain the XML elements for each data collector in the set.

To use the data collector set elements to initialize the property values of a data collector set, call the SetXml method. The contents of the XML will overwrite the existing contents of the set. The following shows how to include the elements for the alert data collector.

XML