.\" @(#)PEXElementSearch.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXElementSearch 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXElementSearch \- Element Search
.SH SYNTAX
.HP
Status PEXElementSearch\^(\^Display *\fIdisplay\fP\^, PEXStructure \fIstructure\fP\^, int \fIwhence\fP\^, long \fIoffset\fP\^, int \fIdirection\fP\^, unsigned long \fIincl_count\fP\^, unsigned short *\fIincl_list\fP\^, unsigned long \fIexcl_count\fP\^, unsigned short *\fIexcl_list\fP\^, unsigned long *\fIelem_offset_return\fP\^)
.SH PARAMETERS
.TP 1i
\fIdisplay\fP
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.TP
\fIstructure\fP
The resource identifier of the structure.
.TP
\fIwhence\fP
A value specifying, with \fIoffset\fP, the offset at which the search is to
begin (
.B PEXBeginning,
.B PEXCurrent,
.B PEXEnd
).
.TP
\fIoffset\fP
The offset from \fIwhence\fP at which the search is to begin.
.TP
\fIdirection\fP
The direction of the search (
.B PEXForward
or
.B PEXBackward
).
.TP
\fIincl_count\fP
The number of values in inclusion array.
.TP
\fIincl_list\fP
An array of short integers specifying structure elements to be searched for.
.TP
\fIexcl_count\fP
The number of values in exclusion array.
.TP
\fIexcl_list\fP
An array of short integers specifying structure elements not to be searched for.
.TP
\fIelem_offset_return\fP
Returns the offset of the element located by the search.
.SH RETURNS
Zero if unsuccessful, non-zero otherwise.
The non-zero value will be either
.B PEXFound
or
.B PEXNotFound
depending upon the result of the search.
.SH DESCRIPTION
.\" indexing
.IX PEXElementSearch
.LP
This function searches for the first occurrence of the specified
element type in the specified
.I structure.
The search always includes the starting element.
.LP
If the computed
.I offset
is less than zero, it is set to zero before
the search is performed.  If the computed
.I offset
is greater than
the number of elements in the
.I structure,
it is set to the
.I offset
of the last structure element in the
.I structure.
.LP
An element is selected if its element type is contained in
inclusion list and is not contained in exclusion list.
An element type of
.B PEXOCAll
causes all element types to match.  If a structure element
type is in both the inclusion and exclusion list, it is excluded.
.LP
The search terminates if a match is found or if the limits of the
.I structure
are reached.  The search progresses from the start point
in the specified
.I direction (
.B PEXForward
or
.B 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
.B PEXFound
and the
.I offset
of the matching element is returned.
If the search is unsuccessful, a return status of
.B PEXNotFound
is returned.
.LP
The element pointer position of
.I structure
is not changed.
.SH DATA STRUCTURES
.LP
.nf
typedef  XID	PEXStructure;
.fi
.sp
.SH ERRORS
.TP
.SB BadPEXStructure
The specified structure resource identifier is invalid.
.TP
.SB BadValue
The specified value for
.I whence
or
.I direction
parameter is invalid.
.SH SEE ALSO
.LP
.nf
.BR PEXCreateStructure (3)
.fi