Functions: Properties

The functions described in this chapter allow for setting or reading the properties of an object in the database.

eplGetProperty

EplHandle
eplGetProperty( EplSession        session,
                EplHandle        objHandle,
                EplProperty        prop,
                EplIndex        idx,
                EplChar*        buf,
                EplSize                buflen);

Reads the property of an object.

Most objects in EPLAN 21 have their list of possible properties. These properties can be queried via the eplGetProperty function which, at the moment, returns all data types as UNICODE character strings.

Return Description
EplHandle The function returns EPL_OK if the property of the object could be read. If this is not the case, EPL_ERROR is returned.
Input Type Description
session EplSession Session ID of the object handle.
prop EplProperty ID of the property which could be queried.
prop EplProperty ID of the property which is to be queried.
idx EplIndex Index of the property which is to be queried.
buf EplChar* If successful, this character buffer contains the value of the property as character string.
buflen EplSize Length of the character buffer buf.

eplGetPropertyExpanded

EplHandle
eplGetPropertyExpanded(EplSession        session,
                       EplHandle        objHandle,
                       EplProperty        prop,
                       EplIndex                idx,
                       EplChar*                buf,
                       EplSize                buflen);

Reads the expanded property of an object. The returned property value depends on the language set and must not be written back via eplSetProperty.

While the eplGetProperty function of the example above would return the value @V=00@DE=deutscher Text;EN=German text, the function eplGetPropertyExpanded would return the value German text.

Return Description
EplHandle The function returns EPL_OK if the property of the object could be read. If this is not the case, EPL_ERROR is returned.
Input Type Description
session EplSession Handle of the session to which the objHandle handle belongs.
objHandle EplHandle Handle of the object whose expanded property is to be determined.
prop EplProperty ID of the property which is to be determined.
idx EplIndex Index of the property.
buf EplChar* Character buffer into which the value of the expanded property is to be written.
buflen EplSize Length of the buffer for the expanded property.

eplGetPropertyUser

EplHandle
eplGetPropertyUser(EplSession        session,
                   EplHandle        propUser,
                   EplProperty        indProp,
                   EplIndex        idx);

This function serves the navigation through the data model. This way you may, e.g., use an indirect property to determine the project of a page.

In contrast to the functions described above, this function returns no property values, but a handle to the object to which an indirect property refers. Using this handle, you can query all properties of this object.

Return Description
EplHandle Handle of the object which is referenced by the indirect property.
Input Type Description
session EplSession Handle of the session to which the propUser object belongs.
propUser EplHandle Handle of the object whose indirect property is to be determined.
indProp EplProperty ID of the indirect property
idx EplIndex Index of the indirect property (the value of idx is 0 for a non-indexed property).

eplSetProperty

EplHandle
eplSetProperty( EplSession        session,
                EplHandle        objHandle,
                EplProperty        prop,
                const EplChar*        val,
                EplIndex        idx );

Sets the value of the property of an object in the database.

All writable direct properties of an object can be assigned via the eplSetProperty function.

Please note that the eplSetProperty function does not carry out a semantic check of your entries so that you can principally use any property for each type of object. If you try to use reserved IDs or enter invalid values, this may lead to unintentional results.

Return Description
EplHandle If successful, EPL_OK is returned, otherwise EPL_ERROR.
Input Type Description
session EplSession Handle of the session to which the object belongs whose property is to be set.
objHandle EplHandle Handle of the object whose property is to be set.
prop EplProperty ID of the property which is to be set.
val const EplChar* New property value.
idx EplIndex Index of the property which is to be set.