Scripting Language Reference

Topic: DMD0168

Help File Version: 2.10.0.636

String Scripting Language Reference

The Do-more String Scripting language was designed to allow for maximum flexibility in generating ASCII text strings. The Text Field of the various String Output instructions will accept almost any combination of characters and data from the CPU's memory. This data can simply be the CPU data elements themselves, or formatted versions of the data using the formatting functions or casting operators.

What follows is a listing of the various types of data that can be entered into the Text Field of the Print to String (STRPRINT) and Send Email (EMAIL) instructions:

String Literals (double quoted text)

String literals are any printable ASCII characters enclosed within a pair of double quotes. These string literals will be sent to the selected output device exactly as entered.

"This string is being sent from an H2-DM1E CPU"

CPU Data Elements

Any data element in the CPU can be sent to the selected device. The CPU element's value will be sent using the elements default display format. The elements are separated by spaces, not commas. You can optionally use the data formatting functions to change how these data values will be displayed.

"The values of D0, R10, V27 & Y39 are" D0 R10 V27 Y39

Because structures such as Counters, Ramp/Soak Profiles, PID loops, etc. have multiple fields, you must specify the structure name and the desired field of the structure, for example, you must specify CT0.Acc, MyPID.SP, or MyRampSoak.Step.

"The current count of CT0 is" CT0.Acc "and the current step of Ramp/Soak Profile #0 is" MyRampSoak.Step

There is one notable exception and it is the Timer instruction. The Text Field will allow you to enter just the Timer name, for example, T0. The result will be the Timer's Accumulator value (the .Acc field) displayed in the TIME format (HH:MM:SS.mmm).

"The current value of T0 is" T0 " and the SetPoint of loop #5 is" MyPID.SP

Control Characters - ($-based escape sequence for control codes)

$-based escape sequences are used to insert control characters in the Text Field. Each of the codes is preceded by the '$' character. Refer to the '$-based' Code chart below for a complete list of the available control characters that can be entered in the Text Field.

$-based escape sequence	Resulting Text	Description
$$	$	dollar sign
$"	"	double quote
$L	<LF>	line feed
$N	<CR>< LF>	carriage return & line feed
$P	<FF>	form feed
$R	<CR>	carriage return
$T	<TAB>	tab
$hh	hh	any one-byte hex value

In the ladder display, the $-based control character sequences (except for $$ and $") will be converted to their $hh form. For example, the String below was created with $-based escape codes:

"The price of $"part$" #1 is $$" R0 "$T and $"part$" #2 is $$" R1 "$N"

It will be displayed as :

"The price of $"part$" #1 is $$"R0 "$09 and $"part$" #2 is $$" R1 "$0D0A"

Notice the $T was changed to $09, and $N was changed to $0D$0A, but $" and $$ remained as created.

Built-in or User-defined Strings

The Text Field can consist of any of the built-in Short Strings (SS data Block), or built-in Long Strings (SL data block), or any user defined Strings. There are also system-defined Strings named ERR, MSG, SysDesc, and SysName, and system-defined data blocks LastERR and LastMSG.

"The Strings SS0 and SL5 contain" SS0 SL5

Strings themselves can also be modified using the FmtString function to set the width and text justification. If the default value for any of the modifiers is entered through the editor, that default modifier will be removed as part of the validation routine. The order of the modifiers may also change, so don't be alarmed if the saved Text Field isn't exactly the same as what was entered through the editor.:

Set the Length and / or Text Justification of a String FmtString(<string element>, string width [, right \| left \| center])
Parameters	Example	Additional Notes
Required parameters: <string element> can be any string element string width can only be a constant value in the range of 0..1023 Optional Modifiers: text justification
right means all characters will be moved to the right-most end of the string and padded with leading spaces.	FmtString(SL0, 80, right)	Right justified is the default.
left means all characters will be moved to the left-most end of the string and padded with trailing spaces.	FmtString(SL0, 80, left)
center means all characters will be moved to the center of the string and padded with leading and trailing spaces.	FmtString(SL0, 80, center)

Fill a String with a Character

Fill(hexadecimal constant [, fill length)

Parameters

Example

Additional Notes

Required parameters:

hexadecimal constant can only be a hex constant value in the range of 0x00 ... 0xFF.

fill length is the number characters to write to the string.

"My dog has fleas" Fill(0x20, 5) "and so does mine."

BIT Formatting Function

The default display for a BIT element is a 0 if the BIT is OFF and an 1 if the BIT is ON. This function lets you specify a word which represents the status of the BIT instead of the values 0 or 1.

Format a BIT FmtBit(<bit element>, onoff \| truefalse \| val)
Parameters	Example	Additional Notes
Required parameters: <bit element> can be any readable BIT location	Assuming X7 is ON:
onoff will display: OFF if the value of the bit location is 0. ON if the value of the bit location is 1.	"The status of X7 is" FmtBit(X7, onoff) will result in: "The Status of X7 is ON"
truefalse will display: FALSE if the value of the bit location is 0. TRUE if the value of the bit location is 1.	"The status of X7 is" FmtBit(X7, truefalse) will result in: "The Status of X7 is TRUE"
val (default) will display the numeric value.	"The status of X7 is" FmtBit(X7, val) will result in: "The Status of X7 is 1"

Number Formatting Functions

These functions control how Integers and floating point (real) numbers will appear. If the default value for any of the modifiers is entered through the editor, that default modifier will be removed as part of the validation routine. The order of the modifiers may also change, so don't be alarmed if the saved Text Field isn't exactly the same as what was entered through the editor.

Note: If the number to be formatted is NOT the correct type for the formatting string, the number will be converted to the appropriate type then the modifiers will be applied, for example, if you use the FmtReal() function but specify a integer (like D0), D0 will be promoted to a Real value, then the modifiers will be applied.

Format an Integer Value FmtInt(<numeric element>, dec \| oct \| hex \| ipaddr [, <#digits> [, right \| left \| zeropad]] [, commas [, eu \| us]] [, prefix]))
Parameters	Example	Additional Notes
Required parameters: <numeric element> can be any readable numeric location.	Assuming WX7 has a value of 1024:
format dec will display the value in decimal format. oct will display the value in octal format. hex will display the value in hexadecimal format.	"The value of WX7 is" FmtInt(WX7, hex) will result in: "The value of WX7 is 400"
Optional Modifiers: #digits defines how many digits of the number to display, from 2 to 255. justification right will right justify the number and pad with leading spaces if needed. left will left justify the number and pad with trailing spaces if needed. zeropad will right justify the number and pad with leading zeros if needed.	"The value of WX7 is" FmtInt(WX7, hex, 4) will result in: "The value of WX7 is 400" "The value of WX7 is" FmtInt(WX7, hex, 4, left) will result in: "The value of WX7 is 400 " "The value of WX7 is" FmtInt(WX7, hex, 4, zeropad) will result in: "The value of WX7 is 0400 "	The complete value will be displayed if the number of digits specified is too small. The default is right justified.
commas specifies whether commas will be placed in the result. commas,us is the default and places commas between each three digits of a number commas,eu specifies the use of european style separators, meaning each three digits will be separated by a period	"The value of WX7 is" FmtInt(WX7, dec, 4, commas) will result in: "The value of WX7 is 1,024"	The default setting is commas,us.
prefix will add a format specific prefix to the value. 0x if the format is hexadecimal 0 if the format is octal no prefix if the format is decimal	"The value of WX7 is" FmtInt(WX7, hex, 4, zeropad, prefix) will result in: "The value of WX7 is 0x0400 "
ipaddr will format the DWord value in traditional TCP/IP Address format: that is, four numeric values between 0 and 255, separated by decimal points.	"The TCP/IP Address is" FmtInt(D0, ipaddr) will result in: "The TCP/IP Address is 192.168.0.45"	The numeric element must be a DWord. No other format options are allowed when ipaddr is used.

Format a Real (floating point) Value

FmtReal(<numeric element>, <width>, <precision> [, dec | exp | smart] [, commas] [, eu | us], [,right | left])

Parameters

Example

Additional Notes

Required parameters:

<numeric element> can be any readable numeric location

Assuming the value of is 86.24

width defines the minimum number of digits to display, not including the decimal point, from 1 to 255. The value is not truncated even if the result is larger than the specified width.

precision has different meanings based on the format, for smart format it defines the number of significant digits; for dec or exp format it defines the number of digits to the right of the decimal point.

The range of valid values is 0 to 254.

A value of 255 means "no precision".

"The value of R0 is" FmtReal(R0, 8, 4) will result in: "The value of R0 is 86.24"

If the value to be printed is shorter than this number, the result is padded with blank spaces.

If there are fewer digits in the number than are specified in precision, the number will be padded with zeros. If needed, the number will be rounded up to fit the precision.

Optional Modifiers:

format

dec will display the value as a full number without the use of exponential notation.
exp will display the value in exponential form.
smart will display whichever is shorter of dec or exp.

"The value of R0 is" FmtReal(R0, 8, 4, dec) will result in: "The value of R0 is 86.2400"

"The value of R0 is" FmtReal(R0, 8, 4, exp) will result in: "The value of R0 is 8.6240e+001"

The default format setting is smart.

commas specifies whether commas will be placed in the result.

commas,us places commas between each three digits of the whole number and a period to separate the whole number and the fraction, e.g. 1,000,000.00.
commas,eu specifies the use of European style separators, which places a period between each three digits of the whole number and a comma between the whole number and the fraction, e.g. 1.000.000,00.

The default setting is commas,us.

eu is valid for the decimal separator even if commas are not specified; FmtReal(R1, 4, 1, dec, eu, left).

justification

right will right justify the number and pad with leading spaces if needed.
left will left justify the number and pad with trailing spaces if needed.

The default setting is right justified.

Timer Accumulator Formatting Function

This function controls how Timer Accumulator values will appear. If the default value for any of the modifiers is entered through the editor, that default modifier will be removed as part of the validation routine. The order of the modifiers may also change, so don't be alarmed if the saved Text Field isn't exactly the same as what was entered through the editor.

Format a Timer Value

Parameters

Example

Additional Notes

Required parameters:

<tmr element> can be any Timer structure

Assuming T0.Acc has a value of 15m 43.385s

Optional Modifiers:

size

smart only displays significant hour and minute time values.
full always displays hour and minute values.

seconds resolution

sec will display whole numbers of seconds.
tenths will display tenths of seconds.
hundredths will display hundredths of seconds.
thousandths will display thousandths of seconds.

"The value of T0 is" FmtTmr(T0, full) will result in: "The value of T0 is 0h 15m 43.385s"

"The value of T0 is" FmtTmr(T0, sec) will result in: "The value of T0 is 15m 43s"

"The value of T0 is" FmtTmr(T0, hundredths) will result in: "The value of T0 is 15m 43.39s"

This allows for displaying any value as a time value.

Date and Time Formatting Functions

These functions control how Dates and Times will appear. If the default value for any of the modifiers is entered through the editor, that default modifier will be removed as part of the validation routine. The order of the modifiers may also change, so don't be alarmed if the saved Text Field isn't exactly the same as what was entered through the editor.

Format the Date

FmtDate(<date / time structure element> | <numeric element>, us | eu | asia)

Parameters

Example

Additional Notes

Required parameters:

<date / time structure element> Date / Time structure element

<numeric element> the .Date field of a Date / Time structure element.

Optional Modifiers:

format

us (m/d/yyyy) specifies month (1 - 12) / date (1 - 31) / 4 digit year (1970 - 2038).
eu (d/m/yyyy) specifies date (01 - 31) / month (01 - 12) / 4 digit year (1970 - 2038).
asia (yyyy/m/d) specifies 4 digit year (1970 - 2038) / month (01 - 12) / date (01 - 31).

FmtDate($now, us)

FmtDate($now.Date, us)

Assuming the current date is March 23, 2012:

"The value of $$now is" FmtDate($now, asia) will result in: "The value of $now is 2012/3/23"

for example: $now, SDT0, UDT5

When specifying a numeric element, the element must be the .Date field of a Date / Time structure element or a DWord sourced by the .Date field of a Date / Time structure.

Format the Time

FmtTime(<date / time structure element> | <numeric element>, 12h | 24h)

Parameters

Example

Additional Notes

Required parameters:

<date/time structure element> Date / Time structure element

<numeric element> the .Time field of a Date / Time structure element.

Optional Modifiers:

format

12h (HH:MM:SS AM/PM) (01-12 : 00-59 : 00-59 : AM or PM)
24h (HH:MM:SS) (01-12 : 00-59 : 00-59)

FmtTime($now, 24h)

FmtTime($now.Time, 12h)

Assuming the current time is 3:16 PM:

"The value of $$now is" FmtTime($now, 12h) will result in: "The value of $now is 3:16:00 PM"

for example: $now, SDT0, UDT5

When specifying a numeric element, the element must be the .Time field of a Date / Time structure element or a DWord sourced by the .Date field of a Date / Time structure.

Generate a Time Stamp

TimeStamp(<resolution>, <clock-time-type>)

Parameters

Example

Additional Notes

Required parameters:

min will not display seconds at all.
sec (default) will display whole numbers of seconds.
tenths will display tenths of seconds.
hundredths will display hundredths of seconds.
thousandths will display thousandths of seconds.

<clock-time-type>

local (default) will use $Localtime which has been adjusted for time zone and daylight saving mode.
utc will use UTC time with no adjustments.

Assuming the current Date / Time is October 3, 2016 / 3:15 PM

"The current Date / Time is" TimeStamp() will result in :

"The current Date / Time is 2016/10/3 15:15:04"

"This event occurred at " TimeStamp(thousandths,utc) will result in :

" This event occurred at 2016/10/3 19:15:04.524"

Display the local date / time to the whole number of seconds.

Display UTC date / time (GMT) to the thousandths of a second.

Select (Lookup) a String based on a Value

Will select the string at the position indicated by the selector's value from the given list of strings. The first string in the list is selected when the selector's value is 0. The last string in the list is selected if the selector value is negative, or if the selector value is greater than the total number of strings in the list. The list of strings can contain any valid string, that is, either string literals or other string elements.

Lookup(<numeric element>, <any string> [, <any string>])

If there are N strings listed in the Lookup function

if value = 0 then select string 0

else if value <= N-1 then select string ( value )

else select string N (i.e. default)

Parameters

Example

Additional Notes

Required parameters:

<numeric element> can be any readable numeric memory location

<any string> can be any valid <string literal> or <string element>

Lookup (MyRS.step, "initializing", "preheat", "cook", "chill", "soak", "done")

Lookup (Y1, "Motor Off", "*Motor ON*")

Copy Raw Data to a String

This function is used to place bytes of data from numeric data blocks in a String. A typical use of this is when implementing a protocol driver that does not use ASCII characters for data, for example DirectNET protocol.

Raw(<start element>, <#bytes>, swap)

Parameters

Example

Additional Notes

Required parameters:

<start element> can be any readable (<Byte element> or <Word element> or <DWord element>)

<#bytes> constant in range of 1 to 1023, or any readable numeric memory location.

<swap> can be either:

none means the Bytes will be placed into the String in the same order the appear in the memory block.
bytes means the Bytes in each Word will be swapped.
words means the Words in each DWord will be swapped.
both means the Bytes in each Word will be swapped and the Words in each DWord will be swapped.

Raw(V100, 128, none) places the contents of V100 through V163 in the specified string.

Raw(V100, 128, bytes) places the contents of V100 through V163 in the specified string with the bytes swapped.

Raw(V100, 128, both) places the contents of V100 through V163 in the specified string with the bytes and words swapped.

<start element> must resolve to the address of a Byte memory location, so you cannot specify a Bit element, and cannot specify a constant value. You can however use a BYTE Cast to send 8 consecutive bits, for example X0:B would send bits X0- X7.

String Scripting Language Reference

String Literals (double quoted text)

CPU Data Elements

Control Characters - ($-based escape sequence for control codes)

Built-in or User-defined Strings

BIT Formatting Function

Number Formatting Functions

Timer Accumulator Formatting Function

Date and Time Formatting Functions

Select (Lookup) a String based on a Value

Copy Raw Data to a String

See Also:

String Reference Topics:

Instructions for Strings containing ASCII data:

Instructions for Strings containing simple byte data:

Related Topics: