added basic documentation

diff --git a/org.glite.lb.utils/Makefile b/org.glite.lb.utils/Makefile
index 9967d32..f8d3043 100644 (file)
--- a/org.glite.lb.utils/Makefile
+++ b/org.glite.lb.utils/Makefile
@@ -19,7 +19,7 @@ gsoap_prefix=/opt/gsoap
 
 -include Makefile.inc
 
-VPATH=${top_srcdir}/src:${top_srcdir}/test
+VPATH=${top_srcdir}/src:${top_srcdir}/doc
 
 CC=gcc
 DEBUG:=-g -O0 -Wall
@@ -73,9 +73,13 @@ JP_LIBS:=-lglite_jp_common -lglite_jp_trio
 
 UTILS:=statistics mon mon-db
 
+MAN_GZ:=glite-lb-mon.1.gz glite-lb-mon-db.1.gz
+MAN = $(MAN_GZ:.gz=)
+
+
 default: all
 
-compile all: ${UTILS}
+compile all: ${UTILS} ${MAN_GZ}
 
 %.o: %.c 
        ${CC} ${CFLAGS} ${GLOBUSINC} -c $<
@@ -91,7 +95,11 @@ statistics: statistics.o
 
 check: compile 
 
-doc:
+doc: ${MAN_GZ}
+
+${MAN_GZ}: ${MAN}
+       cp $? .
+       gzip -f $(notdir $?)
 
 stage: compile
        $(MAKE) install PREFIX=${stagedir} DOSTAGE=yes
@@ -111,9 +119,12 @@ distbin:
         
 install:
        -mkdir -p ${PREFIX}/bin 
-       -mkdir -p ${PREFIX}/share/doc/${package}-${version}
        -mkdir -p ${PREFIX}/lib
+       -mkdir -p ${PREFIX}/share/doc/${package}-${version}
+       -mkdir -p ${PREFIX}/share/man/man1
        ${INSTALL} -m 644 ${top_srcdir}/LICENSE ${PREFIX}/share/doc/${package}-${version}
+       ${INSTALL} -m 644 ${top_srcdir}/doc/README* ${PREFIX}/share/doc/${package}-${version}
+       ${INSTALL} -m 644 ${MAN_GZ} ${PREFIX}/share/man/man1
 
        for p in ${UTILS} ; do \
                ${INSTALL} -m 755 "$$p" "${PREFIX}/bin/glite-lb-$$p"; \
@@ -124,6 +135,7 @@ install:
        fi
 
 clean:
+       rm -fv ${UTILS} ${MAN_GZ} *.{lo,o}
 
 %.o: %.c
        ${COMPILE} -c $<

diff --git a/org.glite.lb.utils/doc/README.LB-monitoring b/org.glite.lb.utils/doc/README.LB-monitoring
new file mode 100644 (file)
index 0000000..868f5c9
--- /dev/null
+++ b/org.glite.lb.utils/doc/README.LB-monitoring
@@ -0,0 +1,65 @@
+LB monitoring tools
+===================
+
+GLITE-LB-MON
+------------
+NAME
+       glite-lb-mon - program for monitoring the number of jobs on the LB server and their several statistics
+
+
+SYNOPSIS
+       glite-lb-mon [-t time]
+
+DESCRIPTION
+       glite-lb-mon is a low-level program for monitoring the the number of jobs on the LB server and their several statistics.
+       Values like minimum, average and maximum time spent in the system are calulated for jobs that entered  the  final  state
+       (Aborted,  Cleared,  Cancelled) in specific time (default last hour). Also number of jobs that entered the system during
+       this time is calculated.
+
+OPTIONS
+       -t time, --time=time
+              querying time in seconds from now to the past [deault 3600]
+
+ENVIRONMENT
+       EDG_WL_QUERY_SERVER
+              set this environment variable to specify the LB server address to query
+
+FILES
+       A special bkindex configuration needed. The following time indices must be defined:
+
+            [ type = "time"; name = "submitted" ],
+            [ type = "time"; name = "cleared" ],
+            [ type = "time"; name = "aborted" ],
+            [ type = "time"; name = "cancelled" ],
+
+
+GLITE-LB-MON-DB
+---------------
+NAME
+       glite-lb-mon-db - program for monitoring the number of jobs in the LB system
+
+SYNOPSIS
+       glite-lb-mon-db [-m dbstring]
+
+DESCRIPTION
+       glite-lb-mon-db  is a low-level program for monitoring the the number of jobs in the LB system.  Using the LB internals,
+       it connects directly to the underlying MySQL database and reads the number of jobs in each state.
+
+OPTIONS
+       -m dbstring, --mysql=dbstring
+              use non-default database connection string
+
+EXAMPLES
+       glite-lb-mon-db
+              this is the default usage
+
+       glite-lb-mon-db -m lbserver/@localhost:lbproxy
+              use this dbstring to query the LB Proxy database. WARNING: the data in the LB Proxy may be incomplete!
+
+ENVIRONMENT
+       MYSQL_UNIX_PORT
+              set this environment variable to specify the path to the non-default MySQL socket path
+
+       LBDB   you can set this environment variable as an alternative to specify the non-default database connection string
+
+

diff --git a/org.glite.lb.utils/doc/README.LB-statistics b/org.glite.lb.utils/doc/README.LB-statistics
new file mode 100644 (file)
index 0000000..9cf4fa0
--- /dev/null
+++ b/org.glite.lb.utils/doc/README.LB-statistics
@@ -0,0 +1,5 @@
+LB statistics tools
+===================
+
+GLITE-LB-STATISTICS
+-------------------

diff --git a/org.glite.lb.utils/doc/glite-lb-mon-db.1 b/org.glite.lb.utils/doc/glite-lb-mon-db.1
new file mode 100644 (file)
index 0000000..3005e56
--- /dev/null
+++ b/org.glite.lb.utils/doc/glite-lb-mon-db.1
@@ -0,0 +1,45 @@
+.TH GLITE-LB-MON-DB 1 "Mar 2006" "EU EGEE Project" "Logging & Bookkeeping Utils"
+
+.SH NAME
+glite-lb-mon-db - program for monitoring the number of jobs in the LB system
+
+.SH SYNOPSIS
+.B glite-lb-mon-db
+.B [-m dbstring]
+.br
+
+.SH DESCRIPTION
+.B glite-lb-mon-db
+is a low-level program for monitoring the the number of jobs in the LB system. 
+Using the LB internals, it connects directly to the underlying MySQL database and reads
+the number of jobs in each state.
+
+.SH OPTIONS
+.TP
+.B \-m dbstring, \-\-mysql=dbstring
+use non-default database connection string
+
+.SH EXAMPLES
+.TP 
+.BI glite-lb-mon-db 
+this is the default usage
+.TP
+.BI glite-lb-mon-db \ -m \ lbserver/@localhost:lbproxy
+use this dbstring to query the LB Proxy database. WARNING: the data in the LB Proxy may be incomplete!
+
+.SH ENVIRONMENT
+.TP
+.B MYSQL_UNIX_PORT
+set this environment variable to specify the path to the non-default MySQL socket path
+.TP
+.B LBDB
+you can set this environment variable as an alternative to specify the non-default database connection string
+
+.SH REPORTING BUGS
+Please, report all bugs to EU EGEE Bug Tracking System located at https://savannah.cern.ch/bugs/?func=additem&group=jra1mdw 
+
+.SH SEE ALSO
+.BR glite-lb-mon (1)
+
+.SH AUTHOR
+EU EGEE JRA1, CESNET group.

diff --git a/org.glite.lb.utils/doc/glite-lb-mon.1 b/org.glite.lb.utils/doc/glite-lb-mon.1
new file mode 100644 (file)
index 0000000..5088df0
--- /dev/null
+++ b/org.glite.lb.utils/doc/glite-lb-mon.1
@@ -0,0 +1,47 @@
+.TH GLITE-LB-MON 1 "Mar 2006" "EU EGEE Project" "Logging & Bookkeeping Utils"
+
+.SH NAME
+glite-lb-mon - program for monitoring the number of jobs on the LB server and their several statistics
+
+.SH SYNOPSIS
+.B glite-lb-mon
+.B [-t time]
+.br
+
+.SH DESCRIPTION
+.B glite-lb-mon
+is a low-level program for monitoring the the number of jobs on the LB server and their several statistics.
+Values like minimum, average and maximum time spent in the system are calulated for jobs that entered 
+the final state (Aborted, Cleared, Cancelled) in specific time (default last hour). Also number of jobs
+that entered the system during this time is calculated.
+
+.SH OPTIONS
+.TP
+.B \-t time, \-\-time=time
+querying time in seconds from now to the past [deault 3600]
+
+.SH ENVIRONMENT
+.TP
+.B EDG_WL_QUERY_SERVER
+set this environment variable to specify the LB server address to query
+
+.SH FILES
+A special bkindex configuration needed. The following time indices must be defined:
+
+.nf
+       [ type = "time"; name = "submitted" ],
+       [ type = "time"; name = "cleared" ],
+       [ type = "time"; name = "aborted" ],
+       [ type = "time"; name = "cancelled" ],
+.fi
+
+
+.SH REPORTING BUGS
+Please, report all bugs to EU EGEE Bug Tracking System located at https://savannah.cern.ch/bugs/?func=additem&group=jra1mdw 
+
+.SH SEE ALSO
+.BR glite-lb-bkindex (8), 
+.BR glite-lb-mon (1)
+
+.SH AUTHOR
+EU EGEE JRA1, CESNET group.