basic.substring.field.store Definition/BASIC Program

basic.substring.field.store

Command basic.substring.field.store Definition/BASIC Program
Applicable release versions: AP
Category BASIC Program (486)
Description change one or more fields or substrings within a character string variable which are delimited by a specific character.

"variable" is the string expression or variable.

"substring" is the substring or group of substrings (separated by a delimiter) to be substituted.

"delimiter" is the delimiter character separating fields or substrings in the original string.

"beg.fld.expression" is the starting field within the string for the substring to be placed.

"num.flds.expression" is the number of fields or substrings to be replaced in string.

The expression, "beg.fld.expression", determines the starting field to be changed by the operation. If "beg.fld.expression" is less than 1, 1 is assumed. If "beg.fld.expression" is greater than the number of fields within the string, the number of fields in the string is increased by adding null fields separated by the delimiter so that string has the length of "beg.fld.expression" fields.

Multiple substrings separated by the specified delimiter can be substituted in the original string.

The expression, "num.flds.expression", has different effects depending on whether it is positive, negative or zero:

If it is positive, then "num.flds.expression" fields in the string are replaced with "num.flds.expression" substrings. If "beg.fld.expression + num.flds.expression" is greater than the number of fields in string, the number of fields in the resulting string is increased to the value "beg.fld.expression + num.flds.expression", and the extra substrings are concatenated to the end of the original string. If "beg.fld.expression + num.flds.expression" is less than the number of fields in string but "num.flds.expression" is greater than the number of substrings specified, only the specified substrings are substituted and the remainder of the "num.flds.expression" fields in string are nulled. See example 1.

If "num.flds.expression" is zero, no fields in the string are deleted and the specified substring(s) are inserted into the string before the "beg.fld.expression"th field. See example 2.

If "num.flds.expression" is less than zero, "num.flds.expression" fields greater than or equal to "beg.fld.expression" are deleted from the string and the entire expression containing the substring(s) is inserted at that point in the string. See example 3.
Syntax variable[delimiter,beg.fld.expression, num.flds.expression] = substring
Options
Example
1) string = "a,b,c,d"
string[",",2,3] = "x,y,z"

This results in the string: "a,x,y,z"

string = "a,b,c,d"
string[",",4,2] = "x"

This results in the string: "a,b,c,x,"

string = "a,b,c,d"
string[",",2,2] = "x,y,z"

This results in the string: "a,x,y,d"

2) string = "a,b,c,d"
string[",",3,0] = "x,y"

This results in the string: "a,b,x,y,c,d"

3) string = "a,b,c,d"
string[",",3,-1] = "x,y"

This results in the string:  "a,b,x,y,d"

string = "a,b"
string[",",4,-5] = "x"

This results in the string: "a,b,,x"

string = "a,b,c,d"
string[",",2,-2] = ""

This results in the string: "a,,d"
Purpose
Related basic.substring.expressions
basic.casing
basic.substring.extraction
basic.assignment
basic.[
basic.substring.assignment
basic.field