Homework II

Explanations about keys (PK / FK)

PK (primary key) – Unique field or a pair of fields in a table or a file that identifies a record (row in a file). Quite often an integer is used, but it can be any type that is unique. One file or table can only have a single primary key. Each file or table has to have a primary key.

FK (foreign key) – this is used to create relations to other tables or files. If a foreign key matches the primary key in another file or table, then these items are related to each other. One file or table can have multiple foreign keys and they’re not unique (can repeat within).

Foreign key and primary key form a relation between 2 or more files or database tables. A single primary key in one file can be related to multiple foreign items in the second file.

I.e. one person can have multiple children; one receipt can have multiple products; one student can have multiple subject declarations; One person can own multiple properties;

For homework II, you have to write a program based on the set requirements and document the work. The focus of this homework is implement dynamic memory allocation for data storage and writing a large, complex program.

Keep in mind, that this homework task is larger and more complex than any of the homework tasks before. Plan your time accordingly!

The task

Requirements for the program

The code must adhere to all of the best practices introduced during Programming 1 and Programming 2.

Your solution can include topics that have not been covered, as long as they are used correctly and well documented. You need to provide motivation why those concepts were used so that it clear, that you have mastered those topics.

Requirements for the standards and environment

The program must be written in the C programming language. You are permitted to use the C90 and C99 standards. Upon an agreement, you can also use newer standards such as C11,  C17 or C23.

In addition to using the standard C libraries, you are allowed to use C POSIX and GNU C libraries. Any libraries outside of this must be agreed upon separately.

Your program will be compiled and tested in a Linux environment, equivalent to the one in the lab computers (OpenSUSE SLED-15 SP5, using GCC-12) or the recommendation for home setup  (Ubuntu Linux 24.04, using GCC-13 compiler or later). The software does not need to be compatible with other operating systems such as Windows or MacOS.

General requirements for the solution

  • Code must be divided into more than a single file. Exact number of files is and their division left to the author of the solution.
    • Minimally it must be split into a header and a code file
    • If multiple .c files exist or code is divided between multiple directories, a Makefile must be provided for compilation
  • The data must be read from two separate files into memory
  • Default data file names should be coded into the program. You are allowed to use command line arguments, but they must not be necessary to execute your program.
  • Data must be kept in dynamically created data structures
    • You can use dynamic arrays, linked lists or trees
    • Allocation for the data structures must be dependent on the length of the input file
    • The amount of memory allocated must match what is required to keep the data in memory
    • Program must work with a variable amount of records – if we add or remove records from the files, it should still work
    • There must not be any arbitrary length limitation for the input files
    • Variable length arrays inside of the struct (i.e. strings) must be allocated dynamically to match exactly the required amount they take. Fixed length strings must be static
    • Buffers can be either statically or dynamically allocated, depending on how you are using them (fixed-length, dynamically expanding)
  • Structures used must be appropriate for the given task
    • At minimum, all information from the files should be stored in the structures
    • You can freely add members to the structure as needed
    • You can define additional structures to support your task as needed
    • If your solution contains time and/or date, you must either use a substructure (nested structure) to store it or pick an appropriate one from time.h  library
  • All actions by your program must be repeatable without exiting the program!
    • Create a menu to allow performing of the tasks
    • Each task in your variant makes for one menu option. You are allowed to add more
    • The result of each action is displayed on the screen
  • If a task requires you to modify, add or delete data, the modifications must be persistent (written to the data files used by the program). If the program is executed again, the user must see the updated data
  • Your program must include logging
    • Every action by the user must be logged
    • Log must also include non-visible actions such as starting of the program, successful reading of input file, etc.
    • Logs must include a date and a time. Each log entry is written on a separate line. All previous logs must be retained.
  • The program must provide basic user experience (UX)
    • The program must notify the user of any errors encountered in a clear manner. The message must be precise and helpful to the user to solve the issue. All error messages must be written to the stderr  standard stream.
    • When user input is expected, the prompt must be clear to the user. If the input needs to be in a specific format, you must provide the user with the expected format. If applicable, add an example of how the input should be written.
    • If the program contains searching, filtering or grouping features and there are no matches the set criteria, it must be written explicitly to the user.
  • No memory leaks, wasted or unreleased resources. All resources must be returned to the system by you before the program exits. Use valgrind to check.

Input data file requirements

  • In total, you must create and use two data files. Each data file must only contain the fields described in your task variant.
  • The data in the files is connected by a PK-FK (primary key – foreign key) key-pair
    • The entities are tied with a zero to many multiplicity (i.e. one student can declare multiple subjects; a student can also have no subjects declared)
  • Data model for the input files is created by the author of the solution based on their capabilities and knowledge. This includes data field delimiters, order of data fields, data field contents,  complexity,  etc. The chosen data model and the decisions for it are documented by the author in the document provided alongside the program.
  • The data records will be created by the author of the solution and submitted with the solution.
    • There must be at least 10 records the first file (containing only the primary key) and at least 15 records in the second file (containing the FK referring to the records in the first file).
    • If the author submits multiple sets of input files to demonstrate different capabilities of the program, the minimum data length limits are only applied to one of the sets.

Documentation template

Use the same templates as you used in Programming 1, Homework 1 (https://blue.pri.ee/ttu/programming-i/homework-i/) and adjust it to fit the requirements of this homework.

Documentation requirements

Focus on structured documentation!  Avoid story-telling (except summary).

  • Title page
  • Declaration of originality
  • List of abbreviations and terms (can be omitted if not present)
  • Table of contents
  • List of figures and tables (can be omitted if not present)
  • The task description (variant)
  • Detailed description of the solution (no walls of text!)
    • A brief description of what the program does.
    • Program workflow – In what order are things done? (Do not go into details! About half a page)
    • Document the structures (for each structure)
      • Purpose of the structure
      • For each member, their name, data type and description
    • Special situation / error handling
      • Description of issue
      • What’s the status of it – did you solve it, work around it, is it still present in the code
      • If it was mitigated, how did you mitigate it.
  • Data file structure
    • Structure of one record (data field order, separators between fields, separators between records
    • Data fields – name, data type, example of a value, meaning of data (semantics), any limitations (e.g. length, value range, illegal values)
    • Present a single data record from the file as an example.
  • Extra task (if you solved the extra task)
  • Summary
    • Write a few sentences about your approach to the task and progression during it
    • Write a few sentences about the task itself and the complexity of it
    • If possible, give an estimate on the workload
    • Would you recommend using this task in the future? Would you change anything about it and if so, what?
    • Additional comments, emotions, thoughts
  • References (can be omitted if not present)
  • Screen capture(s) of the program
    • Screenshots can be added as an appendix or embedded within the write up of the solution – in this case you can extend the length by the amount of pictures
    • The screenshots should show both normal operation and operation in various error situations

Extra task for bonus points

It is possible to earn up to 2 bonus points from the task. In order to get any points, you must include the added features to the report. It is possible to obtain partial bonus points if not all requirements are met.

To get bonus points, the following requirements must also be met in addition to the basic ones:

  • Code must be well structured. Makefile must be provided to compile the solution.
    • Code must be divided into multiple code and header files
    • You can’t have all the files left in the root directory of the project – some effort must be put into at least basic division of files into subdirectories
    • Makefile must use at least CFLAGS and CC variables. Set the compiler to be either gcc, gcc-12 or gcc-13
    • Makefile must be written in such a way that it would support recompilation of only modified source files
    • The rest of the complexity for the Makefile is up to the author
  • Logging must be created as an independent library
    • It must be designed as an independent library, contained within itself (no use of extern )!
    • It must support setting the name of the log file
    • It must support different logging levels, implemented as an enumerable type
    • It must support setting the logging level. Logs with lower priority than the set level are not logged.
    • All logging events must include the logging level.
    • All state variables (log file name, logging level, …) for the library must be stored within the library. You are not allowed to directly access the variables from your main project, but instead must use the functions implemented in the logging library.
  • Program must be able to work with text fields containing multiple words
  • Files must use a comma or a semicolon as a separator between fields (CSV: https://en.wikipedia.org/wiki/Comma-separated_values)
  • Good structure, optimal use of code, fast algorithms, error proofing.
  • No memory leaks (http://valgrind.org/). Include proof in the report.
  • You must add a level 1 heading to the documentation called “Extra task”, that describes the features added and modified for the extra task.

Deadlines

A complete homework must be submitted no later than 27.04.2025

Each week passed the homework deadline will deduct 1 point from the final homework score. The late penalty is capped at 5 points, meaning if you submit 7 weeks late, you will still lose 5 points..

If we have questions about the submitted homework or are not sure about the original author of this work, we will grade this with 0p. In this case, the work must be defended.

If it becomes necessary, we will enforce the rules and guidelines of [Procedure for processing a student’s violation of academic practices and contemptible behavior in the School of Information Technologies]

We will only accept Your homework until the lockdown date (check introduction slides). Past that, submitting your homework will not be possible.

Submitting Your work

The homework needs to be submitted in the Moodle course under Homework 2.

Files required:

  • Documentation (pdf)
  • All of the code files (.c and .h)
  • Data files required to run the program
  • If you have more than one code file, include a Makefile for compiling
  • Files can be uploaded as a .zip. If you choose to do so, then
    • Remove all unnecessary files (binaries, object files, project configuration files for complex IDEs etc.)
    • Documentation (pdf) must be submitted as as separate file and not be in the archive!

Naming schema: HW2_<last_name>[_filename]

Note: If you upload as a zip, the naming schema only applies to the files uploaded to Moodle, but not the contents of the archive.

Example (separate files):

HW2_Smith.c
HW2_Smith.h
HW2_Smith_documentation.pdf
HW2_Smith_data_students.txt
HW2_Smith_data_grades.txt

Example (archive):

HW2_Smith_project.zip
HW2_Smith_documentation.pdf

NB! If you renamed your files just before submitting, make sure your program still compiles and executes!

Result and feedback

After your work has been checked and graded, you will see the result and feedback on Moodle (visible from your gradebook only!). If everything was well done, feedback may be absent.

Fixing your homework

You are allowed to fix and improve your homework score until the date of homework lockdown. All fixed submissions are subject to defense.

To fix your homework, first go through your feedback. Then contact your teacher and agree upon the process of how this homework can be fixed.

NB! If fixing the homework changes more than half of the original homework, it is considered as submitting a completely new homework, from which minus points can be deducted from depending on the time of submission.