![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to q-quipu.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual|
Return to q-quipu.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual |
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.