Name

PEXElementSearch - Element Search

Synopsis

Status PEXElementSearch(Display ∗display, PEXStructure structure, int whence, long offset, int direction, unsigned long incl_count, unsigned short ∗incl_list, unsigned long excl_count, unsigned short ∗excl_list, unsigned long ∗elem_offset_return)

Arguments

displayA pointer to a display structure returned by a successful XOpenDisplay call. 

structureThe resource identifier of the structure. 

whenceA value specifying, with offset, the offset at which the search is to begin (PEXBeginning, PEXCurrent, PEXEnd).

offsetThe offset from whence at which the search is to begin. 

directionThe direction of the search (PEXForward or PEXBackward).

incl_countThe number of values in inclusion array. 

incl_listAn array of short integers specifying structure elements to be searched for. 

excl_countThe number of values in exclusion array. 

excl_listAn array of short integers specifying structure elements not to be searched for. 

elem_offset_return
Returns the offset of the element located by the search.

Returns

Zero if unsuccessful, non-zero otherwise.  The non-zero value will be either PEXFound or PEXNotFound depending upon the result of the search.

Description

This function searches for the first occurrence of the specified element type in the specified structure.  The search always includes the starting element. 

If the computed offset is less than zero, it is set to zero before the search is performed.  If the computed offset is greater than the number of elements in the structure, it is set to the offset of the last structure element in the structure. 

An element is selected if its element type is contained in inclusion list and is not contained in exclusion list.  An element type of PEXOCAll causes all element types to match.  If a structure element type is in both the inclusion and exclusion list, it is excluded.

The search terminates if a match is found or if the limits of the structure are reached.  The search progresses from the start point in the specified direction (PEXForward or PEXBackward). This is a non-descending search; that is, the search does not include any structures referenced by "execute structure" elements.  If the search finds a match, a return status of PEXFound and the offset of the matching element is returned. If the search is unsuccessful, a return status of PEXNotFound is returned.

The element pointer position of structure is not changed. 

Data Structures

typedef XID             PEXStructure;

Errors

BadPEXStructure
The specified structure resource identifier is invalid.

BadValueThe specified value for whence or direction parameter is invalid. 

See Also

PEXCreateStructure