Union Catalogue Profile
Internationally Registered Profile to be used with ISO 23950
(Z39.50 Information Retrieval Protocol) Extended Service for Update
Last updated June 1999
This Profile is intended for use with the ISO 23950 (Z39.50 Information Retrieval Protocol) standard to allow a data creator to update a database in a distributed environment using the Database Update Extended Service of the standard.
It was developed under the auspices of the IT/19 Committee (a joint committee of Standards Australia and Standards New Zealand) by Janifer Gatenby from Stowe Computing Australia (now GEAC Computing) and Lesley Bezear and Judith Pearce from the National Library of Australia.
Table of Contents
1. Introduction
2. Record
Insert
3. Record Replace
4. Element Update
5. Record
Delete
6. Special Update
7. Record Locking
8. Querying the
Task Package
9. Diagnostic List
10. Notes on Other Areas of Z39.50
11. Conformance
12. Document
History
Appendix 1: Scenarios
Appendix 2: References
Appendix 3: Staged
Base-Level Conformance
Appendix 4: Holdings
Scenarios
1. Introduction
1.1 Overview
This Profile is intended for use with the ISO 23950 (Z39.50 Information Retrieval Protocol) standard to allow a data creator to update a database in a distributed environment using the Database Update Extended Service of the standard.
The Z39.50 standard specifies the formats and procedures for the exchange of messages when an origin searches a target database and retrieves records. This includes formats and procedures for initialising a Z39.50 session and for control by the target of access, and other procedures related to the management of a search and retrieval session.
The Z39.50 Database Update Extended Service specifies the formats and procedures for the exchange of messages when, at some point after initialising a Z39.50 session, the origin requests that the target update a database. The target decides whether and when to initiate the appropriate database operation to complete the task. The task itself is not considered part of the Extended Service operation. The response from the target which completes the operation does not necessarily signal completion of the task, which may have a lifetime beyond the Z39.50 association.
The justification for incorporating update as an extension to a standard for search and retrieval is based on the recognition that the update function is often dependent on searching. Database searches are frequently done at several stages in the update process, for example a preliminary search to determine whether a record already exists, followed by the decision to create or copy a record. The database may also be searched during creation or update of a record, to check related data.
The need for this profile to assist implementors of the Z39.50 Database Update Extended Service originated from work by Janifer Gatenby from Stowe Computing Australia (now GEAC Computing) and Lesley Bezear and Judith Pearce from the National Library of Australia under the auspices of the IT/19 Committee, a joint committee of Standards Australia and Standards New Zealand.
The National Library of Australia operates a national union catalogue which is maintained as a cooperative effort by the Australian library community. Libraries add holdings and original cataloguing data to the union catalogue as part of the process of obtaining records for their local library management systems.
The aim of the work team was to identify a suitable protocol for integrating maintenance of the union catalogue into creator workflows in such a way that creators could perform all creation/ update processes within their own workstation/ systems environment using local client software. The Z39.50 standard was found to be suitable for this purpose. Australian libraries have begun increasingly to use Z39.50 client software for obtaining copy cataloguing data from external databases. With a few minor exceptions, the standard already contains the full range of functionality for developers to enhance this process to enable updating of the union catalogue and the local system at the same time.
While the Z39.50 Database Update Extended Service is rich in update functionality and enables update to be integrated fully with searching, decisions as to how specific update functions might be implemented are left open in the standard. This profile identifies appropriate options and parameters for accomplishing the full range of update functions required to be supported in the union catalogue environment.
To the extent that it provides a generic framework for database update, the profile should be of use to any implementor of the Z39.50 Database Update Extended Service. It supplements the base standard by clarifying the differences between the Z39.50 record insert, record replace and element update actions and the conditions under which each should be used. It also defines procedures for addressing a range of update scenarios not addressed specifically by the base standard. These include:
- Addressing concurrent update through version control alone, or through record locking via the update schema.
- Exchanging messages relating to duplicate detection and control.
- Reviewing submitted records.
- Merging linked records when a duplicate record is deleted.
- Performing batch edit / replaces.
A comprehensive list of diagnostic messages is also included in the profile as an adjunct to those in the base standard.
1.2 Area of Use
For libraries and library system vendors, the major area of use for this profile will be the provision of support for a range of business transactions requiring a library to update a national union catalogue, and/or a consortium catalogue, at the same time as updating its local catalogues. In the Internet environment, union catalogues are still a very efficient location tool. Since multi-target searches strike performance degradation as the number of target databases increase, such searches are inferior in coverage to a union catalogue search and the results may not be subjected to duplicate or authority control.
Features of the profile specific to union catalogue implementations are:
- The conformance tables.
- The logical databases needing to be supported (limited to bibliographic, authority and holdings databases in MARC format).
- The business transactions needing to be supported (these are listed in Appendix 1).
There are significant benefits for libraries and developers in using this profile to support update in a union catalogue environment:
· Reduced training costs and increased productivity. The data creator only has to be familiar with one user interface.
· Efficiencies in local software maintenance and configuration. As organisations migrate to client/ server applications, multiple clients will not have to be installed at the user's desktop to support access to both the local system and the union catalogue.
· Increased modularity. Use of Z39.50 as the internal protocol for searching and update will allow modular development and opportunities for product substitution.
· Client/ server access to legacy databases. Legacy databases can be made accessible and updatable as Z39.50 targets without needing to upgrade the underlying database management system.
· Increased data security. Since the targets interaction with the origin involves only receipt and delivery of protocol transactions, the origin is prevented from directly initiating update programs on the target and thus has no access to an operating system command line.
· Update of multiple databases with less effort. At present, when an organisation wishes to update multiple databases, the organisation is generally obliged to do this through a multistep process. In some cases, local data is selected for extraction in batches and then sent to an external database. In other cases, the data is first created on the external database and later extracted and sent to the local database. More complex cases also occur, where for instance creation occurs on one system but changes occur on both systems, with corresponding effort in keeping the databases synchronised. Use of the Profile avoids this duplication of effort and complexity through allowing a single transaction to update multiple databases.
· More timely update. The Profile allows virtually real-time update of multiple databases and virtually immediate resolution by the origin of any errors or rejections. It also provides a framework for the provision of error messages to the origin for updates performed in batch or background mode.
· Support for richer functionality. The Profile supports, optionally, the processes of merge and global replace, which cannot normally be controlled through batch updates. It also allows the target to provide immediate reports to the data creator on update errors and results of any duplicate detection processes.
1.3 Z39.50 Specifications
The Z39.50 protocol versions, objects and services needing to be supported by origin and target for conformance with the Union Catalogue Profile are specified in Section 11, Conformance. It is recognised that implementors may wish to move towards conformance in stages. A set of possible priorities for staged implementation is included in Appendix 3.
1.4 Development Process
National Library of Australia and IT/19 members first met in July 1996 to determine the feasibility of using the Z39.50 Database Update Extended Service to support update in a union catalogue environment. A draft profile was developed and reviewed by interested parties from the user and vendor communities in Australia and New Zealand before being made available for general comment by the Z39.50 Implementors Group (ZIG) The concept was favourably received at the ZIG Meeting in October 1996 and a second version of the profile was prepared for the April 1997 meeting, incorporating changes resulting from the initial round of comments. A key comment from implementors was the need to incorporate an optional record locking mechanism.
Following the April 1997 meeting, the ZIG undertook to develop a solution for record locking and to review the solutions for record merge and global replace. The outcome was an Update Extended Service Proposal for discussion at the August 1997 ZIG meeting. This proposal addressed the record locking requirement through a new update schema and incorporated several minor changes to the base standard to support a new merge qualifier and to allow a record to be returned with a diagnostic message. A solution for global update was presented separately.
The outcome of the August 1997 ZIG meeting was a new update proposal introducing a new action qualifier defined as an external and a new special update function that supported both merge and batch edit / replace. Global update was renamed batch edit / replace to more adequately reflect its role. The update proposal also allowed for supplementary diagnostics and defined the update schema.
The action qualifier, originally restricted to special update, was later extended to apply to any update function so that it could be used to specify detailed replacement parameters in record replace and element update actions.
A version of the profile was issued in March 1998 incorporating the changes outlined above. This version was approved by ISO TC 46/ SC 4 as an internationally registered profile.
1.5 Status of the Current Version of the Profile
This version of the profile has been updated to include the object identifiers assigned by the Z39.50 Maintenance Agency and minor editorial corrections.
2. Record Insert
Record Insert is used:
- When the origin has no knowledge of the contents of the target database
- When the origin has determined that a record does not already exist on the target database.
2.1 Origin Request
|
Element Name |
Contents |
|
referenceId |
Optional - supplied by origin |
|
function |
Create |
|
packageType |
Update |
|
packageName |
ex: 199607031045 |
|
userId |
ex: NU:46 |
|
retentionTime |
ex: 7 days |
|
permissions |
Omitted (optional) |
|
description |
Omitted (optional) |
|
taskSpecificParameters |
{Z39-50-extendedServices5} esRequest |
|
recordInsert |
|
ex: UC-B (bibliographic record) |
|
Omitted or record insert schema |
|
set containing record ID, version identifier (date / time stamp) and title - default for successful update |
|
used for record review notes or does not duplicate lists |
|
|
|
|
|
optional, i.e. not required for a MARC record insert because within the record itself |
|
optional, i.e. not required for a MARC record insert because within the record itself |
|
not used |
|
waitAction |
wait if possible ( 1-10 records) do not wait |
|
elements |
full - requesting that the target should return all task package elements in the update response where applicable |
|
otherInfo |
Reference id is optional, but package name is mandatory if the client wants to later modify or delete a task package.
2.1.1 Action Qualifier
The action qualifier may be used for duplicate detection or record review. See below.
2.1.2 Duplicate Detection
The "does not duplicate list" allows the client to convey to the server that certain records retrieved in a search had been considered and rejected before this record was created. This information may be used by the target to prevent the supply of potentially irritating diagnostics that could cause an end user to ignore more important diagnostics. This list could also be managed by the client to discard such messages that arrived from the server.
If a record insert action contains only one record, then the does not duplicate list may be sent in the action qualifier using the nonDupRecordId field from the record structure illustrated in the table below. Where multiple records are sent in one request, then GRS-1 record syntax with the record insert schema should be used.
The structure for the Record Insert record ( 1.2.840.10003.10.9) is as follows:
|
Element |
Occurrence |
Repeatable |
Datatype |
|
recordWrapper |
Mandatory |
no |
RecordWrapper |
|
nonDupRecordId |
Mandatory if recordReviewCode absent |
yes |
InternationalString |
|
recordReviewCode |
Mandatory if nonDupRecordId absent |
no |
InternationalString |
|
recordReviewNote |
Optional |
no |
InternationalString |
Definition of RecordWrapper
|
Element |
Occurrence |
Repeatable |
Datatype |
|
schemaId |
Optional |
no |
ObjectIdentifier |
|
record |
Mandatory |
no |
EXTERNAL |
2.1.3 Holdings Information
Holdings information in the form of summary statements or full holdings details could be supplied either:
- Via a MARC field in the bibliographic record
- Via separate holdings record (for example, in the USMARC Holdings Format)
- Via the OPAC schema currently under development
For conformance with the Union Catalogue Profile, the origin must be able to supply holdings as part of the bibliographic record and the target must be able to support the update of holdings supplied as part of a bibliographic record for the specific MARC variant supported.
Support for a separate MARC holdings record or for the OPAC schema is optional.
If supplied as MARC fields in a bibliographic record, then record replace rather than record insert would be used where the bibliographic record already exists on the target. If supplied as a separate record, the control number for the parent bibliographic record must also be supplied (for example, in USMARC Holdings Records, field 004 is used to provide the control number of the parent bibliographic record).
When multiple sets of holdings information are supplied in a bibliographic record or OPAC schema, the target must be able to process each set according to the instructions in the update request.
Inconsistencies within a specific MARC variant in the semantics for supplying holdings information as part of a bibliographic record will need to be resolved outside the Profile. For instance, USMARC targets will need in the short-medium term to handle the fact that holdings may be supplied in a locally defined field (e.g., 984 in Australian implementations) to circumvent limitations of embedded holdings information in the USMARC record. UNIMARC, targets will need to handle the fact that holdings may be supplied in one of the National Use Block fields 9--.
2.1.4 Distributed Review
If the origin wishes to signal that a record being updated should be reviewed by another party, this can be done on a record by record basis for individual supplied records within an update request.
If a record insert action contains only one record, then the review messages may be sent in the action qualifier using the record insert structure as illustrated in the table above under section 2.1.2 without the record wrapper. Where multiple records are sent in one request, then GRS-1 record syntax with the record insert schema as illustrated above should be used.
2.2 Target Response
|
Element Name |
Contents |
|
referenceId |
optional - supplied by origin |
|
operationStatus |
Done |
|
diagnostics |
only if failure |
|
taskPackage consisting of: |
{Z39-50-recordSyntax (106)} taskPackage |
|
Update |
|
ex: 199607031045 |
|
ex: NU:46 |
|
ex: 7 days |
|
Omitted |
|
Omitted |
|
ex: NU46:23 |
|
ex: 19960703104734 |
|
0 (pending) 1 (active) |
|
ex: Diagnostic record, format extServices, permission 1 (id not authorised) |
|
update taskPackage |
|
recordInsert |
|
ex: UC-B (bibliographic record) |
|
Omitted |
|
as per request |
|
Omitted |
|
success |
|
if applicable |
|
|
|
see table under Error Message Handling |
|
as supplied by target |
|
success |
|
see table under Error Message Handling |
|
otherInfo |
Omitted - This data element is returned with the update response which may be given before the update has actually occurred. When this happens, the origin will later use search to access records in the task package. For this reason, information relating to records in the task package must be contained within the task package parameters and hence this data element is of limited value in an update response. |
2.2.1 Background or Batch Processing
The target has control over the timing of the update if the origin request includes the parameter "wait if possible" or "do not wait". If the target receives the parameter "wait" and cannot process the update interactively, then a diagnostic should be sent immediately in the update response. When the target chooses not to process interactively, the update response indicates this via the task status parameter. When the update is completed, the target will update the task package within the extended services database held on the target. When the origin (client) receives an update response with the task (package) status set to pending or active, it notes that it should check on this later via a client defined timetable. The origin (client) later generates a search request / present request on the extended services database to retrieve updated update responses. See Section 8, Querying the Task Package.
2.2.2 Diagnostic Messages
General extended services / update
Validation messages
Update
messages
Authority Control messages
Duplication messages
Holdings
error messages
2.2.3 Error Message Handling
The target may return a message alone, multiple messages, or it may return a record accompanied by one or more messages. A single message is used when the update has been accepted with nothing else to report (e.g. message 950). When a target returns a record, it is because the current database record is different from that supplied. Additional information within the diagnostic message is used by the target to indicate to the origin which parts of the record have changed, so that the origin can use this information, for example to highlight changed data.
|
Case |
recordOrSurDiag |
supplementalDiagnostics |
|
Record accepted unmodified |
Diagnostic 950 (contains record ID + version identifier in additional info) |
blank |
|
Record not accepted because invalid |
Full record |
Diagnostic 933 and / or 935 and / or 938 and / or 943 |
|
Record not accepted because a suspect duplicate |
Full record - existing database record |
Diagnostic 970 |
|
Record accepted but modified |
Full record |
Authority control 980-985 |
|
Record accepted but suspect duplicate |
Full record - existing database record |
Diagnostic 971 or 972 |
|
Record queued or in process |
Record ID plus title |
blank |
3. Record Replace
Record replace is used for the following types of changes:
- Field insert
- Field delete
- Field replace where there is more than one field of the same tag name in the record, where more than one field is being updated and optionally for any other type of field replace
- Holdings insert, replace or delete if supplied as MARC fields in a bibliographic record where the bibliographic record already exists on the target
3.1 Origin Request
|
Element Name |
Contents |
|
referenceId |
optional - supplied by origin |
|
function |
Create |
|
packageType |
Update |
|
packageName |
ex: 199607031045 |
|
userId |
ex: NU:46 |
|
retentionTime |
ex: 7 days |
|
permissions |
Omitted |
|
description |
Omitted |
|
taskSpecificParameters |
{Z39-50-extendedServices5} esRequest |
|
recordReplace |
|
ex: UC-B (bibliographic record) |
|
Omitted or update schema or edit / replace schema |
|
set containing record ID, version identifier (date / time stamp) and title to be used for successful update |
|
Optional - Edit / replace record or update schema |
|
Although the standard says that a full record is necessary, it could be permissible for some single field additions or changes to supply a very brief record, e.g. with record ID, version identifier (date / time stamp) and title and the field being added or changed. The action qualifier is mandatory in this case. |
|
|
|
<record ID> More than one per task package not recommended |
|
version identifier (date / time stamp) |
|
optional |
|
waitAction |
wait if possible ( 1-10 records) |
|
elements |
full - requesting that the target should return all task package elements in the update response where applicable |
|
OtherInfo |
Omitted |
3.1.1 Action Qualifier
The edit / replace record can be used to convey to the target the exact nature of changes that have been made to a record. Without the qualifier, the target would assume that any fields not in the record supplied by the origin are to be deleted. This may not be the intention of the origin that may be unaware that the record it received was not a full record, perhaps having been obtained from an unrelated search that used an unknown element set. In this situation, the target takes risks when accepting a full record but how the target copes with this (e.g., via comparison and merge routines or bumping hierarchies) is outside the scope of the profile.
Where a record replace contains only one record, the Action qualifier can contain an edit / replace record relating to that one record. Where there are multiple records in a single record replace transaction, the records can be sent using GRS-1 as record syntax with the edit / replace schema.
Any modification to a record can be achieved by a record replace, but not all modifications can be achieved by an element update. Those that can only be achieved by a record replace are:
- Field insert (FI)
- Field delete (FD)
Other Edit / replace types that are valid are:
- Field replace (FR)
- Subfield insert (SI)
- Subfield delete (SD)
- Subfield replace (SR)
- Indicator change (IC)
The following tables list the elements of the Edit / replace record (1.2.840.10003.10.10) that are applicable in a record replace.
|
Element |
Occurrence |
Repeatable |
Datatype |
|
persistentResultSetPackageName |
Omitted |
No |
|
|
numberOfRecords |
Omitted |
No |
|
|
creationDateTime |
Omitted |
No |
|
|
reviewCode |
Optional |
No |
InternationalString |
|
reviewNote |
Optional |
No |
InternationalString |
|
changeDataInfo |
Mandatory |
Yes |
Definition of changeDataInfo
|
Element |
Occurrence |
Repeatable |
Datatype |
|
fieldIdentifier |
Optional - all types |
No |
|
|
oldValue |
Mandatory - all types except FI, SI |
No |
|
|
oldValueTruncationAttribute |
Optional - all types except FI & SI |
No |
|
|
conditionalField |
Omitted |
No |
|
|
conditionalValue |
Omitted |
No |
|
|
conditionalTruncationAttribute |
Omitted |
No |
|
|
newValue |
Mandatory - FI, SI |
No |
|
|
editReplaceType |
Mandatory - all types |
No |
|
|
case |
Omitted |
No |
A separate changeDataInfo record should be included for each occurrence of a field to be changed.
Field identifier includes field tag and optionally field sequence number, subfield tag and sequence number. Sequence number for a field applies to the occurrence of a field in a record and not to the
sequence number of the field in relation to the record as a whole. For example, in a USMARC record a 650 field (topical subject heading) might be the second 650 in a record and the 15th field in a record. The field sequence number is 2 in this case. Conversely, sequence number in relation to a subfield counts the relative position of the subfield in relation to the field as a whole. The valid formats for Field identifier are:
<tag>/<seq>:<sf>/<seq>
<tag>:<sf>/<seq>
<tag>:<sf>
<tag>/<seq>
<tag>
In the absence of a sequence number, the default would be to change or delete all occurrences of the specified field or field / subfield which match the specified old value. For a subfield insert, the subfield should be placed on the end of the field. For a field insert, the target may choose where to insert the field within the record.
The edit / replace record is also used in element update and special update, see sections 4.1.1 and 6.1.2.
3.1.2 Holdings Information
If holdings information is sent via MARC fields in a bibliographic record, then the action qualifier may be used to specify the required action (field insert/ field replace/ field delete). In the absence of an action qualifier, the full bibliographic record must be supplied.
3.1.3 Concurrent Update
It is possible for an origin to obtain a copy of a record and subsequently send an update transaction for that record, which has in the mean time been independently updated. Accurate version control of records can be used to avoid this type of incorrect updating. Another method of control is via record locking which assigns an exclusive update option to a particular identified user, optionally for a specific time period. The Profile does not assume that every target would support record locking. See Section 7. Record Locking for specific details.
To control updating, the supplementary identification is used to indicate which version of the record is being changed and the edit / replace record is used to identify which fields of the record are being changed, deleted or inserted. When the target sends records in response to search or present requests, the version identifier (e.g. field 005 in USMARC and UNIMARC) is always sent containing the date and time qualifier of the last update of that record on the target database. The origin must not change this field. It is returned with the record for modification, together with the new data within the supplied records data area and also in the supplementary id field. If the version identifier information (i.e. the date / time stamp) is the same as the targets database record, the target can process the transaction with no further check. If not, then the target uses the edit / replace record, containing the identification of fields and their original contents to determine whether or not it is safe to process the update.
In the scenario where the target accepts update transactions from devices outside the Z39.50 update protocol as well as Z39.50 update transactions, the version identifier (date / time stamp) can be used to control the concurrent update problem. For example, a dumb terminal might be in the process of updating a record, causing a record lock on the target. A Z39.50 update request arrives and is either queued and sent to the task package or the update request is failed with error message 956 - Record replace or element update rejected - record protected or locked by another user. If it is queued, either the record update will fail because of a version conflict with the date / time stamp or, if the terminal released the record without updating it, the update would process.
Note that the update schema may be used even when the target does not support record locking. It is used by the target in a search or present response to convey in an explicit way the record id and version in record formats that do not contain these elements. Some targets may not supply a record suitable for update in a normal search or present response, but will supply it when the request indicates the preferred record syntax of GRS-1 with the update schema. See Section 7 - Record Locking for details on the update schema.
3.2 Target Response
|
Element Name |
Contents |
|
referenceId |
optional -supplied by origin |
|
operationStatus |
Done |
|
diagnostics |
only if failure |
|
taskPackage consisting of: |
{Z39-50-recordSyntax (106)} taskPackage |
|
Update |
|
ex: 199607031045 |
|
ex: NU:46 |
|
ex: 7 days |
|
Omitted |
|
Omitted |
|
ex: NU46:23 |
|
ex: 19960703104735 |
|
0 (pending) 1 (active) 2 (complete) 3 (aborted) |
|
ex: Diagnostic record, format extServices, permission 1 (id not authorised) |
|
update taskPackage |
|
recordReplace |
|
ex: UC-B (bibliographic record) UC-H (holdings record) UC-A (authority record) |
|
Omitted or update schema |
|
as per request |
|
as supplied by client |
|
success partial failure |
|
if applicable |
|
|
|
see table under Error Message Handling |
|
as supplied by client |
|
success |
|
see table under Error Message Handling |
|
otherInfo |
Omitted |
3.2.1 Diagnostic Messages
General extended services / update
Validation
Update
Authority Control
Holdings
3.2.2 Error Message Handling
|
Case |
recordOrSurDiag |
supplementalDiagnostics (examples) |
|
Record replace accepted unmodified |
Diagnostic 953 (contains record ID and version identifier in additional info) |
blank |
|
Record replace not accepted because invalid |
Full record |
Validity 933, 935, 938 Update 943, 944, 945, 955 |
|
Record replace not accepted because version conflict |
Full record from database |
Diagnostic 964, 965 |
|
Record replace not accepted because of procedural error |
Diagnostic 1040-1047, 957, 967 |
|
|
Record replace not accepted because unavailable |
Diagnostic 968, 956, 966, 968 |
|
|
Record replace accepted but modified |
Full record |
Authority control 980-985 Validity 920-932, 934, 936-937, 939-942 Update diagnostics 954 |
|
Record replace queued or in process |
Record ID plus title |
blank |
4. Element Update
Element Update is used for:
- changing a field
- changing the lock status of a record
When used for changing a field in a supplied record, element update cannot be used for inserting or deleting fields. It should be avoided where there are multiple occurrences of the same field because there is no way of specifying the value to be replaced. Record replace should be used in these cases.
4.1 Origin Request
|
Element Name |
Contents |
|
referenceId |
optional - supplied by origin |
|
function |
Create |
|
packageType |
Update |
|
packageName |
ex: 199607031045 |
|
userId |
ex: NU:46 |
|
retentionTime |
ex: 7 days |
|
permissions |
Omitted |
|
description |
Omitted |
|
taskSpecificParameters |
{Z39-50-extendedServices5} esRequest |
|
elementUpdate |
|
ex: UC-B (bibliographic record) |
|
Omitted or update schema or edit / replace schema |
|
set containing record ID, version identifier and title to be used for successful update |
|
Optional - Edit / replace record or update schema |
|
Single field being changed |
|
|
|
<record ID> More than one per task package not recommended |
|
version identifier (date / time stamp) |
|
Optional |
|
waitAction |
wait if possible ( 1-10 records) |
|
elements |
full - requesting that the target should return all task package elements in the update response where applicable |
|
OtherInfo |
Omitted |
4.1.1 Action Qualifier
In the absence of an edit / replace record in the action qualifier, the target will replace the existing field in the database record with the field in the supplied record. If there is more than one occurrence of the supplied field, the target will respond with an appropriate diagnostic (955).
Alternatively, an action qualifier may be used to specify the sequence number of the field to be changed and to supply a copy of the existing field in the database record for correlation purposes.
Where only one record is included in an element update request, the action qualifier can contain an edit / replace record detailing the nature of changes made. In this case, the supplied record need only include record ID and version identifier (date / time stamp). Where multiple records are supplied in an element update request and the records can be sent using GRS-1 as syntax with the edit / replace schema and the action qualifier should be left blank.
The edit / replace record can be used to convey to the target the exact nature of changes that have been made to a record. Edit / replace types valid for Element update are:
- Field replace (FR)
- Subfield insert (SI)
- Subfield delete (SD)
- Subfield replace (SR)
- Indicator change (IC)
- Data string change (DC)
The following table lists the elements of the Edit / replace record (1.2.840.10003.10.10) that are applicable in an element update.
|
Element |
Occurrence |
Repeatable |
Datatype |
|
persistentResultSetPackageName |
Omitted |
No |
|
|
numberOfRecords |
Omitted |
No |
|
|
creationDateTime |
Omitted |
No |
|
|
reviewCode |
Optional |
No |
InternationalString |
|
reviewNote |
Optional |
No |
InternationalString |
|
changeDataInfo |
Mandatory |
Yes |
Definition of changeDataInfo
|
Element |
Occurrence |
Repeatable |
Datatype |
|
fieldIdentifier |
Optional - all types |
No |
|
|
oldValue |
Mandatory - all types except SI |
No |
|
|
oldValueTruncationAttribute |
Optional - all types except SI |
No |
|
|
conditionalField |
Omitted |
No |
|
|
conditionalValue |
Omitted |
No |
|
|
conditionalTruncationAttribute |
Omitted |
No |
|
|
newValue |
Mandatory |
No |
|
|
editReplaceType |
Mandatory - all types |
No |
|
|
case |
Omitted |
No |
Field identifier includes field tag and optionally field sequence number, subfield tag and sequence number. Sequence number for a field applies to the occurrence of a field in a record and not to the
sequence number of the field in relation to the record as a whole. For example, in a USMARC record the a 650 field (topical subject heading) might be the second 650 in a record and the 15th field in a record. The field sequence number is 2 in this case. Conversely, sequence number in relation to a subfield counts the relative position of the subfield in relation to the field as a whole. The valid formats for Field identifier are:
<tag>/<seq>:<sf>/<seq>
<tag>:<sf>/<seq>
<tag>:<sf>
<tag>/<seq>
<tag>
In the absence of a sequence number, the default would be to change or delete all occurrences of the specified field or field / subfield which match the specified old value. For a subfield insert, the subfield should be placed on the end of the field.
The edit / replace record is also used in record replace and special update, see sections 3.1.1 and 6.1.2.
4.2 Target Response
|
Element Name |
Contents |
|
referenceId |
optional - supplied by origin |
|
operationStatus |
Done |
|
diagnostics |
only if failure |
|
taskPackage consisting of: |
{Z39-50-recordSyntax (106)} taskPackage |
|
Update |
|
ex: 199607031045 |
|
ex: NU:46 |
|
ex: 7 days |
|
Omitted |
|
Omitted |
|
ex: NU46:23 |
|
ex: 19960703104735 |
|
0 (pending) |
|
ex: Diagnostic record, format extServices, permission 1 (id not authorised) |
|
update taskPackage |
|
elementUpdate |
|
ex: UC-B (bibliographic record) |
|
Omitted or update response |
|
as per request |
|
as per request |
|
success |
|
if applicable |
|
|
|
see table under Error Message Handling |
|
as supplied by client |
|
success |
|
see table under Error Message Handling |
|
otherInfo |
Omitted |
4.2.1 Diagnostic Messages
General extended services / update
Validity
Update
Authority
control
Holdings
4.2.2 Error Message Handling
|
Case |
recordOrSurDiag |
supplementalDiagnostics (examples) |
|
Element update accepted unmodified |
Diagnostic 953 (contains record ID and version identifier in additional info) |
blank |
|
Element update not accepted because invalid |
Validity 933, 935, 938 |
|
|
Element update not accepted because version conflict |
Full record from database |
Diagnostic 964,965 |
|
Element update not accepted because of procedural error |
Diagnostic 1040-1047, 957, 967 |
|
|
Element update not accepted because unavailable |
Diagnostic 956, 966, 968 |
|
|
Element update accepted but modified |
Full record |
Authority control 980-985 |
|
Element update queued or in process |
Record ID |
blank |
5. Record Delete
Record delete is used to delete a known record.
5.1 Origin Request
|
Element Name |
Contents |
|
referenceId |
optional - supplied by origin |
|
function |
Create |
|
packageType |
Update |
|
packageName |
ex: 199607031045 |
|
userId |
ex: NU:46 |
|
retentionTime |
ex: 7 days |
|
permissions |
Omitted |
|
description |
Omitted |
|
taskSpecificParameters |
{Z39-50-extendedServices5} esRequest |
|
recordDelete |
|
ex: UC-B (bibliographic record) |
|
Omitted |
|
set containing version identifier and record ID for successful transactions |
|
Omitted - not applicable for a record delete |
|
Records can include minimal info, e.g. record ID, version identifier (date / time stamp) and title |
|
|
|
<record ID> |
|
version identifier (date / time stamp) |
|
Omitted |
|
waitAction |
wait if possible ( 1-10 records) do not wait |
|
elements |
full - requesting that the target should return all task package elements in the update response where applicable |
|
OtherInfo |
Omitted |
5.1.1 Action Qualifier
The action qualifier is not used for record delete.
5.1.2 Deleting holdings information
If holdings are supplied as MARC fields in a bibliographic record, then record replace rather than record delete should be used to request the deletion of holdings on the target. Holdings can only be deleted through record replace by using the edit / replace schema.
5.2 Target Response
|
Element Name |
Contents |
|
referenceId |
optional - supplied by origin |
|
operationStatus |
Done Accepted Failure |
|
diagnostics |
only if failure |
|
taskPackage consisting of: |
{Z39-50-recordSyntax (106)} taskPackage |
|
Update |
|
ex: 199607031045 |
|
ex: NU:46 |
|
ex: 7 days |
|
Omitted |
|
Omitted |
|
ex: NU46:23 |
|
ex: 19960703104735 |
|
0 (pending) |
|
ex: Diagnostic record, format extServices, permission 1 (id not authorised) |
|
update taskPackage |
|
recordDelete |
|
ex: UC-B (bibliographic record) |
|
Omitted |
|
as per request |
|
Omitted |
|
success |
|
if applicable |
|
|
|
see table under Error Message Handling |
|
Omitted |
|
success |
|
see table under Error Message Handling |
|
otherInfo |
Omitted |
5.2.1 Diagnostic Messages
General extended services / update
Update
Deletion
Holdings
5.2.2 Error Message Handling
|
Case |
recordOrSurDiag |
supplementalDiagnostics |
|
Record delete accepted unmodified |
Diagnostic 958 |
blank |
|
Record delete not accepted because invalid |
Diagnostic 959, 960 |
blank |
|
Record delete not accepted because version conflict |
Full record from database |
Diagnostic 964, 965 |
|
Record delete not accepted because of procedural error |
Diagnostic 957, 1040-1047 |
blank |
|
Record delete not accepted because unavailable |
Diagnostic 956, 961, 962, 963, 966 |
blank |
|
Record delete queued or in process |
Record ID plus title |
blank |
6. Special Update
Special Update is a new action enabling an origin to convey record merge instructions and batch edit / replace instructions to a target via an externally defined OID, using the action qualifier parameter.
Other special update types may be defined in the future.
6.1 Origin Request
|
Element Name |
Contents |
|
referenceId |
optional - supplied by origin |
|
function |
Create |
|
packageType |
Update |
|
packageName |
ex: 199607031045 |
|
userId |
ex: NU:46 |
|
retentionTime |
ex: 7 days |
|
permissions |
Omitted |
|
description |
Omitted |
|
taskSpecificParameters |
{Z39-50-extendedServices5} esRequest |
|
specialUpdate |
|
ex: UC-B (bibliographic record) |
|
Omitted or edit / replace schema or update schema |
|
set containing version identifier and record ID for successful transactions |
|
externally defined OID - see sections 6.1.1 and 6.1.2 below on Merge and edit / replace |
|
See separate examples in sections following on Merge and Batch edit / replace |
|
|
|
<record Id> |
|
Version identifier (date / time stamp) |
|
Omitted |
|
waitAction |
wait if possible ( 1-10 records) |
|
elements |
full - requesting that the target should return all task package elements in the update response where applicable |
|
OtherInfo |
Omitted |
6.1.1 Merge
A merge request is a form of delete that also transfers linked data to another record. Merge is generally used when duplicate records have been identified on a target database and the origin needs to specify the record to be retained.
In a library catalogue, when a duplicate bibliographic record is deleted, any linked holdings, reservation or order data defined by the target's database need to be transferred to the kept bibliographic record. When a duplicate authority record is deleted, any linked bibliographic records or related authority records need to be transferred to the kept authority record. More than one duplicate record may be involved in a merge transaction.
The merge to information (i.e. the ID of the record that is to be retained) is contained within the actionQualifier external. Using a special update action, merge conveys to the target that a merge is required. The client cannot manage the merge process itself, for example by sending record deletions, holdings deletions and additions because it cannot determine the ripple effect on the database involved.
There can only be one "merge to" record ID in the actionQualifier area, although there may be multiple records in the supplied records area. This allows for example, multiple incorrect forms of an authority to be merged into one authority.
6.1.2 Batch Edit / Replace
Batch edit / replace is a form of special update enabling an origin to convey instructions to a target for a group of records to be changed in a similar way. The special action reduces the traffic that would be required to process multiple element update requests.
To request a batch edit / replace, the origin:
- Conducts a search to identify candidate records
- Uses the Persistent Result Set Extended Service to request the target to create a persistent result from the transient result set with a specific name.
- Creates an edit / replace record.
- Sends a special update request to the target with the edit / replace record as an external parameter in the actionQualifier.
The target is not required to perform all or none of the changes. It may fail some, e.g. because a record is not available for update, or because its version is incorrect, but process others. Detailed results are reported to the task package including results for each record processed or not processed.
The structure for the edit / replace record (1.2.840.10003.10.10) is as follows:
|
Element |
Occurrence |
Repeatable |
Datatype |
|
persistentResultSetPackageName |
Mandatory |
No |
|
|
numberOfRecords |
Mandatory |
No |
|
|
creationDateTime |
Mandatory |
No |
|
|
reviewCode |
Optional |
No |
InternationalString |
|
reviewNote |
Optional |
No |
InternationalString |
|
changeDataInfo |
Mandatory |
Yes |
Definition of changeDataInfo
|
Element |
Occurrence |
Repeatable |
Datatype |
|
fieldIdentifier |
Optional |
No |
|
|
oldValue |
Mandatory |
No |
|
|
oldValueTruncationAttribute |
Optional |
No |
|
|
conditionalField |
Optional |
No |
|
|
conditionalValue |
Optional |
No |
|
|
conditionalTruncationAttribute |
Optional |
No |
|
|
newValue |
Optional |
No |
|
|
editReplaceType |
Mandatory |
No |
|
|
case |
Optional |
No |
BOOLEAN |
The number of records from the transient result set is included as a check. If this differs from the number of records in the persistent result set, the target should not proceed with the update request.
The creation-date-time is the date and time the persistent result set task package was created by the target. If the date and time of last update of a record in the persistent result set is more recent than the date in the Batch edit / replace request, the target should not process the update for that record.
The field identifiers must correlate with the database name and schema cited in the element update package. If there is more than a single occurrence of a specified field in the record, the update should be applied to all occurrences of the field matching the update criteria. If the origin does not specify any field identifiers in the edit / replace record, the target should look for the old value anywhere in the record.
The old value should consist of the entire value to be replaced or deleted as it would appear in the field, with punctuation and spaces. The old value truncation attribute should include values from Bib1 Table A3-5, e.g. 1 = right truncation, 100 = do not truncate. In the absence of a truncation attribute, the target defines the default.
The update should only occur if the conditional field/ value pair is present in the record, taking into account the specified conditional truncation attribute.
The new value is a mandatory field except where the edit / replace type is set to field or subfield delete.
Edit / replace types would include the following values:
- Field insert (FI)
- Field delete (FD)
- Field replace (FR)
- Subfield insert (SI)
- Subfield delete (SD)
- Subfield replace (SR)
- Subfield merge (SM)
- Indicator change (IC)
- Data string change (DC)
Case is an optional toggle with 'true' meaning 'case dependent' and 'false' meaning 'case independent'. In the absence of this field, the target should process the update only if an exact match on case is found.
Field identifier includes field tag and optionally field sequence number, subfield tag and sequence number. Sequence number for a field applies to the occurrence of a field in a record and not to the
sequence number of the field in relation to the record as a whole. For example, in a USMARC record the a 650 field (topical subject heading) might be the second 650 in a record and the 15th field in a record. The field sequence number is 2 in this case. Conversely, sequence number in relation to a subfield counts the relative position of the subfield in relation to the field as a whole. The valid formats for Field identifier are:
<tag>/<seq>:<sf>/<seq>
<tag>:<sf>/<seq>
<tag>:<sf>
<tag>/<seq>
<tag>
Use of sequence number in a batch edit / replace transaction would be rare. In the absence of a sequence number, the default would be to change or delete all occurrences of the specified field or field / subfield which match the specified old value. For a subfield insert, the subfield should be placed on the end of the field. For a field insert, the target may choose where to insert the field within the record.
The edit / replace record is also used in record replace and element update, see sections 3.1.1 and 4.1.1.
6.2 Target Response
|
Element Name |
Contents |
|
referenceId |
optional - supplied by origin |
|
operationStatus |
Done |
|
diagnostics |
only if failure |
|
taskPackage consisting of: |
{Z39-50-recordSyntax (106)} taskPackage |
|
Update |
|
ex: 199607031045 |
|
ex: NU:46 |
|
ex: 7 days |
|
Omitted |
|
Omitted |
|
ex: NU46:23 |
|
ex: 19960703104735 |
|
0 (pending) |
|
ex: Diagnostic record, format extServices, permission 1 (id not authorised) |
|
update taskPackage |
|
specialUpdate |
|
ex: UC-B (bibliographic record) |
|
Omitted |
|
as per request |
|
as per request |
|
|