hpux man page for xrmqgetseaa

XrmQGetSearchList()													       XrmQGetSearchList()

Name
  XrmQGetSearchList - return a list of database levels.

Synopsis
  Bool XrmQGetSearchList(database, names, classes,
	    list_return, list_length)
	  XrmDatabase database;
	  XrmNameList names;
	  XrmClassList classes;
	  XrmSearchList list_return;
	  int list_length;

Arguments
  database  Specifies the database to be searched.

  names     Specifies a list of resource names.

  classes   Specifies a list of resource classes.

  list_return
	    Returns  a	search	list  for  further use.  The caller must allocate sufficient space for the list before calling XrmQGetSearch-
	    List().

  list_length
	    Specifies the number of entries (not the byte size) allocated for list_return.

Returns
  True if list_return was large enough for the search list, else False.

Description
  XrmQGetSearchList() is a tool for searching the database more efficiently.  It is used in combination with XrmQGetSearchResource().  Often,
  one  searches  the  database for many similar resources which differ only in their final component (e.g., xmh.toc.foreground, xmh.toc.back-
  ground, etc).  Rather than looking for each resource in its entirety, XrmGetSearchList searches the database for the	common	part  of  the
  resource  name,  returning  a whole list of items in the database that match it.  This list is called the search list.  This search list is
  then used by XrmQGetSearchList(), which searches for the last components one at a time.   In this way, the common  work  of  searching  for
  similar resources is done only once, and the specific part of the search is done on the much shorter search list.

  XrmQGetSearchList()  takes  a list of names and classes and returns a list of database levels where a match might occur.  The returned list
  is in best-to-worst order and uses the same algorithm as XrmGetResource() for determining precedence.  If list_return was large enough  for
  the search list, XrmQGetSearchList() returns True.  Otherwise, it returns False.

  The size of the search list that must be allocated by the caller is dependent upon the number of levels and wildcards in the resource spec-
  ifiers that are stored in the database.  The worst case length is 3n , where n is the number of  name  or  class  components	in  names  or
  classes.

  Only the common prefix of a resource name should be specified in the name and class list to XrmQGetSearchList().  In the example above, the
  common prefix would be xmh.toc.  However, note that XrmQGetSearchResource() requires that name represent a single component  only.   There-
  fore, the common prefix must be all but the last component of the name and class.

  For more information, see Volume One, Chapter 13, Managing User Preferences.

Structures
  XrmDatabase is a pointer to an opaque data type.

     typedef XrmQuarkList XrmNameList;
     typedef XrmQuarkList XrmClassList;
     typedef XrmQuark	  XrmRepresentation;

  XrmSearchList is a pointer to an opaque data type.

See Also
  XrmDestroyDatabase(),  XrmGetFileDatabase(),	XrmGetResource(),  XrmGetStringDatabase(), XrmInitialize(), XrmMergeDatabases(), XrmParseCom-
  mand(), XrmPutFileDatabase(), XrmPutLineResource(), XrmPutResource(), XrmPutStringResource(),  XrmQGetResource(),  XrmQGetSearchResource(),
  XrmQPutResource(),  XrmQPutStringResource(), XrmQuarkToString(), XrmStringToBindingQuarkList(), XrmStringToQuarkList(), XrmStringToQuark(),
  XrmUniqueQuark().

Xlib - Resource Manager 												       XrmQGetSearchList()