--- loncom/lonsql	2001/11/29 13:53:56	1.39
+++ loncom/lonsql	2001/11/29 14:59:52	1.40
@@ -1,7 +1,7 @@
 #!/usr/bin/perl
 
 # The LearningOnline Network
-# lonsql - LON TCP-MySQL-Server
+# lonsql - LON TCP-MySQL-Server Daemon for handling database requests.
 #
 # YEAR=2000
 # lonsql-based on the preforker:harsha jagasia:date:5/10/00
@@ -13,9 +13,21 @@
 # 8/30 Gerd Kortemeyer
 # 10/17,11/28,11/29 Scott Harrison
 #
-# $Id: lonsql,v 1.39 2001/11/29 13:53:56 harris41 Exp $
+# $Id: lonsql,v 1.40 2001/11/29 14:59:52 harris41 Exp $
 ###
 
+###############################################################################
+##                                                                           ##
+## ORGANIZATION OF THIS PERL SCRIPT                                          ##
+## 1. Modules used                                                           ##
+## 2. Enable find subroutine                                                 ##
+## 3. Read httpd access.conf and get variables                               ##
+## 4. Make sure that database can be accessed                                ##
+## 5. Make sure this process is running from user=www                        ##
+## 6. Check if other instance is running                                     ##
+## 7. POD (plain old documentation, CPAN style)                              ##
+##                                                                           ##
+###############################################################################
 
 use IO::Socket;
 use Symbol;
@@ -436,3 +448,75 @@ sub propath {
     my $proname="$perlvar{'lonUsersDir'}/$udom/$subdir/$uname";
     return $proname;
 } 
+
+# ----------------------------------- POD (plain old documentation, CPAN style)
+
+=head1 NAME
+
+lonsql - LON TCP-MySQL-Server Daemon for handling database requests.
+
+=head1 SYNOPSIS
+
+This script should be run as user=www.  The following is an example invocation
+from the loncron script.  Note that a lonsql.pid file contains the pid of
+the parent process.
+
+    if (-e $lonsqlfile) {
+	my $lfh=IO::File->new("$lonsqlfile");
+	my $lonsqlpid=<$lfh>;
+	chomp($lonsqlpid);
+	if (kill 0 => $lonsqlpid) {
+	    print $fh "<h3>lonsql at pid $lonsqlpid responding</h3>";
+	    $restartflag=0;
+	} else {
+	    $errors++; $errors++;
+	    print $fh "<h3>lonsql at pid $lonsqlpid not responding</h3>";
+		$restartflag=1;
+	print $fh 
+	    "<h3>Decided to clean up stale .pid file and restart lonsql</h3>";
+	}
+    }
+    if ($restartflag==1) {
+	$errors++;
+	         print $fh '<br><font color="red">Killall lonsql: '.
+                    system('killall lonsql').' - ';
+                    sleep 60;
+                    print $fh unlink($lonsqlfile).' - '.
+                              system('killall -9 lonsql').
+                    '</font><br>';
+	print $fh "<h3>lonsql not running, trying to start</h3>";
+	system(
+ "$perlvar{'lonDaemons'}/lonsql 2>>$perlvar{'lonDaemons'}/logs/lonsql_errors");
+	sleep 10;
+
+=head1 DESCRIPTION
+
+LON TCP-MySQL-Server Daemon for handling database requests.
+
+=head1 README
+
+LON TCP-MySQL-Server Daemon for handling database requests.
+
+=head1 PREREQUISITES
+
+IO::Socket
+Symbol
+POSIX
+IO::Select
+IO::File
+Socket
+Fcntl
+Tie::RefHash
+DBI
+
+=head1 COREQUISITES
+
+=head1 OSNAMES
+
+linux
+
+=head1 SCRIPT CATEGORIES
+
+Server/Process
+
+=cut