You can include labels in a segment to make locating particular elements of the segment easier. If you label an element that is likely to be edited, you can access that element when necessary, regardless of whether the actual position of the label-element pair within the segment has changed.
Warning: When editing segments, do not inadvertently insert elements between a label and the element that follows. Your application will no longer be able to use certain GPIs correctly because their default locations and offsets will be invalid.
A label is only a place-holder or reference point, and is itself an element of the segment. Labels are long integer values. To include a label in a segment, use GpiLabel. The following example includes the label 5 in the current segment, whose segment id is 4.
GpiOpenSegment(hps, 4L); GpiLabel(hps, 5L); . . .Your application can set the element pointer to the label position using GpiSetElementPointerAtLabel, then increment the pointer position to the element itself using GpiOffsetElementPointer with an offset of 1.
Note: This example of GPI cannot work properly if your application has allowed the insertion of elements between a label and the element that follows it.
Labels do not have to be unique. If you do not use unique labels, GpiSetElementPointerAtLabel positions the element pointer at the first occurrence of the label, starting from the current pointer position. If the label is not found between the current pointer position and the end of the segment, an error condition is raised. Using labels as a navigation aid might be quicker than scanning the segment for a particular element.
If you do not use labels, you must locate an element before you can change it. To locate a specific element in a segment, you must repeatedly move the element pointer using GpiSetElementPointer then read the contents of the element using GpiQueryElement. This can be quite a lengthy procedure depending upon the number of elements in the segment.