Turnin is a program which students use to hand in their homework assignments for a class via the Unix command line. The instructor has to make certain preparations for the use of turnin, so don't try to use it unless the instructor says to. Turnin works by copying a file into a special directory in the class umbrella. The directory is under the control of the instructor or TA. Assignment deadlines may be enforced.
Turnin works well in situations where students only need to hand in one file per assignment. In more complex situations, for example where students are required to hand in a a set of files or a directory hierarchy, there is an instructor configurable utility called "bundle" which acts as a front-end to turnin.
The usage for turnin is designed to be flexible. The syntax for simple, direct use of turnin is:
turnin [-c courseid] [file]
The courseid is a code (like cs181w) which identifies the course for which the file is being turned in. The courseid can easily be determined using the allocations command.
allocations
This will report the course allocations associated with your account. OCE accounts typically will have more than one course allocation, but it should be easy to pick out the courseids for each class. The courseid used for the turnin command is the same courseid that you would use when doing the prep command for an OCE compatible class. In fact, if you have done a prep command and you do not specify a courseid to turnin, turnin will ask you if the prep'd class is the one to which you want to submit your homework file. For more information about courseid's and the prep command, see the article under "help prep".
CAUTION: it is not possible to submit a set of homework files by running turnin once for each file. Each successive run of turnin overwrites what was previously turned in. This can be useful if you turnin an assignment and later wish to replace that submission with something better.
The recommended approach to submitting multiple files or directories involves using the "bundle" mechanism described in the online "help bundle" articles. Bundle requires additional set-up by the instructor. Another alternative is to use the tar command in conjucntion with turnin. This requires less set-up by the instructor, but is more complex for students. The use of tar in conjunction with turnin is demonstrated in one of the examples below.
Depending on the circumstances there are various ways to run turnin. Three examples with explanations will be given below.
Example 1: Using turnin after having done prep for the class
Usage: turnin file
Example: turnin hwk1.c
When you do prep for an OCE compatible class, one of the side-effects is that the courseid is stored in the shell environment variable PREPLABEL. Turnin is clever enoungh to take advantage of that, so if you have done prep for the class, you can run turnin without specifying the courseid. You simply identify the file you want to turnin as shown in the example above.
Example 2:
Usage: turnin -c courseid file
Example: turnin -c cs161f hwk1.c
You can explicitly specify a courseid by using the -c option. This method can be used regardless of whether you have run the prep command. It is appropriate for classes which are not on the OCE model.
Example 3: Using tar with turnin to handle multiple files
As mentioned above, if the material to be turned in for an assignment consists of multiple files or directories the recommended approach is to use the "bundle" mechanism (which must be set-up by the instructor). Another alternative is to use tar in conjunction with turnin. In this case tar packages the files and directories into a single file called a tar archive which turnin can handle.
Usage: tar-command | turnin -c courseid
Example: tar cvf - hw1.dir | turnin -c cs163w
In this example hw1.dir is a directory that contains multiple files and possibly sub-directories. Tar packages the whole hw1.dir directory hierarchy into a archive and that archive is passed via a Unix pipe to turnin. Notice that when turnin receives its input in this way (via stdin in Unix parlance) the courseid MUST be specified using the -c option. That is because turnin is prevented from asking the user to confirm a courseid determined from the prep PREPLABEL setting.
For more information about the tar program see "man tar".
Again, if the user has already turned in a file and is attempting to do so again, turnin will verify with the user that s/he wishes to overwrite the previous turnin (unless turnin is being run non-interactively -- as in the last example -- in which case the overwrite is automatic). In other words, turnin will accept only one file at a time and all subsequent turnins will overwrite previous ones. This is why "tar" is required for multi-file turnins.
There are two steps which are explained in further detail below.
The disk space quota for the instructor's account must be sufficiently large to accomodate ALL of the turned-in files. When turned in, the resulting files will be owned by the instructor account. Therefore, they will count against the quota for that account. If you have questions about quotas or need to request additional space, please contact the Account Services Office.
In order to allow your students to use the "turnin" program to hand in homework assignments, you will need to create the destination directory. This directory should be called "turnin.dest" and must exist in the class directory umbrella, and must be owned by the instructor's account (not a TA account). To create the directory, you should log into the instructor's account and issue the following commands:
cd ~/..
mkdir turnin.dest
chmod o-rwx turnin.dest
The first command puts you at the root level of the umbrella. The second creates the turnin.dest directory. Finally, the third command ensures that the directory is not accessible by anyone except the instructor and the TA accounts. This prevents students from accessing files turned in by other students. Again, the turnin.dest directory must be owned and writeable by the instructor's account. The ownership and permissions are verified by the turnin program.
Once the directory has been created, students may begin to use the "turnin" program to hand in assignments. The material submitted by each student will be placed in a file in turnin.dest. The file is named after the student's account.
As described in the information for students, turnin only stores one file per student. It is recommended that instructors setup the "bundle" mechanism in cases where a multifile capability is required. Alternatively, but with more complexity for students, they can use tar to create a tar archive and submit that with turnin.
Tar archives submitted by students may be examined using the "tv" options:
tar tvf jsmith
Before unpacking a tar archive it probably would be wise to create an empty directory and unpack the archive there to avoid name conflicts with files from other students.
mkdir from.jsmith
mv jsmith from.jsmith
cd from.jsmith
tar xvf jsmith
The sequence shown above creates a new directory "from.jsmith"; moves the "jsmith" tar archive into the new directory; does a change directory (cd) to the new directory; unpacks the archive (actually extracts copies of the contents leaving the archive intact).
Some classes require that an assignment be handed in by a specific time after which homework is not accepted. The deadline can be rigidly enforced by simply renaming the turnin.dest directory to something else at the deadline. Since "turnin" won't be able to find the turnin.dest directory, files cannot be handed in.
To rename the directory to, say, "hwk1-files", use the "mv" command as follows:
cd ~/..
mv turnin.dest hwk1-files
The directory will be renamed to "hwk1-files" and students will be unable to turn in assignments.
If it is inconvenient to be logged on at the time of the deadline, use of the "at" command can allow you to rename the directory at the specified time even if you are not around to do it. Here's an example.
Let's say the deadline is Friday, January 25, at 9:00pm. You can use the "at" command to rename the turnin.dest directory to something else at exactly that moment.
cd ~/..
at 9pm jan 25
"at" will then prompt for the commands to be executed until you press CTRL-D. So, to rename the directory, continue by typing
mv turnin.dest hkw4-files
<CTRL-D>
This will set up a job that will be run at exactly 9:00pm on January 25 to rename the turnin.dest directory. See man at for more information about the format and usage of the "at" command.
An alternative to enforcing a rigid deadline by changing the directory name is simply to look at the timestamp on the turned-in file. If the date on the file is prior to the dealine, then the user was able to turn in their assignment before the deadline. It is not possible for the student to change the date on the turnin file.
Turnin command line options (and running silently)
The following two options are designed to support the "bundle" utility; they are not intended for direct use by students. The bundle Perl script illustrates how these options are employed.
See "man turnin" for details about the format of project configuration files.
If the student already has a file in the turnin.dest directory, turnin normally will ask the student to confirm before overwriting the previously turned in file. If turnin is reading the assignment file from a pipe, then the request for confirmation is suppressed. This can be used to advantage in scripted applications of turnin where you do not want the student to be asked questions.
cat homework2 | turnin -c ec170f
If you also want to suppress turnin messages, use:
cat homework2 | turnin -c ec170f > /dev/null
While the error messages returned by turnin are generally descriptive enough to figure out what went wrong, some may need some further expanation. IMMEDIATELY after running turnin, type
echo $status
and match the number printed with the number in the left column here.
These error messages are numbered in chronological order -- that is, error 22 will occur later than error 21 would have. This may be useful for determining how far into the program the user got before it crashed.
Additionally, the error codes are grouped by severity: 0-19 represent general usage errors; 20-49 represent errors which likely point to incorrect "turnin" setup; and those above 50 represent internal errors which should be reported to ACMS.
If the "REQUIREPROJECTCONFIG" option has been set within the master CONFIG file, confirm that a CONFIG.<projname> file exists which corresponds to the supplied project name.
Note that project names are case-sensitive: "p1" and "P1" are considered to be different projects.