First version of JobId description, changed beginning and context.

diff --git a/org.glite.lb.doc/src/LBDG-Introduction.tex b/org.glite.lb.doc/src/LBDG-Introduction.tex
index 7c44a37..2c51209 100644 (file)
--- 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}