IDSSRelationshipNode Interface Reference

List of all members.

---

Detailed Description

A DSS Expression is a tree structure built up of objects called nodes.

Each node has a type, and a type-specific interface, which is used to expose properties that are only possessed by nodes of the given type.

The interface IDSSRelationshipNode is the type-specific interface for a DSS Relationship node. This is a node that represents a relationship between attributes. We use the same relationship concept to tell the DSS Engine how two attributes are related in a schema and how to relate attributes when extending a fact to a new attribute.

A relationship node is used to construct relationship filter objects. A relationship filter expresses a filter on elements of one attribute by actually giving a restriction on another attribute. The relationship is needed to indicate how the two attributes should be related for the filter.

We expect a relationship node to be used in the following manner:

• It is not a leaf node. Like the Operator Node it can have child nodes. We expect it to have a single child node, which contains a sub-expression. The relationship is applied to this sub-expression.
• The node has an Output level dimensionality. This dimensionality is really only a list of attributes. It contains the attributes to which we are relating the sub-expression.

For example you could use a relationship filter to ask for a list of all the destination cities of flights from Denver, which have had to be refunded. The base filter would say Source = Denver. The relationship node asks for output at the Destination City level and states that 'Source City' and Destination City should be related by the Refund amount fact. The filter acts like it is a list of destination cities like Destination-City IN (Chicago, New York, Bolder).

Public Member Functions
HRESULT	ApplySubExpression ([in] VARIANT_BOOL ApplySubExpression)
	Whether we apply sub-expression as well as use it for relationship.
HRESULT	ApplySubExpression ([out, retval] VARIANT_BOOL *pApplySubExpression)
	Whether we apply sub-expression as well as use it for relationship.
HRESULT	Node ([out, retval] IDSSNode ppNode)
	The node on which this time appears Node is a read-only property.
HRESULT	Prompt ([in] IDSSPrompt *pPrompt)
	The prompt used to define the relationship.
HRESULT	Prompt ([out, retval] IDSSPrompt ppPrompt)
	The prompt used to define the relationship.
HRESULT	Relationship ([out, retval] IDSSRelationship ppRelationship)
	The relationship used to relate the attributes Relationship is a read-only relationship valued property.
HRESULT	UseSchema ([in] VARIANT_BOOL UseSchema)
	Whether we use the relationship from the schema.
HRESULT	UseSchema ([out, retval] VARIANT_BOOL *pUseSchema)
	Whether we use the relationship from the schema.

---

Member Function Documentation

HRESULT IDSSRelationshipNode::ApplySubExpression (  [in] VARIANT_BOOL  ApplySubExpression  )

Whether we apply sub-expression as well as use it for relationship. True = apply sub-expression as well as use it for relationship ApplySubExpression is a Boolean property. Under normal use in a filter, the subexpression below the relationship node is converted to a different filter by applying the relationship on this node. The expression is not used, other than as a source for the relationship. Setting this property to True asks that the sub-expression is applied in its own right as well. For example, in the introduction we described how a relationship filter could specify all of the destinations from Denver on which an airline had paid out refunds. The resulting filter behaved like a list of destination cities, like Destination-City IN (Chicago, New York, Bolder). Setting this property to true keeps the underlying restriction Source-City = Denver. So the filter would behave like Source-City = Denver and Destination-City IN (Chicago, New York, Bolder). This is a different filter. ApplySubExpression is set to False on a new relationship node. The Engine team internal documents use the symbol a (alpha) to represent a relationship in which this property has been set to True. Parameters: ApplySubExpression  New value for the property Returns: Usual COM result code: S_OK

HRESULT IDSSRelationshipNode::ApplySubExpression (  [out, retval] VARIANT_BOOL *  pApplySubExpression  )

Whether we apply sub-expression as well as use it for relationship. True = apply sub-expression as well as use it for relationship ApplySubExpression is a Boolean property. Under normal use in a filter, the subexpression below the relationship node is converted to a different filter by applying the relationship on this node. The expression is not used, other than as a source for the relationship. Setting this property to True asks that the sub-expression is applied in its own right as well. For example, in the introduction we described how a relationship filter could specify all of the destinations from Denver on which an airline had paid out refunds. The resulting filter behaved like a list of destination cities, like Destination-City IN (Chicago, New York, Bolder). Setting this property to true keeps the underlying restriction Source-City = Denver. So the filter would behave like Source-City = Denver and Destination-City IN (Chicago, New York, Bolder). This is a different filter. ApplySubExpression is set to False on a new relationship node. The Engine team internal documents use the symbol a (alpha) to represent a relationship in which this property has been set to True. Parameters: pApplySubExpression  True = (in a filter) keep the restriction of the sub-expression False = (in a filter) only use the sub-expression as a source for the relationship Returns: Usual COM result code: S_OK

HRESULT IDSSRelationshipNode::Node (  [out, retval] IDSSNode   ppNode  )

The node on which this time appears Node is a read-only property. It returns the IDSSNode interface associated with this node. This interface contains methods and properties that are common to all types of nodes in expressions. In particular it contains methods used to navigate between different nodes in the expression. Parameters: ppNode  The node interface of this node. Never NULL. Returns: Usual COM result code: S_OK

HRESULT IDSSRelationshipNode::Prompt (  [in] IDSSPrompt *  pPrompt  )

The prompt used to define the relationship. Prompt is a read-write prompt-valued property. It contains a prompt that can be used to modify the relationship in this node. There is no Exports property on this interface, since the only place to export prompts is into this prompt. If the user wants to do this she would use the prompt's ExportsToPrompt collection. Parameters: pPrompt  The new value of the prompt. May be NULL. Prompt question = use as underlying prompt instance. Prompt instance (this object) = use this instance. Other prompt instance = use underlying prompt object. Prompt object = use first instance in this object based on this prompt object. Returns: Usual COM result code: S_OK RESSVR_E_NOT_PROMPTABLE Cannot set the prompt because this application object doesn't support prompts. OBJSVR_E_NO_PROMPT_TYPE This prompt has not been given a prompt type. OBJSVR_E_CONFLICTS_PROMPT_TYPE Can't use this prompt - it is not a suitable type.

HRESULT IDSSRelationshipNode::Prompt (  [out, retval] IDSSPrompt   ppPrompt  )

The prompt used to define the relationship. Prompt is a read-write prompt-valued property. It contains a prompt that can be used to modify the relationship in this node. There is no Exports property on this interface, since the only place to export prompts is into this prompt. If the user wants to do this she would use the prompt's ExportsToPrompt collection. Parameters: ppPrompt  A prompt instance from the DSS Object that contains this node. NULL if the node has no prompt. Returns: Usual COM result code: S_OK RESSVR_E_NOT_PROMPTABLE Cannot set the prompt because this application object doesn't support prompts. OBJSVR_E_NO_PROMPT_TYPE This prompt has not been given a prompt type. OBJSVR_E_CONFLICTS_PROMPT_TYPE Can't use this prompt - it is not a suitable type.

HRESULT IDSSRelationshipNode::Relationship (  [out, retval] IDSSRelationship   ppRelationship  )

The relationship used to relate the attributes Relationship is a read-only relationship valued property. It returns an interface with parameters used to specify a relationship. There are many ways to do this, and the interface has several enumeration properties used to specify join type, join attributes and so on. However in the context of a relationship filter, by far the most common type of relationship is to specify a fact. The user does this by setting the Relationship.RelationshipType property to DssExtnTypeFact, and setting the Relationship.Guide property to the chosen fact. Note that since UseSchema defaults to True, a user must set UseSchema to False before attempting to use the Relationship property. If the user sets UseSchema to True then the user has asked to use the relationship in the schema rather than define a specific relationship in the expression node. It this case this property returns NULL. Parameters: ppRelationship  The DSSRelationship object. NULL if UseSchema is set to True Returns: Usual COM result code: S_OK

HRESULT IDSSRelationshipNode::UseSchema (  [in] VARIANT_BOOL  UseSchema  )

Whether we use the relationship from the schema. True = use relationship from the schema. UseSchema is a Boolean property. It records whether the user wants to use the relationship in the schema (True) or instead apply a specific relationship given in this node (False). If the property is True then there is no Relationship object in this node and the Relationship property returns NULL. In this case the engine uses whatever relationship between the attributes is contained in the standard schema. This could be a normal parent-child refinement relationship, or it could be a many-to-many relationship. This property is set to True on a new relationship node. Setting UseSchema to True and then setting it back to False retains the values on the relationship object on an instance of this node held in memory. However if a user saves an expression with UseSchema set to True and then reloads it and sets UseSchema to False the user finds that the values on the relationship object were not saved with the expression. Parameters: UseSchema  New value for the property. Returns: Usual COM result code: S_OK

HRESULT IDSSRelationshipNode::UseSchema (  [out, retval] VARIANT_BOOL *  pUseSchema  )

Whether we use the relationship from the schema. True = use relationship from the schema UseSchema is a Boolean property. It records whether the user wants to use the relationship in the schema (True) or instead apply a specific relationship given in this node (False). If the property is True then there is no Relationship object in this node and the Relationship property returns NULL. In this case the engine uses whatever relationship between the attributes is contained in the standard schema. This could be a normal parent-child refinement relationship, or it could be a many-to-many relationship. This property is set to True on a new relationship node. Setting UseSchema to True and then setting it back to False retains the values on the relationship object on an instance of this node held in memory. However if a user saves an expression with UseSchema set to True and then reloads it and sets UseSchema to False the user finds that the values on the relationship object were not saved with the expression. Parameters: pUseSchema  True = this node does not have its own relationship object False = this node has its own relationship object Returns: Usual COM result code: S_OK

---