⟦62ef6ca23⟧

TextFile

% run this through LaTeX with the appropriate wrapper

\f

\chapter {Using the Quipu Library}

This part of the manual is written for implementors who wish to use
the \man libquipu(3n) library.

The library provides some routines to manage the data returned by the DUA
procedure calls described in Section~\ref{proc_model}.


\section{The Entry Structure}

The \verb"Entry" structure is used by the Quipu DSA to store the data
in the local DIT.  
This structure can also be used by a DUA to cache information from a
successful read operation, an so the structure is described.
In fact, this is how \pgm{dish} and \pgm{widget} maintain their caches.

The structure is shown below,
many of the field are not appropriate to a DUA, but are briefly described for
completeness.

\begin{quote}\index{Entry}\small\begin{verbatim}
typedef struct entry {
    RDN              e_name;
    Attr_Sequence    e_attributes; 
    AV_Sequence      e_oc_avseq;    	
    char             e_leaf;         
    char             e_complete;     
    int              e_data;         
#define E_DATA_MASTER             1
#define E_TYPE_SLAVE              2
#define E_TYPE_CACHE_FROM_MASTER  3
#define E_TYPE_CONSTRUCTOR        4
    char            * e_passwd;      
    AV_Sequence       e_struct;
    struct acl      * e_acl;         
    DN                e_alias;        
    struct dsa_info * e_dsainfo; 
    char              e_allchildrenpresent;
    char            * e_edbversion;
    AV_Sequence       e_master;	
    AV_Sequence	      e_slave;	
    struct entry    * e_sibling;    
    struct entry    * e_parent;
    struct entry    * e_child;
    char              e_lock;         
} entry, *Entry;
\end{verbatim}\end{quote}

\begin{describe}
\item [\verb"e\_name":] The RDN of the entry, to find the DN, use the routine
\begin{quote}\small\begin{verbatim}
DN get_copy_dn (entryptr)
Entry entryptr;
\end{verbatim}\end{quote}
\item [\verb"e\_attributes":] The attributes returned by the DSA.
\item [\verb"e\_oc\_avseq":] A pointer to the object class attribute.
\item [\verb"e\_leaf":] Set to \verb"TRUE" if the entry is known to be a leaf.
\item [\verb"e\_complete":] Set to \verb"TRUE" if it is know that we have
ALL the attributes
\item [\verb"e\_data":] This takes one of four values. in the DUA only two
apply. \verb"E_TYPE_CACHE_FROM_MASTER" implies the entry has data that has
been read from the DSA.
\verb"E_TYPE_CONSTRUCTOR" is used when the entry has been ``made'' by the
caching mechanism to fill in a missing part of the DIT on the way down to 
another entry.  An entry of this type will contain no data except form the
RDN of the entry.
\item [\verb"e\_password":] The password required to bind as this entry.
This is a DSA specific field.
\item [\verb"e\_struct":] A pointer to the ``Tree\_Structure''
attribute.
\item [\verb"e\_acl":] A pointer to the ``Access Control List'' attribute.
\item [\verb"e\_alias":] Set to \verb"TRUE" if the entry represents an alias.
This is a DSA specific field.
\item [\verb"e\_dsa\_info":] pointers to the ``EDBInfo'' and
``PresentationAddress'' attribute of entries representing DSAs
\item [\verb"e\_allchildrenpresent":] Set to \verb"TRUE" when it is known
that all the children are held.  
This is a DSA specific field.
\item [\verb"e\_edbversion":]
This is a DSA specific field representing the EDB version number of the
children.
\item [\verb"e\_master":] Pointer to the ``MasterDSA'' attribute
\item [\verb"e\_slave":] Pointer to the ``SlaveDSA'' attribute
\item [\verb"e\_sibling":] Pointer to other nodes at this level in the tree.
\item [\verb"e\_parent":] Pointer to the parent entry.
\item [\verb"e\_child":] Pointer to the children
\item [\verb"e\_lock":] This field has a dual purpose! In the DSA it is used
to prevent an entry from being modified.  In the DUA, if \verb"FALSE", then
is suggests that in the field \verb"e_attributes" there are only the
attribute types for some attributes, this is a result of caching an results
from an operation in which the entry info selection requested that
attribute type only were returned (see Section~\ref{eis}).
\end{describe}

Using this structure a tree, mapping the DIT can be built up.
The tree is rooted by the external \verb"Entry" ``\verb"database_root"''.
This entry will NEVER have any attributes or siblings, ONLY children.

When this structure is built up from results of DAP operations, only the
fields \verb"e_name", \verb"e_attributes", \verb"e_parent", \verb"e_siblings"
and \verb"e_child" will be set.
To use the other fileds, you need to ``unravel'' the attributes:-

\begin{quote}\index{unravel\_attribute}\small\begin{verbatim}
unravel_attribute (eptr,error,decode)
Entry eptr;
struct DSError * error;
char decode;
\end{verbatim}\end{quote}

This return \verb"OK" or \verb"NOTOK"
The \verb"error" parameter is used to supply details of what is ong in the
case of a \verb"NOTOK" return value.

If the \verb"decode" parameter is \verb"TRUE", then the attribute in the
entry will be fully decoded.

Before you call \verb"unravel_attributes" you MUST call
\begin{quote}\index{check\_known\_oids}\small\begin{verbatim}
check_known_oids ()
\end{verbatim}\end{quote}
This set various local pointers, and informs you of any known problems with the
object identifier tables.
This need only be called once per program.

\section {Caching Results}

There are four routines to create a cache form results of DAP operations:-

To cache results returned from a \verb"read" or \verb"search" operation call
\begin{quote}\index{cache\_entry}\small\begin{verbatim}
cache_entry (ptr, complete, vals)
EntryInfo      *ptr;
char            complete;
char            vals;
\end{verbatim}\end{quote}

The \verb"complete" parameter should be \verb"TRUE" if all attribute were requested
and returned.

The \verb"vals" parameter should be \verb"TRUE" if the attribute values were
asked for.

The external \verb"Entry" ``\verb"current_entry"'' will be a poiter to 
the newly created entry.

To remove an entry from the cache use:-
\begin{quote}\index{delete\_cache}\small\begin{verbatim}
delete_cache (adn)
DN              adn;
\end{verbatim}\end{quote}

\section{Finding Data in the Cache}

The procedure 
\begin{quote}\index{local\_find\_entry}\small\begin{verbatim}
Entry local_find_entry (object,deref)
DN                      object;
char                    deref;
\end{verbatim}\end{quote}
is used to find an entry in the cache.
If the entry exists, it will be returned, otherwise \verb"NULLENTRY"
will be returned.
\verb"object" is the DN of the entry you want to find.
If \verb"deref" is \verb"TRUE" then any aliases encountered in trying 
to find the entry will be de-referenced.

The procedure 
\begin{quote}\index{really\_find\_entry}\small\begin{verbatim}
Entry really_find_entry (object,err,deref)
DN                      object;
struct DSError          *err;
char                    deref;
\end{verbatim}\end{quote}
is used to find an entry in the cache, if the find fails
the \verb"err" structure will contain an indication of what has gone wrong.
There is a corresponding routine \verb"find_entry", but this only applies to
a DSA, as it will only find an entry if the access control lists allow the
entry to be found.

The parameters are:
\begin{describe}
\item[\verb"object":]	The DN of the object you want to find
\item[\verb"err":] An error structure - this essentially says the entry was
not in the local cache.
\item[\verb"deref":] If \verb"TRUE" then aliases will be dereferenced.
\end{describe}

When an entry is found, the ordering of the siblings is changed, to make the
``found'' entry the first sibling in the list of children.

\section {Caching List Results}
List results are cached slightly differently, as only the RDN is known.
\begin{quote}\index{cache\_list}\small\begin{verbatim}
cache_list (ptr, prob,dn,sizelimit)
struct subordinate *ptr;
int             prob;
DN 		dn;
int 		sizelimit;
\end{verbatim}\end{quote}
The parameters are as follows:-
\begin{describe}
\item [\verb"ptr":] A pointer to the subordinates returned by the search.
\item [\verb"prob":] The \verb"srr_limitproblem" field of the search results, see
Section~\ref{proc_search}.
\item [\verb"dn":] The DN of the entry that has been listed.
\item [\verb"ptr":] The \verb"svc_sizelimit" field of the common argument of
the list argument (see Section~\ref{common_args}).
\end{describe}

To inspect the cache use
\begin{quote}\small\begin{verbatim}
struct list_cache *find_list_cache (dn,sizelimit)
DN dn;
int sizelimit;
\end{verbatim}\end{quote}
The \verb"sizelimit" parameter is the sizelimit you would send in the list
request.

This returns a \verb"list_cache" structure, if the result is NULL, then the
entry is not cached, of did not have ``sizelimit'' results.
\begin{quote}\small\begin{verbatim}
struct list_cache {
	DN              list_dn;
	struct subordinate *list_subs;
	struct subordinate *list_sub_top;
	int             list_count;
	int             list_problem;
	struct list_cache *list_next;
};
\end{verbatim}\end{quote}
The subordinates can be found in \verb"list_sub_top".
The other field should be ignored, as they are for internal management only.


\section{Writing a cache to disk}

The routines for writing a cache to disk have not been fully developed.
It is hoped to do more in this area for the next release of the software.
Below, two routines are described, that may be of use, but it is intended
to improve upon them.

To write the cache to disk using the routine
\begin{quote}\small\begin{verbatim}
directory_dump (dir,directory,format,level)
char * dir;
Entry directory;
int format;
char level;
\end{verbatim}\end{quote}

Where \verb"dir" is the name of the \unix/ directory you want to store the
cache, \verb"directory" is the tree you want to save --- essentially
``database\_root'', \verb"format" should be ``EDBOUT'', \verb"level" should
be ``w''.


This will load a subtree of the DIT into the cache structure.
If will look for the subtree under the \unix/ directory specified in the
external \verb"char *" ``\verb"tree_dir"''.
\begin{quote}\small\begin{verbatim}
Entry subtree_load (parent,dn)
Entry parent;
DN dn;
\end{verbatim}\end{quote}
The \verb"parent" parameter is the parent of the entry you want to load.
\verb"dn" is the name of the subtree you want to load.

The procedure returns a pointer to the subtree loaded, or \verb"NULLENTRY"
if the load failed.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦62ef6ca23⟧ TextFile

Derivation

TextFile
