$MV

Builds or modifies a MultiValue dynamic array.

Synopsis

SET $MV(dynvar,fpos[,vpos])=value

Parameters

Argument	Description
dynvar	A variable used to hold the MultiValue dynamic array.
fpos	Field-level element. An integer that specifies where to insert the value as a field-level element in the dynvar dynamic array. A value of 0 appends value to the beginning of the dynamic array. A value of –1 appends value to the end of the dynamic array. A positive integer replaces the field-level element at that position with value.
vpos	Optional — Value-level element. An integer that specifies where to insert the value as a value-level element within the field specified in fpos in the dynvar dynamic array. A value of 0 appends value to the beginning of the fpos field. A value of –1 appends value to the end of the fpos field. A positive integer replaces the value-level element at that position in the fpos field with value.
spos	Optional — Subvalue-level element. An integer that specifies where to insert the value as a subvalue-level element within the value-level element specified in vpos in the dynvar dynamic array. A value of 0 appends value to the beginning of the vpos element. A value of –1 appends value to the end of the vpos element. A positive integer replaces the subvalue-level element at that position in the vpos with value.

Description

The $MV function creates or modifies a MultiValue dynamic array by inserting element values with the appropriate dynamic array delimiters: fpos inserts field mark (@FM) delimiters (CHAR(254)). vpos inserts value mark (@VM) delimiters (CHAR(253)). spos inserts subvalue mark (@SM) delimiters (CHAR(252)). $MV can add elements to the beginning or end, or replace an existing element value with a specified value.

By default, $MV inserts or appends elements, not delimiters. Therefore, it does not insert dynamic array delimiters without element values. To insert or append dynamic array delimiters, specify the positional parameter value as pos::1 and equate to an empty string. This is shown in the following example:

  SET $MV(dynval,-1)="apple"
  SET $MV(dynval,-1)="orange"
  WRITE dynval,!
  SET $MV(dynval,-1)="" // appends empty element
  WRITE dynval,!
  SET $MV(dynval,-1)="" // does nothing
  WRITE dynval,!
  SET $MV(dynval,-1::1)="" // appends 2nd delimiter
  WRITE dynval,!
  SET $MV(dynval,-1::1)=""  // appends 3rd delimiter
  WRITE dynval

Examples

The following example creates a dynamic array with three field elements:

  SET $MV(dynval,-1)="apple"
  SET $MV(dynval,-1)="orange"
  SET $MV(dynval,-1)="banana"
  WRITE dynval

The following example appends the element value “FRUIT” to the beginning of a three-element dynamic array, creating a dynamic array with four field elements:

  SET $MV(dynval,-1)="apple"
  SET $MV(dynval,-1)="orange"
  SET $MV(dynval,-1)="banana"
  SET $MV(dynval,0)="FRUIT"
  WRITE dynval

The following example replaces the value of the second dynamic array element (“orange”) with the value “nectarine”:

  SET $MV(dynval,-1)="apple"
  SET $MV(dynval,-1)="orange"
  SET $MV(dynval,-1)="banana"
  SET $MV(dynval,2)="nectarine"
  WRITE dynval

The following example creates a dynamic array with three field elements, appends an empty fourth element and deletes the second element value:

  SET $MV(dynval,-1)="apple"
  SET $MV(dynval,-1)="orange"
  SET $MV(dynval,-1)="banana"
  SET $MV(dynval,-1)=""
  SET $MV(dynval,2)=""
  WRITE dynval

The following example creates a dynamic array with three field elements, then adds two value-level elements within the first field element:

  SET $MV(dynval,-1)="apple"
  SET $MV(dynval,-1)="orange"
  SET $MV(dynval,-1)="banana"
  SET $MV(dynval,1,-1)="Braeburn"
  SET $MV(dynval,1,-1)="Macintosh"
  WRITE dynval

$MV

Synopsis

Parameters

Description

Examples

See Also