get_user_data()

Reads a user-bound data record for the currently logged-in user via dms.GetUserData. Each entry is identified by a free-form name (max 100 characters), a type, and the user ID. The user ID is automatically derived from the active session by the server.

1. Signature

  • Sync

  • Async

ecm.system.get_user_data(
    name: str,
    data_type: ECMUserDataType | int,
    *,
    as_string: bool = False,
) -> bytes | str | None
await ecm.system.get_user_data(
    name: str,
    data_type: ECMUserDataType | int,
    *,
    as_string: bool = False,
) -> 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.

as_string

bool

False

Controls the server response format (OutputUnicode). When True the server returns a string; when False it returns raw bytes. See the note below.

3. Return value

  • bytes — when as_string=False (the default) and the entry exists.

  • str  — when as_string=True and the entry exists.

  • None  — when no entry with the given name and type exists.

4. Important: Unicode servers and text-typed entries

On modern Unicode servers, dms.GetUserData rejects text-typed entries when they are requested without OutputUnicode=1. The server protocol returns:

Under Unicode systems the job 'GetUserData' is not allowed anymore for text values, use the job 'GetUserDataAsString' for text values instead

Practical consequence:

  • For binary data types (e.g. ADDITIONAL_APP_CONFIG_80…85, user-defined BLOB slots): use as_string=False (the default).

  • For text data types (e.g. STORED_QUERIES, AS_INI, EXTERNAL_PROGRAMS): use as_string=True, otherwise the server rejects the request.

Whether a particular type is text- or binary-flagged depends on the server configuration and may vary between installations.

5. Examples

5.1. Read binary data

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMUserDataType

value = ecm.system.get_user_data(
    "my_settings",
    ECMUserDataType.ADDITIONAL_APP_CONFIG_80,
)
if value is None:
    print("Entry does not exist")
else:
    print(f"{len(value)} bytes read")
from ecmind_blue_client.ecm import ECMUserDataType

value = await ecm.system.get_user_data(
    "my_settings",
    ECMUserDataType.ADDITIONAL_APP_CONFIG_80,
)

5.2. Read text data

  • Sync

  • Async

from ecmind_blue_client.ecm import ECMUserDataType

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

config = await ecm.system.get_user_data(
    "my_query_name",
    ECMUserDataType.STORED_QUERIES,
    as_string=True,
)

5.3. Existence check without consuming the value

Since None means "does not exist", a simple is not None is enough:

if ecm.system.get_user_data("foo", ECMUserDataType.ADDITIONAL_APP_CONFIG_80) is not None:
    print("Entry exists")

6. See also

  • dms.SetUserData — store a value (not yet in the Python API)

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

  • dms.GetUserDataAsString — specialized variant for strings only (not yet in the Python API)

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