SLANG Extensions

SLANG is a powerful and yet simple sequence language within Prodigy software that allows you to control and monitor the process via signal values. For the main article on SLANG click here.

Sometimes SLANG needs to perform functions that are beyond the scope of the language itself, such as manipulating Access™ databases or requesting input from the operator. In these cases SLANG will call on Extensions, which are purpose made routines that can perform quite complex operations.

In order to make selecting an extension easier, they are grouped into families, which is basically a common area of functionality, and the functions are listed by family below.

This list of extensions was comprehensive at the time of publishing this article. For an up to date list please contact us.

Alarms & Events.

AcceptAlarm
Accept an alarm that is specified via its unique identifier number.

AlarmFeedback
Enable/Disable the alarm feedback facility. Also passes the text to be displayed for the Alarm Feedback item on the Alarm Display context menu.

AlarmFullScreen
Turn alarm display full screen on/off.

AlarmScheduleSignal
Triggers the alarm scheduler to load a new set of alarm limits.

DisableAlarm
Disable a signal's alarm levels (each of the 4 levels can be manipulated).

DisplayEvent
Displays an event message in the Alarm Display.

DisplayEventDB
Displays an event message in the Alarm Display and records it into the specified batch in the specified database.

DisplayTimedEvent
Displays an event message in the Alarm Display. The message will remain there for the specified length of time.

DisplayTimedEventDB
Displays an event message in the Alarm Display and records it into the specified batch in the specified database. The message will remain there for the specified length of time.

EnableAlarm
Set, enable or disable a signal's alarm levels (each of the 4 levels can be manipulated).

GetAcceptedAlarms
Gets a list of all of the currently accepted alarms, with various associated properties, all of which are returned in a variety of arrays. The parameters are as follows:

• The number of currently accepted alarms
• An array containing the time that each alarm occurred
• An array containing each alarm's description
• An array containing each alarm's associated text
• An array containing each alarm's identity
• An array containing each alarm's signal tagname
• An array containing the time that each alarm was accepted

GetAlarmFeedback
Get an alarm feedback message from the alarm display. This occurs when an operator right clicks on an item in full screen mode. All relevant details about that alarm are sent back to Slang via this routine. The parameters are:

• Feedback obtained flag
• The signal that was selected
• The alarm text
• Is the alarm accepted
• Is the entry an event
• Has the alarm reverted
• The alarm identifier
• The alarm priority
• The alarm date/time
• The value that triggered the alarm

GetAlarmStatus
Gets the alarm status of a signal, including occurance time, revert time, accept time and so on.

GetUnacceptedAlarms
Gets a list of all of the currently unaccepted alarms, with various associated properties, all of which are returned in a variety of arrays. The parameters are as follows:

• The number of currently unaccepted alarms
• An array containing the time that each alarm occurred
• An array containing each alarm's description
• An array containing the state that each alarm is in
• An array containing each alarm's associated text
• An array containing each alarm's identity
• An array containing each alarm's signal tagname

Batch Handling.

ReadNumFromBatch
Reads a numeric value from a specified batch and database.

ReadStringFromBatch
Reads a string value from a specified batch and database.

WriteBatchEvent
Writes an event message into the alarms table of a specified batch.

WriteNumToBatch
Writes a numeric value into a specified batch and database.

WriteStringToBatch
Writes a string value into a specified batch and database.

Conversions

AsciiValue
Returns the ASCII value of the character that is passed in.

CharVal
Returns the character that matches the numeric value passed in, using the normal ASCII table.

RealToString2
Converts a real number into a string using the number of digits and decimal places specified.

RealToString
Superseded by RealToString2.

StrToNum
Converts a string into a real number, e.g. “1.25” into 1.25.

Database.

To work with databases is quite complicated and a good deal of confidence and knowledge is required. Basically SLANG works with handles to both databases and recordsets (the handle is a numeric identifier).

You open a database using DBOpen and it returns a numeric identifier to that database. You can have several databases open at once, each having a different identifier.

You open recordsets (groups of records within a database) by passing to DBOpenRecord the database handle and an SQL string to select the required records. This returns another handle, which is a numeric identifier of the recordset returned. Again, you can have more than one recordset open, each having its own unique identifier.

There might be several records in a recordset, or there might only be one, depending on the SQL used to select and depending on how many records are in the database to start with. You can move through all of the records in the recordset, delete records and add new ones.

You can read and write values to fields within any record in a given recordset.
It is very important to close databases when you are finished with them, and even more important to not repeatedly open the same database again and again without having closed it.

From a performance aspect it is good practice to avoid closing a database if it is to be reopened again soon (within a few seconds) as opening and closing are two of the most intensive database actions. Once a database is closed, do not try to use that numeric identifier in any record actions and do not try to use any recordset identifiers that derived from that database – all will produce dire errors.

A basic loop for database actions is:
• Open database.
• Open recordset.
• Go to first record.
• Perform actions on record.
• Go to next record.
• (repeat till end of recordset)
• Close database.

The list of extensions is:

BatchChooser2
As for BatchChooser (below) but with the additional parameter:

• Chooser Config
The path of a Batch Chooser Config file.

BatchChooser.
Allows you to select a batch from a given batch database. The user will have the option to browse to another location or another database. The parameters are:

• Database Path
The path of the database, including name if not using separate databases.
• Separate
Set to 1 if using separate databases.
• Selection Flag
• 0 = Must Exist
• 1 = Must Not Exist
• 2 = May Exist
• Selected
Set to 1 if the user made a selection.
• Batch Name
The name of the selected batch.
• Start Date
Start date of the batch.
• End Date
End date of the batch.
• Moved
Returns 1 if the user browsed to a new batch area.
• New Path
The new batch path that was browsed to.
• New Data Path
The new M data path (for tbmrr) that matches the batch path.

DBAddNew
Adds a new record to the given recordset. This must be followed by one or more calls to DBSetValuexxx (sufficient to fill all key fields of the record) and a call to DBUpdate.

DBClose
Closes a database. All recordsets within that database are also closed.

DBCopyFields
Copies up to three fields from one record to another.

DBCopyRecordset
Copies one entire recordset to another database (i.e. all fields from all records are copied).

DBDelete
Deletes the given record.

DBEdit
Must be called before new values can be written to an existing recordset. Should be followed by one or more DBSetValuexxx calls and finally a DBUpdate.

DBEmpty
Tells if the given recordset is empty (contains no records).

DBGetValue
Reads a value from the given record and returns not only the value but also the type of the value that is returned (numeric or string).

DBMove
Moves to a different record within the given recordset, using macros to determine where to move as follows:

• DBFIRST = Start of recordset (first record).
• DBLAST = End of recordset (last record).
• DBNEXT = Next record.
• DBPREV = Previous record.

DBOpen
Opens a database.

DBOpenRecord
Opens a recordset within the given database.

DBRecordCount
Returns the number of records in the given recordset.

DBSetValueNum
Sets a numeric value within the given record.

DBSetValueString
Sets a string value within the given record.

DBUpdate
Updates the given record (must follow a DBEdit or a DBAddNew and one or more DBSetValuexxx calls).

Debug.

ReportText
Displays a message in the Spy error log

ReportTextAndDouble
Displays a message followed by a number (the number is a double) in the Spy error log.

Dialogs.

AskForComment
Requests the user to enter a multi line string into a dialog box.

AskForNumber
Requests the user to input a number into a dialog box.

AskForString
Requests the user to input a string into a dialog box.

DecisionBox
Displays a dialog with a Title, Message and two labelled buttons.

DecisionBoxPic
Displays a dialog with a Title, Message, Picture (.jpg or .bmp) and two labelled buttons.

GetUnprivilegedUser
Simply gets a valid user id and password, unrelated to any privileges.

GetUserId
As below, but does not check if logged in user has privilege.

GetUserIdLogin
Checks to see if the current logged in user has the given privilege. If the current user doesn't have the privilege it displays a login dialog requesting a valid Id & password for the given privilege.

KillWindow
Specify the name of a window (as it appears in the window’s title bar) and the function will attempt to close the process that owns the window. The process will first be asked to close and if, after a specified time it hasn’t, it will be forcibly closed.

Message
Displays a simple dialog box containing a title, a message and an OK button.

MessageBox
Displays one of the standard Windows message boxes.
You can specify:

• The title of the box.
• The string that goes into the box.
• The button style.
• 0 = OK
• 1 = OK & Cancel
• 2 = Abort, Retry & Cancel
• 3 = Yes, No & Cancel
• 4 = Yes & No
• 5 = Retry & Cancel
• 6 = Cancel, Retry & Continue
• The icon that appears in the box.
• 0 = None
• 1 = Hand (Stop)
• 2 = Query
• 3 = Warning
• 4 = Information
• The return codes are:
• 1 = OK
• 2 = Cancel
• 3 = Abort
• 4 = Retry
• 5 = Ignore
• 6 =Yes
• 7 = No

MultipleChoice
Displays a dialog containing up to six labelled buttons and returns the number of the button that was clicked by the user.

YesNo
Displays a dialog box with two buttons, Yes and No and returns which one is pressed.

Down Time.

GetDownTimeReason
Gets a down time reason code's description.

GetDownTimeShortCode
Translates a down time reason short code into its constituent parts.

GetDownTimeStatus
Gets the current down time status from DTL2. The arguments are as follows:

• The DTL2 configuration slot number").
• The current down time status
• -999=No DTL2 response
• 0=No reason required
• 1=Override mode
• 2=Short stoppage
• 3=Previous reason required
• 4=Current reason required
• 5=Current reason entered
• The level 1 reason code
• The level 2 reason code
• The level 3 reason code
• The level 4 reason code
• The level 5 reason code
• The level 6 reason code
• The down time reason comment

GetLastDownTimeStatus
Gets a variety of information about the last down time event by reading the last down time record from the down time database.

SetDownTimeStatus
Sets the current down time status for DTL2.

Engineering Test.

BBDumpData
Send an instruction for the Black Box Recorder to dump its data from the rolling data module to the static module.

BBDumpToDatabase
Send an instruction for the Black Box Recorder to dump its data to an access database (named by time and date) in the Data/Black Box Recordings area.

BBLoggingRate
Instructs Black Box Recorder to change its logging rate.

ETLoggerComment
Sends a comment message to ETLogger.

ETLoggerRecord
Sends a record message to ETLogger.

ETLoggerStart
Sends a start message to ETLogger.

ETLoggerStop
Sends a stop message to ETLogger.

FastAvgValue
Gets current value, averaged over a number of readings from the fast data buffer.

FastIndex
Gets the current index from a named fast data buffer.

FastIndexedTime
Gets the current timestamp from an index in a named fast data buffer.

FastIndexedValue
Gets the current value from an index in a named fast data buffer.

FastReset
Send a reset request to the fast data driver to reset its index to -1. By then using FastIndex to check when this index is no longer 1 you can detect when a dump is completed.

FastValue
Gets the current value and timestamp from the fast data buffers.

TexcelClearQ
Send a clear demand queue message to the Froude Consine Texcel V4 Interface driver.

TexcelCrank
Send a crank message to the Froude Consine
Texcel V4 Interface driver.

TexcelDumpLoad
Send a dump load message to the Froude Consine Texcel V4 Interface driver.

TexcelGlowPlug
Send a glow plug control message to the Froude Consine Texcel V4 Interface driver.

TexcelHost
Send a switch to host control message to the Froude Consine Texcel V4 Interface driver.

TexcelIgnition
Send an ignition message to the Froude Consine Texcel V4 Interface driver.

TexcelImSetDemands1
Send an immediate set throttle and dynamometer demand message to the Froude Consine Texcel V4 Interface driver.

TexcelImSetDemands2
Send an immediate set throttle, dynamometer and inlet valve demand message to the Froude Consine Texcel V4 Interface driver.

TexcelImStop
Send an immediate stop message to the Froude Consine Texcel V4 Interface driver.

TexcelManual
Send a switch to manual control message to the Froude Consine Texcel V4 Interface driver.

TexcelResetStop
Send a reset stop message to the Froude Consine Texcel V4 Interface driver.

TexcelResetTime
Send a reset time message to the Froude Consine Texcel V4 Interface driver.

TexcelRestoreLoad
Send a restore load message to the Froude Consine Texcel V4 Interface driver.

TexcelSetDemands1
Send a set throttle and dynamometer demand message to the Froude Consine Texcel V4 Interface driver.

TexcelSetDemands2
Sends a set throttle, dynamometer and inlet valve demand message to the Froude Consine Texcel V4 Interface driver.

TexcelSetTrqUnits
Sends a “set torque units” message to the Froude Consine Texcel V4 Interface driver.

TexcelStop
Sends a stop message to the Froude Consine Texcel V4 Interface driver.

External Interaction.

EnableSMSUser
Enable/disable an individual SMS users, or enable/disable the SMS facility for all users.

GetDriverText2
Gets any available text from the ASCII Text to Serial Port driver. It reads a maximum of 100 characters and returns the characters that it has read along with a code indicating the read status, as follows:

• > 0 = the read was successful, the value is the number of characters read.
• 0 = the driver is still waiting for a response from the device.
• -1 = the driver has waited longer than its timeout period without receiving a reply.
• Anything else = there was an unspecified error.

GetDriverText
Superceded by GetDriverText2.

Logoff
Logs Default User in as the current user.

MimicSubs
Launches a Mimic with a dynamic tagname substitution after first requesting the substitution string.

RequestDriverText
Sends a request for text to the ASCII Text to Serial Port driver.

RunMimic2
Launches a DisplayBuilder or Mimic display with a variety of optional parameters.

RunMimic
Superceded by RunMimic2.

RunProgram
Runs an external program with an optional argument list and optionally waiting for program termination.

SendDriverText
Sends text to the ASCII Text to Serial Port driver.

SerialFlush
Sends a request to flush the comms to the ASCII Text to Serial Port driver.

SMSText
Sends the specified text as an SMS message to the specified phone number.

File Manipulation.

CopyFile
Copies a file from one path to another. The second path can be either just a path or it can be a path and file name. A parameter specifies whether or not to overwrite if the “to” file already exists.

CSVArray
As CSVStringArray, but returns an array of numbers rather than strings.

CSVStringArray
Finds a starting point (a row and column position) within a CSV file and then reads values into a string array from either a row or a column starting at that position. The top left position of the CSV file is 0,0.

CSVWrite
Not only writes but also opens and/or closes a CSV File. The action taken depends on the value of the first (Action) parameter. The parameters are:

• Action
• 0 = Close
• 1 = Open
• 2 = Write Real(s)
• 3 = Write String(s)
• 4 = Write New Line
• Handle
File handle. Returned by Action = 1 and used for every other operation.
• String(s)
String to be written (scalar or array), or path of file if Action = 1.
• Number(s)
Double to be written (scalar or array).
• Number Of Items
The number of items. 1 for a scalar, > 1 for array. 1 cannot be used with arrays.
• Separator
Separator to use between items (e.g. comma (,)).

DeleteFile
Deletes the specified file (full path must be given).

FileStats
Gets information about a file or number of files, including create and modify dates, file size, attributes and so on. Allows wildcarding and returns number of files that matched, including their names.

GetHistoricalData
Gets time/data pairs from TBMRR based on the dates and number of points requested. The parameters are:
• The signal name for which data is required
• The start date of the data required
• The end date of the data required
• The number of points required (use -1 for all)
• Look in remote location flag
• Path of the remote data
• Array of dates for the returned data
• Array of values for the returned data
• Array of validity for the returned data
• The number of points that have been returned

LookForFile
Give a path name and file specification (e.g. *.mdb) and if any files are found that match the given file specification the function returns the fully specified filename of the first such matching file.

MoveFile
Moves a file from one specified path to another and returns a value indicating the success of the move operation.

RecurseCopyFile
Recursively copies files and folders from one path to another. Allows wildcarding in the “from” file specification.

Mathematical.

Abs
Returns the value of a number (the positive value of the number, irrespective of its sign).

ArcCosine
Returns the arc cosine.

ArcSine
Returns the arc sine.

ArcTan
Returns the arc tangent.

BitwiseAnd
Applies a bitwise AND operation of the two parameters.

BitwiseLShift
Applies a bitwise left shift (by a specified number of bits).

BitwiseOnesComp
Returns a bitwise ones complement of the value.

BitwiseOr
Applies a bitwise OR operation of the two parameters.

BitwiseRShift
Applies a bitwise right shift (by a specified number of bits).

BitwiseXOr
Applies a bitwise Exclusive OR operation to the two parameters.

ChecksumType1
Returns a 2-character checksum equal to modulo 256 of all the ASCII values in the input string.

Cosine
Returns the cosine of an angle that is specified in degrees.

Fix
Rounds a number to the nearest integer.

LinearRegression
Calculates the least squares fit of a straight line using simple linear regression. The parameters are:

• An array containing the X values
• An array containing the Y values
• The array position to start at (0, 1 etc.)
• The number of values to use
• The returned linear regression value
• The returned x-coefficient or slope, m value
• The returned y-intercept, b value
• The returned coefficient of determination, r2 value
• The returned standard error of the estimate, SE value.

Log10
Returns the common logarithm of the given number.

Log
Returns the natural logarithm of the given number.

Mod
Splits a number into its whole and fractional parts and returns them as two values e.g. if 1.25 is the input 1 and .25 are the returns.

Polynomial
Evaluates a polynomial expression given X, an offset and the 1st, 2nd, 3rd, 4th, 5th and 6th order values.

Power
Raises a given number to a given power.

RandomNumber
Returns a random number in the range 0 to 32767.

Sine
Calculates the sine of a given angle (specified in degrees).

Sqroot
Calculates the square root of a number.

Tan
Calculates the tangent of a given angle (specified in degrees).

Signal Manipulation.

DisableSignal
Disable a signal whose name is passed in as a string.

EnableAllSignals
Enables all signals that were disabled and returns the number of signals that were successfully re enabled.

EnableSignal
Enable a signal whose name is passed in as a string.

GetCalibration
Reads the current calibration settings for a signal whose name is passed in as a string.

GetEventText
Gets the specified event text entry of a signal whose name is passed in as a string.

GetRange
Gets the normal range of a signal whose name is passed as a string.

GetSignalValue
Gets the value of a signal whose name is passed as a string.

GetSignalValueTime
Gets the signal value and timestamp of a signal.

PollSignal
Forces the driver to read a signal value now, even if it is not currently due according to its update rate.

ResetSignal
The specified signal will have its value set to 0 and in addition any software driver attached to the signal (such as a software counter) will be reset. If there is any hardware device attached to the driver controlling the signal (e.g. a hardware counter) an attempt will be made to reset the hardware device.

SetCalibration
Sets the calibration (scaling) factors for a given signal (signal name is passed in as a string).

SetEventText
Sets the specified event text entry for a signal (signal name is passed in as a string).

SetNagPeriod
Sets the alarm nag period for a signal (signal name is passed in as a string).

SetRange
Sets the high and low range for a signal (signal name is passed in as a string).

SetSignalDescription
Sets the description for a given signal (signal name is passed in as a string).

SetSignalValue
Sets the value of a given signal (signal name is given as a string). Its timestamp is assumed to be “now”.

SetSignalValueTime
Sets the value and timestamp of a signal.

SetUpdatePeriod
Sets the update period for a signal.

UpdateTime
Returns the last update time of a signal.

ValidSignal
Tests to see if a given string value is the name of a valid signal.

Specials.

GetPointsData
Gets a set of data points from a modbus device, stores them into an Access database and returns an array of values.

The data set is based on a signal that uses the base address of the modbus addresses to be read. The function reads from this base modbus address and from n contiguous address locations. The signals values are sent to the SignalManager with a specified interval between them, as well as being recorded to an Access database and being returned in an Array.

PLCErrorLookup
Reads an error message for a matching error code from a CSV file.

TM712Cm
Constructs a command string (including CRC) for a TM712 unit, given the various address parameters that may be specified. The command is sent to the unit by the serial text driver (see elsewhere).

String Manipulation.

Strlen
Returns the length of a string.

Strpos
Returns the position of a substring within a string.

Substring
Returns a substring of a given string.

System Functions.

AddAMessage
Sends a message code to a defined queue.
WARNING - this is a low level system function that should only be used by expert users.

ComputerName
Returns the name of the computer.

StartADriver
Starts the driver in the slot specified.

StopADriver
Stops the driver in the slot specified.

WriteComment
Writes a comment into the trend recordings. See the section on Comments elsewhere in this manual.

Time.

CombineTime
Takes individual date/time components (day, month, year, hour, minutes and seconds) and returns a single number representing that date/time.

DateString
Returns a given date (passed in as a double) as a string. As well as the date you pass in a formatting string, which can be any sensible date/time formatting string (e.g. DD MMM YY, DD/MM/YYYY hh:mm:ss etc.).

DayOfWeek
Returns the day of the week of a particular date, both as a numeric value (1 = Sunday) and as a string.

DST
Adjust a time to either Daylight Saving Time or Greenwich Mean Time. It does this by seeing if the date/time passed in falls within a daylight saving period. If it does it is adjusted either to DST or GMT according to the parameter. If it is not, then it is left unchanged regardless of the parameter.

TimeParts
Takes a date/time specifier (as a real) and returns it as year, month, day, hours, minutes, seconds.

TimePeriodParts
Takes a time period specifier (in seconds) and returns it in its constituent parts of days, hours, minutes and seconds.

TimeStringToSeconds
Converts a date/time string into a number of seconds since 01/01/1970. Allows manipulation of two such strings to find the elapsed time between them.