etm.wccoa.services.protocols

None

Return value of the function, or None for void functions.

This can be found at: etm.wccoa.datatypes.OaVariant

Call a function in this script.

• Parameters:
  • func_name – The CTRL function name to call.
  • params – Positional arguments passed to the function. Types are inferred from the Python values via OaValueLike.
• Returns: A result containing the return value of the CTRL function. Reference parameters are not returned.

Unload this script and release resources.

After unloading, no further calls are allowed. Called automatically when used as with context manager.

Check whether a datapoint identifier can be resolved.

Validates that the given identifier is resolvable. The identifier may refer to a system, DP type, DP, DPE, config, detail, or attribute — all specified parts must exist.

Examples:

dp_exists("System1:")              # True (system exists)
dp_exists("System1:MyDp")          # True (system + DP exist)
dp_exists("System1:MyDp.element")  # True (system + DP + element exist)
dp_exists("System1:NoSuchDp")      # False (DP not found)
dp_exists("MyDp.noSuchEl")         # False (element not found)

• Parameters:
  • dpe – A datapoint target (name, DpIdentifier, or DpReference).
• Returns: True if the identifier can be resolved successfully.

Return datapoint names matching a pattern.

• Parameters:
  • pattern – A wildcard pattern to filter names (empty = all).
  • dp_type – Restrict results to this datapoint type.
  • ignore_case – Whether to match the pattern case-insensitively.
• Returns: A list of matching datapoint names.

Return datapoint type names matching a pattern.

• Parameters:
  • pattern – A wildcard pattern to filter type names (empty = all).
  • system_id – The system ID to query (0 = local system).
  • include_empty – Whether to include types with no instances.
• Returns: A list of matching datapoint type names.

Create a new datapoint.

• Parameters:
  • dp_name – The name of the datapoint to create.
  • dp_type – The datapoint type name.
  • system_id – The target system ID (0 = local system).
  • dp_id – Explicit DP ID (0 = auto-assigned by system).

Set value(s) without waiting for completion (fire-and-forget).

• Parameters:
  • dpe – A single DPE target or a sequence of DPE targets.
  • value – A single value or a sequence of values (matching dpe).

Set value(s) and wait for completion.

• Parameters:
  • dpe – A single DPE target or a sequence of DPE targets.
  • value – A single value or a sequence of values (matching dpe).

Set value(s) with a source timestamp (fire-and-forget).

• Parameters:
  • time – The source timestamp to attach to the values.
  • dpe – A single DPE target or a sequence of DPE targets.
  • value – A single value or a sequence of values (matching dpe).

Set value(s) with a source timestamp and wait for completion.

• Parameters:
  • time – The source timestamp to attach to the values.
  • dpe – A single DPE target or a sequence of DPE targets.
  • value – A single value or a sequence of values (matching dpe).

Set value(s) and wait until target DPEs satisfy conditions.

• Parameters:
  • set_dpes – DPE targets to write before waiting. Empty, together with set_values, to only wait, like the CTRL function dpWaitForValue().
  • set_values – Values written to set_dpes.
  • wait_dpes – DPE targets monitored for condition matching.
  • conditions – Condition values for wait_dpes.
  • return_dpes – DPE targets returned when wait condition is satisfied.
  • timeout_ms – Wait timeout in milliseconds (0 = no timeout).
• Returns: Values for return_dpes as a list of OaVariant.
• Raises:
  • ValueError – If wait_dpes or return_dpes is empty, or if a list does not match the length of its counterpart.
  • OaError – If a DPE does not exist (error 71), or if the timeout expires before the conditions are met (error 54).

Read current value(s) of one or more datapoint elements.

• Parameters:
  • dpe – A single DPE target or a sequence of DPE targets.
• Returns: A single OaVariant when called with a single target, or a list of OaVariant when called with a sequence.

Read value(s) with a maximum age check.

If a value is older than age_ms milliseconds the driver is queried for an update before replying.

• Parameters:
  • age_ms – Maximum age in milliseconds.
  • dpe – A single DPE target or a sequence of DPE targets.
• Returns: A single OaVariant when called with a single target, or a list of OaVariant when called with a sequence.

Read value(s) directly from the driver, bypassing the cache.

• Parameters:
  • dpe – A single DPE target or a sequence of DPE targets.
  • timeout_ms – Timeout in milliseconds (0 = no timeout).
• Returns: A single OaVariant when called with a single target, or a list of OaVariant when called with a sequence.

Read alert value(s) for the given alert target(s).

• Parameters:
  • alert_target_or_alert_time – Either a single AlertTarget, a sequence of AlertTargets, or a convenience single AlertTime.
  • dpe – Required only when alert_target_or_alert_time is AlertTime.
• Returns: A single OaVariant when called with a single alert_target, or a list of OaVariant when called with a sequence.

Set alert value(s) without waiting (fire-and-forget).

• Parameters:
  • alert_target – A single alert target or a sequence of alert targets.
  • value – A single value or a sequence of values (matching alert_target).

Set alert value(s) and wait for completion.

• Parameters:
  • alert_target – A single alert target or a sequence of alert targets.
  • value – A single value or a sequence of values (matching alert_target).

Set alert value(s) with a source timestamp (fire-and-forget).

• Parameters:
  • time – The source timestamp to attach to the values.
  • alert_target – A single alert target or a sequence of alert targets.
  • value – A single value or a sequence of values (matching alert_target).

Set alert value(s) with a source timestamp and wait for completion.

• Parameters:
  • time – The source timestamp to attach to the values.
  • alert_target – A single alert target or a sequence of alert targets.
  • value – A single value or a sequence of values (matching alert_target).

Get the type definition for a datapoint type.

• Parameters:
  • dp_type_name – The name of the datapoint type.
  • include_sub_types – Whether to include sub-type definitions.
• Returns: The type definition tree.

Create a new datapoint type from a definition tree.

• Parameters:
  • definition – The type definition tree to create.

Change an existing datapoint type from a definition tree.

Replaces the definition of the existing type completely. If the type does not exist yet, it is created.

• Parameters:
  • definition – The type definition tree to apply.

Delete a datapoint type.

• Parameters:
  • dp_type_name – The name of the datapoint type to delete.

Get the type name of a datapoint.

• Parameters:
  • dp – The datapoint path.
• Returns: The datapoint type name.

Get the referenced type name of a TYPE_REFERENCE element.

• Parameters:
  • dpe – A datapoint target (name, DpIdentifier, or DpReference).
• Returns: The referenced type name.

Get forward type references of a datapoint type.

• Parameters:
  • dp_type_name – The datapoint type name.
• Returns: A list of reference items (ref_name, dpe_path).
• Raises:
  • OaError – If the datapoint type does not exist (error 57).

Get backward references to a datapoint type.

• Parameters:
  • dp_type_name – The datapoint type name.
• Returns: A list of usage-reference items (dpt_name, dpe_path). Empty if no type references it, including when no type of that name exists.

Subscribe to value changes of one or more datapoint elements.

The callback receives a single ObserveMultiDpValueEventArgs on each hotlink, which encapsulates names, values, update flags, and error.

• Parameters:
  • callback – Called on each value change (or error).
  • dpes – A single DPE target or a sequence of DPE targets.
  • answer – Whether to receive an initial answer with current values.
• Returns: A connection ID for use with dp_disconnect.

Unsubscribe a dp_connect subscription.

• Parameters:
  • connect_id – The connection ID returned by dp_connect.

Get the numeric system ID for a system name.

• Parameters:
  • system_name – The system name (empty = local system).
• Returns: The numeric system ID.

Get the system name for a numeric system ID.

• Parameters:
  • system_id – The numeric system ID (0 = local system).
• Returns: The system name.

Delete a datapoint.

• Parameters:
  • dp_name – The name of the datapoint to delete.

Execute a SQL-like query and return the result.

The OaQueryResult supports both structured access (get_data, column metadata) and iteration (for row in result).

• Parameters:
  • query – The SQL-like query string.
• Returns: The query result with columns and rows.

Execute a split query (for large result sets).

Pass a query string on first call, then the returned request_id for subsequent calls until progress is 100.

• Parameters:
  • query_or_id – A query string (first call) or a request ID (subsequent calls).
• Returns: A split result envelope containing request_id, progress (0–100), and the partial data.

Cancel a running split query.

• Parameters:
  • request_id – The request ID returned by dp_query_split.

Get historical values within a time period.

• Parameters:
  • start_time – Start of the time period.
  • end_time – End of the time period.
  • dpes – Datapoint element targets to query.
  • count – Maximum number of additional values (0 = unlimited).
• Returns: A period result grouped by DPE, each group holding its time/value pairs. Iterate over result for a flattened stream of OaDpTimedValueItem.

Get historical values via split request (large result sets).

Pass start_time on first call, then the returned request_id for subsequent calls until progress is 100.

• Parameters:
  • start_or_id – Start time (first call) or request ID (subsequent).
  • end_time – End of the time period (required on first call).
  • dpes – DPE targets to query (required on first call).
  • count – Maximum number of additional values (0 = unlimited).
• Returns: A split result envelope containing request_id, progress (0–100), and the partial data.

Get alert history within a time period.

• Parameters:
  • start_time – Start of the time period.
  • end_time – End of the time period.
  • dpes – A single DPE target or a sequence of DPE targets.
• Returns: A list of alert value items within the period.

Subscribe to a query — callback fires for changed rows only.

• Parameters:
  • callback – Called on each query result change (or error).
  • answer – Whether to receive an initial answer.
  • query – The SQL-like query string.
  • blocking_time_ms – Minimum interval between callbacks (-1 = default).
• Returns: A connection ID for use with dp_query_disconnect.

Subscribe to a query — callback fires with all rows on each change.

• Parameters:
  • callback – Called on each query result change (or error).
  • answer – Whether to receive an initial answer.
  • query – The SQL-like query string.
  • blocking_time_ms – Minimum interval between callbacks (-1 = default).
• Returns: A connection ID for use with dp_query_disconnect.

Unsubscribe a dp_query_connect subscription.

• Parameters:
  • connect_id – The connection ID returned by dp_query_connect_*.

Get the unit for a datapoint element.

• Parameters:
  • dpe – The datapoint element path.
• Returns: The localized unit string.

Set the unit for a datapoint element.

• Parameters:
  • dpe – The datapoint element path.
  • unit – The localized unit string to set.

Get the format string for a datapoint element.

• Parameters:
  • dpe – The datapoint element path.
• Returns: The localized format string.

Set the format string for a datapoint element.

• Parameters:
  • dpe – The datapoint element path.
  • fmt – The localized format string to set.

Get the description for a datapoint element.

• Parameters:
  • dpe – The datapoint element path.
  • mode – The description formatting mode.
• Returns: The localized description.

Set the description for a datapoint element.

• Parameters:
  • dpe – The datapoint element path.
  • description – The localized description to set.

Get the alias for a datapoint element.

• Parameters:
  • dpe – The datapoint element path.
• Returns: The alias string (empty if none set).

Resolve an alias to a datapoint element name.

• Parameters:
  • alias – The alias to resolve.
• Returns: The datapoint element path.

Get all aliases matching the filters.

• Parameters:
  • alias_filter – Wildcard filter for alias names.
  • dpe_filter – Wildcard filter for DPE paths.
• Returns: A list of alias items (dp_path, dp_ident, alias).

Set the alias for a datapoint element.

• Parameters:
  • dpe – The datapoint element path.
  • alias – The alias string to set.

Get the hostname of this redundancy partner.

• Returns: The hostname string.

Get the host number of this redundancy partner.

• Returns: The host number (1 or 2).

Get the hostname of the other redundancy partner.

• Returns: The hostname string.

Check whether the system is in redundant mode.

• Returns: True if the system is configured for redundancy.

Check whether this host is the active redundancy partner.

• Returns: True if this host is the active partner.

Get all config names for a datapoint or type.

• Parameters:
  • dp_name_or_type – DP name or type name.
• Returns: A list of config names.

Get all detail names for a config.

• Parameters:
  • config_name – Config name.
• Returns: A list of detail names.

Get all descriptions matching the filters.

• Parameters:
  • desc_filter – Wildcard filter for description text.
  • dpe_filter – Wildcard filter for DPE paths.
  • mode – The description formatting mode.
• Returns: A list of description items with DPE path and localized text.

Get all attribute names for a config.

• Parameters:
  • config_name – Config name.
• Returns: A list of attribute names.

Get the element type enum for a datapoint element.

• Parameters:
  • dpe – A datapoint target (name, DpIdentifier, or DpReference).
• Returns: The element type enum value.

Get the identifier of a datapoint element.

• Parameters:
  • dp_name – The datapoint element path (e.g., “Dp1.element”).
• Returns: A resolved DpIdentifier containing system_id, dp_id, element_id, and further identifier parts.

Get the datapoint path for an identifier.

• Parameters:
  • dp_ident_or_dp_id – Either a full DpIdentifier or a datapoint ID.
  • elem_id – Element ID when passing numeric IDs.
  • system_id – System ID when passing numeric IDs (0 = local system).
• Returns: The datapoint path.

Resolve DPE target(s) to DpReference(s).

Accepts a string path, DpIdentifier, or DpReference and returns a DpReference that holds both the resolved path and DpIdentifier.

• Parameters:
  • dpe – A single DPE target or a sequence of DPE targets.
• Returns: A single DpReference when called with a single target, or a list of DpReference when called with a sequence.
• Raises:
  • OaError – If a target cannot be resolved.

Get the user name for a user ID.

• Parameters:
  • user_id – The user ID (-1 = current user).
• Returns: The user name.
• Raises:
  • OaError – If the user ID is unknown (error 76).

Get the user ID for a user name.

• Parameters:
  • user_name – The user name (empty = current user).
• Returns: The numeric user ID.
• Raises:
  • OaError – If the user name is unknown (error 76).

Check whether the given user is enabled.

• Parameters:
  • user – The user, either as a numeric user ID or as a user name.
• Returns: True if the user is enabled.
• Raises:
  • OaError – If the user is unknown (error 76).

Create a CTRL script from inline code.

The script is compiled, loaded, and ready for function calls. Use with for automatic cleanup:

with api.create_ctrl_script(code) as script:
    result = script.call_function("add", [3, 4])
    print(result.return_value)  # 7

• Parameters:
  • code – The CTRL source code.
  • name – Optional display name for diagnostics.
• Returns: A loaded script object ready for function calls.

Create a CTRL script from a file in the WinCC OA search paths.

• Parameters:
  • file_path – Relative path to the CTRL file (resolved via WinCC OA project/installation search paths).
• Returns: A loaded script object ready for function calls.