STRGETB - Get Bytes Out of a String

Topic: DMD0306

Help File Version: 2.9.4.37

STRGETB - Get Bytes Out of a String

The Get Bytes Out of a String (STRGETB) instruction will extract bytes of data from the specified String and place them in the specified memory block. The primary use of this instruction - and its companion instruction Put Bytes Into a String (STRPUTB) - is in creating protocol drivers, where the data in the String is not ASCII text but consists of 16-bit, or 32-bit integers, or floating point numbers.

Note: this instruction is NOT intended to operate on data buffers containing ASCII text; working with data buffers that contain ASCII text is better handled through the STRCMP, STRFIND, STRSUB, STRDELETE, STRINSERT, STRCASE,STRCLEAR, STRTRIM, STRTRUNC instructions that are purpose-built to handle ASCII data.

Note: If the data in the String is an ASCII text representation of integer or floating point numbers, the correct instruction to use for handling that data is the Convert String to Integer (STR2INT) or Convert String to Real (STR2REAL) respectively.

Element References:

Note: Use the F9 key to open the Default Element Selection Tool (the Element Picker or the Element Browser) or use the Down-Arrow key (Auto-Complete) on any parameter field to see a complete list of the memory locations that are valid for that parameter of the instruction.

Get out of String - specifies the String which contains the bytes of data to copy. This can be any of the system-defined Short Strings, system-defined Long Strings, or any user-defined String.

Start at Index - specifies the first location in the String where to begin copying the bytes of data. This can be any readable numeric location or a constant value from 0 to the maximum number of characters in the String.

Note: if the Index value is greater than the number of bytes of data in the String, the following warning message will be generated:

"Attempted string operation was longer than target string and was truncated in STRGETB at <code-block>@<address>"

Length in Bytes - specifies the total number of bytes of data to copy from the String. This can be any readable numeric location or a constant value from 1 to the maximum number of bytes available in the String.

Note: if the Length in Bytes value is greater than the number of bytes of data in the String, the following warning message will be generated:

"Attempted string operation was longer than target string and was truncated in STRGETB at <code-block>@<address>"

Into Starting Element - specifies the beginning location of the memory block to place the bytes of data read from the String. This can be any writable numeric location.

Create Byte Buffer... - many communication protocols are constructed using Bytes of data, but the Do-more controller does NOT have a preconfigured block of Unsigned Bytes. If a Byte buffer is needed, clicking Create Byte Buffer will open the Create Unsigned Byte Buffer Block dialog where one can be created.

Data Block Name (1 to 16 letters) - Block names must be unique, and consist of 1 to 16 characters (A-Z, a-z; no numbers, no spaces). The default name STRGETBBuff can be changed if desired.

Number of Elements - specifies the number of bytes in the data block. The data blocks must be created on a DWord (4-byte) boundary. The maximum number of Bytes that can be received from a single packet is 1024.

Unsigned Byte Data Block Range - displays the first and last element of the block that will be created based on the current entries for Data Block Name and Number of Elements.

Data Type - the data block will consist of Unsigned Bytes.

Make Data Block Retentive (retain values after power loss) - a data block marked as retentive will hold its state through a power cycle or a Program-to-Run mode transition. The status of memory NOT marked as retentive will be cleared at power up and during a Program-to-Run mode transition.

Clicking OK will automatically select the newly created data block as the Into Starting Element location.

Status Display:

The Status display of the Get Bytes Out of a String instruction will only display as many of the characters of the Get out of String as will fit within the borders of the instruction, typically this is about 50 characters.