getlistitems

Copy multiple items from a list into a field or variable.

Description

Use the getlistitems statement to copy data from an indexed list of values or an associative list of ID=value pairs. For more information, see Lists and Sublists.

Use getlistitems without qualifiers to copy the contents of items in an indexed list to a field in successive occurrences of its parent entity.

You can use getlistitems/id to copy:

• The ID and value parts of items in an associative list into the fields IdField and ValueField in successive occurrences of the current entity.
• The value of items in an associative list into the fields or variables that are identified by the associated ID of each item.

You can use getlistitems/occ to copy the value part of items in an associative list into the fields of the named Entity that are identified by the associated ID of each item.

Copying to Successive Occurrences

When items are copied from a list into a field or pair of fields in successive occurrences of an entity, the first list item is copied into the current occurrence and new occurrences are created for the subsequent items.

When copying data into successive occurrences, if one of the specified fields occurs in an Up entity, then the nearest outer Down entity is used to control the movement of data into occurrences. If both of the fields specified are Up entities, the nearest outer entity of the first field controls the movement.

Filling One Field in Successive Occurrences

To copy items from an indexed list to a single field in successive occurrences, use getlistitems with no switch. Each item is copied to the indicated field in successive occurrences of its entity. If an unqualified field name is used, the current entity is used. The entire item is copied to Field, even if the item is structured like an associative list item.

Filling One or Two Fields From Associative Lists

To copy list items into one or two fields in successive occurrences, use getlistitems with the /id switch and at least one of IdField and ValueField.

• If both IdField and ValueField are present, for each item in the associative list, the ID part of the item is copied to the field IdField and the value part is copied to the field ValueField in successive occurrences.
• If IdField is omitted, only the values are copied.
• If ValueField is omitted, only the IDs are copied.

Copying Values of List items Into Targets

To copy the value part of each item in an associative list into the target specified by the ID part of that item, use getlistitems/id , a List name, and no further arguments. The ID part of the item can contain the name of a field, a component variable, a global variable, or a general variable. For example:

vList = "NAME=Frodo;$LOC_TOT$=14;$$GLOB_TOT=329;$1=-8"
getlistitems/id vList

After these statements have been executed, the field NAME field contains Frodo, the component variable $LOC_TOT$ contains 14, the global variable $$GLOB_TOT contains 329 and the general variable $1 contains -8.

For each item, if the field or variable named by the item ID cannot be found, no action is taken.

The ID part of the list item is assumed to be a field name if it does not contain a dollar sign ($). If the ID part includes a dollar sign, it is treated as the variable type specified. However, if one of the target qualifiers /field, /component, or /global is specified, Item IDs that do not include a dollar sign are treated as the selected source type.

For example, a field NAME, a component variable $NAME$ and a global variable $$NAME are all available, as well as a field TOTAL and a component variable $TOTAL$:

NAME = ""
$NAME$ = ""
$$NAME = ""
TOTAL = 0
$TOTAL$ = 0

vList = "NAME=Frodo;$TOTAL$=123.45"
getlistitems/id vList     
;NAME is Frodo, $TOTAL$ Is 123.45, TOTAL Is 0

getlistitems/id/field $LIST$   
;NAME is Frodo, $TOTAL$ Is 123.45, TOTAL Is 0

getlistitems/id/component $LIST$ 
;$NAME$ is Frodo, $TOTAL$ Is 123.45, TOTAL Is 0

getlistitems/id/global $LIST$   
;$$NAME is Frodo, $TOTAL$ Is 123.45, TOTAL Is 0

Note:  Although it is usually good practice to include the dollar signs ($) that form part of the variable name in each list item's value, these must be omitted to take advantage of the power of the target switches.

Because the list argument is evaluated at run time, you should consider the following points when you create the component:

• The existence of the referenced objects (fields and variables) cannot be verified by the compiler
• Any referenced fields cannot be included in an Automatic field list

Be sure that all the fields that will be referenced are included in the entity's field list and that all the component and global variables are defined.

Filling Fields in an Entity

You can use getlistitems/occ to copy the value part of associative list items into the fields of the current occurrence of the specified Entity. The field name must match the ID part of the list items. If a field is not available in the component, the item is not copied. Specifying Entity makes it possible to identify the uniquely entity in case of duplicate field names.