set_message_tupleT_set_message_tupleSetMessageTupleSetMessageTuple (Operator)

Name

set_message_tupleT_set_message_tupleSetMessageTupleSetMessageTuple — Hinzufügen eines Schlüssel-Tupeldaten-Paares zu einer Nachricht.

Signatur

set_message_tuple( : : MessageHandle, Key, TupleData : )

set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTuple speichert in einer Nachricht ähnlich zu einem assoziativem Array ein Datentupel in Verbindung mit einem Schlüsselwort ab. Das Nachrichtenobjekt wird durch den Parameter MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle referenziert.

TupleDataTupleDataTupleDataTupleDatatupleData wird in das Nachrichtenobjekt kopiert und kann anschließend weiterverwendet oder gelöscht werden. Ein leeres Tupel ist ebenfalls ein gültiger Wert, der mit einem Schlüsselwort referenziert werden kann. Falls bereits Daten (Tupel oder Objekt) durch das gegebenen Schlüsselwort referenziert werden, werden die alten Daten freigegeben und durch TupleDataTupleDataTupleDataTupleDatatupleData ersetzt.

KeyKeyKeyKeykey ist ein nicht leerer String der ausnahmslos aus ASCII-Buchstaben, Zahlen und Unterstrichen besteht, wobei das Schlüsselwort mit einem Buchstaben beginnen muss. Dabei werden Groß-/Kleinschreibung beachtet.

Die Tupeldaten für den übergebenen Schlüssel können mit Hilfe des Operators get_message_tupleget_message_tupleGetMessageTupleGetMessageTupleGetMessageTuple aus dem Nachrichtenobjekt wieder ausgelesen werden.

Achtung

Falls TupleDataTupleDataTupleDataTupleDatatupleData Handles enthält, werden nur die Handle-Werte kopiert, nicht aber die Objekte welche die Handles referenzieren.

Ausführungsinformationen

Multithreading-Typ: reentrant (läuft parallel zu nicht-exklusiven Operatoren).
Multithreading-Bereich: global (kann von jedem Thread aufgerufen werden).
Wird ohne Parallelisierung verarbeitet.

Dieser Operator modifiziert den Zustand des folgenden Eingabeparameters:

MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle

Der Wert dieses Parameters darf nicht über mehrere Threads verwendet werden.

Parameter

MessageHandleMessageHandleMessageHandleMessageHandlemessageHandle (input_control, Zustand wird modifiziert) message → (integer)

Nachrichtenobjekt.

Parameteranzahl: MessageHandle == 1

Restriktion: MessageHandle != 0

KeyKeyKeyKeykey (input_control) string → (string)

Schlüsselwort.

Parameteranzahl: Key == 1

Restriktion: length(Key) > 0

TupleDataTupleDataTupleDataTupleDatatupleData (input_control) tuple-array → (string / integer / real)

Vom Schlüssel zu referenzierende Tupeldaten.

Beispiel (HDevelop)

create_message (Message)
set_message_tuple (Message, 'simple_integer', 27)
set_message_tuple (Message, 'simple_string', 'Hello world')
set_message_tuple (Message, 'mixed_tuple', ['The answer', 42])

Ergebnis

Im Erfolgsfall gibt set_message_tupleset_message_tupleSetMessageTupleSetMessageTupleSetMessageTuple den Wert 2 (H_MSG_TRUE) zurück. Andernfalls wird eine Fehlerbehandlung durchgeführt. Mögliche Fehler sind ungültige Parameter (Nachrichtenobjekt oder Schlüssel) oder ein Allokierungsfehler.