This is the API to connect with the editor database.  For now, I'd recommend
running everything on speedy.cc because I hardcoded some things temporarily.
However, the client can connect to other hosts... just not right now.  Some
things  you should know before you get started...
 

1)
Username:  vrmidtown
Password:  vrmidtown
Database:  vrmidtown
tables: editors

This account has ALL privileges so please be careful when doing anything from
the mysql prompt.

2)
Start the server by typing:
startdb-X where X is the platform you're running on.

3)
I have included a test client that executes all the functions in the library.
It's pretty simple and everything is explained further in the userdb.h file.
The "make" file is just a script called "run" for now.

4)
I have included a script to create a small test table for the test client.
You will require both create and create.sql files.  Create can be run from any
directory.  Please run this before you run the test client so you can start
with fresh data.

5)
I probably left something out so e-mail me if you have problems.  Also,
there's an extensive manual in html format included with the mysql server.

6)
Start the server before you do ANYTHING.  Otherwise, it's pretty much
pointless, isn't it.  Also, don't forget to kill the server after you're
done.  This can be done my typing:
killdb-X where X is the platform you're running on.
 
 
 

#define SUCCESS 0
#define ERROR   1
#define ERROR_A -1
 
 

/* error types */
#define ERR_CONNECT             1
#define ERR_QUERY               2
#define ERR_INITIALIZE_MYSQL    3
#define ERR_STORE_RESULT        4
 

typedef struct{
        char    editor[21];
        char    label[41];
        float   x_coord;
        float   y_coord;
        float   z_coord;
        float   rotX;
        float   rotY;
        float   rotZ;
        float   rotAmt;
        int     mode;
        int     record_lock;
        char    filename[256];
} object_t;
 

/* return values for the following functions.
SUCCESS and ERROR are obvious.  ERROR_A represents check errors, for eg: the
user you want to delete does not exist, etc...
*/
 

/* function prototypes */

int attempt_CheckOut (char *name, char *label);
/*
Lock both tables.  If universal is not null, unlock and try again.
If the universal lock is null, update it using the username.  Server checks
to see if the update for the given label is allowed, ie: no one else has
checked out the particular label, by locking the table and executing a
select stmt.  It Checks record_locked field and makes sure it's 0.  If
it's a 1, unlock everything and return an error and disconnect.
Otherwise, unlock all tables.  Used when checking in items into the
database.
Input:  name, label
Output: int
"0" -> success
"1" -> someone already owns the item (record_lock = 1)
"2" -> item does not exist.
"100+" -> assorted errors
*/
 

int CheckOut (object_t *object);
/* This function will be
used to check-out the item from the database so it can be edited.  It will
pass in a pointer to the struct to be edited by the function.  Update the
editor's name and record_lock.  Unlock the table.
Inputs:  object struct.
Outputs:  int
"0" -> success
"1" -> you already own it
"2" -> someone owns it already
"3" -> does not exist
*/

int attempt_CheckIn (char *name, char *label);
/*
 Lock both tables.  If universal is not null, unlock and try again.  If
the universal lock is null, update it using the username.  Server checks
to see if the update for the given label is allowed, ie: no one else has
checked out the particular label, by locking the table and executing a
select stmt.  It Checks record_locked field and makes sure it's 0.  If
it's a 1, unlock everything and return an error and disconnect.
Otherwise, unlock all tables.  Used when checking in items into the
database.
Input:  name, label
Output: int.
"0" -> success
"1" -> someone already owns the item (record_lock = 1)
"2" -> item does not exist.
"100+" -> assorted errors
*/
 

int CheckIn (object_t *object);
/*
Lock the universal and editor's table.  If the universal is locked,
release and try again.  Otherwise, continue.  This function is going to
take in an object struct.  This is going to finish what attempt_CheckIn
was doing.  It will update the record, unlock the record_lock field = 0,
remove the editor's name, and unlock the tables.
Input:  object_t
Output:  int
"0" -> success
"1" -> the record was not locked.
"2" -> other assorted errors
*/
 

object_t *
reqGetWorld (char *user, int *const NumItems);
/*
This function is going to make sure that no one is checking in an
object.  It locks the editor and universal table and looks at all the
records in the table and makes sure that all record_locks = 0.  If
something =1, then unlock the table, wait a little while, and try it
again.  Then, it tries to lock the table.  It does this by trying to lock
the universal record lock=1.  If univ_lock=0, go ahead.  Otherwise,
unlock universal table, wait a little while and try it again.
Basically acts like a file permission setter.  If the universal lock is null,
it sets it to user and returns "0".  This function also takes in a pointer
that will be an array of structs of type object_t.  It will iterate
through the database and fill in the array.  Otherwise, it returns "2".

Inputs: username, some value that will hold the number of items in the array.
Outputs: array of object_t structs

NumItems will take on:
"-1" -> success
"-2" -> error
*/

int doneGetWorld (char *name);
/*
Lock universal table.  If value is username, set to null.  This function is
going to unlock the universal lock.  It is usually called after reqGetWorld
has set the universal lock and done whatever it needs to do.  Then unlock
universal table.

Inputs: name
Outputs: int
"0" -> success
"1" -> the table is already unlocked
"2" -> other kind of error
*/
 
 
 
 
 
 

int importMetaFile (object_t *object, int NumItems);
/*
Only used at the beginning of starting up a server in order to read in
old metafile data.   Lock the table.  This function is going to accept a
pointer to an array of structs of type object_t.  It will then read
through the array and populate the editor table as necessary.  Unlock
table.
Inputs: pointer type object_t , NumItems
Outputs: int
"0" -> success
"1" -> failure
*/
 
 

object_t *
exportMetaFile (int *NumItems);
/*
Lock table. This function is going to accept a pointer to an integer.  It
will then read through the database and populate the array as deemed
necessary. This array is then returned.  Finally, the table is
unlocked.
Inputs:
Outputs: array of object_t structs
NumItems:
">0" -> success
"-1" -> failure
*/