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:

• Apache Webserver, with OpenSSL support enabled for secure transactions.
• PHP, version 5 or greater
• MySQL, version 5 or greater, with an account capable of creating and maintaing new schemas and tables
• A UNIX environment for running the admin scripts. This does not have to be on the server, but it must have network access to the MySQL server.

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.

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

• "phy103 & phy104 & mat203 $ same":
  PHY 103 and PHY 104 are prerequisites, MAT 203 is a corequisite.
• "3 @ genHA & 5 @ (genST, genSTX)":
  Three HA courses, and five ST or STX courses.
• "3 @ (1 % genHA, 1 % genST, 1 % genEC, 1 % genSA)":
  Three courses distributed among four distribution areas (no more than one course from each area may count towards the total of three).
• The following

  cos126 | mat399;
  cos217;
  cos226;
  	

  is equivalent to "(cos126 | mat399) & cos217 & cos226" (note the weak precedence of the ; operator as opposed to that of &).

Some currently problematic constraints

• The following corresponds to the "Areas of Concentration" clause of the Chemical Engineering Major (60% down the page):

  (3 @ cheGrAaa) & (2 @ (          cheGrBbb, cheGrCcc, cheGrDdd, cheGrEee, cheGrFff)) |
  (3 @ cheGrBbb) & (2 @ (cheGrAaa,           cheGrCcc, cheGrDdd, cheGrEee, cheGrFff)) |
  (3 @ cheGrCcc) & (2 @ (cheGrAaa, cheGrBbb,           cheGrDdd, cheGrEee, cheGrFff)) |
  (3 @ cheGrDdd) & (2 @ (cheGrAaa, cheGrBbb, cheGrCcc,           cheGrEee, cheGrFff)) |
  (3 @ cheGrEee) & (2 @ (cheGrAaa, cheGrBbb, cheGrCcc, cheGrDdd,           cheGrFff)) |
  (3 @ cheGrFff) & (2 @ (cheGrAaa, cheGrBbb, cheGrCcc, cheGrDdd, cheGrEee          ))
  

  Where the cheGrXxx groups are used to count courses in each of the six possible areas of concentration. The requirement is fully describable, but the size of the expression is quadratic with the number of concentrations. A better method for specifying these kinds of constraints is needed, and will be added if the software is to be used in a production setting in the future. One approach would be to add another and-type operator, say &&, which would allow each group code in the subexpressions to the left and right to be counted in only one of the expressions. The expression above, and similar ones, would then simplify to:

  3 @ (cheGrAaa, cheGrBbb, cheGrCcc, cheGrDdd, cheGrEee, cheGrFff) &&
  2 @ (cheGrAaa, cheGrBbb, cheGrCcc, cheGrDdd, cheGrEee, cheGrFff)
  

  ...but the algorithm for evaluating this would not be trivial. There is also the issue of how such a constraint would be displayed to the user.
• "2 @ (chm303, eco313, mol437, (1 % (mus312, mus324) & !cos325))":
  Two of the specified courses may count towards something, but you can count at most one of the music courses, and you cannot count the music courses if you took cos325 (example from the Computer Science Major, halfway down the page). The ! operator is not implemented in the current version of the software, because there might be better ways to describe the same constraint once a language construct is added for better handling the case mentioned in the previous example. If not, though, the ! operator is trivial to implement.

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
			}