CMSC 106

Project #7

Spring 2002

Due date: Friday, May 10, 2002

1. Purpose

In this project you will write a program using structures, structures which contain other structures as members, arrays of structures, and functions with structure parameters, using both call-by-value and call-by-reference.

Assume you found a collection of LP music albums in your basement, and you plan to record them onto CD's. Since multiple albums will fit onto a single CD, you decide to write a program to keep track of which albums are on which compact disc. At the same time, you can also use the program to search your disc collection to find albums containing songs with a certain title or by a certain author, or albums with a certain date. You will first read in a list of albums with their song titles and other information. Then you will read in a list of commands to record collections of albums onto discs and find albums or songs on the recorded discs.

2. Project description

As you read this section, you may also want to refer to the ``Sample output'' section below.

2.1 Program input

The input data file will consist of two sections. The first section will consist of a list of albums and their songs. The first line for each album will contain:

• Artist's name
• Album title
• Year

The artist's name will followed by a semi-colon (';'). The album title will be followed by a comma (',').

Following the album title line will be a list of songs. Each song will be on a separate line, consisting of:

• Song title
• Author name
• Playing time, in minutes and seconds, separated by a colon (':')

The song title will be followed by a comma, and the author name will be followed 1 or more blanks. The author name may consist of multiple names separated by a slash ('/'), but the names do not have to be stored separately. The last song on an album will be followed by a line containing ``#####''. The last album will be followed by a line containing only the word ``end''.

Following the list of albums will be a list of commands. The possible commands are:

• record: The ``record'' command is followed by a list of album titles. Each title will be on a separate line, and the end of the list will be shown by a line containing ``#####''.
• list: The ``list'' command will contain the number of a CD.
• find: The ``find'' command may be followed on the same line by:
  • The word ``song'' and a song title.
  • The word ``author'' and an author name.
  • The word ``year'' and a year value.

The name of a command will be separated from its parameters by white space (one or more blanks) and there could be blanks at the beginning or end of the line. The list of commands will end with the end of the input file. The actions to be performed for each operation are described in the "Processing and output" section below.

2.2 Processing and output

The program will read the list of albums and their contents and store the data in STRUCTURES, as described below. After the album data has been read and stored, the program will read and process each command. The output of each command should be preceded by a blank line, then a separator line containing 20 equal signs ("=").

The commands are processed as follows:

• record: The ``record'' command will tell the program to read the list of album titles and store the data for each album on the same CD. Each CD which is recorded is assigned a number, beginning with 1. If the input contains an album title which is not found in the list of albums originally read in, then the program must print the message:

  
  Album "Name" not found!
  

  where ``Name'' is the name of the album. If an album name is not found, the program will continue processing the list of albums for the ``record'' command.

  The program must calculate the total playing time for all the albums on a CD to determine if the albums will fit on the CD. If the total playing time for the CD would be too long, the program must print the message:

  
  Album "Name" exceeds maximum playing time!
  

  where ``Name'' is the name of the album which would cause the playing time of the CD to exceed the capacity of a CD. The maximum playing time for a CD is 90 minutes. If the maximum playing time for a CD is exceeded, the program must go on to the next command without storing the data for that CD.

  After a disc has been successfully recorded, the program must print the message:

  
  Disc nn recorded.
  

  where nn is the number of the disc.

• list: The ``list'' command will tell the program to print the contents of a particular CD given by the number on the command. The contents are printed by giving the title, artist, and year for each album, followed by the list of songs on the album, as shown in the sample output. If the CD with that number does not exist, the program must print the message:

  
  Disc nn not found!
  

  where nn is the number of the disc.

• find: If the ``find'' command contains a song name, then the program must list the names of all albums containing the song, along with the CD numbers for each album. If the command contains an author name, then the program must list the names of all songs by that author, along with the CD numbers for each album containing those songs. If the command contains a year, then the program must list the names of all albums from that year, along with the CD numbers for each album. If the song, author, or year is not found, the program must print out a message. For a song, the message is of the form:

  
  Song "Name" not found on nn discs.
  

  where ``Name'' is the name of the song, and nn is the total number of currently recorded discs. For an author or a year, the word ``Song'' would be replaced with ``Author'' or ``Year'', and ``Name'' would be replaced with the name of the author or the year.

• The program will continue reading and processing commands until it reaches the end of the input file.

2.3 Program limits and assumptions

• The maximum lengths of strings are as follows:
  • input line: 80
  • artist or author name: 20
  • title: 40

• Maximum sizes are:
  • number of songs per album: 20
  • number of albums per disc: 30
  • number of discs: 10

• There is no limit to the total number of commands to be processed.

3. Project requirements

All your C programs in this course should be written in ANSI C, which means they must compile and run correctly with cc -std1 -trapuv on the OIT UNIX Class Cluster. You will lose credit if your program generates any warning messages when it is compiled. Prototypes must appear for all functions used, listed at the top of the program file.

You may use any ANSI C language features we have discussed in the course so far, plus anything we will discuss between now and the end of the semester, with the following exceptions:

• neither the goto nor the continue statement may be used, and the break statement may not be used in any loop.

• the exit() library function may not be used at all, and at most one return statement may be used in any function, including main. The return statement must appear at the end of the function.

• no global variables may be used.

• no functions whose names start with mem can be used

• no single function, including the main function, can be longer than 30 lines of executable statements

Using any of these disallowed C features will result in losing credit.

Your program must define three structure types, as described below, which must be named exactly as shown. Your structures must contain the data items specified, but can have additional data fields besides these if you want. Unless otherwise specified, you may choose the type of any structure fields, but all numeric values must be defined as int or float. You may also define additional structure types and declare arrays of structures.

Disc:

• array of albums
• number of albums
• total playing time

Album:

• title
• artist name
• year
• number of songs
• array of songs
• total playing time

Song:

• title
• author
• playing time

Your program must contain (and use) at least eight separate structure functions. A structure function either has a structure as a parameter, a structure as its return value, or has a pointer to a structure as a parameter. Your program must have at least one such function for each of the three required structures. To get more practice using functions with structures, and to make your program easier to develop and test, it is highly recommended that you write more than eight structure functions (that you write as many as possible). At least two of your structure functions must use call-by-value for their structure parameter(s) or must have a structure as their return value. At least two of the functions must use call-by-reference for their structures, so they must have pointers to structures as parameters, and they access the structures through the pointers.

If your program doesn't contain, and call, at least eight structure functions, of the types indicated, it will be graded as if it does not work on the primary input- even if its output is correct.

You may also write functions which don't operate on structures, as you like.

Here are some suggestions for possible structure functions; feel free to use others:

• Initialize a disc
• Read and process the contents of an album
• Read and process the data for a song
• Print the contents of a disc
• Print the contents of an album
• Print the data for a song
• Process a command
• Record an album
• Find the albums and discs containing a song
• Find the songs by an author and the discs containing them
• Find the albums from a given year and the discs containing them

Your program must have a comment near the top which contains your name, login ID, student ID, your section number, your TA's name, and an original description of the action and operation of the program. Do not put your alias in this comment! In addition, you must have a comment before each function, explaining its action and operation. Your program should be written using good programming style and formatting, as discussed in class and throughout your textbook. For this project, style is considered to consist of:

• adequate descriptive comments throughout (in addition to the comments mentioned above), to describe what your program is doing and how

• neat and proper indentation and formatting, including correctly aligning braces using any of the bracing styles illustrated in your textbook

• writing clear and readable code

• use of meaningful descriptive variable and parameter names

• use of symbolic constants for all ``special'' values which don't change and which are used in more than one place in your code, and for all array dimensions

• avoiding disallowed C language features and global variables as discussed above

• using prototypes for all functions with descriptions of the purpose of each function either by the prototype or the function definition

• using character constants (e.g., 'A'), rather than the characters' numeric ASCII values anywhere that specific character values are needed.

• avoiding multiple return statements in any function

4. Developing your program

You may want to skip this section at first, read the rest of the project, and come back to study it carefully when you are about to begin writing your program.

The more you write functions to perform various manipulations on structures, the easier your code becomes to test. You can use either call-by-value or call-by-reference for structure functions, but you have to have the indicated number of functions of each type. It is really recommended you use functions for each separate, discrete operation to be performed on any structure.

Do not use a global structure variable or array, like your book does in its example in Chapter 16! You will lose substantial credit if you use global variables in your project.

4.1 Possible development steps

It is extremely useful to first develop your program to work for simple cases of input. When it works perfectly for these, you can add code to handle the more complex situations one at a time. For this project, this might mean first developing your program for a simple input data file with just one valid command. You can create several such files, with one command of each type, making sure your results are correct for each. When you have thoroughly tested the different situations which can occur for the various commands and the results for all of them are fine, you can create a larger input file with several commands of different types.

This outline is a suggestion only; you do not have to follow it. There are many ways to develop any program. However, whatever steps you do choose in developing your project, you should be certain to write small parts of your program at a time and test each one to verify that it works before going on!

1. To get more practice with structures, it might be a good idea to first define just the Song structure type. It contains several fields, but is much simpler than the Disc structure, which contains other structures. You might also write a function which initializes a variable of this type of structure, using either call-by-value (returning a new structure with appropriate values in its fields) or call-by-reference. Declare a variable of this type, and call this function on it. Store some new values into the appropriate fields of your structure and print the values in all its fields, to verify you are manipulating structures correctly.

2. Create functions to read and print the information from the album list. Make sure everything is being read and printed correctly before you try to do processing of commands.

3. Create several simple input files
   • one with only one album, one song and one command
   • modify the command data to test the different error messages from that part of the input

4. Go back and read the project description above to identify the other cases and situations which have to be handled. Add code for each of these, compiling and checking after each one.

5. Lastly, thoroughly check your entire program after finishing it before submitting it.

4.2 Finding compilation errors

If you get an error from the first line of your first structure function, which identifies a syntax error right after the name of the structure type, you probably have declared the structure type after this function which uses it. All structure type definitions must precede the first use of a variable or parameter of that structure type.

Here are several other common compilation errors having to do with structures produced by the cc compiler on our class machines and what they mean:

• Invalid member declaration

  Structure fields cannot be initialized in a structure type definition. See your class notes or text for the proper way to declare a structure variable with an initializer.

• ``X'' has a struct type, but occurs in a context that requires a pointer

  (where X is the name of a structure variable)

  You are using the -> operator with something which is a structure, not a pointer to a structure. The -> operator only operates upon a pointer to a structure. Carefully draw a picture of your structure variables, and look at how the statement with the error is referencing them.

• ``X'' has a pointer type, but occurs in a context that requires a union or struct

  (where X is the name of a pointer variable)

  This is the opposite of the above problem. You are using the . operator with something which is a pointer to a structure, not a structure.

• Identifier expected but not found

  You are using the . operator directly in front of an array subscript (i.e., x.[y]). The . operator selects a field of a structure, so it must be followed by a field name, not a subscript. Perhaps you are trying to refer to an element within an array field, but you forgot the array field name after the . and before the subscript.

• ``X'' is not an lvalue, but occurs in a context that requires one

  (where X is the name of an array variable)

  You are trying to assign something to the name of an array. Perhaps you are trying to copy one character string to another, but you have to use strcpy since you cannot assign arrays.

• ``X'' is of type ``int'', and may not be converted to ``unnamed struct''

  (where X is the name of a variable being used as a function's return value)

  You are probably trying to return an int from a function whose return type is a structure, not a number.

• ``X'' is of type ``unnamed struct'', and may not be converted to ``int''

  (where X is the name of a structure variable)

  This is the opposite of the above problem. You are probably trying to return a structure from a function whose return type is int, not a structure.

• ``X'' is of type ``unnamed struct'', and may not be converted to ``pointer to unnamed struct''

  (where X is the name of a structure variable)

  You are trying to pass a structure to a call-by-reference structure function, which is expecting an argument which is a pointer to a structure.

• ``&X'' is of type ``pointer to unnamed struct'', and may not be converted to ``unnamed struct''

  (where X is the name of a structure variable)

  This is the opposite of the above problem. You are trying to pass a pointer to a structure to a call-by-value structure function, which is expecting an argument which is a structure, not a pointer to a structure.

4.3 Program debugging

1. Add lots of debug printf statements if your code isn't working, to find out where! You need to know this before you can find out why the problem is occurring.

2. Draw lots of pictures of your structure types to trace exactly where things are in memory.

3. If after you have tried these techniques, and tested each of your functions, you still can't figure out why your program doesn't work, bring a printout to our office hours, and we can help you learn how to track the problem down.

4.4 Helpful hints

Frequently save backup copies of your program under different names or in different subdirectories, so even if you inadvertently delete your file or change things which you realize you shouldn't have, it's easy to recover a recent version.

5. Academic integrity statement

Any evidence of unauthorized use of computer accounts or cooperation on projects will be submitted to the Student Honor Council, which could result in an XF for the course, suspension, or expulsion from the University. Projects are to be written INDIVIDUALLY. For academic honesty purposes, projects are to be considered comparable to a take-home exam. Any cooperation or exchange of ideas which would be prohibited on an exam is also prohibited on a project assignment, and WILL BE REPORTED to the Honor Council.

VIOLATIONS OF ACADEMIC HONESTY INCLUDE:

1. failing to do all or any of the work on a project by yourself, other than assistance from the instructional staff.

2. using any ideas or any part of another student's project, or copying any other individual's work in any way.

3. giving any parts or ideas from your project, including test data, to another student.

4. having programs on an open account or on a PC that other students can access.

5. transferring any part of a project to or from another student or individual by any means, electronic or otherwise.

IT IS THE RESPONSIBILITY, UNDER THE UNIVERSITY HONOR POLICY, OF ANY STUDENT WHO LEARNS OF AN INCIDENT OF ACADEMIC DISHONESTY TO REPORT IT TO THEIR INSTRUCTOR.

6. Submitting your project

Your project must be electronically submitted by the date above, to avoid losing credit as described on the syllabus. No projects more than two days late will be accepted for credit without prior permission or a valid medical excuse, as described on your syllabus. Only the project which you electronically submit, according to the procedures provided, can be graded; it is your responsibility to test your program and verify that it works properly before submitting. Lost passwords or other system problems do not constitute valid justifications for late projects, so do not put off working on your program or wait to submit it at the last minute!

Turn in your assignment using the ``submit'' program as before, except using ``7'' for the project number. You are to submit only the .c file containing your source code, not the executable version of your program! If your program is in a file named ``music.c'', submit would be run as submit 7 music.c.

Before you submit your project, you must exactly follow the specific submission checklist in the ``Testing projects before submitting'' handout separately posted by your instructor!

7. Sample output

Assuming the name of the executable version of the program is ``music.x'', here is a sample execution for one set of input. The information contained in the input file is shown as displayed by the UNIX ``cat''command. Following the data file's contents, the results of running the program with input redirected from that file are shown.

Be sure to test your program against a variety of inputs, so you are sure it works in all circumstances!

% cat p7.in1

Beatles; Abbey Road, 1969
Come Together, Lennon/McCartney 4:20
Something, Harrison 3:03
Maxwell's Silver Hammer, Lennon/McCartney 3:27
Oh! Darling, Lennon/McCartney 3:26
Octopus's Garden, Starkey 2:51
I Want You (She's So Heavy), Lennon/McCartney 7:47
Here Comes The Sun, Harrison 3:05
Because, Lennon/McCartney 2:45
You Never Give Me Your Money, Lennon/McCartney 4:02
Sun King, Lennon/McCartney 2:26
Mean Mr. Mustard, Lennon/McCartney 1:06
Polythene Pam, Lennon/McCartney 1:12
She Came In Through The Bathroom Window, Lennon/McCartney 1:57
Golden Slumbers, Lennon/McCartney 1:31
Carry That Weight, Lennon/McCartney 1:36
The End, Lennon/McCartney 2:19
Her Majesty, Lennon/McCartney 0:23
#####
Beatles; Rubber Soul (Original Uk Edition), 1965
Drive My Car, Lennon/McCartney 2:30
Norwegian Wood (This Bird Has Flown), Lennon/McCartney 2:05
You Won't See Me, Lennon/McCartney 3:22
Nowhere Man, Lennon/McCartney 2:44
Think For Yourself, Harrison 2:19
The Word, Lennon/McCartney 2:43
Michelle, Lennon/McCartney 2:42
What Goes On, Lennon/McCartney 2:50
Girl, Lennon/McCartney 2:33
I'm Looking Through You, Lennon/McCartney 2:27
In My Life, Lennon/McCartney 2:27
Wait, Lennon/McCartney 2:16
If I Needed Someone, Harrison 2:23
Run For Your Life, Lennon/McCartney 2:18
#####
Beatles; Yellow Submarine (Original Version), 1969
Yellow Submarine, Lennon/McCartney 2:42
Only A Northern Song, Harrison 3:27
All Together Now, Lennon/McCartney 2:13
Hey Bulldog, Lennon/McCartney 3:14
It's All Too Much, Harrison 6:28
All You Need Is Love, Lennon/McCartney 3:52
Pepperland, Martin 2:23
Sea Of Time, Martin 3:00
Sea Of Holes, Martin 2:20
Sea Of Monsters, Martin 3:39
March Of Meanies, Martin 2:22
Pepperland Laid Waste, Martin 2:15
Yellow Submarine In Pepperland, Lennon/McCartney 2:10
#####
Bob Dylan; Nashville Skyline, 1969
Girl From The North Country, Dylan 3:41
Nashville Skyline Rag, Dylan 3:12
To Be Alone With You, Dylan 2:05
I Threw It All Away, Dylan 2:23
Peggy Day, Dylan 1:59
Lay Lady Lay, Dylan 3:20
One More Night, Dylan 2:25
Tell Me That It Isn't True, Dylan 2:45
Country Pie, Dylan 1:35
Tonight I'll Be Staying Here With You, Dylan 3:23
#####
Simon & Garfunkel; Bridge Over Troubled Water, 1970
Bridge Over Troubled Water, Simon 4:52
Condor Pasa (If I Could), Robles/Simon 3:06
Cecilia, Simon 2:55
Keep the Customer Satisfied, Simon 2:33
So Long Frank Lloyd Wright, Simon 3:41
Boxer, Simon 5:08
Baby Driver, Simon 3:15
Only Living Boy in New York, Simon 3:57
Why Don't You Write Me, Simon 2:45
Bye Bye Love, Bryant/Bryant 2:55
Song for the Asking, Simon 1:39
#####
Everly Brothers; Everly Brothers' Best, 1959
Bye Bye Love, Bryant/Bryant 2:26
Wake Up Little Susie, Bryant/Bryant 2:06
All I Have To Do Is Dream, Bryan 2:23
This Little Girl Of Mine, Charles 2:20
Brand New Heartache, Bryant/Bryant 2:19
Hey Doll Baby, Turner 2:09
Claudette, Orbison 2:10
#####
end
record
Abbey Road
Dot-com Blues
Rubber Soul (Original Uk Edition)
#####
list 1
find song Nowhere Man
list 2
find song Love Me Do
record
Everly Brothers' Best
Nashville Skyline
Abbey Road
#####
find author Starkey
find author Martin

% music.x <p7.in1

====================
Album Dot-com Blues not found!
Disc 1 recorded.

====================
Title:  Abbey Road
Artist: Beatles
Year:   1969
Songs:  Come Together
        Something
        Maxwell's Silver Hammer
        Oh! Darling
        Octopus's Garden
        I Want You (She's So Heavy)
        Here Comes The Sun
        Because
        You Never Give Me Your Money
        Sun King
        Mean Mr. Mustard
        Polythene Pam
        She Came In Through The Bathroom Window
        Golden Slumbers
        Carry That Weight
        The End
        Her Majesty
        
Title:  Rubber Soul (Original Uk Edition)
Artist: Beatles
Year:   1965
Songs:  Drive My Car
        Norwegian Wood (This Bird Has Flown)
        You Won't See Me
        Nowhere Man
        Think For Yourself
        The Word
        Michelle
        What Goes On
        Girl
        I'm Looking Through You
        In My Life
        Wait
        If I Needed Someone
        Run For Your Life

====================
Song "Nowhere Man" found in album "Rubber Soul (Original Uk Edition)" on disc 1.

====================
Disc 2 not found!

====================
Song "Love Me Do" not found on 1 discs.

====================
Disc 2 recorded.

====================
Author "Starkey" found for song "Octopus's Garden" on disc 1.
Author "Starkey" found for song "Octopus's Garden" on disc 2.

====================
Author "Martin" not found on 2 discs.

For this project, the primary input consists of the contents of the file shown above. This file will be posted in your instructor's class posting account- do not try to type it in yourself! The primary output consists of all the data values in the entire output shown above. Note that this primary input does not exercise a number of conditions discussed above which your program should work for in order to earn credit for the secondary inputs.