putlistitems

Copy data from a group of fields or variables into a list.

Example: putlistitems vItem, FLD1.ENT

Copying from Successive Occurrences

When items are copied into a list from a field or pair of fields in successive occurrences of an entity, the first item of the list is copied from the current occurrence of the entity in the component and remaining items from the following occurrences of the entity in the component. The hitlist is completed, if necessary.

Note:  To ensure that the entire set of occurrences in the component is being addressed, make the first occurrence the current occurrence.

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

Using /id to Build an Associative List from Fields

To copy the contents of one or two fields from successive occurrences into the items of an associative list, use putlistitems/id and at least one of IdField and ValueField. The fields named by IdField and ValueField are used to build a new list in AssociativeList.

• If both IdField and ValueField are specified, the contents of IdField, the values these fields in successive occurrences of the current entity are used to populate the ID and value parts of items in the associative list.

  For example, consider a case where there are three occurrences of entity ENT in a component. Field FLD1 in the three occurrences contains 'day1', 'day2', and 'day3', and FLD2 contains 'Mon', 'Tue', and 'Wed'. The following statements build a list that contains those IDs and values:

  setocc "ENT", 1
  putlistitems/id vList, FLD1, FLD2
  ;Result: vList is "day1=Mon;day2=Tue;day3=Wed"

• If IdField is omitted, only the values are copied. For example, if field FLD2 in three occurrences of entity ENT in a component contains 'Mon', 'Tue', and 'Wed', the following statements build a list that contains those values:

  setocc "ENT", 1
  putlistitems/id vList,, FLD2 
  ; Result: vList is "Mon;Tue;Wed"

  Note:  This is equivalent to:

  setocc "ENT", 1
  putlistitems vList, FLD2 
  ;Result: vList is "Mon;Tue;Wed"

• If ValueField is omitted, only the IDs are copied. For example, Field FLD1 in the three occurrences contains 'day1', 'day2', and 'day3':

  setocc "ENT", 1
  putlistitems/id vList, FLD1 
  ;Result: vList is "day1=;day2=;day3="

Updating the Value Part of Associative List Items

To update the value part of items in an associative list, you can use putlistitems/idAssociativeList with no further arguments. The value part of each item is updated from the source specified in the ID part of that item. The ID part of a list item can contain the name of a field, a component variable, a global variable, or a general variable. For example:

NAME = "Frodo"    ; field name
$CPT_TOT$ = 14    ; component variable
$$GLOB_TOT = 329  ; global variable
$1 = -8           ; general variable

vList = "NAME;$CPT_TOT$;$$GLOB_TOT;$1"
putlistitems/id vList 
;Result: vList is "NAME=Frodo;$LOC_TOT$=14;$$GLOB_TOT=329;$1=-8"

For each item in AssociativeList, if the field or variable named by the item ID cannot be found, the associated values remains unchanged.

The source is assumed to be a field if the ID part of a list item does not contain a dollar sign ($). If a name includes a dollar sign, it is treated as the variable type specified. However, if one of the source qualifier /field, /component, or /global is specified, names 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 = "Field"
$NAME$ = "Component"
$$NAME = "Global"
TOTAL = 987.65
$TOTAL$ = 123.45

; Initialize a list 
vList = "name;$total$"

; Update the value part of list items:
putlistitems/id vList 
;Result: vList is "NAME=Field;$TOTAL$=123.45"

; Another way to update the value part of list items
putlistitems/id/field vList 
;Result: vList is "NAME=Field;$TOTAL$=123.45"

; Update associative list items from component variables
putlistitems/id/component vList 
;Result: vList is "NAME=Component;$TOTAL$=123.45"

; Update associative list items from global variables
putlistitems/id/global vList 
;Result: vList is "NAME=Global;$TOTAL$=123.45"

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 source switches.

Because the list argument is evaluated at runtime, 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.

Using /occ to Build an Associative List

To build an associative list that contains the names and contents of all fields in the field list of Entity in the current component, use putlistitems/occ.

For example, if the component entity WEEK contains three fields (DAY1, DAY2, and DAY3), the name of the field is mapped to the ID part of item and field data is mapped to the value part of the list Item:

DAY1.WEEK = "Mon"
DAY2.WEEK = "Tue"
DAY3.WEEK = "Wed"
putlistitems/occ vList,"WEEK"
; Result: vList is "day1=Mon;day2=Tue;day3=Wed"

If the /modonly switch is also used, the values will only be loaded from a field if the field data has been modified (that is, if $fieldmod=1). Field IDs from fields that have not been modified are removed from the list.