-We are really sorry that it took us so long to reply to this GGUS
-ticket, however we took all the comments and suggestions really
-seriously and during the gLite restructuring we made all the required
-changes and among others we now have a completely new documentation both
+We are really sorry that it took us so long to reply to this GGUS
+ticket, however we took all the comments and suggestions really
+seriously and during the gLite restructuring we made all the required
+changes and among others we now have a completely new documentation both
for Logging and Bookkeeping (LB) and Job Provenance (JP).
We attach our comments inline to your initial review/request:
-> The available 'Logging and Bookkeeping User and Reference Guide' has
+> The available 'Logging and Bookkeeping User and Reference Guide' has
> several problems:
->
-> General remarks : the link from the general glite doc page
-> (http://glite.web.cern.ch/glite/documentation/default.asp) links to
-> https://edms.cern.ch/file/571273/1/LB-guide.pdf while EDMS proposes
-> https://edms.cern.ch/file/571273/2/LB-guide.pdf However both documents
-> seem to be the same (even so says diff on the pdf files). Now the most
-> surprising thing is that the proposed document is still a DRAFT dating
-> almost 1.5 years now. Isn't that more than enough time to publish a
+>
+> General remarks : the link from the general glite doc page
+> (http://glite.web.cern.ch/glite/documentation/default.asp) links to
+> https://edms.cern.ch/file/571273/1/LB-guide.pdf while EDMS proposes
+> https://edms.cern.ch/file/571273/2/LB-guide.pdf However both documents
+> seem to be the same (even so says diff on the pdf files). Now the most
+> surprising thing is that the proposed document is still a DRAFT dating
+> almost 1.5 years now. Isn't that more than enough time to publish a
> final document?
-The LB documentation has been changed completely. It is now part of the
-org.glite.lb.doc module and it contains three major documents:
+The LB documentation has been changed completely. It is now
+part of the org.glite.lb.doc module and it contains four major
+documents:
+
- LB User's Guide (LBUG)
- LB Adminstrator's Guide (LBAG)
- LB Developer's Guide (LBDG)
The official web location for these documents is now
http://egee.cesnet.cz/en/JRA1/LB
-and links to these documents were updated on all the following webs:
+and links to these documents were updated on all the following webs:
+
TODO honik, ljocha:
-http://glite.web.cern.ch/glite/documentation/default.asp
+http://glite.web.cern.ch/glite/documentation/default.asp
http://glite.web.cern.ch/glite/packages/R3.1/deployment/glite-LB/glite-LB.asp
http://egee-jra1-wm.mi.infn.it/egee-jra1-wm
https://twiki.cern.ch/twiki/bin/view/EGEE/Glite-LB
TODO honik, ljocha:
The old LB User's Guide was removed from
-https://edms.cern.ch/document/571273/2
+https://edms.cern.ch/document/571273/2
-The JP documentation is going to have a similar structure, it is now kept
+The JP documentation is going to have a similar structure, it is now kept
in the org.glite.jp.doc module and it will be published soon.
-> At last, the guide mentions example code (quote from p. 14 : "You can
-> found this example in client module, file job_status.c."). I found an
-> 'examples' dir in the glite-lb-client package, however it does not
+> At last, the guide mentions example code (quote from p. 14 : "You can
+> found this example in client module, file job_status.c."). I found an
+> 'examples' dir in the glite-lb-client package, however it does not
> contain C source code but rather useless executable files!!
-The source code of all the examples is now also included in the
-glite-lb-client (RPM) together with a simple Makefile so that users
+The source code of all the examples is now also included in the
+glite-lb-client (RPM) together with a simple Makefile so that users
can make the examples on their machines.
> I skip the "Introduction" section.
->
+>
> 2/ Quickstart Guide
> 2.1/ Command Line Tools
-> quite OK but is missing the (C) type of the values that can be given
-> to a user tag: only a string or is an integer value possible? This has
+> quite OK but is missing the (C) type of the values that can be given
+> to a user tag: only a string or is an integer value possible? This has
> it's importance in the following.
-LB keeps user tags only as strings, it is left on the application level to
-give the values some semantics. It is mentioned in LBUG Section 2.3.1.
+LB keeps user tags only as strings, it is left on the
+application level to give the values some semantics. It is now
+mentioned in LBUG Section 2.3.1.
-> I think the documentation misses a description of the equivalent API.
-> At least some part of the code of the CLI interface should be
-> available, as in a job this duty is probably better done by the code
+> I think the documentation misses a description of the equivalent API.
+> At least some part of the code of the CLI interface should be
+> available, as in a job this duty is probably better done by the code
> itself than by some external command.
-glite-lb-logevent is now in details described in LBUG, Section
-2.3, and the use-case of using this tool to log the user-tag is
-described in the LBUG 2.3.1. The logging API is in details described in
+glite-lb-logevent is now in details described in LBUG, Section
+2.3, and the use-case of using this tool to log the user-tag is
+described in the LBUG 2.3.1. The logging API is in details described in
LBDG together with the programming examples.
> 2.2/ L&B querying API
> General remarks:
-> when compiling, of course header files and libraries are required. Why
-> not indicate them ? what flavor of libglite_lb_client shall be used ?
-> And to have some code querying an edg/lcg LB ? although stuff in this
-> API is prefixed by edg_, it's not possible to query an edg/lcg LB with
-> this API when linking against glite libs : error msg is 'Operation not
-> supported (Protocol versions incompatible)'. I'm glad to know now but
+> when compiling, of course header files and libraries are required. Why
+> not indicate them ? what flavor of libglite_lb_client shall be used ?
+> And to have some code querying an edg/lcg LB ? although stuff in this
+> API is prefixed by edg_, it's not possible to query an edg/lcg LB with
+> this API when linking against glite libs : error msg is 'Operation not
+> supported (Protocol versions incompatible)'. I'm glad to know now but
> I would have preferred reading it in the docs.
TODO michal, sitera: All this is now mentioned in LBDG Section 4.
> Section 2.2.2,
> example 1 ("Job status", p. 13)
-> It would be quite interesting to give some details about the
-> edg_wll_JobStat data type and more generally about every data type
-> used for returning results. Also I do not agree with "The code also
-> shows a complete handling of returned errors": although it is claimed
-> it uses errno values, errno variable is not used and the return codes
-> do not always match the defined errno values. Hence the question : how
-> to interpret these return codes, can't some details be given in the
+> It would be quite interesting to give some details about the
+> edg_wll_JobStat data type and more generally about every data type
+> used for returning results. Also I do not agree with "The code also
+> shows a complete handling of returned errors": although it is claimed
+> it uses errno values, errno variable is not used and the return codes
+> do not always match the defined errno values. Hence the question : how
+> to interpret these return codes, can't some details be given in the
> docs ?
TODO michal, sitera: consumer_api.tex, see \label{JS}
-> example 2 ("All user's jobs" p. 14) does not work: it misses the
+> example 2 ("All user's jobs" p. 14) does not work: it misses the
> calling of
> edg_wll_SetParam(ctx, EDG_WLL_PARAM_QUERY_SERVER, my_lb_srv);
> edg_wll_SetParam(ctx, EDG_WLL_PARAM_QUERY_SERVER_PORT, srv_port);
-> for the soft to know which LB host to query. This is needed in also
-> every following example where no explicit jobid is used. If there is a
-> general/convenient way to set it through config files or environment
+> for the soft to know which LB host to query. This is needed in also
+> every following example where no explicit jobid is used. If there is a
+> general/convenient way to set it through config files or environment
> vars, it is not mentioned.
TODO michal, sitera: consumer_api.c, see \label{JQ-auj}
-> One more thing about this example : output can be HUGE! Better mention
+> One more thing about this example : output can be HUGE! Better mention
> it...
TODO michal, sitera: Mentioned :).
> example "querying user tags", p. 17
-> I haven't managed to get it working and after quite a few tries I'm
-> still unable to query user tags I did set myself (proved by the output
-> of the 'glite-lb-logevent' command, which also shows that the tag
-> could be capitalized by the m/w) from some successfully
+> I haven't managed to get it working and after quite a few tries I'm
+> still unable to query user tags I did set myself (proved by the output
+> of the 'glite-lb-logevent' command, which also shows that the tag
+> could be capitalized by the m/w) from some successfully
> executing/executed job.
->
-> Is this code really working ? Could it be a problem linked with the LB
+>
+> Is this code really working ? Could it be a problem linked with the LB
> or VO I'm using (I tried under 'esr' and 'dteam' VOs)?
TODO michal, sitera: consumer_api.c, see \label{JQ_ut}
-> I had no more chance with example "All jobs marked as red" p. 19 and
-> the event query. Is there some available code somewhere that does
+> I had no more chance with example "All jobs marked as red" p. 19 and
+> the event query. Is there some available code somewhere that does
> successfully query some user tag?
TODO michal, sitera: consumer_api.c, see \label{ASQ_allred}
> 3/ The reference
-> Hey, is it really supposed to turn out as a reference? For now, it
-> looks more like an index, except that an index helps locating
-> occurrences. Has the function 'edg_wll_GetServerLimit' (mentioned on
-> p. 97) disappeared from the library? No libglite_lb_whatever seems to
+> Hey, is it really supposed to turn out as a reference? For now, it
+> looks more like an index, except that an index helps locating
+> occurrences. Has the function 'edg_wll_GetServerLimit' (mentioned on
+> p. 97) disappeared from the library? No libglite_lb_whatever seems to
> contain it.
-The automatically generated documentation was really unreadeble, so we removed
+The automatically generated documentation was really unreadable, so we removed
it almost completely from the LBDG. Only a list of header files and important
API functions can be found there.
> I can provide the full source code I used if requested.
-We would really appreciate if you could look at the documentation now
-and tell us if you find it suitable and if all examples are working for
+We would really appreciate if you could look at the documentation now
+and tell us if you find it suitable and if all examples are working for
you without problems.
-
-
service using the \LB library. It is not intended as a complete API
reference; for this, the reader is referred to the C or C++ header
files, which are thoroughly documented using the doxygen--style
-comments.
+comments.
The \LB API can be divided by functionality into two independent
parts:
\begin{itemize}
-\item \textit{\LB Producer API} (section \ref{s:ProdOverview}) is used
+\item \textit{\LB Producer API} (section \ref{s:Producer-API}) is used
to create and send events to the \LB server (proxy),
-\item \textit{\LB Consumer API} (section \ref{s:ConsOverview}) and \textit{\LB
-Notification API} (section \ref{s:NotifOverview}) are used to obtain
+\item \textit{\LB Consumer API} (section \ref{s:Consumer-API}) and \textit{\LB
+Notification API} (section \ref{s:Notification-API}) are used to obtain
information from the \LB server (proxy).
\end{itemize}
These two parts (and in fact the whole \LB service implementation)
\subsection{Language Bindings}
The \LB library itself is developed in C language, the C API covers
all the \LB services. There are bindings for other languages (C++,
-Java) as well as web--service based interface, but these cover only
+Java) as well as web-service (WS) based interface, but these cover only
subsets of \LB functionality and internally they use the C API
themselves (in the C++ case the C API also exported).
We describe the C API first and then the differences between C and the
other languages, as the C constructs often reflect directly.
+As for the \LB\ WS interface, it reflects only the functionality of legacy
+\LB\ Querying API (see Sect.~\ref{s:Consumer-API-WS}).
+
+There exist also HTML and plain text interfaces to \LB. We do not expect anybody using them
+in a programming language (though it is possible), they might be useful rather in
+scripts. Their usage is rather straightforward as it is described in the User's Guide \cite{lbug}.
+
+
\subsection{General Guidelines}
\marginpar{Naming conventions}%
\label{s:context}
The \LB library does not maintain internal state (apart of network
-connections, see \ref{s:pool}), all the API
+connections, see \ref{s:pool}), all the API
functions refer to a~\emph{context} argument instead.
Context object preserves state information among the various API
calls, the state including \LB library parameters (\eg security
The context also stores details on errors of the recent API call.
-For use with the \emph{producer} calls (see section~\ref{s:producer})
+For use with the \emph{producer} calls (see section~\ref{s:Producer-API})
the context has to be assigned a~single \jobid (with the
\verb'edg_wll_SetLoggingJob()' call), and keeps track of an event
-\emph{sequence code} for the job (see~\cite{lbug}, detailed
-description in~\cite{lbarch}).
+\emph{sequence code} for the job (see also \LB Architecture described in \cite{lbug}).
The context object and its API functions are described more thoroughly
in section~\ref{s:edg_wll_context}
\label{t:cheaders}
\end{table}
-\subsubsection{Context}
+\subsubsection{Context}
\label{s:edg_wll_context}
\marginpar{Context initialization}%
Opaque data structure representing \LB API context (see
\begin{tabularx}{\textwidth}{lX}
{\bf C name} & {\bf Description} \\
\hline
-\lstinline'EDG_WLL_PARAM_X509_KEY' &
-Key file to use for authentication.
+\lstinline'EDG_WLL_PARAM_X509_KEY' &
+Key file to use for authentication.
\par {\it Type: } \lstinline'char *'
-\par {\it Environment: } \lstinline'X509_USER_KEY'
+\par {\it Environment: } \lstinline'X509_USER_KEY'
\\
-\lstinline'EDG_WLL_PARAM_X509_CERT' &
-Certificate file to use for authentication.
+\lstinline'EDG_WLL_PARAM_X509_CERT' &
+Certificate file to use for authentication.
\par {\it Type: } \lstinline'char *'
\par {\it Environment: } \lstinline'X509_USER_CERT'
\\
-\lstinline'EDG_WLL_PARAM_CONNPOOL_SIZE' &
-Maximum number of open connections maintained by the library.
+\lstinline'EDG_WLL_PARAM_CONNPOOL_SIZE' &
+Maximum number of open connections maintained by the library.
\par {\it Type: } \lstinline'int'
\par {\it Environment: } \\
\end{tabularx}
\end{table}
The third argument is parameter value, which can be of type
-\verb'int', \verb'char *' or \verb'struct timeval *'.
-If the parameter value is set to \verb'NULL' (or 0), the
+\verb'int', \verb'char *' or \verb'struct timeval *'.
+If the parameter value is set to \verb'NULL' (or 0), the
parameter is reset to the default value.
If you want to obtain current value of some context parameter, call
from the context:
\begin{lstlisting}
char *err_text,*err_desc;
-
+
edg_wll_Error(ctx, &err_text, &err_desc);
fprintf(stderr, "LB library error: %s (%s)\n", err_text, err_desc);
free(err_text);
For more information see file \verb'glite/lb/context.h'
-\subsubsection{JobId}
+\subsubsection{JobId}
The primary entity of \LB is a job, identified by JobId -- a unique
identifier of the job (see also \cite{lbug}). The type representing
the JobId is opaque \verb'glite_jobid_t'. The JobId is in fact
generated by the \LB library):
\begin{lstlisting}
glite_jobid_t jobid;
-int ret;
+int ret;
if(ret = glite_jobid_create("some.host", 0, &jobid)) {
fprintf(stderr, "error creating jobid: %s\n", strerror(ret));
}
\bf Attribute name & \bf Attribute type & \bf Description \\
\hline
\verb'type' & \verb'edg_wll_EventCode' & Event type. Values are
-symbolic constants \eg \verb'EDG_WLL_EVENT_DONE' \\
+symbolic constants \eg \verb'EDG_WLL_EVENT_DONE' \\
\verb'jobId' & \verb'glite_jobid_t' & Jobid of the job the event
belongs to. \\
\verb'user' & \verb'char*' & Identity (certificate subject) of the
\end{table}
The \verb'edg_wll_Event' is returned by consumer \LB
-API job event related calls. The only important operation defined on
+API job event related calls. The only important operation defined on
\verb'edg_wll_Event' itself is
\begin{lstlisting}
-edg_wll_FreeEvent(edg_wll_Event *event)
+edg_wll_FreeEvent(edg_wll_Event *event)
\end{lstlisting}
-to free the event structure.
+to free the event structure.
\marginpar{List of event types}%
The event structure makes use of enumerated types extensively,
\verb'edg_wll_Event' structure it can be viewed as a set of
attributes, where some attributes are common and some specific
for a given job state (but unlike the \verb'edg_wll_Event' it is not
-implemented as union of structs but rather as one big struct).
+implemented as union of structs but rather as one big struct).
Generally speaking, when the attribute value is set, it is a valid
part of job state description. Most important common attributes are
summarized in table~\ref{t:cstatus}.
\verb'owner' & \verb'char*' & Owner (certificate subject) of the
job. \\
\end{tabularx}
-\caption{Common job status attributes}
+\caption{Common job status attributes}\label{t:cstatus}
\end{table}
Job status structure is returned by the \LB consumer API job status
\newpage
\input{notification_api}
-\newpage
-\input{web_services}
+% \newpage
+% \input{web_services}
\TODO{zminit http interface - podporujeme ho jeste? tusim ze fila
to nejak resuscitoval}
% -*- mode: latex -*-
\section{\LB\ Querying (Consumer) API}
-\label{s:ConsOview}
+\label{s:Consumer-API}
The \LB Consumer API is used to obtain information from \LB server
or Proxy using simple query language (see
Sect.~\ref{s:querylang}). There are two types of queries based
\end{itemize}
The potential result sets can be very large; the \LB server imposes
limits on the result set size, which can be further restricted by the
-client.
+client.
\subsection{Query Language}
Simple queries are can be described by the following formula:
\begin{displaymath}
\textit{attr}_1 \mathop{\textrm{ OP }} \textit{value}_1 \wedge \dots \wedge
-\textit{attr}_n \mathop{\textrm{ OP }} \textit{value}_n
+\textit{attr}_n \mathop{\textrm{ OP }} \textit{value}_n
\end{displaymath}
where $\textit{attr}_i$ is attribute name, $\mathop{\textrm{ OP }}$ is
one of the $=$, $<$, $>$, $\neq$ and $\in$ relational operators and
$\textit{value}$ is single value (or, in the case of $\in$ operator,
-interval) from attribute type.
+interval) from attribute type.
Complex queries can be described using the following formula:
\begin{multline*}
(\textit{attr}_2 \mathop{\textrm{ OP }} \textit{value}_{2,1} \vee \dots \vee
\textit{attr}_2 \mathop{\textrm{ OP }} \textit{value}_{2,i_2}) \wedge \\
\vdots \\
-\wedge (\textit{attr}_n \mathop{\textrm{ OP }} \textit{value}_{n,1} \vee \dots \vee
-\textit{attr}_n \mathop{\textrm{ OP }} \textit{value}_{n,i_n})
+\wedge (\textit{attr}_n \mathop{\textrm{ OP }} \textit{value}_{n,1} \vee \dots \vee
+\textit{attr}_n \mathop{\textrm{ OP }} \textit{value}_{n,i_n})
\end{multline*}
The complex query can, in contrast to simple query, contain more
assertions on value of single attribute, which are ORed together.
\subsubsection{Call Semantics}
The \LB server queries are, in contrast to logging event calls,
-synchronous (for asynchronous variant see Sect.~\ref{s:NotifOverview},
+synchronous (for asynchronous variant see Sect.~\ref{s:Notification-API},
notifications). The server response contains \jobid's, job states
and/or events known to the server at the moment of processing the
query. Due to the asynchronous nature of event delivery it may not
\item \verb'EDG_WLL_QUERYRES_NONE'\,---\,In case the limit is reached,
no results are returned at all.
\item \verb'EDG_WLL_QUERYRES_LIMITED'\,---\,A result contains at most
-``limit'' item count.
+``limit'' item count.
\item \verb'EDG_WLL_QUERYRES_ALL'\,---\,All results are returned and
limits have no effect. This option is available only in special cases
such as ``user jobs query'' and the ``job status query''. Otherwise
-the EINVAL error is returned.
+the EINVAL error is returned.
\end{itemize}
Default value is \verb'EDG_WLL_QUERYRES_NONE'.
\begin{tabularx}{\textwidth}{lX}
{\bf Name} & {\bf Description} \\
\hline
-\lstinline'EDG_WLL_PARAM_QUERY_SERVER' &
-Default server name to query.
+\lstinline'EDG_WLL_PARAM_QUERY_SERVER' &
+Default server name to query.
\\
\lstinline'EDG_WLL_PARAM_QUERY_SERVER_PORT' &
-Default server port to query.
+Default server port to query.
\\
\lstinline'EDG_WLL_PARAM_QUERY_SERVER_OVERRIDE' &
host:port parameter setting override even values in \jobid (useful for
-debugging \& hacking only)
+debugging \& hacking only)
\\
\lstinline'EDG_WLL_PARAM_QUERY_TIMEOUT' &
-Query timeout.
+Query timeout.
\\
-\lstinline'EDG_WLL_PARAM_QUERY_JOBS_LIMIT' &
+\lstinline'EDG_WLL_PARAM_QUERY_JOBS_LIMIT' &
Maximal query jobs result size.
\\
-\lstinline'EDG_WLL_PARAM_QUERY_EVENTS_LIMIT' &
+\lstinline'EDG_WLL_PARAM_QUERY_EVENTS_LIMIT' &
Maximal query events result size.
\\
\lstinline'EDG_WLL_PARAM_QUERY_RESULTS' &
The simplest case corresponds to the situation when an exact job ID
is known and the only information requested is the job status. The job ID
format is described in~\cite{djra1.4}.
-The following example shows
+The following example shows
all the relevant structures and API calls to retrieve status information
about a job with the ID\\
\texttt{https://lhun.ics.muni.cz:9000/OirOgeWh\_F9sfMZjnIPYhQ}.
The first function call in this example initializes the \LB\ context\,---\,variable
\texttt{ctx}\,---\,which is necessary for later use. The most important part
of this code fragment is the \texttt{jc} variable setting.
-Variable \texttt{jc} is a list of conditions terminated with the
+Variable \texttt{jc} is a list of conditions terminated with the
\texttt{EDG\_WLL\_QUERY\_ATTR\_UNDEF} item.
In this example it contains the only data item\,---\,the job ID
(in its parsed form).
-If \texttt{edg\_wll\_QueryJobs()} is successful, returned results are available
+If \texttt{edg\_wll\_QueryJobs()} is successful, returned results are available
in the \texttt{statesOut} variable. This variable contains an array of job states\,---\,
in this example state of a given job.
The simple query example is a request for all user's jobs. Another
condition type, \\
-\texttt{EDG\_WLL\_QUERY\_ATTR\_OWNER}, is used in this case, with the
+\texttt{EDG\_WLL\_QUERY\_ATTR\_OWNER}, is used in this case, with the
value field filled with a user name. You can found this example in client module, file \texttt{job\_status.c}.
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[2];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
Developers should keep in mind that the output of such a query could be really huge.
\par
-The following examples demonstrates how \texttt{edg\_wll\_QueryJobs()} combines
+The following examples demonstrates how \texttt{edg\_wll\_QueryJobs()} combines
the given conditions in a logical conjugation.
%\partitle{Running jobs}
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[3];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[4];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
%\partitle{The WITHIN operator}
The \texttt{EDG\_WLL\_QUERY\_OP\_WITHIN} operator can be used in any condition with numeric values.
-The following example shows a query on all user's jobs that have returned
+The following example shows a query on all user's jobs that have returned
an exit code from 2 to 7.
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[4];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
call is to call it twice. The \texttt{edg\_wll\_QueryJobsExt()} call allows to make
such a~query in a single step.
The function accepts an array of condition lists. Conditions within a~single list are
-OR-ed and the lists themselves are AND-ed.
+OR-ed and the lists themselves are AND-ed.
%It is allowed to use only identical attributes in every standalone condition list.
%This is forced by an ``indexing'' definition, look at Sect.~\ref{ConsIndx}
%for further details.
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec *jc[4];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
As clearly seen, there are three lists supplied to
\texttt{edg\_wll\_QueryJobsExt()}. The first list specifies the owner of the
job, the second list provides the required status (\texttt{Running}) and
-the last list specifies the two destinations.
+the last list specifies the two destinations.
The list of lists is terminated with \texttt{NULL}.
-This query equals to the formula
+This query equals to the formula
\begin{quote}
\texttt{(user=NULL) and (state=Running) and (dest='XXX' or dest='YYY')}.
\end{quote}
\label{JQ_ut}
\TODO{Is it really working?}
User tags can be used for marking (labelling) jobs. A user tag is
-a pair of user defined \texttt{name} and \texttt{value}.
+a pair of user defined \texttt{name} and \texttt{value}.
\label{JQ_RedJobs}
For example, if all jobs marked with the user tag \texttt{color} and with its
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[2];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[1][3];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[2];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
...
\end{verbatim}
-Due to performance reasons
+Due to performance reasons
it is not possible to make query with two tags of different type in one
-or-clause.
+or-clause.
% fakt nevim, co tahle veta znamena. ljocha
%That means that user tags are composed of two variable components
%and user tag indices depend on tag names.
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[2];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
In this case, a record representing the necessary condition is quite
different. The \LB\ API allows to ask for jobs with a particular status at a
given time. When \LB\ server gets \texttt{EDG\_WLL\_QUERY\_ATTR\_TIME}
-as a job condition, it checks \texttt{jc[0].attr\_id.state} for job state.
+as a job condition, it checks \texttt{jc[0].attr\_id.state} for job state.
Note that \texttt{timenow} is a variable which contains current time in
seconds.
-It is easy to modify previous example and add another time boundary. It is then
+It is easy to modify previous example and add another time boundary. It is then
possible to ask for all jobs with a specified state within a particular time
interval.
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc[3];
edg_wll_JobStat *statesOut = NULL;
edg_wlc_JobId *jobsOut = NULL;
\subsubsection{Event queries and application specific queries}
\label{ASQ}
-Event queries and job queries are similar.
+Event queries and job queries are similar.
Obviously, the return type is different\Dash the \LB\ raw events.
There is one more input parameter
representing specific conditions on events (possibly empty)
in addition to conditions on jobs.
-Some examples showing event queries
+Some examples showing event queries
are considered in the following paragraph.
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_Event *eventsOut;
edg_wll_QueryRec jc[2];
edg_wll_QueryRec ec[2];
The \texttt{edg\_wll\_QueryEvents()} returns matched events and save them in the
\texttt{eventsOut} variable. Required job IDs are stored in the edg\_wll\_Event
-structure.
+structure.
Due to the need of ``historic'' information it's impossible to address
this type of query with calling the function \texttt{edg\_wll\_QueryJobs()}, raw events has to
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_Event *eventsOut;
edg_wll_QueryRec jc[2];
edg_wll_QueryRec ec[2];
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_Event *eventsOut;
edg_wll_QueryRec jc[2];
edg_wll_QueryRec ec[2];
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_Event *eventsOut;
edg_wll_QueryRec jc[2];
edg_wll_QueryRec ec[3];
%\partitle{Complex query}
The last example illustrates the API usage on
- a~meaningful but rather complex query ``which of my red jobs are heading
+ a~meaningful but rather complex query ``which of my red jobs are heading
to a~destination that already encountered problems executing red jobs''.
First we retrieve the information of red jobs failures.
This cannot be accomplished with a~job query because the job may
-get resubmitted automatically to another computing element and terminate
+get resubmitted automatically to another computing element and terminate
successfully. Therefore we need to search for the ``historic''
information\,---\,`Done' events with their minor status
equal to `Failed'.
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_QueryRec jc1[3],ec1[3];
edg_wll_Event *failures;
Due to job resubmissions again
a~job may be represented several times in \verb'failures'.
-Because of obvious performance reasons
+Because of obvious performance reasons
it is desirable to avoid repeated queries on the same job.
On the other hand, we may rely on \LB\ queries returning data grouped
according to jobs. Therefore checking duplicities is easy.
ec2[0][1].value.i = EDG_WLL_EVENT_DONE;
ec2[0][2].attr = EDG_WLL_QUERY_ATTR_UNDEF;
ec2[1] = NULL;
-
+
n = 0;
for (i=0; failures[i].type; i++) {
this_job = edg_wlc_JobIdUnparse(failures[i].any.jobId);
sites.
A~job's destination is known starting from the `Ready' state,
and the query makes sense also in the `Scheduled' state (\ie\ the job reached
-the LRMS queue but has not been started yet).
+the LRMS queue but has not been started yet).
\begin{verbatim}
...
query must be
split into two simpler queries and user must perform an intersection
on the obtained results.
-We need to get all red jobs routed to destination X on which were already some
-red jobs, but they have failed.
+We need to get all red jobs routed to destination X on which were already some
+red jobs, but they have failed.
\begin{verbatim}
#include <glite/lb/consumer.h>
...
- edg_wll_Context ctx;
+ edg_wll_Context ctx;
edg_wll_Event *eventsOut;
edg_wll_JobStat *statesOut;
edg_wlc_JobId *jobsOut;
\TODO{pro prehlednost bych mozna pridal seznam vsech atributu
na ktere se lze ptat}
+
+
+\subsection{C++ Language Binding}
+\TODO{michal}
+
+
+\subsection{Web-Services Binding}\label{s:Consumer-API-WS}
+
+\TODO{ljocha: Complete review, list of all relevant (WSDL) files, their location, etc.}
+
+In this section we describe the operations defined in the \LB\ WSDL
+file (\texttt{LB.wsdl}) as well as its custom types (\texttt{LBTypes.wsdl}).
+
+For the sake of readability this documentation does not follow the structure
+of WSDL strictly, avoiding to duplicate information which is already present
+here. Consequently, the SOAP messages are not documented, for example, as they
+are derived from operation inputs and outputs mechanically.
+The same holds for types: \eg\ we do not document defined elements
+which correspond 1:1 to types but are required due to the literal SOAP
+encoding.
+
+For exact definition of the operations and types see the WSDL file.
+
+\TODO{ljocha: Add fully functional WS examples - in Java, Python, C?}
% -*- mode: latex -*-
\section{\LB\ Notification API}
-\label{s:NotifOverview}
+\label{s:Notification-API}
The purpose of this section is demonstrating the usage of the \LB\ notification API. Two examples of basic API usage are given.
\subsection{Registering and receiving notification}
-The following example registers on \LB\ server to receive notifications triggered by events belonging to job with \verb'jobid' and waits for notification until \verb'timeout'.
+The following example registers on \LB\ server to receive notifications triggered by events belonging to job with \verb'jobid' and waits for notification until \verb'timeout'.
The code assumes the user to prepare a~reasonable value in \verb'jobid'
(\ie\ identifying an existing job).
edg_wll_FreeStatus(&stat);
edg_wll_NotifIdFree(recv_notif_id);
}
-
+
/* Release registration on BK server. Don't do this if notif_id is reused. */
edg_wll_NotifDrop(ctx, notif_id);
\end{verbatim}
-First of all the context is initialised. During this procedure user's credentials are loaded. %(see \ref{cmdln_interface} for information on environmental variables pointing to user's X509 credentials).
+First of all the context is initialised. During this procedure user's credentials are loaded. %(see \ref{cmdln_interface} for information on environmental variables pointing to user's X509 credentials).
-Then conditions under which notifications are sent are set. In this example, user is notified every time when event with given jobId is logged to \LB\ server. For more complicated conditions, please, consider the conditions limitations mentioned in \ref{notification}.
+Then conditions under which notifications are sent are set. In this example, user is notified every time when event with given jobId is logged to \LB\ server. For more complicated conditions, please, consider the conditions limitations mentioned in \cite{lbug}.
Afterwards, a new registration is created and a unique notification ID is
returned.
\subsection{Changing destination for notifications}
-The second example illustrates how to receive notifications from different host or different application.
+The second example illustrates how to receive notifications from different host or different application.
Let us suppose that user is registered for receiving notifications on \LB\ server. She obtained a notification ID and information how long this registration will be valid as described in the previous example but she did not delete registration with \verb'edg_wll_NotifDrop'.
\begin{verbatim}
edg_wll_NotifId nid;
- char *ns; // notification ID string returned
+ char *ns; // notification ID string returned
// in previous example
...
edg_wll_NotifIdParse(ns, &nid);
/* prolong the registration validity if necessary */
if (...validity close to expire...)
- edg_wll_NotifRefresh(ctx, nid, &valid);
+ edg_wll_NotifRefresh(ctx, nid, &valid);
edg_wll_NotifReceive(ctx, -1, &timeout, &status, &recv_notif_id);
...
% -*- mode: latex -*-
\section{\LB\ Logging (Producer) API}
-\label{s:ProdOverview}
+\label{s:Producer-API}
\subsection{C Language Binding}
The \LB\ logging API (or producer API) is used to create and deliver
string in the form \verb'EDG_WLL_FORMAT_'\textit{EventType}, \eg\
\verb'EDG_WLL_FORMAT_UserTag', as well as three convenience functions
\verb'edg_wll_LogUserTag(...)', \verb'edg_wll_LogUserTagSync(...)',
-\verb'edg_wll_LogUserTagProxy(...)'.
+\verb'edg_wll_LogUserTagProxy(...)'.
For most developers (\ie\ those not developing the WMS itself) the
\verb'edg_wll_LogUserTag*(...)' and \verb'edg_wll_ChangeACL(...)' are
returned immediatelly and the success of the call means that the first
\LB infrastructure component takes over the event and queues it for
delivery. If you require transaction semantics, you have to use
-synchronous \verb'edg_wll_LogEventSync(...)' call.
+synchronous \verb'edg_wll_LogEventSync(...)' call.
The \LB proxy on the other hand provides a \emph{local view}
semantics, events logged into proxy using
The table~\ref{t:pcontext} summarizes context parameters relevant to the
event logging. If parameter is not set in the context explicitly, the
\LB\ library will search for value of corresponding environment
-variable.
+variable.
\begin{table}[h]
\begin{tabularx}{\textwidth}{lX}
{\bf Name} & {\bf Description} \\
\hline
-\lstinline'EDG_WLL_PARAM_HOST' &
-Hostname that appears as event origin.
-\par {\it Type: } \lstinline'char*'
+\lstinline'EDG_WLL_PARAM_HOST' &
+Hostname that appears as event origin.
+\par {\it Type: } \lstinline'char*'
\par {\it Environment: } \\
-\lstinline'EDG_WLL_PARAM_SOURCE' &
-Event source component.
+\lstinline'EDG_WLL_PARAM_SOURCE' &
+Event source component.
\par {\it Type: }\lstinline'edg_wll_Source'
\par {\it Environment: } \\
-\lstinline'EDG_WLL_PARAM_DESTINATION' &
-Hostname of machine running locallogger/interlogger.
-\par {\it Type: }\lstinline'char*'
-\par {\it Environment: }\lstinline'GLITE_WMS_LOG_DESTINATION' \\
-\lstinline'EDG_WLL_PARAM_DESTINATION_PORT' &
-Port the locallogger is listening on.
-\par {\it Type: } \lstinline'int'
-\par {\it Environment: }\lstinline'GLITE_WMS_LOG_DESTINATION' \\
-\lstinline'EDG_WLL_LOG_TIMEOUT' &
-Logging timeout for asynchronous logging.
-\par {\it Type: }\lstinline'struct timeval'
-\par {\it Environment: }\lstinline'GLITE_WMS_LOG_TIMEOUT' \\
-\lstinline'EDG_WLL_LOG_SYNC_TIMEOUT' &
-Logging timeout for synchronous logging.
-\par {\it Type: }\lstinline'struct timeval'
+\lstinline'EDG_WLL_PARAM_DESTINATION' &
+Hostname of machine running locallogger/interlogger.
+\par {\it Type: }\lstinline'char*'
+\par {\it Environment: }\lstinline'GLITE_WMS_LOG_DESTINATION' \\
+\lstinline'EDG_WLL_PARAM_DESTINATION_PORT' &
+Port the locallogger is listening on.
+\par {\it Type: } \lstinline'int'
+\par {\it Environment: }\lstinline'GLITE_WMS_LOG_DESTINATION' \\
+\lstinline'EDG_WLL_LOG_TIMEOUT' &
+Logging timeout for asynchronous logging.
+\par {\it Type: }\lstinline'struct timeval'
+\par {\it Environment: }\lstinline'GLITE_WMS_LOG_TIMEOUT' \\
+\lstinline'EDG_WLL_LOG_SYNC_TIMEOUT' &
+Logging timeout for synchronous logging.
+\par {\it Type: }\lstinline'struct timeval'
\par {\it Environment: }\lstinline'GLITE_WMS_LOG_SYNC_TIMEOUT' \\
-\lstinline'EDG_WLL_LBPROXY_STORE_SOCK' &
-\LB\ Proxy store socket path (if logging through \LB\ Proxy)
-\par {\it Type: }\lstinline'char*'
-\par {\it Environment: }\lstinline'GLITE_WMS_LBPROXY_STORE_SOCK' \\
-\lstinline'EDG_WLL_LBPROXY_USER' &
-Certificate subject of the user (if logging through \LB\ proxy).
-\par {\it Type: }\lstinline'char*'
+\lstinline'EDG_WLL_LBPROXY_STORE_SOCK' &
+\LB\ Proxy store socket path (if logging through \LB\ Proxy)
+\par {\it Type: }\lstinline'char*'
+\par {\it Environment: }\lstinline'GLITE_WMS_LBPROXY_STORE_SOCK' \\
+\lstinline'EDG_WLL_LBPROXY_USER' &
+Certificate subject of the user (if logging through \LB\ proxy).
+\par {\it Type: }\lstinline'char*'
\par {\it Environment: }\lstinline'GLITE_WMS_LBPROXY_USER' \\
\end{tabularx}
\caption{Producer specific context parameters}
\end{lstlisting}
After setting the logging job identity, all the following logging
calls refer to this \jobid and the sequence code is incremented
-according to the source component.
+according to the source component.
\TODO{how is the sequence code updated?}
\subsubsection{Return values}
If you use this function, you have to provide event code, format
string and corresponding arguments yourself. The UserTag event has
only two arguments, tag name and value, but other events require more
-arguments.
+arguments.
Instead of using the generic \verb'edg_wll_LogEvent()' at line~\ref{l:logevent}, we could also
write:
\TODO{Complete review, list of all relevant (WSDL) files, their location, etc.}
The \LB\ web service interface currently reflects the functionality of legacy
-\LB\ query API (Sect.~\ref{query-C}).
+\LB\ Querying API (Sect.~\ref{Consumer-API}).
The following sections describe the operations defined in the \LB\ WSDL
file as well as its custom types.
For the sake of readability this documentation does not follow the structure
of WSDL strictly, avoiding to duplicate information which is already present
-here.
-Consequently, the SOAP messages are not documented, for example, as they
+here. Consequently, the SOAP messages are not documented, for example, as they
are derived from operation inputs and outputs mechanically.
The same holds for types: \eg\ we do not document defined elements
which correspond 1:1 to types but are required due to the literal SOAP
git://scientific.zcu.cz / jra1mw.git / commitdiff