STR_CUT, MID, SUBSTR

The STR_CUT, MID and SUBSTR functions copy characters of a string and lets you truncate the resulting string. Use these functions when you want to copy all or parts of strings. Define which character to begin copying from, and optionally define the number of characters you want to copy.

These script functions all serve a similar purpose, which is to copy a part of a string. Define the String that you want to copy the characters from, and which character in that string to begin copying from Start. Optionally specify the Length if you only want to copy a certain number of characters. If you do not specify a length, the function returns all characters until the end of the string.

Note: You can specify an absolute length that exceeds the number of characters that are available in the string. In this case, the functions return the defined characters with additional blanks that are appended. If necessary, you can truncate these blanks with the STR_RTRIM function.

The original string itself remains unchanged, as you store the new string in a variable.

Syntax

STR_CUT (String, Start[, Length])
MID (String, Start[, Length])
SUBSTR (String, Start[, Length])

Parameters

STR_CUT, MID, or SUBSTR
Copy the characters of a string

String
Alphanumeric string
Format: script literal or script variable

Start
Start position from which to start copying
Format: number without quotation marks or script variable
Important! With the introduction of UTF-8, this parameter refers to the character position and not the byte position. For example, a value of 7 specifies the 7th character, and not necessarily the 7th byte.

Length
(Optional) The number of characters that should be copied
Format: number without quotation marks or script variable
Important! With the introduction of UTF-8, this parameter refers to the number of characters and not the number of bytes. For example, a value of 10 specifies characters, but it can contain ten or more bytes.

Return code: The specified part of the string

Examples

The following script returns all characters starting with the fourth character until the end of the string. The result is system.

:SET &PARTOFSTRING# = SUBSTR("AE system", 4)

The following example returns two characters, starting with the third character of the string. The result is CD.

:SET &STRING# = MID("ABCDEFGH",3,2)

The following example returns all characters starting with the third character. The returned result is CDEFGH.

:SET &STRING# = SUBSTR("ABCDEFGH",3)

The following example sets a length that exceeds the number of characters that are available in the string. Therefore, the function appends blanks for the missing characters. The result is >>CDEFGH <<.

:SET &STRING# = STR_CUT("ABCDEFGH",3,10)

:PRINT ">>&STRING#<<"

The following script splits a user-defined term. The first three characters are assigned to the first script variable and the last character to the second script variable.

:READ &TABNAME#, "04", "Please specify table name xxxy"
:SET &TABPRE# = SUBSTR(&TABNAME#,1,3)
:SET &TABSUF# = SUBSTR(&TABNAME#,4,1)

Due to the UTF-8 changes as of v24, the common trick of splitting CRLF into its two constituent elements CR and LF, does not work anymore because CRLF is now perceived as one character:

:SET &CRLF# = UC_CRLF()

:SET &CR# = substr(&CR#,1,1)
:SET &LF# = substr(&LF#,2,1)

The above script leads to the following error message:

U00020305 Runtime error in object 'xxx', line '00003'. The start column for the sub-string statement ('002') is not within the string (length '0001').

Solution: To specify a single CR ("0D") or LF ("0A"), you can now use the new HEX_2_STRING script function:

:SET &CR# = HEX_2_STRING("0D")
:SET &LF# = HEX_2_STRING("0A")