Application Calculation Engine (ACE) methods

AlarmDB (tableName, pointName, fieldName, "alarmCategory", "alarmMessage", persistentAlarmBool, flashingBool, OASySDNA.Common.

Severity, almPurgeTimeSecs)

Used when custom alarm generation is needed. It generates an alarm within the Alarm Summary.

Note: Using Fldput to write a value to the current value field within a table, for example analog curval, generates alarms when the current value moves into an alarm condition.

• tableName = is the name of the RealTime database (RTDB) table.

• analog. pointName = is an example of the name of the point.

• stnXinputPres2. fieldName = is an example of the name of field that is in alarm or "".

• alarmCategory = alarms are replaced within the same category.

  If there are several alarm messages, but only one should be visible in the Alarm Summary at a time, then give the Alarm database (AlarmDB) calls for those messages the same alarm category.

• string.alarmMessage = the alarm message.

• stringpersistentAlarmBool = a boolean that, when set to true, indicates that the alarm should remain in the Alarm Summary after it has been acknowledged.

• In this case, there should be a return to normal alarm generated later that has persistentAlarmBool set to false.

• flashingBool = a boolean that indicates that the alarm should flash within the Alarm Summary until the Controller acknowledges it.

• OASySDNACommon.Severity = an enumeration that sets the severity level of the alarm (for example, OASySDNA.Common.Severity.LOW).

• The severity enumerations include: HIGH, LOW, MEDIUM.

• almPurgeTimeSecs = a short (that is, a 16 bit integer) which defines the time in seconds that the alarm should remain in the Alarm Summary after acknowledgement when persistentAlarmBool is set to false.

AlarmDB (tableName, pointNum, fieldName, "alarmCategory", "alarmMessage", persistentAlarmBool, flashingBool, OASySDNA.Common.Severity)

Similar to AlarmDB above, but it accepts a point number (ptnum field value), rather than the point name.

AlarmAPP(string dbname, string ptname, string fldname, string description, string group, string category, string almMsg, persistentAlarmBool, flashingBool, OASySDNA.Common.Severity, short purgeTimer, string dataset, string priorityDisplay)

Used to generate alarms for changes without having to directly reference a database point. Instead of a point name, it accepts any given string for the dbname, ptname, or fldname.

AlarmSys ("Key", "alarmMessage", persistentAlarmBool, flashingBool, "alarmCategory", OASySDNA.Common.Severity, almPurgeTimeSecs)

Used to generate a system alarm. The parameters are similar to AlarmDB except for when you define a Key string that is used to differentiate the system alarms.

DNALog.WriteLog (DNALog.LogLevel, "LogMessage")

Used to write a message into the ACEEngine.log file within the log directory.

• DNALog.LogLevel = the log level enumeration to use (for example, DNALog.LogLevel.Always) where the supported enumeration values include: Always, DebugLog, Exit, Fatal, Warning, Info and Verbose.LogMessage = the message string.

  • Always - Always logged to both error log files.

  • DebugLog - Always logged to the application file log.

  • Exit - Exits the application, not recommended for the ACE.

  • Fatal - Exits the application, not recommended for ACE.

  • Warning - Only logged to application log file and only if debug level is toggled Always and DebugLog.

  • Info - only logged to application log file and only if debug level is toggled Warning.

  • Verbose - Only logged to application log file and only if debug level is toggled Info.

  • To always log to both the oasErrLog and the ACEEngine log, set: DNALog.WriteLog(DNALog.LogLevel.Always, logMessage).

  • To log only to the ACEEngine log, set: DNALog.WriteLog(DNALog.LogLevel.DebugLog, logMessage).

value = Fldget (tableName, pointName, fieldName)

Used to get a numeric value from a RTDB point.

• tableName = the name of the RTDB table (for example, "analog").

• pointName = the name of the point (for example, "stnXinputPres2").

• fieldName = name of field.

value = Fldget (tableName, pointNum, fieldName)

Similar to previous Fldget, but expects a numeric point number – the point’s ptnum field value, rather than a point name string.

value = FldgetString (tableName, pointName, fieldName)

Used to get a numeric value from a RTDB point.

• tableName = the name of the RTDB table (for example, "analog").

• pointName = the name of the point (for example, "stnXinputPres2").

• fieldName = name of field.

value = FldgetString (tableName, pointNum, fieldName)

Similar to previous FldgetString, but expects a text point number – the point’s ptnum field value, rather than a point name string.

Fldput (tableName,

pointName, fieldName, value)

Used to put a numeric value into the RTDB point.

• tableName = the name of the RTDB table (for example, "analog").

• pointName = the name of the point ("stnXinputPres2").

• fieldName = name of field.

Fldput (tableName, pointNum,

fieldName, value)

Similar to previous Fldput, but expects a numeric point number – the point’s ptnum field value, rather than a point name string. It is recommended to place a try-catch block around the method in order to trap exceptions that may occur during normal operations. (for example, Command failure due to remote offscan, writing new current value failed due to Controller placing the point into manual-override, or command failure due to the command inhibit tag.) If you do not use a try-catch block and an exception is thrown, then the code following the method will not get executed. If the exception is due to a temporary condition, then the ACE code (acecode) will execute again when the ACE Configuration (aceconfig) record execution is next triggered (see Types of execution). If the exception is not due to a temporary condition, then the aceconfig point is disabled, an alarm generated, and an event is logged.

FldputString (tableName, pointName, fieldName, value)

Used to put a numeric value into the RTDB point.

• tableName = the name of the RTDB table (for example, "analog").

• pointName = the name of the point (for example, "stnXinputPres2").

• fieldName = name of field.

FldputString (tableName, pointNum, fieldName, value)

Similar to previous FldputString, but expects a text point number – the point’s ptnum field value, rather than a point name string.

Fnput (tableName, pointName, "command")

Sends a command to a point.

• tableName = the name of the RTDB table (for example, "analog").

• pointName = the name of the point (for example, "stnXinputPres2.").

• command = the command string.

  It is recommended to place a try-catch block around the method in order to trap exceptions that may occur during normal operations. (for example, Command failure due to remote offscan, writing new current value failed due to Controller placing the point into manual-override, or command failure due to a command inhibit tag). If you do not use a try-catch block and an exception is thrown, then the code following the method will not get executed. If the exception is due to a temporary condition, then the acecode will execute again when the aceconfig record execution is next triggered (see Types of execution). If the exception is not due to a temporary condition, then the aceconfig point is disabled, an alarm generated, and an event is logged.

Fnput (tableName, pointNum,

"command")

Similar to previous Fnput, but expects a numeric point number – the point’s ptnum field value, rather than a point name string.

Fnput (tableName, args(<parameterNumber>).

PointNumber, "command")

Execute an fnput command using a parameter's point number. Input parameter numbers start at 1. The output point is referenced using a parameterNumber of 0.

value =GetEnumByName ("enumTypeName", "enumValueString")

Get the numeric representation for an enumeration description. This method is used to convert from a string description to an enumeration number.

• enumTypeName = the enumeration type name (for example, " hilowstate").

• enumValueString = the enumeration descriptions (for example, hi-hi, Dim, hiState as integer =).

• GetEnumByName (for example, "hilowstate","hi") if (input1 = hiState) Fnput("status",input2,"command stop")End If.

value = GetMultistateInputByName ("multistatePointName", "stateName")

Get the numeric input base message offset representation of a multistate point state. This method is used to convert from string to input base message offset, which is a double.

• multistatePointName = the point name in the multistate table.

• stateName = the multistate point’s state message text.

For example:

Open.Example:Dim closeVal As Double = GetMultistateInputByName("myMultistate", "CLOSE") Dim openVal As Double = GetMultistateInputByName("myMultistate","OPEN") If (input1 = closeVal) Then output = openValElse output = closeValEnd If

value = GetMultistateInputByName (multistatePtnum,"

stateName")

Similar to the previous GetMultistateInputByName method, but this method expects a multistate point number (the multistate ptnum field value) rather than a multistate name string.

value = GetMultistateOutputByName ("multistatePointName", "stateName")

Get the numeric output base message offset representation of a multistate point state. This method is used to convert from string to output base message offset, which is a double.

• multistatePointName = the point name in the multistate table.

• stateName = the multistate point’s state message text.

  For example:

  Open.Example:Dim closeVal As Double = GetMultistateOutputByName("myStatus", "CLOSE") Dim openVal As Double = GetMultistateOutputByName("myMultistate", "OPEN") If (input1 = closeVal) Then output = openValElse output = closeValEnd If

value = GetMultistateOutputByName (multistatePtnum,"

stateName")

Similar to the previous GetStatusByName method, but this method expects a status point number (the status ptnum field value) rather than a status name string.

value = GetStatusByName ("statusPointName", "stateName")

Get the numeric representation of a status point state. This method is used to convert from string to number.

• statusPointName = the point name in the status table.

• stateName = the status point’s state message text.

  For example:

  Open.Example:Dim closeVal As Double = GetStatusByName("myStatus", "CLOSE") Dim openVal As Double = GetStatusByName("myStatus","OPEN") If (input1 = closeVal) Then output = openValElse output = closeValEnd If

value = GetStatusByName (statusPtnum,"stateName")

Similar to the previous GetStatusByName method, but this method expects a status point number (the status ptnum field value) rather than a status name string.

IsOutputFresh = True

Used to directly set the output point's fresh state to the desired value. In this case, "True".

LastValues (<parameterNumber>)

The previous value of the specified parameter. 0 is used for the output point and 1-18 is used to specify the associated input parameters. LastValues is a property on the ACEProcedure class and can be used without specifying the class. "Current and last parameter values" under "Examples" shows an example.

Log ("LogMessage")

Logs the message string to the hot RealTime server's %DNADataRoot%\RealTime\log file.

value = Tnow ()

Get the current time in seconds in Coordinated Universal Time (UTC) (formerly Greenwich Mean Time (GMT)) starting at January 01, 1970.

value = UTCNowSeconds()

Get the current time in seconds UTC starting at January 01, 1970.

SetFreshFunctionToAND()

Used to control the ACE's calculation of the output point's fresh state. This function sets the ACE to use an AND function (the default), which sets the output point's fresh state to stale if any input database points are stale.

SetFreshFunctionToOR()

Used to control the ACE's calculation of the output point's fresh state. This function sets the ACE to use an OR function, which sets the output point's fresh state to fresh if any input database points are fresh.

value = args(<parameterNumber>).

Has Dataset

Parameter Property. True if the parameter has a dataset.

value = args(<parameterNumber>).

Has Flags

Parameter Property. True if the parameter has a flag structure.

value = args(<parameterNumber>).

IsFresh

Parameter Property. True if the parameter was fresh before execution.

value = args(<parameterNumber>).IsInError

Parameter Property. True if the parameter was in error before execution.

value = args(<parameterNumber>).

CurrentValue

Parameter Property. The current value of the input point.

value = args(<parameterNumber>).

IsConstant

Parameter Property. True if the parameter is a constant numeric value; false if it’s a database point.

value = args(<parameterNumber>).

DatabasePathString

Parameter Property. The path to the database point (for example, analog.ana1.curval).

value = args(<parameterNumber>).

Key Name

Parameter Property. The key name for the database point (that is, ana1).

value = args(<parameterNumber>).

PointNumber

Parameter Property. The database point number for this point.

WriteEvent (DNALog.EventType, "EventMessage.")

Writes a message to the Windows Event Log.

• DNALog.EventType = an enumeration which sets the event type.

  The event types include: Error, Info, Success, Warning (for example, DNALog.EventType.Error).

• EventMessage = the message string.

WriteEventSummary (tableName, pointName, "message")

Writes a message to the Historical Event Summary and the spool device associated with the point’s group.

• tableName = the name of the RTDB table (for example, "analog").

• pointName = the name of the point (for example, "stnXinputPres2").

• message = the event message.

WriteEventSummary (tableName, pointNum, "message")

Similar to previous WriteEventSummary but expects a numeric point number, that is to say the point’s ptnum field value, rather than a point name string.