PropertyHandle :: GetPropertyHandle - Get property handle
The function returns the property handle for the selected path. The function handles property paths within a structure instance (e.g. location.city, where city is a member of the embedded Address structure of location), as well as paths that include references (mother.name, where mother is a reference to a persons (Person) mother). One must not pass path properties or operation path to the function, i.e. the path must not refer to operations or selector or iterator operators (mother(0).name is not a valid property path).
When referring to transient references one has to take into account that the data source referenced by the transient reference may change during processing. This affects the type of referenced instances as well as the referenced collection or instance.
When using the GetPropertyHandle() function instead of using a property handle constructor, the cursor and the data source are shared with other property handles provided by this function.
For creating a shared subordinated property handle one may use the constructor in combination with the GetPropertyHandle() function:
PropertyHandle ph(parent.GetPropertyHandle(prop_path));
or the corresponding PropertyHandle::Open() function.
GetPropertyHandle() returns a so-called static property handle, which is not able to react on type changes in upper weak-typed property handles. To avoid problems with static property handles (error 348) create a shared property handle as described above.
In order to create access handles for more complex path definitions one may use the PropertyHandle::Open() function or the constructor, which also supports property and operation paths. This allows opening property handles for queries of any complexity.
Is a pointer to an (usually) opened property handle.
Implementation overview
- Get property handle with transient option
PropertyHandle :: GetPropertyHandle ( prop_path, transient_ref ) - Simplified call for GetPropertyHandle
PropertyHandle :: GetPropertyHandle ( prop_path )
Implementation details
-
Get property handle with transient option
PropertyHandle * PropertyHandle :: GetPropertyHandle ( NString &prop_path, logical *transient_ref )
In addition to the property handle, the function returns, whether the property handle is a transient property or not.
- prop_path
- Property path
A property path is passed as 0-terminated string. It may contain an extent or property name but also a sequence of property names separated by dot.
Property path may start with a dot (.), which indicates, that the path starts in an upper property handle. One dot indicates, that the path starts in the current property handle. This distinction becomes necessary, when a property has the same name as an extent. To access the property in this case, one dot must precede the property name. The first dot can be omitted, when the property name is not an extent name.
Referring to a path starting in a parent property handle requires two dots (..), the parents parent three and so on.
address.street
.address.street
- transient_ref
- Transient option
The option indicates, whether the property is a transient property or not.
to list
- prop_path
- Property path
-
Simplified call for GetPropertyHandle
PropertyHandle * PropertyHandle :: GetPropertyHandle ( NString &prop_path )
The implementation has been provided for convenience reasons to avoid the requirement of passing a transient reference, which is not requires in most cases.
- prop_path
- Property path
A property path is passed as 0-terminated string. It may contain an extent or property name but also a sequence of property names separated by dot.
Property path may start with a dot (.), which indicates, that the path starts in an upper property handle. One dot indicates, that the path starts in the current property handle. This distinction becomes necessary, when a property has the same name as an extent. To access the property in this case, one dot must precede the property name. The first dot can be omitted, when the property name is not an extent name.
Referring to a path starting in a parent property handle requires two dots (..), the parents parent three and so on.
address.street
.address.street
to list
- prop_path
- Property path