Problem Record Structure

/* Error numbers returned, use the constant names not their values */

#define BADTYPE		130	/* the type passed into a function is not
				 * defined */
#define NOTFOUND	131	/* the problem record asked for was not
				 * found */
#define DOUBLE		132	/* the reporter is already in the list of 
				 * reporters or the problem has already been 
				 * requested for reopening */
#define DELETED		133	/* the record has been deleted */
#define LINKED		134	/* the request was to move a problem that has 
				 * links (see move_problem) */
#define SOLVED		139	/* the problem has been solved */
#define NOTOWNER        140	/* a request to end an edit has been made by 
				 * someone that did not start it */
#define TXTBSY		141	/* the file that was requested for opening is
				 * busy */
/* EWOULDBLOCK defined in errno.h - the file that was requested to be locked
 * is already locked. */
#define EXIXTS		142	/* the problem already has been requested for
				 * reopening */
#define ORGLINK		143	/* the problem requested for deletion is
				 * an original link */

/* The following are used in the records for field widths */

#define MAXPRID		13			/* length of a problem ID */
#define MAXNAME		41			/* length of an account name */
#define DBPATHLEN	81			/* length of a database path */
#define FNAMELEN	MAXPRID + 4
#define INAMELEN	DBPATHLEN + 6		/* length of the name of an
						 * index file */
#define COMPLETEPATHLEN DBPATHLEN + INAMELEN	/* length of a complete path */
#define MAXSUMLEN	DBPATHLEN		/* length of the short desc. */
#define MAXREC		999999			/* maximum # of records in an
						 * index file */

/* #define MAXHOSTNAMELEN 64 defined in sys/param.h */

/* values for parameters */

/* SOLVED defined above */
#define UNSOLVED	144	/* problem is unsolved */
#define PARTICULAR	145	/* want to find a particular problem */
#define START		146	/* start an edit session */
#define END		147	/* end an edit session */
#define DELETEOK	148	/* it is ok to delete a problem */
#define DELETENOTOK	149	/* it is not ok to delete an original link */

/* structure for a problem record */

typedef struct 
{
   char prid[MAXPRID]			/* the problem id of this problem */
   char short_description[MAXSUMLEN]	/* the short description for this 
					 * problem */ 
   int  num_rep;			/* the number of reporter records */
   reporter_record   *reporter_list;	/* an array of reporter records */
   int		     num_old_rep;	/* the number of old reporter records */
   reporter_record   *old_reporter_list; 
   char              log_file[FNAMELEN];/* the file name of the log file */
} problem_record;

/* structure for a reporter record */


typedef struct
{
   char account_name[MAXNAME];     /* the name of the reporter */
   char node_name[MAXHOSTNAMELEN]; /* the name of the machine the problem
			            * is on */
   char date_time[MAXNAME];        /* the date and time the report was made */
} reporter_record;

/* structure for a reopend record, what is returned by view_reopen() */

typedef struct 
{
   char prid[MAXPRID];         /* the problem id of the reopened record */
   char db_path[DBPATHLEN];    /* the db_path to the problem that is to be 
				* reopened */
   char *reasons_log[FNAMELEN];/* the name of the file containing the reasons */
   reporter_record *rep_rec;   /* see above */
   problem_record *reop_pro_rec;/* the problem record of the reopened 
				 * problem */
} reopend_record;

/* structure for the edit information */

typdef struct
{
   char account_name[MAXNAMELEN];	/* the name of the user doing the
					 * edit */
   char node_name[MAXHOSTNAMELEN];	/* the name of the machine the PTS
					 * is running on */
   int pid;				/* the process id of the PTS running 
					 * the edit */
} edit_info;


Database Operations, Function Prototypes

problem_record *get_problem(char *db_path, char *prid, int type,
				int direction)

int reopen_request(char *db_path, char *prid, char *reasons,
			reporter_record *rep_rec)

int make_branch(char *db_path)

reopen_record *view_reopened(char *reop_prid)

char *confirm_reopen(char *db_path, char *prid, char *reop_prid, 
			reporter_record *rep_rec, char *sys_string, 
			char *reasons)

int deny_reopen(char *prid)

int solve_problem(char *db_path, char *prid)

int delete_problem(char *db_path, char *prid, int perm)

int link_problem(char *old_db_path, /* old database path */
		 char *new_db_path, /* the new database path */
		 char *prid)        /* the problem id of the problem to
				     * link */

int move_problem(char *old_db_path, /* old database path */
		 char *new_db_path, /* the new database path */
		 char *prid)        /* the problem id of the problem to
				     * move */

char *add_problem(reporter_record *rep_rec, char *problem_description,
                  char *short_description, char *db_path)

char *add_reporter(char *db_path, char *prid, reporter_record *rep_rec)

int edit_log(char *db_path, char *prid, int mode)

int remove_edit(char *db_path, char *prid)

Where:

	db_path             - the pathlist to the leaf you want to
				work with
	prid                - the problem identifier (eg. 022119920001)
	reop_prid	    - the problem identifier of a problem to
				reopen
	type		    - the type of problem record (solved, unsolved,
				particular)
	direction	    - the direction of the search (forwards,
				backwards)
	rep_rec		    - a record containing information about the
				reporter.
	problem_description - a variable length text record, containing 
		 		the description of the problem
	short_description   - a short description of the user's problem
        reasons             - a variable length test record, containing
				the reasons for the user wanting to reopen
				a problem.
	sys_string	    - information about the sysop that is
			      confirming the reopening of a problem.
	reopend_record      - a record containing information about the 
				problem to be reopend.
	mode                - the mode of the edit session, see below
	edit_record	    - information about the editing of a record
	perm		    - whether or not it is ok to delete the
				original link of a problem

Operation descriptions

GET_PROBLEM

 The following functions are performed by this function depending on the
type passed. For every call except to find a particular problem the prid
should be set to NULL, this is just to avoid confusion this version will
igonre the parameter unless it is used. This version does not support the
direction parameter, so this should be set to NULL as well to avoid
problems when it is implememted.

	NOTE - The problem record returned by this function is a static
		record and is overwritten each time the functionis called.


	FIND_PROBLEM (PARTICULAR)

	 This function will find a particular problem from a database.
	The problem record for that problem will be returned if the 
	problem is found.  NULL will be returned if the problem does 
	not exist in the database given or if there was an error.  
	The error number is located in the global variable db_errorno.


	NEXT_UNSOLVED (UNSOLVED)

	 This function returns the next unsolved problem from the 
	database given.  The problem record for the next unsolved 
	problem is returned if there is one.  If there are no more 
	unsolved problems then NULL is returned.  If there is an error 
	NULL is returned and the error number is placed in the global 
	variable db_errorno.


	NEXT_SOLVED (SOLVED)

	 This function returns the next solved problem from the 
	database specified.  The problem_record for the next solved 
	problem is returned if there is one.  NULL is returned if either 
	there are no solved problems or an error occured.  If an error 
	occued the error code is placed in the global variable bd_errorno.


REOPEN_REQUEST

 This function places the problem that has been requested to be reopened
into the special reopen directory.  If the placement succeeds a 1 is
returned, a 0 is returned on error.  The error number is located in the
global variable db_errorno.


MAKE_BRANCH

 This function will create the branch of the problem tree given if it does not
already exist.  It travels down the tree and creates those directories that
do not already exist.  It will also create the index file in the leaf node,
which will be the final name in the path given.  If the creation succeeds 
a 1 is returned.  If the creation fails 0 is returned.  The error number 
is placed in the global variable db_errorno.  

	NOTE - If the entire branch already exists the function 
		will return one, since by default the creation was 
		successful.


VIEW_REOPENED

 This function returns the next problem that has been requested for
ropening.  All the requests are stored in one directory, so there is no need
to specify a path.   The reopened_record is returned if there is a reopen
request pending.  NULL is returned if there are no requests pending or if
there was an error.  If there was an error the error number is placed in
the global variable db_errorno.

	NOTE - The reopened record returned by this function is static
		storage and is overwritten each time the function is called.


CONFIRM_REOPEN

 This function moves a requested reopened problem from the special
directory to the directory it belongs to.  The entry is then removed from
the reopend directory.  The new problem id is returned if the problem is
successfully added to the database and 0 otherwise.  The global variable
db_errorno will contain the error number, if there was an error.


DENY_REOPEN

 This function will remove an entry from the reopened directory without
reopening the problem.  After this function is called the problem is no
longer listed as a reopened request.  The function returns a 1 if the
removal succeded.  If there was an error then 0 is returned and the error
number is placed in the global variable db_errorno.


SOLVE_PROBLEM

 This function marks a currently unsolved problem as solved, in the
database given.  It returns 1 if successful and 0 otherwise.  The error
number is placed in the global variable db_errorno if an error occurs.


DELETE_PROBLEM

 This function removes the specified problem from the specified database.
If the problem to be deleted is the originating problem of a series of 
linked problems then all the links associated with it will also be deleted.  
For this reason one of the two following parameters must be used:

	DELETEOK
or
	DELETENOTOK

If the problem to be deleted is an orginal link and DELETENOTOK is
specified then the call fails and ORGLINK is placed in db_errorno.  If
DELETEOK is specified then the problem will be deleted whether it is
an original link or not.  The function should normally be called with
DELETENOTOK and the user notified when the call fails.  If she still wishes
to deleted the problem then it can be called again with DELETEOK.

 It returns 1 if the deletion is successful and 0 otherwise.  If not
successful the error number is placed in the global variable db_errorno.


LINK_PROBLEM

 This function copies a problem and places the copy in the new leaf.  This
operation in effect creates a virtual copy since only one complete copy of
the problem exists in the database tree.  After this operation the problem
given can be accessed by searching either the old leaf or the new leaf.
This is to help facilitate retrieving a problem that can relate to more
than one leaf of the problem tree.  If the move is successful a 1 is 
returned, otherwise 0 is returned.  If an error occurs the error number 
is located in the global variable db_errorno.

MOVE_PROBLEM

 After a call to this function the problem will no longer be listed in the old
leaf.  It will be listed in the new leaf.  All links made to the problem before
it was moved will remain, though the updating of the links may take a day or
more.

ADD_PROBLEM

 This function adds a problem to the leaf specified.  It returns the
problem id of the new problem if the problem was successfully added and NULL
if there was a problem.  If a problem occurs the error number will be 
located in the global variable db_errorno.

ADD_REPORTER

 This function will add a reporter to the list of reporters for the problem
specified by the problem id and the db_path.  If the call succeeds it
returns the problem id of the problem the reporter was added to.  If an
error occurs then NULL is returned and the error number can be found in
db_errorno.


EDIT_LOG

 This function marks a problem as currently being in edit.  It places the
account name of the person performing the edit, the machine the PTS system
performing the edit is running on and the process id of the PTS system that
is performing the edit.  The mode parameter is currently one of two values;

	START - to start the edit session
	END   - to end the edit session

If the change of state succeeds 1 is returned.  If the request was to begin
the edit and the record is currently being edited or there is an error then
0 is returned and the error number is placed in db_errorno.

NOTE - if the caller is not the person who started the edit then the call will
fail and place NOTOWNER in db_errorno.  To remove an edit lock that was not
started by the caller they must use remove_edit() below.  You can get the 
information about an edit lock from a call to edit_info() below.


EDIT_INFO

 This function returns information about the current (or past) edit of a problem
This information can be used to check to see if the proccess that locked a 
problem is still alive.  This should be used before a call to remove_edit().


REMOVE_EDIT

 This function unconditionally removes the edit flag from the record 
specified.  It does no checking to see if the record is currently being
edited or not, because of this and because of possible update problems 
this function should only be called when absolutly necessary.  The
edit_log() function with a value of END should be used unless the proccess
that was performing the edit dies without removing the lock, in which case
this is the only way to remove the lock.  If the call succeeds a 1 is 
returned.  If an error ocuurs the error number is placed in the global 
variable db_errorno.
