delete_user_data()

Deletes the user-bound data record identified by name and type for the currently logged-in user via dms.DeleteUserData.

This is the counterpart to set_user_data(). Overwriting a record with an empty value does not remove it — only delete_user_data() does.

1. Signature

  • Sync

  • Async

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

2. Parameters

Parameter Type Default Description

name

str

—

Identifier of the data record (max 100 characters). The lookup is case-insensitive.

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.

3. Return value

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

4. Important: deleting is not idempotent

The server does not accept the deletion of a record that does not exist. It answers with result code -1, which the client raises as an ECMException:

from ecmind_blue_client.ecm import ECMException, ECMUserDataType

try:
    ecm.system.delete_user_data("never_stored", ECMUserDataType.ADDITIONAL_APP_CONFIG_80)
except ECMException:
    pass  # the record was already gone

The same applies when the name exists but under a different type — name and type together identify the record.

To delete only when present, check first:

if ecm.system.get_user_data("my_settings", ECMUserDataType.ADDITIONAL_APP_CONFIG_80) is not None:
    ecm.system.delete_user_data("my_settings", ECMUserDataType.ADDITIONAL_APP_CONFIG_80)

5. Important: empty value vs. deleted record

Storing an empty value leaves a row behind. The record still exists, reads back as b"" (or "") rather than None, and is still listed by get_user_data_names():

from ecmind_blue_client.ecm import ECMUserDataType

SLOT = ECMUserDataType.ADDITIONAL_APP_CONFIG_80

ecm.system.set_user_data("my_settings", SLOT, b"")
assert ecm.system.get_user_data("my_settings", SLOT) == b""          (1)
assert "MY_SETTINGS" in ecm.system.get_user_data_names(SLOT)

ecm.system.delete_user_data("my_settings", SLOT)
assert ecm.system.get_user_data("my_settings", SLOT) is None         (2)
assert "MY_SETTINGS" not in ecm.system.get_user_data_names(SLOT)
1 Empty value — the row is still there.
2 Deleted — the row is gone.

6. Examples

6.1. Round trip

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMUserDataType

SLOT = ECMUserDataType.ADDITIONAL_APP_CONFIG_80

ecm.system.set_user_data("my_app_config", SLOT, b'{"schema": 1}')
assert ecm.system.get_user_data("my_app_config", SLOT) is not None

ecm.system.delete_user_data("my_app_config", SLOT)
assert ecm.system.get_user_data("my_app_config", SLOT) is None
from ecmind_blue_client.ecm import ECMUserDataType

SLOT = ECMUserDataType.ADDITIONAL_APP_CONFIG_80

await ecm.system.set_user_data("my_app_config", SLOT, b'{"schema": 1}')
assert await ecm.system.get_user_data("my_app_config", SLOT) is not None

await ecm.system.delete_user_data("my_app_config", SLOT)
assert await ecm.system.get_user_data("my_app_config", SLOT) is None

6.2. Clear out every record of one type

from ecmind_blue_client.ecm import ECMUserDataType

SLOT = ECMUserDataType.ADDITIONAL_APP_CONFIG_80

for name in ecm.system.get_user_data_names(SLOT):
    ecm.system.delete_user_data(name, SLOT)

7. See also

  • get_user_data() — Read the value

  • set_user_data() — Store or overwrite the value

  • get_user_data_names() — List all names for a given type

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