Latest news 2024-10-15: New blog post: Tales for Our Times Book Launch.

PASS FAQ

General

🔗 PASS helps to prepare your assignment source code into a PDF that contains all the information required for submission. It’s your responsibility to check that the PDF accurately represents your work, and it’s your responsibility to submit the PDF via the method indicated in your assignment brief.

There are several applications that use the PASS library (written in Java) including:

  • PASS GUI: this has a graphical user interface and is installed on the lab computers.
  • PASS CLI: this is a command line program that can be used as an alternative to PASS GUI on devices that don’t support a graphical interface.
  • Server PASS: this is a modified version of PASS CLI designed to run inside a Docker image on a server.
The PASS library is used by the above applications to perform the following:
  1. Look up the assignment specifications provided by your lecturer in an XML file. This data includes:
    • the assignment title;
    • a short tag identifying the assignment;
    • the submission date;
    • whether or not PASS should test your code by compiling (if appropriate) and running it;
    • (optionally) any source code files that you are required to submit (identifying the main file, if appropriate) and the order in which those files should be listed in the PDF (“required files”);
    • (optionally) the base name of any reports (PDF or Word) that should accompany your submission (“reports”);
    • (optionally) content to be passed to STDIN for your code to read (“input”);
    • (optionally) the URL of any accompanying files that your code needs to read (“resource files”);
    • (optionally) the names of any files that your code needs to create (“result files”);
    • (optionally) any flags that must be passed to the compiler;
    • (optionally) the URL of a custom build script to be used to compile and run your source code in order to test it (instead of PASS's default compile and run methods).
  2. Copy all your supplied source code files to a temporary directory. (That is, the required files and any additional files you have provided.)
  3. Create a zip file containing all your source code.
  4. Fetch any accompanying resource files or build script from the URLs provided by your lecturer.
  5. (Optionally) compile and run your source code (or run the build script) and capture any messages written to STDERR and STDOUT.
  6. Create a PDF containing your Blackboard ID and registration number, your source code listings, and the results of the testing (compile and run stage). The zip file and any reports or result files are added as attachments. This should be all the information required for submitting your work.

If you use PASS GUI in the lab, they are processed while the application is running using the compiler installed on the lab computer. Once successfully completed, you can save the PDF to your preferred location. You should then check the PDF and submit it, if it’s correct, or fix any problems and reprocess your project files (you will need to restart PASS GUI).

When you upload your project files via the Server PASS website, they are saved in an upload directory and the job details are queued. There is a backend script running on the server that pops the job details off the queue and starts up a Docker container that processes your files using the version of Server PASS installed in that Docker image. The script logs the exit code and sends you an email. You can then download the PDF (if one was successfully created) from the “My Uploads” page. You should then check the PDF and submit it, if it’s correct, or fix any problems and re-upload your project files.

🔗 There are a number of reasons why this can happen:
  1. You haven’t supplied one or more required files. Check that you have named them correctly (including case).
  2. You have forgotten to include some additional code files or you didn’t specify the correct file type (for example, if you had the selector set to “Plain Text” instead of “Java” for a Java project).
  3. You forgot to specify that the relative directory structure must be preserved if your project has source code files in multiple subdirectories.
  4. You have used some platform-specific code that works on your device but doesn’t work on the device PASS is running on. This includes hard-coding an absolute path or directory divider when referencing a file or assuming a specific newline marker.
  5. You may have a subtle bug that only has a noticeable effect under certain conditions.
  6. Your application takes a long time to run and the process timed-out.
  7. You haven’t set the appropriate compiler flags in your IDE. For example, your assignment brief may stipulate that your C code must be ANSI compliant. In order to ensure this, your lecturer may instruct PASS to add the -ansi or -std=c89 flag to the C compiler. If you haven’t also set this flag on your IDE, your project may be using non-compliant code but your IDE isn’t alerting you to it, so your code will work in your IDE but not with PASS.
  8. You have used syntax from a newer version of the language that isn’t supported by the compiler version used by PASS. If you have been instructed to conform to a particular version (for example, Java 11) then you shouldn’t use syntax introduced in a newer version.

Remember that you will lose marks if you don’t follow the assignment brief. PASS isn’t a compiler. It simply spawns a sub-process that runs the appropriate compiler (for example, gcc or javac). The compiler flags are set to alert you to problems that may lose you marks. This means that you have the opportunity to fix your code before you submit it.

Other things that can make PASS fail:

  1. The assignment provides a resource file (such as a CSV file) that your code should read but your local copy has become corrupted. PASS fetches a fresh copy from a remote source. If your code is designed to work on the corrupted copy it may fail on the correct version. For example, when you downloaded the file and opened it on your device, the line endings may have silently been changed. Another possibility is that the remote file that PASS fetches is slightly different from the one you were supplied with. For example, the rows of a CSV file may be in a different order. This is done to test that your solution works in the general case and hasn’t been hard-coded for very specific content. (Remember that in real-world applications, data files are often changed as information is added, removed or edited.)
  2. You tried to send PASS a forbidden file. This includes your local copy of a resource file (which PASS expects to download from its remote location) or result files (which PASS expects your application to create).
  3. You tried to send PASS a binary file misidentified as source code or plain text. The only binary files that you can send to PASS are PDF or Word documents (for example, as an accompanying report). If you get errors in the form “Control character U+hex detected” or “Keyboard character used is undefined” then this is the most likely cause. This can also happen if you misidentify the file encoding. For example, you indicated that the source code is ASCII or UTF-8 when it’s actually Latin 1. Check the file encoding settings in your IDE.
🔗 You can upload text files that contain your source code, but don’t include any text files (such as CSV files) that you have been provided with that your project needs to read.

PASS is designed to produce a PDF containing source code listings, with the source code also provided in a zip attachment. Source code should be in plain text files with the encoding set to one of: ASCII, Latin 1 (ISO-8859-1) or UTF-8.

Your assignment specification may require a set of files with specific names (case-sensitive). If so, make sure that you have followed the requirements.

You may also include a report as either a PDF (.pdf) or Word (.doc or .docx) file. This will be attached to the PDF created by PASS. If the report is a PDF file then it will also be incorporated into the document (so that it can be viewed without downloading the attachment). It’s therefore better to supply a PDF rather than a Word file. (You can export to PDF from Word.)

PASS does not permit any other type of binary file to be uploaded (such as PNG or JPEG). If you are unsure of the difference between binary files, text files and file encodings, see the article Binary Files, Text Files and File Encodings.

🔗 When you upload your project files on this site, there is an encoding selector which gives you a choice of ASCII, Latin 1 or UTF-8. This should be set to the appropriate encoding. If you set it incorrectly, some characters may appear incorrect in the PDF (or not appear at all) and it will trigger warnings and error messages.

Computers internally store characters (such as a or $) as numbers (or, more specifically, as binary information). The encoding specifies the mapping between a number (as a byte or sequence of bytes) and the corresponding character. For example, the binary value 01001110 (78 in decimal) represents the Latin capital N and 01101110 (110 in decimal) represents the Latin small n. Computer programmers commonly use hexadecimal values. For example, 0x4E for Latin capital N and 0x6E for Latin small n.

ASCII (or, more strictly, US-ASCII) provides mappings for 128 characters, ranging from 0x0 (the null character) to 0x7F (the delete character). Anything outside this range is invalid. The characters from 0x0 to 0x20 and the final character 0x7F are non-printable characters (control codes) that include the horizontal tab (0x9), line feed (0xA), form feed (0xC), carriage return (0xD) and the space character (0x20).

The codes from 0x21 to 0x2F represent the following punctuation characters: ! (exclamation mark), " (straight quote), # (hash), $ (dollar), % (percent), & (ampersand), ' (straight apostrophe), ( (left parenthesis), ) (right parenthesis), * (asterisk), + (plus), , (comma), - (hyphen-minus), . (full stop or period), / (solidus or forward slash).

The codes from 0x30 to 0x40 start with the decimal digits: 0 to 9 then : (colon), ; (semi-colon), < (less than), = (equals), > (greater than), ? (question mark), @ (at).

The codes from 0x41 to 0x5A represent the Latin capitals A to Z. These are followed by [ (left square bracket), \ (backslash), ] (right square bracket), ^ (circumflex), _ (underscore), ` (grave or backtick).

The codes from 0x61 to 0x7A represent the Latin lower case a to z. (So you can obtain the lower case by simply adding 0x20 to the corresponding capital.) Then follows: { (left curly bracket), | (vertical line or pipe), } (right curly bracket) and ~ (tilde).

Note that ASCII doesn’t include accented characters (such as é), other currency symbols (such as £), long dashes (such as —), or “smart quotes”. (Some fonts may render the straight quote " and straight apostrophe ' with a curl so they have the appearance of smart closing quotes but they are different characters.)

ASCII is a very limited set of characters but it forms the subset of many encodings so it’s the most portable. Only select ASCII if you’re sure that you have no non-ASCII characters in your code or written to STDOUT/STDERR. For example, suppose your (Java) code contains: 

System.out.println("\u00A3");
then this source code only contains ASCII but a non-ASCII character will be written to STDOUT. In this case, select UTF-8 not ASCII.

Latin 1 (or ISO-8859-1) has mappings ranging from 0x0 to 0xFF. As with ASCII, every character is represented by a single byte. The first 128 characters are identical to ASCII. The range 0x80 to 0x9F aren’t printable. The remaining characters from 0xA0 to 0xFF consists of additional punctuation and symbols (such as £) and extended Latin characters (such as é and ø). This doesn’t include characters such as “smart quotes”, long dashes or emoticons and doesn’t include any non-Latin alphabets.

UTF-8 is a variable-width character encoding using one to four one-byte code units that identify the Unicode codepoint and covers all Unicode characters. The first 128 characters are identical to ASCII, with each character identified by a single byte. Outside of that range, characters are identified by multiple bytes.

For example, the hash character # is represented by a single byte 00100011 with all three types of encoding (ASCII, Latin 1 and UTF-8). Whereas the character £ can’t be represented in ASCII, but is represented in Latin 1 with the single byte 10100011 (0xA3) and is represented in UTF-8 with two bytes 11000010 (0xC2) and 10100011 (0xA3). So if you misidentify a UTF-8 file as Latin 1, those two bytes will be treated as two separate characters (Â and £) instead of as a single character (£). If you misidentify the file as ASCII then both bytes are invalid, as they are both outside the valid range (> 0x7F).

So if you selected ASCII or Latin 1 and any non-ASCII character appears as two or more characters (such as “£” instead of “£”) then you should’ve chosen UTF-8.

UTF-8 is by far the most common encoding on the web and if you have any non-ASCII characters this is the best encoding to use. There are many other encodings, such as UTF-16, but these aren’t supported by PASS. As a general rule of thumb, choose UTF-8 but make sure that your IDE is set to UTF-8.

Error Messages

🔗 A Java project must have the main file identified in the assignment XML file. Check that you have supplied all the required files and that they match the required names (case-sensitive).
🔗 You have identified a file (filename) as Java source code, but it doesn’t end with the extension .java (case-sensitive).
🔗 You have either supplied a binary file identified as source code/plain text or you have identified the wrong file encoding. For example, you have told PASS that the file is UTF-8 when it’s actually Latin 1.

Alternatively, it may mean that your application writes binary content to STDOUT, which can’t be rendered in the PDF.

🔗 This error indicates that a file contains the Unicode character U+FEFF (typically right at the start of the file). The Java compiler doesn’t allow the byte order mark (BOM) even with the -encoding utf8 setting. This character is invisible but must be deleted in order for the source code to compile. Unfortunately some text editors automatically silently insert this character. The purpose of the BOM is to indicate endianness for UTF-16. It has no meaning for UTF-8.
🔗 You have either supplied a binary file identified as source code/plain text or you have identified the wrong file encoding. For example, you have told PASS that the file is ASCII when it’s actually UTF-8 or Latin 1.

Alternatively, it may mean that you have specified ASCII but your application writes non-ASCII content to STDOUT.

🔗 You have either supplied a binary file identified as source code/plain text or you have identified the wrong file encoding. For example, you have told PASS that the file is ASCII or UTF-8 when it’s actually Latin 1.

Alternatively, it may mean that your application writes binary content to STDOUT, which can’t be rendered in the PDF.

🔗 You have either supplied a binary file identified as source code/plain text or you have identified the wrong file encoding. For example, you have told PASS that the file is UTF-8 when it’s actually Latin 1.

Alternatively, it may mean that your application writes binary content to STDOUT, which can’t be rendered in the PDF.

🔗 This exception is thrown when an input bytes sequence isn’t legal for the given charset, so it most likely means that you have misidentified the file encoding or you supplied a binary file as source code/plain text. For example, you have told PASS that the file is UTF-8 when it’s actually Latin 1.

Alternatively, it may mean that your application writes binary content to STDOUT, which can’t be rendered in the PDF.

🔗 You have accidentally uploaded the same file multiple times (in the same upload job). Alternatively, you have uploaded multiple files with the same name and haven’t supplied their relative paths.
🔗 To prevent excessively large PDF files, PASS will truncate content. You may encounter this if you have a particularly verbose application that writes vast amounts of information to STDOUT.
🔗 You didn’t upload any files.
🔗 It may be that the assignment XML file has been changed since you logged in. If you are using Server PASS, try logging out and log back into the site to clear the session data.