company logo

PropertyHandle :: ExtractKey - Extract identifying key value

The function extracts the identifying key value according to the structure definition of the property handle.

When no instance has been passed the function extracts the key from the currently selected instance. If no instance has been selected in the property handle the function will select the instance located in the property handle. When no instance could be selected an no instance has been passed the function returns an empty key.

When a key area has been passed in the key parameter the function returns the key in the passed key area. When no key or an empty key has been passed the returned key area refers to an internal area, which should not be modified by the application. This area is valid until the next ODABA interface function has been called.

When the key to be extracted is the __IDENTITY key, an instance must be selected in the property handle or the structure must have an __IDENTITY attribute. Otherwise, the function returns NULL.

When applying the function on weak-typed collections, the function returns the identifying key value as defined for the base type in the collection. This might differ from identifying key values defined in the data type for the currently selected instance. To extract the identifying key value for the identifying key definition in the currently selected instance, one may call ExtractCurrentKey().
Return value:  Key value (   )

The key is provided in the internal key format. When necessary the key value can be converted to a string using the ({.r pib.KeyToString}()) function.

Implementation overview

Implementation details

  1. Extracting ident key
    ::Key PropertyHandle  :: ExtractKey ( ::Key ident_key_w=Key(), ::Instance instance_w=Instance() )

    This implementation extracts the identity key from the selected or passed instance.
    • ident_key_w - Ident key value

      The key is provided in the internal key format. When necessary the key value can be converted from a string into the internal format using the StringToKey() function.

      Default: Key()
    • instance_w - Instance area

      Instances do have the type of the referenced property handle (collection type). The instance contains a reference to a property structured area.

      You can use the !-operator or the GetData() function to check whether the instance refers to data or not.

             Default: Instance()
    2. to list
  2. - internal feature (not documented)
    ::Key PropertyHandle  :: ExtractKey ( NString &key_name )
    • key_name - Key name

      The key name is passed as 0-terminated string or as buffer with a maximum size of 40 characters and trailing blanks.
    3. to list
to top previous next upper table of contents Comment