INS, INSERT()

The INS statement and INSERT() function insert a field, value or subvalue into a dynamic array. Used with a data collection, the INS statement inserts a name/value pair.

Format

INS string BEFORE dyn.array<field {, value {, subvalue}}>

INSERT(dyn.array, field, value, subvalue, string)

INSERT(dyn.array, field {, value {, subvalue}} ; string)

INS item AS collection{path}

where

string

is the string to be inserted.

dyn.array

is the dynamic array into which the item is to be inserted.

field

evaluates to the number of the field before which insertion is to occur.

value

evaluates to the number of the value before which insertion is to occur. If omitted or zero, value 1 is assumed.

subvalue

evaluates to the number of the subvalue before which insertion is to occur. If omitted or zero, subvalue 1 is assumed.

item	is a data item value to be inserted into a data collection.

collection

is a data collection variable.

path	is the element path to be used for the inserted item.

Dynamic Arrays

The string is inserted before the specified field, value or subvalue of the dynamic array. The INS statement assigns the result to the dyn.array variable. The INSERT() function returns the result without modifying dyn.array.

A negative value of field, value or subvalue causes the next item at this level to be appended. For example,

INS X BEFORE S<3, -1>

appends X as a new value at the end of field 3 of S. See the description of the S<f,v,sv> assignment operator for a discussion of how QM appends items.

Additional delimiters will be added to reach the specified field, value and subvalue unless the string to be inserted is null. Absent fields, values and subvalues are assumed to be null so there is no need to insert additional marks in this case.

Setting the COMPATIBLE.APPEND option of the $MODE compiler directive modifies the behaviour such that a mark character is not inserted if the final element of the portion of the dynamic array to which data is being appended is null.

Data Collections

The INS statement inserts the supplied item value into the named data collection at the specified element path. Note that when used in this way, the curly brackets surrounding the path are part of the syntax, not markers for optional items.

If the element path corresponds to an array element, the final component of the element path must be numeric and is the array index position at which the item is to be inserted. Any elements at or beyond this position are moved to make space. The index value must not be greater than one more than the existing number of elements in the array.

If the element path does not correspond to an array element, the new item is inserted. If the path already exists, the named collection element is replaced.

Examples

LOCATE PART.NO IN PARTS<1> BY "AL" SETTING I ELSE

INS PART.NO BEFORE PARTS<I>

END

This program fragment locates PART.NO in a sorted list PARTS and, if it is not already present, inserts it.

INS CLIENT.NAME AS CLIENT.DATA{'CONTACT.NAME'}

This statement inserts or updates the CONTACT.NAME element of the CLIENT.DATA collection.