- print available fields

- manpage

diff --git a/org.glite.lb.client/Makefile b/org.glite.lb.client/Makefile
index ee711aa..a36a170 100644 (file)
--- a/org.glite.lb.client/Makefile
+++ b/org.glite.lb.client/Makefile
@@ -150,7 +150,7 @@ EXAMPLES_CL:=${EXAMPLES_CL_SRC:.c=}
 EXAMPLES_CL_THR_SRC:=user_jobs_threaded.c
 EXAMPLES_CL_THR:=${EXAMPLES_CL_THR_SRC:.c=}
 
-MAN_GZ:=glite-lb-logevent.1.gz
+MAN_GZ:=glite-lb-logevent.1.gz glite-lb-notify.1.gz
 MAN8_GZ:=glite-lb-dump.8.gz glite-lb-load.8.gz glite-lb-purge.8.gz
 MAN = $(MAN_GZ:.gz=)
 MAN8 = $(MAN8_GZ:.gz=)

diff --git a/org.glite.lb.client/doc/glite-lb-notify.1 b/org.glite.lb.client/doc/glite-lb-notify.1
new file mode 100644 (file)
index 0000000..3b01fa2
--- /dev/null
+++ b/org.glite.lb.client/doc/glite-lb-notify.1
@@ -0,0 +1,127 @@
+.TH GLITE-LB-NOTIFY 1 "Apr 2008" "EU EGEE Project" "Logging&Bookkeeping"
+
+.SH NAME
+glite-lb-notify - Register and receive notification from L&B 
+
+.SH SYNOPSIS
+.B glite-lb-notify 
+.br
+       \fBnew\fR [ { \fB-s\fI socket_fd\fR | \fB-a \fIfake_addr\fR } \fB-t \fIrequested_validity\fR ] { \fB-j \fIjobid \fR| \fB-o \fIowner \fR| \fB-n \fInetwork_server \fR| \fB-v\fI virtual_organization\fR }
+.br
+       \fBbind \fR [ { \fB-s\fI socket_fd\fR | \fB-a \fIfake_addr\fR } \fB-t \fIrequested_validity\fR ] \fInotifid\fR
+.br
+       \fBrefresh\fR [ \fB-t \fIrequested_validity \fR ] notifid
+.br
+       \fBreceive\fR [ { \fB-s\fI socket_fd\fR | \fB-a \fIfake_addr\fR } \fB-t \fIrequested_validity\fR ] [ \fB -i \fItimeout \fR] [ \fB-f\fI field1,field2\fR,... \fInotifid\fR
+.br
+       \fBdrop\fR \fInotifid\fR
+
+
+.SH DESCRIPTION
+.B glite-lb-notify 
+is a fairly simple wrapper on the L&B notification API.
+It allows to create a notification (with a restricted richness of specifying
+conditions), bind to it for receiving notifications, and drop it finally.
+
+L&B notification is a user-initiated trigger at the server.
+Whenever a job enters a state matching conditions specified with the notification,
+the current state of the job is sent to the notification client.
+On the other hand, the notification client is a network listener
+which receives server-initiated connections to get the notifications.
+Unless
+.B -s
+is specified, the notification library creates the listener
+socket.
+
+Within the notification validity,
+clients can disappear and even migrate.
+However, only a single active client for a notification is allowed. 
+
+This command
+is intended to be used in user scripts, graphical tools etc. where
+direct access to the API is difficult. 
+
+L&B server and port to contact is specified with GLITE_WMS_NOTIF_SERVER environment
+variable.
+
+.SH USAGE
+Common options (mostly)
+.TP
+.B -t
+specifies a requested validity of the notification (in seconds of UNIX Epoch),
+the server can truncate the value according to its policy. 
+.TP
+.B -a
+allows to specify a fake listener address to register with the notification,
+i.e. to overcome firewalls etc.
+When notifications are delivered, the server tries to connect to this
+address rather than the true address of the listening socket.
+Requires re-binding therefore it
+can't be used in conjunction with
+.B -s
+.
+.TP
+.B -s
+allows to pass a opened listening socket (filedescriptor number), see EXAMPLE bellow.
+In this case there is no need to re-bind the notification
+(it is assumed the socket is recycled)
+This is critical for a real usage, as the re-bind operation is rather
+expensive.
+
+.SH \ 
+
+Subcommands:
+.TP
+.B new
+Create a new notification. Conditions on matching jobs are specified
+with exacltly one of 
+.B -j\fR,
+.B -o\fR,
+.B -n,\fR
+.B -v
+options. 
+Prints ID of the created notification.
+
+.TP
+.B bind
+
+Binds to an existing notification, changing its listener eventually.
+Useful for debugging purposes mostly. 
+
+.TP
+.B refresh
+
+Extend validity of an existing notification.
+
+.TP
+.B receive
+
+Bind to an existing notification, and start waiting for an incoming
+event, at most the time specified with
+.B -i
+(seconds).
+.B -f
+allows to specify a custom list of fields of the job status
+to display. Run 
+.B glite-lb-notify
+to get list of available fields.
+
+.TP
+.B drop
+
+Drop the notification from the server, removing all messages on the way eventually.
+
+.SH EXAMPLE
+Installed with the package as share/examples/glite-lb-notify.pl.
+Demontstrates using the non-trivial
+.B -s
+option.
+
+
+.SH SEE ALSO
+.B glite-lb-bkserverd\fR(8),\fP glite-lb-interlogd\fR(8),\fP glite-lb-logd\fR(8)
+
+L&B Users Guide, http://www.glite.org
+
+.SH AUTHOR
+EU EGEE JRA1, CESNET cluster.

diff --git a/org.glite.lb.client/src/notify.c b/org.glite.lb.client/src/notify.c
index 5d5ec2e..71b2b61 100644 (file)
--- a/org.glite.lb.client/src/notify.c
+++ b/org.glite.lb.client/src/notify.c
@@ -63,12 +63,16 @@ static void usage(char *cmd)
        if ( !cmd || !strcmp(cmd, "refresh") )
                fprintf(stderr,"\n'refresh' command usage: %s refresh [-t requested_validity ] notifid\n"
                        "    notifid     Notification ID.\n", me);
-       if ( !cmd || !strcmp(cmd, "receive") )
+       if ( !cmd || !strcmp(cmd, "receive") ) {
                fprintf(stderr,"\n'receive' command usage: %s receive [ { -s socket_fd | -a fake_addr } ] [-t requested_validity ] [-i timeout] [-f field1,field2,...] [notifid]\n"
                        "    notifid     Notification ID (not used if -s specified).\n"
                        "    fake_addr   Fake the client address.\n"
                        "    field1,field2,...  list of status fields to print (only owner by default)\n"
                        "    timeout     Timeout to receive operation in seconds.\n", me);
+               fprintf(stderr,"\navailable fields:\n\t");
+               dump_fields();
+               putc(10,stderr);
+       }
        if ( !cmd || !strcmp(cmd, "drop") )
                fprintf(stderr,"\n'drop' command usage: %s drop notifid\n"
                        "    notifid     Notification to remove.\n", me);

diff --git a/org.glite.lb.client/src/notify_supp.cpp b/org.glite.lb.client/src/notify_supp.cpp
index 1b7bd61..05f3778 100644 (file)
--- a/org.glite.lb.client/src/notify_supp.cpp
+++ b/org.glite.lb.client/src/notify_supp.cpp
@@ -25,6 +25,7 @@ char * parse_fields(const char *arg,void **out)
        return NULL;
 }
 
+
 std::string & escape(std::string &s)
 {
        for (std::string::iterator p = s.begin(); p < s.end(); p++) switch (*p) {
@@ -39,6 +40,20 @@ std::string & escape(std::string &s)
 
 typedef std::vector<std::pair<JobStatus::Attr,JobStatus::AttrType> > attrs_t;
 
+void dump_fields(void)
+{
+       JobStatus       s;
+       attrs_t         a = s.getAttrs(); 
+       for (attrs_t::iterator i=a.begin(); i != a.end(); i++) {
+               switch (i->second) {
+                       case JobStatus::INT_T:
+                       case JobStatus::STRING_T:
+                               std::cerr << JobStatus::getAttrName(i->first) << ", ";
+                       default: break;
+               }
+       }
+}
+
 void print_fields(void **ff,const edg_wll_NotifId n,edg_wll_JobStat const *s)
 {
        std::vector<JobStatus::Attr>    *fields = (std::vector<JobStatus::Attr> *) ff;

diff --git a/org.glite.lb.client/src/notify_supp.h b/org.glite.lb.client/src/notify_supp.h
index 0d261d2..acb5322 100644 (file)
--- a/org.glite.lb.client/src/notify_supp.h
+++ b/org.glite.lb.client/src/notify_supp.h
@@ -4,6 +4,8 @@ extern "C" {
 
 char * parse_fields(const char *,void **);
 void print_fields(void **,const edg_wll_NotifId,edg_wll_JobStat const *);
+void dump_fields(void);
+
 
 #ifdef __cplusplus
 }