NAME    [Toc]    [Back]

       MrmOpenHierarchy  - Allocates a hierarchy ID and opens all
       the UID files in the hierarchy

SYNOPSIS    [Toc]    [Back]

       #include <Mrm/MrmPublic.h>

       Cardinal   MrmOpenHierarchy(num_files,    file_names_list,
       ancillary_structures_list, hierarchy_id)
               MrmCount num_files;
               String file_names_list[];
               MrmOsOpenParamPtr *ancillary_structures_list;
               MrmHierarchy *hierarchy_id;

DESCRIPTION    [Toc]    [Back]

       This routine is obsolete and exists for compatibility with
       previous releases.  It is replaced by MrmOpenHierarchyPerDisplay.
  MrmOpenHierarchy  is identical to MrmOpenHierarchyPerDisplay
 except that MrmOpenHierarchy does not take a
       display  argument.   Specifies  the number of files in the
       name list.  Specifies an array of character  strings  that
       identify the UID files.  A list of operating-system-dependent
 ancillary structures corresponding to such things  as
       filenames,  clobber  flag,  and  so  forth.  This argument
       should be NULL for most operations. If you need to  reference
  this  structure,  see  the  definition of MrmOsOpenParamPtr
 in <MrmPublic.h> for more  information.   Returns
       the  search  hierarchy ID. The search hierarchy ID identifies
 the list of UID files that MRM  searches  (in  order)
       when performing subsequent fetch calls.

       Each UID file string in file_names_list can specify either
       a full pathname or a filename. If a UID file string has  a
       leading  slash  (/), it specifies a full pathname, and MRM
       opens the file  as  specified.  Otherwise,  the  UID  file
       string  specifies  a  filename. In this case MRM looks for
       the file along a search  path  specified  by  the  UIDPATH
       environment  variable  or  by a default search path, which
       varies depending on whether or not the  XAPPLRESDIR  environment
 variable is set.

       The  UIDPATH  environment variable specifies a search path
       and naming conventions associated with UID files.  It  can
       contain  the  substitution  field  %U,  where the UID file
       string from the file_names_list argument to MrmOpenHierarchyPerDisplay
  is  substituted for %U. It can also contain
       the substitution fields accepted by XtResolvePathname. The
       substitution  field %T is always mapped to uid. The entire
       path is first searched with %S mapped to .uid and then, if
       no  file  is  found,  is  searched again with %S mapped to
       NULL.

       If no display is set prior to calling this  function,  the
       result  of  this  function's  call to XtResolvePathname is
       undefined.

       For example, the following UIDPATH value and  MrmOpenHierarchy
 call cause MRM to open two separate UID files:

       UIDPATH=/uidlib/%L/%U.uid:/uidlib/%U/%L
         static  char  *uid_files[]  = {"/usr/users/me/test.uid",
       "test2"};
         MrmHierarchy  *Hierarchy_id;
         MrmOpenHierarchy((MrmCount)2,uid_files,  NULL,   Hierarchy_id)


       MRM opens the first file, /usr/users/me/test.uid, as specified
 in the file_names_list argument to MrmOpenHierarchy,
       because  the  UID file string in the file_names_list argument
 specifies a full pathname. MRM looks for  the  second
       file,  test2,  first as /uidlib/%L/test2.uid and second as
       /uidlib/test2/%L, where the display's language  string  is
       substituted for %L.

       After MrmOpenHierarchy opens the UID hierarchy, you should
       not delete or modify the UID files until you close the UID
       hierarchy by calling MrmCloseHierarchy.

       If  UIDPATH  is  not set but the environment variable XAPPLRESDIR
 is set, MRM searches the following pathnames:
               %U%S
               $XAPPLRESDIR/%L/uid/%N/%U%S
               $XAPPLRESDIR/%l/uid/%N/%U%S
               $XAPPLRESDIR/uid/%N/%U%S
               $XAPPLRESDIR/%L/uid/%U%S
               $XAPPLRESDIR/%l/uid/%U%S
               $XAPPLRESDIR/uid/%U%S
               $HOME/uid/%U%S
               $HOME/%U%S
               /usr/lib/X11/%L/uid/%N/%U%S
               /usr/lib/X11/%l/uid/%N/%U%S
               /usr/lib/X11/uid/%N/%U%S
               /usr/lib/X11/%L/uid/%U%S
               /usr/lib/X11/%l/uid/%U%S
               /usr/lib/X11/uid/%U%S
               /usr/include/X11/uid/%U%S

       If neither UIDPATH nor XAPPLRESDIR is  set,  MRM  searches
       the following pathnames:
               %U%S
               $HOME/%L/uid/%N/%U%S
               $HOME/%l/uid/%N/%U%S
               $HOME/uid/%N/%U%S
               $HOME/%L/uid/%U%S
               $HOME/%l/uid/%U%S
               $HOME/uid/%U%S
               $HOME/%U%S
               /usr/lib/X11/%L/uid/%N/%U%S
               /usr/lib/X11/%l/uid/%N/%U%S
               /usr/lib/X11/uid/%N/%U%S
               /usr/lib/X11/%L/uid/%U%S
               /usr/lib/X11/%l/uid/%U%S
               /usr/lib/X11/uid/%U%S
               /usr/include/X11/uid/%U%S

       These  paths  are  defaults  that  vendors may change. For
       example,  a  vendor  may  use  different  directories  for
       /usr/lib/X11 and /usr/include/X11.

       The  following  substitutions are used in these paths: The
       UID file string, from the file_names_list  argument.   The
       class  name  of  the  application.  The display's language
       string.  The language component of the display's  language
       string.   The  suffix to the file name. The entire path is
       searched first with a suffix of .uil, and if  no  file  is
       found, it is searched again with a NULL suffix.

RETURN VALUES    [Toc]    [Back]

       This  function  returns  one  of  these status return constants:
 The  function  executed  successfully.   File  not
       found.  The function failed.

SEE ALSO    [Toc]    [Back]

       MrmOpenHierarchyPerDisplay(3X), MrmCloseHierarchy(3X)



                                             MrmOpenHierarchy(3X)