IDataCollectorSet::Commit method (pla.h)
Saves, updates, or validates the data collector set. You can also use this method to flush a trace session.
Syntax
HRESULT Commit(
[in] BSTR name,
[in] BSTR server,
[in] CommitMode mode,
[out] IValueMap **validation
);
Parameters
[in] name
A unique name used to save the data collector set. The name is of the form [Namespace]Name. For details, see Remarks.
[in] server
The computer on which you want to save the set. You can specify a computer name, a fully qualified domain name, or an IP address (IPv4 or IPv6 format). If NULL, the set is saved to the local computer.
[in] mode
Indicates whether you want to save, update, flush, or validate the data collector set. For possible values, see the CommitMode enumeration.
[out] validation
An IValueMap interface that you use to retrieve the validation error of each property whose value is not valid or is ignored. The IValueMap::Count property is zero if there were no errors or warnings.
Return value
Returns S_OK if the method call was successful. You must check the value map for errors (see Remarks). If the method returns S_OK and there are no validation errors, then the set was successfully committed. The following table shows possible error values when calling this method.
| Return code/value | Description |
|---|---|
|
The user must be running as an administrator. |
|
The specified namespace is not supported (for example, if you specified the System namespace when committing the data collector set on a computer running an operating system prior to Windows Vista). |
|
The RPC server is not available. The method is unable to save the data collector set remotely. To commit remotely to a computer running Windows Vista, enable Performance Logs and Alerts in Windows Firewall Settings on the remote computer. |
|
You are trying to commit a new set, but a set with the specified name already exists. |
Remarks
If you save the set, use the specified name and server parameter values when calling the IDataCollectorSet::Query method to retrieve the set.
The name parameter can contain an optional namespace; however, you should always specify the namespace. If you do not specify the namespace, PLA uses "Service" for computers running Windows Vista and "Legacy" for computers running operating systems prior to Windows Vista. The following table lists the possible namespace values.
| Namespace | Description |
|---|---|
| Autosession | Contains ETW AutoLogger sessions. The collector starts when the computer starts, cannot be stopped, and the status is undefined. |
| Legacy | Same as Service but on computers running an operating system that is prior to Windows Vista. |
| Service | Contains all data collector sets created by the user. These sets can be scheduled and can be set to run as anyone. The user needs the Log on as a batch job account right (see Administrative Tools, Local Security Policy, Local Policies, User Rights Assignment). If you do not specify credentials, the set will run as LocalSystem (if the user is an administrator). |
| Session | Contains Event Tracing for Windows (ETW) trace sessions. These sets cannot be scheduled. If you use this namespace, the set must contain only one data collector and it must be a trace data collector. |
| System | Contains read-only data collector sets that cannot be scheduled; however, you can start these sets manually. If you do not specify credentials, the set will run as the current user. |
Note that the Service namespace can be used in place of the Legacy namespace on computers running operating systems prior to Windows Vista.
To determine the validation errors that occurred, retrieve the IValueMapItem interface for each error in the value map collection. The IValueMapItem::Key property contains the XPath of the element in error, for example, /AlertDataCollector/TaskArguments. The IValueMapItem::Value property contains the HRESULT value, which can be an error or warning (success code). The IValueMapItem::Description property contains the message text associated with the error.
Typically, any errors that occur will be one of the following HRESULT values in the value map collection.
| Error | Description |
|---|---|
| PLA_S_PROPERTY_IGNORED | The property is not used. PLA uses this warning to disable the item in its UI so the user knows the property is being ignored. |
| PLA_E_PROPERTY_CONFLICT | The property conflicts with another property, for example, both LogAppend and LogCircular are VARIANT_TRUE. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | pla.h |
| DLL | Pla.dll |