3.78 DM_ValueChange
Mit dieser Funktion kann eine von IDM gemanagte Wertereferenz manipuliert werden. Entweder kann der Gesamtwert ersetzt werden oder ein einzelner Elementwert in einer Sammlung.
Es findet eine automatische Umwandlung von einer ungemanagten Wertereferenz in eine gemanagte Wertereferenz statt. Ist in diesem Fall die Option DMF_StaticValue gesetzt, so wird eine statische bzw. globale gemanagte Wertereferenz gesetzt. Für eine bessere Kontrolle empfiehlt sich auch die explizite Nutzung von DM_ValueInit.
Handelt es sich beim value-Parameter um eine Sammlung, z.B. vom Typ DT_vector, DT_list, DT_hash, DT_matrix oder DT_refvec, so kann durch Angabe des index-Parameters ein Elementwert ausgetauscht werden. Analog zu den vordefinierten Attributen ist eine Erweiterung einer Sammlung möglich indem schrittweise der um +1 erhöhte Index verwendet wird. Für assoziative Felder ist einfach die Nutzung eines noch nicht verwendeten Indexschlüssels möglich.
Wird eine Sammlung im data-Parameter dem Ziel komplett (also mit NULL als index-Parameter) zugewiesen, so wird der gesamte Wert mit allen Werteelementen kopiert. Die Umwandlung eines Argumentes in einen lokal gemanagten Wert erfordert ebenso ein komplettes Kopieren um die weitere Manipulation zu ermöglichen.
DM_Boolean DML_default DM_EXPORT DM_ValueChange
(
DM_Value *value,
DM_Value *index,
DM_Value *data,
DM_Options options
)
Parameter
-> DM_Value * value
Dieser Parameter verweist auf die Wertereferenz, welche verändert werden soll. Falls sie noch nicht vom IDM gemanagt wird, wird sie in eine gemanagte Wertereferenz überführt.
-> DM_Value * index
Dieser Parameter kann für die Änderung von Elementwerten in Sammlungen verwendet werden und dient zur Angabe des Index. Ansonsten sollte er mit NULL belegt werden. Dieser Parameter muss nicht eine gemanagte Wertereferenz sein.
-> DM_Value * data
Dieser Parameter definiert den Wert, der gesetzt werden soll. Es kann sich dabei um eine gemanagte oder auch um eine ungemanagte Wertereferenz handeln. Ist dieser Wert NULL, so wird der Wert bzw. das Element auf DT_undefined gesetzt.
-> DM_Options options
Hier sind folgende Optionen möglich:
|
Option |
Bedeutung |
|---|---|
|
DMF_StaticValue |
Bei der automatischen Umwandlung des value-Parameters in eine gemanagte Wertereferenz wird diese als statische bzw. globale Wertereferenz behandelt. |
|
DMF_AppendValue |
Bei Sammlungen wird der Datenwert aus data hinten angehängt. Der Index muss hierfür NULL sein. |
|
DMF_SortBinary |
Bei Sammlungen erfolgt für den neu gesetzten Wert abschließend eine Sortierung des neu gesetzten Wertes. Kombinierbar mit DMF_SortReverse. |
|
DMF_SortLinguistic |
Bei Sammlungen erfolgt für den neu gesetzten Wert abschließend eine Sortierung, welche für Strings nach linguistischen Regeln (siehe hierzu die Funktion sort()) erfolgt. Kombinierbar mit DMF_SortReverse. |
|
DMF_SortReverse |
Bei Sammlungen erfolgt für den neu gesetzten Wert abschließend eine Sortierung in umgekehrter Reihenfolge. |
Rückgabewert
|
DM_TRUE |
Funktion erfolgreich ausgeführt, die Wertesetzung war erfolgreich oder der Wert war schon gesetzt. |
|
DM_FALSE |
Wertesetzung konnte nicht durchgeführt werden. Das kann auf einen fehlerhaften Aufruf, eine nicht gemanagte oder ungültige Wertereferenz oder eine fehlerhafte Indizierung hinweisen. |
Beispiel
dialog YourDialog
function anyvalue FindData(hash DataHash, string Pattern,
anyvalue FirstIndex output);
on dialog start
{
variable hash Stations := ["1"=>"ARD ","2"=>"ZDF ","9"=>"SWR3 "];
variable anyvalue Idx;
print "Found(D)=" + FindData(Stations,"D",Idx);
print " at " + Idx;
exit();
}
...
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(...)
Verfügbarkeit
Support