DM_ValueIndex

3.80 DM_ValueIndex

This function can be used to determine the corresponding index for a position in a collection. This is especially important for values of type DT_hash and DT_matrix in order to access all respective indexes the easiest way. The function only allows access to indexes that do not belong to default values.

The returned index can be stored in a managed retvalue parameter value or in an unmanaged one. In the latter case, the string value is allocated in the temporary buffer if necessary.

DM_UInt DML_default DM_EXPORT DM_ValueIndex
(
  DM_Value   *value,
  DM_UInt     indexpos,
  DM_Value   *retvalue,
  DM_Options  options
)

Parameters

-> DM_Value* value

This parameter refers to the value reference from which the index for the position will be retrieved. It must be a managed value reference or function argument.

-> DM_UInt indexpos

This parameter defines the position of the index and should be in the range 0 < indexpos <= DM_ValueCount().

-> DM_Value * retvalue

Wenn dieser Parameter nicht NULL ist, wird hier der entsprechende Index abgelegt. Es kann sich dabei um eine gemanagte oder auch um eine ungemanagte Wertereferenz handeln.

If this parameter is not NULL, the retrieved index is stored here. This may be a managed or an unmanaged value reference.

-> DM_Options options

These are the options available:

Option	Meaning
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	The value has an index at this position; the obtained index can afterward be found in *retvalue if retvalue != NULL.
DM_FALSE	The index could not be determined. This may be due to an faulty call, an unmanaged or invalid value reference, or an incorrect position.

Example

Dialog File

dialog YourDialog
function anyvalue FindData(hash DataHash, string Pattern,
                           anyvalue FirstIndex output);

on dialog start
{
  variable hash Stations := ["1"=>"ABC","2"=>"CBS","9"=>"HBO"];
  variable anyvalue Idx;

  print "Found(D)=" + FindData(Stations,"D",Idx);
  print " at " + Idx;
  exit();
}

C Part

...

static DM_Value InvalidIndex;
static DM_Value InvalidValue;

DM_Value * DML_default DM_ENTRY FindData(DM_Value *DataHash, DM_String Pattern,
                                         DM_Value *FirstIndex)
{
  DM_Value index;
  DM_Value value;

  /* initialize the managed values */
  DM_ValueInit(&index, DT_void, NULL, 0);
  DM_ValueInit(&value, DT_void, NULL, 0);
  DM_StringInit(&retString, 0);

  count = DM_ValueCount(DataHash, NULL, 0);
  while(count>0)
  {
    /* loop through the hash */
    if (DM_ValueIndex(DataHash, count--, &index, 0)
        && DM_ValueGet(DataHash, &index, &value, DMF_GetLocalString)
        && value.type == DT_string)
    {
      if (strstr(value.value.string, Pattern))
      {
        /* return the first found index & value */
        DM_ValueChange(FirstIndex, NULL, &index, 0);
        return DM_ValueReturn(&value, 0);
      }
    }
  }

  /* return the invalid index & value */
  DM_ValueChange(FirstIndex, NULL, &InvalidIndex, 0);
  return &InvalidValue;
}

...

int DML_c AppMain __2((int, argc), (char **,argv))
{
  DM_Value data;

  ...

  data.type = DT_string;
  data.value.string = "NO-VALUE";
  DM_ValueChange(&InvalidValue, NULL, &data, DMF_StaticValue);
  data.type = DT_string;
  data.value.string = "INVALID-INDEX";
  DM_ValueChange(&InvalidIndex, NULL, &data, DMF_StaticValue);

  ...

  DM_StartDialog(...)

Availability

Since IDM version A.06.01.a