String Functions Overview

Topic: DMD0167

String Functions Overview

Within the Do-more controller's memory system the String data type provides the underlying storage mechanism for data that is received from communication ports, and data that is sent to communication ports. The data from these communication ports can be either bytes of ASCII text or simple bytes of numeric data. Both types of data from these communication ports gets stored in Strings.

String Lengths

Strings are predefined containers that are used to store bytes of data. Because of this, there are two length values associated with a String that you need to be concerned with when dealing with Strings, The first is the maximum length of the String, and the second is the number of bytes of data currently stored in that String.

The maximum length of the String is determined when the String is initially created and that length cannot be changed at runtime. This value determines the maximum number of bytes of data that the String can contain. (for more information on creating Strings, refer to the Memory Configuration Help topic. For example, the maximum length of the system-defined Short Strings is 64 bytes, and the maximum length of the system-defined Long Strings is 256 bytes. The maximum length of any String is available through the <stringname>.maxlen variable.

The number of bytes of data that a String can store at any time is 0 up to the value in the <stringname>.maxlen field of that String. The number of bytes that are currently stored in a String at any given time is available through the <stringname>.length variable.

Unlike a C/C++ string, Strings in a Do-more controller are NOT null-terminated, if a String needs a null terminator it will have to be manually added and accounted for in the .length value.

String Errors

If any String instruction attempts to store more data in a String than that String can hold, the instruction will store as many of the bytes of data in the String as it can hold, and generate a 'Buffer Overflow' warning which will be seen on the Do-more Designer status bar in yellow, and it will be logged in the System Information's Event Log.

String Literals

Many of the String instructions can process either Strings or string literals. String literals are 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 $AA).

Data View formats for Strings

When using the Data View to see the contents of Strings, there are four display options available to you. Which of the display options you use will largely depend on the type of data in String, that is, whether the data in the String is ASCII text or simple byte data or a combination of the two.

ASCII - This is the default display option for a String.

printable ASCII characters are displayed as expected
non-printable ASCII characters are displayed as a decimal point

Quoted

printable ASCII characters are displayed as expected
non-printable ASCII characters are displayed as "$" and the two-digit hex value

Hexadecimal

each byte of the String is displayed as a two-digit hexadecimal value
a space is displayed between each value and an extra space after each fourth value

Hexadecimal/ASCII bytes are displayed in groups of:

4 Hex/ASCII
8 Hex/ASCII
16 Hex/ASCII
24 Hex/ASCII
32 Hex/ASCII

4, 8, 16, 24 or 32 Columns of hexadecimal data with 4, 8, 16, 24 or 32 Columns of ASCII text respectively

String Instructions:

The instructions that operate on Strings are listed below. Notice the instructions are organized into five groups:

Instructions that modify ASCII text stored in a String whether generating, searching, extracting, or modifying the text

STRCASE - Convert String to UPPER / Lower Case - convert the characters in a String to all upper or lower case

STRCLEAR - Clear Strings - will remove the contents from the specified string or range of strings.

STRCMP - String Compare - compare two Strings, or compare one String with some ASCII text

STRDELETE - Delete Substring - delete characters from a String

STRINSERT - Insert Substring - insert characters into a String

STRPRINT - Print to String - send ASCII data to another String

STRSUB - Get Sub-String - extract the ASCII data from a portion of a String

STRTRIM - Trim Whitespace - remove leading and trailing whitespace characters from a String

STRTRUNC - Set String Length - set the length of a String to a fixed value

Instructions that compare the text stored in a String

STRCMP - String Compare - compare two Strings, or compare one String with some ASCII text

STRFIND - Find within String - search within a String for another String, or search within a String for some ASCII text

Instructions that convert text to their numeric equivalent values

STR2INT - Convert String to Integer - convert ASCII data to an integer

STR2REAL - Convert String to Real - send ASCII data to a Real (floating point) number

Instructions that operate on simple byte data stored in a String

STRGETB - Get Bytes Out of a String - copy bytes of data from a String to memory in the controller

STRPUTB - Put Bytes Into a String - copy bytes of data from controller memory to a String

CHECKSUM - Checksum Algorithm - compute a checksum on the bytes of data in a String

Instructions that send and receive String data from such as serial ports or a UDP packet on an Ethernet port

STREAMIN - Stream In Data from Device - retrieve data from the specified Stream Device and place that data in a String or a numeric data block

STREAMOUT - Stream Out Data to Device - send the data contained in a String or a numeric data block to the specified Stream Device

PACKETIN - Input Data from Packet Device - retrieve data from a Packet Device (UDP Connection) and place that data in a String or a numeric data block

PACKETOUT - Output Data to Packet Device - send the data contained in a String or a numeric data block to Packet Device (UDP Connection)