INS statement

Syntax

INS expression BEFORE dynamic.array < field# [ ,value# [ ,subvalue#] 
] >

Description

Use the INS statement to insert a new field, value, or subvalue into the specified dynamic.array.

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

dynamic.array is an expression that evaluates to the dynamic array to be modified.

field#, value#, and subvalue# specify the type and position of the new element to be inserted and are called delimiter expressions.

There are three possible outcomes of the INS statement, depending on the delimiter expressions specified.

Case 1:
If both value# and subvalue# are omitted or are 0, INS 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, INS 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, INS 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#.

If all delimiter expressions are 0, the original string is returned.

In IDEAL, PICK, PIOPEN, and REALITY 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, the dynamic array, field, or value is left unchanged. Additional delimiters are not appended. Use the EXTRA.DELIM option of the $OPTIONS statements to make the INS statement 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 the INS statement references a subordinate element of an element whose value is the null value, the dynamic array is unchanged.

If any delimiter expression is the null value, the INS statement 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 INS statement 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 #FFF1V2V3S6F9F5F7V3:

R=@FM:@FM:1:@VM:2:@VM:3:@SM:6:@FM:9:@FM:5:@FM:7:@VM:3
Q=R
INS "#" BEFORE Q<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=R
INS "#" BEFORE Q<3,3,0>

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

Q=R
INS "#" BEFORE Q<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=R
INS "#" BEFORE Q<3,2,2>
Parent topic: BASIC Statements and Functions