The Z39.50 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:

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 the section called “The Zebra Configuration File”.

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 GRS-1 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 section called “Retrieval of Zebra internal record data”.

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.

We can now start a yaz-client admin session and create a database:

    
     $ yaz-client localhost:9999 -u admin/secret
     Z> adm-create
     
   

Now the Default database was created, we can insert an XML file (esdd0006.grs from example/gils/records) and index it:

  
    
     Z> update insert id1234 esdd0006.grs
     
   

The 3rd parameter - id1234 here - is the recordIdOpaque package field.

Actually, we should have a way to specify "no opaque record id" for yaz-client's update command.. We'll fix that.

The newly inserted record can be searched as usual:

    
     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
     
    

Let's delete the beast, using the same recordIdOpaque string parameter:

    
     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
     
     

If shadow register is enabled in your zebra.cfg, you must run the adm-commit command

    
     Z> adm-commit
     
    

after each update session in order write your changes from the shadow to the life register space.

Extended services are also available from the YAZ PHP client layer. An example of an YAZ-PHP extended service transaction is given here:

    
     $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";
     
    

When debugging ES over PHP we recomment the following order of tests: