Installation Instructions

Installation Instructions

Part 1 - Server Setup

Preparing the Server

Before you can use the Princeton Plan-O-Matic, you will need to set up the server with the necessary features this software requires. The requirements are as follows:

You will need to find installation instructions for these services somewhere else, as they are too large to fit into this document. Once you have all of these features enabled, installation of the software is easy.

Installing the Source Code

  1. Download the source files from our website.
  2. Extract the source files, making sure that the entire directory tree of the archive is preserved.
  3. You will need to compile the Report Generator, which is located in the ./repgen/ directory. This should compile on a Linux system with no errors using the provided makefile.
  4. Update the hostname in ./db/dbsetup.php to the hostname (or, preferably, IP address, to avoid the need for DNS lookups) of your MySQL server, along with your write-access username and password.
  5. Set permissions: all .php files except for those in the ./admin/ subdirectory need to be executable by everyone. Everything in the ./gui/ directory should be accessible via read access to everyone. However, you will most likely want to restrict read access to ./db/dbsetup.php and the ./admin/ subdirectory, to prevente unauthorized users from reading the MySQL login information which is stored in those files.
At this point, you will have a working setup of the Plan-O-Matic--login.php should display correctly--but you won't have any data in your database and so will be unable to login to the system. Continue on to the next section.

Part 2 - Database Setup

Control Script

This script is used by an administrator to create a new database or update the old one after changing the manually entered pursuit specifications. It is also intended to be run automatically every day so that updated course data is downloaded and imported from the Registrar. In production use, this is the only back-end script that an administrator needs to be concerned with.

Usage: control <dbhost> <dbuser> <dbpasswd> <dbname> [<regwebURL> | --create]

Connect to the MySQL using the specified host name, user name and password. If the --create option is set, create a new database with the specified name. If a database of the specified name already exists, a new one of that name cannot be created without deleting the old one first. If an URL was specified, pass it to the Download Script in order to download new copies of the Registrar's course data. (This URL is http://reg-web.princeton.edu/.) If the --create option was not set, invoke the Import Script to convert the course data into the corresponding textfiles. The update scripts are then run to update the data in the database.

Part 3 - Administration

Prerequisite Expressions

Course prerequisites and program requirements are described by so-called prerequisite expressions. When a user adds a course or program, called pursuits, to a semester in his or her schedule, he or she automatically satisfies any fulfilled requirements associated with that pursuit by the end of that semester. Pursuits satisfy requirements by being members of groups. Each group has a descriptive title such as "COS 126" or "Historical Analysis", in addition to an internally used group code such as "cos126" or "genHA". Prerequisite expressions are written in terms of the latter group codes. For a more thorough discussion of pursuits, groups, schedules, semesters, and group code naming conventions, see Internals.

Operators and Grammar

A prerequisite expression is a text string containing group codes connected by operators in various ways. White space is ignored except for separating the individual parts of the expression. There are only a few different operators and usages, defined below. In the following, Ei denotes a subexpression, n denotes an integer literal of one or more, and s denotes an integer literal of zero or more to represent a semester number. Operators are listed in order of increasing precedence. In the following list "satisfied if" is taken to mean "satisfied if and only if".

  1. $ ("by semester")
    "E $ s" evaluates to E at the end of semester s (how many times the group was satisfied by pursuits scheduled in or before that semester). The word "same" may be substituted for s to indicate the current semester; in this case E will be a corequisite.
  2. ; ("and")
    Same as &, see below. The ; operator has a lower precedence than &, but is otherwise equivalent.
  3. | ("or")
    "E1 | E2" is satisfied once if either E1 or E2 (or both) are satisfied at least once.
  4. & ("and")
    "E1 & E2" is satisfied once if both E1 and E2 are satisfied at least once.
  5. @ ("at least from")
    "n @ (E1, E2, ..., EN)" is satisfied if the total number of times the expressions E1...N have been satisfied is more than or equal to n.
  6. % ("at most from")
    "n % (E1, E2, ..., EN)" is satisfied as many times as the total number of times the expressions E1...N have been satisfied, but not more than n times.

Operator precedence may be overridden with parentheses. Line breaks are ignored. The # character denotes that the rest of the line is to be ignored as a comment.

Examples of Prerequisite Expressions

Some currently problematic constraints



Interestingly, the inclusion of a not-type operator would make it formally possible to describe every possible constraint (given unlimited expression size!), since any constraint could be described in a canonical form, similar to that of boolean expressions. In practical applications, however, students are seldom penalized for fulfilling specific requirements, and hence the small set of existing operators work well to specify the vast majority of possible constraints. The exception, of course, is in examples like the above, and since exceptions exist everywhere, more language features are needed before prerequisite expressions may cover all practically encountered constraints.

Requirements Files

The Requirements Files contain information about the degrees, majors and certificate programs. The data is stored in files with the extension .req. They should be stored in the admin/Requirements folder. Only one pursuit per file should be defined but more than one associated group can be defined

Format


		Code "Title" {
			PrEx
			}	

where the Code is the code given to the major (e.g. cosMajor), Title is the title of the major (in English) and PrEx is the prerequiste expression string associated with that pursuit. The naming conventions for group codes should be followed.
'#' can be used for commenting within the PrEx. The Title should be enclosed within double quotations and PrEx within '{' and ')'.

Groups related to the pursuit can be specified either in the same file or a different one. It is indicated by the 'group' keyword.


		group Code "Title" {
			courseA	courseB ..
			}
		

Code and Title are the same as above. All the courses that are part of a certain group are listed by their course codes (or by other group codes) within the curly brackets and are white-space delimited. Comments cannot be used here. An example of this is:


		group cosTheory "COS Theory Courses" {
			cos341 cos342
			cos423 cos433 cos441 cos451 cos487 cos345
			}