Module `cimplicity`

Supercharge your Proficy solution! Download a free trial of Proficy Operations Hub, CSense analytics, and more. Explore our Proficy 2024 releases!

This module provides Python APIs for CIMPLICITY SCADA system.

Multithreading in Event Manager

(This assumes you are familiar with the concepts and terminology about the Event Manager and Python script actions as described in the CIMPLICITY documentation.)

Depending on the configuration of the events, the do_event_action method of a particular EventHandlerClass object instance may be called at the same time from separate threads. (Rememeber that there is a seperate EventHandlerClass object instance for each event-action.)

Therefore it is good practice to use the threading.Lock class or similar synchronization constructs to protect against issues.

Be aware, however, that multithreading programming can be tricky and introducing locks to protect sections of the code can also introduce deadlocks as well as affect performance.

Functions

def alarm_generate(project_name: str, alarm_id: str, resource_id: str, message: str, user_id: str = 'PYTHON_SCRIPTING', ref_id: str = '', time_stamp: datetime.datetime = None, send_to_active: bool = False)

Use this function to generate an alarm in the given CIMPLICITY project.

Parameters

project_name: str - the project name.
alarm_id: str - the id of the alarm to generate.
resource_id: str - the resource id to generate the alarm against. Used to control routing of the alarm.
message: str - the update alarm message to display. Note: This string is substituted into the first variable field of the Alarm's message. For a user-defined alarm message, this will be the first %s field in the message (the alarm must be of type $CIMBASIC). For a point alarm message, it will be the first variable field (%VAL, %ID, etc.) in the alarm message. For this reason, it is not recommended that you use the message when updating point alarms.
user_id: str - optional parameter, the user id for which to attribute the alarm generation.
ref_id: str - optional parameter, a reference id used to distinguish identical alarms.
time_stamp: datetime - optional parameter, specifying generation time. If provided it should be a time zone "aware" object.
send_to_active: bool - optional parameter, set it to True to allow an alarm to be generated from a script on a standby computer. By default on a computer with Server Redundancy, alarms sent by the standby computer's Event Manager are ignored.

Notes

If the Alarm ID is invalid, no error is raised but an error is logged to the status log.

The Alarm ID must have an Alarm Type of $CIMBASIC otherwise the alarm message may not be displayed correctly.

A unique alarm in CIMPLICITY is defined by the Alarm ID, Resource ID and Reference ID combination. Each unique alarm can be displayed as a distinct entry in the Alarm Viewer. Non-unique alarms are stacked, so that the user only sees the most recent occurrence. In general, the Resource ID is used to control the routing of alarms to users. The Reference ID is used by an application to distinguish between different instances of the same alarm.

Example

import cimplicity
import time

cimplicity.log_status(cimplicity.StatusSeverity.SUCCESS, 'example', 'generate')
cimplicity.alarm_generate('BLANK', 'MaintenanceAlarmCAP',
                   '$MAC_FR', 'PC LOAD LETTER')

time.sleep(2)
cimplicity.log_status(cimplicity.StatusSeverity.SUCCESS, 'example', 'update')
ca_args = {'performer_user_id': 'administrator',
           'performer_password': '',
           'performer_comment': 'fixed it'}
cimplicity.alarm_update('BLANK', 'MaintenanceAlarmCAP', '$MAC_FR',
                 cimplicity.AlarmUpdateAction.ACKNOWLEDGE,
                 **ca_args)

def alarm_update(project_name: str, alarm_id: str, resource_id: str, action: AlarmUpdateAction, message: str = '', user_id: str = 'PYTHON_SCRIPTING', ref_id: str = '', time_stamp: datetime.datetime = None, send_to_active: bool = False, **change_approval_args)

Use this function to update a currently generated alarm in the given CIMPLICITY project.

Parameters

project_name: str - the project name.
alarm_id: str - the id of the alarm to generate.
resource_id: str - the resource id to generate the alarm against. Used to control routing of the alarm.
action: AlarmUpdateAction - indicates the action to take.
message: str - the update alarm message to display. Note: This string is substituted into the first variable field of the Alarm's message. For a user-defined alarm message, this will be the first %s field in the message (the alarm must be of type $CIMBASIC). For a point alarm message, it will be the first variable field (%VAL, %ID, etc.) in the alarm message. For this reason, it is not recommended that you use the message when updating point alarms.
user_id: str - optional parameter, the user id for which to attribute the alarm generation.
ref_id: str - optional parameter, a reference id used to distinguish identical alarms.
time_stamp: datetime - optional parameter, specifying generation time. If provided it should be a time zone "aware" object.
send_to_active: bool - optional parameter, set it to True to allow an alarm to be generated from a script on a standby computer. By default on a computer with Server Redundancy, alarms sent by the standby computer's Event Manager are ignored.

The following parameters can optionaly be passed as keyword arguments with the following keys to apply change aproval information

performer_user_id: str - The id of the user on whose behalf the point operation is performed
performer_password: str - The password of this user
performer_comment: str - Performer comment to log with the operation
verifier_user_id: str - The id of the user on whose behalf the operation is verified (if required by change_approval_level)
verifier_password: str - The password of the verifying user
verifier_comment: str - Verifier comment to log with the operation

Notes

When updating an alarm, the Alarm ID, Resource ID and Ref ID must match exactly to the alarm to be updated; if they do not match, the alarm will not be updated. When updating a point alarm, the Ref ID is always the Point ID (which is also the Alarm ID).

Example

import cimplicity
import time

cimplicity.log_status(cimplicity.StatusSeverity.SUCCESS, 'example', 'generate')
cimplicity.alarm_generate('BLANK', 'MaintenanceAlarmCAP',
                   '$MAC_FR', 'PC LOAD LETTER')

time.sleep(2)
cimplicity.log_status(cimplicity.StatusSeverity.SUCCESS, 'example', 'update')
ca_args = {'performer_user_id': 'administrator',
           'performer_password': '',
           'performer_comment': 'fixed it'}
cimplicity.alarm_update('BLANK', 'MaintenanceAlarmCAP', '$MAC_FR',
                 cimplicity.AlarmUpdateAction.ACKNOWLEDGE,
                 **ca_args)

def log_status(severity: StatusSeverity, function: str, message: str, error_code: int = 0, error_reference: int = 0)

Logs a message to the CIMPLICITY status log file. The message will appear either in the system log file or the project log file depending on the environment. To view the messages, use the CIMPLICITY Status Log Viewer.

Parameters

severity: StatusSeverity - the severity of the log message (SUCCESS - informational message, WARNING - warning message, FAILURE - failure message). You must pass the enum object; you cannot pass an int.
function: str - the name of the python function which logged the error
message: str - the error message to log
error_code: int - a user-defined error code (optional, defaults to 0)
error_reference: int - a user-defined error reference. Used to distinguish between two errors with the same error_code. (optional, defaults to 0)

Example

import cimplicity

secs = 23.4
cimplicity.log_status(cimplicity.StatusSeverity.SUCCESS, 'test_logging', f'The operation took {secs} seconds.', 17, 23)

def point_add_multiple(timeout_ms: datetime.timedelta, points: Iterable)

point_add_multiple(timeout_ms: timedelta, points: Iterable) -> bool:

Adds all the points in a collection of Point objects as a batch operation to the ptmap API. If the timeout expires, any points not added will that do not already have an error state, will have an error set that can be retrieved with Point.has_error and Point.error_msg and Point.error_code

Possible values for timeout_ms:

-1: Wait an infinite amount of time.
Positive integer: Number of milliseconds to wait for a change.

Parameters

timeout_ms: int|timedelta - Maximum number of milliseconds to wait for a change.
points: Iterable[Point] - The collection of points to be read.

Example

import cimplicity

with cimplicity.Point() as point1, cimplicity.Point() as point2:
    points = [point1, point2]

    point1.set_id_without_add('PointWSTRING_20')
    point2.set_id_without_add('PointINT')

    all_added = cimplicity.point_add_multiple(1000, points)
    if all_added:
        point1.value = 'sampling complete'
        point2.value = 17
        cimplicity.point_set_multiple(points)
        cimplicity.point_read_multiple(points)

        assert point1.value == 'sampling complete', f'point {point1.id} has wrong value'
        assert point2.value == 17, f'point {point2.id} has wrong value'
    else:
        for point in points:
            if point.has_error:
                print("Point ", point.id, " had error : ", point.error_msg)

def point_get(point_id: str) ‑> Any

Use this function to read the value of a point. If the point is an array point, point_get function also supports getting an individual element of the array, by using [] brackets arround the element index in the point_id paramater string. If the point is an array point, and no element is specified then point_get will get a list of values correlating to the contents of the array point. If the point ID contains square brackets in its name the whole point id can include single quotes to skip parsing of the poind ID for any array index. Such as "'PointWithBrakets[2]'"

Parameters

point_id: str - The id of the point. Optionaly an array index to be specified.

Example

import cimplicity

pt_val = cimplicity.point_get('PointINT')
pt_val_list = cimplicity.point_get('PointINT_array')
pt_val_4 = cimplicity.point_get('PointINT_array[4]')

print("Value of point is: ", pt_val)

def point_read_multiple(points: Iterable)

point_read_multiple(points: Iterable) -> None:

Performs a point read for all the points in the points collection.

If you need to get the value of multiple points, use this function rather than issuing multiple single Point.get_value() or Point.read() or point_get('id') requests for faster script execution.

Parameters

points: Iterable[Point] - The collection of points to be read.

Example

import cimplicity

with cimplicity.Point() as point1, cimplicity.Point() as point2:
    points = [point1, point2]

    point1.id = 'PointWSTRING_20'
    point1.set_value('')
    assert point1.get_value() == '', f'problem clearing point {point1.id}'

    point2.id = 'PointINT'
    point2.set_value(0)
    assert point2.get_value() == 0, f'problem clearing point {point2.id}'

    point1.value = 'sampling complete'
    point2.value = 17
    cimplicity.point_set_multiple(points)
    cimplicity.point_read_multiple(points)

    assert point1.value == 'sampling complete', f'point {point1.id} has wrong value'
    assert point2.value == 17, f'point {point2.id} has wrong value'

def point_read_next(timeout_ms: datetime.timedelta, points: Iterable)

point_read_next(timeout_ms: timedelta, points: Iterable) -> Point:

Waits for the next point to change in a collection of `cimplicity.Point' objects for up to the specified timeout. If the timeout expires before a point changes None is returned.

Use this after calling one of Point.on_alarm(), Point.on_alarm_ack(), Point.on_change(), or Point.on_timed() to wait for the specified condition.

Parameters

timeout_ms: int or timedelta - time in milliseconds to wait before returning False if no new point value is available
points: Iterable[Point] - The collection of points to be read

Timeout values (milliseconds) can be also be -1 to wait indefinitely or 0 to return immediately even if there is no value ready.

Possible values for timeout_ms:

0: return immediately (even if there is no value ready)
-1: Wait indefinitely
Positive integer: Number of milliseconds to wait for a change

Example

import cimplicity

with cimplicity.Point() as point1, cimplicity.Point() as point2:
    points = [point1, point2]

    point1.id = 'SomePoint1'
    point2.id = 'SomePoint2'
    point1.on_change()
    point2.on_change()

    for i in range(3):
        next_point = cimplicity.point_read_next(-1, points)
        if(next_point != None):
            print(next_point.id, " = ", next_point.value)

    for point in points:
        point.cancel()

def point_set(point_id: str, value, **change_aproval_args)

Use this function to set the value of a point. If the point is an array point, point_set function also supports setting an individual element of the array, by using [] brackets arround the element index in the point_id paramater string. If the point is an array point, and no element is specified then point_set can take a python list of values and set each element of the array with the corresponding list member. If the point ID contains square brackets in its name the whole point id can include single quotes to skip parsing of the poind ID for any array index. Such as "'PointWithBrakets[2]'"

Parameters

point_id: str - The id of the point. Optionaly an array index to be specified.
value: - The value to set the point to.

The following parameters can optionaly be passed as keyword arguments with the following keys to apply change aproval information

performer_user_id: str - The id of the user on whose behalf the point operation is performed
performer_password: str - The password of this user
performer_comment: str - Performer comment to log with the operation
verifier_user_id: str - The id of the user on whose behalf the operation is verified (if required by change_approval_level)
verifier_password: str - The password of the verifying user
verifier_comment: str - Verifier comment to log with the operation

Example

import cimplicity

cimplicity.point_set('PointINT', 100)
cimplicity.point_set('PointINT_array[4]', 100)
cimplicity.point_set('PointINT_array', [100, 200, 300, 400, 500])
cimplicity.point_set("'PointWithBrakets[2]'", [100, 200, 300, 400, 500])


cimplicity.point_set('PointUINT', 200, performer_user_id='USER1', performer_password='MyPassword1!', performer_comment='Performed by USER1', verifier_user_id='VERIFIER1', verifier_password='MyPassword@2', verifier_comment='Verified by VERIFIER1')

def point_set_multiple(points: Iterable, password: str = '')

point_set_multiple(points: Iterable, password: str = "") -> bool:

Performs setpoints in a single setpoint request, using the provided setpoint password. If a failure occurs the function returns false, otherwise true is returned.

If you need to set the value of multiple points, use this function rather than issuing multiple single setpoint requests for faster script execution.

The point error_code property will be set to a non-zero value for a setpoint that failed. The point error_msg property will contain the associated error message.

Parameters

points: Iterable[Point] - The collection of points to be set.
password: str - optional "download" password that might be configured on the point for set operations

Example

import cimplicity

with cimplicity.Point() as point1, cimplicity.Point() as point2:
    points = [point1, point2]

    point1.id = 'PointWSTRING_20'
    point1.set_value('')
    assert point1.get_value() == '', f'problem clearing point {point1.id}'

    point2.id = 'PointINT'
    point2.set_value(0)
    assert point2.get_value() == 0, f'problem clearing point {point2.id}'

    point1.value = 'sampling complete'
    point2.value = 17
    cimplicity.point_set_multiple(points)
    cimplicity.point_read_multiple(points)

    assert point1.value == 'sampling complete', f'point {point1.id} has wrong value'
    assert point2.value == 17, f'point {point2.id} has wrong value'

def project_clear_user_password(project: str, user: str, password: str)

Clears the CIMPLICITY project user name and password that will be used whenever a project login is required.

Returns a StatusSeverity indicating the result.

Note: This does not log out any currently logged in user. This does disable future attempts to automatically log in.

def project_login(project: str)

Initiates the CIMPLICITY login sequence for the project.

Returns a StatusSeverity indicating the result.

This function is asynchronous. It returns immediately, before the actual login has completed. For example, if no credentials have been set with project_set_user_password(), the the login dialog box will be shown. This function returns immediately while the login dialog box will remain until the user has logged in.

Example

import cimplicity

PROJECT = 'BLANK'
cimplicity.project_set_user_password(PROJECT, 'merida', 'N39gwMgA9N')
cimplicity.project_logout(PROJECT)
cimplicity.project_login(PROJECT)
print(cimplicity.point_get(f'\\\\{PROJECT}\\PointINT'))

def project_logout(project: str)

Forces a logout of the currently logged in user.

Returns a StatusSeverity indicating the result.

Example

import cimplicity

PROJECT = 'BLANK'
cimplicity.project_set_user_password(PROJECT, 'merida', 'N39gwMgA9N')
cimplicity.project_logout(PROJECT)
cimplicity.project_login(PROJECT)
print(cimplicity.point_get(f'\\\\{PROJECT}\\PointINT'))

def project_set_user_password(project: str, user: str, password: str)

Sets the CIMPLICITY project user name and password that will be used whenever a project login is required.

Returns a StatusSeverity indicating the result.

These parameters remain set until explicitly updated or cleared (see project_clear_user_password()). This means that if the user is logged out (for example, by the system timeouts forcing a logout), a subsequent request would again reference this data for login.

Note: If the provided credentials are not valid, no attempt is made to obtain the login information via GUI or otherwise, and no error is given.

def terminate_api_in_thread()

This function is used to cleanup CIMPLICITY resources that are allocated for thread local storage before a thread exits. This does not need to be called in threads that EMRP creates for running events. If however CIMPLICITY APIs are used in a Python created thread this should be called before it exits.

Example

import cimplicity
import threading

def thread_function(point_int64, point_value):
    with point_int64:
        point_int64.set_value(point_value)
    # The `with` statement above makes sure the point is detached from
    # ptmap before we terminate the api in this thread.
    cimplicity.terminate_api_in_thread()

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass

    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        point_int64 = cimplicity.Point()
        point_int64.id = "PointQINT"
        with point_int64:
            point_int64.set_value(int(event_data.point_event.value))
        # The `with` statement above makes sure the point is detached from
        # ptmap before handing it to the other thread.
        worker = threading.Thread(target=thread_function, args=(point_int64, int(event_data.point_event.value) + 10))
        worker.start()
        worker.join()

Classes

class AlarmState (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining the state of alarms.

(Note: in CimBasic, CP_RESET is a synonym for CP_CLEARED.)

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var ACKNOWLEDGED
var CLEARED
var DELETED
var GENERATED
var NONEXISTENT

class AlarmUpdateAction (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining possible alarm actions in the alarm_update() function.

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var ACKNOWLEDGE
var CLEAR
var DELETE

class ChangeApprovalLevel (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining various levels of change approval.

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var LOG_ONLY
var NONE
var PERFORM
var PERFORM_VERIFY
var UNSIGNED
var UNSIGNED_LOG_ONLY
var UNSIGNED_PERFORM
var UNSIGNED_PERFORM_VERIFY

class CimEMAlarmEvent (alarm_id: str, message: str, ref_id: str, resource_id: str, gen_timestamp_cimp: int, req_action: int, prev_state: int, final_state: int)

The CimEMAlarmEvent instances contain information about alarm based events in the event manager. A CimEMAlarmEvent object is the alarm_event member of the CimEMEvent object passed to the do_event_action method of the EventHandlerState class defined in each Python event manager script.

Parameters

alarm_id: str - The alarm id of the alarm that triggered the event.
message: str - The alarms message at the time the event was triggered.
ref_id: str - The reference id of the alarm that triggered the event.
resource_id: str - The resource id of the alarm that triggered the event.
gen_timestamp_cimp: int - The generation timestamp of the alarm that triggered the event. This is in units of 100 ns since January 1, 1970 00:00:00 UTC. That is, it is nanoseconds divided by 100 or milliseconds times 10,000.
req_action: int - The action requested on the alarm that triggered the alarm event. For example, if the user had acknowledged the alarm in the Alarm Viewer the requested action would be AlarmState.ACKNOWLEDGED.
prev_state: int - The previous state of the alarm. Before the triggering action occurred. This should be one of the AlarmState enum values.
final_state: int - The final state of the alarm after the requested action that triggered the event. For example, if the user acknowledged the alarm and the deletion requirements for the alarm only require acknowledgement then the final state would be AlarmState.DELETED. This should be one of the AlarmState enum values.

Example

import cimplicity
import sys
import time

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass

    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass

    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        if event_data.alarm_event is None:
            print(f"script ran for non alarm event")
        else:
            ae: cimplicity.CimEMAlarmEvent = event_data.alarm_event
            print(f'script ran for alarm "{ae.alarm_id}", ref "{ae.ref_id}"'
                  f' from state {ae.prev_state} to state {ae.final_state}')
        sys.stdout.flush()


def do_test():
    # create the EventHandlerState instance
    eh_state = EventHandlerState(cimplicity.EMEventActionContext(
        "TestEvent", "TestAction", None, None))
    # create the event and alarm event instances
    ts_cimp = time.time_ns() / 100  # in 100 ns units
    alm_event = cimplicity.CimEMAlarmEvent(
        "AlarmId", "alarm message", "RefId", "TEST_RESOURCE", ts_cimp,
        cimplicity.AlarmState.ACKNOWLEDGED, cimplicity.AlarmState.GENERATED,
        cimplicity.AlarmState.ACKNOWLEDGED)
    event = cimplicity.CimEMEvent(
        cimplicity.EventType.ALARM_ACK, None, "TestEvent", "TestAction",
        ts_cimp, alm_event, None, None)
    # call the do event action method
    eh_state.do_event_action(event)


if __name__ == "__main__":
    do_test()

Instance variables

var alarm_id

alarm_id: str

The alarm id of the alarm that triggered the action.

This is a read-only property.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_alarm_event(self, alarm_event: cimplicity.CimEMAlarmEvent):
        print('Start display_alarm')
        print(' alarm_event.alarm_id = ', alarm_event.alarm_id)
        print(' alarm_event.message = ', alarm_event.message)
        print(' alarm_event.ref_id = ', alarm_event.ref_id)
        print(' alarm_event.resource_id = ', alarm_event.resource_id)
        print(' alarm_event.gen_timestamp_ns = ', alarm_event.gen_timestamp_ns)
        print(' alarm_event.gen_timestamp_local = ', alarm_event.gen_timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.gen+timestamp_utc = ', alarm_event.gen_timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.req_action = ', alarm_event.req_action)
        print(' alarm_event.prev_state = ', alarm_event.prev_state)
        print(' alarm_event.final_state = ', alarm_event.final_state)
        print('end display_alarm')

var final_state

prev_state: AlarmState

The final state of the alarm after the requested action at the time the event was triggered. For example, if the user acknowledged the alarm and the deletion requirements for the alarm only require acknowledgement then the final state would be AlarmState.DELETED.

This is a read-only property.

Valid States are :

GENERATED: - The alarm is active and not acknowledged.
ACKNOWLEDGED: - The alarm is active and acknowledged.
CLEARED: - The alarm has returned to normal and is not acknowledged.
DELETED: - The alarm has met its deletion requirements.
NONEXISTENT: - The alarm is not in any alarm state

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_alarm_event(self, alarm_event: cimplicity.CimEMAlarmEvent):
        print('Start display_alarm')
        print(' alarm_event.alarm_id = ', alarm_event.alarm_id)
        print(' alarm_event.message = ', alarm_event.message)
        print(' alarm_event.ref_id = ', alarm_event.ref_id)
        print(' alarm_event.resource_id = ', alarm_event.resource_id)
        print(' alarm_event.gen_timestamp_ns = ', alarm_event.gen_timestamp_ns)
        print(' alarm_event.gen_timestamp_local = ', alarm_event.gen_timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.gen_timestamp_utc = ', alarm_event.gen_timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.req_action = ', alarm_event.req_action)
        print(' alarm_event.prev_state = ', alarm_event.prev_state)
        print(' alarm_event.final_state = ', alarm_event.final_state)
        print('end display_alarm')

var gen_timestamp_local

gen_timestamp_local: datetime

Represents the alarm generation timestamp at the time of the event as Python datetime object. This will be a time zone "naive" object in local time.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_string = event_data.alarm_event.gen_timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S %p")

var gen_timestamp_ns

gen_timestamp_ns: int

Represents the alarm generation timestamp at the time of the event in nanoseconds since the epoch (Jan 1, 1970 UTC). This is similar to Python time.time_ns(), but the resolution is 100 nanoseconds.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_ns = event_data.alarm_event.gen_timestamp_ns
        timestamp_string = str(timestamp_ns)

var gen_timestamp_utc

gen_timestamp_utc: datetime

Represents the alarm generation timestamp at the time of the event as Python datetime object. This will be a time zone "aware" object representing time in UTC.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_string = event_data.alarm_event.gen_timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S %p")

var message

message: str

The message of the alarm at the time event occurred.

This is a read-only property.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_alarm_event(self, alarm_event: cimplicity.CimEMAlarmEvent):
        print('Start display_alarm')
        print(' alarm_event.alarm_id = ', alarm_event.alarm_id)
        print(' alarm_event.message = ', alarm_event.message)
        print(' alarm_event.ref_id = ', alarm_event.ref_id)
        print(' alarm_event.resource_id = ', alarm_event.resource_id)
        print(' alarm_event.gen_timestamp_ns = ', alarm_event.gen_timestamp_ns)
        print(' alarm_event.gen_timestamp_local = ', alarm_event.gen_timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.gen+timestamp_utc = ', alarm_event.gen_timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.req_action = ', alarm_event.req_action)
        print(' alarm_event.prev_state = ', alarm_event.prev_state)
        print(' alarm_event.final_state = ', alarm_event.final_state)
        print('end display_alarm')

var prev_state

prev_state: AlarmState

The previous state of the alarm at the time the event was triggered.

This is a read-only property.

Valid States are :

GENERATED: - The alarm is active and not acknowledged.
ACKNOWLEDGED: - The alarm is active and acknowledged.
CLEARED: - The alarm has returned to normal and is not acknowledged.
DELETED: - The alarm has met its deletion requirements.
NONEXISTENT: - The alarm is not in any alarm state

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_alarm_event(self, alarm_event: cimplicity.CimEMAlarmEvent):
        print('Start display_alarm')
        print(' alarm_event.alarm_id = ', alarm_event.alarm_id)
        print(' alarm_event.message = ', alarm_event.message)
        print(' alarm_event.ref_id = ', alarm_event.ref_id)
        print(' alarm_event.resource_id = ', alarm_event.resource_id)
        print(' alarm_event.gen_timestamp_ns = ', alarm_event.gen_timestamp_ns)
        print(' alarm_event.gen_timestamp_local = ', alarm_event.gen_timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.gen+timestamp_utc = ', alarm_event.gen_timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.req_action = ', alarm_event.req_action)
        print(' alarm_event.prev_state = ', alarm_event.prev_state)
        print(' alarm_event.final_state = ', alarm_event.final_state)
        print('end display_alarm')

var ref_id

ref_id: str

The reference id of the alarm that triggered the action.

This is a read-only property.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_alarm_event(self, alarm_event: cimplicity.CimEMAlarmEvent):
        print('Start display_alarm')
        print(' alarm_event.alarm_id = ', alarm_event.alarm_id)
        print(' alarm_event.message = ', alarm_event.message)
        print(' alarm_event.ref_id = ', alarm_event.ref_id)
        print(' alarm_event.resource_id = ', alarm_event.resource_id)
        print(' alarm_event.gen_timestamp_ns = ', alarm_event.gen_timestamp_ns)
        print(' alarm_event.gen_timestamp_local = ', alarm_event.gen_timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.gen+timestamp_utc = ', alarm_event.gen_timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.req_action = ', alarm_event.req_action)
        print(' alarm_event.prev_state = ', alarm_event.prev_state)
        print(' alarm_event.final_state = ', alarm_event.final_state)
        print('end display_alarm')

var req_action

req_action: AlarmState

The action requested on the alarm. For example, if the user had acknowledged the alarm in the Alarm Viewer the requested action would be AlarmState.ACKNOWLEDGED.

This is a read-only property.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_alarm_event(self, alarm_event: cimplicity.CimEMAlarmEvent):
        print('Start display_alarm')
        print(' alarm_event.alarm_id = ', alarm_event.alarm_id)
        print(' alarm_event.message = ', alarm_event.message)
        print(' alarm_event.ref_id = ', alarm_event.ref_id)
        print(' alarm_event.resource_id = ', alarm_event.resource_id)
        print(' alarm_event.gen_timestamp_ns = ', alarm_event.gen_timestamp_ns)
        print(' alarm_event.gen_timestamp_local = ', alarm_event.gen_timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.gen+timestamp_utc = ', alarm_event.gen_timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.req_action = ', alarm_event.req_action)
        print(' alarm_event.prev_state = ', alarm_event.prev_state)
        print(' alarm_event.final_state = ', alarm_event.final_state)
        print('end display_alarm')

var resource_id

resource_id: str

The resource id of the alarm that triggered the action.

This is a read-only property.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_alarm_event(self, alarm_event: cimplicity.CimEMAlarmEvent):
        print('Start display_alarm')
        print(' alarm_event.alarm_id = ', alarm_event.alarm_id)
        print(' alarm_event.message = ', alarm_event.message)
        print(' alarm_event.ref_id = ', alarm_event.ref_id)
        print(' alarm_event.resource_id = ', alarm_event.resource_id)
        print(' alarm_event.gen_timestamp_ns = ', alarm_event.gen_timestamp_ns)
        print(' alarm_event.gen_timestamp_local = ', alarm_event.gen_timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.gen+timestamp_utc = ', alarm_event.gen_timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' alarm_event.req_action = ', alarm_event.req_action)
        print(' alarm_event.prev_state = ', alarm_event.prev_state)
        print(' alarm_event.final_state = ', alarm_event.final_state)
        print('end display_alarm')

class CimEMEvent (event_type: int, object_id: str, event_id: str, action_id: str, timestamp_cimp: int, alarm_event: CimEMAlarmEvent, point_event: CimEMPointEvent, shutdown_event: CimEMShutdownEvent)

An object used by the Event Manager to hold information about the event that triggered the action. A CimEMEvent object instance is passed to the do_event_action method of the EventHandlerState class defined in each Python event manager script.

Parameters

type: int - The type of event that triggered the event. This should be one of the EventType enum values.
object_id: str - If this event-action is part of a class definition this will be the object_id the event-action was created for.
event_id: str - The event id that identifies the event that triggered the execution of this script.
action_id: str - The action id that identifies the action running the script.
timestamp_cimp: int - The timestamp that indicates when the event that triggered the action occurred. This is in units of 100 ns since January 1, 1970 00:00:00 UTC. That is, it is nanoseconds divided by 100 or milliseconds times 10,000.
alarm_event: CimEMAlarmEvent - The alarm information for events that are triggered by alarms events. May be None if this event is not an alarm event.
point_event: CimEMPointEvent - The point information for events that are triggered by point events. May be None if this event is not a point event.
shutdown_event: CimEMShutdownEvent - The shutdown information for events that are triggered by EMPR shutting down or reloading the script. May be None if this event is not a shutdown event.

Example

import cimplicity
import sys
import time

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass

    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass

    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        cimplicity.log_status(
            cimplicity.StatusSeverity.SUCCESS, "myscript", "script ran")

def do_test():
    # emulate a CIMPLICITY class object event
    obj_attrs = {"$DEVICE_ID": "TEST_DEVICE",
                 "$RESOURCE_ID": "TEST_RESOURCE"}
    eactx = cimplicity.EMEventActionContext(
        "TESTOBJECT.TestEvent", "TESTOBJECT.TestAction", "TestObject",
        obj_attrs)

    EventHandlerState(eactx).do_event_action(cimplicity.CimEMEvent(
        cimplicity.EventType.RUN_ONCE, "TestObject", "TESTOBJECT.TestEvent",
        "TESTOBJECT.TestAction", time.time_ns() / 100, None, None, None))

if __name__ == "__main__":
    do_test()

Instance variables

var action_id

action_id: str

The ID of the action running the script.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        print('start EventHandlerState.do_event_action')
        print('type: ' , event_data.type)
        print('object_id: ' , event_data.object_id)
        print('event_id: ' , event_data.event_id)
        print('action_id: ' + event_data.action_id)
        print('timestamp_ns: ', event_data.timestamp_ns)
        print('timestamp_local: ', event_data.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print('timestamp_utc: ',  event_data.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        if(event_data.point_event != None):
            self.display_point_event(event_data.point_event)
        if(event_data.alarm_event != None):
            self.display_alarm_event(event_data.alarm_event)
        print('end EventHandlerState.do_event_action')

var alarm_event

alarm_event: CimEMAlarmEvent

An instance of CimEMAlarmEvent that provides information about the alarm event that triggered an event. If the event is not an alarm event this property has the value None.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        print('start EventHandlerState.do_event_action')
        print('type: ' , event_data.type)
        print('object_id: ' , event_data.object_id)
        print('event_id: ' , event_data.event_id)
        print('action_id: ' + event_data.action_id)
        print('timestamp_ns: ', event_data.timestamp_ns)
        print('timestamp_local: ', event_data.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print('timestamp_utc: ',  event_data.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        if(event_data.point_event != None):
            self.display_point_event(event_data.point_event)
        if(event_data.alarm_event != None):
            self.display_alarm_event(event_data.alarm_event)
        print('end EventHandlerState.do_event_action')

var event_id

event_id: str

The event id that triggered this action.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        print('start EventHandlerState.do_event_action')
        print('type: ' , event_data.type)
        print('object_id: ' , event_data.object_id)
        print('event_id: ' , event_data.event_id)
        print('action_id: ' + event_data.action_id)
        print('timestamp_ns: ', event_data.timestamp_ns)
        print('timestamp_local: ', event_data.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print('timestamp_utc: ',  event_data.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        if(event_data.point_event != None):
            self.display_point_event(event_data.point_event)
        if(event_data.alarm_event != None):
            self.display_alarm_event(event_data.alarm_event)
        print('end EventHandlerState.do_event_action')

var object_id

object_id: str

The ID of the object instance associated with this event-action. This property only has a value if this event-action is part of class.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        print('start EventHandlerState.do_event_action')
        print('type: ' , event_data.type)
        print('object_id: ' , event_data.object_id)
        print('event_id: ' , event_data.event_id)
        print('action_id: ' + event_data.action_id)
        print('timestamp_ns: ', event_data.timestamp_ns)
        print('timestamp_local: ', event_data.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print('timestamp_utc: ',  event_data.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        if(event_data.point_event != None):
            self.display_point_event(event_data.point_event)
        if(event_data.alarm_event != None):
            self.display_alarm_event(event_data.alarm_event)
        print('end EventHandlerState.do_event_action')

var point_event

point_event: CimEMPointEvent

An instance of CimEMPointEvent that provides information about the point event that triggered an event. If the event is not a point event this property has the value None.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        print('start EventHandlerState.do_event_action')
        print('type: ' , event_data.type)
        print('object_id: ' , event_data.object_id)
        print('event_id: ' , event_data.event_id)
        print('action_id: ' + event_data.action_id)
        print('timestamp_ns: ', event_data.timestamp_ns)
        print('timestamp_local: ', event_data.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print('timestamp_utc: ',  event_data.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        if(event_data.point_event != None):
            self.display_point_event(event_data.point_event)
        if(event_data.alarm_event != None):
            self.display_alarm_event(event_data.alarm_event)
        print('end EventHandlerState.do_event_action')

var shutdown_event

shutdown_event: CimEMShutdownEvent

An instance of CimEMShutdownEvent that provides information about the reason for the do_shutdown being called. If the event is not a shutdown this property has the value None.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        print('start EventHandlerState.do_shutdown')
        print('   Shutdown reason : ', event_data.shutdown_event.reason)
        print('end EventHandlerState.do_shutdown')
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

var timestamp_local

timestamp_local: datetime

Represents the timestamp at the time of the event as Python datetime object. This will be a time zone "naive" object in local time.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_string = event_data.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S %p")

var timestamp_ns

timestamp_ns: int

Represents the timestamp at the time of the event in nanoseconds since the epoch (Jan 1, 1970 UTC). This is similar to Python time.time_ns(), but the resolution is 100 nanoseconds.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_ns = event_data.timestamp_ns
        timestamp_string = str(timestamp_ns)

var timestamp_utc

timestamp_utc: datetime

Represents the timestamp at the time of the event as Python datetime object. This will be a time zone "aware" object representing time in UTC.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_string = event_data.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S %p")

var type

type: EventType

The type of event that triggered the action

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        print('start EventHandlerState.do_event_action')
        print('type: ' , event_data.type)
        print('object_id: ' , event_data.object_id)
        print('event_id: ' , event_data.event_id)
        print('action_id: ' + event_data.action_id)
        print('timestamp_ns: ', event_data.timestamp_ns)
        print('timestamp_local: ', event_data.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print('timestamp_utc: ',  event_data.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        if(event_data.point_event != None):
            self.display_point_event(event_data.point_event)
        if(event_data.alarm_event != None):
            self.display_alarm_event(event_data.alarm_event)
        print('end EventHandlerState.do_event_action')

class CimEMPointEvent (id: str, value: str, quality: QualityFlags, timestamp_cimp: int, state: int, user_flags: int)

The CimEMPointEvent instances contain information about point based events in the event manager. A CimEMPointEvent object instance is the point_event member of the CimEMEvent object instance passed to the do_event_action method of the EventHandlerState class defined in each Python event manager script.

Parameters

id: str - The point id of the point that triggered the event.
value: str - The value of the point at the time the event was triggered.
quality: QualityFlags - The 64-bit quality bitmask of the point at the time the event was triggered.
timestamp_cimp: int - The timestamp of the point at the time the event was triggered. This is in units of 100 ns since January 1, 1970 00:00:00 UTC. That is, it is nanoseconds divided by 100 or milliseconds times 10,000.
state: int - The state of the point at the time the event was triggered. This should be one of the PointState enum values.
user_flags: int - The value of the points user flags at the time the event was triggered.

Example

import cimplicity
import sys
import time

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass

    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass

    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        if event_data.point_event is None:
            print(f"script ran for non point event")
        else:
            print(f'script ran for point "{event_data.point_event.id}"')
        sys.stdout.flush()


def do_test():
    # create the EventHandlerState instance
    eh_state = EventHandlerState(cimplicity.EMEventActionContext(
        "TestEvent", "TestAction", None, None))
    # create the event and point event instances
    ts_cimp = time.time_ns() / 100  # in 100 ns units
    pt_event = cimplicity.CimEMPointEvent(
        "PointId", "17", cimplicity.QualityFlags(300), ts_cimp,
        cimplicity.PointState.NORMAL, 0)
    event = cimplicity.CimEMEvent(
        cimplicity.EventType.POINT_CHANGE, None, "TestEvent", "TestAction",
        ts_cimp, None, pt_event, None)
    # call the do event action method
    eh_state.do_event_action(event)


if __name__ == "__main__":
    do_test()

Instance variables

var id

id: str

The point id of the point that triggered the event.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_point_event(self, point_event: cimplicity.CimEMPointEvent):
        print('Start display_point')
        print(' point_event.id = ', point_event.id)
        print(' point_event.value = ', point_event.value)
        print(' point_event.quality = ', point_event.quality)
        print(' point_event.timestamp_ns = ', point_event.timestamp_ns)
        print(' point_event.timestamp_local = ', point_event.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.timestamp_utc = ', point_event.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.state = ', point_event.state)
        print(' point_event.user_flags = ', point_event.user_flags)
        print('end display_point')

var quality

quality: QualityFlags

The 64-bit quality bitmask for the point at the time the event was triggered

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_point_event(self, point_event: cimplicity.CimEMPointEvent):
        print('Start display_point')
        print(' point_event.id = ', point_event.id)
        print(' point_event.value = ', point_event.value)
        print(' point_event.quality = ', point_event.quality)
        print(' point_event.timestamp_ns = ', point_event.timestamp_ns)
        print(' point_event.timestamp_local = ', point_event.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.timestamp_utc = ', point_event.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.state = ', point_event.state)
        print(' point_event.user_flags = ', point_event.user_flags)
        print('end display_point')

var quality_alarmed

quality_alarmed: bool

This property has the value of True if the point is in alarm, False otherwise at the time of the event.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        is_alarmed = event_data.point_event.quality_alarmed

var quality_alarms_enabled

quality_alarms_enabled: bool

This property has the value of True if alarming for the point is enabled at the time of the event, False otherwise.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        is_alarmed = event_data.point_event.quality_alarms_enabled

var quality_disable_write

quality_disable_write: bool

This property has the value of True if setpoints have been disabled for the point at the time of the event, otherwise it is False.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
       is_alarmed = event_data.point_event.quality_disable_write

var quality_is_available

quality_is_available: bool

This property has the value of True if the point value is available at the time of the event, otherwise it is False.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
       is_alarmed = event_data.point_event.quality_is_available

var quality_is_in_range

quality_is_in_range: bool

This property has the value of True if the current value of the point is in range at the time of the event, otherwise it is False. When a point is out of range its value is unavailable.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
       is_alarmed = event_data.point_event.quality_last_update_manual

var quality_is_stale_data

quality_is_stale_data: bool

This property has the value of True if the value of point is "stale" at the time of the event, otherwise it is False.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
       is_alarmed = event_data.point_event.quality_is_stale_data

var quality_last_update_manual

quality_last_update_manual: bool

This property has the value of True if the current value of the point at the time of the event came from a manual update rather than a device read, otherwise it is False.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
       is_alarmed = event_data.point_event.quality_last_update_manual

var quality_manual_mode

quality_manual_mode: bool

This property has the value of True if the point has been placed into Manual Mode at the time of the event, otherwise it is False.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
       is_alarmed = event_data.point_event.quality_manual_mode

var state

state: PointState

The value of the points state at the time the event was triggered.

This property is read-only

NORMAL: Point is in "Normal" state
ALARM: Point is in "Alarm" state
WARNING: Point is in "Warning" state
ALARM_HIGH: Point is in "Alarm High" state
ALARM_LOW: Point is in "Alarm Low" state
WARNING_HIGH: Point is in "Warning High" state
WARNING_LOW: Point is in "Warning Low" state
AVAILABLE: Point has gone from "Unavailable" to "Available" state
UNAVAILABLE: Point has gone from "Available" to "Unavailable" state

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_point_event(self, point_event: cimplicity.CimEMPointEvent):
        print('Start display_point')
        print(' point_event.id = ', point_event.id)
        print(' point_event.value = ', point_event.value)
        print(' point_event.quality = ', point_event.quality)
        print(' point_event.timestamp_ns = ', point_event.timestamp_ns)
        print(' point_event.timestamp_local = ', point_event.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.timestamp_utc = ', point_event.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.state = ', point_event.state)
        print(' point_event.user_flags = ', point_event.user_flags)
        print('end display_point')

var timestamp_local

timestamp_local: datetime

Represents the point timestamp at the time of the event as Python datetime object. This will be a time zone "naive" object in local time.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_string = event_data.point_event.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S %p")

var timestamp_ns

timestamp_ns: int

Represents the point timestamp at the time of the event in nanoseconds since the epoch (Jan 1, 1970 UTC). This is similar to Python time.time_ns(), but the resolution is 100 nanoseconds.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_ns = event_data.point_event.timestamp_ns
        timestamp_string = str(timestamp_ns)

var timestamp_utc

timestamp_utc: datetime

Represents the point timestamp at the time of the event as Python datetime object. This will be a time zone "aware" object representing time in UTC.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data):
        timestamp_string = event_data.point_event.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S %p")

var user_flags

user_flags: int

The value of the points user flags at the time the event was triggered.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_point_event(self, point_event: cimplicity.CimEMPointEvent):
        print('Start display_point')
        print(' point_event.id = ', point_event.id)
        print(' point_event.value = ', point_event.value)
        print(' point_event.quality = ', point_event.quality)
        print(' point_event.timestamp_ns = ', point_event.timestamp_ns)
        print(' point_event.timestamp_local = ', point_event.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.timestamp_utc = ', point_event.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.state = ', point_event.state)
        print(' point_event.user_flags = ', point_event.user_flags)
        print('end display_point')

var value

value: str

The value of the point at the time the event was triggered.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def display_point_event(self, point_event: cimplicity.CimEMPointEvent):
        print('Start display_point')
        print(' point_event.id = ', point_event.id)
        print(' point_event.value = ', point_event.value)
        print(' point_event.quality = ', point_event.quality)
        print(' point_event.timestamp_ns = ', point_event.timestamp_ns)
        print(' point_event.timestamp_local = ', point_event.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.timestamp_utc = ', point_event.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S.%f %p"))
        print(' point_event.state = ', point_event.state)
        print(' point_event.user_flags = ', point_event.user_flags)
        print('end display_point')

class CimEMShutdownEvent (reason: int)

The CimEMShutdownEvent instances contain information about shutdown events in the event manager. A CimEMShutdownEvent object instance is the shutdown_event member of the CimEMEvent object passed to the do_shutdown method of the EventHandlerState class defined in each Python event manager script.

Parameters

reason: int - The reason the do_shutdown method was called.

Example

import cimplicity
import time

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass


def do_test():
  test_event_action_context = cimplicity.EMEventActionContext("TestEvent", "TestAction", None, None)

  test_event_handler_state = EventHandlerState(test_event_action_context)

  event_time_stamp = time.time_ns()//100

  shutdown_event = cimplicity.CimEMShutdownEvent(cimplicity.ShutdownReason.SCRIPT_RELOAD)

  test_event = cimplicity.CimEMEvent(cimplicity.EventType.SHUTDOWN, "TestObject", "TestEvent", "TestAction", event_time_stamp, None, None, shutdown_event)

  test_event_handler_state.do_shutdown(test_event)

Instance variables

var reason

reason: ShutdownReason

The the reason the do_shutdown method was called on the EventHandlerState object instance for an event-action.

This is a read-only property.

Valid reasons are :

SCRIPT_RELOAD: - The event manager recieved a dynamic update request and the script that impliments the EventHandlerState for this event has changed.
PROCESS_SHUTDOWN: - The event manager is shutting down.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        print('Start do_shutdown')
        print(' event_data.shutdown_event.reason = ', event_data.shutdown_event.reason)
        print('end do_shutdown')

class EMEventActionContext (event_id: str, action_id: str, object_id: str, object_attributes: dict)

Objects of this class contain information that is useful for initializing an instance the user defined EventHandlerState class. An EMEventActionContext object instance is passed to the __init__ method of the EventHandlerState class defined in each Python event manager script.

Parameters

event_id: str - The event id that identifies the event configured in the event manager configuration.
action_id: str - The action id that identifies the action configured in the event manager configuration.
object_id: str - If this event-action is part of a class definition this will be the object_id instance the event-action is created for.
object_attributes: dict - If this event-action is part of a class definition this will be a dictionary of all the object attributes and their values used to define the object instance this event-action is associated with.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        pass
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

object_attributes = {"$DEVICE_ID" : "TEST_DEVICE", "$RESOURCE_ID" : "TEST_RESOURCE"}

test_event_action_context = cimplicity.EMEventActionContext("TestEvent", "TestAction", "TestObject", object_attributes)

test_event_handler_state = EventHandlerState(test_event_action_context)

Instance variables

var action_id

action_id: str

The ID of the action configured in the event manager configuration.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        print('start EventHandlerState.__init__')
        print('event_id: ', event_action_context.event_id)
        print('action_id: ', event_action_context.action_id)
        print('object_id: ', event_action_context.object_id)
        print('object_attributes: ', event_action_context.object_attributes)
        print('end EventHandlerState.__init__ end')
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

var event_id

event_id: str

The ID of the event configured in the event manager configuration.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        print('start EventHandlerState.__init__')
        print('event_id: ', event_action_context.event_id)
        print('action_id: ', event_action_context.action_id)
        print('object_id: ', event_action_context.object_id)
        print('object_attributes: ', event_action_context.object_attributes)
        print('end EventHandlerState.__init__ end')
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

var object_attributes

object_attributes: dict

The object instance attributes associated with this event-action. This property only has a value if this event-action is part of class.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        print('start EventHandlerState.__init__')
        print('event_id: ', event_action_context.event_id)
        print('action_id: ', event_action_context.action_id)
        print('object_id: ', event_action_context.object_id)
        print('object_attributes: ', event_action_context.object_attributes)
        print('end EventHandlerState.__init__ end')
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

var object_id

object_id: str

The ID of the object instance associated with this event-action. This property only has a value if this event-action is part of class.

This property is read-only.

Example

import cimplicity

class EventHandlerState:
    def __init__(self, event_action_context: cimplicity.EMEventActionContext):
        print('start EventHandlerState.__init__')
        print('event_id: ', event_action_context.event_id)
        print('action_id: ', event_action_context.action_id)
        print('object_id: ', event_action_context.object_id)
        print('object_attributes: ', event_action_context.object_attributes)
        print('end EventHandlerState.__init__ end')
    def do_shutdown(self, event_data: cimplicity.CimEMEvent):
        pass
    def do_event_action(self, event_data: cimplicity.CimEMEvent):
        pass

class Error (*args, **kwargs)

Base class for exceptions in this module.

Ancestors

builtins.Exception
builtins.BaseException

Subclasses

ScriptStoppedError

class EventType (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining the types of events that can trigger actions

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var ALARM_ACK
var ALARM_CLR
var ALARM_DEL
var ALARM_GEN
var POINT_CHANGE
var POINT_EQUALS
var POINT_TRANS_HIGH
var POINT_TRANS_LOW
var POINT_UNAVAIL
var POINT_UPDATE
var RUN_ONCE
var SHUTDOWN
var TIMED
var TRIGGERED

class OnAlarmState (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining the possible conditions to use in the OnAlarm method.

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var ALARM
var ALARM_HIGH
var ALARM_LOW
var NONE
var WARNING
var WARNING_HIGH
var WARNING_LOW

class Point (default_project='')

The Point class provides an object-oriented interface to CIMPLICITY real-time point data. Using this class, you may set and read point values. Methods are supplied to receive the point value as it changes, periodically, or when the alarm state changes.

A point object should be used with a with statement to help ensure that a scope of usage detaches the Point from ptmap. Simple common usage is with cimplicity.Point() as my_point:.

In more advanced scenarios, the with statement can also be used to attach a previously created point object to ptmap, if the point object was previously detached. This would look like with my_point:.

In addition to using a with statement, a point object can be attached and detached from ptmap using the Point.attach_ptmap() and Point.detach_ptmap() methods.

Threading. While it is attached to ptmap, a Point object is only valid in 1 thread at a time. After calling Point.detach_ptmap() a script can call Point.attach_ptmap() in another thread to use the point in another thread. It cannot be used in multiple threads at the same time while it is attached. Before a script exits all the Point objects must be detached from Ptmap using the detach_ptmap() method or by exiting a with block. See the example in terminate_api_in_thread().

Parameters

default_project: str - optional parameter, if provided will use the given project for non-fully qualified point ids.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'
    x = my_point.get_value()

Instance variables

var added

added: bool

Use this property to determine if the point has been added to ptmap. A point is automatically added when the Point.id property is assigned. It is not added automatically when the Point.set_id_without_add() is called. To add point if added is false, and the Point.id property is not empty, Point.add_point() or point_add_multiple() can be called. When Point.detach_ptmap() is called, or when a with block using a point is exited the Point.added will be false.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.added
    print("PointINT added: ", x)

var alarm_ack

alarm_ack: bool

When used in combination with the Point.on_alarm_ack() method, a Boolean value is returned indicating if the point's alarm is in an Acknowledged state.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:

    my_point.id = 'PointAlarmLimits'

    my_point.on_alarm_ack()
    my_point.read_next(0)
    my_point.read_next(-1)

    x = my_point.alarm_ack

var change_approval_level

change_approval_level: ChangeApprovalLevel

The level of change approval that is required to perform an operation.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:

    my_point.id = 'PointINT'
    if my_point.change_approval_level == cimplicity.ChangeApprovalLevel.PERFORM_VERIFY:
        my_point.set_change_approval_info(performer_user_id='USER1', performer_password='MyPassword1!', performer_comment='Performed by USER1', verifier_user_id='VERIFIER1', verifier_password='MyPassword@2', verifier_comment='Verified by VERIFIER1')

    my_point.set_value(my_point.get_value() + 100)

var data_length

data_length: int

Represents the length in bytes of the point value. This is valid only for character strings.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointSTRING_20'

    x = my_point.data_length
    print("PointSTRING_20 Data Length: ", x)

var data_type

data_type: PointDataType

The CIMPLICITY point type.

This property is read-only.

Example

import cimplicity

def data_type_conv(argument):
    switcher = {
        cimplicity.PointDataType.COR_U1: "std::uint8_t",
        cimplicity.PointDataType.COR_U2: "std::uint16_t",
        cimplicity.PointDataType.COR_U4: "std::uint32_t",
        cimplicity.PointDataType.COR_U8: "std::uint64_t",
        cimplicity.PointDataType.COR_I1: "std::int8_t",
        cimplicity.PointDataType.COR_I2: "std::int16_t",
        cimplicity.PointDataType.COR_I4: "std::int32_t",
        cimplicity.PointDataType.COR_I8: "std::int64_t",
    }
    return switcher.get(argument, "Invalid Data Type")

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    dt = my_point.data_type
    print("PointINT Data Type: ", data_type_conv(dt))

var display_format

display_format: str

A string containing the configured display format for the point.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.display_format
    print("PointINT Display Format: ", x)

var download_password

download_password: bool

Use this property to determine if a download password is required to set the point.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.download_password
    print("PointINT Download Password Required: ", x)

var enabled

enabled: bool

Use this property to determine if the point is enabled to be collected from the PLC.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.enabled
    print("PointINT Enabled: ", x)

var error_code

error_code: int

This property is the error code if an error occured during an operation on the Point object. The value is None if there is no current error.

This property is read-only.

See also: Point.error_msg, Point.has_error

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.read()

    if my_point.has_error:
        print("Error message = ", my_point.error_msg, " Error code = ", my_point.error_code)

var error_msg

error_msg: str

This property is the error message if an error occured with an operation on the Point object. The value is None if there is no current error.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.read()

    x = my_point.user_flags

var eu_label

eu_label: str

This is the name of the engineering units (e.g. "psi") configured on this point.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.eu_label
    print("PointINT Engineering Unit Label: ", x)

var has_error

has_error: bool

This property is true if an error occured in an operation performed on a the Point object.

This property is read-only.

See also: Point.error_msg, Point.error_code

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.read()

    if my_point.has_error:
        print("Error message = ", my_point.error_msg, " Error code = ", my_point.error_code)

var has_eu_conversion

has_eu_conversion: bool

Use this property to determine if the point has engineering units conversion configured.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.has_eu_conversion
    print("PointINT Engineering Units Conversion Configured: ", x)

var has_set_point_priv

has_set_point_priv: bool

This property is True if the user on whose behalf the script is executing has the setpoint privilege for this point. Otherwise it is False.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.has_set_point_priv
    print("PointINT Has Set Point Privileges: ", x)

var id

id: str

Represents the object's CIMPLICITY Point ID. Assignment will throw an exception if the point is not configured or the remote server is not available.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'
    mp = my_point.get_value()

var in_user_view

in_user_view: bool

Use this property to determine if the point is in the user's view.

If "Resource Setpoint Security" is checked in the Point Setup dialog box for the point's project and the point's resource is not in the user's view, then it is False.
If "Level Setpoint Security" is checked in the Point Setup dialog box and the point's level is greater than the level of the user's role, then it is False.
Otherwise, it is True.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.in_user_view
    print("PointINT is In User's View: ", x)

var num_elements

num_elements: int

This property represents the number of elements configured for the point. For array points this will be greater than 1, for non-array points the value will be 1.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT_x5'

    x = my_point.num_elements
    print("PointINT_x5 Number of Elements: ", x)

var point_type_id

point_type_id: str

This property represents point data type name.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.point_type_id
    print("PointINT Point Type: ", x)

var ptmap_detached

ptmap_detached: bool

Use this property to determine if the point has been detached from ptmap. A point is automatically attached when it is constucted or when a with block is entered. To attach a point if Point.ptmap_detached is true call Point.attach_ptmap() or enter a with block using the Point so that functionality that requires communicating with CIMPLICITY can be used. When Point.detach_ptmap() is called or when a with block using a Point is exited the property Point.ptmap_detached will be true.

This property is read-only.

Example

import cimplicity

my_point = cimplicity.Point()
with my_point:
    my_point.id = 'PointINT'

x = my_point.ptmap_detached
print("PointINT detached: ", x)

var quality

quality: QualityFlags

The 64-bit quality bitmask for the point. The quality flag bits are defined in QualityFlags.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointREAL'
    my_point2.id = 'PointUQINT'

    my_point.read()

    x = my_point.quality

    my_point2.set_value(x)

var quality_alarmed

quality_alarmed: bool

This property has the value of True if the point is in alarm, False otherwise.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointBOOL'

    my_point.read()

    x = my_point.quality_alarmed

    my_point2.set_value(x)

var quality_alarms_enabled

quality_alarms_enabled: bool

This property has the value of True if alarming for the point is enabled, False otherwise.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointBOOL'

    my_point.read()

    x = my_point.quality_alarms_enabled

    my_point2.set_value(x)

var quality_disable_write

quality_disable_write: bool

This property has the value of True if setpoints have been disabled for the point, otherwise it is False.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointBOOL'

    my_point.read()

    x = my_point.quality_disable_write

    my_point2.set_value(x)

var quality_is_available

quality_is_available: bool

This property has the value of True if the point value is available, otherwise it is False.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointBOOL'

    my_point.read()

    x = my_point.quality_is_available

    my_point2.set_value(x)

var quality_is_in_range

quality_is_in_range: bool

This property has the value of True if the current value of the point is in range, otherwise it is False. When a point is out of range its value is unavailable.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointBOOL'

    my_point.read()

    x = my_point.quality_is_in_range

    my_point2.set_value(x)

var quality_is_stale_data

quality_is_stale_data: bool

This property has the value of True if the value of point is "stale", otherwise it is False.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointBOOL'

    my_point.read()

    x = my_point.quality_is_stale_data

    my_point2.set_value(x)

var quality_last_update_manual

quality_last_update_manual: bool

This property has the value of True if the current value of the point came from a manual update rather than a device read, otherwise it is False.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointBOOL'

    my_point.read()

    x = my_point.quality_last_update_manual

    my_point2.set_value(x)

var quality_manual_mode

quality_manual_mode: bool

This property has the value of True if the point has been placed into Manual Mode, otherwise it is False.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointBOOL'

    my_point.read()

    x = my_point.quality_manual_mode

    my_point2.set_value(x)

var raw_value

raw_value: Any

Same as the value property except that it bypasses engineering units conversion if configured for the point. Will return into Any type, subject to some restrictions. All numeric types may be returned into any other numeric type and into string types. String and BitString types can only be returned into string types.

Note: It does not return the underlying numerical value for an enumerated point. If you want to obtain the underlying numerical value, define a point with the id property set to <point_id>.$RAW_VALUE. Use the value property of that point.

When setting a value of an array point, the passed list must have the same number of elements as the num_elements property of this point. Otherwise the ValueError exception is raised.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.raw_value
    print("PointINT Raw Value: ", x)

var state

state: PointState

This property represents the state of the point's value. It can be any of these values:

NORMAL: Point is in "Normal" state
ALARM: Point is in "Alarm" state
WARNING: Point is in "Warning" state
ALARM_HIGH: Point is in "Alarm High" state
ALARM_LOW: Point is in "Alarm Low" state
WARNING_HIGH: Point is in "Warning High" state
WARNING_LOW: Point is in "Warning Low" state
AVAILABLE: Point has gone from "Unavailable" to "Available" state
UNAVAILABLE: Point has gone from "Available" to "Unavailable" state

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointAlarmLimits'
    my_point2.id = 'PointINT'

    my_point.read()

    x = my_point.state

    my_point2.set_value(x)

var timestamp_local

timestamp_local: datetime

Represents the point timestamp as Python datetime object. This will be a time zone "naive" object in local time.

Note: This value is rounded to the microsecond resolution of the datetime object. To get the full CIMPLICITY 100-nanosecond resolution use the Point.timestamp_ns property.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointBOOL'
    my_point2.id = 'PointSTRING_80'

    my_point.set_value(1)
    my_point.read()

    timestamp_string = my_point.timestamp_local.strftime("%#m/%#d/%Y %#I:%M:%S %p")

    my_point2.set_value(timestamp_string)

var timestamp_ns

timestamp_ns: int

Represents the point timestamp in nanoseconds since the epoch (Jan 1, 1970 UTC). This is similar to Python time.time_ns(), but the resolution is 100 nanoseconds.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointBOOL'
    my_point2.id = 'PointUQINT'

    my_point.set_value(1)
    my_point.read()

    timestamp_ns = my_point.timestamp_ns
    timestamp_string = str(timestamp_ns)

    my_point2.set_value(timestamp_string)

var timestamp_utc

timestamp_utc: datetime

Represents the point timestamp as Python datetime object. This will be a time zone "aware" object representing time in UTC.

Note: This value is rounded to the microsecond resolution of the datetime object. To get the full CIMPLICITY 100-nanosecond resolution use the Point.timestamp_ns property.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point, cimplicity.Point() as my_point2:

    my_point.id = 'PointBOOL'
    my_point2.id = 'PointSTRING_80'

    my_point.set_value(1)
    my_point.read()

    timestamp_string = my_point.timestamp_utc.strftime("%#m/%#d/%Y %#I:%M:%S %p")

    my_point2.set_value(timestamp_string)

var user_flags

user_flags: int

This property represents the value of the 64-bit user-defined flags for the point.

This property is read-only.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.read()

    x = my_point.user_flags

var value

value: Any

Use this property to retrieve or set the value in the point object.

The value property uses Engineering Units conversion if supplied by the point. To bypass Engineering Units conversion, use the raw_value property. Automatic conversion will be performed between data types as needed. The only exceptions are String and BitString points, which can only be assigned from strings.

When setting a value of an array point, the passed list must have the same number of elements as the num_elements property of this point. Otherwise the ValueError exception is raised.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.read()
    x = my_point.value

Methods

def add_point()

Adds the Point object to the ptmap instance in a thread. A Point point object needs to have the Point.add_point() or point_add_multiple() affter calling Point.set_id_without_add()(id). After calling Point.detach_ptmap(), a call to Point.attach_ptmap() and (Point.add_point() or point_add_multiple()) needs to be called.

Example

import cimplicity

my_point = cimplicity.Point()

my_point.id = 'PointAlarmLimits'

my_point.on_alarm_ack()
my_point.read_next(0)
my_point.read_next(-1)

alarm_ack = my_point.alarm_ack

my_point.cancel()
my_point.detach_ptmap()

my_point.attach_ptmap()
my_point.add_point()
x = my_point.get_value()
my_point.detach_ptmap()

def attach_ptmap()

Attaches the Point object to the ptmap instance in a thread. A Point object is only valid in 1 thread when it is attached to ptmap. After calling Point.detach_ptmap() a script can call Point.attach_ptmap() in another thread (or the same thread) to use the point again. It cannot be used in multiple threads at the same time while it is attached. Before a script exits all the Point objects must be detached from Ptmap using the detach_ptmap() method. A point object can also be used with the with statement to help ensure that the Point is detached from ptmap.

See also: Point.add_point(), point_add_multiple()

Example

import cimplicity

my_point = cimplicity.Point()

my_point.id = 'PointAlarmLimits'

my_point.on_alarm_ack()
my_point.read_next(0)
my_point.read_next(-1)

alarm_ack = my_point.alarm_ack

my_point.cancel()
my_point.detach_ptmap()

my_point.attach_ptmap()
my_point.add_point()
x = my_point.get_value()
my_point.detach_ptmap()

def cancel()

Cancels the currently active on_change, on_alarm, on_timed, or on_alarm_ack request.

Example

import cimplicity

with cimplicity.Point() as my_point:

    my_point.id = 'PointAlarmLimits'

    my_point.on_alarm_ack()
    my_point.read_next(0)
    my_point.read_next(-1)

    alarm_ack = my_point.alarm_ack

    my_point.cancel()
    my_point.on_change()

def detach_ptmap()

Detaches the Point object from the ptmap instance in a thread. A Point object is only valid in 1 thread when it is attached to ptmap. After calling Point.detach_ptmap() a script can call Point.attach_ptmap() in another thread (or the same thread) to use the point again. It cannot be used in multiple threads at the same time while it is attached. Before a script exits all the Point objects must be detached from Ptmap using the Point.detach_ptmap() method. A point object can also be used with the with statement to help ensure that the Point is detached from the ptmap API.

Example

import cimplicity

my_point = cimplicity.Point()

my_point.id = 'PointAlarmLimits'

my_point.on_alarm_ack()
my_point.read_next(0)
my_point.read_next(-1)

alarm_ack = my_point.alarm_ack

my_point.cancel()
my_point.detach_ptmap()

with my_point:
    my_point.set_value(0)

def enable_alarm(enable)

Enables or disables alarming on the point. Can be used to temporarily disable alarming on a point.

Parameters

enable: bool - set to True to enable alarming, set to False to disable.

Example

import cimplicity

with cimplicity.Point() as my_point:

    my_point.id = 'PointAlarmLimits'

    my_point.read()

    are_alarms_enabled = my_point.quality_alarms_enabled

    if are_alarms_enabled == True:
        my_point.enable_alarm(0)

def get_raw_value(index: int = 0) ‑> Any

Returns a snapshot of the point value from the Point Manager. The returned value is "as is", without engineering unit conversion.

This operation combines the read and raw_value property into a single command. If the point is unavailable (due to the device being down, remote server unavailable, etc.) an error will be generated if you attempt to access the value (since the value is unavailable.)

See the state property if you need to determine if the point is available or not.

Parameters

index: int - optional index for array points (defaults to 0)

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.get_raw_value()

def get_value(index: int = 0) ‑> Any

Returns a snapshot of the point value from the Point Manager.

This operation combines the read and value property into a single command. If the point is unavailable (due to the device being down, remote server unavailable, etc.) an error will be generated if you attempt to access the value (since the value is unavailable.)

See the state property if you need to determine if the point is available or not.

Parameters

index: int - optional index for array points (defaults to 0)

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.get_value()

def on_alarm(condition_1: OnAlarmState = OnAlarmState.NONE, condition_2: OnAlarmState = OnAlarmState.NONE, condition_3: OnAlarmState = OnAlarmState.NONE, condition_4: OnAlarmState = OnAlarmState.NONE)

Use this method to request this point object be updated when its alarm state changes.

If no parameters are specified, the value will be returned whenever the alarm state changes. The four optional parameters can be used to restrict which alarm conditions will be reported to the application.

Call Point.read_next() to obtain the next value of the point. Call Point.cancel() to cancel the request. The first read_next call will return immediately. Any subsequent read_next call will block until the point's value changes.

Only one of the on_change, on_alarm, on_timed, or on_alarm_ack requests may be active at a time.

Parameters

condition1..4: OnAlarmState - The type of condition(s) that triggers the point value request:
- ALARM: Send the value whenever the point changes into or out of an Alarm (High or Low) state.
- WARNING: Send the value whenever the point changes into or out of a Warning (High or Low) or Alarm (High or Low) state.
- ALARM_HIGH: Send the value whenever the point changes into or out of an Alarm High state.
- ALARM_LOW: Send the value whenever the point changes into or out of an Alarm Low state.
- WARNING_HIGH: Send the value whenever the point changes into or out of a Warning High or Alarm High state.
- WARNING_LOW: Send the value whenever the point changes into or out of a Warning Low or Alarm Low state.

Note: Due to a current limitation, selecting both ALARM_HIGH and WARNING_LOW , for example, will return the point for all alarm and warning states. In other words, the High and Low end up applying to both the Alarm and Warning.

Example

import cimplicity

with cimplicity.Point() as my_point:

    my_point.id = 'PointAlarmLimits'

    my_point.on_alarm()
    my_point.read_next(0)
    my_point.read_next(-1)

    x = my_point.state

def on_alarm_ack()

Use this method to request this point object be updated when the alarm acknowledgment state changes.

Only one of the on_change, on_alarm, on_timed, or on_alarm_ack requests may be active at a time.

Example

import cimplicity

with cimplicity.Point() as my_point:

    my_point.id = 'PointAlarmLimits'

    my_point.on_alarm_ack()
    my_point.read_next(0)
    my_point.read_next(-1)

    x = my_point.alarm_ack

def on_change()

Use this method to request the point's value on change.

Only one of the on_change, on_alarm, on_timed, or on_alarm_ack requests may be active at a time.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.set_value(10)
    my_point.on_change()
    my_point.read_next(0)

    x = my_point.get_value()

    my_point.read_next(-1)

    x1 = my_point.get_value()

    print("my_point Average Value: ", (x + x1)/2)

def on_timed(interval_secs: Union[int, datetime.timedelta])

Use this method to update this point object by polling periodically. A new value will be sent to the application every interval seconds.

Only one of the on_change, on_alarm, on_timed, or on_alarm_ack requests may be active at a time.

Parameters

interval_secs: int or timedelta- time interval in seconds to poll the point at.

Note : Unlike when using the on_change method, you may miss values of

the point if it changes in between your polls. Use the on_change method to receive the point whenever it changes. on_timed is useful if the point is rapidly changing and you are only interested in its value in a periodic manner.

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.set_value(10)
    my_point.on_timed(10) # seconds

    my_point.read_next(0)
    my_point.read_next(-1)

    x = my_point.get_value()

    print("my_point Value After 10 Seconds: ", x)

def read()

Reads (but does not return) the current CIMPLICITY point value. It will then be accessible as the value property.

See also: Point.get_value(), Point.value

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'
    my_point.read()
    x = my_point.value

def read_next(timeout_ms: Union[int, datetime.timedelta] = 0) ‑> bool

Reads the next value of a point with an optional timeout in milliseconds.

Use this after calling one of Point.on_alarm(), Point.on_alarm_ack(), Point.on_change(), or Point.on_timed() to wait for the specified condition.

Only one of the on_change, on_alarm, on_timed, or on_alarm_ack requests may be active at a time.

Parameters

timeout_ms: int or timedelta - time in milliseconds to wait before returning False if no new point value is available

Timeout values (milliseconds) can be also be -1 to wait indefinitely or 0 to return immediately even if there is no value ready.

Possible values for timeout_ms:

0: return immediately (even if there is no value ready)
-1: Wait indefinitely
Positive integer: Number of milliseconds to wait for a change

Returns

True if the point was read, False if the timeout expired

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    my_point.set_value(10)
    my_point.on_change()
    my_point.read_next(0)

    x = my_point.get_value()

    my_point.read_next(-1)

    x1 = my_point.get_value()

    print("my_point Average Value: ", (x + x1)/2)

def set_change_approval_info(**kwargs)

Sets the parameters for point operations requiring change approval.

Parameters

Pass all parameters as keyword arguments with the following keys:

performer_user_id: str - The id of the user on whose behalf the point operation is performed
performer_password: str - The password of this user
performer_comment: str - Performer comment to log with the operation
verifier_user_id: str - The id of the user on whose behalf the operation is verified (if required by change_approval_level)
verifier_password: str - The password of the verifying user
verifier_comment: str - Verifier comment to log with the operation

Example

import cimplicity

with cimplicity.Point() as my_point:

    my_point.id = 'PointINT'

    if my_point.change_approval_level == cimplicity.ChangeApprovalLevel.PERFORM_VERIFY:
        my_point.set_change_approval_info(performer_user_id='USER1', performer_password='MyPassword1!', performer_comment='Performed by USER1', verifier_user_id='VERIFIER1', verifier_password='MyPassword@2', verifier_comment='Verified by VERIFIER1')
    elif my_point.change_approval_level == cimplicity.ChangeApprovalLevel.PERFORM:
        my_point.set_change_approval_info(performer_user_id='USER1', performer_password='MyPassword1!')

    my_point.set_value(my_point.get_value() + 100)

def set_id_without_add(id: str)

Parameters

id: str - Represents the object's CIMPLICITY Point ID.

Sets the id of a point without adding it to ptmap. This usefull when used in conjunction with point_add_multiple(), or Point.add_point(), or when using the point in a with statement. When the with statement calls enter on the point it will call attach_ptmap, then within the with block Point.add_point or cimplicity.point_add_multiple needs to be called.

Example

import cimplicity

with cimplicity.Point() as point1, cimplicity.Point() as point2:
    points = [point1, point2]

    point1.set_id_without_add('PointWSTRING_20')
    point2.set_id_without_add('PointINT')

    all_added = cimplicity.point_add_multiple(1000, points)
    if all_added:
        point1.value = 'sampling complete'
        point2.value = 17
        cimplicity.point_set_multiple(points)
        cimplicity.point_read_multiple(points)

        assert point1.value == 'sampling complete', f'point {point1.id} has wrong value'
        assert point2.value == 17, f'point {point2.id} has wrong value'
    else:
        for point in points:
            if point.has_error:
                print("Point ", point.id, "had error :", point.error_msg)

def set_raw_value(new_value, index: int = 0, password: str = '')

Writes the given value into the CIMPLICITY point without engineering units conversion.

Parameters

new_value: Any
index: int - optional index for array points (defaults to 0)
password: str - optional "download" password that might be configured on the point for set operations

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    a = my_point.get_raw_value(0)
    b = a + 100

    my_point.set_raw_value(b, 0)

def set_value(new_value, index: int = 0, password: str = '')

Writes the given value into the CIMPLICITY point.

Parameters

new_value: Any
index: int - optional index for array points (defaults to 0)
password: str - optional "download" password that might be configured on the point for set operations

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'

    x = my_point.get_value()

    my_point.set_value(x + 100)

def write(element=-1, password='')

Writes the value property value into the actual CIMPLICITY point.

Parameters

element: int - optional index of the element to write
password: str - optional "download" password that might be configured on the point for set operations

Example

import cimplicity

with cimplicity.Point() as my_point:
    my_point.id = 'PointINT'
    my_point.read()
    my_point.value = my_point.value + 100
    my_point.write()

class PointDataType (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining the possible point data types.

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var ALARMLIM
var BITSTRING
var CHARACTERSTRING
var CHARACTERSTRINGW
var COR_BOOLEAN
var COR_I1
var COR_I2
var COR_I4
var COR_I8
var COR_U1
var COR_U2
var COR_U4
var COR_U8
var DYNAMIC
var FLOATINGPOINT
var OCTETSTRING
var STRUCTURE

class PointState (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining the state of the point.

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var ALARM
var ALARM_HIGH
var ALARM_HIGH_NOACK
var ALARM_HIGH_RESET
var ALARM_LOW
var ALARM_LOW_NOACK
var ALARM_LOW_RESET
var ALARM_NOACK
var ALARM_RESET
var AVAILABLE
var AVAILABLE_NOACK
var AVAILABLE_RESET
var MANUAL_MODE
var NORMAL
var NORMAL_NOACK
var NORMAL_RESET
var NOT_CONFIGURED
var OUT_OF_RANGE
var OUT_OF_RANGE_NOACK
var OUT_OF_RANGE_RESET
var UNAVAILABLE
var UNAVAILABLE_NOACK
var UNAVAILABLE_RESET
var UNAVAIL_INIT
var UNKNOWN
var WARNING
var WARNING_HIGH
var WARNING_HIGH_NOACK
var WARNING_HIGH_RESET
var WARNING_LOW
var WARNING_LOW_NOACK
var WARNING_LOW_RESET
var WARNING_NOACK
var WARNING_RESET

class QualityFlags (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum identifying the quality flags (bits) used in the 64-bit quality bitmask.

Ancestors

enum.IntFlag
builtins.int
enum.Flag
enum.Enum

Class variables

var ACK_OCCURRED
var ALARMED
var ALARMS_ENABLED
var DISABLE_WRITE
var IS_AVAILABLE
var IS_IN_RANGE
var IS_NOT_CONFIGURED
var LAST_UPD_MAN
var MANUAL_MODE
var STALE_DATA
var SYSBITS_DEVCOMM_ALARM

class ScriptStoppedError (*args, **kwargs)

This exception is raised when a script is stopped from BCEUI.

You should not catch this exception. If you do, you should re-raise it with a simple raise statement with no expression.

You should not raise this exception yourself.

Ancestors

Error
builtins.Exception
builtins.BaseException

class ShutdownReason (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining the types reasons do_shutdown can be called

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var PROCESS_SHUTDOWN
var SCRIPT_RELOAD

class StatusSeverity (value, names=None, *, module=None, qualname=None, type=None, start=1)

An enum defining the severity of the log message (or the COR_STATUS structure).

(SUCCESS - informational message, WARNING - warning message, FAILURE - failure message)

Ancestors

enum.IntEnum
builtins.int
enum.Enum

Class variables

var FAILURE
var SUCCESS
var WARNING