INS Statement

Inserts an attribute, value or subvalue into a dynamic array.

Note

The INS statement replaces the INSERT intrinsic function.

Syntax

INS char-string BEFORE dyn-array<attr# {,value# {,subval#}}>

char-string is a field of characters expressed as a variable name, a dynamic array reference, or a literal enclosed in quotes.

dyn-array is the dynamic array within which the expression is to be inserted.

attr# is the number of the attribute within dyn-array.

value# is the value number within the referenced attribute.

subval# is the subvalue number within the referenced value.

Dynamic array indices are evaluated as follows:

Nonnumeric expressions print a warning message and default to zero.
Noninteger expressions truncate the decimal value. For example, 1.7 and 1.2 become 1.
All trailing zero-valued positional expressions (except attr#) are ignored.
Any remaining zero-valued positional expressions are treated as ones.
If multiple negative positional values occur, the first occurrence remains negative and subsequent values are converted to 1.
The single remaining negative value creates a new position according to the following:
If the dynamic array is not null, the insertion value (preceded by a delimiter) is added as a new attribute, value or subvalue (depending on which position was negative) at the end of the existing item, attribute or value, respectively. The remaining positional values, if any, are treated as usual.
If the dynamic array is null, the negative value is converted to 1, and the following rule is applied.
If the positional expression specifies a nonexistent position (that is, a position greater than the number of attributes, values or subvalues below), or if the dynamic array is initially null, then nulls are created where necessary to put the insertion value in the position specified by the expressions.

INS 123 BEFORE ITEM<3>

Inserts attribute value 123 before the third attribute in dynamic array ITEM.

INS PRICE<3> BEFORE A<X,Y>

Inserts value of attribute 3 in array PRICE before the Y'th multivalue in the X'th attribute in dynamic array A.

INS YR*365 BEFORE ORDER<I,J,3>

Inserts value of YR*365 before the third subvalue in the specified multivalue and attribute.

IF PART<1,X+2> = 0 THEN 
    INS 1 BEFORE PART<1,X+2>
    END

If the multivalue is zero, then a new multivalue (1) is created before the indicated multivalue.

In the following examples:

N = ""
S = "1\2\3]11\22]333^A\B\C]AA"
X = "XXX"

INS X BEFORE S<0,2,0>

Result = 1\2\3]XXX]11\22]333^A\B\C]AA.

INS X BEFORE S<1,-2,-5>

Result = 1\2\3]11\22]333XXX^A\B\C]AA.

INS X BEFORE N<1,2,0>

Result = XXX.