⟦79e5a560d⟧

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 Chapter~\ref{DUA:proc}.


\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, and 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 fields 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; 
    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_allchildrenpresent;
    struct acl      * e_acl;         
    DN                e_alias;        
    struct dsa_info * e_dsainfo; 
    char            * e_edbversion;
    AV_Sequence       e_master;	
    AV_Sequence	      e_slave;	
    struct entry    * e_sibling;    
    struct entry    * e_parent;
    struct entry    * e_child;
    time_t            e_age;
    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\_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\_allchildrenpresent":] Set to \verb"TRUE" when it is known
that all the children are held.  
This is a DSA specific field.
\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\_dsainfo":] pointers to the ``EDBInfo'' and
``PresentationAddress'' attribute of entries representing DSAs.
\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\_age":] If the data type is \verb"E_TYPE_CACHE_FROM_MASTER",
then the entry is time stamped. This enables the cache to be `timed out'.
NOTE in a DUA all entries are cached!
\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.

\section {Caching Results}

There are four routines to create a cache from 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 pointer 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.

\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.


\f

\section {Changes}

To conclude this part of the Manual, a brief summary of the changes between the 
\man libdsap(3n) library supplied with ISODE-5.0 and the version ISODE-6.0
is given.
The aim is to make it as simple as possible to get code you may have
developed with ISODE-5.0 working with ISODE-6.0.

The method of handling attributes has changed at the lowest level.
This means there are two changes you need to make:
\begin{itemize}
\item
To load the new syntax handlers you should call \verb+quipu_syntaxes()+
(as discussed in Section~\ref{quipusyntaxes}).
\item
In a few places in-line structures have been replaced with structure pointers
and vice-versa.  In the preceding Chapters footnotes indicate the where this
has happened.  You are reminded of the \pgm{lint} program, which is
particular useful for catching changes like these, especially when the
effected structures are used in procedure calls.
\end{itemize}

Procedure calls to support the method of binding used in ISODE-5.0 are still
supplied, but you are advised to look at Section~\ref{dap:bind} which
discusses various alternatives which make the process more secure.

If your program used \verb+log_stat+, previously you had to define the LOG
in your code.  This is now done as part of \verb+dsap_init()+ and so is not
required.

If you have any problems you are should contact \verb+quipu-support+, the
address is given in Section~\ref{quipu:support}.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦79e5a560d⟧ TextFile

Derivation

TextFile
