Topic: DMD0168
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 |
|
|
$$ |
$ |
dollar sign |
|
$" |
" |
double quote |
|
$L |
line feed |
|
|
$N |
<CR>< LF> |
carriage return & line feed |
|
$P |
<FF> |
form feed |
|
$R |
<CR> |
carriage return |
|
$T |
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.:
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.
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.
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.
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.
|
TimeStamp(<resolution>, <clock-time-type>)
|
||
|
Parameters |
Example |
Additional Notes |
|
Required parameters:
<resolution>
<clock-time-type> |
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.
See Also:
String Reference Topics:
Instructions for Strings containing ASCII data:
STREAMIN - Stream In Data from Device
STREAMOUT - Stream Out Data to Device
STR2INT - Convert String to Integer
STR2REAL - Convert String to Real
Instructions for Strings containing simple byte data:
STRGETB - Get Bytes Out of a String
STRPUTB - Put Bytes Into a String
PACKETIN - Input Data from Packet Device
PACKETOUT - Output Data to Packet Device
Related Topics:
Data View (ASCII, Quoted ASCII, or Hex/ASCII)