DM_ValueGet

3.79 DM_ValueGet

This function allows to retrieve a single element value that belongs to a defined index from collections.

If the given index is NULL, the entire value is returned, which usually means copying the value.

If the retvalue parameter is an unmanaged value, it remains unmanaged. When strings are returned, they are only stored in a temporary buffer which may be cleared or overwritten the next time a DM function without the DMF_DontFreeLastStrings option is called.

DM_Boolean DML_default DM_EXPORT DM_ValueGet
(
  DM_Value   *value,
  DM_Value   *index,
  DM_Value   *retvalue,
  DM_Options  options
)

Parameters

-> DM_Value* value

This parameter refers to the value reference from which the element value is retrieved. It should be a managed value reference or function argument.

-> DM_Value * index

This parameter sets the index for which the element value is retrieved. This parameter does not need to be a managed value. If the parameter is set to NULL, the value parameter is copied into the return parameter retvalue.

-> DM_Value * retvalue

This parameter defines the value to be set. It may be a managed or an unmanaged value reference. If this value is NULL, the value or element is set to DT_undefined.

-> DM_Options options

These are the options available:

Option	Meaning
DMF_StaticValue	When the value parameter is automatically converted into a managed value reference, it is treated as a static respectively global value reference.
DMF_GetLocalString	This option means that text values (IDs of type DT_text) should be returned as strings in the currently set language.
DMF_GetMasterString	This option means that text values (IDs of type DT_text) should be returned as a strings in the development language, regardless of which language the user is currently working with.
DMF_DontFreeLastStrings	Strings are usually passed to the application in a temporary buffer, which is retained until the next call to the IDM. If strings in the application shall be valid longer, the option DMF_DontFreeLastStrings has to be set. Then the memory will not be released until an IDM function returning a string from the IDM to the applicationis called without this option.

Return value

DM_TRUE	Getting the value has been successful.
DM_FALSE	The value could not be retrieved. This may be due to an faulty call, an unmanaged or invalid value reference, or an incorrect indexing.

Availability

Since IDM version A.06.01.a