set_user_data()

Speichert einen benutzerbezogenen Datensatz für den aktuell angemeldeten Benutzer über dms.SetUserData. Existiert noch kein Eintrag für den angegebenen Namen und Typ, wird ein neuer Eintrag erzeugt; ein bestehender Eintrag wird überschrieben (Upsert-Semantik).

1. Signatur

  • Sync

  • Async

ecm.system.set_user_data(
    name: str,
    data_type: ECMUserDataType | int,
    value: bytes | str,
) -> None
await ecm.system.set_user_data(
    name: str,
    data_type: ECMUserDataType | int,
    value: bytes | str,
) -> None

2. Parameter

Parameter Typ Standard Beschreibung

name

str

—

Bezeichner des Datensatzes (max. 100 Zeichen).

data_type

ECMUserDataType | int

—

Typkennung. ECMUserDataType enthält die dokumentierten Standard-Typen (z. B. STORED_QUERIES, EXTERNAL_PROGRAMS, AS_INI, ADDITIONAL_APP_CONFIG_80…85). Eigene registrierte Typen können als int übergeben werden.

value

bytes | str

—

Der zu speichernde Wert. Der Python-Typ entscheidet, wie der Wert an den Server übertragen wird (siehe Hinweis unten).

3. Rückgabewert

Keiner. Wirft eine Ausnahme, wenn der Server-Job einen Fehlercode zurückliefert.

4. Wichtiger Hinweis: bytes vs. str

Der Server akzeptiert zwei Übertragungsformate:

  • bytes wird als Value (BASE64) an den Server gesendet — verwende diesen Pfad für binäre Slot-Typen (z. B. ADDITIONAL_APP_CONFIG_80…85, eigene BLOB-Slots).

  • str wird als sValue (STRING) an den Server gesendet — verwende diesen Pfad für textuelle Slot-Typen (z. B. STORED_QUERIES, AS_INI, EXTERNAL_PROGRAMS).

Der Pfad muss zur Server-Konfiguration des Slots passen. Wird beispielsweise ein String in einen binären Slot geschrieben und anschließend mit get_user_data(…​, as_string=False) gelesen, kommt der UTF-8-Bytestream inklusive BOM-Präfix zurück.

5. Beispiele

5.1. Binäre Daten speichern und lesen

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMUserDataType

ecm.system.set_user_data(
    "my_settings",
    ECMUserDataType.ADDITIONAL_APP_CONFIG_80,
    b"\x00\x01\x02binary payload",
)

value = ecm.system.get_user_data("my_settings", ECMUserDataType.ADDITIONAL_APP_CONFIG_80)
assert value == b"\x00\x01\x02binary payload"
from ecmind_blue_client.ecm import ECMUserDataType

await ecm.system.set_user_data(
    "my_settings",
    ECMUserDataType.ADDITIONAL_APP_CONFIG_80,
    b"\x00\x01\x02binary payload",
)

5.2. Text-Daten speichern und lesen

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMUserDataType

ecm.system.set_user_data(
    "my_query_name",
    ECMUserDataType.STORED_QUERIES,
    "SELECT * FROM …",
)

config = ecm.system.get_user_data(
    "my_query_name",
    ECMUserDataType.STORED_QUERIES,
    as_string=True,
)
from ecmind_blue_client.ecm import ECMUserDataType

await ecm.system.set_user_data(
    "my_query_name",
    ECMUserDataType.STORED_QUERIES,
    "SELECT * FROM …",
)

5.3. Upsert-Semantik

Ein erneuter Aufruf mit demselben name/data_type überschreibt den vorhandenen Eintrag — eine separate Existenzprüfung ist nicht nötig:

ecm.system.set_user_data("foo", ECMUserDataType.ADDITIONAL_APP_CONFIG_80, b"v1")
ecm.system.set_user_data("foo", ECMUserDataType.ADDITIONAL_APP_CONFIG_80, b"v2")
assert ecm.system.get_user_data("foo", ECMUserDataType.ADDITIONAL_APP_CONFIG_80) == b"v2"

6. Siehe auch

  • get_user_data() — Wert lesen

  • dms.DeleteUserData — Wert löschen (noch nicht in der Python-API)

  • dms.IsUserData — Existenz prüfen (noch nicht in der Python-API; mit get_user_data() is not None lässt sich dasselbe erreichen)

  • dms.GetUserDataNames — alle Namen für einen Typ auflisten (noch nicht in der Python-API)