/****************************************************************
 * File: srvlib.c 
 * Date: 02/15/91
 * Description:
 *   This file contains the entire application programming 
 *   interface for the srvlib. All communication with the
 *   database server (dbsrv) is accomplished using this 
 *   application programming interface. All function return
 *   -1 if an error occurred and 0 if successful.
 *
 * Revisions:
 * 01/12/91 (BDM): added srv_add_event_handler and srv_dispatch_event.
 *   These functions were added to allow different groups within
 *   a particular application to register event handlers 
 *   independently of each other and that these handlers would
 *   be called using srv_dispatch_event.
 * 01/17/91 (BDM): added the functions srv_host, srv_port, and
 *   srv_database. The function srv_init was modified to store
 *   the calling parameters into the connection record so that
 *   this info could later be retrieved via the functions added.
 * 01/22/91 (BDM): added error handling to the srvlib. The main
 *   function added was srv_error which routes error message to a
 *   logfile (default stderr). Several support functions were also
 *   added. The srv_error function is now used in all public
 *   functions so that wach may be traced. An environment variable
 *   SRVTRACE can be set to allow different levels of printing to
 *   the logfile. Those levels are:
 *     SRVTRACE = 3 - Fatal errors only will be logged (the default)
 *              = 2 - Errors and fatal errors will be logged.
 *              = 1 - Warnings, errors, and fatal errors will be logged.
 *              = 0 - Everything is logged
 * 02/15/91 (BDM): reworked the entire library so that the connection
 *   record is now dynamically allocated and returned as a pointer
 *   to a structure. As a result of this change, the calling 
 *   interface of all the functions was modified to handle the 
 *   new connection pointer. Also, checking for a NULL connection
 *   pointer was added (there was no checking in the previous version).
 *   Also, srv_validate_page was modified to return different flags
 *   (positive) to avoid conflict with the standard error return 
 *   flags. The standard return flag was adopted where the following
 *   is returned by most library functions unless otherwise specified:
 *      Error Flag =  0 - no error
 *                 = -1 - warning
 *                 = -2 - error
 *                 = -3 - fatal error
 * 02/21/91 (BDM): Add version numbers to srvlib.h for the library
 *   and added several functions for returning this information
 *   for use by application front-ends (log files, bug mail, etc.).
 ****************************************************************/
/****************************************************************
 *                     PRIVATE FUNCTIONS
 ****************************************************************/
/****************************************************************
 * Function: find_error_level 
 * Date: 01/18/91
 *
 * Description:
 *   Find the error level associated with a given error flag.
 * 
 * Linkage: int find_error_level(error_id)
 *   int err - error id
 *
 * Returns: return the error level or -1 otherwise
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: find_error_name 
 * Date: 01/18/91
 *
 * Description:
 *   Find the error name associated with a given error flag.
 * 
 * Linkage: char *find_error_name(error_id)
 *   int err - error id
 *
 * Returns: the error name or NULL if error id not found in table.
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_error  
 * Date: 01/18/91
 *
 * Description:
 *   Dispatch an error to the stderr file pointer. The function
 *   returns the error flag spcified when calling srv_error.
 * 
 * Linkage: int srv_error(sc,module,type,msg)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   char *module   - name of the function
 *   int type       - error flag or type of error
 *   char *msg      - error message
 * 
 * Returns: the error level assocated with the error flag:
 *    0 - no error
 *   -1 - warning
 *   -2 - error
 *   -3 - fatal error
 *
 * Revisions:
 * 2/13/91 (BDM) - now returns 0,-1,-2,-3 for each error level
 ****************************************************************/
/****************************************************************
 * Function: add_event
 * Date: 01/17/91
 *
 * Description:
 *   This function reads information related to a specific event
 *   from the socket, fills in the SrvEvent structure appropriately,
 *   and adds this event to the event queue.
 * 
 * Linkage: int add_event(sc,type)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int type       - type of event
 *
 * Returns: srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: wait_for_reply
 * Date: 01/03/91
 *
 * Description:
 *   Waits for the server to reply back to a command.
 * 
 * Linkage: int wait_for_reply(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 *                     PUBLIC FUNCTIONS
 ****************************************************************/
/****************************************************************
 * ==> Library initialization and termination functions 
 ****************************************************************/
/****************************************************************
 * Function: srv_init
 * Date: 01/03/91
 *
 * Description:
 *   Initialize the srvlib and establish connection with dbsrv.
 *   This function all performs protocol version checking with
 *   dbsrv and will abort if there is a protocol mismatch error.
 *   This function returns the server id flag which is a required
 *   argument for all other srvlib functions.
 *
 * Notes:
 *   (1) This function does not call srv_error since this function
 *   is establishing the connection which srv_error depends. Instead,
 *   stderr is used to send all error messages that occurr during
 *   the execution of this function. If any error does occur, a
 *   message is printed to standard error output and -1 is returned.
 *   The application programmer should always check this function for
 *   -1 error return.
 * 
 * Linkage: SrvContext *srv_init(hostname,port,db)
 *   char *hostname - name of the host where dbsrv is running
 *   int port       - the port number on which to connect.
 *   char *db       - the name of the database.
 *
 * Returns:
 *  >=0 - the connection id (required by all other srvlib functions)
 *   -1 - if an eror occurred (error messages are printed to stderr)
 *
 * Revisions:
 * 01/17/91 (BDM): hostname, port, and db are now stored into the
 *   connection record when this function is called.
 ****************************************************************/
/****************************************************************
 * Function: srv_close
 * Date: 01/03/91
 *
 * Description:
 *   Closes the connection with dbsrv.
 * 
 * Linkage: int srv_close(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 * 
 * Revisions:
 ****************************************************************/
/****************************************************************
 * ==> Utilities for getting and setting basic connection info 
 ****************************************************************/
/****************************************************************
 * Function: srv_port
 * Date: 01/17/91
 *
 * Description:
 *   Obtain the current port used for connecting to dbsrv.
 * 
 * Linkage: int srv_port(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 * 
 * Returns:
 *   >=0 - port number
 *   < 0 - standard srvlib error code
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_host
 * Date: 01/17/91
 *
 * Description:
 *   Obtain the hostname where dbsrv is located.
 * 
 * Linkage: char *srv_host(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Returns: the host name or NULL if error
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_database
 * Date: 01/17/91
 *
 * Description:
 *   Obtain the database name that we are communicating with.
 * 
 * Linkage: char *srv_database(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Returns: the database name or NULL if error
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_socket
 * Date: 01/03/91
 *
 * Description:
 *   This function returns the actual socket that is used for
 *   communication with dbsrv.
 * 
 * Linkage: int srv_socket(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_uid
 * Date: 01/03/91
 *
 * Description:
 *   Get the user id for the invoker.
 * 
 * Linkage: int srv_uid(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_trace  
 * Date: 01/22/91
 *
 * Description:
 *   Set the level of tracing performed by srvlib.
 * 
 * Linkage: int srv_trace(sc,level)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int level      - level of tracing for srvlib:
 *                    = 0 : trace everything
 *                    = 1 : warnings, errors, and fatal errors only
 *                    = 2 : error and fatal errors
 *                    = 3 : fatal errors only
 *
 * Returns: serlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_set_logfile
 * Date: 01/22/91
 *
 * Description:
 *   Set the file pointer where log messages are sent.
 * 
 * Linkage: int srv_set_logfile(sc,fp)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   FILE *fp       - file pointer for logfile redirection.
 *
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_major
 * Date: 02/21/91
 *
 * Description:
 *   Get the major version number of the srvlib.
 * 
 * Linkage: int srv_major(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Returns: 
 *   > 0 - major version number for the srvlib
 *   < 0 - standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_minor
 * Date: 02/21/91
 *
 * Description:
 *   Get the minor version number of the srvlib.
 * 
 * Linkage: int srv_minor(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Returns: 
 *   > 0 - minor version number for the srvlib
 *   < 0 - standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_release
 * Date: 02/21/91
 *
 * Description:
 *   Get the release version number of the srvlib.
 * 
 * Linkage: int srv_release(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Returns: 
 *   > 0 - release version number for the srvlib
 *   < 0 - standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * ==> Notebook functions
 ****************************************************************/
/****************************************************************
 * Function: srv_get_allowed_notebooks  
 * Date: 01/03/91
 *
 * Description:
 *   Gets a list of notebook ids that are allowed to be used 
 *   by the invoker.
 * 
 * Linkage: int srv_get_allowed_notebooks(sc,l,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   long **l       - list of notebook ids (returned)
 *   int *n         - number of notebooks in list (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_find_note_by_name
 * Date: 01/03/91
 *
 * Description:
 *   Find a notebook by the name of the notebook (title).
 *   The function returns the notebook id is the notebook exists
 *   or -1 if an error occurred.
 * 
 * Linkage: int srv_find_note_by_name(sc,title)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   char *title    - title of the notebook
 *
 * Returns:
 *   > 0 - the notebook id
 *   < 0 - notebook not found
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_inq_notebook_orphans  
 * Date: 01/03/91
 *
 * Description:
 *   Returns a list of orphan pages contained in a specified
 *   notebook.
 * 
 * Linkage: int srv_inq_notebook_orphans(sc,nid,l,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id 
 *   long **l       - list of orphaned page ids (returned)
 *   int *n         - number of pages in list (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_inq_notebook_pages  
 * Date: 01/03/91
 *
 * Description:
 *   Returns a list of page ids in a specified notebook.
 * 
 * Linkage: int srv_inq_notebook_pages(sc,nid,l,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id 
 *   long **l       - list of page ids (returned)
 *   int *n         - number of pages in list (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_create_notebook
 * Date: 02/19/91
 *
 * Description:
 *   Creates a notebook in the database based on information 
 *   contained in the notebook info structure. This function
 *   returns the notebook id for the new notebook.
 * 
 * Linkage: int srv_create_notebook(sc,title)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   char *title    - notebook name
 *
 * Return: returns the notebook id
 *   > 0 - notebook id is returned
 *    -1 - otherwise
 *
 * Revisions:
 * 02/19/91 (BDM): Modified so only the name of the notebook is
 *   specified. Now the server creates the notebook, creates the
 *   home page, and allows the invoker read/write access to the
 *   notebook.
 ****************************************************************/
/****************************************************************
 * Function: srv_modify_notebook
 * Date: 01/03/91
 *
 * Description:
 *   Modify the information about a notebook given the notebook
 *   id and the new notebook info.
 * 
 * Linkage: int srv_modify_notebook(sc,nid,info)
 *   SrvContext *sc      - connection record (returned from srv_init)
 *   int nid             - notebook id
 *   Notebook_info *info - new notebook information
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_inq_notebook
 * Date: 01/03/91
 *
 * Description:
 *   Obtain information about a spcific notebook.
 * 
 * Linkage: int srv_inq_notebook(sc,nid,info)
 *   SrvContext *sc      - connection record (returned from srv_init)
 *   int nid             - notebook id
 *   Notebook_info *info - notebook information (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_get_blurted_note
 * Date: 01/03/91
 *
 * Description:
 * 
 * Linkage: int srv_get_blurted_note(sc,notes,nnotes)
 *   SrvContext *sc         - connection record (returned from srv_init)
 *   Notebook_Block **notes - list of notebook blocks (returned)
 *   int *nnotes            - number of notebook blocks (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_delete_notebook
 * Date: 01/03/91
 *
 * Description:
 *   Delete a notebook in the database given it's id number.
 * 
 * Linkage: int srv_delete_notebook(sc,nid)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * ==> Page functions
 ****************************************************************/
/****************************************************************
 * Function: srv_create_page
 * Date: 02/21/91
 *
 * Description:
 *   Create a page in a spcified notebook in the database based
 *   on the the page information passed. This function returns
 *   the page id for the new page.
 * 
 * Linkage: int srv_create_page(sc,nid,info)
 *   SrvContext *sc  - connection record (returned from srv_init)
 *   int nid         - notebook id
 *   char *title     - page title
 *   int width       - page width (in pixels)
 *   int height      - page height (int pixels)
 *   char *color     - page color
 *
 * Returns:
 *   > 0 - page id
 *   < 0 - standard srvlib error flag
 *
 * Revisions:
 *   02/21/92 (BDM): Modified function header so that all parameters
 *   are passed instead of passing the Page_Info structure.
 ****************************************************************/
/****************************************************************
 * Function: srv_validate_page
 * Date: 01/03/91
 *
 * Description:
 *   Obtain a list of object ids for a specific page in a 
 *   specific notebook.
 * 
 * Linkage: int srv_validate_page(sc,nid,pid)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   int pid        - page id
 *
 * Returns:
 *   1 - If the page is valid
 *   2 - If the page does no exist
 *   3 - If the page exists but the invoker does not have access.
 *
 * Revisions:
 *   2/13/91 (BDM) - changed return codes for consistency with
 *     the standard srvlid error return.
 ****************************************************************/
/****************************************************************
 * Function: srv_modify_page
 * Date: 01/03/91
 *
 * Description:
 *   Modify the basic page information given the page id, notebook
 *   id, and page information.
 * 
 * Linkage: int srv_modify_page(sc,nid,pid,info)
 *   SrvContext *sc  - connection record (returned from srv_init)
 *   int nid         - notebook id
 *   int pid         - page id
 *   Page_Info *info - page info
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_find_page_by_name
 * Date: 01/03/91
 *
 * Description:
 *   Find a page by name in a given notebook.
 * 
 * Linkage: int srv_find_page_by_name(sc,nid,title)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   char *title    - page title
 *
 * Returns:
 *   > 0 - the page id is returned
 *   < 0 - page not found
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_inq_page_links  
 * Date: 01/03/91
 *
 * Description:
 *   Returns a list of links on page. The links are returned as
 *   a list of destination notebook ids and page ids.
 * 
 * Linkage: int srv_inq_page_links(sc,nid,pid,ln,lp,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id 
 *   int pid        - page id 
 *   long **ln      - list of destination notebook ids (returned)
 *   long **lp      - list of destination page ids (returned)
 *   int *n         - number of id in list (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_inq_page_objects
 * Date: 01/03/91
 *
 * Description:
 *   Obtain a list of object ids for a specific page in a 
 *   specific notebook.
 * 
 * Linkage: srv_inq_page_objects(sc,nid,pid,l,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid  - notebook id
 *   int pid  - page id
 *   long **l - list of object ids (returned)
 *   int *n   - number of object ids in list (returned)
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_inq_page
 * Date: 01/03/91
 *
 * Description:
 *   Obtain information about a given page in a given notebook.
 * 
 * Linkage: int srv_inq_page(sc,nid,pid,info)
 *   SrvContext *sc  - connection record (returned from srv_init)
 *   int nid         - notebook id
 *   int pid         - page id
 *   Page_Info *info - page information (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_get_blurted_page
 * Date: 01/03/91
 *
 * Description:
 *   Obtain information about a spcific page and all of the 
 *   objects on that page in one shot. This function should be
 *   used when rendering a page to reduce the number of round
 *   trip transfers between srvlib and dbsrv.
 * 
 * Linkage: int srv_get_blurted_page(sc,nid,pid,page,objects,nobjects)
 *   SrvContext *sc         - connection record (returned from srv_init)
 *   int nid                - notebook id
 *   int pid                - page id
 *   Page_Info *page        - page informatio (returned)
 *   Object_Block **objects - list or object blocks (returned)
 *   int *nobjects          - number of object blocks (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_delete_page
 * Date: 01/03/91
 *
 * Description:
 *   Delete a page in the database given the notebook id and
 *   the page id. The additional argument is used to tell dbsrv
 *   whether to delete all reference links to the page (1) or
 *   to leave the links dangling (0).
 * 
 * Linkage: int srv_delete_page(sc,nid,pid,del_links)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   int pid        - page id
 *   int del_links  - (0) leave links dangling (1) delete ref links
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * ==> Object functions
 ****************************************************************/
/****************************************************************
 * Function: srv_create_object
 * Date: 01/03/91
 *
 * Description:
 *   Create a new object in the database for a given page in a
 *   given notebook. This function returns the object id for
 *   the new object.
 * 
 * Linkage: int srv_create_object(sc,nid,pid,info)
 *   SrvContext *sc    - connection record (returned from srv_init)
 *   int nid           - notebook id
 *   int pid           - page id
 *   Object_Info *info - new object info
 * 
 * Returns:
 *   > 0 - object id
 *   < 0 - standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_modify_object
 * Date: 01/03/91
 *
 * Description:
 *   Obtain a list of object ids for a specific page in a 
 *   specific notebook.
 * 
 * Linkage: int srv_modify_object(sc,nid,pid,oid,info)
 *   SrvContext *sc    - connection record (returned from srv_init)
 *   int nid           - notebook id
 *   int pid           - page id
 *   int oid           - object id
 *   Object_Info *info - new object info
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_inq_object
 * Date: 01/03/91
 *
 * Description:
 *   Obtain spcific information about a specific object on a 
 *   page in a notebook. The full path to the object is required
 *   which includes the notebook id, page id, and object id.
 * 
 * Linkage: int srv_inq_object(sc,nid,pid,oid,info)
 *   SrvContext *sc    - connection record (returned from srv_init)
 *   int nid           - notebook id
 *   int pid           - page id
 *   int oid           - object id
 *   Object_Info *info - object information (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_delete_object
 * Date: 01/03/91
 *
 * Description:
 *   Delete an object in the database given the notebook id,
 *   page id, and object id (full path to the object).
 * 
 * Linkage: int srv_delete_object(sc,nid,pid,oid)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   int pid        - page id
 *   int oid        - object id
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_set_object_text
 * Date: 01/03/91
 *
 * Description:
 *   Set the object text for a specified text object.
 * 
 * Linkage: int srv_set_object_text(sc,nid,pid,oid,txt)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   int pid        - page id
 *   int oid        - text object id
 *   char *txt      - text string
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_get_object_text
 * Date: 01/03/91
 *
 * Description:
 *   Get a pointer to the text for a specific text object.
 *   The function returns a pointer to the text.
 * 
 * Linkage: char *srv_get_object_text(sc,nid,pid,oid)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   int pid        - page id
 *   int oid        - object id
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_get_object_img
 * Date: 01/03/91
 *
 * Description:
 *   Get the image data in raster image format for a spcific
 *   image object.
 * 
 * Linkage: int srv_get_object_img(sc,nid,pid,oid,img)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   int pid        - page id
 *   int oid        - object id
 *   Rast_Img *img  - raster image (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_set_object_img
 * Date: 01/03/91
 *
 * Description:
 *   Store a rater image for a spcific image object.
 * 
 * Linkage: int srv_set_object_img(sc,nid,pid,oid,img)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   int pid        - page id
 *   int oid        - object id
 *   Rast_Img *img  - raster image to be stored
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * ==> Event  functions
 ****************************************************************/
/****************************************************************
 * Function: srv_add_event_handler  
 * Date: 01/12/91
 *
 * Description:
 *   Registers an event handler with srvlib for a specific
 *   dynamic event. These event handlers will be called by
 *   using srv_dispatch_event which handles searching and calling
 *   the appropriate event handler for a given event.
 *
 * Callback Syntax:
 *
 *   void EventHandler(sc,event,client_data)
 *   SrvContext *sc    - connection record (returned from srv_init)
 *   SrvEvnet *event   - event information for spcific event
 *   char *client_data - client data specific when adding handler
 * 
 * Linkage: int srv_add_event_handler(sc,type,proc,data)
 *   SrvContext *sc    - connection record (returned from srv_init)
 *   SrvEventType type - the type of event the handler handles
 *   void (*proc)()    - pointer to the event handler function
 *   char *data;       - client data passed to the event handler
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_dispatch_event  
 * Date: 01/12/91
 *
 * Description:
 *   Dispatches the passed event by calling all registered 
 *   event handlers for the spcified event.
 * 
 * Linkage: int srv_dispatch_event(sc,event)
 *   SrvContext *sc  - connection record (returned from srv_init)
 *   SrvEvent *event - srvlib dynamic event
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_next_event
 * Date: 01/03/91
 *
 * Description:
 *   Retrieves the next event from the event queue.
 * 
 * Linkage: int srv_next_event(sc,event)
 *   SrvContext *sc  - connection record (returned from srv_init)
 *   SrvEvent *event - next event (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_pending
 * Date: 01/03/91
 *
 * Description:
 *   Check if there are any pending events in the event queue.
 * 
 * Linkage: int srv_pending(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 * 
 * Returns:
 *   0 - No pending events
 *   1 - events are pending
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_proc_events
 * Date: 02/21/91
 *
 * Description:
 *   This function process events by getting the next event and
 *   dispatching it. This function will process all pending events
 *   until the event queue is empty.
 *
 * Notes: 
 *   This function is designed to be used with the X function
 *   XtAppAddInput as the callback. When adding this function,
 *   use srv_socket to determine the socket on which to add this
 *   function as an input callback. This allows dynmaic events
 *   generated by dbsrv to be process by any X application.
 * 
 * Linkage: void srv_proc_events(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 * 
 * Returns:  nothing (type void)
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * ==> Author functions
 ****************************************************************/
/****************************************************************
 * Function: srv_get_author_list 
 * Date: 01/03/91
 *
 * Description:
 *   Returns a list of valids user ids. These ids correspond to
 *   the user ids specified in the /etc/passwd file.
 * 
 * Linkage: int srv_get_author_list(sc,l,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   long **l       - list of user ids (returned)
 *   int *n         - number of user ids in list (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_get_active_authors 
 * Date: 01/03/91
 *
 * Description:
 *   Returns a list of valids user ids for users who are currently
 *   connected to dbsrv.
 * 
 * Linkage: int srv_get_active_authors(sc,l,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   long **l       - list of user ids (returned)
 *   int *n         - number of user ids in list (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_allow_author
 * Date: 01/03/91
 *
 * Description:
 *   Allow an author access to a spcific notebook.
 * 
 * Linkage: int srv_allow_author(sc,aid,nid,access)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int aid        - author id
 *   int nid        - notebook id
 *   int access     - access flag 
 *                    = 0 - read access
 *                    = 1 - read/write access
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_disallow_author
 * Date: 01/03/91
 *
 * Description:
 *   Disallow an author access to a specific notebook.
 * 
 * Linkage: int srv_disallow_author(sc,aid,nid)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int aid        - author id
 *   int nid        - notebook id
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_get_author_access
 * Date: 01/03/91
 *
 * Description:
 *   Get the access information for a specific notebook.
 * 
 * Linkage: int srv_get_author_access(sc,nid,nacc,acc)
 *   SrvContext *sc    - connection record (returned from srv_init)
 *   int nid           - notebook id
 *   int nacc          - number of access items (returned)
 *   Access_Item **acc - list of access items (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * ==> Search Functions
 ****************************************************************/
/****************************************************************
 * Function: srv_search_database
 * Date: 01/03/91
 *
 * Description:
 *   Search the database by page title given a spcifiec string.
 *   The function supports case sensitive searches and allows
 *   the user to specifiy a specific wildcard contained within
 *   the string.
 * 
 * Linkage: int srv_search_database(sc,case_sens,wild,s,ln,lp,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int case_sens  - (0) off (1) on : case sensitive searches
 *   int wild       - wild card character code
 *   char *s        - search string
 *   long **ln      - list of notebook ids (returned)
 *   long **lp      - list of page ids (returned)
 *   int *n         - number of notebook ids and page ids (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_search_notebook
 * Date: 01/03/91
 *
 * Description:
 *   Search a notebook for a page by page name
 * 
 * Linkage: int srv_search_notebook(sc,nid,case_sens,wild,s,lp,n)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int nid        - notebook id
 *   int case_sens  - (0) off (1) on : case sensitive searches
 *   int wild       - wild card character code
 *   char *s        - search string
 *   long **lp      - list of page ids (returned)
 *   int *n         - number of page ids (returned)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * ==> System administration functions (restricted access)
 ****************************************************************/
/****************************************************************
 * Function: srv_shutdown_clients
 * Date: 01/03/91
 *
 * Description:
 *   Shutdown all of the clients connected to the server.
 *
 * Restrictions:
 *   This function will only work for authorized users and is
 *   for system administration only.
 * 
 * Linkage: srv_shutdown_clients(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_kill
 * Date: 01/03/91
 *
 * Description:
 *   Kill the server.
 *
 * Restrictions:
 *   This function will only work for authorized super and is
 *   for system administration only.
 * 
 * Linkage: srv_kill(sc)
 *   SrvContext *sc - connection record (returned from srv_init)
 *
 * Revisions:
 ****************************************************************/
/****************************************************************
 * Function: srv_add_author
 * Date: 02/19/91
 *
 * Description:
 *   This function adds an author to the database. The user id should
 *   be the same as the UID in /etc/passwd for any given user.
 *
 * Restrictions:
 *   This function will only work for authorized users and is
 *   for system administration only.
 * 
 * Linkage: int srv_add_author(sc,uid)
 *   SrvContext *sc - connection record (returned from srv_init)
 *   int uid        - user id (as in /etc/passwd)
 * 
 * Returns: standard srvlib error flag
 *
 * Revisions:
 *   02/19/91 (BDM) changed the name from srv_add_user. 
 ****************************************************************/