Working with the Data Element List

Data Element List objects represent two important DICOM Data Structures attached to the image: DataSet Property and FileMetaInfo Property.

Working with an Element List includes two main steps: setting the "Current Index" of the Element List to a particular Data Element, and obtaining or modifying its data. This section lists various ways of setting the Current Index.

Due to the SQ Data Elements, Element List actually represents a tree. Navigation methods of the IGMedElemList Object allow to move the Current Index from element to element and up and down the nesting levels.

Internally, Element List is represented as a one-dimensional continuous array of Data Elements. The Current Index is the index in this array. It enumerates the whole Element List, disregarding the nesting levels. To obtain or change the current index, use CurrentIndex Property of the IGMedElemList Object.

It is important to note how the SQ Data Elements are structured. An SQ Data Element contains one or more "Sequence Items" (SQ Items), but no Data Elements. Each of the SQ Items, in turn, contains a set of Data Elements. Thus, the actual Data Elements can only be located at the even-numbered nesting levels.

Navigation properties and methods of the IGMedElemList Object are listed in the table below.

Navigation Method	API Reference
Move Current Index element by element	MoveFirst Method MoveLast Method MoveNext Method MovePrev Method
Move Current Index from level to level	MoveDown Method MoveUp Method
Move Current Index by searching for a particular Tag or Tag Group	MoveFind Method MoveFindFirst Method
Obtain or change current index	CurrentIndex Property
Obtain the level where Current Index is located	CurrentLevel Property

All of the navigation methods, except MoveDown Method and MoveUp Method, take the LevelOp parameter that tells what to do when the Current Index comes to a Level boundary: go up or down to the next level, or stay within the current level.

The following methods provide access to the Data Elements in the Element List:

Action	API Reference
Access the Current Data Element to retrieve information about it, obtain or change its data.	CurrentElem Property
Insert new Data Element	InsertElem Method
Remove a Data Element	RemoveCurrentElem Method

To insert a new Data Element to the ElementList, use the InsertElem Method, specifying the Tag, Value Representation, and Item Count for the new Element, and then populate the Element with data using the CurrentElem Property.

The following group of properties obtain information on the Element List:

Information Obtained	API Reference
Returns number of Elements in the list	ElemCount Property
Checks whether the Element List contains any Elements	IsEmpty Property
Returns maximum nesting level in the Element List	MaxLevel Property

Inserting a Sequence of Data Elements

Use the following steps to create and fill a sequence (SQ) of Data Elements:

Insert the Data Element of VR = SQ. This positions you one level lower in the DataSet hierarchy. At this level you can only add items to the sequence, not the Data Elements.
Insert the DCM_TAG_ItemItem Data Element to denote the beginning of a new item in the sequence. This positions you one level lower in the DataSet hierarchy. Now you can add Data Elements to the embedded Data Set.
Insert the data elements you would like to insert to this item.
Insert the DCM_TAG_ItemDeliminationItem Data Element to denote end of the item. This positions you one level higher. Repeat steps 2-4 for every item you would like to add.
Insert the DCM_TAG_SequenceDeliminationItem Data Element to denote the end of the sequence. This moves you one level higher - to the same level where you added the SQ Data Element.