Read a list of structured elements from application program memory in the target system. This list can be used in expressions or out elements. The structured element is based on a data type that is defined with typedef. This typedef may contain temporary variables defined with var that are used for calculations (temporary variables are not read from the target system).
The individual data type elements of the <readlist> are referenced using name[index].member.
<readlist> manages two predefined member variables with the following names:
The attribute attribute symbol together with attribute offset specifies the start address in target memory of the list. When attribute attribute based:
<readlist> is able to read:
<readlist> can be used multiple times to add list items. The attribute init="1" clears the list and any list items collected on previous <readlist> calls is discarded.
Parent Element | Element Chain | ||
---|---|---|---|
object | /component_viewer/objects/object | ||
list | /component_viewer/objects/object/.../list | ||
Attributes | Description | Type | Use |
name | Name of the list variable for usage in Expressions. | xs:string | required |
type | A scalar data type or complex data type defined with typedef. | xs:string | required |
count | Number of list items to read from an array. Default value is 1. | xs:string | optional |
next | Name of a member element in the list that is used as next pointer. This is used to read a linked list. <readlist> stops reading on a NULL pointer. The maximum number of list items is limited to 1024. | xs:string | optional |
symbol | Symbol name used to calculate the memory address in the target system. | xs:string | optional |
offset | Offset to the memory address specified with attribute symbol address. If attribute symbol is not specified it is the memory address. Default value is 0. | xs:string | optional |
const | When const="1" the memory is read when the object is created the first time. Default value is 0. | xs:int | optional |
info | Descriptive text with additional information (comment). | xs:string | optional |
cond | Conditional execution: element is executed when expression result is not 0. Default value is 1. | xs:string | optional |
init | When init="1" previous read items in the list are discarded. Default value is 0. | xs:boolean | optional |
based | When based="1" the attribute symbol and attribute offset specifies a pointer (or pointer array). Default value is 0. | xs:boolean | optional |
Example
C source file:
The data type of the list is defined with typedef. The var element is a variable used to store a string.
Read the linked list starting with ValueA:
Read the linked list starting with head pointer ListStart:
Clear a previous list and read ValueA, ValueB, and ValueArray.
Read the list based on the pointers stored in pArray:
Read the pArray using read and read the list items addressed with pArray[1] and pArray[2].