set_user_data()

Stores a user-bound data record for the currently logged-in user via dms.SetUserData. If no entry exists for the given name and type a new record is created; an existing entry is overwritten (upsert semantics).

1. Signature

  • 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. Parameters

Parameter Type Default Description

name

str

—

Identifier of the data record (max 100 characters).

data_type

ECMUserDataType | int

—

Type identifier. ECMUserDataType lists the documented standard types (e.g. STORED_QUERIES, EXTERNAL_PROGRAMS, AS_INI, ADDITIONAL_APP_CONFIG_80…85). Custom registered types can be passed as plain int.

value

bytes | str

—

The value to store. The Python type determines how it is sent to the server (see note below).

3. Return value

None. Raises an exception when the server job returns an error code.

4. Important: bytes vs str

The server accepts two transmission formats:

  • bytes is sent as the Value (BASE64) parameter — use this for binary slot types (e.g. ADDITIONAL_APP_CONFIG_80…85, custom BLOB slots).

  • str is sent as the sValue (STRING) parameter — use this for text slot types (e.g. STORED_QUERIES, AS_INI, EXTERNAL_PROGRAMS).

The chosen path must match the server-side configuration of the slot. For example, writing a string into a binary slot and then reading it back via get_user_data(…​, as_string=False) returns the UTF-8 byte stream including a BOM prefix.

5. Examples

5.1. Store and read binary data

  • 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. Store and read text data

  • 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 semantics

A repeated call with the same name / data_type overwrites the existing entry — no separate existence check is needed:

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. See also

  • get_user_data() — Read the value

  • dms.DeleteUserData — Delete a value (not yet in the Python API)

  • dms.IsUserData — Existence check (not yet in the Python API; get_user_data() is not None achieves the same)

  • dms.GetUserDataNames — List all names for a given type (not yet in the Python API)