--- projects/cms/source/host/ihost-perl/ihost.pl	2001/02/01 09:10:52	1.11
+++ projects/cms/source/host/ihost-perl/ihost.pl	2001/02/01 09:24:54	1.12
@@ -2,6 +2,7 @@
 
 # -----------------------------------------------------------
 # Perl i-scream Host.
+# http://www.i-scream.org.uk
 #
 # An all-in-one script to act as an i-scream host on
 # a typical Unix/Linux box.  You may adapt the data-gathering
@@ -9,7 +10,7 @@
 #  - pjm2@ukc.ac.uk
 #
 # $Author: pjm2 $
-# $Id: ihost.pl,v 1.11 2001/02/01 09:10:52 pjm2 Exp $
+# $Id: ihost.pl,v 1.12 2001/02/01 09:24:54 pjm2 Exp $
 #------------------------------------------------------------
 
 $| = 1;
@@ -71,6 +72,13 @@ while (1) {
 
 exit(0);
 
+
+#-----------------------------------------------------------------------
+# tcp_configure
+# Establishes a TCP connection to the specified i-scream filter manager.
+# The host then requests details from the server, such as the intervals
+# at which to send UDP packets.
+#-----------------------------------------------------------------------
 sub tcp_configure() {
     
     my($sock) = new IO::Socket::INET(
@@ -85,7 +93,7 @@ sub tcp_configure() {
         exit(1);
     }
 
-    # Now run through the configuration process.
+    # Now run through the configuration process...
     my($response);
     
     print $sock "STARTCONFIG\n";
@@ -155,8 +163,19 @@ sub tcp_configure() {
     close($sock);
 
     print "Configuration finished sucessfully!\n";
+    
+    return;
 }
 
+
+
+
+#-----------------------------------------------------------------------
+# send_udp_packet
+# Sends a UDP packet to an i-scream filter.
+# The packet contains XML markup describing some of the machine's state.
+# Receipt of UDP packets is not guaranteed.
+#-----------------------------------------------------------------------
 sub send_udp_packet() {
 
     my(@statgrab) = `./statgrab.pl`;
@@ -191,6 +210,8 @@ sub send_udp_packet() {
 
     # Build the XML packet this way, as we can clearly
     # see the structure and contents... I like this ;-)
+    # [Note that the server rejects UDP packets that are
+    # larger than 8196 bytes]
     my($xml) = <<EOF;
     
 <packet seq_no="$seq_no" machine_name="$machine_name" date="$date" type="data" ip="$ip">
@@ -238,6 +259,7 @@ sub send_udp_packet() {
 
 EOF
 
+    # Make the packet smaller by stripping out newlines and leading spaces.
     $xml =~ s/\n\s*//g;
     
     my($sock) = new IO::Socket::INET (
@@ -250,8 +272,18 @@ EOF
     close($sock);
     $seq_no++;
     print "-";
+    
+    return;
 }
 
+
+
+
+#-----------------------------------------------------------------------
+# send_tcp_heartbeat
+# Establishes a TCP connection to an i-scream filter.
+# The heartbeat is used as a guaranteed "I'm alive" delivery mechanism.
+#-----------------------------------------------------------------------
 sub send_tcp_heartbeat() {
 
     my($sock) = new IO::Socket::INET(
@@ -319,4 +351,6 @@ sub send_tcp_heartbeat() {
     
     close($sock);
     print "^";
+    
+    return;
 }