company logo

PropertyHandle :: Open - Open property handle

Open property handle opens a property handle for a persistent or transient data source. A data source is a collection, object instance or an elementary database field. A data source contains the data for a property of a specific object. Usually property handles are opened when constructing them. You can, however, create an unopened property handle using the dummy constructor (without parameters) or by closing another property handle.

If the property handle to be opened is a subsequent property handle the parent must be opened. The data source provided in the subsequent property handle depends on the parents property handle current selection and will be provided automatically whenever the parent property handle changes its current selection.

You can open static property handles for constants or other elementary data sources as well as for structured instances or transient collections using the appropriate open function.

When applying the Open() function to a property handle that has been opened previously the handle is closes implicitly before reopening. You cannot reopen property handles that have been provided with GetPropertyHandle().

When creating a copy handle sort order and selected instance are set in the copy handle as well.

Paul Millers children are the data source for the property 'children' of the person 'Paul Miller', as well as 'Paul' is the data source for his 'name' property.

Return value:  Success ( logical  )

Implementation overview

Implementation details

  1. Open property handle for a 64-bit integer value
    logical PropertyHandle  :: Open ( int64 int64_val )

    The function opens an unbound property handle for a platform independent 64-bit integer value (int64, INT(17)).
    • int64_val - 64 bit integer value
    2. to list
  2. Open property handle for a logical value
    logical PropertyHandle  :: Open ( logical logval )

    The function opens an unbound property handle for a logical value (LOGICAL).
    • logval - Logical value

      Is a logical (bool) value.
    3. to list
  3. Open subordinated property handle
    logical PropertyHandle  :: Open ( PropertyHandle &prop_hdl, NString &prop_path )

    The function opens a subordinated property handle of the instance. Since the property handles for instance properties are part of the instance the function creates a copy handle with an own cursor. It behaves, however, like a normal subordinated property handle, that depends on the selection in the upper property handle (if there is any).
    • prop_hdl - Property Handle

      Is a reference to an (usually) opened property handle.
    • 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
    4. to list
  4. - internal feature (not documented)
    logical PropertyHandle  :: Open ( PropertyHandle &prop_hdl, NString &prop_path, OperEnvironment *operenv )
    • prop_hdl - Property Handle

      Is a reference to an (usually) opened property handle.
    • 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
    • operenv - Pointer to operation environment
    5. to list
  5. Open subordinated property handle
    logical PropertyHandle  :: Open ( PropertyHandle *property_handle, NString &prop_path )

    The constructor provides a subordinated property handle of the instance. Since property handles for an instance are part of the instance the function provides a property handle that shares area and cursor with the property handle in the instance. As subordinated property handle it depends on the selection in the upper property handle (if there is any).
    • property_handle - Pointer to property handle

      Is a pointer to an (usually) opened property handle.
    • 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
    6. to list
  6. - internal feature (not documented)
    logical PropertyHandle  :: Open ( PropertyHandle *property_handle, NString &prop_path, OperEnvironment *operenv )
    • property_handle - Pointer to property handle

      Is a pointer to an (usually) opened property handle.
    • 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
    • operenv - Pointer to operation environment
    7. to list
  7. - internal feature (not documented)
    logical PropertyHandle  :: Open ( char *string, StringCoding coding_type, logical conv_opt=NO )
    • string - C string
    • coding_type - - internal feature (not documented)
    • conv_opt - Data conversion required Default: NO
    8. to list
  8. Open property handle for a string value
    logical PropertyHandle  :: Open ( char *cstring, logical conv_opt=NO )

    The function opens an unbound property handle for a string value (STRING). The area is allocated with the size of the string passed to the constructor. The string is copied into the instance area owned by the property handle. To enable dynamical re-size feature for the property handle use the SetDynLength() function.
    • cstring - C string

      Usually, the string has to be 0-terminated, but there might be exceptions.
    • conv_opt - Data conversion required Default: NO
    9. to list
  9. - internal feature (not documented)
    logical PropertyHandle  :: Open ( NString &cnstring, logical conv_opt=NO )
    • cnstring - String containing the text
    • conv_opt - Data conversion required Default: NO
    10. to list
  10. - internal feature (not documented)
    logical PropertyHandle  :: Open ( utf16char *utfstr_c, logical conv_opt=NO )
    • utfstr_c - - Title unknown
    • conv_opt - Data conversion required Default: NO
    11. to list
  11. Open non sharing copy for a property handle
    logical PropertyHandle  :: Open ( PropertyHandle &cprop_hdl )

    The function opens a copy of the passed property handle with an own cursor and an own instance area. When the origin has set a filter condition (selection), this is copied as well.

    • cprop_hdl - Property Handle
    12. to list
  12. Open property handle for a date value
    logical PropertyHandle  :: Open ( dbdt date_val )

    The function opens an unbound property handle for a date value (DATE).
    • date_val - Date value

      The data value is passed in the internal data format.
    13. to list
  13. Open property handle for a double value
    logical PropertyHandle  :: Open ( double dbl_value )

    The function opens an unbound property handle for a double value (REAL(15)).
    • dbl_value - Double value

      A double value is a 64 bit floating number.
    14. to list
  14. Open extent property handle
    logical PropertyHandle  :: Open ( DBObjectHandle &object_handle, NString &extnames, PIACC accopt, logical transient_w=NO, NString &key_name_w=NString::Null() )

    The function opens a property handle for a global collection (extent). The extent name passed may contain symbolic references to system variables (e.g. "%EXT_PREF%Pers") which are resolved according to the current setting of the referenced system variables. A key name can be passed to set the sort order for the property handle. If no key is passed the sort order is set to the default order.

    You may open a transient extent that stores data only in main storage by passing the transient_w option.

    • object_handle - Database Object handle

      This is a pointer to an opened Database Object handle.
    • extnames - Extent name

      The name contains the name of the extent, only. It does not contain a namespace scope.
      Notes:

      retval checked for const &NString
    • accopt - Access mode
    • transient_w - Transient option

      To create transient property handles transient=YES has to be passed. In this case the property handle instances and indexes are stored in main storage, only.

      Default: NO
    • key_name_w - Key name for conversion Default: NString::Null()
    15. to list
  15. Open property handle for a float value
    logical PropertyHandle  :: Open ( float float_val )

    The function opens an unbound property handle for a double value (REAL(7)).
    • float_val - Float value

      Float values are 32 bit floating numbers.
    16. to list
  16. Open property handle for a 32-bit integer value
    logical PropertyHandle  :: Open ( int32 int_val )

    The function opens an unbound property handle for a platform independent 32-bit integer value (int32, INT(10)).
    • int_val - Integer value
    17. to list
  17. Open a sharing copy for a property handle
    logical PropertyHandle  :: Open ( PropertyHandle *property_handle )

    The function opens a copy of the passed property handle that shares the instance area and cursor with its origin.
    • property_handle - Pointer to property handle

      Is a pointer to an (usually) opened property handle.
    18. to list
  18. Open property handle for a 16-bit integer value
    logical PropertyHandle  :: Open ( int16 short_val )

    The function opens an unbound property handle for a platform independent 16-bit integer value (int16, INT(4)).
    • short_val - short_val - Title unknown
    19. to list
  19. - internal feature (not documented)
    logical PropertyHandle  :: Open ( NString &cnstring, int32 string_len )
    • cnstring - String containing the text
    • string_len - String length

      The string length defines the maximum number of characters that can be stored in the string area without counting the terminating 0. Usually this value is 1 less that the allocated string area.
    20. to list
  20. Open property handle for a string value
    logical PropertyHandle  :: Open ( char *string, int32 string_len )

    The function opens an unbound property handle for a string value (STRING). The area is set to the string pointer passed to the function.
    • string - C string
    • string_len - String length

      The string length defines the maximum number of characters that can be stored in the string area without counting the terminating 0. Usually this value is 1 less that the allocated string area.
    21. to list
  21. Open property handle for a 8-bit integer value
    logical PropertyHandle  :: Open ( int8 int8_val )

    The function opens an unbound property handle for a platform independent 8-bit integer value (int8, INT(2)).
    • int8_val - - internal feature (not documented)
    22. to list
  22. Open property handle for a time value
    logical PropertyHandle  :: Open ( dbtm time_val )

    The function opens an unbound property handle for a time value (TIME).
    • time_val - Time value

      The time value is passed in the internal data format.
    23. to list
  23. Open property handle for a date/time value
    logical PropertyHandle  :: Open ( dttm datetime_val )

    The function opens an unbound property handle for a date/time value (DATETIME).
    • datetime_val - Date time value
    24. to list
  24. Open property handle for an unsigned 64-bit integer value
    logical PropertyHandle  :: Open ( uint64 uint64_val )

    The function opens an unbound property handle for a platform independent unsigned 64-bit integer value (uint64, UINT(17)).
    • uint64_val - - internal feature (not documented)
    25. to list
  25. Open property handle for an unsigned 32-bit integer value
    logical PropertyHandle  :: Open ( uint32 ulong_val )

    The function opens an unbound property handle for a platform independent unsigned 32-bit integer value (uint32, UINT(10)).
    • ulong_val - ulong_val - Title unknown
    26. to list
  26. Open property handle for an unsigned 16-bit integer value
    logical PropertyHandle  :: Open ( uint16 ushort_val )

    The function opens an unbound property handle for a platform independent unsigned 1-bit integer value (uint16, UINT(4)).
    • ushort_val - ushort_val - Title unknown
    27. to list
  27. Open an undefined property handle
    logical PropertyHandle  :: Open (  )

    The function opens an undefined and unbound property handle. Before using the property handle definition and instance area must be set.
    28. to list
to top previous next upper table of contents Comment