--- loncom/homework/grades.pm	2009/11/21 16:41:41	1.581
+++ loncom/homework/grades.pm	2009/12/15 18:26:18	1.584
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # The LON-CAPA Grading handler
 #
-# $Id: grades.pm,v 1.581 2009/11/21 16:41:41 www Exp $
+# $Id: grades.pm,v 1.584 2009/12/15 18:26:18 bisitz Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -97,9 +97,15 @@ sub ssi_print_error {
 #
 # --- Retrieve the parts from the metadata file.---
 sub getpartlist {
-    my ($symb) = @_;
+    my ($symb,$errorref) = @_;
 
     my $navmap   = Apache::lonnavmaps::navmap->new();
+    unless (ref($navmap)) {
+        if (ref($errorref)) { 
+            $$errorref = 'navmap';
+            return;
+        }
+    }
     my $res      = $navmap->getBySymb($symb);
     my $partlist = $res->parts();
     my $url      = $res->src();
@@ -144,9 +150,15 @@ sub nameUserString {
 #--- Get the partlist and the response type for a given problem. ---
 #--- Indicate if a response type is coded handgraded or not. ---
 sub response_type {
-    my ($symb) = shift;
+    my ($symb,$response_error) = @_;
 
     my $navmap = Apache::lonnavmaps::navmap->new();
+    unless (ref($navmap)) {
+        if (ref($response_error)) {
+            $$response_error = 1;
+        }
+        return;
+    }
     my $res = $navmap->getBySymb($symb);
     my $partlist = $res->parts();
     my %vPart = 
@@ -194,37 +206,49 @@ sub get_display_part {
 #--- Show resource title
 #--- and parts and response type
 sub showResourceInfo {
-    my ($symb,$probTitle,$checkboxes) = @_;
-    my $col=3;
-    if ($checkboxes) { $col=4; }
+    my ($symb,$probTitle,$checkboxes,$res_error) = @_;
     my $result = '<h3>'.&mt('Current Resource').': '.$probTitle.'</h3>'."\n";
-    $result .='<table border="0">';
-    my ($partlist,$handgrade,$responseType) = &response_type($symb);
+    my ($partlist,$handgrade,$responseType) = &response_type($symb,$res_error);
+    if (ref($res_error)) {
+        if ($$res_error) {
+            return;
+        }
+    }
+    $result.=&Apache::loncommon::start_data_table()
+            .&Apache::loncommon::start_data_table_header_row();
+    if ($checkboxes) {
+        $result.='<th>&nbsp;</th>';
+    }
+    $result.='<th>'.&mt('Problem Part').'</th>'
+            .'<th>'.&mt('Res. ID').'</th>'
+            .'<th>'.&mt('Type').'</th>'
+            .&Apache::loncommon::end_data_table_header_row();
     my %resptype = ();
     my $hdgrade='no';
     my %partsseen;
     foreach my $partID (sort(keys(%$responseType))) {
-	foreach my $resID (sort(keys(%{ $responseType->{$partID} }))) {
-	    my $handgrade=$$handgrade{$partID.'_'.$resID};
-	    my $responsetype = $responseType->{$partID}->{$resID};
-	    $hdgrade = $handgrade if ($handgrade eq 'yes');
-	    $result.='<tr>';
-	    if ($checkboxes) {
-		if (exists($partsseen{$partID})) {
-		    $result.="<td>&nbsp;</td>";
-		} else {
-		    $result.="<td><input type='checkbox' name='vPart' value='$partID' checked='checked' /></td>";
-		}
-		$partsseen{$partID}=1;
-	    }
-	    my $display_part=&get_display_part($partID,$symb);
-            $result.='<td><b>'.&mt('Part: [_1]',$display_part).'</b>'.
-                ' <span class="LC_internal_info">'.$resID.'</span></td>'.
-                '<td><b>'.&mt('Type: [_1]',$responsetype).'</b></td></tr>';
-#	    '<td>'.&mt('<b>Handgrade: </b>[_1]',$handgrade).'</td></tr>';
-	}
+        foreach my $resID (sort(keys(%{ $responseType->{$partID} }))) {
+            my $handgrade=$$handgrade{$partID.'_'.$resID};
+            my $responsetype = $responseType->{$partID}->{$resID};
+            $hdgrade = $handgrade if ($handgrade eq 'yes');
+            $result.=&Apache::loncommon::start_data_table_row();
+            if ($checkboxes) {
+                if (exists($partsseen{$partID})) {
+                    $result.="<td>&nbsp;</td>";
+                } else {
+                    $result.="<td><input type='checkbox' name='vPart' value='$partID' checked='checked' /></td>";
+                }
+                $partsseen{$partID}=1;
+            }
+            my $display_part=&get_display_part($partID,$symb);
+            $result.='<td>'.$display_part.'</td>'
+                    .'<td>'.'<span class="LC_internal_info">'.$resID.'</span></td>'
+                    .'<td>'.&mt($responsetype).'</td>'
+#                   .'<td>'.&mt('<b>Handgrade: </b>[_1]',$handgrade).'</td>'
+                    .&Apache::loncommon::end_data_table_row();
+        }
     }
-    $result.='</table>'."\n";
+    $result.=&Apache::loncommon::end_data_table();
     return $result,$responseType,$hdgrade,$partlist,$handgrade;
 }
 
@@ -755,7 +779,7 @@ sub verifyreceipt {
 
     my $title.=
 	'<h3><span class="LC_info">'.
-	&mt('Verifying  Receipt No. [_1]',$receipt).
+	&mt('Verifying Receipt No. [_1]',$receipt).
 	'</span></h3>'."\n".
 	'<h4>'.&mt('<b>Resource: </b>[_1]',$env{'form.probTitle'}).
 	'</h4>'."\n";
@@ -767,7 +791,13 @@ sub verifyreceipt {
     if ($env{"course.$courseid.receiptalg"} eq 'receipt2' ||
 	$env{"course.$courseid.receiptalg"} eq 'receipt3') { $receiptparts=1; }
     my $parts=['0'];
-    if ($receiptparts) { ($parts)=&response_type($symb); }
+    if ($receiptparts) {
+        my $res_error; 
+        ($parts)=&response_type($symb,\$res_error);
+        if ($res_error) {
+            return &navmap_errormsg();
+        } 
+    }
     
     my $header = 
 	&Apache::loncommon::start_data_table().
@@ -809,11 +839,14 @@ sub verifyreceipt {
 	}
     }
     if ($matches == 0) {
-	$string = $title.&mt('No match found for the above receipt.');
+        $string = $title
+                 .'<p class="LC_warning">'
+                 .&mt('No match found for the above receipt number.')
+                 .'</p>';
     } else {
 	$string = &jscriptNform($symb).$title.
 	    '<p>'.
-	    &mt('The above receipt matches the following [numerate,_1,student].',$matches).
+	    &mt('The above receipt number matches the following [quant,_1,student].',$matches).
 	    '</p>'.
 	    $header.
 	    $contents.
@@ -1745,13 +1778,17 @@ sub gradeBox {
         $$record{'resource.'.$partid.'.tries'}.'" />'."\n".
         '<input type="hidden" name="aggtries'.$counter.'_'.$partid.'" value="'.
         $aggtries.'" />'."\n";
-    $result.=&handback_box($symb,$uname,$udom,$counter,$partid,$record);
+    my $res_error;
+    $result.=&handback_box($symb,$uname,$udom,$counter,$partid,$record,\$res_error);
+    if ($res_error) {
+        return &navmap_errormsg();
+    }
     return $result;
 }
 
 sub handback_box {
-    my ($symb,$uname,$udom,$counter,$partid,$record) = @_;
-    my ($partlist,$handgrade,$responseType) = &response_type($symb);
+    my ($symb,$uname,$udom,$counter,$partid,$record,$res_error) = @_;
+    my ($partlist,$handgrade,$responseType) = &response_type($symb,$res_error);
     my (@respids);
      my @part_response_id = &flatten_responseType($responseType);
     foreach my $part_response_id (@part_response_id) {
@@ -2046,7 +2083,12 @@ KEYWORDS
     }
 
     my %record = &Apache::lonnet::restore($symb,$env{'request.course.id'},$udom,$uname);
-    my ($partlist,$handgrade,$responseType) = &response_type($symb);
+    my $res_error;
+    my ($partlist,$handgrade,$responseType) = &response_type($symb,\$res_error);
+    if ($res_error) {
+        $request->print(&navmap_errormsg());
+        return;
+    }
 
     # Display student info
     $request->print(($counter == 0 ? '' : '<br />'));
@@ -2597,7 +2639,12 @@ sub processHandGrade {
     }
     $ctr = 0;
     @parsedlist = reverse @parsedlist if ($button eq 'Previous');
-    my ($partlist) = &response_type($symb);
+    my $res_error;
+    my ($partlist) = &response_type($symb,\$res_error);
+    if ($res_error) {
+        $request->print(&navmap_errormsg());
+        return;
+    }
     foreach my $student (@parsedlist) {
 	my $submitonly=$env{'form.submitonly'};
 	my ($uname,$udom) = split(/:/,$student);
@@ -2795,8 +2842,12 @@ sub check_and_remove_from_queue {
 sub handback_files {
     my ($request,$symb,$stuname,$domain,$newflg,$new_part,$newrecord) = @_;
     my $portfolio_root = '/userfiles/portfolio';
-    my ($partlist,$handgrade,$responseType) = &response_type($symb);
-
+    my $res_error;
+    my ($partlist,$handgrade,$responseType) = &response_type($symb,\$res_error);
+    if ($res_error) {
+        $request->print('<br />'.&navmap_errormsg().'<br />');
+        return;
+    }
     my @part_response_id = &flatten_responseType($responseType);
     foreach my $part_response_id (@part_response_id) {
     	my ($part_id,$resp_id) = @{ $part_response_id };
@@ -3254,7 +3305,11 @@ sub viewgrades {
     $result.= '<h3>'.$common_header.'</h3>'.&Apache::loncommon::start_data_table();
     #radio buttons/text box for assigning points for a section or class.
     #handles different parts of a problem
-    my ($partlist,$handgrade,$responseType) = &response_type($symb);
+    my $res_error;
+    my ($partlist,$handgrade,$responseType) = &response_type($symb,\$res_error);
+    if ($res_error) {
+        return &navmap_errormsg();
+    }
     my %weight = ();
     my $ctsparts = 0;
     my %seen = ();
@@ -3314,7 +3369,11 @@ sub viewgrades {
 	      &Apache::loncommon::start_data_table_header_row().
 	      '<th>'.&mt('No.').'</th>'.
 	      '<th>'.&nameUserString('header')."</th>\n";
-    my (@parts) = sort(&getpartlist($symb));
+    my $partserror;
+    my (@parts) = sort(&getpartlist($symb,\$partserror));
+    if ($partserror) {
+        return &navmap_errormsg();
+    }
     my (undef,undef,$url)=&Apache::lonnet::decode_symb($symb);
     my @partids = ();
     foreach my $part (@parts) {
@@ -3473,7 +3532,11 @@ sub editgrades {
     my %columns = ();
     my ($i,$ctr,$count,$rec_update) = (0,0,0,0);
 
-    my (@parts) = sort(&getpartlist($symb));
+    my $partserror;
+    my (@parts) = sort(&getpartlist($symb,\$partserror));
+    if ($partserror) {
+        return &navmap_errormsg();
+    }
     my $header;
     while ($ctr < $env{'form.totalparts'}) {
 	my $partid = $env{'form.partid_'.$ctr};
@@ -3805,8 +3868,14 @@ ENDPICK
 }
 
 sub csvupload_fields {
-    my ($symb) = @_;
-    my (@parts) = &getpartlist($symb);
+    my ($symb,$errorref) = @_;
+    my (@parts) = &getpartlist($symb,$errorref);
+    if (ref($errorref)) {
+        if ($$errorref) {
+            return;
+        }
+    }
+
     my @fields=(['ID','Student/Employee ID'],
 		['username','Student Username'],
 		['domain','Student Domain']);
@@ -3906,8 +3975,12 @@ sub csvuploadmap {
     &csvuploadmap_header($request,$symb,$datatoken,$#records+1);
     my ($i,$keyfields);
     if (@records) {
-	my @fields=&csvupload_fields($symb);
-
+        my $fieldserror;
+	my @fields=&csvupload_fields($symb,\$fieldserror);
+        if ($fieldserror) {
+            $request->print(&navmap_errormsg());
+            return;
+        }
 	if ($env{'form.upfile_associate'} eq 'reverse') {	
 	    &Apache::loncommon::csv_print_samples($request,\@records);
 	    $i=&Apache::loncommon::csv_print_select_table($request,\@records,
@@ -4143,7 +4216,12 @@ LISTJAVASCRIPT
 	&mt('Manual Grading by Page or Sequence').'</span></h3>';
 
     $result.='<form action="/adm/grades" method="post" name="displayPage">'."\n";
-    my ($titles,$symbx) = &getSymbMap();
+    my $map_error;
+    my ($titles,$symbx) = &getSymbMap($map_error);
+    if ($map_error) {
+        $request->print(&navmap_errormsg());
+        return; 
+    }
     my ($curpage) =&Apache::lonnet::decode_symb($symb); 
 #    my ($curpage,$mapId) =&Apache::lonnet::decode_symb($symb); 
 #    my $type=($curpage =~ /\.(page|sequence)/);
@@ -4238,8 +4316,14 @@ LISTJAVASCRIPT
 }
 
 sub getSymbMap {
+    my ($map_error) = @_;
     my $navmap = Apache::lonnavmaps::navmap->new();
-
+    unless (ref($navmap)) {
+        if (ref($map_error)) {
+            $$map_error = 'navmap';
+        }
+        return;
+    }
     my %symbx = ();
     my @titles = ();
     my $minder = 0;
@@ -4298,6 +4382,11 @@ sub displayPage {
     $request->print($result);
 
     my $navmap = Apache::lonnavmaps::navmap->new();
+    unless (ref($navmap)) {
+        $request->print(&navmap_errormsg());
+        $request->print(&show_grading_menu_form($symb));
+        return;
+    }
     my ($mapUrl, $id, $resUrl)=&Apache::lonnet::decode_symb($env{'form.page'});
     my $map = $navmap->getResourceByUrl($resUrl); # add to navmaps
     if (!$map) {
@@ -4552,7 +4641,12 @@ sub updateGradeByPage {
 
     $request->print($result);
 
+
     my $navmap = Apache::lonnavmaps::navmap->new();
+    unless (ref($navmap)) {
+        $request->print(&navmap_errormsg());
+        return;
+    }
     my ($mapUrl, $id, $resUrl) = &Apache::lonnet::decode_symb( $env{'form.page'});
     my $map = $navmap->getResourceByUrl($resUrl); # add to navmaps
     if (!$map) {
@@ -4775,14 +4869,19 @@ sub defaultFormData {
    Return html dropdown of possible sequences to grade
  
  Arguments:
-   $symb - $symb of the current resource 
+   $symb - $symb of the current resource
+   $map_error - ref to scalar which will container error if
+                $navmap object is unavailable in &getSymbMap().
 
 =cut
 
 sub getSequenceDropDown {
-    my ($symb)=@_;
+    my ($symb,$map_error)=@_;
     my $result='<select name="selectpage">'."\n";
-    my ($titles,$symbx) = &getSymbMap();
+    my ($titles,$symbx) = &getSymbMap($map_error);
+    if (ref($map_error)) {
+        return if ($$map_error);
+    }
     my ($curpage)=&Apache::lonnet::decode_symb($symb); 
     my $ctr=0;
     foreach (@$titles) {
@@ -5048,7 +5147,12 @@ sub scantron_selectphase {
     my ($r,$file2grade) = @_;
     my ($symb)=&get_symb($r);
     if (!$symb) {return '';}
-    my $sequence_selector=&getSequenceDropDown($symb);
+    my $map_error;
+    my $sequence_selector=&getSequenceDropDown($symb,\$map_error);
+    if ($map_error) {
+        $r->print('<br />'.&navmap_errormsg().'<br />');
+        return;
+    }
     my $default_form_data=&defaultFormData($symb);
     my $grading_menu_button=&show_grading_menu_form($symb);
     my $file_selector=&scantron_uploads($file2grade);
@@ -6222,7 +6326,12 @@ sub scantron_validate_file {
     $r->print('<p>'.&mt('Gathering necessary information.').'</p>');$r->rflush();
     #get the student pick code ready
     $r->print(&Apache::loncommon::studentbrowser_javascript());
-    my $max_bubble=&scantron_get_maxbubble();
+    my $nav_error;
+    my $max_bubble=&scantron_get_maxbubble(\$nav_error);
+    if ($nav_error) {
+        $r->print(&navmap_errormsg());
+        return '';
+    }
     my $result=&scantron_form_start($max_bubble).$default_form_data;
     $r->print($result);
     
@@ -6634,6 +6743,10 @@ sub scantron_validate_sequence {
     my ($r,$currentphase) = @_;
 
     my $navmap=Apache::lonnavmaps::navmap->new();
+    unless (ref($navmap)) {
+        $r->print(&navmap_errormsg());
+        return (1,$currentphase);
+    }
     my (undef,undef,$sequence)=
 	&Apache::lonnet::decode_symb($env{'form.selectpage'});
 
@@ -6665,8 +6778,13 @@ sub scantron_validate_ID {
     #get scantron line setup
     my %scantron_config=&get_scantron_config($env{'form.scantron_format'});
     my ($scanlines,$scan_data)=&scantron_getfile();
-    
-    &scantron_get_maxbubble();	# parse needs the bubble_lines.. array.
+
+    my $nav_error;
+    &scantron_get_maxbubble(\$nav_error); # parse needs the bubble_lines.. array.
+    if ($nav_error) {
+        $r->print(&navmap_errormsg());
+        return(1,$currentphase);
+    }
 
     my %found=('ids'=>{},'usernames'=>{});
     for (my $i=0;$i<=$scanlines->{'count'};$i++) {
@@ -7219,7 +7337,12 @@ sub scantron_validate_CODE {
 
     my %allcodes=&get_codes();
 
-    &scantron_get_maxbubble();	# parse needs the lines per response array.
+    my $nav_error;
+    &scantron_get_maxbubble(\$nav_error); # parse needs the lines per response array.
+    if ($nav_error) {
+        $r->print(&navmap_errormsg());
+        return(1,$currentphase);
+    }
 
     my ($scanlines,$scan_data)=&scantron_getfile();
     for (my $i=0;$i<=$scanlines->{'count'};$i++) {
@@ -7273,7 +7396,12 @@ sub scantron_validate_doublebubble {
     #get scantron line setup
     my %scantron_config=&get_scantron_config($env{'form.scantron_format'});
     my ($scanlines,$scan_data)=&scantron_getfile();
-    &scantron_get_maxbubble();	# parse needs the bubble line array.
+    my $nav_error;
+    &scantron_get_maxbubble(\$nav_error); # parse needs the bubble line array.
+    if ($nav_error) {
+        $r->print(&navmap_errormsg());
+        return(1,$currentphase);
+    }
 
     for (my $i=0;$i<=$scanlines->{'count'};$i++) {
 	my $line=&scantron_get_line($scanlines,$scan_data,$i);
@@ -7291,6 +7419,7 @@ sub scantron_validate_doublebubble {
 
 
 sub scantron_get_maxbubble {
+    my ($nav_error) = @_;
     if (defined($env{'form.scantron_maxbubble'}) &&
 	$env{'form.scantron_maxbubble'}) {
 	&restore_bubble_lines();
@@ -7301,6 +7430,11 @@ sub scantron_get_maxbubble {
 	&Apache::lonnet::decode_symb($env{'form.selectpage'});
 
     my $navmap=Apache::lonnavmaps::navmap->new();
+    unless (ref($navmap)) {
+        if (ref($nav_error)) {
+            $$nav_error = 1;
+        }
+    }
     my $map=$navmap->getResourceByUrl($sequence);
     my @resources=$navmap->retrieveResources($map,\&scantron_filter,1,0);
 
@@ -7390,7 +7524,11 @@ sub scantron_validate_missingbubbles {
     #get scantron line setup
     my %scantron_config=&get_scantron_config($env{'form.scantron_format'});
     my ($scanlines,$scan_data)=&scantron_getfile();
-    my $max_bubble=&scantron_get_maxbubble();
+    my $nav_error;
+    my $max_bubble=&scantron_get_maxbubble(\$nav_error);
+    if ($nav_error) {
+        return(1,$currentphase);
+    }
     if (!$max_bubble) { $max_bubble=2**31; }
     for (my $i=0;$i<=$scanlines->{'count'};$i++) {
 	my $line=&scantron_get_line($scanlines,$scan_data,$i);
@@ -7450,6 +7588,10 @@ sub scantron_process_students {
     my $classlist=&Apache::loncoursedata::get_classlist();
     my %idmap=&username_to_idmap($classlist);
     my $navmap=Apache::lonnavmaps::navmap->new();
+    unless (ref($navmap)) {
+        $r->print(&navmap_errormsg());
+        return '';
+    }  
     my $map=$navmap->getResourceByUrl($sequence);
     my @resources=$navmap->retrieveResources($map,\&scantron_filter,1,0);
     my (%grader_partids_by_symb,%grader_randomlists_by_symb);
@@ -7492,7 +7634,12 @@ SCANTRONFORM
     my $i=-1;
     my $started;
 
-    &scantron_get_maxbubble();	# Need the bubble lines array to parse.
+    my $nav_error;
+    &scantron_get_maxbubble(\$nav_error); # Need the bubble lines array to parse.
+    if ($nav_error) {
+        $r->print(&navmap_errormsg());
+        return '';
+    }
 
     # If an ssi failed in scantron_get_maxbubble, put an error message out to
     # the user and return.
@@ -7976,6 +8123,10 @@ sub checkscantron_results {
     my $classlist=&Apache::loncoursedata::get_classlist();
     my %idmap=&Apache::grades::username_to_idmap($classlist);
     my $navmap=Apache::lonnavmaps::navmap->new();
+    unless (ref($navmap)) {
+        $r->print(&navmap_errormsg());
+        return '';
+    }
     my $map=$navmap->getResourceByUrl($sequence);
     my @resources=$navmap->retrieveResources($map,\&scantron_filter,1,0);
     my (%grader_partids_by_symb,%grader_randomlists_by_symb);
@@ -7994,8 +8145,12 @@ sub checkscantron_results {
                                     'Progress of Bubblesheet Data/Submission Records Comparison',$count,
                                     'inline',undef,'checkscantron');
     my ($username,$domain,$started);
-
-    &scantron_get_maxbubble();  # Need the bubble lines array to parse.
+    my $nav_error;
+    &scantron_get_maxbubble(\$nav_error); # Need the bubble lines array to parse.
+    if ($nav_error) {
+        $r->print(&navmap_errormsg());
+        return '';
+    }
 
     &Apache::lonhtmlcommon::Update_PrgWin($r,\%prog_state,
                                           'Processing first student');
@@ -8346,7 +8501,7 @@ sub grading_menu {
 
     $Str .= Apache::lonhtmlcommon::generate_menu(@menu);
     #$menudata->{'jscript'}
-    $Str .='<hr /><input type="button" value="'.&mt('Verify Receipt').'" '.
+    $Str .='<hr /><input type="button" value="'.&mt('Verify Receipt No.').'" '.
         ' onClick="javascript:checkChoice(document.forms.gradingMenu,\'5\',\'verify\')" '.
         ' /> '.
         &Apache::lonnet::recprefix($env{'request.course.id'}).
@@ -8989,7 +9144,11 @@ sub assign_clicker_grades {
     my ($symb)=&get_symb($r);
     if (!$symb) {return '';}
 # See which part we are saving to
-    my ($partlist,$handgrade,$responseType) = &response_type($symb);
+    my $res_error;
+    my ($partlist,$handgrade,$responseType) = &response_type($symb,\$res_error);
+    if ($res_error) {
+        return &navmap_errormsg();
+    }
 # FIXME: This should probably look for the first handgradeable part
     my $part=$$partlist[0];
 # Start screen output
@@ -9093,6 +9252,13 @@ ENDHEADER
     return $result.&show_grading_menu_form($symb);
 }
 
+sub navmap_errormsg {
+    return '<div class="LC_error">'.
+           &mt('An error occurred retrieving information about resources in the course.').'<br />'.
+           &mt('It is recommended that you [_1]re-initialize the course[_2] and then return to this grading page..','<a href="/adm/roles?selectrole=1&newrole='.$env{'request.role'}.'">','</a>').
+           '</div>';
+}
+
 sub handler {
     my $request=$_[0];
     &reset_caches();
@@ -9318,6 +9484,13 @@ ssi_with_retries()
 
 =item  scantron_get_maxbubble() : 
 
+   Arguments:
+       $nav_error  - Reference to scalar which is a flag to indicate a
+                      failure to retrieve a navmap object.
+       if $nav_error is set to 1 by scantron_get_maxbubble(), the 
+       calling routine should trap the error condition and display the warning
+       found in &navmap_errormsg().
+
    Returns the maximum number of bubble lines that are expected to
    occur. Does this by walking the selected sequence rendering the
    resource and then checking &Apache::lonxml::get_problem_counter()
@@ -9383,6 +9556,11 @@ ssi_with_retries()
    Validates all scanlines in the selected file to not have any
    invalid or underspecified student/employee IDs
 
+=item navmap_errormsg() :
+
+   Returns HTML mark-up inside a <div></div> with a link to re-initialize the course.
+   Should be called whenever the request to instantiate a navmap object fails.  
+
 =back
 
 =cut