


XrmGetResource(3X11)					 XrmGetResource(3X11)
X11R5									X11R5



NAME
  XrmGetResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource -
  retrieve database resources and search lists

SYNTAX
  Bool XrmGetResource(_d_a_t_a_b_a_s_e,	_s_t_r__n_a_m_e, _s_t_r__c_l_a_s_s, _s_t_r__t_y_p_e__r_e_t_u_r_n,
  _v_a_l_u_e__r_e_t_u_r_n)
       XrmDatabase _d_a_t_a_b_a_s_e;
       char *_s_t_r__n_a_m_e;
       char *_s_t_r__c_l_a_s_s;
       char **_s_t_r__t_y_p_e__r_e_t_u_r_n;
       XrmValue	*_v_a_l_u_e__r_e_t_u_r_n;

  Bool XrmQGetResource(_d_a_t_a_b_a_s_e, _q_u_a_r_k__n_a_m_e, _q_u_a_r_k__c_l_a_s_s, _q_u_a_r_k__t_y_p_e__r_e_t_u_r_n,
  _v_a_l_u_e__r_e_t_u_r_n)
       XrmDatabase _d_a_t_a_b_a_s_e;
       XrmNameList _q_u_a_r_k__n_a_m_e;
       XrmClassList _q_u_a_r_k__c_l_a_s_s;
       XrmRepresentation *_q_u_a_r_k__t_y_p_e__r_e_t_u_r_n;
       XrmValue	*_v_a_l_u_e__r_e_t_u_r_n;

  typedef XrmHashTable *XrmSearchList;

  Bool XrmQGetSearchList(_d_a_t_a_b_a_s_e, _n_a_m_e_s, _c_l_a_s_s_e_s, _l_i_s_t__r_e_t_u_r_n,	_l_i_s_t__l_e_n_g_t_h)
       XrmDatabase _d_a_t_a_b_a_s_e;
       XrmNameList _n_a_m_e_s;
       XrmClassList _c_l_a_s_s_e_s;
       XrmSearchList _l_i_s_t__r_e_t_u_r_n;
       int _l_i_s_t__l_e_n_g_t_h;

  Bool XrmQGetSearchResource(_l_i_s_t, _n_a_m_e, _c_l_a_s_s,	_t_y_p_e__r_e_t_u_r_n, _v_a_l_u_e__r_e_t_u_r_n)
       XrmSearchList _l_i_s_t;
       XrmName _n_a_m_e;
       XrmClass	_c_l_a_s_s;
       XrmRepresentation *_t_y_p_e__r_e_t_u_r_n;
       XrmValue	*_v_a_l_u_e__r_e_t_u_r_n;

ARGUMENTS

  _c_l_a_s_s	    Specifies the resource class.

  _c_l_a_s_s_e_s   Specifies a	list of	resource classes.

  _d_a_t_a_b_a_s_e  Specifies the database that	is to be used.

  _l_i_s_t	    Specifies the search list returned by _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.

  _l_i_s_t__l_e_n_g_t_h
	    Specifies the number of entries (not the byte size)	allocated for
	    list_return.

  _l_i_s_t__r_e_t_u_r_n
	    Returns a search list for further use.

  _n_a_m_e	    Specifies the resource name.

  _n_a_m_e_s	    Specifies a	list of	resource names.

  _q_u_a_r_k__c_l_a_s_s
	    Specifies the fully	qualified class	of the value being retrieved
	    (as	a quark).

  _q_u_a_r_k__n_a_m_e
	    Specifies the fully	qualified name of the value being retrieved
	    (as	a quark).

  _q_u_a_r_k__t_y_p_e__r_e_t_u_r_n
	    Returns the	representation type of the destination (as a quark).

  _s_t_r__c_l_a_s_s Specifies the fully	qualified class	of the value being retrieved
	    (as	a string).

  _s_t_r__n_a_m_e  Specifies the fully	qualified name of the value being retrieved
	    (as	a string).

  _s_t_r__t_y_p_e__r_e_t_u_r_n
	    Returns the	representation type of the destination (as a string).

  _t_y_p_e__r_e_t_u_r_n
	    Returns data representation	type.

  _v_a_l_u_e__r_e_t_u_r_n
	    Returns the	value in the database.

DESCRIPTION
  The _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e functions retrieve a resource from
  the specified	database.  Both	take a fully qualified name/class pair,	a
  destination resource representation, and the address of a value
  (size/address	pair). The value and returned type point into database
  memory; therefore, you must not modify the data.

  The database only frees or overwrites	entries	on _X_r_m_P_u_t_R_e_s_o_u_r_c_e, _X_r_m_Q_P_u_-
  _t_R_e_s_o_u_r_c_e, or	_X_r_m_M_e_r_g_e_D_a_t_a_b_a_s_e_s.  A client that is not storing new values
  into the database or is not merging the database should be safe using	the
  address passed back at any time until	it exits.  If a	resource was found,
  both _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e return _T_r_u_e; otherwise, they return
  _F_a_l_s_e.

  The _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t	function 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
  _X_r_m_G_e_t_R_e_s_o_u_r_c_e for determining precedence.  If list_return was large enough
  for the search list, _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t returns _T_r_u_e; otherwise, it returns
  _F_a_l_s_e.

  The size of the search list that the caller must allocate is dependent upon
  the number of	levels and wildcards in	the resource specifiers	that are
  stored in the	database.  The worst case length is 3^n	where _n	is the number
  of name or class components in names or classes.

  When using _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t followed	by multiple probes for resources with
  a common name	and class prefix, only the common prefix should	be specified
  in the name and class	list to	_X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.

  The _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e function searches the specified database levels
  for the resource that	is fully identified by the specified name and class.
  The search stops with	the first match.  _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e	returns	_T_r_u_e
  if the resource was found; otherwise,	it returns _F_a_l_s_e.

  A call to _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t with a name and class list containing all	but
  the last component of	a resource name	followed by a call to _X_r_m_Q_G_e_t_S_e_a_r_-
  _c_h_R_e_s_o_u_r_c_e with the last component name and class returns the	same database
  entry	as _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e with the fully qualified name
  and class.

MATCHING RULES
  The algorithm	for determining	which resource database	entry matches a	given
  query	is the heart of	the resource manager.  All queries must	fully specify
  the name and class of	the desired resource (use of "*" and "?" are not per-
  mitted).  The	library	supports up to 100 components in a full	name or
  class.  Resources are	stored in the database with only partially specified
  names	and classes, using pattern matching constructs.	 An asterisk (*) is a
  loose	binding	and is used to represent any number of intervening com-
  ponents, including none.  A period (.) is a tight binding and	is used	to
  separate immediately adjacent	components.  A question	mark (?) is used to
  match	any single component name or class.  A database	entry cannot end in a
  loose	binding; the final component (which cannot be "?") must	be specified.
  The lookup algorithm searches	the database for the entry that	most closely
  matches (is most specific for) the full name and class being queried.	 When
  more than one	database entry matches the full	name and class,	precedence
  rules	are used to select just	one.

  The full name	and class are scanned from left	to right (from highest level
  in the hierarchy to lowest), one component at	a time.	 At each level,	the
  corresponding	component and/or binding of each matching entry	is deter-
  mined, and these matching components and bindings are	compared according to
  precedence rules.  Each of the rules is applied at each level, before	mov-
  ing to the next level, until a rule selects a	single entry over all others.
  The rules (in	order of precedence) are:

  11..   An entry	that contains a	matching component (whether name, class, or
       "?") takes precedence over entries that elide the level (that is,
       entries that match the level in a loose binding).

  22..   An entry	with a matching	name takes precedence over both	entries	with
       a matching class	and entries that match using "?".  An entry with a
       matching	class takes precedence over entries that match using "?".

  33..   An entry	preceded by a tight binding takes precedence over entries
       preceded	by a loose binding.

SEE ALSO
  XrmInitialize(3X11), XrmMergeDatabases(3X11),	XrmPutResource(3X11),
  XrmUniqueQuark(3X11)
  _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e

























