Topic: DMD0170 STRPRINT - Print to String |
|
The Print to String (STRPRINT) instruction is used to put data into a String. The data can be any combination of PLC data elements, Sting Literals Zero or more characters enclosed in double quotes, as in "hello", and may include both simple escape sequences (such as \t for the tab character) and hexadecimal data (such as 0xAA)., the contents of existing Strings, and results from formatting functions which are used to modify the appearance of the data before it's added to the string.
Beginning with Do-more Designer version 2.8, the Print to String instruction editor will use a new table-style editor instead of the text-based editor used in the previous versions. The table-style editor works by building a series of commands with their required data parameters that will sequentially add content to the target string. Each table entry is built by a sub-dialog which makes it very easy to correctly use the script functions any their required parameters.
The original text-based editor can still be used by clicking the Switch to Text-Based Editor button at the bottom of the instruction editor. The text-based editor works by letting you enter the text data and script functions as a single entry. The text-based editor can be quicker for simple Print to String operations, or for those who don't need the assistance of the print script function's sub-dialog editors.
|
|
Parameters:Print to is the target String where the output of the instruction will be placed. This can be any writable user-defined String (max 1024 bytes), any system-defined Short String (SS0 - SS127, max 64 bytes), or any system-defined Long String (SL0 - SL63, max 256 bytes).
Append to String controls how any existing data in the target String will be handled.
Automatically insert space after each term will insert a space between the terms in the script when the instruction is stored in the Do-more CPU. This is very useful when the Text Field contains only a list of elements that would otherwise require a manually entered space character to separate the items.
For example, assume that D0 contains the value 1234, D1 contains 5678, and D2 contains 9012:
If the Print Script contains "D0 D1 D2" and the 'Automatically insert space' is checked the output string will be "1234 5678 9012".
If the Print Script contains "D0 D1 D2" and the 'Automatically insert space' is NOT checked the output string will be "123456789012".
The same result can be achieved by manually inserting space characters in the Text Field like this: D0 " " D1 " " D2
Print Script contains the PLC data, ASCII text, and script functions that will be processed to generate the output string. This can be any combination of PLC data elements, existing Strings, Sting Literals Zero or more characters enclosed in double quotes, as in "hello", and may include both simple escape sequences (such as \t for the tab character) and hexadecimal data (such as 0xAA). (which can be both printable and control character escape sequences), and results from the data formatting functions. If the resulting contents of the Print Script exceeds the maximum length of the destination string, the destination string will contain only the number of characters it can store (the remaining characters are lost) and a 'Buffer overflow' Warning will be generated.
When using the Table-style Editor, the buttons below the table provide functions for organizing the rows in the table: Add opens the row editor sub-dialog so that a new entry can be added to the end of the table. Insert inserts an empty row before the currently selected row / Edit opens the currently selected row in the row editor sub-dialog / Remove deletes the currently selected row. Move Up / Move Down moves the currently selected row up one row or down one row respectively.
Input Leg selects which of the following power-flow conditions will cause this instruction to run:
Click OK to save changes, click Cancel to abort changes, Script Help to open the String Scripting Language Reference or Switch to Text-Based Editor / Switch to Table Style Editor to select the style of editor to use for the Print Script section.
|
|
Using the Table-Style Editor:After selecting Add, Edit, or Insert the sub-command editor will open where one of the available sub-commands can be selected and it's required parameters can be entered. The various sub-commands and their parameters are described in the sections that follow.
Selecting Insert Structure Fields will open the following dialog that makes it easy to add most (or all) of the fields of a structure to the String when it's printed:
When the editing session is done, use the buttons at the bottom of the dialog as follows:
|
The following is a list of the available commands and their required parameters for constructing the text for the target String with the table-style editor: ElementThis function places data elements from the CPU memory into a string using the element's default display format. Any Bit (X0, Y0, C0, ...), numeric element (D0, R0, N0), constant value (3.14159, ...), or individual structure field (such as T0.Acc, MyPID.SP, MyProgram.RanThisScan, ...) can be specified.
String LiteralString literals are ASCII characters enclosed within a pair of double quotes.
String Literals can also use $-based escape sequences to insert control characters in the text. Each of the codes is preceded by the '$' character.
FmtInt - Format an Integer ValueThis function controls how integer numbers will appear in a String.
Value Element is the numeric value to format. This can be any readable numeric memory location or any constant value. If the value to format is NOT an integer, it will be converted to an integer then the modifiers will be applied. For example, if you specify a floating point (Real) location like R0, the value in R0 will be converted to an integer, then the modifiers will be applied.
Data Format selects how the value will appear in the String:
Optional Modifiers control how the value will be displayed:
FmtReal - Format a Real (Floating Point) ValueThis function controls how Real (floating point) numbers will appear in a String.
Real Element is the memory location that holds the Real (floating point) value to format. This can be any readable numeric memory location in the CPU. If the number to be formatted is NOT a Real number it will be promoted to a Real then the modifiers will be applied, for example, if you specify an integer (like D0), D0 will be converted to a Real, then the modifiers will be applied.
Field Width is the minimum number of digits to the left of the decimal point. This can be 1 to 255 digits. The value is not truncated even if the result is larger than the specified Field Width. If the value is shorter than the Field Width the result is padded with blank spaces.
Number of Significant Digits has different meanings based on the Format specified below:
Format
Justification controls the alignment of the digits within the Field Width specified above (typically used to align columns of numbers):
Commas specifies whether commas will be placed in the result:
FmtBit - Format a Bit ValueThis function controls how Bit values will appear in a String.
Bit Element is the memory location that holds the Bit value to format. This can be any readable Bit memory location.
Format selects the style of formatted text:
TimeStamp - Format a Date / Time StampGenerates a Time Stamp (both Time and Date )from the CPUs real-time clock's current value.
Resolution selects the level of detail for the Time:
Clock Time Type selects the formatted style of the text:
FmtDate - Format a DateThis function formats the date portion of a Date / Time structure.
Date / Time Struct or Numeric is a location that contains the date information to format. This can be any system-defined Date/Time structure (SDT0 - SDT7), any user-defined Date/Time structure (UDT0 - UDTx), the .Date field of any Date-Time structure, or any DWord location containing a value that has been sourced from the .Date field of a Date/Time structure.
Format selects the style of the formatted date:
FmtTime - Format the TimeThis function formats the time portion of a Date / Time structure.
Date / Time Struct or Numeric contains the time information to format. This can be any system-defined Date/Time structure (SDT0 - SDT7), any user-defined Date/Time structure (UDT0 - UDTx), the .Time field of any Date-Time structure, or any DWord location containing a value that has been sourced from the .time field of a Date/Time structure.
Format selects the style of the formatted time:
FmtString - Format a StringThis function adjusts the length of a string and sets the left / center / right justification of the text within a string.
String Element contains the text to justify. This can be any writable user-defined String (max 1024 bytes), any system-defined Short String (SS0 - SS127, max 64 bytes), or any system-defined Long String (SL0 - SL63, max 256 bytes).
String Width is the maximum number of characters in the target string to work with.
Justification selects the position of the String Element text within the Width:
FmtTimer - Format a Timer Accumulator ValueThis function controls how Timer Accumulator values will appear in a String.
Timer Struct or Numeric contains the Timer information to format. This can be any system-defined Timer structure (T0 - T255), any user-defined Timer structure, or any numeric memory location.
Size selects how to format the Hours and Minutes information:
Seconds Resolution selects the amount of information about the seconds to display:
Lookup - Select a String based on a ValueThis function selects 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.
0-based Index Element is the numeric memory location that contains the value that selects the String. This can be any readable numeric memory location.
Strings is the list of Strings that correspond to the 0-based Index values. The list of strings can contain String literals, any writable user-defined String (max 1024 bytes), any system-defined Short String (SS0 - SS127, max 64 bytes), or any system-defined Long String (SL0 - SL63, max 256 bytes).
The buttons below the table provide functions for organizing the rows in the table: Add opens the row editor sub-dialog so that a new entry can be added to the end of the table. Insert inserts an empty row before the currently selected row / Edit opens the currently selected row in the row editor sub-dialog / Remove deletes the currently selected row. Move Up / Move Down moves the currently selected row up one row or down one row respectively.
Raw - Copy Bytes from Numeric Memory to a StringThis function places bytes of data from numeric data blocks into a String. This is typically used when implementing a protocol driver that does not use ASCII characters for data.
Start Element is the numeric data block that contains the source bytes. This can be any can be any readable Byte, Word, or DWord numeric memory location. Start Element must resolve to the address of a Byte memory location, so you cannot specify a single Bit element, or a constant value. You can however use a BYTE Cast to send 8 consecutive bits, for example X0:B would send bits X0- X7.
Number of Bytes is the number of consecutive bytes to put into the String. This can be any constant from 1 to 1023.
The Swap options can change the order in which the bytes will be placed in the String:
Fill - Fill a String with a CharacterThis function places the same hexadecimal constant in the specified number of consecutive locations in a String.
Hexadecimal Constant is the constant Hex value (0x00 to 0xFF) to place in the String.
Fill Length is the number of consecutive copies of the specified Hex Constant to place in the String
|
|
Using the Text-Based Editor:When using the text-based editor, the Print Script is a single form that can contain any combination of PLC data elements (with or without data formatting functions), existing Strings, and Sting Literals Zero or more characters enclosed in double quotes, as in "hello", and may include both simple escape sequences (such as \t for the tab character) and hexadecimal data (such as 0xAA). (which can be both printable and control character escape sequences). For a complete description of the available data formatting functions for use in the Print Script, see the Help reference for the String Scripting Language.
If the resulting contents of the Print Script exceeds the maximum length of the target String (user-defined String (max 1024 bytes), system-defined Short String (SS0 - SS127, max 64 bytes), system-defined Long String (SL0 - SL63, max 256 bytes)), the target String will contain only the number of characters it can store - the remaining characters are lost - and a 'Buffer overflow' Warning will be generated.
|
|
Status Display:
The Status display will only show as many of the characters of the Print To that will fit within the borders of the instruction, typically this is about 50 characters.
The gray triangle at the right end of an input leg indicates the input is edge triggered, meaning that each time the input logic transitions from OFF to ON the instruction will run one time to completion.
|
|
See Also:
STR2REAL - Convert String to Real
STR2INT - Convert String to Integer
STRCASE - Convert String to UPPER / lower Case
STRCOPYR - Copy a Range of Strings
STRPRINT - Print to String
|
|
Related Topics:String Scripting Language Reference
PACKETOUT - Output Data to Packet Device
STREAMOUT - Stream Out Data to Device
MQTTPUB - IoT Publish MQTT Topics
HTTPCMD - Execute HTTP Command
|
|
Rung Example:
|
|