###########################################################################
# TAU Browser Databse Manager Utilities
#
# This file will be included by other TAU tools needing to interface with
# the browser database.  It contains functions that (via the BDBM) 
# querry and modify the database.
#
# The functions described below are to be sourced into all TAU tools needing
# the depfile indexing services of the browser database.
# Each function in the BDBM interfacecommunicates with the Tau daemon, 
# which contains the BDBM, requesting information, which is returned via 
# RPC from the interface function.  The TAU daemon MUST be running for these
# functions to operate.
#
# This document refers to three types of source code files: 
#   1. A "program file" (abbreviated "progfile") contains primary source code, 
#      such as function definitions.  Examples of progfiles are 
#      ".c, .C, or .pc" files.  
#   2. A "header file" is a file that may be multiply included into progfiles,
#      usually containing function and type declarations.  Examples of header
#      files are .h files in C, C++, or pC++.  
#   3. A "depfile" is a representation of the abstract syntax tree for a
#      single progile and multiple included header files.  The depfile is
#      created by the compiler parser and read by TAU via a "CGM" program,
#      described in the document, "Interfacing to TAU".
# The functions in the BDBM interface usually take progfile names, rather
# than depfile names, as parameters.
# 
# In this document names surrounded by angle brackets, "<>", are 
# representations of parameters or return values.  The brackets are not 
# used in actual code. Items surrounded by square brackets, "[]", are 
# optional, and the brackets should not appear in actual code.  The "==>" 
# symbol is used to indicate the format of the return value which follows.
#  
# Any BDBM interface functions will return the string "BDBM_FAILED" if the
# operation failed.
#
# Kurt Windisch (kurtw@cs.uoregon.edu) - 5/24/96
###########################################################################


###########################################################################
#
# To use Browser Database Functions, the tool should source include
#    TAU/tools/inc/bdbm_utils.tcl
#
###########################################################################


###########################################################################
# Data Structures - these data structures are used internally by the 
# 		    browser database and are not to be accessed directly 
#                   by tools except the TAU daemon.
#
# BDB_projname -> string containing name of project
#
# BDB_host -> string containing the host computer name or "localhost"
#
# BDB_names(<progfile>,<name>) -> list of {<tag> <filen> <line>} for files
#                                 defining the function <name>.
#
# BDB_classes(<progfile>,<class>) -> list of {<tag> <filen> <line> for files
#                                    defining the class <class>.
#
# BDB_progfile_headers(<progfile>) -> list of header files included by
#                                     <progfile>
#
# BDB_progfiles_comptime(<progfile>) -> compile timestamp for <progfile>
#
# BDB_maintag -> {<depfilename> <tag>}
#
###########################################################################



###########################################################################
#
# Bdb_GetFuncs - Return a list containing all functions 
#                that are defined separately in a given progfile, or if
#                the progfile is unspecified, return a list of all functions
#                in the application.
#    Usage:
#      Bdb_GetFuncs [ <progfile> ]
#        ==> { {<func_name> <progfile> <tag>} ... }
#


###########################################################################
#
# Bdb_GetClasses - Return a list containing all classes (if C++ based language)
#                  that are defined separately in a given progfile, or if
#                  the progfile is unspecified, return a list of all classes
#                  in the application.
#    Usage:
#      Bdb_GetClasses [ <progfile> ]
#        ==> { {<classname> <progfile> <tag>} ... }
#


###########################################################################
#
# Bdb_GetHeaders - Return a list of the header files included by a given
#                  progfile, or if a progfile is not specified, return a 
#                  list of all header files in the application.
#    Usage:
#      Bdb_GetHeaders [ <progfile> ]
#        ==> { <header_name> ... }
#


###########################################################################
#
# Bdb_AddFile - Adds a specified progfile to the browser database (but does 
#               not build the index for it).  Header files are implicitly
#               added at compile-time.  The language is returned.
#    Usage:
#      Bdb_AddFile <progfile> 
#        ==> <language>


###########################################################################
#
# Bdb_RemoveFile - Removes a given progfile and any uniquely included 
#                  header files from the browser database.  Returns nothing.
#    Usage:
#      Bdb_RemoveFile <progfile>


###########################################################################
#
# Bdb_BuildIndex - Builds or update an index for a given progfile from the 
#                  compiled depfile.  This must be called anytime the depfile 
#                  for a progfile is updated.  Returns nothing.
#    Usage:
#      Bdb_BuildIndex <progfile>


###########################################################################
#
# Bdb_QueryFunc - Lookup a function name in the browser DB index and return
#                 a list of associated progfile, tag, line, definition file, 
#                 and function name lists, one per distinct instance in the 
#                 index.
#    Usage:
#      Bdb_QueryFunc <funcname> 
#        ==> { { <progfile> <tag> <linenum> <deffile> <funcname> } ... }


###########################################################################
#
# Bdb_QueryClass - Lookup a class name in the browser DB index and return
#                  a list of associated progfile, tag, line, definiton file,
#                  and class name lists, one per distinct instance in the 
#                  index.
#    Usage:
#      Bdb_QueryClass <classname>
#        ==> { { <progfile> <tag> <linenum> <deffile> <classname> } ... }


###########################################################################
#
# Bdb_QueryName - Lookup a name in the browser DB index and return
#                  a list of associated progfile, tag, line, and type lists,
#                  one per distinct instance in the index.  The name may
#                  refer to either a FUNC or CLASS and all matches on either
#                  will be returned.  Valid types are "FUNC" and "CLASS".
#    Usage:
#      Bdb_QueryName <name>
#        ==> { { <progfile> <tag> <linenum> <def-file> <name> <type> } ... }


###########################################################################
#
# Bdb_QueryFuncTag - Lookup a tag in a given progfile and returns
#                    a list of associated progfile, tag and line, and
#                    definition file.
#    Usage:
#      Bdb_QueryFuncTag <progfile> <tag>
#        ==> { <progfile> <tag> <linenum> <def-file> <funcname>}


###########################################################################
#
# Bdb_QueryClassTag - Lookup a tag in a given progfile and returns
#                    a list of associated progfile, tag and line, and
#                    definition file.
#    Usage:
#      Bdb_QueryClassTag <progfile> <tag>
#        ==> { <progfile> <tag> <linenum> <def-file> <classname>}


###########################################################################
#
# Bdb_GetMaintag - Returns the filename and tag associated with the 
#                  Main function of the applications, or 0 if a main
#                  function is not defined.
#    Usage:
#      Bdb_GetMaintag
#        ==> { <progfile> <tag> }


###########################################################################
#
# Bdb__Init - Initializes the browswer database for a specific project.
#            Bdb_DeInit must be used between sucessive calls to Init.
#    Usage:
#      Bdb__Init <project_name> <host> <project_directory> <progfile_list>
#
# No interface function is provided for Bdb__Init, since it is only called
# from within the daemon.


###########################################################################
#
# Bdb__DeInit - Uninitializes the browswer database for a specific project.
#    Usage:
#      Bdb_DeInit 
#
# No interface function is provided for Bdb__DeInit, since it is only called
# from within the daemon.


###########################################################################
#
# Bdb__LoadDB - Load the browswer database from the project-specific BDB file.
#              Returns nothing.
#    Usage:
#      Bdb__LoadDB 
#
# No interface function is provided for Bdb__LoadDB, since it is only called
# from within the daemon.


###########################################################################
#
# Bdb__SaveDB - Save the browswer database from the project-specific BDB file.
#               Returns nothing.
#    Usage:
#      Bdb__SaveDB 
#
# No interface function is provided for Bdb__SaveDB, since it is only called
# from within the daemon.

