1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
|
<html><head><meta charset="ISO-8859-1"><title>10.Extended Services: Remote Insert, Update and Delete</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><link rel="home" href="index.html" title="Zebra - User's Guide and Reference"><link rel="up" href="administration.html" title="Chapter6.Administrating Zebra"><link rel="prev" href="administration-ranking.html" title="9.Relevance Ranking and Sorting of Result Sets"><link rel="next" href="record-model-domxml.html" title="Chapter7.DOM XML Record Model and Filter Module"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">10.Extended Services: Remote Insert, Update and Delete</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="administration-ranking.html">Prev</a></td><th width="60%" align="center">Chapter6.Administrating <span class="application">Zebra</span></th><td width="20%" align="right"><a accesskey="n" href="record-model-domxml.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="administration-extended-services"></a>10.Extended Services: Remote Insert, Update and Delete</h2></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Extended services are only supported when accessing the <span class="application">Zebra</span>
server using the <a class="ulink" href="https://www.loc.gov/z3950/agency/" target="_top"><acronym class="acronym">Z39.50</acronym></a>
protocol. The <a class="ulink" href="https://www.loc.gov/standards/sru/" target="_top"><acronym class="acronym">SRU</acronym></a> protocol does
not support extended services.
</p></div><p>
The extended services are not enabled by default in zebra - due to the
fact that they modify the system. <span class="application">Zebra</span> can be configured
to allow anybody to
search, and to allow only updates for a particular admin user
in the main zebra configuration file <code class="filename">zebra.cfg</code>.
For user <code class="literal">admin</code>, you could use:
</p><pre class="screen">
perm.anonymous: r
perm.admin: rw
passwd: passwordfile
</pre><p>
And in the password file
<code class="filename">passwordfile</code>, you have to specify users and
encrypted passwords as colon separated strings.
Use a tool like <code class="filename">htpasswd</code>
to maintain the encrypted passwords.
</p><pre class="screen">
admin:secret
</pre><p>
It is essential to configure <span class="application">Zebra</span> to store records internally,
and to support
modifications and deletion of records:
</p><pre class="screen">
storeData: 1
storeKeys: 1
</pre><p>
The general record type should be set to any record filter which
is able to parse <acronym class="acronym">XML</acronym> records, you may use any of the two
declarations (but not both simultaneously!)
</p><pre class="screen">
recordType: dom.filter_dom_conf.xml
# recordType: grs.xml
</pre><p>
Notice the difference to the specific instructions
</p><pre class="screen">
recordType.xml: dom.filter_dom_conf.xml
# recordType.xml: grs.xml
</pre><p>
which only work when indexing XML files from the filesystem using
the <code class="literal">*.xml</code> naming convention.
</p><p>
To enable transaction safe shadow indexing,
which is extra important for this kind of operation, set
</p><pre class="screen">
shadow: directoryname: size (e.g. 1000M)
</pre><p>
See <a class="xref" href="zebra-cfg.html" title="2.The Zebra Configuration File">Section2, “The <span class="application">Zebra</span> Configuration File”</a> for additional information on
these configuration options.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
It is not possible to carry information about record types or
similar to <span class="application">Zebra</span> when using extended services, due to
limitations of the <a class="ulink" href="https://www.loc.gov/z3950/agency/" target="_top"><acronym class="acronym">Z39.50</acronym></a>
protocol. Therefore, indexing filters can not be chosen on a
per-record basis. One and only one general <acronym class="acronym">XML</acronym> indexing filter
must be defined.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="administration-extended-services-z3950"></a>10.1.Extended services in the <acronym class="acronym">Z39.50</acronym> protocol</h3></div></div></div><p>
The <a class="ulink" href="https://www.loc.gov/z3950/agency/" target="_top"><acronym class="acronym">Z39.50</acronym></a> standard allows
servers to accept special binary <span class="emphasis"><em>extended services</em></span>
protocol packages, which may be used to insert, update and delete
records into servers. These carry control and update
information to the servers, which are encoded in seven package fields:
</p><div class="table"><a name="administration-extended-services-z3950-table"></a><p class="title"><b>Table6.1.Extended services <acronym class="acronym">Z39.50</acronym> Package Fields</b></p><div class="table-contents"><table class="table" summary="Extended services Z39.50 Package Fields" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Parameter</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><code class="literal">type</code></td><td><code class="literal">'update'</code></td><td>Must be set to trigger extended services</td></tr><tr><td><code class="literal">action</code></td><td><code class="literal">string</code></td><td>
Extended service action type with
one of four possible values: <code class="literal">recordInsert</code>,
<code class="literal">recordReplace</code>,
<code class="literal">recordDelete</code>,
and <code class="literal">specialUpdate</code>
</td></tr><tr><td><code class="literal">record</code></td><td><code class="literal"><acronym class="acronym">XML</acronym> string</code></td><td>An <acronym class="acronym">XML</acronym> formatted string containing the record</td></tr><tr><td><code class="literal">syntax</code></td><td><code class="literal">'xml'</code></td><td>XML/SUTRS/MARC. GRS-1 not supported.
The default filter (record type) as given by recordType in
zebra.cfg is used to parse the record.</td></tr><tr><td><code class="literal">recordIdOpaque</code></td><td><code class="literal">string</code></td><td>
Optional client-supplied, opaque record
identifier used under insert operations.
</td></tr><tr><td><code class="literal">recordIdNumber </code></td><td><code class="literal">positive number</code></td><td><span class="application">Zebra</span>'s internal system number,
not allowed for <code class="literal">recordInsert</code> or
<code class="literal">specialUpdate</code> actions which result in fresh
record inserts.
</td></tr><tr><td><code class="literal">databaseName</code></td><td><code class="literal">database identifier</code></td><td>
The name of the database to which the extended services should be
applied.
</td></tr></tbody></table></div></div><br class="table-break"><p>
The <code class="literal">action</code> parameter can be any of
<code class="literal">recordInsert</code> (will fail if the record already exists),
<code class="literal">recordReplace</code> (will fail if the record does not exist),
<code class="literal">recordDelete</code> (will fail if the record does not
exist), and
<code class="literal">specialUpdate</code> (will insert or update the record
as needed, record deletion is not possible).
</p><p>
During all actions, the
usual rules for internal record ID generation apply, unless an
optional <code class="literal">recordIdNumber</code> <span class="application">Zebra</span> internal ID or a
<code class="literal">recordIdOpaque</code> string identifier is assigned.
The default ID generation is
configured using the <code class="literal">recordId:</code> from
<code class="filename">zebra.cfg</code>.
See <a class="xref" href="zebra-cfg.html" title="2.The Zebra Configuration File">Section2, “The <span class="application">Zebra</span> Configuration File”</a>.
</p><p>
Setting of the <code class="literal">recordIdNumber</code> parameter,
which must be an existing <span class="application">Zebra</span> internal system ID number, is not
allowed during any <code class="literal">recordInsert</code> or
<code class="literal">specialUpdate</code> action resulting in fresh record
inserts.
</p><p>
When retrieving existing
records indexed with <acronym class="acronym">GRS-1</acronym> indexing filters, the <span class="application">Zebra</span> internal
ID number is returned in the field
<code class="literal">/*/id:idzebra/localnumber</code> in the namespace
<code class="literal">xmlns:id="https://www.indexdata.com/zebra/"</code>,
where it can be picked up for later record updates or deletes.
</p><p>
A new element set for retrieval of internal record
data has been added, which can be used to access minimal records
containing only the <code class="literal">recordIdNumber</code> <span class="application">Zebra</span>
internal ID, or the <code class="literal">recordIdOpaque</code> string
identifier. This works for any indexing filter used.
See <a class="xref" href="special-retrieval.html" title="4.Retrieval of Zebra internal record data">Section4, “Retrieval of <span class="application">Zebra</span> internal record data”</a>.
</p><p>
The <code class="literal">recordIdOpaque</code> string parameter
is an client-supplied, opaque record
identifier, which may be used under
insert, update and delete operations. The
client software is responsible for assigning these to
records. This identifier will
replace zebra's own automagic identifier generation with a unique
mapping from <code class="literal">recordIdOpaque</code> to the
<span class="application">Zebra</span> internal <code class="literal">recordIdNumber</code>.
<span class="emphasis"><em>The opaque <code class="literal">recordIdOpaque</code> string
identifiers
are not visible in retrieval records, nor are
searchable, so the value of this parameter is
questionable. It serves mostly as a convenient mapping from
application domain string identifiers to <span class="application">Zebra</span> internal ID's.
</em></span>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="administration-extended-services-yaz-client"></a>10.2.Extended services from yaz-client</h3></div></div></div><p>
We can now start a yaz-client admin session and create a database:
</p><pre class="screen">
$ yaz-client localhost:9999 -u admin/secret
Z> adm-create
</pre><p>
Now the <code class="literal">Default</code> database was created,
we can insert an <acronym class="acronym">XML</acronym> file (esdd0006.grs
from example/gils/records) and index it:
</p><pre class="screen">
Z> update insert id1234 esdd0006.grs
</pre><p>
The 3rd parameter - <code class="literal">id1234</code> here -
is the <code class="literal">recordIdOpaque</code> package field.
</p><p>
Actually, we should have a way to specify "no opaque record id" for
yaz-client's update command.. We'll fix that.
</p><p>
The newly inserted record can be searched as usual:
</p><pre class="screen">
Z> f utah
Sent searchRequest.
Received SearchResponse.
Search was a success.
Number of hits: 1, setno 1
SearchResult-1: term=utah cnt=1
records returned: 0
Elapsed: 0.014179
</pre><p>
</p><p>
Let's delete the beast, using the same
<code class="literal">recordIdOpaque</code> string parameter:
</p><pre class="screen">
Z> update delete id1234
No last record (update ignored)
Z> update delete 1 esdd0006.grs
Got extended services response
Status: done
Elapsed: 0.072441
Z> f utah
Sent searchRequest.
Received SearchResponse.
Search was a success.
Number of hits: 0, setno 2
SearchResult-1: term=utah cnt=0
records returned: 0
Elapsed: 0.013610
</pre><p>
</p><p>
If shadow register is enabled in your
<code class="filename">zebra.cfg</code>,
you must run the adm-commit command
</p><pre class="screen">
Z> adm-commit
</pre><p>
after each update session in order write your changes from the
shadow to the life register space.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="administration-extended-services-yaz-php"></a>10.3.Extended services from yaz-php</h3></div></div></div><p>
Extended services are also available from the <span class="application">YAZ</span> <acronym class="acronym">PHP</acronym> client layer. An
example of an <span class="application">YAZ</span>-<acronym class="acronym">PHP</acronym> extended service transaction is given here:
</p><pre class="screen">
$record = '<record><title>A fine specimen of a record</title></record>';
$options = array('action' => 'recordInsert',
'syntax' => 'xml',
'record' => $record,
'databaseName' => 'mydatabase'
);
yaz_es($yaz, 'update', $options);
yaz_es($yaz, 'commit', array());
yaz_wait();
if ($error = yaz_error($yaz))
echo "$error";
</pre><p>
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="administration-extended-services-debugging"></a>10.4.Extended services debugging guide</h3></div></div></div><p>
When debugging ES over PHP we recommend the following order of tests:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Make sure you have a nice record on your filesystem, which you can
index from the filesystem by use of the zebraidx command.
Do it exactly as you planned, using one of the GRS-1 filters,
or the DOMXML filter.
When this works, proceed.
</p></li><li class="listitem"><p>
Check that your server setup is OK before you even coded one single
line PHP using ES.
Take the same record form the file system, and send as ES via
<code class="literal">yaz-client</code> like described in
<a class="xref" href="administration-extended-services.html#administration-extended-services-yaz-client" title="10.2.Extended services from yaz-client">Section10.2, “Extended services from yaz-client”</a>,
and
remember the <code class="literal">-a</code> option which tells you what
goes over the wire! Notice also the section on permissions:
try
</p><pre class="screen">
perm.anonymous: rw
</pre><p>
in <code class="literal">zebra.cfg</code> to make sure you do not run into
permission problems (but never expose such an insecure setup on the
internet!!!). Then, make sure to set the general
<code class="literal">recordType</code> instruction, pointing correctly
to the GRS-1 filters,
or the DOMXML filters.
</p></li><li class="listitem"><p>
If you insist on using the <code class="literal">sysno</code> in the
<code class="literal">recordIdNumber</code> setting,
please make sure you do only updates and deletes. Zebra's internal
system number is not allowed for
<code class="literal">recordInsert</code> or
<code class="literal">specialUpdate</code> actions
which result in fresh record inserts.
</p></li><li class="listitem"><p>
If <code class="literal">shadow register</code> is enabled in your
<code class="literal">zebra.cfg</code>, you must remember running the
</p><pre class="screen">
Z> adm-commit
</pre><p>
command as well.
</p></li><li class="listitem"><p>
If this works, then proceed to do the same thing in your PHP script.
</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="administration-ranking.html">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="administration.html">Up</a></td><td width="40%" align="right"><a accesskey="n" href="record-model-domxml.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.Relevance Ranking and Sorting of Result Sets</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">Chapter7.<acronym class="acronym">DOM</acronym> <acronym class="acronym">XML</acronym> Record Model and Filter Module</td></tr></table></div></body></html>
|
