|
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 controller's
memory. This data can simply be the controller 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.
Controller Data Elements
Any data element in the controller can be sent to the selected device.
The controller 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.
Because structures such as Counters, Ramp/Soak Profiles, PID loops,
etc. have multiple fields, you must specify the structure name and the
desired "dot" field of the structure, for example, you must
specify CT0.Acc, MyPID.SP, or 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.ss).
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 |
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, e.g. "$N"
will be displayed as "$0D$0A"
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.
Strings 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
|
|
|
|
|
FmtString(SL0, 80, right) |
Right justified is the default.
|
|
|
FmtString(SL0, 80, left)
|
|
|
|
FmtString(SL0, 80, center) |
|
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
|
"The status of X7 is" FmtBit(X7, onoff)
will result in: "The Status of X7 is ON" |
|
|
truefalse will display
|
"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 [, <#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, dec, 4, left) will result
in: "The value of WX7 is 400 "
"The value of WX7 is" FmtInt(WX7, dec, 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
|
"The value of WX7 is" FmtInt(WX7, hex, 4, zeropad, prefix)
will result in: "The value of WX7 is 0x0400 " |
|
|
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 255
|
"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
|
|
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
FmtTMR(<tmr
element> | <numeric
element> [, smart |
full], [sec
| tenths | hundredths
| thousandths])
|
|
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
seconds resolution
sec
- display whole numbers of seconds tenths
- display tenths of seconds hundredths
- display hundredth of seconds thousandths
- 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 Date and Time stamps 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
- mm/dd/yyyy eu
- dd/mm/yyyy asia
- yyyy/mm/dd
|
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 24h
- HH:MM:SS
|
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. |
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 for when
the selector's value is 0, so the selector values should begin at 0. If
the selector value is negative, or if the selector value is greater than
the total number of strings in the list, the last string in the list is
selected.
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 read/write
numeric location
<any string> can be any
valid <string literal> or <string element>
|
Lookup(MyRampsoak.step, "initializing", "preheat",
"cook", "chill", "soak", "done")
Lookup( Y1, "Motor Off", "*Motor ON*") |
|
Send Raw Data
This function
allows for sending bytes of binary data to the specified device from numeric
data blocks. This is most useful when implementing a protocol driver that
does not use ASCII characters for data, for example DirectNET protocol.
|
Raw(<start element>,
<#bytes>)
|
|
|
|
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 to1023, or <read/write numeric location> |
Raw(V100, 128) sends the contents of V100 through V127 to the specified
device
|
<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. |
|