Main Page | Class Hierarchy | Class List | File List | Class Members | File Members

IDSSJobPriorityMap Interface Reference

List of all members.

Detailed Description

A job priority table specifies how a priority is assigned to a job request.

Requests waiting to be executed by the MicroStrategy Intelligence Server are placed on a queue. Instead of being executed in order of arrival the requests are assigned a priority. The way the server assigns a priority to waiting requests is configurable.
A DSS Server Definition object is used to store the configuration of a server. Among many other things this includes specifying how priorities are assigned to requests. The IDSSJobPriorityMap interface is used to expose this part of the definition of a server. It is found in two places:
A job priority map is a collection of map entries. Each entry describes a set of factors that might or might not be true for any particular request, and a priority (in the range 0 to 999). To determine the priority of a request the server uses the maximum priority of all entries of the map whose factors agree with the factors on the request. If none of the factors agree we use the value of the IDSSJobPriorityMap::DefaultPriority property instead.
One of these factors involves specifying a range for the cost of a report request. There are many different ways of obtaining a 'cost' for the report. The ReportCostWeight parameterized property assigns weights to the different possible ways of calculating a cost to obtain a single cost figure that is used by this map.
Please see the specification for IDSSJobPriorityEntry for a list of the other factors that are considered to attach a priority to a request.


Public Member Functions

HRESULT Add ([out, retval] IDSSJobPriorityMapEntry ppEntry)
 Create a new entry in the job priority map.
HRESULT Count ([out, retval] Int32 *pCount)
 Number of entries in the map.
HRESULT DefaultPriority ([in] Int32 DefaultPriority)
 The default priority assigned to jobs not covered by any entries.
HRESULT DefaultPriority ([out, retval] Int32 *pDefaultPriority)
 The default priority assigned to jobs not covered by any entries.
HRESULT Delete ([in] Int32 Index)
 Remove an entry specified by index number.
HRESULT DeleteByName ([in] BSTR Name)
 Delete a map entry specified by its name.
HRESULT Description ([in] BSTR Description)
 Description of this job priority map.
HRESULT Description ([out, retval] BSTR *pDescription)
 Description of this job priority map.
HRESULT Item ([in] Int32 Index,[out, retval] IDSSJobPriorityMapEntry ppEntry)
 Return an entry specified by index number.
HRESULT ItemByName ([in] BSTR Name,[out, retval] IDSSJobPriorityMapEntry ppEntry)
 This method returns a reference to a map entry that is specified by name.
HRESULT JobPriorityMapEntrys ([out, retval] IDSSJobPriorityMapEntrys ppJobPriorityMapEntrys)
 Alternative interface to the collection of map entries.
HRESULT Name ([in] BSTR Name)
 Unique name used to identify the job priority map.
HRESULT Name ([out, retval] BSTR *pName)
 Unique name used to identify the job priority map.
HRESULT ReportCostThreshold ([in] Int32 Index,[in] Int32 Threshold)
 Vector of integers that could be used as a system of thresholds.
HRESULT ReportCostThreshold ([in] Int32 Index,[out, retval] Int32 *pThreshold)
 Vector of integers that could be used as a system of thresholds.
HRESULT ReportCostThresholds ([in] Int32 N)
 Number of properties held by ReportCostThreshold.
HRESULT ReportCostThresholds ([out, retval] Int32 *pN)
 Number of properties held by ReportCostThreshold.
HRESULT ReportCostWeight ([in] EnumDSSReportCostFactor ReportCostFactor,[in] Int32 ReportCostWeight)
 Weights applied when calculating the cost of a report.
HRESULT ReportCostWeight ([in] EnumDSSReportCostFactor ReportCostFactor,[out, retval] Int32 *pReportCostWeight)
 Weights applied when calculating the cost of a report.

Member Function Documentation

HRESULT IDSSJobPriorityMap::Add (  [out, retval] IDSSJobPriorityMapEntry   ppEntry  ) 
 

Create a new entry in the job priority map.

Calling the method creates a new entry and inserts it in the map. The new entry is in an uninitialized state. The client should assign the properties on the IDSSJobPriorityMapEntry interface to specify the new map entry.

To be valid the entry's Priority property and at least one of the cost factors must be set.
Parameters:
ppEntry Pointer to the new entry that is just added to the map
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSJobPriorityMap::Count (  [out, retval] Int32 *  pCount  ) 
 

Number of entries in the map.

Parameters:
pCount Number of the priority map entries
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSJobPriorityMap::DefaultPriority (  [in] Int32  DefaultPriority  ) 
 

The default priority assigned to jobs not covered by any entries.

DefaultPriority is a numeric property. A job priority map contains a collection of map entries. A job is assigned a priority by taking maximum of the priorities assigned by all of the entries that apply to the job. This property specifies the priority that the server assigns to any job that is not covered by any of the map entries.

A priority is in the range 0 to 999.
Parameters:
DefaultPriority New value for default priority
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG DefaultPriority must be in the range 0 to 999

HRESULT IDSSJobPriorityMap::DefaultPriority (  [out, retval] Int32 *  pDefaultPriority  ) 
 

The default priority assigned to jobs not covered by any entries.

DefaultPriority is a numeric property. A job priority map contains a collection of map entries. A job is assigned a priority by taking maximum of the priorities assigned by all of the entries that apply to the job. This property specifies the priority that the server assigns to any job that is not covered by any of the map entries.

A priority is in the range 0 to 999.
Parameters:
pDefaultPriority Current value for DefaultPriority
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG DefaultPriority must be in the range 0 to 999

HRESULT IDSSJobPriorityMap::Delete (  [in] Int32  Index  ) 
 

Remove an entry specified by index number.

The entry is specified using its index number in the collection. After deleting the entry the other entries are renumbered so that they are in the same relative order.

Parameters:
Index The index of the entry in the map The number should be in the range 1 to Count
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_INDEX_OUT_OF_RANGE Index number is not in correct range

HRESULT IDSSJobPriorityMap::DeleteByName (  [in] BSTR  Name  ) 
 

Delete a map entry specified by its name.

The names of entries are case insensitive. After deleting an entry, the following entries are renumbered in the usual manner.

No attempt is made to make entries have unique names. This call deletes the first entry with the given name when there are multiple entries with same name.
Parameters:
Name The name of the entry
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_KEY_NOT_FOUND No entries of the given name exist in the map

HRESULT IDSSJobPriorityMap::Description (  [in] BSTR  Description  ) 
 

Description of this job priority map.

Description is a string-valued property. It is an arbitrary string value that is stored with the map. The intention is that it should be used to clarify the prioritization policy that was used to define this map.

Parameters:
Description Description of the priority map
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSJobPriorityMap::Description (  [out, retval] BSTR *  pDescription  ) 
 

Description of this job priority map.

Description is a string-valued property. It is an arbitrary string value that is stored with the map. The intention is that it should be used to clarify the prioritization policy that was used to define this map.

Parameters:
pDescription Description of the priority map
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSJobPriorityMap::Item (  [in] Int32  Index,
[out, retval] IDSSJobPriorityMapEntry   ppEntry
) 
 

Return an entry specified by index number.

Refer to the member by his or her index number.

Item is the default method on the interface.
Use the JobPriorityMapEntrys property to obtain an item method on the same collection that takes a Variant parameter.
Parameters:
Index Index of the item to return The index number should be in the range 1 to Count
ppEntry Address to receive the map entry interface pointer
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_INDEX_OUT_OF_RANGE Index number is not in correct range

HRESULT IDSSJobPriorityMap::ItemByName (  [in] BSTR  Name,
[out, retval] IDSSJobPriorityMapEntry   ppEntry
) 
 

This method returns a reference to a map entry that is specified by name.

The name comparison is case insensitive.

No attempt is made to make entries have unique names. This call returns the first entry with the given name when there are multiple entries with the same name.
Parameters:
Name Name of the item
ppEntry Address to receive the map entry interface pointer
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_KEY_NOT_FOUND No entries of the given name exist in the map

HRESULT IDSSJobPriorityMap::JobPriorityMapEntrys (  [out, retval] IDSSJobPriorityMapEntrys   ppJobPriorityMapEntrys  ) 
 

Alternative interface to the collection of map entries.

JobPriorityMapEntries is a read-only object property. It returns a collection interface to the entries in this job priority map.

The interface provides access to the same contents as are available from this interface.
The only reason to use this property is if you want to use an interface whose methods and properties follow the usual COM collection conventions. In particular the IDSSJobPriorityMapEntrys interface has a _NewEnum method, which is not found on IDSSJobPriorityMap.
Parameters:
ppJobPriorityMapEntrys The collection of all map entries
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSJobPriorityMap::Name (  [in] BSTR  Name  ) 
 

Unique name used to identify the job priority map.

Name is a string-valued property. It assigns a name to the map. We do not enforce the uniqueness of the name.

We apply the usual restrictions on which strings we allow for a valid name.
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_NAME_REQUIRED The name cannot be an empty string.
  • DSSCOM_E_NAME_TOO_LONG Too many characters in the proposed name.
  • DSSCOM_E_NAME_INVALID_CHAR Forbidden character in the proposed name.

HRESULT IDSSJobPriorityMap::Name (  [out, retval] BSTR *  pName  ) 
 

Unique name used to identify the job priority map.

Name is a string-valued property. It assigns a name to the map. The name does not have to be unique.

We apply the usual restrictions on which strings we allow for a valid name.
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_NAME_REQUIRED The name cannot be an empty string.
  • DSSCOM_E_NAME_TOO_LONG Too many characters in the proposed name.
  • DSSCOM_E_NAME_INVALID_CHAR Forbidden character in the proposed name.

HRESULT IDSSJobPriorityMap::ReportCostThreshold (  [in] Int32  Index,
[in] Int32  Threshold
) 
 

Vector of integers that could be used as a system of thresholds.

ReportCostThreshold is a parameterized numeric property. It takes parameters in the range 0 to the current value of the ReportCostThresholds property.

The intention of this parameterized property is to allow a GUI to record in the metadata a series of thresholds (for example low, medium and high) which are stored individually for each job priority map.
The values held by this parameterized property have no effect on the behavior of the Server.
Parameters:
Index Parameter of the required property. Number should be in range 0 to ReportCostThresholds minus 1.
Threshold New value for this threshold. Any integer value is allowed.
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG Index should be in the range 0 to ReportCostThresholds.

HRESULT IDSSJobPriorityMap::ReportCostThreshold (  [in] Int32  Index,
[out, retval] Int32 *  pThreshold
) 
 

Vector of integers that could be used as a system of thresholds.

ReportCostThreshold is a parameterized numeric property. It takes parameters in the range 0 to the current value of the ReportCostThresholds property.

The intention of this parameterized property is to allow a GUI to record in the metadata a series of thresholds (for example low, medium and high) which are stored individually for each job priority map.
The values held by this parameterized property have no effect on the behavior of the Server.
Parameters:
Index Parameter of the required property. Number should be in range 0 to ReportCostThresholds minus 1.
pThreshold Existing value for this threshold.
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG Index should be in the range 0 to ReportCostThresholds.

HRESULT IDSSJobPriorityMap::ReportCostThresholds (  [in] Int32  N  ) 
 

Number of properties held by ReportCostThreshold.

ReportCostThresholds is a numeric property. It records the number of threshold values that are stored in the parameterized property ReportCostThreshold.

This property default to zero. Changing this property resets all values of the parameterized property ReportCostThreshold. The default values for the parameterized property are values evenly spaced between 0 and 1000, the largest value always being 1000.
The value of this property has no effect on the behavior of the Server.
Parameters:
N New value for ReportCostThresholds.
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG This property must lie in the range 0 to 500.

HRESULT IDSSJobPriorityMap::ReportCostThresholds (  [out, retval] Int32 *  pN  ) 
 

Number of properties held by ReportCostThreshold.

ReportCostThresholds is a numeric property. It records the number of threshold values that are stored in the parameterized property ReportCostThreshold.

This property default to zero. Changing this property resets all values of the parameterized property ReportCostThreshold. The default values for the parameterized property are values evenly spaced between 0 and 1000, the largest value always being 1000.
The value of this property has no effect on the behavior of the Server.
Parameters:
pN Current value of ReportCostThresholds.
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG This property must lie in the range 0 to 500.

HRESULT IDSSJobPriorityMap::ReportCostWeight (  [in] EnumDSSReportCostFactor  ReportCostFactor,
[in] Int32  ReportCostWeight
) 
 

Weights applied when calculating the cost of a report.

ReportCostWeight is a parameterized numeric property. It records for each of the appropriate reports costs a weighting factor.

There are several different ways of obtaining a cost for a report. For example, we have a historic cost and the user-supplied cost. For simplicity a job priority map entry uses a single report cost value. This value is obtained by summing the various other cost measures. Each measure is given a weight so the administrator can choose which costs should have more significance for the map.
A weight is a positive integer, or zero. A weight of zero means that a given cost factor does not contribute to the report's cost. This property defaults to zero.
This is the enumeration EnumDSSReportCostFactor of possible report cost factors.
Name Value Meaning
DssReportCostUserSupplied 1 The cost supplied by the user for the report. This cost is read from the UserSuppliedCost property on IDSSReportDefinition.
DssReportCostEstimated 2 The system's estimate for the cost of this report.
DssReportCostHistorical 3 The (average) cost of this report from previous executions. This cost is read from the HistoricalCost property on IDSSReportDefinition.
DssReportCostResultSetSize 4 The cost obtained from the size of the result set. This cost is not available until after the report's SQL has been executed.
Parameters:
ReportCostFactor Report cost factor from the EnumReportCostFactor.
ReportCostWeight The new weight for the given cost factor.
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG Either ReportCostFactor is not a value in the enumeration, or ReportCostWeight is negative.

HRESULT IDSSJobPriorityMap::ReportCostWeight (  [in] EnumDSSReportCostFactor  ReportCostFactor,
[out, retval] Int32 *  pReportCostWeight
) 
 

Weights applied when calculating the cost of a report.

ReportCostWeight is a parameterized numeric property. It records for each of the appropriate reports costs a weighting factor.

There are several different ways of obtaining a cost for a report. For example, we have a historic cost and the user-supplied cost. For simplicity a job priority map entry uses a single report cost value. This value is obtained by summing the various other cost measures. Each measure is given a weight so the administrator can choose which costs should have more significance for the map.
A weight is a positive integer, or zero. A weight of zero means that a given cost factor does not contribute to the report's cost. This property defaults to zero.
This is the enumeration EnumDSSReportCostFactor of possible report cost factors.
Name Value Meaning
DssReportCostUserSupplied 1 The cost supplied by the user for the report. This cost is read from the UserSuppliedCost property on IDSSReportDefinition.
DssReportCostEstimated 2 The system's estimate for the cost of this report.
DssReportCostHistorical 3 The (average) cost of this report from previous executions. This cost is read from the HistoricalCost property on IDSSReportDefinition.
DssReportCostResultSetSize 4 The cost obtained from the size of the result set. This cost is not available until after the report's SQL has been executed.
Parameters:
ReportCostFactor Report cost factor from the EnumReportCostFactor.
pReportCostWeight The current value of the weight.
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG Either ReportCostFactor is not a value in the enumeration, or ReportCostWeight is negative.

Copyright © 1996-2018 MicroStrategy Inc. All Rights Reserved.