X-Git-Url: http://git.indexdata.com/?p=idzebra-moved-to-github.git;a=blobdiff_plain;f=doc%2Fadministration.xml;h=762ba7db9f2dea232dfc8d6f2106713b6272652c;hp=7303d30a4dc637a73207c1de70a78440714f34b2;hb=99842ec71f065fd6886daa355923b01d9ce71d26;hpb=558bf94a5f36eb89b0ca7ac4780b641da852c36b diff --git a/doc/administration.xml b/doc/administration.xml index 7303d30..762ba7d 100644 --- a/doc/administration.xml +++ b/doc/administration.xml @@ -1,6 +1,5 @@ - - Administrating Zebra + Administrating &zebra; - Unlike many simpler retrieval systems, Zebra supports safe, incremental + Unlike many simpler retrieval systems, &zebra; supports safe, incremental updates to an existing index. - Normally, when Zebra modifies the index it reads a number of records + Normally, when &zebra; modifies the index it reads a number of records that you specify. Depending on your specifications and on the contents of each record one the following events take place for each record: @@ -25,8 +24,8 @@ The record is indexed as if it never occurred before. - Either the Zebra system doesn't know how to identify the record or - Zebra can identify the record but didn't find it to be already indexed. + Either the &zebra; system doesn't know how to identify the record or + &zebra; can identify the record but didn't find it to be already indexed. @@ -53,20 +52,20 @@ - Please note that in both the modify- and delete- case the Zebra + Please note that in both the modify- and delete- case the &zebra; indexer must be able to generate a unique key that identifies the record in question (more on this below). - To administrate the Zebra retrieval system, you run the + To administrate the &zebra; retrieval system, you run the zebraidx program. This program supports a number of options which are preceded by a dash, and a few commands (not preceded by dash). - Both the Zebra administrative tool and the Z39.50 server share a + Both the &zebra; administrative tool and the &acro.z3950; server share a set of index files and a global configuration file. The name of the configuration file defaults to zebra.cfg. @@ -85,7 +84,7 @@ Indexing is a per-record process, in which either insert/modify/delete will occur. Before a record is indexed search keys are extracted from whatever might be the layout the original record (sgml,html,text, etc..). - The Zebra system currently supports two fundamental types of records: + The &zebra; system currently supports two fundamental types of records: structured and simple text. To specify a particular extraction process, use either the command line option -t or specify a @@ -94,11 +93,11 @@ - - The Zebra Configuration File + + The &zebra; Configuration File - The Zebra configuration file, read by zebraidx and + The &zebra; configuration file, read by zebraidx and zebrasrv defaults to zebra.cfg unless specified by -c option. @@ -127,7 +126,7 @@ In the configuration file, the group name is placed before the option name itself, separated by a dot (.). For instance, to set the record type for group public to grs.sgml - (the SGML-like format for structured records) you would write: + (the &acro.sgml;-like format for structured records) you would write: @@ -195,7 +194,7 @@ database - Specifies the Z39.50 database name. + Specifies the &acro.z3950; database name. @@ -220,10 +219,10 @@ Specifies whether the records should be stored internally - in the Zebra system files. + in the &zebra; system files. If you want to maintain the raw records yourself, this option should be false (0). - If you want Zebra to take care of the records for you, it + If you want &zebra; to take care of the records for you, it should be true(1). @@ -233,7 +232,7 @@ register: register-location - Specifies the location of the various register files that Zebra uses + Specifies the location of the various register files that &zebra; uses to represent your databases. See . @@ -243,7 +242,7 @@ shadow: register-location - Enables the safe update facility of Zebra, and + Enables the safe update facility of &zebra;, and tells the system where to place the required, temporary files. See . @@ -281,20 +280,93 @@ Specifies a path of profile specification files. The path is composed of one or more directories separated by - colon. Similar to PATH for UNIX systems. + colon. Similar to PATH for UNIX systems. + + + modulePath: path + + + Specifies a path of record filter modules. + The path is composed of one or more directories separated by + colon. Similar to PATH for UNIX systems. + The 'make install' procedure typically puts modules in + /usr/local/lib/idzebra-2.0/modules. + + + + + + index: filename + + + Defines the filename which holds fields structure + definitions. If omitted, the file default.idx + is read. + Refer to for + more information. + + + + + + sortmax: integer + + + Specifies the maximum number of records that will be sorted + in a result set. If the result set contains more than + integer records, records after the + limit will not be sorted. If omitted, the default value is + 1,000. + + + + + + staticrank: integer + + + Enables whether static ranking is to be enabled (1) or + disabled (0). If omitted, it is disabled - corresponding + to a value of 0. + Refer to . + + + + + + + estimatehits: integer + + + Controls whether &zebra; should calculate approximate hit counts and + at which hit count it is to be enabled. + A value of 0 disables approximate hit counts. + For a positive value approximate hit count is enabled + if it is known to be larger than integer. + + + Approximate hit counts can also be triggered by a particular + attribute in a query. + Refer to . + + + + attset: filename - Specifies the filename(s) of attribute set files for use in - searching. At least the Bib-1 set should be loaded - (bib1.att). - The profilePath setting is used to look for - the specified files. - See + Specifies the filename(s) of attribute set files for use in + searching. In many configurations bib1.att + is used, but that is not required. If Classic Explain + attributes is to be used for searching, + explain.att must be given. + The path to att-files in general can be given using + profilePath setting. + See also . @@ -326,9 +398,9 @@ root: dir - Specifies a directory base for Zebra. All relative paths + Specifies a directory base for &zebra;. All relative paths given (in profilePath, register, shadow) are based on this - directory. This setting is useful if your Zebra server + directory. This setting is useful if your &zebra; server is running in a different directory from where zebra.cfg is located. @@ -339,7 +411,7 @@ passwd: file - Specifies a file with description of user accounts for Zebra. + Specifies a file with description of user accounts for &zebra;. The format is similar to that known to Apache's htpasswd files and UNIX' passwd files. Non-empty lines not beginning with # are considered account lines. There is one account per-line. @@ -353,10 +425,10 @@ passwd.c: file - Specifies a file with description of user accounts for Zebra. + Specifies a file with description of user accounts for &zebra;. File format is similar to that used by the passwd directive except that the password are encrypted. Use Apache's htpasswd or similar - for maintenanace. + for maintenance. @@ -366,27 +438,68 @@ permstring - Specifies permissions (priviledge) for a user that are allowed - to access Zebra via the passwd system. There are two kinds + Specifies permissions (privilege) for a user that are allowed + to access &zebra; via the passwd system. There are two kinds of permissions currently: read (r) and write(w). By default users not listed in a permission directive are given the read - priviledge. To specify permissions for a user with no - username, or Z39.50 anonymous style use + privilege. To specify permissions for a user with no + username, or &acro.z3950; anonymous style use anonymous. The permstring consists of a sequence of characters. Include character w - for write/update access, r for read access. + for write/update access, r for read access and + a to allow anonymous access through this account. - dbaccess accessfile + dbaccess: accessfile Names a file which lists database subscriptions for individual users. - The access file should consists of lines of the form username: - dbnames, where dbnames is a list of database names, seprated by - '+'. No whitespace is allowed in the database list. + The access file should consists of lines of the form + username: dbnames, where dbnames is a list of + database names, separated by '+'. No whitespace is allowed in the + database list. + + + + + + encoding: charsetname + + + Tells &zebra; to interpret the terms in Z39.50 queries as + having been encoded using the specified character + encoding. The default is ISO-8859-1; one + useful alternative is UTF-8. + + + + + + storeKeys: value + + + Specifies whether &zebra; keeps a copy of indexed keys. + Use a value of 1 to enable; 0 to disable. If storeKeys setting is + omitted, it is enabled. Enabled storeKeys + are required for updating and deleting records. Disable only + storeKeys to save space and only plan to index data once. + + + + + + storeData: value + + + Specifies whether &zebra; keeps a copy of indexed records. + Use a value of 1 to enable; 0 to disable. If storeData setting is + omitted, it is enabled. A storeData setting of 0 (disabled) makes + Zebra fetch records from the original locaction in the file + system using filename, file offset and file length. For the + DOM and ALVIS filter, the storeData setting is ignored. @@ -400,7 +513,7 @@ Locating Records - The default behavior of the Zebra system is to reference the + The default behavior of the &zebra; system is to reference the records from their original location, i.e. where they were found when you run zebraidx. That is, when a client wishes to retrieve a record @@ -415,9 +528,9 @@ If your input files are not permanent - for example if you retrieve your records from an outside source, or if they were temporarily mounted on a CD-ROM drive, - you may want Zebra to make an internal copy of them. To do this, + you may want &zebra; to make an internal copy of them. To do this, you specify 1 (true) in the storeData setting. When - the Z39.50 server retrieves the records they will be read from the + the &acro.z3950; server retrieves the records they will be read from the internal file structures of the system. @@ -446,7 +559,7 @@ Consider a system in which you have a group of text files called simple. - That group of records should belong to a Z39.50 database called + That group of records should belong to a &acro.z3950; database called textbase. The following zebra.cfg file will suffice: @@ -509,7 +622,7 @@ To enable indexing with pathname IDs, you must specify file as the value of recordId in the configuration file. In addition, you should set - storeKeys to 1, since the Zebra + storeKeys to 1, since the &zebra; indexer must save additional information about the contents of each record in order to modify the indexes correctly at a later time. @@ -539,7 +652,7 @@ You cannot start out with a group of records with simple indexing (no record IDs as in the previous section) and then later - enable file record Ids. Zebra must know from the first time that you + enable file record Ids. &zebra; must know from the first time that you index the group that the files should be indexed with file record IDs. @@ -565,7 +678,7 @@ information. If you have a group of records that explicitly associates an ID with each record, this method is convenient. For example, the record format may contain a title or a ID-number - unique within the group. - In either case you specify the Z39.50 attribute set and use-attribute + In either case you specify the &acro.z3950; attribute set and use-attribute location in which this information is stored, and the system looks at that field to determine the identity of the record. @@ -650,9 +763,9 @@ - For instance, the sample GILS records that come with the Zebra + For instance, the sample GILS records that come with the &zebra; distribution contain a unique ID in the data tagged Control-Identifier. - The data is mapped to the Bib-1 use attribute Identifier-standard + The data is mapped to the &acro.bib1; use attribute Identifier-standard (code 1007). To use this field as a record id, specify (bib1,Identifier-standard) as the value of the recordId in the configuration file. @@ -669,7 +782,7 @@ - (see + (see for details of how the mapping between elements of your records and searchable attributes is established). @@ -704,7 +817,7 @@ zebraidx. If you wish to store these, possibly large, files somewhere else, you must add the register entry to the zebra.cfg file. - Furthermore, the Zebra system allows its file + Furthermore, the &zebra; system allows its file structures to span multiple file systems, which is useful for managing very large databases. @@ -713,13 +826,11 @@ The value of the register setting is a sequence of tokens. Each token takes the form: - - dir:size. - + dir:size The dir specifies a directory in which index files will be stored and the size specifies the maximum - size of all files in that directory. The Zebra indexer system fills + size of all files in that directory. The &zebra; indexer system fills each directory in the order specified and use the next specified directories as needed. The size is an integer followed by a qualifier @@ -728,28 +839,30 @@ k for kilobytes. M for megabytes, G for gigabytes. + Specifying a negative value disables the checking (it still needs the unit, + use -1b). - For instance, if you have allocated two disks for your register, and + For instance, if you have allocated three disks for your register, and the first disk is mounted - on /d1 and has 2GB of free space and the - second, mounted on /d2 has 3.6 GB, you could - put this entry in your configuration file: + on /d1 and has 2GB of free space, the + second, mounted on /d2 has 3.6 GB, and the third, + on which you have more space than you bother to worry about, mounted on + /d3 you could put this entry in your configuration file: - register: /d1:2G /d2:3600M + register: /d1:2G /d2:3600M /d3:-1b - - Note that Zebra does not verify that the amount of space specified is + Note that &zebra; does not verify that the amount of space specified is actually available on the directory (file system) specified - it is your responsibility to ensure that enough space is available, and that other applications do not attempt to use the free space. In a large production system, it is recommended that you allocate one or more - file system exclusively to the Zebra register files. + file system exclusively to the &zebra; register files. @@ -757,13 +870,13 @@ Safe Updating - Using Shadow Registers - + Description - The Zebra server supports updating of the index + The &zebra; server supports updating of the index structures. That is, you can add, modify, or remove records from - databases managed by Zebra without rebuilding the entire index. + databases managed by &zebra; without rebuilding the entire index. Since this process involves modifying structured files with various references between blocks of data in the files, the update process is inherently sensitive to system crashes, or to process interruptions: @@ -778,7 +891,7 @@ You can solve these problems by enabling the shadow register system in - Zebra. + &zebra;. During the updating procedure, zebraidx will temporarily write changes to the involved files in a set of "shadow files", without modifying the files that are accessed by the @@ -811,7 +924,7 @@ - + How to Use Shadow Register Files @@ -925,11 +1038,11 @@ Relevance Ranking and Sorting of Result Sets - + Overview The default ordering of a result set is left up to the server, - which inside Zebra means sorting in ascending document ID order. + which inside &zebra; means sorting in ascending document ID order. This is not always the order humans want to browse the sometimes quite large hit sets. Ranking and sorting comes to the rescue. @@ -948,7 +1061,7 @@ Simply put, dynamic relevance ranking sorts a set of retrieved records such that those most likely to be relevant to your request are retrieved first. - Internally, Zebra retrieves all documents that satisfy your + Internally, &zebra; retrieves all documents that satisfy your query, and re-orders the hit list to arrange them based on a measurement of similarity between your query and the content of each record. @@ -967,7 +1080,7 @@ Static Ranking - Zebra uses internally inverted indexes to look up term occurencies + &zebra; uses internally inverted indexes to look up term frequencies in documents. Multiple queries from different indexes can be combined by the binary boolean operations AND, OR and/or NOT (which @@ -989,7 +1102,7 @@ staticrank: 1 - directive in the main core Zebra configuration file, the internal document + directive in the main core &zebra; configuration file, the internal document keys used for ordering are augmented by a preceding integer, which contains the static rank of a given document, and the index lists are ordered @@ -1001,7 +1114,7 @@ The experimental alvis filter provides a - directive to fetch static rank information out of the indexed XML + directive to fetch static rank information out of the indexed &acro.xml; records, thus making all hit sets ordered after ascending static rank, and for those doc's which have the same static rank, ordered @@ -1038,31 +1151,31 @@ indexing time (this is why we call it ``dynamic ranking'' in the first place ...) It is invoked by adding - the Bib-1 relation attribute with - value ``relevance'' to the PQF query (that is, + the &acro.bib1; relation attribute with + value ``relevance'' to the &acro.pqf; query (that is, @attr 2=102, see also - The BIB-1 Attribute Set Semantics, also in + The &acro.bib1; Attribute Set Semantics, also in HTML). To find all articles with the word Eoraptor in - the title, and present them relevance ranked, issue the PQF query: + the title, and present them relevance ranked, issue the &acro.pqf; query: @attr 2=102 @attr 1=4 Eoraptor - Dynamically ranking using PQF queries with the 'rank-1' + <title>Dynamically ranking using &acro.pqf; queries with the 'rank-1' algorithm The default rank-1 ranking module implements a TF/IDF (Term Frequecy over Inverse Document Frequency) like - algorithm. In contrast to the usual defintion of TF/IDF + algorithm. In contrast to the usual definition of TF/IDF algorithms, which only considers searching in one full-text index, this one works on multiple indexes at the same time. More precisely, - Zebra does boolean queries and searches in specific addressed + &zebra; does boolean queries and searches in specific addressed indexes (there are inverted indexes pointing from terms in the dictionary to documents and term positions inside documents). It works like this: @@ -1071,7 +1184,7 @@ Query Components - First, the boolean query is dismantled into it's principal components, + First, the boolean query is dismantled into its principal components, i.e. atomic queries where one term is looked up in one index. For example, the query @@ -1119,7 +1232,7 @@ It is possible to apply dynamic ranking on only parts of the - PQF query: + &acro.pqf; query: @and @attr 2=102 @attr 1=1010 Utah @attr 1=1018 Springer @@ -1154,7 +1267,7 @@ Ranking weights may be used to pass a value to a ranking - algorithm, using the non-standard BIB-1 attribute type 9. + algorithm, using the non-standard &acro.bib1; attribute type 9. This allows one branch of a query to use one value while another branch uses a different one. For example, we can search for utah in the @@ -1166,7 +1279,7 @@ The default weight is - sqrt(1000) ~ 34 , as the Z39.50 standard prescribes that the top score + sqrt(1000) ~ 34 , as the &acro.z3950; standard prescribes that the top score is 1000 and the bottom score is 0, encoded in integers. @@ -1288,11 +1401,10 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci with or without static ranking enabled. - - @@ -1332,27 +1443,28 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci mitaylor2microsoft.com --> + - Dynamically ranking CQL queries + Dynamically ranking &acro.cql; queries - Dynamic ranking can be enabled during sever side CQL + Dynamic ranking can be enabled during sever side &acro.cql; query expansion by adding @attr 2=102 - chunks to the CQL config file. For example + chunks to the &acro.cql; config file. For example relationModifier.relevant = 2=102 - invokes dynamic ranking each time a CQL query of the form + invokes dynamic ranking each time a &acro.cql; query of the form Z> querytype cql Z> f alvis.text =/relevant house is issued. Dynamic ranking can also be automatically used on - specific CQL indexes by (for example) setting + specific &acro.cql; indexes by (for example) setting index.alvis.text = 1=text 2=102 - which then invokes dynamic ranking each time a CQL query of the form + which then invokes dynamic ranking each time a &acro.cql; query of the form Z> querytype cql Z> f alvis.text = house @@ -1368,10 +1480,10 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci Sorting - Zebra sorts efficiently using special sorting indexes + &zebra; sorts efficiently using special sorting indexes (type=s; so each sortable index must be known at indexing time, specified in the configuration of record - indexing. For example, to enable sorting according to the BIB-1 + indexing. For example, to enable sorting according to the &acro.bib1; Date/time-added-to-db field, one could add the line xelm /*/@created Date/time-added-to-db:s @@ -1388,8 +1500,8 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci Indexing can be specified at searching time using a query term carrying the non-standard - BIB-1 attribute-type 7. This removes the - need to send a Z39.50 Sort Request + &acro.bib1; attribute-type 7. This removes the + need to send a &acro.z3950; Sort Request separately, and can dramatically improve latency when the client and server are on separate networks. The sorting part of the query is separate from the rest of the @@ -1398,7 +1510,7 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci A sorting subquery needs two attributes: an index (such as a - BIB-1 type-1 attribute) specifying which index to sort on, and a + &acro.bib1; type-1 attribute) specifying which index to sort on, and a type-7 attribute whose value is be 1 for ascending sorting, or 2 for descending. The term associated with the sorting attribute is the priority of @@ -1407,7 +1519,7 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci on. For example, a search for water, sort by title (ascending), - is expressed by the PQF query + is expressed by the &acro.pqf; query @or @attr 1=1016 water @attr 7=1 @attr 1=4 0 @@ -1436,26 +1548,237 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci Extended Services: Remote Insert, Update and Delete + + + Extended services are only supported when accessing the &zebra; + server using the &acro.z3950; + protocol. The &acro.sru; protocol does + not support extended services. + + + The extended services are not enabled by default in zebra - due to the - fact that they modify the system. - In order to allow anybody to update, use - - perm.anonymous: rw - + fact that they modify the system. &zebra; can be configured + to allow anybody to + search, and to allow only updates for a particular admin user in the main zebra configuration file zebra.cfg. - Or, even better, allow only updates for a particular admin user. For - user admin, you could use: + For user admin, you could use: + perm.anonymous: r perm.admin: rw passwd: passwordfile - And in passwordfile, specify users and - passwords as colon seperated strings: + And in the password file + passwordfile, you have to specify users and + encrypted passwords as colon separated strings. + Use a tool like htpasswd + to maintain the encrypted passwords. admin:secret + + It is essential to configure &zebra; to store records internally, + and to support + modifications and deletion of records: + + storeData: 1 + storeKeys: 1 + + The general record type should be set to any record filter which + is able to parse &acro.xml; records, you may use any of the two + declarations (but not both simultaneously!) + + recordType: dom.filter_dom_conf.xml + # recordType: grs.xml + + Notice the difference to the specific instructions + + recordType.xml: dom.filter_dom_conf.xml + # recordType.xml: grs.xml + which only work when indexing XML files from the filesystem using + the *.xml naming convention. + + + To enable transaction safe shadow indexing, + which is extra important for this kind of operation, set + + shadow: directoryname: size (e.g. 1000M) + + See for additional information on + these configuration options. + + + + It is not possible to carry information about record types or + similar to &zebra; when using extended services, due to + limitations of the &acro.z3950; + protocol. Therefore, indexing filters can not be chosen on a + per-record basis. One and only one general &acro.xml; indexing filter + must be defined. + + + + + + + + Extended services in the &acro.z3950; protocol + + + The &acro.z3950; standard allows + servers to accept special binary extended services + 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: + + + + Extended services &acro.z3950; Package Fields + + + + Parameter + Value + Notes + + + + + type + 'update' + Must be set to trigger extended services + + + action + string + + Extended service action type with + one of four possible values: recordInsert, + recordReplace, + recordDelete, + and specialUpdate + + + + record + &acro.xml; string + An &acro.xml; formatted string containing the record + + + syntax + 'xml' + 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. + + + recordIdOpaque + string + + Optional client-supplied, opaque record + identifier used under insert operations. + + + + recordIdNumber + positive number + &zebra;'s internal system number, + not allowed for recordInsert or + specialUpdate actions which result in fresh + record inserts. + + + + databaseName + database identifier + + The name of the database to which the extended services should be + applied. + + + + +
+ + + + The action parameter can be any of + recordInsert (will fail if the record already exists), + recordReplace (will fail if the record does not exist), + recordDelete (will fail if the record does not + exist), and + specialUpdate (will insert or update the record + as needed, record deletion is not possible). + + + During all actions, the + usual rules for internal record ID generation apply, unless an + optional recordIdNumber &zebra; internal ID or a + recordIdOpaque string identifier is assigned. + The default ID generation is + configured using the recordId: from + zebra.cfg. + See . + + + + Setting of the recordIdNumber parameter, + which must be an existing &zebra; internal system ID number, is not + allowed during any recordInsert or + specialUpdate action resulting in fresh record + inserts. + + + + When retrieving existing + records indexed with &acro.grs1; indexing filters, the &zebra; internal + ID number is returned in the field + /*/id:idzebra/localnumber in the namespace + xmlns:id="http://www.indexdata.dk/zebra/", + where it can be picked up for later record updates or deletes. + + + + A new element set for retrieval of internal record + data has been added, which can be used to access minimal records + containing only the recordIdNumber &zebra; + internal ID, or the recordIdOpaque string + identifier. This works for any indexing filter used. + See . + + + + The recordIdOpaque 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 recordIdOpaque to the + &zebra; internal recordIdNumber. + The opaque recordIdOpaque 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 &zebra; internal ID's. + + + + + + + Extended services from yaz-client + We can now start a yaz-client admin session and create a database: @@ -1465,18 +1788,15 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci ]]> Now the Default database was created, - we can insert an XML file (esdd0006.grs + we can insert an &acro.xml; file (esdd0006.grs from example/gils/records) and index it: update insert 1 esdd0006.grs + Z> update insert id1234 esdd0006.grs ]]> - The 3rd parameter - 1 here - - is the opaque record ID from Ext update. - It a record ID that we assign to the record - in question. If we do not - assign one, the usual rules for match apply (recordId: from zebra.cfg). + The 3rd parameter - id1234 here - + is the recordIdOpaque package field. Actually, we should have a way to specify "no opaque record id" for @@ -1498,10 +1818,11 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci - Let's delete the beast: + Let's delete the beast, using the same + recordIdOpaque string parameter: update delete 1 + Z> update delete id1234 No last record (update ignored) Z> update delete 1 esdd0006.grs Got extended services response @@ -1530,9 +1851,15 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci after each update session in order write your changes from the shadow to the life register space. + + + + + Extended services from yaz-php + - Extended services are also available from the YAZ client layer. An - example of an YAZ-PHP extended service transaction is given here: + Extended services are also available from the &yaz; &acro.php; client layer. An + example of an &yaz;-&acro.php; extended service transaction is given here: A fine specimen of a record'; @@ -1551,51 +1878,80 @@ where g = rset_count(terms[i]->rset) is the count of all documents in this speci echo "$error"; ]]> - The action parameter can be any of - recordInsert (will fail if the record already exists), - recordReplace (will fail if the record does not exist), - recordDelete (will fail if the record does not - exist), and - specialUpdate (will insert or update the record - as needed). - - - If a record is inserted - using the action recordInsert - one can specify the optional - recordIdOpaque parameter, which is a - client-supplied, opaque record identifier. This identifier will - replace zebra's own automagic identifier generation. - - - When using the action recordReplace or - recordDelete, one must specify the additional - recordIdNumber parameter, which must be an - existing Zebra internal system ID number. When retrieving existing - records, the ID number is returned in the field - /*/id:idzebra/localnumber in the namespace - xmlns:id="http://www.indexdata.dk/zebra/", - where it can be picked up for later record updates or deletes. - - - + + - - YAZ Frontend Virtual Hosts + + Extended services debugging guide - zebrasrv uses the YAZ server frontend and does - support multiple virtual servers behind multiple listening sockets. + When debugging ES over PHP we recommend the following order of tests: - &zebrasrv-virtual; - - - Section "Virtual Hosts" in the YAZ manual. - http://www.indexdata.dk/yaz/doc/server.vhosts.tkl - - + + + + + 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. + + + + + 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 + yaz-client like described in + , + and + remember the -a option which tells you what + goes over the wire! Notice also the section on permissions: + try + + perm.anonymous: rw + + in zebra.cfg 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 + recordType instruction, pointing correctly + to the GRS-1 filters, + or the DOMXML filters. + + + + + If you insist on using the sysno in the + recordIdNumber setting, + please make sure you do only updates and deletes. Zebra's internal + system number is not allowed for + recordInsert or + specialUpdate actions + which result in fresh record inserts. + + + + + If shadow register is enabled in your + zebra.cfg, you must remember running the + + Z> adm-commit + + command as well. + + + + + If this works, then proceed to do the same thing in your PHP script. + + + - + + + +