D64 Programming Assignment #1

Due Wednesday, February 16 at 4p.m.

Your first programming lab is to implement a very simple relation manager that will support creating new relations, inserting records, etc. Specifically you need to implement the functions below. I've provided the header file already that includes the prototypes.

1. int CreateTable(char *table_name, int num_cols, colRec_t *atts)

   This function creates a new table with the given name. The paramater num_cols specifies how many columns will be in the new table and atts is an array of descriptors, one per column. See the header file and the sample test program for more details.

2. int InsertRow(char *table_name, int num_vals, valRec_t *vals)

   This function inserts a new row into an existing table specified by table_name. The column values for the new row are passed in via the vals array and num_vals indicates how many entries are in the array. If a column in the table has no corresponding value in the vals array its value in the new row should be NULL (the database meaning, not necessarily the C meaning).

3. int ScanBegin(char *table_name, struct scanDesc_t **scan)

   This function is used to begin a scan of an existing table specified by table_name. Upon successful completion, the scan descriptor that was passed in will be properly set. The scan will be positioned before the first row in the table.

4. int ScanNext(struct scanDesc_t *scan)

   This function advances the scan by one record. If there are no more records it should return the error END_OF_SCAN. The scan parameter should have already been set by a ScanBegin call.

5. int GetString(struct scanDesc_t *scan, char *col_name, char **val)

   This function get the value of a string column from the current row in the scan. The name of the desired column will be in col_name and on successful completion, the val pointer will be set to the string value. If the column is NULL, the function should return the error NULL_VALUE. If the column is an integer column, it should return the error BAD_COL_TYPE.

6. int GetInteger(struct scanDesc_t *scan, char *col_name, int *val)

   This function get the value of an integer column from the current row in the scan. The name of the desired column will be in col_name and on successful completion, the val pointer will be set to the integer value. If the column is NULL, the function should return the error NULL_VALUE. If the column is a string column, it should return the error BAD_COL_TYPE.

7. int ScanUpdate(struct scanDesc_t *scan, int num_vals, valRec_t *vals)

   This function updates the current record in the scan by setting some of its columns to the values indicated in the vals array. The parameter num_vals will contain the number of entries in the vals array. Any column that does not appear in the array will not have its value changed. In addition, if the vals array entry has the is_null flag set, the value of the corresponding column will be set to NULL. If the scan is not currently on a row, the error NOT_ON_ROW should be returned.

8. int ScanDelete(struct scanDesc_t *scan)

   This function deletes the current record in the scan. If the scan is not currently on a row, the error NOT_ON_ROW should be returned.

9. int ScanEnd(struct scanDesc_t *scan)

   This function ends a scan and reclaims any resources needed by the open scan. Every call to BeginScan should have a matching call to ScanEnd.

Notes:

• You may not, under any circumstance, alter the prototypes of the functions above or the type definitions that they depend upon. They must be implemented exactly as written.
• I expect you to do reasonable error checking on all parameters and will be checking this when I grade the assignment. You may need to add additional error codes to the db.h file. This is acceptable.
• Do not assume that just because your code runs on the example program that it is correct. Write you own code to test it more thoroughly.

Buffer Manager

To make this assignment easier, I'm providing a really simple buffer manager that you MUST use. You should not use any operating systems calls for file access. Both the header file and code are available on the web. You may not change the buffer manager in any way without my permission. Send me email if you think you've found a bug. Here are the functions that the buffer manager supports. A simple test program that shows how to call them is available as well.

1. void InitBuffer(void)

   This function must be called before any other buffer manager calls are made.

2. int FileExists(char *file_name)

   This function will check if a file with the passed in name already exists, returning 1 if it does and 0 if it does not.

3. int OpenFile(char *file_name)

   This function opens the indicated file and returns a file descriptor for it. If the file did not exists, a new file is created. Note that this is not the same as the operating system file descriptor - it is only for use by the buffer manager calls. A negative number indicates an error upon opening the file.

4. int CloseFile(int fd)

   This function closes a file previously opened with the OpenFile function.

5. int GetNumBlocks(int fd)

   This function returns the number of blocks that are in the previously opened file indicated by the passed descriptor.

6. int GetBlock(int fd, int block_num, void **buffer)

   This function reads a particular block from a file and set the buffer pointer to point to it. The parameter block_num should be a non-negative value indicating which block to read. The block will be pinned until a ReleaseBlock call is made.

7. int AppendBlock(int fd, void **buffer)

   This function adds a new block to the end of the file and sets the buffer pointer to point to it. The initial values in the block are undefined. The block will be pinned until a ReleaseBlock call is made.

8. int ReleaseBlock(int fd, int block_num, int modified)

   This function releases a previously pinned block. The modified flag should be 1 if the block was modified since it was read, 0 otherwise. Blocks that were just appended should always be marked as modified. After a block has been released, any previously returned pointer to it (GetBlock, AppendBlock) should be considered invalid.

9. int TruncateFile(int fd, int last_block)

   This function trims the file so that last_block (0-based) is the last block in the file.

Notes:

• The buffer manager can only have one active block per file at a given time. Thus you cannot get or append a new block until the previous block has been released.

Makefile

I've provided an optional makefile for your use.

Documentation

You must submit a description of your design in a plain text file called dbe.doc, and to include comments in the code.

Grading

The grade of your program will be based on three aspects:

• Functionality - that the program correctly implements the specifications.
• Quality - elegant design and modularity.
• Documentation - as described above.

Testing and Submission

Submission of the assignment will take place electronically. Please tar your source code, makefile, and your dbe.doc documentation file. Then, send me an email with the subject Program 1 and attach the tar file.

Collaboration Policy

Students must work alone on this assignment, both on the design, coding, and testing stages. Every line of code should have been written by you or provided by me. YOU MAY NOT SHARE CODE, EVEN TEST CODE. Please do not turn in work that is similar enough to a fellow student's that we have to involve the academic police.