Return to q-quipu.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/q-quipu.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter {Using the Quipu Library}
        !             4: 
        !             5: This part of the manual is written for implementors who wish to use
        !             6: the \man libquipu(3n) library.
        !             7: 
        !             8: The library provides some routines to manage the data returned by the DUA
        !             9: procedure calls described in Chapter~\ref{DUA:proc}.
        !            10: 
        !            11: 
        !            12: \section{The Entry Structure}
        !            13: 
        !            14: The \verb"Entry" structure is used by the Quipu DSA to store the data
        !            15: in the local DIT.  
        !            16: This structure can also be used by a DUA to cache information from a
        !            17: successful read operation, and so the structure is described.
        !            18: In fact, this is how \pgm{dish} and \pgm{widget} maintain their caches.
        !            19: 
        !            20: The structure is shown below,
        !            21: many of the fields are not appropriate to a DUA, but are briefly described for
        !            22: completeness.
        !            23: 
        !            24: \begin{quote}\index{Entry}\small\begin{verbatim}
        !            25: typedef struct entry {
        !            26:     RDN              e_name;
        !            27:     Attr_Sequence    e_attributes; 
        !            28:     char             e_leaf;         
        !            29:     char             e_complete;     
        !            30:     int              e_data;         
        !            31: #define E_DATA_MASTER             1
        !            32: #define E_TYPE_SLAVE              2
        !            33: #define E_TYPE_CACHE_FROM_MASTER  3
        !            34: #define E_TYPE_CONSTRUCTOR        4
        !            35:     char              e_allchildrenpresent;
        !            36:     struct acl      * e_acl;         
        !            37:     DN                e_alias;        
        !            38:     struct dsa_info * e_dsainfo; 
        !            39:     char            * e_edbversion;
        !            40:     AV_Sequence       e_master;        
        !            41:     AV_Sequence              e_slave;  
        !            42:     struct entry    * e_sibling;    
        !            43:     struct entry    * e_parent;
        !            44:     struct entry    * e_child;
        !            45:     time_t            e_age;
        !            46:     char              e_lock;         
        !            47: } entry, *Entry;
        !            48: \end{verbatim}\end{quote}
        !            49: 
        !            50: \begin{describe}
        !            51: \item [\verb"e\_name":] The RDN of the entry, to find the DN, use the routine
        !            52: \begin{quote}\small\begin{verbatim}
        !            53: DN get_copy_dn (entryptr)
        !            54: Entry entryptr;
        !            55: \end{verbatim}\end{quote}
        !            56: \item [\verb"e\_attributes":] The attributes returned by the DSA.
        !            57: \item [\verb"e\_leaf":] Set to \verb"TRUE" if the entry is known to be a leaf.
        !            58: \item [\verb"e\_complete":] Set to \verb"TRUE" if it is know that we have
        !            59: ALL the attributes.
        !            60: \item [\verb"e\_data":] This takes one of four values. in the DUA only two
        !            61: apply. \verb"E_TYPE_CACHE_FROM_MASTER" implies the entry has data that has
        !            62: been read from the DSA.
        !            63: \verb"E_TYPE_CONSTRUCTOR" is used when the entry has been ``made'' by the
        !            64: caching mechanism to fill in a missing part of the DIT on the way down to 
        !            65: another entry.  An entry of this type will contain no data except form the
        !            66: RDN of the entry.
        !            67: \item [\verb"e\_allchildrenpresent":] Set to \verb"TRUE" when it is known
        !            68: that all the children are held.  
        !            69: This is a DSA specific field.
        !            70: \item [\verb"e\_acl":] A pointer to the ``Access Control List'' attribute.
        !            71: \item [\verb"e\_alias":] Set to \verb"TRUE" if the entry represents an alias.
        !            72: This is a DSA specific field.
        !            73: \item [\verb"e\_dsainfo":] pointers to the ``EDBInfo'' and
        !            74: ``PresentationAddress'' attribute of entries representing DSAs.
        !            75: \item [\verb"e\_edbversion":]
        !            76: This is a DSA specific field representing the EDB version number of the
        !            77: children.
        !            78: \item [\verb"e\_master":] Pointer to the ``MasterDSA'' attribute.
        !            79: \item [\verb"e\_slave":] Pointer to the ``SlaveDSA'' attribute.
        !            80: \item [\verb"e\_sibling":] Pointer to other nodes at this level in the tree.
        !            81: \item [\verb"e\_parent":] Pointer to the parent entry.
        !            82: \item [\verb"e\_child":] Pointer to the children.
        !            83: \item [\verb"e\_age":] If the data type is \verb"E_TYPE_CACHE_FROM_MASTER",
        !            84: then the entry is time stamped. This enables the cache to be `timed out'.
        !            85: NOTE in a DUA all entries are cached!
        !            86: \item [\verb"e\_lock":] This field has a dual purpose! In the DSA it is used
        !            87: to prevent an entry from being modified.  In the DUA, if \verb"FALSE", then
        !            88: is suggests that in the field \verb"e_attributes" there are only the
        !            89: attribute types for some attributes, this is a result of caching an results
        !            90: from an operation in which the entry info selection requested that
        !            91: attribute type only were returned (see Section~\ref{eis}).
        !            92: \end{describe}
        !            93: 
        !            94: Using this structure a tree, mapping the DIT can be built up.
        !            95: The tree is rooted by the external \verb"Entry" ``\verb"database_root"''.
        !            96: This entry will NEVER have any attributes or siblings, ONLY children.
        !            97: 
        !            98: \section {Caching Results}
        !            99: 
        !           100: There are four routines to create a cache from results of DAP operations:-
        !           101: 
        !           102: To cache results returned from a \verb"read" or \verb"search" operation call
        !           103: \begin{quote}\index{cache\_entry}\small\begin{verbatim}
        !           104: cache_entry (ptr, complete, vals)
        !           105: EntryInfo      *ptr;
        !           106: char            complete;
        !           107: char            vals;
        !           108: \end{verbatim}\end{quote}
        !           109: 
        !           110: The \verb"complete" parameter should be \verb"TRUE" if all attribute were requested
        !           111: and returned.
        !           112: 
        !           113: The \verb"vals" parameter should be \verb"TRUE" if the attribute values were
        !           114: asked for.
        !           115: 
        !           116: The external \verb"Entry" ``\verb"current_entry"'' will be a pointer to 
        !           117: the newly created entry.
        !           118: 
        !           119: To remove an entry from the cache use:-
        !           120: \begin{quote}\index{delete\_cache}\small\begin{verbatim}
        !           121: delete_cache (adn)
        !           122: DN              adn;
        !           123: \end{verbatim}\end{quote}
        !           124: 
        !           125: \section{Finding Data in the Cache}
        !           126: 
        !           127: The procedure 
        !           128: \begin{quote}\index{local\_find\_entry}\small\begin{verbatim}
        !           129: Entry local_find_entry (object,deref)
        !           130: DN                      object;
        !           131: char                    deref;
        !           132: \end{verbatim}\end{quote}
        !           133: is used to find an entry in the cache.
        !           134: If the entry exists, it will be returned, otherwise \verb"NULLENTRY"
        !           135: will be returned.
        !           136: \verb"object" is the DN of the entry you want to find.
        !           137: If \verb"deref" is \verb"TRUE" then any aliases encountered in trying 
        !           138: to find the entry will be de-referenced.
        !           139: 
        !           140: \section {Caching List Results}
        !           141: List results are cached slightly differently, as only the RDN is known.
        !           142: \begin{quote}\index{cache\_list}\small\begin{verbatim}
        !           143: cache_list (ptr, prob,dn,sizelimit)
        !           144: struct subordinate *ptr;
        !           145: int             prob;
        !           146: DN             dn;
        !           147: int            sizelimit;
        !           148: \end{verbatim}\end{quote}
        !           149: The parameters are as follows:-
        !           150: \begin{describe}
        !           151: \item [\verb"ptr":] A pointer to the subordinates returned by the search.
        !           152: \item [\verb"prob":] The \verb"srr_limitproblem" field of the search results, see
        !           153: Section~\ref{proc_search}.
        !           154: \item [\verb"dn":] The DN of the entry that has been listed.
        !           155: \item [\verb"ptr":] The \verb"svc_sizelimit" field of the common argument of
        !           156: the list argument (see Section~\ref{common_args}).
        !           157: \end{describe}
        !           158: 
        !           159: To inspect the cache use
        !           160: \begin{quote}\small\begin{verbatim}
        !           161: struct list_cache *find_list_cache (dn,sizelimit)
        !           162: DN dn;
        !           163: int sizelimit;
        !           164: \end{verbatim}\end{quote}
        !           165: The \verb"sizelimit" parameter is the sizelimit you would send in the list
        !           166: request.
        !           167: 
        !           168: This returns a \verb"list_cache" structure, if the result is NULL, then the
        !           169: entry is not cached, of did not have ``sizelimit'' results.
        !           170: \begin{quote}\small\begin{verbatim}
        !           171: struct list_cache {
        !           172:        DN              list_dn;
        !           173:        struct subordinate *list_subs;
        !           174:        struct subordinate *list_sub_top;
        !           175:        int             list_count;
        !           176:        int             list_problem;
        !           177:        struct list_cache *list_next;
        !           178: };
        !           179: \end{verbatim}\end{quote}
        !           180: The subordinates can be found in \verb"list_sub_top".
        !           181: The other field should be ignored, as they are for internal management only.
        !           182: 
        !           183: 
        !           184: \section {Changes}
        !           185: 
        !           186: To conclude this part of the Manual, a brief summary of the changes between the 
        !           187: \man libdsap(3n) library supplied with ISODE-5.0 and the version ISODE-6.0
        !           188: is given.
        !           189: The aim is to make it as simple as possible to get code you may have
        !           190: developed with ISODE-5.0 working with ISODE-6.0.
        !           191: 
        !           192: The method of handling attributes has changed at the lowest level.
        !           193: This means there are two changes you need to make:
        !           194: \begin{itemize}
        !           195: \item
        !           196: To load the new syntax handlers you should call \verb+quipu_syntaxes()+
        !           197: (as discussed in Section~\ref{quipusyntaxes}).
        !           198: \item
        !           199: In a few places in-line structures have been replaced with structure pointers
        !           200: and vice-versa.  In the preceding Chapters footnotes indicate the where this
        !           201: has happened.  You are reminded of the \pgm{lint} program, which is
        !           202: particular useful for catching changes like these, especially when the
        !           203: effected structures are used in procedure calls.
        !           204: \end{itemize}
        !           205: 
        !           206: Procedure calls to support the method of binding used in ISODE-5.0 are still
        !           207: supplied, but you are advised to look at Section~\ref{dap:bind} which
        !           208: discusses various alternatives which make the process more secure.
        !           209: 
        !           210: If your program used \verb+log_stat+, previously you had to define the LOG
        !           211: in your code.  This is now done as part of \verb+dsap_init()+ and so is not
        !           212: required.
        !           213: 
        !           214: If you have any problems you are should contact \verb+quipu-support+, the
        !           215: address is given in Section~\ref{quipu:support}.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.