INSERT function

Syntax

INSERT (dynamic.array, field#, value#, subvalue#, expression)
INSERT (dynamic.array, field# [ ,value# [ ,subvalue#] ] ; expression)

Description

Use the INSERT function to return a dynamic array that has a new field, value, or subvalue inserted into the specified dynamic array.

dynamic.array is an expression that evaluates to a dynamic array.

field#, value#, and subvalue# specify the type and position of the new element to be inserted and are called delimiter expressions. value# and subvalue# are optional, but if either is omitted, a semicolon ( ; ) must precede expression, as shown in the second syntax line.

expression specifies the value of the new element to be inserted.

There are three possible outcomes of the INSERT function, depending on the delimiter expressions specified.

Case 1:

If both value# and subvalue# are omitted or are 0, INSERT inserts a new field with the value of expression into the dynamic array.

• If field# is positive and less than or equal to the number of fields in dynamic.array, the value of expression followed by a field mark is inserted before the field specified by field#.
• If field# is -1, a field mark followed by the value of expression is appended to the last field in dynamic.array.
• If field# is positive and greater than the number of fields in dynamic.array, the proper number of field marks followed by the value of expression are appended so that the value of field# is the number of the new field.

Case 2:

If value# is nonzero and subvalue# is omitted or is 0, INSERT inserts a new value with the value of expression into the dynamic array.

• If value# is positive and less than or equal to the number of values in the field, the value of expression followed by a value mark is inserted before the value specified by value#.
• If value# is -1, a value mark followed by the value of expression is appended to the last value in the field.
• If value# is positive and greater than the number of values in the field, the proper number of value marks followed by the value of expression are appended to the last value in the specified field so that the number of the new value in the field is value#.

Case 3:

If field#, value#, and subvalue# are all specified, INSERT inserts a new subvalue with the value of expression into the dynamic array.

• If subvalue# is positive and less than or equal to the number of subvalues in the value, the value of expression following by a subvalue mark is inserted before the subvalue specified by subvalue#.
• If subvalue# is -1, a subvalue mark followed by expression is appended to the last subvalue in the value.
• If subvalue# is positive and greater than the number of subvalues in the value, the proper number of subvalue marks followed by the value of expression are appended to the last subvalue in the specified value so that the number of the new subvalue in the value is subvalue#.

In IDEAL, PICK, PIOPEN, and REALITY accounts, if expression is an empty string and the new element is appended to the end of the dynamic array, the end of a field, or the end of a value, the dynamic array, field, or value is left unchanged. Additional delimiters are not appended. Use the EXTRA.DELIM option of the $OPTIONS statement to make the INSERT function append a delimiter to the dynamic array, field, or value.

If expression evaluates to the null value, null is inserted into dynamic.array. If dynamic.array evaluates to the null value, it remains unchanged by the insertion. If any delimiter expression is the null value, the INSERT function fails and the program terminates with a run-time error message.

INFORMATION and IN2 Flavors

In INFORMATION and IN2 flavor accounts, if expression is an empty string and the new element is appended to the end of the dynamic array, the end of a field, or the end of a value, a delimiter is appended to the dynamic array, field, or value. Use the -EXTRA.DELIM option of the $OPTIONS statement to make the INSERT function work as it does in IDEAL, PICK, and REALITY flavor accounts.

Examples

In the following examples a field mark is shown by F, a value mark is shown by V, and a subvalue mark is shown by S.

The first example inserts the character # before the first field and sets Q to #FFF1V2V3S6F9F5F7V:

R=@FM:@FM:1:@VM:2:@VM:3:@SM:6:@FM:9:@FM:5:@FM:7:@VM:3
Q=INSERT(R,1,0,0,"#")

The next example inserts a # before the third value of field 3 and sets the value of Q to FF1V2V#V3S6F9F5F7V3:

Q=INSERT(R,3,3;"#")

The next example inserts a value mark followed by a # after the last value in the field and sets Q to FF1V2V3S6F9V#F5F7V3:

Q=INSERT(R,4,-1,0,"#")

The next example inserts a # before the second subvalue of the second value of field 3 and sets Q to FF1V2S#V3S6F9F5F7V3:

Q=INSERT(R,3,2,2;"#")