From 9674023645959e311a85b366e9143d6f84a0f383 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Ji=C5=99=C3=AD=20Sitera?= Date: Tue, 15 Jul 2008 08:27:37 +0000 Subject: [PATCH] First version of JobId description, changed beginning and context. --- org.glite.lb.doc/src/LBDG-Introduction.tex | 96 ++++++++++++++++++++---------- 1 file changed, 63 insertions(+), 33 deletions(-) diff --git a/org.glite.lb.doc/src/LBDG-Introduction.tex b/org.glite.lb.doc/src/LBDG-Introduction.tex index 7c44a37..2c51209 100644 --- a/org.glite.lb.doc/src/LBDG-Introduction.tex +++ b/org.glite.lb.doc/src/LBDG-Introduction.tex @@ -3,12 +3,14 @@ \section{\LB API introduction} \input versions -\TODO{Udelat nejaky odkaz na UG - LB introduction and architecture} +A recomended prerequisity for reader of this developer's guide is the +\LB architecture description located in the first part of +the \LB user's guide (\cite{LBUG}). The whole \LB service shares a number of common concepts and principles used to design, develop and use the services. Most of common data types and functions is separated in its own SW module called -\LB common. +\LB common (\texttt{org.glite.lb.common}). \subsection{\LB API design notes} @@ -113,37 +115,54 @@ an error, non-null value means success. \subsection{\LB common general components} \subsubsection{JobId} -\TODO{JobId kratce vetveno na 3.1 a 2.0 (jmeno a umisteni / samostatny - modul) Odkazy na zacatek user's guide pro vysvetleni architektury.} The primary entity of \LB is a job, identified by JobId -- a unique -identifier of the job. The type representing the JobId is opaque, it's -contents is hidden to the API users and should be manipulated with the -access methods only. +identifier of the job (see also \cite{LBUG}). The type representing +the JobId is opaque, it's contents is hidden to the API users and +should be manipulated with the access methods only. The JobId representing data structure name and location changed between \LB versions: -\begin{itemize} - \item \texttt{edg\_wlc\_JobId} -- old data structure used in WMS 3.1 - edg\_wlc\_JobIdParse, edg\_wlc\_JobIdFree - glite/lb/jobid.h - \item \texttt{glite\_jobid\_t} -- new data structure for \LB 2.0 - glite/jobid/cjobid.h -\end{itemize} +\begin{description} + \item [\texttt{edg\_wlc\_JobId}] -- data structure used in WMS 3.1 and earlier + \begin{itemize} + \item header file -- \texttt{glite/lb/jobid.h} + \item important funcions: + \begin{itemize} + \item \texttt{edg\_wlc\_JobIdParse} -- convert JobId in a form of + string into \texttt{edg\_wlc\_JobId} structure; returns 0 for + success and EINVAL if the input string can't be parsed into a valid JobId + \item \texttt{edg\_wlc\_JobIdUnParse} -- produce the string + representation of JobId structure + \item \texttt{edg\_wlc\_JobIdFree} -- dealocation of the structure + \end{itemize} + \end{itemize} + \item [\texttt{glite\_jobid\_t}] -- new data structure for \LB 2.0 + \begin{itemize} + \item different header file -- \texttt{glite/jobid/cjobid.h} + \item new names of important funcions described above: + \begin{itemize} + \item \texttt{glite\_jobid\_parse} + \item \texttt{glite\_jobid\_unparse} + \item \texttt{glite\_jobid\_free} + \end{itemize} + \end{itemize} +\end{description} \subsubsection{edg\_wll\_Event} Data structure \texttt{edg\_wll\_Event} represents a \LB event, atomic -data unit received and processed by \LB. It is a set of -key--value pairs with predefined structure -- allowed event types and -names of attributes. It is returned by customer LB API job event -related calls. The data structure have a common part and a event +data unit received and processed by \LB. It is a set of key--value +pairs with predefined structure -- allowed event types and names of +attributes. In \LB each event must be associated with a particular +job. The \texttt{edg\_wll\_Event} is returned by customer LB API job +event related calls. The data structure have a common part and a event type specific part. Most important common event attributes: \begin{itemize} - \item \texttt{jobId} Grid job id of the job the event belongs to. - \item \texttt{user} Identity (certificate subject) of the event sender. - \item \texttt{timestamp} Time when the event was generated. - \item \texttt{seqcode} Sequence code assigned to the event. - \item \texttt{type} Event type. + \item \texttt{jobId} -- identificaion of the job the event belongs to. + \item \texttt{user} -- identity (certificate subject) of the event sender. + \item \texttt{timestamp} -- time when the event was generated. + \item \texttt{seqcode} -- sequence code assigned to the event. + \item \texttt{type} -- event type. \end{itemize} The event type is transparent. The only important operation defined is @@ -158,11 +177,11 @@ computed by \LB from received events. The data structure have a common part and a job state specific part. Most important common attributes: \begin{itemize} - \item \texttt{state} numeric code of the status + \item \texttt{state} -- numeric code of the status (EDG\_WLL\_JOB\_SUBMITTED, EDG\_WLL\_JOB\_WAITING, \dots) - \item \texttt{type} type of the job (EDG\_WLL\_JOB\_SIMPLE, + \item \texttt{type} -- type of the job (EDG\_WLL\_JOB\_SIMPLE, EDG\_WLL\_JOB\_DAG, EDG\_WLL\_JOB\_COLLECTION) - \item \texttt{children} list of subjob \jobid's + \item \texttt{children} -- list of subjob \jobid's \end{itemize} @@ -178,16 +197,27 @@ appropriate constants. Examples of common context parameters: authentication \end{itemize} +\TODO{Máme odkaz kde jsou popsany defaulty a vazby na promenne environmentu?} + The context type is opaque. Operations with the type instance: \begin{itemize} - \item \texttt{edg\_wll\_InitContext(edg\_wll\_Context *context)} + \item \texttt{edg\_wll\_InitContext(OUT edg\_wll\_Context *context)} Allocate and initialize a new context object. - \item \texttt{edg\_wll\_FreeContext(edg\_wll\_Context context)} - Destroy and free context object. - \item \texttt{edg\_wll\_SetParam(edg\_wll\_Context context, - edg\_wll\_ContextParam param, val)} Set a context parameter. - \item \texttt{edg\_wll\_GetParam(edg\_wll\_Context context, - edg\_wll\_ContextParam param, val)} Get current parameter value. + \item \texttt{edg\_wll\_FreeContext(IN edg\_wll\_Context context)} + Destroy and free context object, performs the necessary cleanup + (closing pending connections etc.). + \item \texttt{edg\_wll\_SetParam(INOUT edg\_wll\_Context context, IN + edg\_wll\_ContextParam param, IN val)} Sets a context parameter to + a given value (supports different types of \texttt{val}). If the + value is NULL (pointer type) or 0 (int), the parameter is reset to + its default value (or the value given by environment variable), in + exactly the same way as on context initialization. + \item \texttt{edg\_wll\_GetParam(INOUT edg\_wll\_Context context, IN + edg\_wll\_ContextParam param, OUT val)} Gets current parameter + value. Different types of \texttt{val} supported. Please note that + if the value of parameter is a~default, an actual value is always + returned, not NULL or 0. + \item edg\_wll\_Error \end{itemize} For more information see file \texttt{context.h} -- 1.8.2.3