Home

YAZ User's Guide and Reference

1. YAZ User s Guide and Reference 163 184 Name Class Constant OID Z3950_PREFIX 5 10 oe oe 73050 PREFIXS 11 an ee Z30950 PREFIKS 12 pda Bo 73950 PREFIXS 13 oe oo 73950_PREFIXS 14 pi RES 73950_PREFIXS 15 En ER Z3950_PREFIX5 16 ido 73950_PREFIXS 17 au sane 73950 PREFIKS I8 ji pan Z30950 PREFIKS 19 cs duel Z30950 PREHIXS20 mes es Z30950 PREFIKS 21 i Baa Z350 PREFIKS 2 LS O Z350 PREFIKS 23 a AN ZAS PRE SAA dde sia 73950 PREFIX 525 one es 73950 PREFIKS 26 pais Ta Z30950 PREFIKS 27 re esa 73950 PREFIX S38 LES ee RO ons roe 73950 PREFIXS 30 A sue saul EN 73050 PREFIX S31 cen DAL SSI 31 Explain RECSYN yaz_oid_recsyn_explain Name Class Constant OID Z3950_PREFIX 5 100 is PEN 23950 PREFIKS 101 o O 73950_PREFIXS 102 saa EAN 73950 PREFIX S103 She in Z3950 PRENSI REGEN 73950_PREFIXS OS us pecan 73950_PREFIXS 106 Fragment RECSYN 730 F PREFIX S 107 ee za on 73950 PREFIX5 109 1 ee meek 73950 PREF S102 a oe 73950 PREFIX 5 1093 aa ao ZO PREFIX 5 1058 da A 73950 PREFIX 5 1095 oe eon OST PREFIX O NENA 73950 PREFIKS 1097 s oe 73950 PREFIX 5 1098 aa 3050 PREFIX 5 1059 ae 73950 PREFIKS 1101 2 RANN Z73950 PREF
2. Code Text 212 Duplicate sort keys 213 Unsupported missing data action 214 Illegal sort relation 215 Illegal case value 216 Illegal missing data action 217 Segmentation Cannot guarantee records will fit in specified segments 218 ES Package name already in use 219 ES no such package on modify delete 220 ES quota exceeded 221 ES extended service type not supported 222 ES permission denied on ES id not authorized 223 ES permission denied on ES cannot modify or delete 224 ES immediate ezecution failed 225 ES immediate execution not supported for this service 226 ES immediate execution not supported for these parameters 227 No data available in requested record syntax 228 Scan malformed scan 229 Term type not supported 230 Sort too many input results 231 Sort incompatible record formats 232 Scan term list not supported 233 Scan unsupported value of position in response 234 Too many indez terms processed 235 Database does not exist 236 Access to specified database denied 237 Sort illegal sort 238 Record not available in reguested syntaz 239 Record syntax not supported 240 Scan Resources exhausted looking for satisfying terms 241 Scan Beginning or end of term list 242 Segmentation max segment size too small to segment record 243 Present additional ranges parameter not supported 244 Present comp spec parameter not sup
3. Field Type Default Value referenceld Z_Referenceld NULL protocol Version Odr_bitmask Empty bitmask options Odr_bitmask Empty bitmask preferredMessageSize Odr_int 30 1024 maximumRecordSize Odr_int 30 1024 idAuthentication Z_IdAuthentication NULL implementationId char 81 implementationName char YAZ implementation Version char YAZ_VERSION userInformationField Z_UserInformation NULL otherInfo Z_OtherInformation NULL Table 5 1 Default settings for PDU Initialize Request Field Type Default Value referenceld Z_Referenceld NULL protocol Version Odr_bitmask Empty bitmask options Odr_bitmask Empty bitmask preferredMessageSize Odr_int 30 1024 maximumRecordSize Odr_int 30 1024 result Odr_bool TRUE implementationId char id implementationName char YAZ implementation Version char YAZ VERSION userInformationField Z_UserInformation NULL otherInfo Z_OtherInformation NULL Table 5 2 Default settings for PDU Initialize Response Field Type Default Value referenceld Z_Referenceld NULL smallSetUpperBound Odr_int 0 largeSetLowerBound Odr_int 1 mediumSetPresentNumber Odr_int 0 replaceIndicator Odr_bool TRUE resultSetName char default num_databaseNames Odr_int 0 databaseNames char NULL smallSetElementSetNames Z_ElementSetNames NULL mediumSetElementSetNames Z_ElementSetNames NULL pr
4. Code Text 1 Permanent system error 2 System temporarily unavailable 3 Authentication error 4 Unsupported operation 5 Unsupported version 6 Unsupported parameter value 7 Mandatory parameter not supplied 8 Unsupported parameter 10 Query syntax error 11 Unsupported query type 12 Too many characters in query 13 Invalid or unsupported use of parentheses 14 Invalid or unsupported use of quotes 15 Unsupported context set 16 Unsupported index 17 Unsupported combination of index and context set 18 Unsupported combination of indexes 19 Unsupported relation 20 Unsupported relation modifier 21 Unsupported combination of relation modifers 22 Unsupported combination of relation and index 23 Too many characters in term 24 Unsupported combination of relation and term 25 Special characters not guoted in term 26 Non special character escaped in term 27 Empty term unsupported 28 Masking character not supported 29 Masked words too short 30 Too many masking characters in term 31 Anchoring character not supported Code Text 32 Anchoring character in unsupported position 33 Combination of proximity adjacency and masking characters not supported 34 Combination of proximity adjacency and anchoring characters not supported 35 Term contains only
5. Delete 2h daha w hd ect sus LUE eRe LA AE Wa eee woe Application Invocation GFS Configuration and Virtual Hosts The Z39 50 ASN 1 Module 5 1 5 2 5 3 5 4 INTTOAUETLON 3004 Cortar di LU A UM Preparing PDUS EXTERNAL Data PDU Contents Table SOAP and SRU 6 1 6 2 6 3 6 4 Introduction 0 drh rs 44 4 33 35 33 34 34 36 36 39 42 42 46 49 49 49 51 52 YAZ User s Guide and Reference vii 7 Supporting Tools 65 7 1 Query Syntax Parsers 224 4 h 452 28h 5442 64444444 2448248444 65 Tl Prefix Query Format s ms p cs Le cs hoods Goan aa Tir ey Wa E aa 65 7 1 1 1 Using Proximity Operators with PQF 68 FLE POR QUERES a boda bd peor br is ee du A eS A 69 ll CCCs reae a A Baba A AA ee GS 70 TZ CELSO a koe or ee scoe a a Oe be amp RRA AR 70 7 1 2 2 CCLOualifers 72 7 1 2 2 1 Oualifierspecification 72 11222 Qualfi ral s LL LIL SNA Che AR CHS SERS 13 LAS Comments s sosog ack LR RSR SR NSE RSR STE er 73 T224 UA oe SN IA A 13 4127 COUAPL oca RS SR IR Rae A ER 75 Ta COE oo Ge a ee DN A Aa a a a ate 75 7 1 3 1 COL parsing 76 Tyee ALOE di da lid a Se SE Se sa
6. ODR stream encoding stream memory source if required ODR print x printing stream int step_size x step size x int term position x desired index of term in result list returned int num_entries number of entries requested returned scan term entries The called handler does not have to allocate this Size of entries is num entries s above x struct scan_entry xentries bend_scan_status status int errcode char x errstring char scanClause x COL scan clause x char setname k Scan in result set NULL if omitted x bend_scan_rr This backend server handles both 239 50 scan and SRU scan In order for a handler to distinguish between SRU CQL scan Z39 50 Scan it must check for a non NULL value of scanClause Note If designed today it would be a choice using a union or similar but that would break binary compatibility with existing servers 4 6 Application Invocation The finished application has the following invocation syntax by way of statserv_main application install installa remove a file v level 1 file u uid c config vconfig C fname t minutes k kilobytes K d daemon w dir p pidfile r kilobytes ziDSTV1 listener spec The options are a file Specify a file for dumping PDUs for diagnostic purposes The special name dash sends output to stderr S Don t fork or make threads
7. STRUCTURE 4 Phrase Word Key vear Date normalized Word list 100 Date un normalized 101 Name normalized 102 Name un normalized 103 Structure 104 Urx 105 Free form text 106 Document text 07 Local number LOS SEELA 109 Numeric string ON Oiler oe CO NO ea TRUNCATION 5 YAZ User s Guide and Reference 159 184 I Kuli truncation 2 Lert truncation 3 Lert anel rigar Kun 100 Do not truncate 101 Process in search term regular 102 REegExprsl 103 RegExpr 2 104 Process Pia o regalar iSo 20m 100 or asi 39 58 Thw 105 106 truncation attributes below are only supported by Index Data s Zebra server 105 Process x regular 106 Process x regular COMPLETENSS 6 1 Incomplete subfield 2 Complete subfield 3 Complete field SORTING 7 1 ascending 2 descending I and right truncate Sep l op Type 7 is an Index Data extension to RPN queries that allows embedding a sort critieria into a query SEE ALSO Bib 1 Attribute Set Attibute Set Bib 1 Semantics 11 14 yaz json parse yaz json parse YAZ JSON parser Synopsis yaz json parse p DESCRIPTION yaz json parse is utility which demonstrates the JSON API of YAZ yaz json h The program attempts to parse a JSON from standard input stdin It will return exit code 1 if parsing fails and the parsing error message will be p
8. delivery address postal address region delivery address postal address country delivery address postal address postal code delivery address electronic address telecom service identifier delivery address electronic address telecom service addreess billing address postal address name of person or institution name of person billing address postal address name of person or institution name of institution billing address postal address extended postal delivery address billing address postal address street and number billing address postal address post office box billing address postal address city billing address postal address region billing address postal address country billing address postal address postal code billing address electronic address telecom service identifier billing address electronic address telecom service addreess ill service type requester optional messages can send RECEIVED requester optional messages can send RETURNED requester optional messages requester S HIPPED requester optional messages requester CHECKED IN search type level of service search type need before date search type expiry date oe ne weet SEG Pin oe he E IA YAZ User s Guide and Reference 29 184 3 7 2 Record Update For Record Update type must be set to update in ZOOM
9. fun A pointer to a function that implements the type of the CHOICE member It may be either a standard ODR type or a type defined by yourself name Name of tag A handy way to prepare the array for use by the odr_choice function is to define it as a static initialized array in the beginning of your decoding encoding function Assume the type definition MyChoice CHOICE untagged INTEGER tagged 99 IMPLICIT INTEGER other BOOLEAN Your C type might look like typedef struct MyChoice enum MyChoice_untagged MyChoice_tagged MyChoice_other maca union Odr_int untagged Odr_int xtagged Oc JOGO WA u And your function could look like this int myChoice ODR o MyChoice x p int optional const char name static Odr_arm arm Sie ST Mwcaouiss mortage Gc imeecsrz uma ODR_IMPLICIT ODR_CONTEXT 99 MyChoice_tagged odr_integer tagged 1 l i MyChorce oriesr coche laV9lecia Worle i p p 4 0 hi if o gt direction ODR_DECODE p odr_malloc o sizeof xxp else 1f xp return optional amp amp odr_ok o if odr_choice o arm p gt u amp x xp gt which name YAZ User s Guide and Reference 113 184 cabida e Il dE LA return optional amp amp odr_ok o In some cases say a non optional choice which is a member of a sequence you can embed the union and its discriminato
10. is provided which prints the message argument to stderr along with an error message from the stream You can also use the function int odr_geterror ODR o to get the current error number from the screen The number will be one of these constants The character string array char x odr_errlistl can be indexed by the error code to obtain a human readable representation of the problem YAZ User s Guide and Reference 103 184 code Description OMEMORY Memory allocation failed OSYSERR A system or library call has failed The standard diagnostic variable errno should be examined to determine the actual error OSPACE No more space for encoding This will only occur when the user has explicitly provided a buffer for an encoding stream without allowing the system to allocate more space OREQUIRED This is a common protocol error A required data element was missing during encoding or decoding OUNEXPECTED An unexpected data element was found during decoding OOTHER Other error This is typically an indication of misuse of the ODR system by the programmer and also that the diagnostic system isn t as good as it should be yet Table 8 1 ODR Error codes 8 2 6 Summary and Synopsis include lt yaz odr h gt void odr_destroy ODR o void odr_ reset ODR o ODR odr_createmem int direction char odr_getbuf ODR o int xlen i
11. if o gt direction ODR_DECODE xp odr_malloc o sizeof xxp if odr_sequence_of o odr_integer amp xp gt elements amp xp gt num_ elements name ei wae l7 HOT return optional amp amp odr_ok o 8 3 6 CHOICE Types The choice type is used fairly often in some ASN 1 definitions so some work has gone into streamlining its interface CHOICE types are handled by the function int odr_choice ODR o Odr_arm arm void xp void x whichp const char xname The arm array is used to describe each of the possible types that the CHOICE type may assume Internally in your application the CHOICE type is represented as a discriminated union That is a C union accom panied by an integer or enum identifying the active arm of the union whichp is a pointer to the union discriminator When encoding it is examined to determine the current type When decoding it is set to reference the type that was found in the input stream The Odr_arm type is defined thus typedef struct odr_arm nt tagmode me elass nt tag nt which Che Ea EDS char xname h Ocia aan OR H H H The interpretation of the fields are tagmode Either ODR_IMPLICIT ODR_EXPLICIT or ODR_NONE 1 to mark no tagging which The value of the discriminator that corresponds to this CHOICE element Typically it will be a defined constant or an enum member
12. xx brief encoding stream for results ODR stream xx brief printing stream ODR print xx brief decoding stream use stream for results ODR decode xx brief reference ID Z Referenceld x referenceld xx brief peer address of client x char xpeer_name xx brief character set and language negotiation see include yaz z charneg h Z_CharSetandLanguageNegotiation charneg_request xx brief character negotiation response Z_ External xcharneg_ response xx brief character set encoding for query terms This is NULL by default It should be set to the native character set that the backend assumes for query terms x char xquery_charset xx brief whehter query_charset also applies to recors Is 0 No by default Set to 1 yes if records is in the same character set as queries If in doubt use 0 No int records_in_same_charset char implementation_id char ximplementation_name char ximplementation_version xx brief 239 50 sort handler x int bend_sort void handle bend sort rr rr xx brief SRU Z39 50 search handler x int bend_search void xhandle bend search rr xrr xx brief SRU Z39 50 fetch handler x int bend_fetch void xhandle bend_fetch_rr rr xx brief SRU Z39 50 present handler int bend_present void xhandle bend_present_rr rr xx brief 239 50 extended ser
13. You will note that even though simplicity was a goal in the design the interface is still orders of magnitudes more complex than the transport systems found in many other packages One reason is that the interface YAZ User s Guide and Reference 117 184 needs to support the somewhat different requirements of the different lower layer communications stacks another important reason is that the interface seeks to provide a more or less industrial strength approach to asynchronous event handling When no function is allowed to block things get more complex particularly on the server side We urge you to have a look at the demonstration client and server provided with the package They are meant to be easily readable and instructive while still being at least moderately useful 9 3 Common Functions 9 3 1 Managing Endpoints COMSTACK cs_create CS_TYPE type int blocking int protocol Creates an instance of the protocol stack a communications endpoint The t ype parameter determines the mode of communication At present the following values are supported tcpip_type TCP IP BER over TCP IP or HTTP over TCP IP ssl_type Secure Socket Layer SSL This COMSTACK is experimental and is not fully implemented If HTTP is used this effectively is HTTPS unix_type Unix socket unix only Local Transfer via file socket See unix 7 The cs_create function returns a null pointer if a system error occurs The blocking parameter sho
14. o yaz marcdump can also be requested to perform character set conversion of each record OPTIONS i format Specifies input format Must be one of marcxml1 marc ISO2709 marcxchange 18025577 line line mode MARC turbomarc Turbo MARC or json MARC in JSON 0 format Specifies output format Must be one of marcxml marc ISO2709 marcxchange ISO25577 line line mode MARC turbomarc Turbo MARC or json MARC in JSON f from Specify the character set from of the input MARC record Should be used in conjunction with option t Refer to the yaz iconv man page for supported character sets t to Specify the character set of of the output Should be used in conjunction with option f Refer to the yaz iconv man page for supported character sets l leaderspec Specify a simple modification string for MARC leader The leaderspec is a list of pos value pairs where pos is an integer offset 0 23 for leader Value is either a quoted string or an integer character value in decimal Pairs are comma separated For example to set leader at offset 9 to a use 9 a Ss prefix Writes a chunk of records to a separate file with prefix given i e splits a record batch into files with only at most chunk 1502709 record per file By default chunk is 1 one record per file See option C C chunksize Specifies chunk size to be used conjunction with option s p Makes yaz marcdump prints record number and input file
15. 1018 Init AC System temporarily out of resources 1019 Init AC System not available due to maintenance 1020 Init AC System temporarily unavailable Addinfo when it s expected back up 1021 Init AC Account has expired 1022 Init AC Password has expired so a new one must be supplied 1023 Init AC Password has been changed by an administrator so a new one must be supplied 1024 Unsupported Attribute 1025 Service not supported for this database 1026 Record cannot be opened because it is locked 1027 SQL error 1028 Record deleted 1029 Scan too many terms requested Addinfo max terms supported 1040 ES Invalid function 1041 ES Error in retention time 1042 ES Permissions data not understood 1043 ES Invalid OID for task specific parameters 1044 ES Invalid action 1045 ES Unknown schema 1046 ES Too many records in package 1047 ES Invalid wait action 1048 ES Cannot create task package exceeds maximum permissable size 1049 ES Cannot return task package exceeds maximum permissable size 1050 ES Extended services request too large 1051 Scan Attribute set id required not supplied ES Cannot process task package record exceeds maximum permissible 1052 record size for ES 1053 ES Cannot return task package record exceeds maximum permissible record size for ES response 1054 Init Required negotiation record not included 1055 Init negotiation option required 1056 Attribute not supported for database
16. 1057 ES Unsupported value of task package parameter 1058 Duplicate Detection Cannot dedup on requested record portion 1059 Duplicate Detection Requested detection criterion not supported 1060 Duplicate Detection Requested level of match not supported YAZ User s Guide and Reference 173 184 Code Text 1061 Duplicate Detection Requested regular expression not supported 1062 Duplicate Detection Cannot do clustering 1063 Duplicate Detection Retention criterion not supported 1064 Duplicate Detection Requested number or percentage of entries 1065 Duplicate Detection Requested sort criterion not supported 1066 CompSpec Unknown schema or schema not supported 1067 Encapsulation Encapsulated sequence of PDUs not supported 1068 Encapsulation Base operation and encapsulated PDUs not executed based on pre screening analysis 1069 No syntaxes available for this request 1070 user not authorized to receive record s in requested syntax 1071 preferredRecordSyntax not supplied 1072 Query term includes characters that do not translate into the target character set 1073 Database records do not contain data associated with access point 1074 Proxy failure YAZ User s Guide and Reference 175 184 Appendix C SRU diagnostics List of SRU diagnostics that are known to YAZ
17. 108 Malformed query 109 Database unavailable 110 Operator unsupported 111 Too many databases specified 112 Too many result sets created 113 Unsupported attribute type 114 Unsupported Use attribute 115 Unsupported value for Use attribute 116 Use attribute reguired but not supplied 117 Unsupported Relation attribute 118 Unsupported Structure attribute 119 Unsupported Position attribute 120 Unsupported Truncation attribute 121 Unsupported Attribute Set 122 Unsupported Completeness attribute 123 Unsupported attribute combination 124 Unsupported coded value for term 125 Malformed search term 126 Illegal term value for attribute 127 Unparsable format for un normalized value 128 Illegal result set name 129 Proximity search of sets not supported 130 Illegal result set in proximity search 131 Unsupported proximity relation 132 Unsupported proximity unit code 201 Proximity not supported with this attribute combination 202 Unsupported distance for proximity 203 Ordered flag not supported for proximity 205 Only zero step size supported for Scan 206 Specified step size not supported for Scan 207 Cannot sort according to sequence 208 No result set name supplied on Sort 209 Generic sort not supported database specific sort only supported 210 Database specific sort not supported 211 Too many sort keys YAZ User s Guide and Reference 171 184
18. Option Description Default databaseName Database from connection object Default Table 3 11 Database Create Options Option Description Default databaseName Database from connection object Default Table 3 12 Database Drop Options 3 7 5 Commit Operation For Commit type must be set to commit in ZOOM_package_send 3 7 6 Protocol behavior All the extended services are Z39 50 only Note The database create drop and commit services are privately defined operations Refer to esadmin asn in YAZ for the ASN 1 definitions 3 8 Options Most ZOOM objects provide a way to specify options to change behavior From an implementation point of view a set of options is just like an associative array hash ZOOM_ options ZOOM options _ create void ZOOM_ options ZOOM options create with parent ZOOM options parent void ZOOM options destroy ZOOM options opt const char ZOOM_options_get 7Z0OOM options opt const char xname void ZOOM options set ZOOM options opt const char name const char xv typedef const char x x7O0O0OM options callback void xhandle const char xname YAZ User s Guide and Reference 31 184 ZOOM_options_callback ZOOM options set callback ZOOM options opt ZOOM options callback c void x handle 3 9 Query conversions int ZOOM query_cql2rpn ZOOM query s const char cql_str ZOOM connection conn int Z00M_query_ccl2rpn Z00M_gquery s
19. Pieter Van Lierop Stefan Lohrum Ronald van der Meer Thomas W Place Peter Popovics Jacob Chr Poulsen Ko van der Sloot Mike Taylor Rustam T Usmanov Charles Woodfield Tom Andr verland
20. The format argument controls whether record data should be XML pretty printed post process operation It is enabled only if format value v is 1 and the record content is XML well formed In addition for certain types the length 1en passed will be set to the size in bytes of the returned informa tion The following are the supported values for form database The Database of the record is returned as a C null terminated string Return type const char x syntax The transfer syntax of the record is returned as a C null terminated string containing the symbolic name of the record syntax e g Usmarc Return type is const char x schema The schema of the record is returned as a C null terminated string Return type is const char render The record is returned in a display friendly format Upon completion buffer is returned type const char x and length is stored in xlen raw The record is returned in the internal YAZ specific format For GRS 1 Explain and others the raw data is returned as type Z_External which is just the type for the member retrievalRec ord in type NamePlusRecord For SUTRS and octet aligned record including all MARCs the octet buffer is returned and the length of the buffer xml The record is returned in XML if possible SRU Solr and Z39 50 records with transfer syntax XML are returned verbatim MARC records are returned in MARCXML converted from ISO2709 to MARCXML by YAZ OPAC records are also converted
21. Z SRW_GDU xxhandler data void client_data const char x ns Here Z_SRW_GDU is either searchRetrieveRequest or a searchRetrieveResponse Note The xQuery and xSortKeys are not handled yet by the SRW implementation of YAZ Explain is also miss ing Future versions of YAZ will include these features The definition of searchRetrieveRequest is typedef struct define Z_SRW_query_type_cql 1 define Z_SRW_query_type_xcgl 2 define Z SRW guery type paf 3 int guery type union char x cql char xcql char pqf query define Z SRW sort type none 1 define Z SRW sort type sort 2 define Z_SRW_sort_type_xSort 3 int sort type union char none char sortKeys char x xSortKeys sort int xstartRecord int x maximumRecords char recordSchema char xrecordPacking char database Z_SRW_searchRetrieveRequest Please observe that data of type xsd string is represented as a char pointer char A null pointer means that the element is absent Data of type xsd integer is representd as a pointer to an int int x Again a null pointer us used for absent elements The SearchRetrieveResponse has the following definition typedef struct int numberOfRecords char resultSetld int x resultSetldleTime YAZ User s Guide and Reference 63 184 Z_SRW_ record xrecords int num records Z_SRW_ diagnostic diagnostics int
22. in num diagnostics xnextRecordPosition Z_SRW_searchRetrieveResponse The num_records and num_diagnostics is number of returned records and diagnostics respectively and also correspond to the size of arrays records and diagnostics A retrieval record is defined as follows typedef struct char xrecordSchema char xrecordData_buf int in recordData_len recordPosition Z_SRW_record The record data is defined as a buffer of some length so that data can be of any type SRW 1 0 currenly doesn t allow for this only XML but future versions might do And a diagnostic as typedef struct int char details Z_SRW diagnostic code YAZ User s Guide and Reference 65 184 Chapter 7 Supporting Tools In support of the service API primarily the ASN module which provides the pro grammatic interface to the 239 50 APDUs YAZ contains a collection of tools that support the development of applications 7 1 Query Syntax Parsers Since the type 1 RPN query structure has no direct useful string representation every origin application needs to provide some form of mapping from a local query notation or representation to a Z RPNQuery structure Some programmers will prefer to construct the query manually perhaps using odr_malloc to simplify memory management The YAZ distribution includes three separate query generating tools that may be of use to you 7 1 1 Prefix Query
23. lalibs Return library specification cflags Return C Compiler flags include Return C compiler includes for YAZ header files Ipath comp Returns full path to YAZ ASN 1 compiler yaz asncomp V Returns YAZ SHA1 ID from Git and version FILES usr bin yaz config usr lib libyazx a usr include yaz x h SEE ALSO yaz 7 Section How to make apps using YAZ on UNIX in the YAZ manual 11 4 yaz yaz Z39 50 toolkit DESCRIPTION YAZ is a C C programmer s toolkit supporting the development of Z39 50v3 clients and servers The YAZ toolkit offers several different levels of access to the IS023950 Z39 50 SRU Solr client only and ILL protocols The level that you need to use depends on your requirements and the role server or client that you want to implement COPYRIGHT Copyright O 1995 2015 Index Data All rights reserved Redistribution and use in source and binary forms with or without modification are permitted provided that the following conditions are met e Redistributions of source code must retain the above copyright notice this list of conditions and the following disclaimer e Redistributions in binary form must reproduce the above copyright notice this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution e Neither the name of Index Data nor the names of its contributors may be used to endorse or promote prod
24. say Z_InitRequest a function is provided that allocates and initializes an instance of that PDU type for you In the case of the InitRequest the function is simply named zget_InitRequest and it sets up reasonable default value for all of the mandatory members The optional members are generally initialized to null pointers This last aspect is very important it ensures that if the PDU definitions are extended after you finish your implementation to accommodate new versions of the protocol say you won t get into trouble with uninitialized pointers in your structures The functions use odr_malloc to allocate the PDUs and its members so you can free everything again with a single call to odr_reset We strongly recommend that you use the zget_x functions whenever you are preparing a PDU in a C API the zget_ functions would probably be promoted to constructors for the individual types The prototype for the individual PDU types generally look like this Z_ lt type gt zget_ lt type gt ODR o eg Z_InitRequest x zget_InitRegquest ODR o The ODR handle should generally be your encoding stream but it needn t be As well as the individual PDU functions a function zget_APDU is provided which allocates a top level Z APDU of the type requested Z_APDU xzget_APDU ODR o int which The which parameter is of course the discriminator belonging to the Z_APDU CHOICE type All of the
25. 6 lt gt 100 a phonetic 101 stem 102 relevance 103 always matches Position attribute 3 Values 1 first in field 2 first in any subfield 3 any position p value in field Structure attribute 4 Values 1 phrase 2 word 3 key 4 year 5 date 6 word list 100 date un 101 name norm 102 name un 103 structure 104 urx 105 or free form text 106 document text 107 local number 108 string 109 numeric string durs Truncation attribute 5 Values 1 right 2 left 3 left amp right 100 none 101 process 102 regular 1 103 regular 2 104 CCL Completeness attribute 6 Values 1 incomplete subfield 2 complete subfield 3 c value complete field Table 7 1 Common Bib 1 attributes ti ranked knuth computer which will set relation ranked use title structure phrase Query date gt 1980 is a valid query But A gt 1980 is invalid 7 1 2 2 2 Qualifier alias A qualifier alias is of the form q ql q2 which declares q to be an alias for q1 q2 such that the CCL query q x is equivalent to q1 x or q2 x CET get 7 1 2 2 3 Comments Lines with white space or lines that begin with character are treated as comments 7 1 2 2 4 Directives Directive specifications takes the form directive value Description The structure is set to either word or phrase depending on the number of tokens in a term phrase word Each token in the term is ANDed and list
26. Bib 1 is used if no attribute set is given and va1 is attribute value The t ype can be specified as an integer or as it be specified either as a single letter u for use r for relation p for position s for structure t for truncation or c for completeness The attributes for the special qualifier name term are used when no CCL qualifier is given in a query Refer to Bib 1 Attribute Set 7 or the complete list of Bib 1 attributes It is also possible to specify non numeric attribute values which are used in combination with certain types The special combinations are Example 7 9 CCL profile Consider the following definition BL u 4 s 1 au u 1 s 1 term s 105 ranked r 102 date u 30 r 0 ti and au both set structure attribute to phrase s 1 ti sets the use attribute to 4 au sets the use attribute to 1 When no qualifiers are used in the query the structure attribute is set to free form text 105 rule for term The date sets the relation attribute to the relation used in the CCL query and sets the use attribute to 30 Bib 1 Date You can combine attributes To Search for ranked title you can do YAZ User s Guide and Reference 73 184 Type Description Use attribute 1 Common use attributes are 1 Personal name 4 Title 7 ISBN 8 as ISSN 30 Date 62 Subject 1003 Author 1016 Any Specify value as an integer Relation attribute 2 Common values are 1 lt 2 lt 3 4 gt 5 gt
27. Geo attset ATTSET Name Class Constant OID Z3950_PREFIX 3 9 yaz_oid_attset_zbig one alee 73950_PREFIX 3 10 yaz_oid_attset_util ou SE 73950_PREFIX 3 11 X yaz_oid_attset_xd_l al ATTSBI Z3950_PREFIX 3 12 yaz_oid_attset_zthes ane APD Z3950_PREFIX 3 13 yaz_oid_attset_fin_ deis ART 73950_PREFIX 3 14 yaz_oid_attset_dan_1 Dane nurse Z3050_PREFIX 3 15 yaz_oid_attset_holdings Monoa ALARA 73950_PREFIX 3 16 yaz_oid_attset_marc MARE SON 73950_PREFIX 3 17 yaz_oid_attset_bib_2 is ATISEL Z3950_PREFIX 3 18 yaz_oid_attset_zeerex NR AUSEL Z3950_PREFIX 3 19 yaz_oid_attset_thesaurus_at Thesaurus attset ATTSET tset Z3950_PREFIX 3 1000 81 1 yaz_oid_attset_idxpath TAIN AVET Z3950_PREFIX 3 1000 81 2 yaz_oid_attset_extlite PATATE ALISET Z3950_PREFIX 3 1000 81 3 Pa yaz_oid_diagset_bib_1 BIDI PRE 73950_PREFIX 4 1 ve yaz_oid_diagset_diag_1 Diag 1 DIAGSET Z3950_PREFIX 4 2 ne yaz_oid_diagset_diag_es peers DIASSET Z3950_PREFIX 4 3 Diag General DIAGSET yaz_oid_ diagset_diag_ general Z3950_PREFIX 4 3 yaz_oid_recsyn_unimarc AS KESS Z3950_PREFIX5 1 yaz_oid_recsyn_intermarc Intermarc RECSYN 73950 PREFIX 5 2 yaz_oid_recsyn_ccf es PRE Z3950_PREFIX 5 3 yaz_oid_recsyn_usmarc Hamag REGRANN Z3950_PREFIX 5 10 MARC21 RECSYN yaz_oid_recsyn_marc21
28. These are declared in yaz oid_std h but are included by yaz oid db h as well Example 7 17 Use a built in OID We can allocate our own OID filled with the constant OID for Bib 1 with Oce oic sorol oek old yaz olc attset olol p 7 3 Nibble Memory Sometimes when you need to allocate and construct a large interconnected complex of structures it can be a bit of a pain to release the associated memory again For the structures describing the Z39 50 PDUs and related structures it is convenient to use the memory management system of the ODR subsystem see Section 8 2 However in some circumstances where you might otherwise benefit from using a simple nibble memory management system it may be impractical to use odr_malloc and odr_reset For this purpose the memory manager which also supports the ODR streams is made available in the NMEM module The external interface to this module is given in the nmem h file The following prototypes are given NMEM nmem_create void void nmem_destroy NMEM n void nmem_malloc NMEM n size_t size void nmem_ reset NMEM n size t nmem_ total NMEM n void nmem_init void void nmem_exit void The nmem_create function returns a pointer to a memory control handle which can be released again by nmem_destroy when no longer needed The function nmem_malloc allocates a block of memory of the requested size A call to nmem_reset or nmem_dest roy
29. int len void stream_close void handle Here the user provides an opaque handle and two handlers stream write for writing and stream_c lose which is supposed to close free resources associated with handle The stream close handler is optional and if NULL for the function is provided it will not be invoked The stream write takes the ODR handle as parameter the user defined handle a type ODR_OCTETSTRING ODR_VISIBLESTRING which indicates the type of contents is being written Another utility useful for diagnostics error handling or as part of the printing facilities is const char xodr_get_element_path ODR o which returns a list of current elements that ODR deals with at the moment For the returned array say ar ar 0 is the top level element ar n is the last The last element has the property that ar n 1 NULL Example 8 3 Element Path for record For a database record part of a PresentResponse the array returned by odr_get_element is presentR esponse databaseOrSurDiagnostics record databaseRecord The question mark appears due to unnamed constructions 8 2 5 Diagnostics The encoding decoding functions all return 0 when an error occurs Until you call odr_reset you cannot use the stream again and any function called will immediately return 0 To provide information to the programmer or administrator the function void odr_perror ODR o char message
30. n 1 When no events are pending for the connections a value of zero is returned To ensure that all outstanding requests are performed call this function repeatedly until zero is returned If ZOOM_event returns and returns non zero the last event that occurred can be expected int ZOOM connection last event ZOOM connection cs ZOOM connection last event returns an event type integer for the last event Event Description ZOOM_EVENT_NONE No event has occurred ZOOM_EVENT_CONNECT TCP IP connect has initiated ZOOM_EVENT_SEND_DATA Data has been transmitted sending ZOOM_EVENT_RECV_DATA Data has been received ZOOM_EVENT_TIMEOUT Timeout ZOOM_EVENT_UNKNOWN Unknown event ZOOM_EVENT_SEND_APDU An APDU has been transmitted sending ZOOM_EVENT_RECV_APDU An APDU has been received ZOOM_EVENT_RECV_RECORD A result set record has been received ZOOM_EVENT_RECV_SEARCH A search result has been received Table 3 13 ZOOM Event IDs YAZ User s Guide and Reference 33 184 Chapter 4 Generic server 4 1 Introduction If you aren t into documentation a good way to learn how the back end interface works is to look at the backend h file Then look at the small dummy server in ztest ztest c The backend h file also makes a good reference once you ve chewed your way through the prose of this file If you have a database system that you would l
31. would be z_SUTRS a function pointer If you receive an EXTERNAL which contains an octet string value that you suspect of being an ASN I structured data value you can use z_ext_gettypebyref to look for the provided direct reference If the return value is different from NULL you can use the provided function to decode the BER string see Section 8 2 If you want to send EXTERNALS containing ASN 1 structured values in the occtet aligned branch of the CHOICE this is possible too However on the encoding phase it requires a somewhat involved juggling around of the various buffers involved If you need to add new externally defined data types you must update the struct above in the source file prt ext h as well as the encoder decoder in the file prt ext c When changing the latter remember to update both the arm arrary and the list type_table which drives the CHOICE biasing that 1s necessary to tell the different structured types apart on decoding Note Eventually the EXTERNAL processing will most likely automatically insert the correct OIDs or indirect refs First however we need to determine how application context management specifically the presentation context list should fit into the various modules 5 4 PDU Contents Table We include for reference a listing of the fields of each top level PDU as well as their default settings YAZ User s Guide and Reference 53 184
32. 0 num_segmentRecords Odr_int 0 segmentRecords Z_NamePlusRecord NULL otherInfo Z_OtherInformation NULL Table 5 16 Default settings for Segment Field Type Default Value referenceld Z_Referenceld NULL closeReason Odr_int Z_Close_finished diagnosticInformation char NULL resourceReportFormat Odr_oid NULL resourceFormat Z_External NULL otherInfo Z_OtherInformation NULL Table 5 17 Default settings for Close YAZ User s Guide and Reference 59 184 Chapter 6 SOAP and SRU 6 1 Introduction YAZ uses a very simple implementation of SOAP that only currenly supports what is sufficient to offer SRU SOAP functionality The implementation uses the tree API of libxml2 to encode and decode SOAP packages Like the Z39 50 ASN 1 module the YAZ SRU implementation uses simple C structs to represent SOAP packages as well as HTTP packages 6 2 HTTP YAZ only offers HTTP as transport carrier for SOAP but it is relatively easy to change that The following definition of Z_GDU Generic Data Unit allows for both HTTP and Z39 50 in one packet include lt yaz zgdu h gt define Z GDU 23950 1 define Z_GDU_HTTP_Request 2 define Z_GDU_HTTP_Response 3 typedef struct int which union Z APDU z3950 Z_HTTP_Request HTTP_Request Z_HTTP_Response HTTP_Response u Z_GDU The corresponding Z_GDU encoder decoder is z_GDU The z3950 is any of the known BER encode
33. 0 the proximity condition must hold e distance 3 the terms must be three units apart e ordered 1 they must occur in the order they are specified e relation 2 lessThanOrEqual to the distance of 3 units e which code is known so the standard unit codes are used e unit code 2 word So the whole proximity query means that the words dylan and zimmerman must both occur in the record in that order differing in position by three or fewer words 1 e with two or fewer words between them The query would find Bob Dylan aka Robert Zimmerman but not Bob Dylan born as Robert Zimmerman since the distance in this case is four Example 7 6 PQF specification of search term type term string a UTF 8 string maybe Example 7 7 PQF mixed queries Gor Qand bob dylan set Result 1 attr 4 1 Rand attr 1 1 bob dylan Q attr 1 4 slow train coming and attr 2 4 attr gils 1 2038 114 attr 2 2 attr gils 1 2039 109 The last of these examples is a spatial search in the GILS attribute set access point 2038 indicates West Bounding Coordinate and 2030 indicates East Bounding Coordinate so the query is for areas extending from 114 degrees to no more than 109 degrees 7 1 2 CCL Not all users enjoy typing in prefix query structures and numerical attribute values even in a minimalis tic test client In the library world the more intuitive Common Command Language CCL ISO 8777 has enjoye
34. 11 1 yaz client 11 2 yaz ztest 11 3 yaz config 114 yaz 11 5 zoomsh 11 6 yaz asncomp 11 7 yaz marcdump 11 8 yaz iconv 11 9 yaz log 11 10yaz illclient 11 11yaz icu 11 12yaz url 11 13Bib 1 Attribute Set 11 14yaz json parse List of Object Identifiers Bib 1 diagnostics SRU diagnostics License D 1 Index Data Copyright About Index Data Credits 119 120 121 122 122 125 127 127 133 139 140 141 142 144 146 148 151 152 154 155 159 161 169 175 179 179 181 183 YAZ User s Guide and Reference xi List of Figures LM YAZ TayETS oe ee eo eee ae ed Ad Aids Se e a de A ete A de oe tee de 3 YAZ User s Guide and Reference xiii List 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 3 10 3 11 3 12 3 13 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 5 10 5 11 5 12 of Tables ZOOM Connection Options 16 ZOOMsortstrategy 17 ZOOM Result set OPLONS 2 26 e 202 Nasa eee AA ANS A A ee 19 Search Info Report Options 19 ZOOM Sean Set Options 25 Extended Service Typ eos abces aoe Brae aoe ae ee bare UN UN res 26 Extended Service Common Options 27 Item Order Opuons s 2 4 2 4 2 46 IIIA aaa
35. 1659 900 vell i Teil e odr_sequence_end o amp amp odr_constructed_end o Notice that the interface here gets kind of nasty The reason is simple Explicitly tagged constructed types are fairly rare in the protocols that we care about so the esthetic annoyance not to mention the dangers of a cluttered interface is less than the time that would be required to develop a better interface Nevertheless it is far from satisfying and it s a point that will be worked on in the future One option for you would be to simply apply the odr_explicit_tag macro to the first function and not have to worry about odr_constructed_ yourself Incidentally as you might have guessed the odr_sequence_ functions are themselves implemented using the odr_constructed_ functions 8 3 5 SEQUENCE OF To handle sequences arrays of a specific type the function int odr_sequence_of ODR o int fun ODR o void xp int optional void xp int num const char xname The fun parameter is a pointer to the decoder encoder function of the type p is a pointer to an array of pointers to your type num is the number of elements in the array Assume a type MyArray SEQUENCE OF INTEGER The C representation might be typedef struct MyArray int num_elements Odr_int xelements MyArray YAZ User s Guide and Reference 111 184 And the function might look like int myArray ODR o MyArray xxp int optional const char name
36. 45 41 23 11 yaz ztest requestdetail pms 1048576 mrs 1048576 14 45 41 23 11 yaz ztest request Present 1 1 1 OK 1 records returned LOG FILENAME EXAMPLES A file with format my_Y Y Y YMMDD log is where Y M Dis year month and day digits is given as follows 1 my_ Y m d log And since the filename is depending on day rotaion will occur on midnight A weekly log could be specified as 1 my_SY U 1log FILES prefix include yaz log h prefix src log c SEE ALSO yaz 7 yaz ztest 8 yaz client 1 strftime 3 11 10 yaz iliclient yaz illclient ILL client Synopsis yaz illclient f filename v l1oglevel Dname value o u user p passw ord V server addr DESCRIPTION yaz illclient is an client which sends an ISO ILL request to a remote server and decodes the response from it Exactly one server address server addr must be specified OPTIONS f filename Specify filename V loglevel Specify the log level D name value Defines name amp value pair 0 Enable OCLC authentication u user Specify user p password Specify password V Show yaz illclient version EXAMPLES None yet FILES None yet SEE ALSO yaz 7 11 11 yaz icu yaz icu YAZ ICU utility Synopsis yaz icu c config p opt s x infile DESCRIPTION yaz icu is utility which demonstrates the ICU chain module of yaz yaz icu h The ut
37. 47 Subject subdivision 48 Number natl biblio YAZ User s Guide and Reference 157 184 49 Number legal deposit 50 Number govt pub Sl Number music publisher 52 Number db BS Number local call 54 Code language 55 Code geographic 56 Code institution 57 Name and title 58 Name geographic 59 Place publication 60 CODEN 61 Microform generation 62 Abstract 63 Note 1000 Author title 1001 Record type 1002 Name 1003 Author 1004 Author name personal 1005 Author name corporate 1006 Author name conference 1007 Identifier standard 1008 Subject LC childrens 1009 Subject name personal 1010 Body of text 1011 Date time added to db 1012 Date time last modified LOS Aurcioriry rormart LEl 1014 Concept text LOS Concept rererene 1016 Any 1017 Server choice 1018 Publisher 1019 Record source O20 PETOT 1021 Bib level 1022 Geographic class 1023 Indexed by 1024 Map scale 1025 Music key 1026 Related periodical 1027 Spore Mums cra 1028 Stock number 1030 Thematic number 1031 Material type OSADO Sel 1033 Host item 1034 Content type 1035 Anywhere 1036 Author Title Subject RELATION 2 1 Less than 2 Less than or equal 3 Equal 4 5 6 Greater or equal Greater than Not equal 100 Phonetic 101 Stem 102 Relevance 103 AlwaysMatches POSITION 3 l mireg alia ieskeulel 2 Watiegie ala Sblouzale lol 3 Any position in field
38. 8 gt lt backend gt lt retrieval gt lt retrieval syntax xml lt backend syntax usmarc lt marc inputformat marc inputcharset marc 8 gt SuSe lt backend gt lt retrieval gt lt retrievalinfo gt This means that our frontend supports e MARC21 F ull records e MARC21 B rief records e MARCXML records e Dublin core records name F gt output format marcxml name dc gt name F gt output format marcxml stylesheet MARC21s1im2DC xs1 gt YAZ User s Guide and Reference 93 184 Example 7 20 MARCXML backend SRW SRU and Solr backends returns records in XML If they return MARCXML or MarcXchange the retrieval module can convert those into IS02709 formats most commonly USMARC AKA MARC21 In this example the backend returns MARCXML for schema marcxml lt retrievalinfo gt lt retrieval syntax usmarc gt lt backend syntax xml name marcxml gt lt marc inputformat xml outputformat marc outputcharset marc 8 gt lt backend gt lt retrieval gt lt retrieval syntax xml name marcxml identifier info srw schema 1 marcxml v1 1 gt lt retrieval syntax xml name dc gt lt backend syntax xml name marcxml gt lt xslt stylesheet MARC21slim2DC xsl gt lt backend gt lt retrieval gt lt retrievalinfo gt This means that our frontend supports e MARC21 records any element set name in MARC 8 e
39. Advance danmarc decode Danmarc in danish is an encoding based on UNICODE which is used for DanMARC2 records EXAMPLES The following command converts from ISO 8859 1 Latin 1 to UTF 8 VaZ LeOny E LSO 8899 1 UN 8S lt INPUT Isic Soucout LST FILES prefix bin yaz iconv prefix include yaz yaz iconv h SEE ALSO yaz 7 iconv 1 11 9 yaz log yaz log Log handling in all yaz based programs Synopsis yaz XXXX v loglevel 1 logfile DESCRIPTION All YAZ based programs use a common log subsystem and should support common command line options for controlling it This man page documents those OPTIONS l logfile Specify the file where the log is to be written If none is specified stderr is used The log is appended to this file If the file grows overly large it is silently rotated It is renamed to logfile l logfile 2 9 old such file is deleted and a new file is opened The limit defaults to 1GB but can be set by the program The rotating limit can be specified with option r for the YAZ frontend server yaz ztest Rotation can also be implicitly enabled by using a filename which gets changed for a given date due to substitutions as given by the strftime 3 function y loglevel Specify the logging level The argument is a set of log level names separated by commas no whitespace optionally preceded by a to negate that level Most programs have their own default
40. Default Value referenceld Z_Referenceld NULL deleteFunction Odr_int Z_DeleteResultSetRequest_list num_ids Odr_int 0 resultSetList char NULL otherInfo Z_OtherInformation NULL Table 5 7 Default settings for Delete Result Set Request Field Type Default Value referenceld Z_Referenceld NULL deleteOperationStatus Odr_int Z_DeleteStatus_success num_ statuses Odr_int 0 deleteListStatuses Z_ListStatus NULL numberNotDeleted Odr_int NULL num_bulkStatuses Odr_int 0 bulkStatuses Z_ListStatus NULL deleteMessage char NULL otherInfo Z_OtherInformation NULL Table 5 8 Default settings for Delete Result Set Response Field Type Default Value referenceld Z_Referenceld NULL num_databaseNames Odr_int 0 databaseNames char NULL attributeSet Odr_oid NULL termListAndStartPoint Z_AttributesPlus NULL stepSize Odr_int NULL numberOfTermsRequested Odr_int 20 preferredPositionInResponse Odr_int NULL otherInfo Z_OtherInformation NULL Table 5 9 Default settings for Scan Request Field Type Default Value referenceld Z_Referenceld NULL stepSize Odr_int NULL scanStatus Odr_int Z_Scan_success numberOfEntriesReturned Odr_int 0 positionOfTerm Odr_int NULL entries Z_ListEntris NULL attributeSet Odr_oid NULL otherInfo Z_OtherInformation NULL Table 5 10 Default settings for Scan Response Field Type Default Value refer
41. Format Since RPN or reverse polish notation is really just a fancy way of describing a suffix notation format operator follows operands it would seem that the confusion is total when we now introduce a prefix notation for RPN The reason is one of simple laziness it s somewhat simpler to interpret a prefix format and this utility was designed for maximum simplicity to provide a baseline representation for use in simple test applications and scripting environments like Tcl The demonstration client included with YAZ uses the PQF Note The PQF have been adopted by other parties developing 239 50 software It is often referred to as Prefix Query Notation PQN The PQF is defined by the pquery module in the YAZ library There are two sets of function that have similar behavior First set operates on a PQF parser handle second set doesn t First set set of functions are more flexible than the second set Second set is obsolete and is only provided to ensure backwards compatibility First set of functions all operate on a PQF parser handle include lt yaz pquery h gt YAZ_PQF_Parser yaz_pqf_create void void yaz pgf destroy YAZ POF _Parser p Z_RPNQuery yaz_pqf_parse YAZ_PQF_Parser p ODR o const char qbuf Z_AttributesPlusTerm yaz_pqf_scan YAZ_PQF Parser p ODR o Odr_oid x attributeSetld const char x qbuf int yaz_pgf_error YAZ_PQF_Parser p const char x xmsg size_t xoff A PQF parser is
42. TCP IP information alone port and address The YAZ frontend server uses XML to describe the backend configurations Command line option f specifies filename of the XML configuration The configuration uses the root element yazgfs This element includes a list of Listen elements fol lowed by one or more server elements The listen describes listener transport end point such as TCP IP Unix file socket or SSL server Con tent for a listener CDATA required The CDATA for the listen element holds the listener string such as tcp 210 tcp serverl1 2100 etc attribute id optional Identifier for this listener This may be referred to from server sections Note We expect more information to be added for the listen section in a future version such as CERT file for SSL servers The server describes a server and the parameters for this server type Content for a server attribute id optional Identifier for this server Currently not used for anything but it might be for logging purposes attribute listenref optional Specifies one or more listeners for this server Each server ID is sepa rated by a comma If this attribute is not given the server is accessible from all listeners In order for the server to be used for real however the virtual host must match if specified in the configuration element config optional Specifies the server configuration This is equivalent to the config specified using command li
43. USMARC SUTRS etc none schema Schema for retrieval such as Gils schema none Geo schema etc setname Name of Result Set Result Set ID If this option isn t set the ZOOM module will automatically default allocate a result set name rpnCharset Character set for RPN terms If this is set ZOOM C will assume that the ZOOM application is running UTF 8 Terms in RPN queries are then converted to the rpnCharset If this is unset ZOOM C will not assume any encoding of RPN terms and no conversion is performed none Table 3 3 ZOOM Result set Options Option Description searchresult size number of search result entries This option is non existent if no entries are returned by the server searchresult no id sub query ID searchresult no count result count for item number of hits searchresult no subquery term subquery term searchresult no interpretation term interpretation term searchresult no recommendation term recommendation term Table 3 4 Search Info Report Options 3 3 2 239 50 Protocol behavior The creation of a result set involves at least a SearchRequest SearchResponse protocol handshake Follow ing that if a sort criteria was specified as part of the query a SortRequest SortResponse handshake takes place Note that it is necessary to perform sorting before any retrieval takes place so no records will be returned from the target
44. Z39 50 SRU server but does not use a database It returns a random hit count and returns a subset of a few built in records The listener spec consists of a transport mode followed by a colon followed by a listener address The transport mode is either tcp unix or ssl For TCP and SSL an address has the form hostname IP number portnumber For UNIX local socket the address is the filename of the local socket OPTIONS a file Specify a file for dumping PDUs for diagnostic purposes The special name dash sends output to stderr S Don t fork or make threads on connection requests This is good for debugging but not recommended for real operation Although the server is asynchronous and non blocking it can be nice to keep a software malfunction okay then a crash from affecting all current users 1 Like S but after one session the server exits This mode is for debugging only T Operate the server in threaded mode The server creates a thread for each connection rather than fork a process Only available on UNIX systems that offer POSIX threads s Use the SR protocol obsolete z Use the Z39 50 protocol default This option and s complement each other You can use both multiple times on the same command line between listener specifications see below This way you can set up the server to listen for connections in both protocols concurrently on different local ports 1 file The logfile c confi
45. a a 21 ILL R gu st Options 3 42 34 ed oe Gee a Ge ede ever o BURRS oe oa 28 Record Update Options 29 Database Cr ate OPINIONS lt s dds a Se St A AA RBA Se Se es 30 Database Drop Options 30 ZOOM Event IDs 32 sis sis se Liebe aa ep ets ses here 32 Default settings for PDU Initialize Request 53 Default settings for PDU InitializeResponse 53 Default settings for PDU Search Request 54 Default settings tor PDU Search Response co 4 25469 449 oe 2 ead oad av have 54 Default settings for PDU Present Request 55 Default settings for PDU Present Response 59 Default settings for Delete Result Set Request 99 Default settings for Delete Result Set Response 56 Default settingsforScanReguest 56 Default settingsforScanResponse 56 Default settings for Trigger Resource Control Reguest 56 Default settings for Resource Control Request 37 5 13 Default settings for Resource Control Response 57 5 14 Default settings for Access Control Request 57 5 15 Default settings for Access Control Response 57 5 16 Default settings for S
46. almost independent of the rest of YAZ the only important dependence is of nmem and that only for using the semaphore definition there The dynamic log levels and log rotation were introduced in YAZ 2 0 28 At the same time the log bit names were changed from LOG_something to YLOG_something to avoid collision with syslog h 7 5 MARC YAZ provides a fast utility for working with MARC records Early versions of the MARC utility only allowed decoding of ISO2709 Today the utility may both encode and decode to a varity of formats include lt yaz marcdisp h gt x create handler x yaz_marc_t yaz_marc_create void destroy void yaz_marc_destroy yaz_marc_t mt set XML mode YAZ MARC LINE YAZ_MARC_SIMPLEXML void yaz_marc_xml yaz_marc_t mt int xmlmode define YAZ MARC LINE 0 define YAZ MARC SIMPLEKML 1 define YAZ MARC OAIMARC 2 define YAZ_MARC_MARCXML 3 define YAZ MARC 1S02709 4 define YAZ MARC XCHANGE 5 define YAZ MARC CHECK 6 define YAZ_MARC_TURBOMARC 7 define YAZ MARC JSON 8 supply iconv handle for character set conversion x void yaz_marc_iconv yaz_marc_t mt yaz_iconv_t cd set debug level O none l more 2 even more void yaz_marc_debug yaz_marc_t mt int level decode MARC in buf of size bsize Returns gt 0 on success lt 0 on fail On success result in result with size xrsize x int yaz_marc_decode_buf
47. an OID from string based representation using dots This function take an ODR stream as parameter This stream is used to allocate memory for the data elements which is released on a subsequent call to odr_reset on that stream Example 7 15 Using odr_getoidbystr We can create a OID for the Bib 1 attribute set with Ocli orel soio Ger GeToicdioystr oer Vi 2640 10003 3o 14 The function Ghar orc Oro co close come Clem oi sore Char TONI ES does the reverse of oid_oiddotstring_to_oid It converts an OID to the string based representation using dots The supplied char buffer oidbuf holds the resulting string and must be at least OID_STR_MAX in size OIDs can be copied with oid_oidcpy which takes two OID lists as arguments Alternativly an OID copy can be allocated on a ODR stream with Qer oic macho Orcera ODR O0 Constr Olla orol 0 OIDs can be compared with oid_oidcmp which returns zero if the two OIDs provided are identical non zero otherwise 7 2 1 OID database From YAZ version 3 and later the oident system has been replaced by an OID database OID database is a misnomer the old odient system was also a database The OID database is really just a map between named Object Identifiers string and their OID raw equiva lents Most operations either convert from string to OID or other way around Unfortunately whenever we supply a string we must also specify the OID class The class is necessa
48. as an NT service and mark it as auto start Control the server by going to the Services in the Control Panel remove Use this to remove the server from the NT services Windows NT 2000 XP only t minutes Idle session timeout in minutes k size Maximum record size message size in kilobytes K Forces no keepalive for HTTP sessions By default GFS will keep sessions alive for HTTP 1 1 sessions as defined by the standard Using this option will force GFS to close the connection for each operation r size Maximum size of log file before rotation occurs in kilobytes Default size is 1048576 k 1 GB d daemon Set name of daemon to be used in hosts access file See hosts_access 5 and tcpd 8 m time format Sets the format of time stamps in the log file Specify a string in the input format to strftime V Display YAZ version and exit TESTING yaz ztest normally returns a random hit count between 0 and 24 However if a query term includes leading digits then the integer value of that term is used as hit count This allows testers to return any number of hits yaz ztest includes 24 MARC records for testing Hit counts exceeding 24 will make yaz ztest return the same record batch over and over So record at position 1 25 49 etc are equivalent For XML if no element set is given or element has value marcxml MARCXML is returned each of the 24 dummy records converted from ISO2709 to XML For element set OP OPAC XM
49. can use the ProxyPass directive If you have virtual host srw mydomain you can use the following directives in Apache s httpd conf lt VirtualHost gt ErrorLog home srw logs error_log TransferLog home srw logs access_log ProxyPass http srw mydomain 210 lt VirtualHost gt The above is for the Apache 1 3 series Example 4 3 Running a server with local access only A server that is only being accessed from the local host should listen on UNIX file socket rather than an Internet socket To listen on tmp mysocket Start the server as follows application unix tmp mysocket 4 7 GFS Configuration and Virtual Hosts The Virtual hosts mechanism allows a YAZ frontend server to support multiple backends A backend is selected on the basis of the TCP IP binding port listening adddress and or the virtual host A backend can be configured to execute in a particular working directory Or the YAZ frontend may perform CQL to RPN conversion thus allowing traditional Z39 50 backends to be offered as a SRW SRU service SRW SRU Explain information for a particular backend may also be specified For the HTTP protocol the virtual host is specified in the Host header For the 239 50 protocol the virtual host is specified as in the Initialize Request in the OtherInfo OID 1 2 840 10003 10 1000 81 1 Note Not all Z39 50 clients allow the VHOST information to be set For those the selection of the backend must rely on the
50. const char ccl_str const char x config int x ccl_error const char xxerror_ string int error_pos ZOOM_query_cql2rpn translates the CQL string client side into RPN which may be passed to the server This is useful for servers that don t themselves support CQL for which Z00M_query_cql is useless conn is used only as a place to stash diagnostics if compilation fails if this information is not needed a null pointer may be used The CQL conversion is driven by option cq1f ile from connection conn This specifies a conversion file e g pqf properties which must be present ZOOM_query_ccl2rpn translates the CCL string client side into RPN which may be passed to the server The conversion is driven by the specification given by config Upon completion 0 is returned on success 1 is returned on failure On failure error_string and error_pos hold the error message and position of first error in original CCL string 3 10 Events If you re developing non blocking applications you have to deal with events int ZOOM_event int no ZOOM connection cs The ZOOM_event executes pending events for a number of connections Supply the number of con nections in no and an array of connections in cs cs 0 cs no 1 A pending event could be sending a search receiving a response etc When an event has occurred for one of the connections this function returns a positive integer n denoting that an event occurred for connection cs
51. created and destructed by functions yaz pgf create and yaz_pqf_destroy re spectively Function yaz_pqf_parse parses query given by string qbuf If parsing was successful a 739 50 RPN Query is returned which is created using ODR stream o If parsing failed a NULL pointer is returned Function yaz pgf scan takes a scan query in qbuf If parsing was successful the function returns attributes plus term pointer and modifies attributeSet Id to hold attribute set for the scan re quest both allocated using ODR stream o If parsing failed yaz_pqf_scan returns a NULL pointer Error information for bad queries can be obtained by a call to yaz pgf error which returns an error code and modifies msg to point to an error description and modifies xof f to the offset within last query were parsing failed The second set of functions are declared as follows include lt yaz pquery h gt Z_RPNQuery p_query_rpn ODR o oid_proto proto const char x qbuf Z_AttributesPlusTerm p_query_scan ODR o oid_proto proto Odr_oid attributeSetP const char xqbuf int p_query_attset const char arg The function p_query_rpn takes as arguments an ODR stream see section The ODR Module to pro vide a memory source the structure created is released on the next call to odr_reset on the stream a protocol identifier one of the constants PROTO_Z3950 and PROTO_ SR an attribute set reference and finally a null terminated string holding the query st
52. for local file access using HTTP All URLs with a leading prefix excluded that matches the value of docpath are used for file access For example if the server is to offer access in directory xs1 the docpath would be xs 1 and all URLs of the form http host xs1 will result in a local file access element explain optional Specifies SRW SRU ZeeRex content for this server Copied verbatim to the client As things are now some of the Explain content seem redundant because host information etc is also stored elsewhere element maximumrecordsize optional Specifies maximum record size message size in bytes This value also serves as the maximum size of incoming packages for Record Updates etc It s the same value as that given by the k option element retrievalinfo optional Enables the retrieval facility to support conversions and specifica tions of record formats types See Section 7 6 for more information The XML below configures a server that accepts connections from two ports TCP IP port 9900 and a local UNIX file socket We name the TCP IP server public and the other server internal lt yazgfs gt lt listen id public gt tcp 9900 lt listen gt lt listen id internal gt unix var tmp socket lt listen gt lt server id serverl gt lt host gt serverl mydomain lt host gt lt directory gt var www s1 lt directory gt COMP Uge Comme AOC ONE lt server gt lt server id server2 listenref public inter
53. for the set Example 7 10 CQL to RPN mapping file This simple file defines two context sets three indexes and three relations a position pattern and a default structure set cgl http www loc gov zing cql context sets cql v1 1 set dc http www loc gov zing cql dc indexes v1 0 index cql serverChoice 1 1016 index dc title 1 4 index dc subject 1 21 relation lt 2 1 Clone 2 3 relation scr 2 3 DOSREAIONE AN 3 3 6 1 ST LUCTUS 4 1 With the mappings above the CQL query computer is converted to the PQF attr 1 1016 attr 2 3 attr 4 1 attr 3 3 attr 6 1 computer by rules index cql serverChoice relation scr structure x position any CQL query computer is rejected since position right is undefined CQL query gt my Vitres vuw LOC Wana alinG cre lL Cle ces Aie ON title x is converted to attr 1 4 attr 2 3 attr 4 1 attr 3 3 attr 6 1 x Example 7 11 CQL to RPN string attributes In this example we allow any index to be passed to RPN as a use attribute ij Identiriers or resis usec in chis riles kai set cql info srw cql context set 1 cql v1 1 set rpn http bogus rpn set http bogus rpn The default index when none is specified by the query index cql serverChoice l any index rpn relation eq SEUS VUCS a position any O amp N EH I Wr WwW The http b
54. format field is the record format requested by the client See Section 7 2 A value of NULL for format indicates that the client did not request a specific format The stream argument is an ODR stream which should be used for allocating space for structured data records The stream will be reset when all records have been assembled and the response package has been transmitted For unstructured data the backend is responsible for maintaining a static or dynamic buffer for the record between calls YAZ User s Guide and Reference 41 184 If a SRU SearchRetrieveRequest is received by the frontend server the referenceId is NULL and the format transfer syntax is the OID for XML The schema for SRU is stored in both the Z_RecordCom position structure and schema simple string In the structure the basename is the name of the database that holds the record 1en is the length of the record returned in bytes and record is a pointer to the record last_in_set should be nonzero only if the record returned is the last one in the given result set errcode and errstring if given will be interpreted as a global error pertaining to the set and will be returned in a non surrogate diagnostic If you wish to return the error as a surrogate diagnostic local error you can do this by setting surrogate_flag to 1 also If the Len field has the value 1 then record is assumed to point to a constructed data type The format field will be used to de
55. include Therefore in your applications you should use include lt yaz proto h gt and not include lt proto h gt For Libtool users the yaz config script provides a different variant of option libs called 1a1 ibs that returns the name of the Libtool archive s for YAZ rather than the ordinary ones For applications using the threaded version of YAZ specify threads after the other options When threads is given more flags and linker flags will be printed by yaz config If our previous example was using threads you d have to modify the lines that set CFLAGS and LIBS as follows CFLAGS YAZCONFIG cflags threads LIBS S YAZCONFIG libs threads There is no need specify POSIX thread libraries in your Makefile The LIBS variable includes that as well 23 Windows The easiest way to install YAZ on Windows is by downloading an installer from here The installer comes with source too in case you wish to compile YAZ with different compiler options etc 2 3 1 Compiling from Source on Windows YAZ is shipped with makefiles for the NMAKE tool that comes with Microsoft Visual Studio It has been tested with Microsoft Visual Studio 2013 Start a command prompt and switch the sub directory WIN where the file makefile is located Customize the installation by editing the makefile file for example by using notepad The following summarizes the most important settings in that file DEBUG If
56. interface described here is provided by the 239 50 ASN 1 module and you access it through the proto h header file YAZ User s Guide and Reference 51 184 5 3 EXTERNAL Data In order to achieve extensibility and adaptability to different application domains the new version of the protocol defines many structures outside of the main ASN 1 specification referencing them through ASN 1 EXTERNAL constructs To simplify the construction and access to the externally referenced data the 739 50 ASN 1 module defines a specialized version of the EXTERNAL construct called Z_External It is defined thus typedef struct Z_External Ojoke Del dhrectererenmence int indirect_reference CHATS clio enum x Generic types x Z_External_single 0 A External_octet Z_External_arbitrary x Specific types AS Sana SUNS Z_External_explainRecord Z_External_resourceReportl Z_External_resourceReport2 which union x Generic types Odr_any single_ASN1_type Odr_oct xoctet_aligned Odr_bitmask xarbitrary x Specific types TESIS SUR Se Z_ExplainRecord xexplainRecord Z_ResourceReportl resourceReportl Z_ResourceReport2 resourceReport2 u Z External When decoding the Z39 50 ASN 1 module will attempt to determine which syntax describes the data by looking at the reference fields currently only the direct reference For ASN 1 structured data you need
57. levels are available in any program that uses yaz log Start the program with v none loglevel and do some common operations with it Another way is to grep for yaz_log_m odule_level in the source code as in TLAC a Meme e leal oie xargs grep yaz_log_module_level greas 12 eure O YY E2 Sore eventl malloc nmem odr are used internally for debugging yaz LOG LEVELS FOR CLIENTS zoom logs the calls to the zoom API which may be useful in debugging client applications LOG LEVELS FOR SERVERS server logs the server functions on a high level starting up listening on a port etc session logs individual sessions connections request logs a one liner for each request init search etc requestdetail logs the details of every request before it is passed to the back end and the results received from it Each server program zebra etc is supposed to define its own log levels in addition to these As they depend on the server in question they can not be described here See above how to find out about them LOGGING EXAMPLES See what log levels yaz ztest is using VEZ ASS L y none logleyel TAAS 20 23 11 Log level MALAS 28 11 Oc le vela 149432 PO 23711 loc level aili lo q levels 142433 29 23 au EAS A local 142432 29 223 11 Locilsvel 14243329223 iil Locilevsl 149438329243 itil MLocu
58. lt directory gt lt config gt config cfg lt config gt lt server gt lt yazgfs gt There are three configured backend servers The first two servers server1 and server2 can be reached by both listener addresses server1 is reached by all two since no listenref attribute is specified server2 1s reached by the two listeners specified In order to distinguish between the two a virtual host has been specified for each server in the host elements For server2 elements for CQL to RPN conversion is supported and explain information has been added a short one here to keep the example small The third server server3 can only be reached via listener internal FILES yaz lt version gt ztest yaz ztest c yaz lt version gt include yaz backend h SEE ALSO yaz 7 yaz log 7 YAZ User s Guide and Reference 139 184 11 3 yaz config yaz config Script to get information about YAZ Synopsis yaz config prefix DIR version libs lalibs cflags incl ude comp V libraries DESCRIPTION yaz config is a script that returns information that your own software should use to build software that uses YAZ The following libraries are supported threads Use the threaded version of YAZ OPTIONS prefix DIR Returns prefix of YAZ or assume a different one if DIR is specified version Returns version of YAZ libs Library specification be used when using YAZ
59. non zero SRU error code otherwise zero is re turned conversion successful The meanings of the numeric error codes are listed in the SRU specification somewhere no direct link anymore If conversion fails more information can be obtained by calling int cql_transform_error cql_transform_t ct char x x addinfop This function returns the most recently returned numeric error code and sets the string pointer at xaddi nfop to point to a string containing additional information about the error that occurred for example 1f the error code is 15 Illegal or unsupported context set the additional information is the name of the requested context set that was not recognised The SRU error codes may be translated into brief human readable error messages using const char cgl_strerror int code If you wish to be able to produce a PQF result in a different way there are two alternatives void cql_transform_pr cql_transform_t ct struct cql_ node cn void pr const char buf void client_data void client_data int cql_transform_FILE cql_transform_t ct struct cql_ node cn FILE xf The former function produces output to a user defined output stream The latter writes the result to an already open FILE 7 1 3 4 Specification of CQL to RPN mappings The file supplied to functions cq1_transform_open_FILE cql_transform_open_fname fol lows a structure found in many Unix utilities It co
60. noria steel es rercomisces Sea es sere sac YA Feb l status cs_put stack protocol package protocol package length iit Steeicus moria Stic Ves joules Seal CS sereno sical A percura i x Now get a response x length_incoming cs_get stack amp buf amp size if length_incoming Rotel mets sitas kani akee retuienr is else if length_incoming lt 0 komaa siecle es gers Sea CS SErerror stack we wwe p de Picton rocne fwrite buf length_incoming 1 stdout clean up cs_close stack LE MOVE xfree buf return 05 9 2 Introduction The COMSTACK subsystem provides a transparent interface to different types of transport stacks for the exchange of BER encoded data and HTTP packets At present the RFC1729 method BER over TCP IP local UNIX socket and an experimental SSL stack are supported but others may be added in time The philosophy of the module is to provide a simple interface by hiding unused options and facilities of the underlying libraries This is always done at the risk of losing generality and it may prove that the interface will need extension later on Note There hasn t been interest in the XTImOSI stack for some years Therefore it is no longer supported The interface is implemented in such a fashion that only the sub layers constructed to the transport methods that you wish to use in your application are linked in
61. of related fields and one of our primary long term objectives is the development of a powerful information management system with open network interfaces and hyper media capabilities We make this software available free of charge on a fairly unrestrictive license as a service to the network ing community and to further the development of quality software for open network communication We ll be happy to answer questions about the software and about ourselves in general Index Data ApS Amagerfelledvej 56 2300 Copenhagen S Denmark Email info indexdata dk The Hacker s Jargon File has the following to say about the use of the prefix YA in the name of a software product 2 YAZ User s Guide and Reference 183 184 Appendix F Credits This appendix lists individuals that have contributed in the development of YAZ Some have contributed with code while others have provided bug fixes or suggestions If we re missing somebody of if you for whatever reason don t like to be listed here let us know e Gary Anderson e Dimitrios Andreadis e Morten B geskov e Rocco Carbone e Matthew Carey e Hans van Dalen e Irina Dijour e Larry E Dixson e Hans van den Dool e Mads Bondo Dydensborg e Franck Falcoz e Kevin Gamiel e Morten Garkier Hendriksen e Morten Holmqvist lan Ibbotson Shigeru Ishida e Heiko Jansen David Johnson Oleg Kolobov Giannis Kosmas Kang Jin Lee
62. of several sort strategies for sorting Refer to Table 3 2 7 7 2 Type 7 sort Type 7 sort is an extension to the Bib 1 based RPN query where the sort specification is embedded as an Attribute Plus Term The objectives for introducing Type 7 sorting is that it allows a client to perform sorting even if it does not implement support Z39 50 sort Virtually all 239 50 client software supports RPN queries It also may improve performance because the sort critieria is specified along with the search query The sort is triggered by the presence of type 7 and the value of type 7 specifies the sortRelation The value for type 7 is 1 for ascending and 2 for descending For the sortElement only the generic part is handled If generic sortKey is of type sortField then attribute type 1 is present and the value is sortField InternationalString If generic sortKey is of type sortAttributes then the attributes in list is used generic sortKey of type elementSpec is not supported The term in the sorting Attribute Plus Term combo should hold an integer The value is 0 for primary sorting criteria 1 for second criteria etc 7 8 Facets YAZ supports facets for in Solr SRU 2 0 and Z39 50 protocols Like Type 1 RPN YAZ supports a string notation for specifying facets For the API this is performed by yaz_pqf_parse_facet_list For ZOOM C the facets are given by option facets For yaz client it is used for the facets command The grammar of this speci
63. offset of each record read n MARC output is omitted so that MARC input is only checkecd v Writes more information about the parsing process Useful if you have 1ll formatted 18502709 records as input V Prints YAZ version EXAMPLES The following command converts MARC21 USMARC in MARC 8 encoding to MARC21 USMARC in UTF 8 encoding Leader offset 9 is set to a Both input and output records are ISO2709 encoded vaz MENTE Cua i MARC e Ur mare Il Yao mere rer menea wie ics lt raw The same records may be converted to MARCXML instead in UTF 8 elz meuCobine ENMARO gt Hi WAO wa merci mere ile N AE seul Turbo MARC is a compact XML notation with same semantics as MARCXML but which allows for faster processing via XSLT In order to generate Turbo MARC records encoded in UTF 8 from MARC21 ISO one could use vez mer ccoo ic MANGE ic UNS a Oo Oma ne il a Aa mul FILES prefix bin yaz marcdump prefix include yaz marcdisp h SEE ALSO yaz 7 yaz iconv 1 11 8 yaz iconv yaz iconv YAZ Character set conversion utility Synopsis yaz iconv f from t to v file DESCRIPTION yaz iconv converts data in file in character set specified by from to output in character set as specified by to This yaz iconv utility similar to the iconv found on many POSIX systems Glibc Solaris etc If no file is specified yaz iconv reads from standard input YAZ User s Guide and Refe
64. on connection requests This is good for debugging but not recommended for real operation Although the server is asynchronous and non blocking it can be nice to keep a software malfunction okay then a crash from affecting all current users 1 Like S but after one session the server exits This mode is for debugging only T Operate the server in threaded mode The server creates a thread for each connection rather than fork a process Only available on UNIX systems that offer POSIX threads s Use the SR protocol obsolete z Use the Z39 50 protocol default This option and s complement each other You can use both multiple times on the same command line between listener specifications see below This way you can set up the server to listen for connections in both protocols concurrently on different local ports 1 file The logfile c config A user option that serves as a specifier for some sort of configuration usually a filename The argument to this option is transferred to member configname of the statserv_options_bl ock f vconfig This specifies an XML file that describes one or more YAZ frontend virtual servers C fname Sets SSL certificate file name for server PEM v level The log level Use a comma separated list of members of the set fatal debug warn log malloc all none u uid Set user ID Sets the real UID of the server process to that of the given user It s useful if you aren t comfortable with h
65. packages yaz e Solaris http unixpackages com e FreeBSD http www freshports org net yaz e Debian http packages debian org search keywords yaz Ubuntu https launchpad net ubuntu source yaz e NetBSD http ftp netbsd org pub pkgsrc current pkgsrc net yaz README html 2 2 1 Compiling from source on Unix Note that if your system doesn t have a native ANSI C compiler you may have to acquire one separately We recommend GCC If you wish to use character set conversion facilities in YAZ or if you are compiling YAZ for use with Zebra it is a good idea to ensure that the iconv library is installed Some Unixes today already have it if not we suggest GNU libiconv YAZ 3 0 16 and later includes a wrapper for the ICU International Components for Unicode In order to use this the developer version of the ICU library must be available ICU support is recommended for applications such as Pazpar2 and Zebra The libxslt libxm12 librararies are required if YAZ is to support SRU Solr These libraries are very portable and should compile out of the box on virtually all Unix platforms It is available in binary forms for Linux and others The GNU tools Autoconf Automake and Libtool are used to generate Makefiles and configure YAZ for the system You do not need these tools unless you re using the Git version of YAZ The CQL parser for YAZ is built using GNU Bison This tool is only needed if you re using the Git versi
66. person or institution symbol person transaction id initial requester id person or institution symbol institution transaction id initial requester id name of person or institution name of person transaction id initial requester id name of person or institution name of institution transaction id transaction group qualifier transaction id transaction qualifier transaction id sub transaction qualifier service date time this date service date time this time service date time original date service date time original time requester id person or institution symbol person requester 1d person or institution symbol institution requester id name of person or institution name of person requester 1d name of person or institution name of institution responder id person or institution symbol person responder id person or institution symbol institution responder id name of person or institution name of person responder id name of person or institution name of institution transaction type delivery address postal address name of person or institution name of person delivery address postal address name of person or institution name of institution delivery address postal address extended postal delivery address delivery address postal address street and number delivery address postal address post office box delivery address postal address city
67. provided The odr_sequence_begin function should be called in the beginning of a function that implements a SEQUENCE type Its parameters are the ODR stream a pointer to a pointer to the type you re imple menting and the size of the type typically a C structure On encoding it returns 1 if x p is a null pointer The size parameter is ignored On decoding it returns 1 if the type is found in the data stream size bytes of memory are allocated and xp is set to point to this space odr_sequence_end is called at the end of the complex function Assume that a type is defined like this MySequence SEQUENCE intval INTEGER boolval BOOLEAN OPTIONAL The corresponding ODR encoder decoder function and the associated data structures could be written like this typedef struct MySequence Ocie ime meva Odr_bool x boolval MySequence int mySequence ODR o MySequence lt p int optional const char xname if odr sequence begin o p sizeof p name 0 return optional amp amp odr_ ok o TESTE WIC OS TO amp sd Simewel O Vaimeyeail te och ocol o amp 39 Ssoolhval i H calralt amp amp odr_sequence_end o Note the 1 in the call to odr_bool to mark that the sequence member is optional If either of the member types had been tagged the macros odr_implicit_tag orodr_explicit_tag could have been used The new function can be used exactly like the stan
68. set to 1 the software is compiled with debugging libraries code generation is multi threaded debug DLL If set to 0 the software is compiled with release libraries code generation is multi threaded DLL HAVE_TCL TCL If HAVE_TCL is set to 1 nmake will use the ASN 1 compiler Tcl based You must set TCL to the full path of the Tcl interpreter A Windows version of Tcl is part of Git for Windows If you do not have Tcl installed set HAVE_TCL to 0 HAVE_BISON BISON If GNU Bison is present you might set HAVE_BISON to 1 and specify the Bison executable in BISON Bison is only required if you use the Git version of YAZ or if you modify the grammar for CQL cal y A Windows version of GNU Bison is part of Git for Windows HAVE_ICONV ICONV_DIR If HAVE_ICONV is set to 1 YAZ is compiled with iconv support In this configuration set ICONV_ DIR to the iconv source directory HAVE_LIBXML2 LIBXML2_DIR If HAVE_LIBXML2 is set to 1 YAZ is compiled with SRU support In this configuration set LIBXML2_ DIR to the libxml source directory You can get pre compiled Libxm12 Libxslt DLLs and headers from here Should you with to compile those libraries yourself refer to to Section 2 3 3 HAVE_LIBXSLT LIBXSLT_DIR If HAVE_LIBXSLT is set to 1 YAZ is compiled with XSLT support In this configuration set LIBXSLT_DIR to the libxslt source directory Note libxsit depends on libxml2 HAVE IC
69. st art is positive or if a sorting criteria is set or if piggyback is 0 then the client will not perform piggyback but send Present Requests instead If either of the options mediumSetElementSetName and smallSetElementSetName are unset the value of option element Set Name is used for piggyback searches This means that for the high level mode you only have to specify one elementSetName option rather than three 3 3 3 SRU Protocol behavior Current version of YAZ does not take advantage of a result set id returned by the SRU server Future versions might do however Since the ZOOM driver does not save result set IDs any present retrieval is transformed to a SRU SearchRetrieveRequest with same query but possibly different offsets Option schema specifies SRU schema for retrieval However options element SetName and prefer redRecordSynt ax are ignored Options start and count are supported by SRU The remaining options piggyback smallSetUp perBound largeSetLowerBound mediumSetPresentNumber mediumSetElementSetN ame smallSetElement SetName are unsupported SRU supports CQL queries not PQF If PQF is used however the PQF query is transferred anyway using non standard element pQuery in SRU SearchRetrieveRequest Solr queries need to be done in Solr query format Unfortunately SRU and Solr do not define a database setting Hence dat abaseName is unsupported and ignored However the path part in host parameter fo
70. start and count specifies the range of records to be returned Upon completion the array recs 0 recs count 1 holds record objects for the records The array of records recs should be allocated prior the call ZOOM resultset_ records Note that for those records that couldn t be retrieved from the target recs 1s setto NULL In order to extract information about a single record ZOOM_record_get is provided The function returns a pointer to certain record information The nature type of the pointer depends on the parameter type The typeis a string of the format format charset fron opacfrom to format v base64 xpath If charset is given then from specifies the character set of the record in its original form as returned by the server to specifies the output returned character set encoding If to is omitted then UTF 8 is assumed If charset is not given then no character set conversion takes place OPAC records may be returned in a different set from the bibliographic MARC record If this is this the case opacfrom should be set to the character set of the OPAC record part The format is generic but can only be used to specify XML indentation when the value v is 1 format 1 The base64 allows a full record to be extracted from base64 encoded string in an XML document Note Specifying the OPAC record character set requires YAZ 4 1 5 or later Specifying the base64 parameter requires YAZ 4 2 35 or later
71. stopwords 36 Term in invalid format for index or relation 37 Unsupported boolean operator 38 Too many boolean operators in guery 39 Prozimity not supported 40 Unsupported proximity relation 41 Unsupported proximity distance 42 Unsupported proximity unit 43 Unsupported proximity ordering 44 Unsupported combination of proximity modifiers 45 Prefix assigned to multiple identifiers 46 Unsupported boolean modifier 47 Cannot process query reason unknown 48 Query feature unsupported 49 Masking character in unsupported position 50 Result sets not supported 51 Result set does not exist 52 Result set temporarily unavailable 53 Result sets only supported for retrieval 54 Retrieval may only occur from an existing result set 55 Combination of result sets with search terms not supported 56 Only combination of single result set with search terms supported 57 Result set created but no records available 58 Result set created with unpredictable partial results available 59 Result set created with valid partial results available 60 Result set not created too many matching records 61 First record position out of range 62 Negative number of records requested 63 System error in retrieving records 64 Record temporarily unavailable 65 Record does not exist 66 Unknown schema for retrieval 67 Record not available in this schema 68 Not authorised to send record 69 Not authorised to send record in this schema 70 Record too large to se
72. the resultSetIndicator field in the protocol num_bases basenames is a length of array of character pointers to the database names provided by the client The query is the full query structure as defined in the protocol ASN 1 specification It can be either of the possible query types and it s up to you to determine if you can handle the provided query type Rather than reproduce the C interface here we ll refer you to the structure definitions in the file include yaz z core h If you want to look at the attributeSetId OID of the RPN query you can either match it against your own internal tables or you can use the OID tools The structure contains a number of hits and an errcode errstring pair If an error occurs during the search or if you re unhappy with the request you should set the errcode to a value from the BIB 1 diagnostic set The value will then be returned to the user in a nonsurrogate diagnostic record in the response The errst ring if provided will go in the addinfo field Look at the protocol definition for the defined error codes and the suggested uses of the addinfo field The bend_search handler is also called when the frontend server receives a SRU SearchRetrieveRequest For SRU a CQL query is usually provided by the client The CQL query is available as part of Z_Query structure note that CQL is now part of Z39 50 via an external To support CQL in existing implementations that only do Type 1 we refer to t
73. to XML and the bibliographic record is converted to MARCXML when possible GRS 1 records are not supported for this form Upon completion the XML buffer is returned type const char x and length is stored in len opac OPAC information for record is returned in XML if an OPAC record is present at the position given If no OPAC record is present a NULL pointer is returned txml The record is returned in TurboMARC if possible SRU and Z39 50 records with transfer syntax XML are returned verbatim MARC records are returned in TurboMARC converted from ISO2709 to TurboMARC by YAZ Upon completion the XML buffer is returned type const char x and length is stored in len json Like xml but MARC records are converted to MARC in JSON YAZ User s Guide and Reference 23 184 Most MARC21 records uses the MARC 8 character set encoding An application that wishes to display in Latin 1 would use render charset marc8 1so 8859 1 3 4 1 Z39 50 Protocol behavior The functions ZOOM_resultset_record and ZOOM_resultset_records inspects the client side record cache Records not found in cache are fetched using Present The functions may block and perform network I O even though option async is 1 because they return records objects And there s no way to return records objects without retrieving them There is a trick however in the usage of function ZOOM_resultset_records that allows for delayed retrieval and makes it non blo
74. will release all memory allocated on the handle since it was created or since the last call to nmem_reset The function nmem_total returns the number of bytes currently allocated on the handle The nibble memory pool is shared amongst threads POSIX mutex es and WIN32 Critical sections are introduced to keep the module thread safe Function nmem_init initializes the nibble memory library and it is called automatically the first time the YAZ DLL is loaded YAZ uses function D1 1Main to achieve this You should not call nmem_init or nmem_exit unless you re absolute sure what you re doing Note that in previous YAZ versions you d have to call nmem_init yourself 7 4 Log YAZ has evolved a fairly complex log system which should be useful both for debugging YAZ itself debugging applications that use YAZ and for production use of those applications The log functions are declared in header yaz 1log h and implemented in src log c Due to name clash with syslog and some math utilities the logging interface has been modified as of YAZ 2 0 29 The obsolete interface is still available if in header file yaz 1log h The key points of the interface are voJLc yaz log amc level Const Chai mite aos void yaz_log_init int level const char xprefix const char x name void yaz_log_init_file const char x fname void yaz_log_init_level int level wao yaz Log inie Silo Const voie yaz Loc time tormac Const CAAT SENE p
75. yaz_marc_t mt const char xbuf int bsize const char result size_t rsize decode MARC in buf of size bsize Returns gt 0 on success lt 0 on failu On success result in WRBUF x int yaz_marc_decode_wrbuf yaz_marc_t mt const char buf int bsize WRBUF wrbuf Note The synopsis is just a basic subset of all functionality Refer to the actual header file marcdisp h for details YAZ User s Guide and Reference 89 184 A MARC conversion handle must be created by using yaz_marc_create and destroyed by calling yaz_marc_destroy All other function operate on a yaz_marc_t handle The output is specified by a call to yaz_marc_xml The xm1mode must be one of YAZ_MARC_LINE A simple line by line format suitable for display but not recommend for further ma chine processing YAZ MARC MARCXML MARCXML YAZ_MARC_ISO2709 1802709 sometimes just referred to as MARC YAZ_MARC_ XCHANGE MarcXchange YAZ_MARC_CHECK Pseudo format for validation only Does not generate any real output except diag nostics YAZ_MARC_TURBOMARC XML format with same semantics as MARCXML but more compact and geared towards fast processing with XSLT Refer to Section 7 5 1 for more information YAZ_MARC_JSON MARC in_JSON format The actual conversion functions are yaz_marc_decode_buf and yaz_marc_decode_wrbuf which decodes and encodes a MARC record The former function operates on simple buffers the stores the resulting reco
76. 0x8000 f RONE EOI for ar ei FOT is is oi is oi LOL NO Log loi LS QUE ON h Fh Hh Fh Hh t gt eventl PTE OK to to yaz ztest v requestdetail 148452385237 yaz ztest server Adding static 23950 listener on tcp 9999 145465635237 yaz ztest server Starting server yaz ztest pid 32200 TALA VEZ AOS ES SS SO SE ANOS SS S MON rron kani pid 32200 asas 38 237 yaz ztest requestdetail Got initRequest 113452882387 yaz ztest requestdetail Id 81 1424528823 yaz ztest requestdetail Name YAZ 14 45 38 23 yaz ztest requestdetail Version 2510628 WASH 8 AA yaz ztest requestdetail Negotiated to v3 srch prst del xtendedServices namedresults scan sort 1434553 3 8 23 Vem acesic mE QUES a ETA e seem NON sil were 250423 agas SIS yaz ztest requestdetail Got SearchRequest 141945289237 yaz ztest requestdetail ResultSet 1 MESES IIS yaz ztest requestdetail Database Default LAS 32D yaz ztest requestdetail RPN query Type Bib 1 LASA SI 23 yaz ztest requestdetail term foo general 1ASASRIS 237 yaz ztest requestdetail resultCount 7 14345 392257 yaz ztest request Search Z attrset Bib 1 foo OK 7 hits 145456412237 yaz ztest requestdetail Got PresentRequest YAZ User s Guide and Reference 151 184 14 45 41 23 11 yaz ztest requestdetail Request to pack 1 1 1 14
77. 210 tcp serverl1 2100 etc attribute id optional Identifier for this listener This may be referred to from server sections Note We expect more information to be added for the listen section in a future version such as CERT file for SSL servers YAZ User s Guide and Reference 137 184 The server describes a server and the parameters for this server type Content for a server attribute id optional Identifier for this server Currently not used for anything but it might be for logging purposes attribute listenref optional Specifies one or more listeners for this server Each server ID is sepa rated by a comma If this attribute is not given the server is accessible from all listeners In order for the server to be used for real however the virtual host must match if specified in the configuration element config optional Specifies the server configuration This is equivalent to the config specified using command line option c element directory optional Specifies a working directory for this backend server If specified the YAZ frontend changes current working directory to this directory whenever a backend of this type is started backend handler bend_start stopped backend handler hand_stop and initialized bend_init element host optional Specifies the virtual host for this server If this is specified a client must specify this host string in order to use this backend element cql2rpn opti
78. 5 Record no authorized to be sent intersystem 16 Record exceeds Preferred message size 17 Record exceeds Maximum record size 18 Result set not supported as a search term 19 Only single result set as search term supported 20 Only ANDing of a single result set as search term supported 21 Result set exists and replace indicator off 22 Result set naming not supported 23 Combination of specified databases not supported 24 Element set names not supported 25 Specified element set name not valid for specified database 26 Only a single element set name supported 2 Result set no longer exists unilaterally deleted by target 28 Result set is in use 29 One of the specified databases is locked 30 Specified result set does not exist Code Text 31 Resources exhausted no results available 32 Resources exhausted unpredictable partial results available 33 Resources exhausted valid subset of results available 100 Unspecified error 101 Access control failure 102 Security challenge required but could not be issued request terminated 103 Security challenge required but could not be issued record not included 104 Security challenge failed record not included 105 Terminated by negative continue response 106 No abstract syntaxes agreed to for this record 107 Query type not supported
79. 64 MB This amount of memory will only be allocated if a client requests a very large amount of records in one operation or a big record Set it to a lower number if you are worried about resource consumption on your host system char configname ODR_MAXNAME 1 Passed to the backend when a new connection is received char setuid ODR MAXNAME 1 Set user id to the user specified after binding the listener addresses void x bend start struct statserv_ options block xp Pointer to function which 1s called after the command line options have been parsed but before the server starts listening For forked UNIX servers this handler is called in the mother process for threaded servers this handler is called in the main thread The default value of this pointer is NULL in which case it isn t invoked by the frontend server When the server operates as an NT service this handler is called whenever the service is started void bend_stop struct statserv options block xp Pointer to function which is called whenever the server has stopped listening for incoming connections This function pointer has a default value of NULL in which case it isn t called When the server operates as an NT service this handler is called whenever the service is stopped void handle User defined pointer default value NULL This is a per server handle that can be used to specify user data Do not confuse this with the session handle as returned by bend_in
80. AZ will be linked the ICU library in the prefix if given If prefix is not given the libraries exposed by the script icu config will be used if found with libgcrypt prefix YAZ will be linked with Libgcrypt in the prefix if given If prefix is not given the libraries exposed by the script libgcrypt config will be used if found with memcached YAZ will be linked with libMemcached to allow for result set caching for ZOOM The prefix can not be given Note that YAZ will only search for libMemcached if Libgcrypt is also enabled Note that 0 40 of libmemcached is required with redis YAZ will be linked with the hiredis C library to allow for result set caching for ZOOM on a redis server The prefix can not be given Note that YAZ will only search for hiredis if Libgcrypt is also enabled When configured build the software by typing make The following files are generated by the make process src libyaz la Main YAZ library This is no ordinary library It s a Libtool archive By default YAZ creates a static library in lib libs libyaz a src libyaz server la Generic Frontend server This is an add on for libyaz la Code in this library uses POSIX threads functions if POSIX threads are available on the platform src libyaz_icu la Functions that wrap the ICU library ztest yaz ztest Test Z39 50 server client yaz client Z39 50 client for testing the protocol See chapter YAZ client for more informa tion util yaz con
81. CQL only we don t expect XCQL to be widely used Furthermore CQL has the advantage over XCQL that it is easy to read 7 1 3 1 CQL parsing A CQL parser is represented by the COL_parser handle Its contents should be considered YAZ internal private include lt yaz cql h gt typedef struct cql_parser CQL_ parser COL _parser cql_parser_create void void cgl parser destroy COL parser cp A parser is created by cql_parser_create and is destroyed by cg1 parser destroy To parse a CQL query string the following function is provided int cgql_parser_string CQL_parser cp const char x str A CQL query is parsed by the cq1_parser_string which takes a query str If the query was valid no syntax errors then zero is returned otherwise 1 is returned to indicate a syntax error YAZ User s Guide and Reference 77 184 int cql_parser_stream CQL parser cp int xgetbyte void client data void xungetbyte int b void xclient_ data void client data int cql_parser_stdio CQL_parser cp FILE f The functions cq1_parser_stream and cql_parser_stdio parses a CQL query just like cql_ parser_string The only difference is that the CQL query can be fed to the parser in different ways The cgl parser stream uses a generic byte stream as input The cql_parser_stdio uses a FILE handle which is opened for reading 7 1 3 2 CQL tree The the query string is valid the CQL pars
82. EFINITIONS FILE The definitions file is really a Tcl script but follows traditional rules for Shell like configuration files That is denotes the beginning of a comment Definitions are line oriented The definitions files usually consists of a series of variable assignments of the form set name valu Available variables are default prefix Sets prefix for names in the produced output The value consists of three tokens C function prefix C typedef prefix and preprocessor prefix respectively prefix module This value sets prefix values for module module The value has same form as defa ult prefix filename module Specifies filename for C header file for module module init module h Code fragment to be put in first part of public header for module module body module h Code fragment to be put in last part of public header for module module trailer init module c Code fragment to be put in first part of C based encoder decoder for module module body module c Code fragment to be put in last part of C based encoder decoder for module module trailer map module name Maps ASN I type in module module of name to value membermap module name member Maps member member in SEQUENCE CHOICE of name in module module to value The value consists of one or two tokens First token is name of C pre processor part Second token is resulting C member name If second token is omitted the value one token is both prepro
83. ERNAL type the C representation is provided by the ODR Open Data Representation subsystem ODR is a basic mechanism for representing an ASN 1 type in the C programming language and for im plementing BER encoders and decoders for values of that type The types defined in the Z39 50 ASN 1 module generally have the prefix Z_ and a suffix corresponding to the name of the type in the ASN 1 specification of the protocol generally Z39 50 1995 In the case of base types those originating in the ASN 1 standard itself the prefix Odr_ is sometimes seen Either way look for the actual definition in either z core h for the types from the protocol odr h for the primitive ASN 1 types The Z39 50 ASN 1 library also provides functions which are in turn defined using ODR primitives for encoding and decoding data values Their general form is int z_xxx ODR o Z_xxx p int optional const char name note the lower case z in the function name Note If you are using the premade definitions of the Z39 50 ASN 1 module and you are not adding a new protocol of your own the only parts of ODR that you need to worry about are documented in Section 8 2 When you have created a BER encoded buffer you can use the COMSTACK subsystem to transmit or receive data over the network The COMSTACK module provides simple functions for establishing a connection passively or actively depending on the role of your application and for exchan
84. IKS 1102 D A 73950_PREFIXS 111 ae sce 73950 PREFIX 5 1000 81 2 on E 73050 PREFIX 51000813 22 es 73950 PREFIX 5 1010 text XML RECSYN yaz_oid_recsyn_text_xml YAZ User s Guide and Reference 165 184 Name Class Constant OID Z3950_PREFIX 5 109 10 application XML RECSYN yaz_oid_recsyn_application_ xml Z3950_PREFIX 5 109 11 Resource 1 RESFORM yaz_oid_resform_resource_1 Z3950_PREFIX 7 1 Resource 2 RESFORM yaz_oid_resform_resource_2 Z3950_PREFIX 7 2 UNlverse Resource Report RESFORM yaz_oid_resform_universe_re source_report Z3950_PREFIX 7 1000 81 1 Prompt 1 ACCFORM yaz_oid_accform_prompt_1 Z3950_PREFIX 8 1 Des 1 ACCFORM yaz_oid_accform_des_1 Z3950_PREFIX 8 2 Krb 1 ACCFORM yaz_oid_accform_krb_1 Z3950_PREFIX 8 3 Persistent set EXTSERV yaz_oid_extserv_persistent_ set Z3950_PREFIX 9 1 Persistent query EXTSERV yaz_oid_extserv_persistent_ query Z3950_PREFIX 9 2 Periodic query EXTSERV yaz_oid_extserv_periodic_qu ery Z3950_PREFIX 9 3 Item order EXTSERV yaz_oid_extserv_item_order Z3950_PREFIX 9 4 Database Update first version EXTSERV yaz_oid_extserv_database_up date_first_version Z3950_PREFIX 9 5 Database Update second version EXTSERV yaz_oid_extserv_database_up date_second_version Z3950_P
85. L certificate for comstack as a PEM file This function returns 1 for success 0 for failure int cs get ssl peer certificate x509 COMSTACK cs char xxbuf int x len This function returns the peer certificate If successful buf and len holds X509 buffer and length respectively Buffer should be freed with xfree This function returns 1 for success O for failure 9 8 Diagnostics All functions return 1 if an error occurs Typically the functions will return 0 on success but the data exchange functions cs_get cs_put cs_more follow special rules Consult their descriptions The error code for the COMSTACK can be retrieved using C macro cs_errno which will return one of the error codes CSYSERR CSOUTSTATE CSNODATA int cs_errno COMSTACK handle You can the textual representation of the error code by using cs_errmsg which works like strerror 3 const char x xcs_errmsg int n It is also possible to get straight to the textual represenataion without the error code by using cs_strer LOT const char cs_strerror COMSTACK h 9 9 Summary and Synopsis include lt yaz comstack h gt include lt yaz tcpip h gt x this is for TCP IP and SSL support x include lt yaz unix h gt x this is for UNIX socket support x COMSTACK cs_create CS TYPE type int blocking int protocol YAZ User s Guide and Reference 123 184 COMSTACK cs_createbysocket int s CS TYPE type int block
86. L is returned yaz ztest may also return predefined XML records for testing This is enabled if YAZ_ZTEST_XML_ FETCH environment variable is defined A record is fetched form a file one record per file The path for the filename is FE d xml where F is the YAZ_ZTEST_XML_FETCH value possibly empty E is element set d is record position starting from 1 The following databases are honored by yaz ztest Default slow and db x all databases with prefix db Any other database will make yaz ztest return diagnostic 109 Database unavailable Options for search may be included in the form or URL get arguments included as part of the Z39 50 database name The following database options are present search delay present delay fetch delay and seed The former delay type options specify a fake delay sleep that yaz ztest will perform when searching presenting fetching records respectively The value of the delay may either be a fixed floating point value which specifies the delay in seconds Alternatively the value may be given as two floating point numbers separated by colon which wil make yaz ztest perform a random sleep between the first and second number The database parameter seed takes an integer as value This will call srand with this integer to ensure that the random behavior can be re played Suppose we want searches to take between 0 1 and 0 5 seconds and a fetch to take 0 2 second To access test database Default
87. O0M connection c const char xx cp const char xxaddinfo int ZOOM_connection_error_x ZOOM_connection c const char xx cp const char x x addinfo const char x x dset Function ZOOM_connection_error checks for errors for the last operation s performed The function returns zero if no errors occurred non zero otherwise indicating the error Pointers cp and addinfo holds messages for the error and additional info if passed as non NULL Function ZOOM_connection_ error_x 1s an extended version of ZOOM_connection_error that is capable of returning name of diagnostic set in dset 3 1 1 Z39 50 Protocol behavior The calls ZOOM_connection_new and ZOOM_connection_connect establishes a TCP IP con nection and sends an Initialize Request to the target 1f possible In addition the calls wait for an Initialize Response from the target and the result is inspected OK or rejected If proxy is set then the client will establish a TCP IP connection with the peer as specified by the proxy host and the hostname as part of the connect calls will be set as part of the Initialize Request The proxy server will then forward the PDU s transparently to the target behind the proxy For the authentication parameters if option user is set and both options group and pass are unset then Open style authentication is used Version 2 3 in which case the username is usually followed by a slash then by a password If either group or pass is set then idPass authentica
88. REFIX 9 5 1 Database Update EXTSERV yaz_oid_extserv_database_up date Z3950_PREFIX 9 5 1 1 exp spec EXTSERV yaz_oid_extserv_exp__spec Z3950_PREFIX 9 6 exp inv EXTSERV yaz_oid_extserv_exp__inv Z3950_PREFIX 9 7 Admin EXTSERV yaz_oid_extserv_admin Z3950_PREFIX 9 1000 81 1 searchResult 1 USERINFO yaz_oid_userinfo_searchresu teI Z3950_PREFIX 10 1 Name Class Constant OID CharSetandLanguageNegotiation yaz_oid_userinfo_charsetand USERINFO languagenegotiation Z3950_PREFIX 10 2 yaz_oid_userinfo_userinfo_l UserInfo 1 USERINFO 73950 PREFIX 10 3 yaz_oid_userinfo_multiplese MultipleSearchTerms 1 USERINFO archterms_1 Z3950_PREFIX 10 4 yaz_oid_userinfo_multiplese MultipleSearchTerms 2 USERINFO archterms_2 Z3950_PREFIX 10 5 i yaz_oid_userinfo_datetime DateTime USERINFO 73950 PREFIX 10 6 y yaz_oid_userinfo_proxy Posy USERINEQ Z3950_PREFIX 10 1000 81 1 y yaz_oid_userinfo_ cookie Cooke OO Z3950_PREFIX 10 1000 81 2 5 yaz_oid_userinfo_client_ip SOI DRAC Z3950_PREFIX 10 1000 81 3 y yaz_oid_userinfo_scan_set aladas USERINEO Z3950_PREFIX 10 1000 81 4 a yaz_oid_userinfo_facet_1 pa ee Z3050_PREFIX 10 1000 81 5 yaz_oid_elemspec_espec_1 Dee PEEMPPRE Z3050_PREFIX 11 1 yaz_oid_varset
89. This does not set the structure at all Each token in the term is ORed or list This does not set the structure at all Tokens that appears as phrases with blank in them gets structure phrase attached 4 1 Tokens that appear to be words gets structure word attached 4 2 Phrases and words are ANDed This is a variant of s al and s pw with the main difference that words are not split with operator AND but instead kept in one RPN token This facility appeared in YAZ 4 2 38 Tokens are split into sub phrases of all combinations in order This facility appeared in YAZ 5 14 0 Allows ranges and the operators greather than less than equals This sets Bib 1 relation attribute accordingly relation ordered A query construct is only treated as a range if dash is used and that is surrounded by white space So 1980 is treated as term 1980 not lt 1 980 If 1980 is used however that is treated as a range Similar to r 0 but assumes that terms are non negative not prefixed with Thus a dash will always be treated as a range The construct 1980 1990 is treated as a range with r r but as a single term 1980 1990 with r o The special attribute r r is available in YAZ 2 0 24 or later This will omit relation equals attr 2 3 when r o r r is used This is useful for servers that somehow breaks when an explicit relation equals is used Omitting the relation is usually safe because equals is the d
90. U ICU DIR If HAVE_ICUis set to 1 YAZ is compiled with ICU support In this configuration set ICU_DIR to the ICU source directory When satisfied with the settings in the makefile type nmake Note If the nmake command is not found on your system you probably haven t defined the environment vari ables required to use that tool To fix that find and run the batch file vcvars32 bat You need to run it from within the command prompt or set the environment variables globally otherwise it doesn t work YAZ User s Guide and Reference 11 184 If you wish to recompile YAZ for example if you modify settings in the makefile you can delete object files etc by running nmake clean The following files are generated upon successful compilation bin yaz5 dll bin yaz5d dll YAZ Release Debug DLL lib yaz5 1lib 1ib yaz5d 1ib Import library for yaz5 d11 yaz5d d11 bin yaz_cond5 dll bin yaz_cond5d dll Release Debug DLL for condition variable utilities condvar c lib yaz_cond5 1ib 1ib yaz_cond5d 1ib Import library for yaz_cond5 d11 yaz_cond5d all bin yaz_icu5 dl1l bin yaz_icu5d dll Release Debug DLL for the ICU wrapper utility Only build if HAVE_ICU is 1 lib yaz_icu5 lib lib yaz_icu5d lib Import library for yaz_icu5 d11 yaz_icu5d dil bin yaz ztest exe Z39 50 multi threaded test example server It s a WIN32 console application bin yaz client exe YAZ Z39 50 client application It s a WIN32 co
91. YAZ User s Guide and Reference YAZ User s Guide and Reference Copyright 1995 2015 Index Data YAZ User s Guide and Reference COLLABORATORS TITLE YAZ User s Guide and Reference ACTION NAME DATE SIGNATURE WRITTEN BY Sebastian Hammer Adam Dickmeiss Mike Taylor Heikki Levanto and Dennis Schafroth September 16 2015 REVISION HISTORY NUMBER DATE DESCRIPTION NAME YAZ User s Guide and Reference v Contents 1 Introduction 1 1 1 Reading this Manual 1 12 USAR s cge a egg a ge Gee Gi de a On Oe WA nos ho dt on 2 2 Compilation and Installation 5 Sel ie AA 5 22 WND oe in a Gee a ee a ei e a Be AA wh ee 5 2 2 1 Compiling from source on Unix 6 2 2 2 How to make apps using YAZ on UNIX 9 23 WINS soes eo AREA aE De D as a AA aoh RGR aii 9 2 3 1 Compiling from Source on Windows 10 2 3 2 How to make apps using YAZ on Windows 11 2 3 3 Compiling Libxml2 and Libxslt on windows 12 3 ZOOM 13 3 1 Connects s e ees a ea EEE a SR OSM ESE ES 13 3 1 1 739 50Protocolbehavior 15 3 1 2 SRU Solr Protocol behavior 13 3 2 QUETES a a Re YA RER a HOS OS 17 33 Result sets fen cea eis Coe Ce eee eee e
92. Z User s Guide and Reference 133 184 EXAMPLE The simplest example of a Prefix Query would be something like f knuth or E Wakomesha Kmita In those queries no attributes was specified This leaves it up to the server what fields to search but most servers will search in all fields Some servers does not support this feature though and require that some attributes are defined To add one attribute you could do f attr 1 4 computer where we search in the title field since the use 1 is title 4 If we want to search in the author field and in the title field and in the title field using right truncation it could look something like this f Qand attr 1 1003 knuth attr 1 4 attr 5 1 computer Finally using a mix of Bib 1 and GILS attributes could look something like this f attrset Bib 1 and attr GILS 1 2008 Washington attr 1 21 weather FILES yaz lt version gt client client c SHOME yazclientre SHOME yazclient history SEE ALSO yaz 7 bibl attr 7 11 2 yaz ztest yaz ztest Z39 50 SRU Test Server Synopsis application install installa remove a file v level 1 file u uid c config f vconfig C fname t minutes k kilobytes K d daemon w dir p pidfile r kilobytes ziDSTV1 listener spec DESCRIPTION yaz ztest is a Z39 50 SRU test server that uses the YAZ generic frontend server GFS API The server acts as a real
93. _variant_1 VANDA VARSET Z3950_PREFIX 12 1 yaz_oid_schema_wais_schema WAIS schema SCHEMA 73950 PREFIX 13 1 yaz_oid_schema_gils_schema GILS schema SCHEMA 73950 PREFIX 13 2 yaz_oid_schema_collections_ Collections schema SCHEMA schema Z3950_PREFIX 13 3 yaz_oid_schema_geo_schema Geo schema SCHEMA 73950 PREFIX 134 yaz_oid_schema_cimi_schema CIMI schema SCHEMA 73950 PREFIX 13 5 yaz_oid_schema_update_es Update Es oe 73950 PREFIK 13 6 yaz_oid_schema_holdings Holdings FOMEMA Z3950_PREFIX 13 7 yaz_oid_schema_zthes Zihes SCHEMA Z3950_PREFIX 13 8 yaz_oid_schema_thesaurus_sc thesaurus schema SCHEMA hema YAZ User s Guide and Reference 167 184 Name Class Constant OID Z3950_PREFIX 13 1000 81 1 yaz_oid_schema_ explain _sche Explain schema SCHEMA ma Z3950_PREFIX 13 1000 81 2 yaz_oid_tagset_tagsetm nee ne Z3950_PREFIX 14 1 yaz_oid_tagset_tagsetg Tags TAPPET Z3950_PREFIX 14 2 yaz_oid_tagset_stas_tagset aos TA PL Z3950_PREFIX 14 3 yaz_oid_tagset_gils_tagset CESR ES pie Z3950_PREFIX 14 4 yaz_oid_tagset_collections_ Collections tagset TAGSET tagset Z3950_PREFIX 14 5 yaz_oid_tagset_cimi_tagset ES PEE Z3950_PREFIX 14 6 yaz_oid_tagset_thesaurus_ta thesaurus tagset TAGSET gset Z3950_PREFIX 14 1000 81 1 yaz_oid_tagset_explain_tags Expla
94. a call to an encoding function you can use odr_setbuf to provide the stream with an encoding buffer of sufficient size length The can_grow parameter tells the encoding ODR stream whether it is allowed to use realloc 2 to increase the size of the buffer when necessary The default condition of a new encoding stream is equivalent to the results of calling odr_setbuf stream 0 0 1 In this case the stream will allocate and reallocate memory as necessary The stream reallocates memory by repeatedly doubling the size of the buffer the result is that the buffer will typically reach 1ts maximum working size with only a small number of reallocation operations The memory is freed by the stream when the latter is destroyed unless it was assigned by the user with the can_grow parameter set to zero in this case you are expected to retain control of the memory yourself To assume full control of an encoded buffer you must first call odr_getbuf to fetch the buffer and its length Next you should call odr_setbuf to provide a different buffer or a null pointer to the stream In the simplest case you will reuse the same buffer over and over again and you will just need to call odr_getbuf after each encoding operation to get the length and address of the buffer Note that the stream may reallocate the buffer during an encoding operation so it is necessary to retrieve the correct address after each encoding operation It is im
95. a struct statserv options block describing the current default settings of the server The structure contains these elements int dynamic A boolean value which determines whether the server will fork on each incoming request TRUE or not FALSE Default is TRUE This flag is only read by UNIX based servers WIN32 based servers do not fork int threads A boolean value which determines whether the server will create a thread on each in coming request TRUE or not FALSE Default is FALSE This flag is only read by UNIX based servers that offer POSIX Threads support WIN32 based servers always operate in threaded mode int inetd A boolean value which determines whether the server will operate under a UNIX INET daemon inetd Default is FALSE char logfile ODR_MAXNAME 1 File for diagnostic output stderr char apdufile ODR_MAXNAME 1 Name of file for logging incoming and outgoing APDUs don t log APDUs stderr char default_listen 1024 Same form as the command line specification of listener address no default listener address Default is to listen at tcp 9999 You can only specify one default listener address in this fashion enum oid_proto default_proto Either PROTO_Z3950 or PROTO_SR Default is PROTO_Z3 9 5 0 int idle timeout Maximum session idle time in minutes Zero indicates no infinite timeout Default is 15 minutes int maxrecordsize Maximum permissible record message size Default is
96. abase system is the backend database and the interface between the two is called the backend API The backend API consists of a small number of function handlers and structure definitions You are required to provide the main routine for the server which can be quite simple as well as a set of handlers to match each of the prototypes The interface functions that you write can use any mechanism you like to communicate with your database system You might link the whole thing together with your database application and access it by function calls you might use IPC to talk to a database server somewhere or you might link with third party software that handles the communication for you like a commercial database client library At any rate the handlers will perform the tasks of e Initialization e Searching e Fetching records e Scanning the database index optional if you wish to implement SCAN e Extended Services optional e Result Set Delete optional e Result Set Sort optional e Return Explain for SRU optional more functions will be added in time to support as much of Z39 50 1995 as possible 4 3 The Backend API The header file that you need to use the interface are in the include yaz directory It s called backend h It will include other files from the include yaz directory so you ll probably want to use the I option of your compiler to tell it where to find the files When you run make in th
97. al SEQUENCE members which don t exist in XDR 8 3 1 The Primitive ASN 1 Types ASN 1 defines a number of primitive types many of which correspond roughly to primitive types in struc tured programming languages such as C 8 3 1 1 INTEGER The ODR function for encoding or decoding or printing the ASN 1 INTEGER type looks like this int odr_integer ODR o Odr_int lt p int optional const char xname The Odr_int is just a simple integer This form is typical of the primitive ODR functions They are named after the type of data that they encode or decode They take an ODR stream an indirect reference to the type in question and an optional flag corresponding to the OPTIONAL keyword of ASN 1 as parameters They all return an integer value of either one or zero When you use the primitive functions to construct encoders for complex types of your own you should follow this model as well This ensures that your new types can be reused as elements in yet more complex types The o parameter should obviously refer to a properly initialized ODR stream of the right type encoding de coding printing for the operation that you wish to perform When encoding or printing the function first looks at x p If x p the pointer pointed to by p is a null pointer this is taken to mean that the data element is absent If the optional parameter is nonzero the YAZ User s Guide and Reference 105 184 function will return one signif
98. ale en gt lt transform rule Control Any Remove gt lt tokenize rule w gt lt transform rule WhiteSpace Punctuation Remove gt lt transliterate rule xy gt z gt lt display gt lt casemap rule 1 gt LE CRANS SEE ALSO yaz 7 ICU Home ICU Transforms 11 12 yaz url yaz url YAZ URL fetch utility Synopsis yaz url H name value m method O fname p fname R nun u user password v x proxy url DESCRIPTION yaz url is utility to get web content It is very limited in functionality compared to programs such as curl wget The options must be precede the URL given on the command line to take effect Fetched HTTP content is written to stdout unless option O is given YAZ User s Guide and Reference 155 184 OPTIONS H name value Specifies HTTP header content with name and value This option can be given multiple times for different names of course m method Specifies the HTTP method to be used for the next URL Default is method GET However option p sets it to POST O fname Sets output filename for HTTP content p fname Sets a file to be POSTed in the folloing URL R num Sets maximum number of HTTP redirects to be followed A value of zero disables follow of HTTP redirects u user password Specifies a user and a password to be uesd in HTTP basic authentication in the fol lowing URL fetch The user and password must be separated b
99. alent to schema short hand for 239 50 it s equivalent to simple element set name For YAZ 3 0 24 and later this name may be specified as a glob expression with operators and identifier OPTIONAL Defines the URI schema name of the retrieval format This can be any string For SRU the value is equivalent to URI schema For 239 50 there is no equivalent The retrieval may include one backend element If a backend element is given it specifies how the records are retrieved by some backend and how the records are converted from the backend to the frontend The attributes name and syntax may be specified for the backend element These semantics of these attributes is equivalent to those for the ret rieval However these values are passed to the backend The backend element may includes one or more conversion instructions as children elements The supported conversions are marc The marc element specifies a conversion to and from ISO2709 encoded MARC and MAR CXML MarcXchange The following attributes may be specified input format REQUIRED Format of input Supported values are marc for ISO2709 xm1 MARCXML Marc Xchange and json MARC in_JSON output format REQUIRED Format of output Supported values are 1ine MARC line for mat marcxml for MARCXML marc ISO2709 marcxhcange for MarcXchange or json MARC in_JSON inputcharset OPTIONAL Encoding of input For XML input formats this need not be given bu
100. alifier fields are merged and assigned to one term Specifies 1f CCL operators and qualifiers should be compared with case case sensitivity or not Specify 1 for case sensitive O for case 1 insensitive and Specifies token for CCL operator AND and or Specifies token for CCL operator OR or not Specifies token for CCL operator NOT not set Specifies token for CCL operator SET set Table 7 3 CCL directives 7 1 2 3 CCL API All public definitions can be found in the header file ccl h A profile identifier is of type CCL_bibset A profile must be created with the call to the function ccl_qual_mk which returns a profile handle of type CCL_bibset To read a file containing qualifier definitions the function ccl_qual_ file may be convenient This function takes an already opened FILE handle pointer as argument along with a CCL_bibset handle To parse a simple string with a FIND query use the function sciure cel rom marce scel zime sur CC limo Siem looser comer Ghar eti OA SO imne 908 F which takes the CCL profile oibset and query str as input Upon successful completion the RPN tree is returned If an error occur such as a syntax error the integer pointed to by error holds the error code and pos holds the offset inside query string in which the parsing failed An English representation of the error may be obtained by calling the ccl_err_msg function The error codes are listed in cc1 h T
101. an ZOOM_connection cC const char xstartpqaf ZOOM _scanset ZOOM connection scanl Z00M connection c ZOOM_query q size_t ZOOM _scanset_size ZOOM_scanset scan const char ZOOM_scanset_term ZOOM_scanset scan size_t pos size t occ size_t len const char ZOOM_scanset_display_term ZOOM_scanset scan size_t pos size_t occ size_t s len void ZOOM_scanset_destroy ZOOM_scanset scan const char ZOOM_scanset_option_get ZOOM_scanset scan YAZ User s Guide and Reference 25 184 const char x key void ZOOM scanset option set Z00M_scanset scan const char key const char x val The scan set is created by function ZOOM connection scan which performs a scan operation on the connection using the specified startpgf If the operation was successful the size of the scan set can be retrieved by a call to ZOOM scanset size Like result sets the items are numbered 0 size 1 To obtain information about a particular scan term call function ZOOM_scanset_term This function takes a scan set offset pos and returns a pointer to a raw term or NULL if non present If present the occ and len are set to the number of occurrences and the length of the actual term respectively ZOOM_scanset_displ ay_term is similar to ZOOM_scanset_term except that it returns the display term rather than the raw term In a few cases the term is different from display term Always use the display term for display and the raw term for subsequent s
102. and ZOOM_resultset_sort1 both sort an existing result set The sort type parameter is not used Set it to yaz The sort_spec is same notation as ZOOM_query_sortby and identical to that offered by yaz client s sort command These functions only work for Z39 50 Use the more generic utility ZOOM_query_sortby2 for other proto cols and even Z39 50 YAZ User s Guide and Reference 19 184 Option Description Default Start Offset of first record to be retrieved from target First record has offset O unlike the protocol specifications where first record has position 1 This option affects ZOOM_resultset_search and ZOOM_resultset_search_pqf and must be set before any of these functions are invoked If a range of records must be fetched manually after search function ZOOM_resultset_records should be used count Number of records to be retrieved This option affects ZOOM_resultset_search and ZOOM resultset_search_pqf and must be set before any of these functions are invoked presentChunk The number of records to be requested from the server in each chunk present request The value 0 means to request all the records in a single chunk 0 The old step option is also supported for the benefit of old applications elementSetName Element Set name of records Most targets should honor element set name B and F for brief and full none respectively preferredRecordS yntax Preferred Syntax such as
103. and update The second argument recid is the record identifier any string Third argument which is optional is the record document for the request If doc is preceded with lt then the following characters are treated as a filename with the records to be updated Otherwise doc is treated as a document itself The doc may also be quited in double quotes If doc is omitted the last received record as part of present response or piggybacked search response is used for the update YAZ User s Guide and Reference 131 184 source filename Executes list of commands from file filename just like source on most UNIX shells A single dot can be used as an alternative args Executes command args in subshell using the system call push_command command The push_command takes another command as its argument That command is then added to the history information so you can retrieve it later The command itself is not executed This command only works if you have GNU readline history enabled set_apdufile filename Sets that APDU should be logged to file filename Another way to achieve APDU log is by using command line option a set_auto_reconnect flag Specifies whether YAZ client automatically reconnect if target closes connection Z39 50 only flag must be either on or of f set_auto_wait flag Specifies whether YAZ client should wait for response protocol packages after arequest By default YAZ client waits on for respons
104. any platforms you should be able to compile everything with little or no changes The software is regularly tested on Debian GNU Linux CentOS Ubuntu Linux FreeBSD 1386 MAC OSX Solaris Windows 7 Windows XP Some versions have be known to work on HP UX DEC Unix NetBSD OpenBSD IBM AIX Data General DG UX with some CFLAGS tinkering SGI IRIX DDE Supermax Apple Macintosh using the Code warrior programming environment and the GUSI socket libraries IBM AS 400 If you move the software to other platforms we d be grateful if you d let us know about it If you run into difficulties we will try to help if we can and if you solve the problems we would be happy to include your fixes in the next release So far we have mostly avoided ifdefs for individual platforms and we d like to keep it that way as far as it makes sense We maintain a mailing list for the purpose of announcing new releases and bug fixes as well as general discussion Subscribe by filling in the form here General questions and problems can be directed at mailto yaz help indexdata dk or the address given at the top of this document 2 2 UNIX We provide Debian GNU Linux 1386 and amd64 Ubuntu 1386 and amd64 and CentOS amd64 only packages for YAZ You should be able to create packages for other CPUs by building them from the source package YAZ is also part of several packages repositories Some of them are e Solaris CSW http www opencsw org
105. as felt to be too inefficient or at least clumsy hence the call for this extra function int cs look COMSTACK handle This function is useful when you re operating in nonblocking mode Call it when select 2 tells you there s something happening on the line It returns one of the following values CS_NONE No event is pending The data found on the line was not a complete package YAZ User s Guide and Reference 119 184 CS_CONNECT A response to your connect request has been received Call cs_rcvconnect to process the event and to finalize the connection establishment CS_DISCON The other side has closed the connection or maybe sent a disconnect request but do we care Maybe later Call cs_close to close your end of the association as well CS_LISTEN A connect request has been received Call cs_1isten to process the event CS DATA There s data to be found on the line Call cs_ get to get it Note You should be aware that even if cs look tells you that there s an event event pending the corre sponding function may still return and tell you there was nothing to be found This means that only part of a package was available for reading The same event will show up again when more data has arrived int cs _fileno COMSTACK h Returns the file descriptor of the association Use this when file level operations on the endpoint are required select 2 operations specifically 9 4 Client Side int cs
106. as part of the SearchResponse because these would be unsorted Hence piggyback is disabled when sort criteria are set Following Search and a possible sort Retrieval takes place as one or more Present Requests Response pairs being transferred The API allows for two different modes for retrieval A high level mode which is somewhat more powerful and a low level one The low level is enabled when searching on a Connection object for which the settings smallSetUpperBound mediumSetPresentNumber and largeSetLowerBound are set The low level mode thus allows you to precisely set how records are returned as part of a search response as offered by the Z39 50 protocol Since the client may be retrieving records as part of the search response this mode doesn t work well if sorting is used The high level mode allows you to fetch a range of records from the result set with a given start offset When you use this mode the client will automatically use piggyback if that is possible with the target and perform one or more present requests as needed Even if the target returns fewer records as part of a present response because of a record size limit etc the client will repeat sending present requests As an example if option start is 0 default and count is 4 and piggyback is 1 default and no sorting criteria is specified then the client will attempt to retrieve the 4 records as part the search response using piggyback On the other hand if either
107. asic Target host This setting is read only It s host automatically set internally when connecting to none a target Proxy host If set the logical host is encoded in proxy the otherInfo area of the Z39 50 Init PDU with none OID 1 2 840 10003 10 1000 81 1 Client IP If set is encoded in the otherInfo area of a Z39 50 PDU with OID clientIP 1 2 840 10003 10 1000 81 3 Holds the original none IP addreses of a client Is used if ZOOM is used in a gateway of some sort If true 1 the connection operates in async asynchronous operation which means that all 0 calls are non blocking except ZOOM_ event maximumRecordSize Maximum size of single record 1 MB preferredMessageSize Maximum size of multiple records 1 MB lang Language for negotiation none charset Character set for negotiation none Implementation ID of server The old serverImplementationId targetImplementationld option is also supported none for the benefit of old applications Implementation Name of server The old targetImplementationName targetImplementationName option is also none supported for the benefit of old applications Implementation Version of server the old serverImplementationVersion targetImplementation Version option is also none supported for the benefit of old applications One or more database names separated by databaseName character plus which is to be used by Default subsequent search requests on this Connection True 1 if piggyback s
108. aving the server run as root but you need to start it as such to bind a privileged port w dir The server changes to this directory before listening to incoming connections This option is useful when the server is operating from the inetd daemon see i p pidfile Specifies that the server should write its Process ID to the file given by pidfile A typical location would be var run yaz ztest pid i Use this to make the the server run from the inetd server UNIX only D Use this to make the server put itself in the background and run as a daemon If neither i nor D is given the server starts in the foreground install Use this to install the server as an NT service Windows NT 2000 XP only Control the server by going to the Services in the Control Panel installa Use this to install the server as an NT service and mark it as auto start Control the server by going to the Services in the Control Panel remove Use this to remove the server from the NT services Windows NT 2000 XP only t minutes Idle session timeout in minutes k size Maximum record size message size in kilobytes K Forces no keepalive for HTTP sessions By default GFS will keep sessions alive for HTTP 1 1 sessions as defined by the standard Using this option will force GFS to close the connection for each operation r size Maximum size of log file before rotation occurs in kilobytes Default size is 1048576 k 1 GB d daemon Set nam
109. can operations to get more terms next scan result etc A scan set may be freed by a call to function ZOOM_scanset_destroy Functions ZOOM_scanset_ option_get and ZOOM_scanset_option_set retrieves and sets an option respectively The startpgf is a subset of PQF namely the Attributes Term part Multiple attr can be used For example to scan in title complete phrases attr 1 4 attr 6 2 science o The Z00M_connecton_scanl is a newer and more generic alternative to ZOOM_connection_scan which allows to use both CQL and PQF for Scan Option Description Default Number of Scan Terms requested in next scan number After scan it holds the actual number of terms 20 returned Preferred Position of term in response in next scan PORMA actual position after completion of scan a stepSize Step Size 0 scanStatus An integer indicating the Scan Status of last scan 0 Character set for RPN terms If this is set ZOOM C will assume that the ZOOM application is running UTF 8 Terms in RPN queries are then converted to rpnCharset none the rpnCharset If this is unset ZOOM C will not assume any encoding of RPN terms and no conversion is performed Table 3 5 ZOOM Scan Set Options 3 7 Extended Services ZOOM offers an interface to a subset of the 239 50 extended services as well as a few privately defined ones e 739 50 Item Order ILL See Section 3 7 1 e Record Update This allows a client to inse
110. cessor part and C struct union unionmap module name member Maps member member in CHOICE of name in module module to value Value consists of to or three tokens The first token is name of the integer in the union that is used as selector for the union itself The second token is name of the union The third token overrides the name of the CHOICE member if omitted the member name is used FILES usr share yaz z39 50 z tcl usr share yaz z39 50 asn SEE ALSO yaz 7 Section The ODR Module in the YAZ manual 11 7 yaz marcdump yaz marcdump MARC record dump utility Synopsis yaz marcdump i format o format f from t tol 1 spec c cfile s pre fix C size n p v V file DESCRIPTION yaz marcdump reads MARC records from one or more files It parses each record and supports output in line format ISO2709 MARCXML MARC in JSON MarcXchange as well as Hex output This utility parses records ISO2709 raw MARC line format MARC in JSON format as well as XML if that is structured aa MARCXML MarcXchange MARC in JSON encoding decoding is supported in YAZ 5 0 5 and later YAZ User s Guide and Reference 145 184 Note As of YAZ 2 1 18 OAI MARC is no longer supported OAI MARC is deprecated Use MARCXML instead By default each record is written to standard output in a line format with newline for each field x for each subfield x The output format may be changed with option
111. cking By using a null pointer for recs you re indicating you re not inter ested in getting records objects now 3 4 2 SRU Solr Protocol behavior The ZOOM driver for SRU Solr treats records returned by a SRU Solr server as 1f they where Z39 50 records with transfer syntax XML and no element set name or database name 3 5 Facets Facet operations is not part of the official ZOOM specification but is an Index Data extension for YAZ based Z39 50 targets Solr and SRU 2 0 targets Facets may be requestd by the facets option before a search 1s sent For inspection of the returned facets the following functions are available ZOOM facet field ZOOM_resultset_facets ZOOM_resultset r ZOOM facet field ZOOM_resultset_get_facet_field ZOOM_resultset r const char facet_name ZOOM_facet_field ZOOM resultset get facet field by indez ZOOM_resultset int pos size_t ZOOM_resultset_facets_size Z00M_resultset r const char ZOOM_facet_field_name ZOOM_facet_field facet_field size_t ZOOM facet field term count ZOOM facet field facet field const char x70O0M facet field get term ZOOM facet field facet field size_t idx int xfreg References to temporary structures are returned by all functions They are only valid as long the Result set is valid ZOOM_resultset_get_facet_field or ZOOM resultset get facet field by _index ZOOM_resultset_facets ZOOM_facet_field_name ZOOM_facet_field_get _term A sin
112. commit Commit Operation Table 3 6 Extended Service Type 3 7 1 Item Order For Item Order t ype must be set to itemorder in ZOOM_package_send There are two variants of item order ILL variant and XML document variant In order to use the XML variant the setting doc must hold the XML item order document If that setting is unset the ILL variant is used YAZ User s Guide and Reference 27 184 Option Description Default Extended Service Request package name Must package name none be specified as part of a request User ID of Extended Service Package Is a user id k none request option y Function of package one of create function create delete modify Is a request option Wait action for package Possible values ne Ko waitIfPossi waitAction wait waitIfPossible dontWait or BIs dontReturnPackage Target Reference This is part of the response as targetReference returned by the server Read it after a successful none operation Table 3 7 Extended Service Common Options Option Description Default contact name ILL contact name none contact phone ILL contact phone none contact email ILL contact email none itemorder setname Name of result set for record default itemorder item Position for item record requested An integer 1 Table 3 8 Item Order Options Option protocol version num transaction id initial requester id
113. connect COMSTACK handle void xaddress Initiate a connection with the target at address more on addresses below The function will return 0 on success and 1 if the operation does not complete immediately this will only happen on a nonblocking endpoint In this case use cs_rcvconnect to complete the operation when select 2 orpoll 2 reports input pending on the association int cs _revconnect COMSTACK handle Complete a connect operation initiated by cs_connect It will return O on success 1 1f the operation has not yet completed in this case call the function again later 1 if an error has occurred 9 5 Server Side To establish a server under the inetd server you can use COMSTACK cs_createbysocket int int socket CS_TYPE type int blocking protocol The socket parameter is an established socket when your application is invoked from inetd the socket will typically be 0 The following parameters are identical to the ones for cs_create int cs bind COMSTACK handle void x address int mode Binds a local address to the endpoint Read about addresses below The mode parameter should be either CS_CLIENT or CS SERVER int cs _listen COMSTACK handle char x addr int x addrlen Call this to process incoming events on an endpoint that has been bound in listening mode It will return 0 to indicate that the connect request has been received 1 to signal a partial reception and 1 to indicate an err
114. cord plus 1 If number is not given then one record will be fetched at a time scan term Scans database index for a term The syntax resembles the syntax for find If you want to scan for the word water you could write scan water but if you want to scan only in say the title field you would write scan attr 1 4 water setscan set term Scans database index for a term within a result set This is similar to the scan command but has a result set as its first argument scanpos pos Sets preferred position for scan This value is used in next scan By default position is 1 scansize size Sets number of entries to be returned by scan Default number of entries is 20 scanstep step Set step size for scan This value is used in next scan sent to the target By default step size is 0 sort sortspecs Sorts a result set The sort command takes a sequence of space separated sort spec ifications with each sort specification consisting of two space separated words so that the whole specification list is made up of an even number of words The first word of each specification holds a field sort criterion and the second holds flags If the sort criterion includes it is assumed that the SortKey is of type sortAttributes using Bib 1 in this case the integer before is the attribute type and the integer following is the attribute value If no character is in the criterion it is treated as a sortfield of type InternationalString The flags word
115. ct void xpr const char xbuf void client_d void client_data Z_RPNQuery xq int cgl_transform_rpn2cql_wrbuf cgl_transform_t ct WRBUF w Z_RPNQuery kg The configuration is the same as used in CQL to PQF conversions 7 2 Object Identifiers The basic YAZ representation of an OID is an array of integers terminated with the value 1 This integer is of type Odr_oid Fundamental OID operations and the type Odr_oid are defined in yaz oid_util h An OID can either be declared as a automatic variable or it can allocated using the memory utilities or ODR NMEM It s guaranteed that an OID can fit in OID_SIZE integers Example 7 13 Create OID on stack We can create an OID for the Bib 1 attribute set with LA Oelic wee Sani Sa bib1 0 1 bib1 1 2 bib1 2 840 bib1 3 10003 bib1 4 3 bib1 5 1 bib1 6 1 And OID may also be filled from a string based representation using dots This is achieved by function rat alale neli aa Char case Ock O16 wai This functions returns 0 if name could be converted 1 otherwise Example 7 14 Using oid_oiddotstring_to_oid We can fill the Bib 1 attribute set OID easier with Coke wai ono Ou Da SEZ ry Gulcl_ aleleloesc icing to oral M1 24840 gt LOOOS 31 DOL 5 We can also allocate an OID dynamically on a ODR stream with Oka Galo sole csroncioysicr ODR O CONSE Char sSTr This creates
116. d 739 50 APDUs HTTP_Request and HTTP Response is the HTTP Request and Response respec tively 6 3 SOAP Packages Every SOAP package in YAZ is represented as follows include lt yaz soap h gt typedef struct char fault_code char fault_string char xdetails Z SOAP Fault typedef struct int no char ns void xp Z SOAP Generic define Z SOAP fault 1 define Z SOAP generic 2 define Z SOAP error 3 typedef struct int which union Z_SOAP_Fault x fault Z_SOAP_Generic x generic Z_SOAP_Fault SOap_error u const char ns Z_SOAP The fault and soap error arms represent both a SOAP fault struct Z_SOAP_Fault Any other generic valid package is represented by Z SOAP Generic The ns as part of Z_SOAP is the namespace for SOAP itself and reflects the SOAP version For version 1 1 itis http schemas xmlsoap org soap envelope for version 1 2 itis http www w3 0org 2001 06 soap envelope int z_soap_codec ODR o Z_SOAP xxpp char xxcontent _buf int content_len Z_SOAP_Handler x handlers The content_buf and content_len is XML buffer and length of buffer respectively YAZ User s Guide and Reference 61 184 The handlers is a list of SOAP codec handlers one handler for each service namespace For SRU SOAP the namespace would be http www loc gov zing srw v1 0 When decoding the z_soap_codec inspects the XML content and tries to match one of the
117. d Libxsit on windows Download libxml2 and Libxslt source and unpack it In the example below we install Libxml2 2 9 2 and Libxslt 1 1 28 for 32 bit so we use the destination directories libxml2 2 9 2 win32 and libxslt 1 1 28 win32 to reflect both version and architecture cd win32 CHSCMIE Comics Ja Prerix e oral e 2 pias skeen no nmake nmake install Note There s an error in configure js for Libxml2 2 9 2 Line 17 should be assigned to configure ac rather than configure in For Libxslt it is similar We must ensure that compilation of Libxslt links against the already installed libxml2 cd win32 escupir OMEN uitera Sm Oke is CM RS EI ST o ZE O NO Lies iq 22 02 vba sy baile N include c libxml2 2 9 2 win32 include libxml2 nmake nmake install YAZ User s Guide and Reference 13 184 Chapter 3 ZOOM ZOOM is an acronym for Z39 50 Object Orientation Model and is an initiative started by Mike Taylor Mike is from the UK which explains the peculiar name of the model The goal of ZOOM is to provide a common Z39 50 client API not bound to a particular programming language or toolkit From YAZ version 2 1 12 SRU is supported You can make SRU ZOOM connections by specifying scheme http for the hostname for a connection The dialect of SRU used is specified by the value of the connection s sru option which may be SRU over HTTP GET get SRU over HTTP POST post SRU over SOAP soap or so
118. d or decodes between OCTETSTRING representations and null terminates C strings Functions are provided for the derived string types eg int odr_visiblestring ODR o char xxp int optional const char xname 8 3 1 6 BIT STRING int odr_bitstring ODR o Odr_bitmask p int optional const char xname The opaque type Odr_bitmask is only suitable for holding relatively brief bit strings eg for options fields etc The constant ODR_BITMASK_SIZE multiplied by 8 gives the maximum possible number of bits A set of macros are provided for manipulating the Odr_bitmask type void ODR_MASK_ZERO Odr_bitmask xb void ODR_MASK_SET Odr_bitmask xb int bitno void ODR_MASK_CLEAR Odr_bitmask x b int bitno int ODR_MASK_GET Odr_bitmask xb int bitno The functions are modeled after the manipulation functions that accompany the fd_set type used by the select 2 call ODR_MASK_ZERO should always be called first on a new bitmask to initialize the bits to zero 8 3 1 7 OBJECT IDENTIFIER int odr_oid ODR o Odr_oid p int optional const char name The C OID representation is simply an array of integers terminated by the value 1 the Odr_oid type is synonymous with the short type We suggest that you use the OID database module see Section 7 2 1 to handle object identifiers in your application YAZ User s Guide and Reference 107 184 8 3 2 Tagging Primitive Types The simplest way of tag
119. d some popularity especially before the widespread availability of graphical interfaces It is still useful in applications where you for some reason or other need to provide a symbolic language for expressing boolean query structures 7 1 2 1 CCL Syntax The CCL parser obeys the following grammar for the FIND argument The syntax is annotated by in the lines prefixed by CCL Find CCL Find Op Elements Elements Op lt Wein Wee Maga The above means that Elements are separated by boolean operators Elements sea CCF amel 4 Set Terms Qualifiers Relation Terms YAZ User s Guide and Reference 71 184 Ouedlalriers Relacion a MCCAIN M Qualities Simon YS Sta Elements is either a recursive definition a result set reference a list of terms qualifiers followed by terms qualifiers followed loy E reCireilye csm LI Ce cwaliriers alin rence lover upper Sete AS string Reference to a result set Terms Terms Prox Term Ea Proimuites OL ESAS eran 2323 S SETIN IS reine This basically means that a term may include a blank QUISAS O US 4 STNE strie Qualifiers is a list of strings separated by comma Relat tom ees CS AS ESO MAA A ZO Relational operators This really doesn t follow the 1508777 Simela PROS SEINE ALE Proximity operator Example 7 8 CCL queries The fol
120. dard functions provided with ODR It will encode decode or pretty print a data value of the MySequence type We like to name types with an initial capital as done in ASN 1 definitions and to name the corresponding function with the first character of the name in lower case You could of course name your structures types and functions any way you please as long as you re consistent and your code is easily readable odr_ok is just that a predicate that returns the state of the stream It is used to ensure that the behavior of the new type is compatible with the interface of the primitive types 8 3 4 Tagging Constructed Types Note See Section 8 3 2 for information on how to tag the primitive types as well as types that are already defined 8 3 4 1 Implicit Tagging Assume the type above had been defined as MySequence 10 IMPLICIT SEQUENCE intval INTEGER YAZ User s Guide and Reference 109 184 boolval BOOLEAN OPTIONAL You would implement this in ODR by calling the function int odr_implicit_settag ODR o int class int tag which overrides the tag of the type immediately following it The macro odr_implicit_tag works by calling odr_implicit_settag immediately before calling the function pointer argument Your type function could look like this int mySequence ODR o MySequence xxp int optional const char xname CAM pcs Saro O MOD RES O NTE O NON odr_sequence_beg
121. e of daemon to be used in hosts access file See hosts_access 5 and tcpd 8 YAZ User s Guide and Reference 45 184 m time format Sets the format of time stamps in the log file Specify a string in the input format to strftime V Display YAZ version and exit A listener specification consists of a transport mode followed by a colon followed by a listener address The transport mode is either tcp unix or ssl For TCP and SSL an address has the form hostname IP number portnumber The port number defaults to 210 standard Z39 50 port For UNIX the address is the filename of socket For TCP IP and SSL the special hostnames maps to INGADDR ANY INIT with IPV4 binding as well bindv6only 0 The special hostname 4 binds to INADDR ANY IPV4 only listener The special hostname 6 binds to INGADDR ANY INIT with bindv6only 1 IPV6 only listener Example 4 1 Running the GFS on Unix Assuming the server application appname is started as root the following will make it listen on port 210 The server will change identity to nobody and write its log to var log app log application 1 var log app log u nobody tcp 210 The server will accept Z39 50 requests and offer SRU service on port 210 Example 4 2 Setting up Apache as SRU Frontend If you use Apache as your public web server and want to offer HTTP port 80 access to the YAZ server on 210 you
122. e one of the higher level interfaces you can skip this section entirely This is important so we ll repeat it for emphasis You do not need to read Section 8 3 to implement Z39 50 with YAZ If you need a part of the protocol that isn t already in YAZ you should contact the authors before going to work on it yourself We might already be working on it Conversely if you implement a useful part of the protocol before us we d be happy to include it in a future release 8 2 Using ODR 8 2 1 ODR Streams Conceptually the ODR stream is the source of encoded data in the decoding mode when encoding it is the receptacle for the encoded data Before you can use an ODR stream it must be allocated This is done with the function ODR odr_createmem int direction The odr_createmem function takes as argument one of three manifest constants ODR_ENCODE ODR_DECODE or ODR_PRINT An ODR stream can be in only one mode it is not possible to change its mode once it s selected Typically your program will allocate at least two ODR streams one for decoding and one for encoding When you re done with the stream you can use void odr_destroy ODR o to release the resources allocated for the stream 8 2 2 Memory Management Two forms of memory management take place in the ODR system The first one which has to do with allocating little bits of memory sometimes quite large bits of memory actuall
123. e packages immediately after a command find show has been issued If of f is used YAZ client does not attempt to receive packages automatically These will have to be manually received when command wait_response is used flag must be either on or of f set_marcdump filename Specifies that all retrieved records should be appended to file filename This command does the thing as option m schema schemaid Specifies schema for retrieval Schema may be specified as an OID for Z39 50 For SRU schema is a simple string URI charset negotiationcharset displaycharset marccharset Specifies character set en coding for 239 50 negotiation SRU encoding and or character set for output terminal negotiationcharset is the name of the character set to be negotiated by the server The special name for negotiationcharset specifies no character set to be negotiated If displaycharset is given it specifies name of the character set of the output on the terminal on which YAZ client is running To disable conversion of characters to the output encoding the special name dash can be used If the special name auto is given YAZ client will convert strings to the encoding of the terminal as returned by nl_langinfo call If marcharset is given it specifies name of the character set of retrieved MARC records from server See also marcharset command Note Since character set negotiation takes effect in the Z39 50 Initialize Request y
124. e top level YAZ directory everything you need to create your server is to link with the Lib libyaz 1a library 4 4 Your main Routine As mentioned your main routine can be quite brief If you want to initialize global parameters or read global configuration tables this is the place to do it At the end of the routine you should call the function int statserv_main int argc char x argv bend_initresult x xbend_init bend_initrequest xr void bend_close void x handle YAZ User s Guide and Reference 35 184 The third and fourth arguments are pointers to handlers Handler bend_init is called whenever the server receives an Initialize Request so it serves as a 239 50 session initializer The bend close handler 1s called when the session is closed statserv_main will establish listening sockets according to the parameters given When connection requests are received the event handler will typically fork and create a sub process to handle a new connection Alternatively the server may be setup to create threads for each connection If you do use global variables and forking you should be aware then that these cannot be shared between associations unless you explicitly disable forking by command line parameters The server provides a mechanism for controlling some of its behavior without using command line options The function statserv_options_block x statserv_getcontrol void will return a pointer to
125. ed directly To avoid a conflict the names ge eq le must be used for CQL operators greater than or equal equal less than or equal respectively The RPN pattern is supposed to include a relation attribute For terms not bound by a relation the pattern relation scr is used If the pattern is not defined the mapping will fail The special pattern relation is used when no other relation pattern is matched relationModifier mod This pattern specifies how a CQL relation modifier is mapped to RPN The RPN pattern is usually a relation attribute structure type This pattern specifies how a CQL structure is mapped to RPN Note that this CQL pattern is somewhat to similar to CQL pattern relation The type is a CQL relation The pattern structure x is used when no other structure pattern is matched Usually the RPN equivalent specifies a structure attribute YAZ User s Guide and Reference 81 184 position type This pattern specifies how the anchor position of CQL is mapped to RPN The type is one of first any last firstAndLast The pattern position is used when no other position pattern is matched set prefix This specification defines a CQL context set for a given prefix The value on the right hand side is the URI for the set not RPN All prefixes used in index patterns must be defined this way set This specification defines a default CQL context set for index names The value on the right hand side is the URI
126. ed in PQF notation by using the function ZOOM_query_prefix The ZOOM_query_cql specifies a CQL query to be sent to the server target More query types will be added in future versions of YAZ such as CCL to RPN mapping native CCL query etc In addition to a search a sort criteria may be set Function ZOOM_query_sortby enables Z39 50 sorting and it takes sort criteria using the same string notation as yaz client s sort command ZOOM_query_sortby2 is similar to ZOOM_query_sortby but allows a strategy for sorting The reason for the strategy parameter is that some protocols offer multiple ways of performing sorting For example Z39 50 has the standard sort which is performed after search on an existing result set It s also possible to use CQL in Z39 50 as the query type and use CQL s SORTBY keyword Finally Index Data s Zebra server also allows sorting to be specified as part of RPN Type 7 Name Description 239 50 Z39 50 resultset sort type7 Sorting embedded in RPN Type 7 cql CQL SORTBY srul1 SRU sortKeys parameter solr Solr sort embed type7 for Z39 50 cql for SRU solr for Solr protocol Table 3 2 ZOOM sort strategy 3 3 Result sets The result set object is a container for records returned from a target ZOOM_resultset ZOOM_connection_search ZOOM_connection ZOOM_query q ZOOM_resultset ZOOM_connection_search_pqf ZOOM connection c const char xq void ZOOM_resultset_destroy ZOOM_res
127. ee SHS a oy aa oS 18 3 3 1 Z39 50 Result set Sort 18 3 3 2 739 50Protocolbehavior 20 3 3 3 SRU Protocol behavior 20 3A Records ees ir AAA AA A TN RS NI TRS 21 3 4 1 739 50Protocolbehavior 23 3 4 2 SRU SolrProtocolbehavior 23 33 Facets O A A IA lt OLE ER LR AA 23 O SCO 2 24h eee Pee oe Pee ee OEE Se OAH OHO is AA 3 7 Extended Services Sal W on xs eh UA Na SH BS SEY AAA AAA AA 3 1 2 Record Update o ss woe oe L ake oo oe oe EE R ERE ESS 3 3 Database Creaie 24 26525442224 CREE eR ESAEER EES EES Eee 3 74 Database Drop 3 7 5 Commit Operation 3 7 6 Protocolbehavior 3 8 CODHONS qa AA aa WAWA WAA 3 9 Q ery conyersions IIIA AAA AUA SE YA des HES INES AA a ara AAA e os e IN a AA aa Generic server 4 1 4 2 4 3 44 4 5 4 6 4 7 Introduction 4 4 visu ire Pa LEA L ek EE DEEPER ee PEER RS The Database Frontend The B ackend API 55 44 amp ehh haha RSG RS RDA E dE RES Your main Routine The B 4 5 1 4 5 2 4 5 3 4 5 4 ackendFunctions UA AAA WAA KAA eee IA eS Search and Retrieve
128. ee the 739 50 standard on set bounds for more details status Displays the values of 1s1b ssub and mspn setname Switches named result sets on and off Default is on cancel Sends a Trigger Resource Control Request to the target format oid Sets the preferred transfer syntax for retrieved records yaz client supports all the record syntaxes that currently are registered See 239 50 Record Syntax Identifiers for more details Com monly used records syntaxes include usmarc sutrs and xml elements e Sets the element set name for the records Many targets support element sets are B for brief and F for full close Sends a Z39 50 Close APDU and closes connection with the peer querytype type Sets the query type as used by command find The following is supported prefix for Prefix Query Notation Type 1 Query cc1 for CCL search Type 2 Query cal for CQL Type 104 search with CQL OID cc12rpn for CCL to RPN conversion Type 1 Query cq12rpn for CQL to RPN conversion Type 1 Query attributeset set Sets attribute set OID for prefix queries RPN Type 1 refid id Sets reference ID for 239 50 Request s itemorder type no Sends an Item Order Request using the ILL External type is either 1 or 2 which corresponds to ILL Profile 1 and 2 respectively The no is the Result Set position of the record to be ordered update action recid doc Sends Item Update Request The action argument must be the action type one of insert replace delete
129. efault behavior This tweak was added in YAZ version 5 1 2 Allows term to be left truncated If term is of the form x the resulting Type 1 ges term is x and truncation is left he Allows term to be right truncated If term is of the form x 7 the resulting Type 1 term is x and truncation is right t n If term is does not include the truncation attribute is set to none 100 rer Allows term to be both left amp right truncated If term is of the form x the 7 resulting term is x and trunctation is set to both left amp right Allows masking anywhere in a term thus fully supporting mask one E x character and zero or more of any If masking is used trunction is set to 102 regexp 1 in term and the term is converted accordingly to a regular expression Allows masking anywhere in a term thus fully supporting mask one poz character and zero or more of any If masking is used trunction is set to 104 Z39 58 in term and the term is converted accordingly to 239 58 masking term actually the same truncation as CCL itself Table 7 2 Special attribute combos YAZ User s Guide and Reference 75 184 Name Description Default truncation Truncation character mask Masking character Requires YAZ 4 2 58 or later Specifies how multiple fields are to be combined There are two field modes or multiple qualifier fields are ORed merge attributes for merge the qu
130. eferredRecordS yntax Odr_oid NULL query Z_Query NULL additionalSearchInfo Z_OtherInformation NULL otherInfo Z_OtherInformation NULL Table 5 3 Default settings for PDU Search Request Field Type Default Value referenceld Z_Referenceld NULL resultCount Odr_int 0 numberOfRecordsReturned Odr_int 0 nextResultSetPosition Odr_int 0 searchStatus Odr_bool TRUE resultSetStatus Odr_int NULL presentStatus Odr_int NULL records Z_Records NULL additionalSearchInfo Z_OtherInformation NULL otherInfo Z_OtherInformation NULL Table 5 4 Default settings for PDU Search Response YAZ User s Guide and Reference 55 184 Field Type Default Value referenceld Z_Referenceld NULL resultSetld char default resultSetStartPoint Odr_int 1 numberOfRecordsRequested Odr_int 10 num_ranges Odr_int 0 additionalRanges Z_Range NULL recordComposition Z_RecordComposition NULL preferredRecordS yntax Odr_oid NULL maxSegmentCount Odr_int NULL maxRecordSize Odr_int NULL maxSegmentSize Odr_int NULL otherInfo Z_OtherInformation NULL Table 5 5 Default settings for PDU Present Request Field Type Default Value referenceld Z_Referenceld NULL numberOfRecordsReturned Odr_int 0 nextResultSetPosition Odr_int 0 presentStatus Odr_int Z_PresentStatus_success records Z_Records NULL otherInfo Z_OtherInformation NULL Table 5 6 Default settings for PDU Present Response Field Type
131. egment Di 5 17 Default settings for Close 58 7 1 CommonBib lattributes 13 7 2 Special attribute combos 74 o WA 25 estr eee e he SESS HSS OES EOS OSS EE ESS aS 13 74 Facet attributes 95 8 1 ODR Error codes 103 Abstract This document is the programmer s guide and reference to the YAZ package version 5 14 10 YAZ is a compact toolkit that provides access to the Z39 50 and SRU Solr protocols as well as a set of higher level tools for implementing the server and client roles respectively The documentation can be used on its own or as a reference when looking at the example applications provided with the package YAZ User s Guide and Reference 1 184 Chapter 1 Introduction YAZ is a C C library for information retrieval applications using the Z39 50 SRU Solr protocols for information retrieval Properties of YAZ Complete 739 50 version 3 support Amendments and Z39 50 2002 revision is supported Supports SRU GET POST SOAP version 1 1 1 2 and 2 0 over HTTP and HTTPS Includes BER encoders decoders for the ISO ILL protocol Supports Apache Solr Web Service version 1 4 x client side only Supports the following transports BER over TCP IP RFC1729 BER over unix local socket and HTTP Lil Sec
132. emove directories created by make install e g usr local include yaz YAZ User s Guide and Reference 9 184 2 2 2 How to make apps using YAZ on UNIX This section describes how to compile and link your own applications using the YAZ toolkit If you re used to Makefiles this shouldn t be hard As for other libraries you have used before you need to set a proper include path for your C C compiler and specify the location of YAZ libraries You can do it by hand but generally we suggest you use the yaz config that is generated by configure This is especially important if you re using the threaded version of YAZ which require you to pass more options to your linker compiler The yaz config script accepts command line options that makes the yaz config script print options that you should use in your make process The most important ones are cflags 1ibs which prints C compiler flags and linker flags respectively A small and complete Makefile for a C application consisting of one source file myprog c may look like this YAZCONFIG usr local bin yaz config CFLAGS YAZCONFIG cflags LIBS S YAZCONFIG libs myprog myprog o CC CFLAGS o myprog myprog o LIBS The CFLAGS variable consists of a C compiler directive that will set the include path to the parent directory of yaz That is if YAZ header files were installed in usr local include yaz then include path is set to usr local
133. enceld Z_Referenceld NULL requestedAction Odr_int Z_TriggerResourceCtrl_resou prefResourceReportFormat Odr_oid NULL resultSetWanted Odr_bool NULL otherInfo Z_OtherInformation NULL Table 5 11 Default settings for Trigger Resource Control Request YAZ User s Guide and Reference 57 184 Field Type Default Value referenceld Z_Referenceld NULL suspendedFlag Odr_bool NULL resourceReport Z_External NULL partialResultsAvailable Odr_int NULL responseRequired Odr_bool FALSE triggeredRequestFlag Odr_bool NULL otherInfo Z_OtherInformation NULL Table 5 12 Default settings for Resource Control Request Field Type Default Value referenceld Z_Referenceld NULL continueFlag bool _t TRUE resultSetWanted bool _t NULL otherInfo Z_OtherInformation NULL Table 5 13 Default settings for Resource Control Response Field Type Default Value referenceld Z_Referenceld NULL which enum Z_AccessRequest_simpleForm u union NULL otherInfo Z_OtherInformation NULL Table 5 14 Default settings for Access Control Request Field Type Default Value referenceld Z_Referenceld NULL which enum Z_AccessResponse_simpleForm u union NULL diagnostic Z_DiagRec NULL otherInfo Z_OtherInformation NULL Table 5 15 Default settings for Access Control Response Field Type Default Value referenceld Z_Referenceld NULL numberOfRecordsReturned Odr_int value
134. er generates a tree representing the structure of the CQL query struct cql_node cql_parser_result CQL_parser cp cql_parser_result returns the a pointer to the root node of the resulting tree Each node in a CQL tree is represented bya struct cql_node It is defined as follows define CQL_NODE_ST 1 define CQL_NODE_BOOL 2 define COL NODE SORT 3 struct cql_ node int which union struct char x xindex char index_uri char xterm char relation char relation_uri struct cql_node modifiers st struct char xvalue struct cql_node xleft struct cgl node x right struct cql_node xmodifiers boolean struct char x index struct cql_ node next struct cql_node xmodifiers struct cql_node x search There are three node types search term ST boolean BOOL and sortby SORT A modifier is treated as a search term too The search term node has five members e index index for search term If an index is unspecified for a search term index will be NULL e index_uri index URI for search term or NULL if none could be resolved for the index e term the search term itself e relation relation for search term e relation uri relation URI for search term modifiers relation modifiers for search term The modifiers list itself of cql_nodes each of type ST The boolean node represents and or not proximity e left a
135. er is taken from the well known list of alternatives de scribed in below or private or p the unit code paramater has semantics specific to an out of band agreement such as a profile unit code If the which code parameter is known then the recognised values are character 2 word 3 sentence 4 paragraph 5 section 6 chapter 7 document 8 element 9 subelement 10 ele mentType and 11 byte If which code is private then the acceptable values are determined by the profile YAZ User s Guide and Reference 69 184 The numeric values of the relation and well known unit code parameters are taken straight from the ASN 1 of the proximity structure in the standard 7 1 1 2 PQF queries Example 7 1 PQF queries using simple terms dylan Mala ely leia Example 7 2 PQF boolean operators or dylan zimmerman and or dylan zimmerman when and when or dylan zimmerman Example 7 3 PQF references to result sets set Result 1 Qand set seta set seth Example 7 4 Attributes for terms attr 1 4 computer attr 1 4 attr 4 1 self portrait attrset expl attr 1 1 CategoryList attr gils 1 2008 Copenhagen attr 1 book title computer Example 7 5 PQF Proximity queries prox 0 3 1 2 k 2 dylan zimmerman Here the parameters 0 3 1 2 k and 2 represent exclusion distance ordered relation which code and unit code in that order So e exclusion
136. es appearing within the PDUs For the primitive data types the C representation often takes the form of an ordinary C language type such as Odr_int which is equivalent to an integral C integer For ASN 1 constructs that have no direct representation in C such as general octet strings and bit strings the ODR module see section The ODR Module provides auxiliary definitions The Z39 50 ASN 1 module is located in sub directory 39 50 There you ll find C files that implements encoders and decoders for the 239 50 types You ll also find the protocol definitions z23950v3 asn esupdate asn and others 5 2 Preparing PDUs A structure representing a complex ASN 1 type doesn t in itself contain the members of that type Instead the structure contains pointers to the members of the type This is necessary in part to allow a mechanism for specifying which of the optional structure SEQUENCE members are present and which are not It follows that you will need to somehow provide space for the individual members of the structure and set the pointers to refer to the members The conversion routines don t care how you allocate and maintain your C structures they just follow the pointers that you provide Depending on the complexity of your application and your personal taste there are at least three different approaches that you may take when you allocate the structures You can use static or automatic local variables in the function that prepa
137. fication is as follows facet spec facet list facet list facet list attr spec attr spec attr spec attr spec Gattr string attr string The notation is inspired by PQF The string following attr may not include blanks and is of the form type value where type is an integer and value is a string or an integer The Facets specification is not Bib 1 The following types apply YAZ User s Guide and Reference 95 184 Type Description 1 Field name This is often a string eg Author Year etc 2 Sort order Value should be an integer Value 0 count descending frequency Value 1 alpha ascending 3 Number of terms requested 4 Start offset Table 7 4 Facet attributes YAZ User s Guide and Reference 97 184 Chapter 8 The ODR Module 8 1 Introduction ODR is the BER encoding decoding subsystem of YAZ Care as been taken to isolate ODR from the rest of the package specifically from the transport interface ODR may be used in any context where basic ASN 1 BER representations are used If you are only interested in writing a Z39 50 implementation based on the PDUs that are already provided with YAZ you only need to concern yourself with the section on managing ODR streams Section 8 2 Only if you need to implement ASN 1 beyond that which has been provided should you worry about the second half of the documentation Section 8 3 If you us
138. fig A Bourne shell script generated by configure that specifies how external applica tions should compile and link with YAZ util yaz asncomp The ASN 1 compiler for YAZ Requires the Tcl Shell tclsh in PATH to operate util yaz iconv This program converts data in one character set to another This command exercises the YAZ character set conversion API util yaz marcdump This program parses 1802709 encoded MARC records and prints them in line format or XML util yaz icu This program exposes the ICU wrapper library 1f that is enabled for YAZ Only if ICU 1s available this program is useful util yaz url This program is a simple HTTP page fetcher ala wget or curl zoom zoomsh A simple shell implemented on top of the ZOOM functions The shell is a command line application that allows you to enter simple commands to perform ZOOM operations zoom zoomt st 1 zoom zoomtst2 Several small applications that demonstrates the ZOOM API If you wish to install YAZ in system directories usr local bin usr local 1ib etc you can type make install You probably need to have root access in order to perform this You must specify the prefix option for configure if you wish to install YAZ in other directories than the default usr local If you wish to perform an un installation of YAZ use make uninstall This will only work if you haven t reconfigured YAZ and therefore changed installation prefix Note that uninstall will not r
139. g A user option that serves as a specifier for some sort of configuration usually a filename The argument to this option is transferred to member configname of the statserv_options_bl ock f vconfig This specifies an XML file that describes one or more YAZ frontend virtual servers C fname Sets SSL certificate file name for server PEM v level The log level Use a comma separated list of members of the set fatal debug warn log malloc all none u uid Set user ID Sets the real UID of the server process to that of the given user It s useful if you aren t comfortable with having the server run as root but you need to start it as such to bind a privileged port YAZ User s Guide and Reference 135 184 w dir The server changes to this directory before listening to incoming connections This option is useful when the server is operating from the inetd daemon see i p pidfile Specifies that the server should write its Process ID to the file given by pidfile A typical location would be var run yaz ztest pid i Use this to make the the server run from the inetd server UNIX only D Use this to make the server put itself in the background and run as a daemon If neither i nor D is given the server starts in the foreground install Use this to install the server as an NT service Windows NT 2000 XP only Control the server by going to the Services in the Control Panel installa Use this to install the server
140. g commands as soon as an error occur The exit code of zoomsh is 1 if error occurs O otherwise yV loglevel Sets YAZ log level to loglevel EXAMPLES If you start the yaz ztest in one console you can use the ZOOM shell as follows zoomsh ZOOM gt connect localhost 9999 ZOOM gt search computer localhost 9999 7 Hits ZOOM gt show 0 1 1 Default USmarc 001 11224466 003 DLC 005 00000000000000 0 00S 91071061991070 Tmt 00010 eng 010 Sa 11224466 040 a DLC c DLC 050 00 a 12377 100 10 a Vack Collins 245 10 a How to program a computer 260 L a Penguin 263 a 8710 300 Sa D Cine ZOOM gt quit You can also achieve the same result by passing the commands as arguments on a single command line zoomsh connect localhost 9999 search computer show 0 1 quit COMMANDS connect zurl Connects to the target given by zuri close zur1 Closes connection to target given by zur1 or all targets if zuri was omitted show start count Displays count records starting at offset given by start First records has offset O unlike the 239 50 protocol quit Quits zoomsh set name value Sets option name to value get name Prints value of option name help Prints list of available commands SEE ALSO yaz 7 yaz ztest 8 Section Building clients with ZOOM in the YAZ manual ZOOM home page 11 6 yaz asncomp yaz asncomp YAZ ASN 1 compiler Synopsis yaz asncomp v c cfile h hfi
141. ging BER encoded PDUs over that connection When you create a connection endpoint you need to specify what transport to use TCP IP SSL or UNIX sockets For the remainder of the connection s lifetime you don t have to worry about the underlying transport protocol at all the COMSTACK will ensure that the correct mechanism is used We call the combined interfaces to ODR Z39 50 ASN 1 and COMSTACK the service level API It s the API that most closely models the Z39 50 service protocol definition and it provides unlimited access to all fields and facilities of the protocol definitions The reason that the YAZ service level API is a conglomerate of the APIs from three different submodules is twofold First we wanted to allow the user a choice of different options for each major task For instance if you don t like the protocol API provided by ODR Z39 50 ASN 1 you can use SNACC or BERUtils instead and still have the benefits of the transparent transport approach of the COMSTACK module Secondly we realize that you may have to fit the toolkit into an existing event processing structure in a way that is incompatible with the COMSTACK interface or some other part of YAZ YAZ User s Guide and Reference 5 184 Chapter 2 Compilation and Installation 2 1 Introduction The latest version of the software will generally be found at http ftp indexdata com pub yaz We have tried our best to keep the software portable and on m
142. ging a type is to use the odr_implicit_tag or odr_explicit_tag macros int odr_implicit_tag ODR o Odr_fun fun int class int tag int optional const char xname int odr_explicit_tag ODR o Odr_fun fun int class int tag int optional const char xname To create a type derived from the integer type by implicit tagging you might write MyInt 210 IMPLICIT INTEGER In the ODR system this would be written like Imr Myint ODR O Oce int spp Le ela Const Chai znane return odr_implicit_tag o odr_integer p ODR_CONTEXT 210 optional name The function my Int can then be used like any of the primitive functions provided by ODR Note that the behavior of odr_explicit_tag and odr_implicit_tag macros act exactly the same as the functions they are applied to they respond to error conditions etc in the same manner they simply have three extra parameters The class parameter may take one of the values ODR_CONTEXT ODR_PRIVATE ODR_UNIVERSAL or ODR_APPLICATION 8 3 3 Constructed Types Constructed types are created by combining primitive types The ODR system only implements the SE QUENCE and SEQUENCE OF constructions although adding the rest of the container types should be simple enough if the need arises For implementing SEQUENCES the functions int odr_sequence_begin ODR o void xp int size const char xname int odr_sequence_end ODR o are
143. gle Facet field is returned by function ZOOM_resultset_get_facet_fieldor ZOOM_resul tset_get_facet_field_by_index that takes a result set and facet name or positive index respec tively First facet has position zero If no facet could be obtained invalid name or index out of bounds NULL is returned An array of facets field can be returned by ZOOM_resultset_facets The length of the array is given by ZOOM_resultset_facets_size The array is zero based and the last entry will be at ZOOM_re sultset_facets_size result_set l It is possible to interate over facets by name by calling ZOOM_resultset_facets_names This will return a const array of char where each string can be used as parameter for ZOOM_resultset_get_f acet_field Function ZOOM facet field name gets the request facet name from a returned facet field Function ZOOM facet field get term returns the idx th term and term count for a facet field Idx must between 0 and ZOOM_facet_field_term_count l otherwise the returned reference will be NULL On a valid idx the value of the freq reference will be the term count The freq parameter must be valid pointer to integer 3 6 Scan This section describes an interface for Scan Scan is not an official part of the ZOOM model yet The result of a scan operation is the ZOOM_scanset which is a set of terms returned by a target The Scan interface is supported for both Z39 50 SRU and Solr ZOOM _scanset ZOOM _connection_sc
144. he CQL to PQF tool described here To maintain backwards compatibility the frontend server of yaz always assume that error codes are BIB 1 diagnostics For SRU operation a Bib 1 diagnostic code is mapped to SRU diagnostic int bend_fetch void xhandle bend_fetch_rr rr typedef struct bend_fetch_rr char xsetname x set name x int number x record number x Z_Referenceld x referenceld reference ID x Odr_oid request_format format transfer syntax OID x Z_RecordComposition xcomp Formatting instructions x ODR stream encoding stream memory source if req ODR print printing stream char basename name of database that provided record x int len length of record or 1 if structured x char xrecord x record x int last_in_set x is it x Odr_oid xoutput_format response format syntax OID x int errcode O success char errstring x system error string or NULL x int surrogate_flag x surrogate diagnostic x char xschema string record schema input output x bend_fetch_rr The frontend server calls the bend_fetch handler when it needs database records to fulfill a Z39 50 Search Request a 239 50 Present Request or a SRU SearchRetrieveRequest The setname is simply the name of the result set that holds the reference to the desired record The number is the offset into the set with 1 being the first record in the set The
145. hould be used in Piggyback searches halos 0 if not If hits is less than or equal to this value then smallSetUpperBound target will return all records using small element 0 set name largeSetLowerBound If hits is greater than this value the target will 1 return no records This value represents the number of records to WA E be returned as part of a search when hits is less 0 than or equal to large set lower bound and if hits 1s greater than small set upper bound smallSetElementSetName element set name to be used for small result on mediumSetElementSetName a a E Dae IO Ds none medium sized result sets init_opt_search After a successful Init these options may be init ont nresent interrooated to discover whether the server none YAZ User s Guide and Reference 17 184 If authentcationMode is url then user and password are encoded in the URL by parameters x username and x password as given by the SRU standard 3 2 Queries Query objects represents queries ZOOM query ZOOM_query_create void void ZOOM guery destroy ZOOM_query a int ZOOM_query_prefix ZOOM_query q const char xstr int ZOOM query_cql ZOOM query s const char x str int ZOOM_query_sortby Z00M_query q const char x criteria int ZOOM_query_sortby2 ZOOM_query q const char strategy const char x criteria Create query objects using ZOOM_query_create and destroy them by calling ZOOM_query_dest roy RPN queries can be specifi
146. ike to make available by means of Z39 50 or SRU YAZ basically offers two options You can use the APIs provided by the 239 50 ASN 1 ODR and COMSTACK modules to create and decode PDUs and exchange them with a client Using this low level interface glves you access to all fields and options of the protocol and you can construct your server as close to your existing database as you like It is also a fairly involved process requiring you to set up an event handling mechanism protocol state machine etc To simplify server implementation we have implemented a compact and simple but reasonably full functioned server frontend that will handle most of the protocol mechanics while leaving you to concentrate on your database interface Note The backend interface was designed in anticipation of a specific integration task while still attempting to achieve some degree of generality We realize fully that there are points where the interface can be improved significantly If you have specific functions or parameters that you think could be useful send us a mail or better sign on to the mailing list referred to in the top level README file We will try to fit good suggestions into future releases to the extent that it can be done without requiring too many structural changes in existing applications Note The YAZ server does not support XCQL 4 2 The Database Frontend We refer to this software as a generic database frontend Your dat
147. ility can be used in two ways It may read some text using an XML configuration for configuring ICU and show text analysis This mode is triggered by option c which specififies the configuration to be used The input file is read from standard input or from a file if infile is specified The utility may also show ICU information This is triggered by option p YAZ User s Guide and Reference 153 184 OPTIONS C config Specifies the file containing ICU chain configuration which is XML based p type Specifies extra information to be printed about the ICU system If type is c then ICU converters are printed If type is 1 available locales are printed If type is t available transliterators are printed s Specifies that output should include sort key as well Note that sort key differs between ICU versions x Specifies that output should be XML based rather than text based ICU chain configuration The ICU chain configuration speicifies one or more rules to convert text data into tokens The configuration format is XML based The toplevel element must be named icu_chain The icu_chain element has one required attribute locale which specifies the ICU locale to be used in the conversion steps The icu_chain element must include elements where each element specifies a conversion step The conversion is performed in the order in which the conversion steps are specified Each conversion element takes one attribute rule which ser
148. in If optional is nonzero the pointer pointed to by p will be set to the null value and the function will return 1 The name argument is used to pretty print the tag in question It may be set to NULL if pretty printing is not desired If the data value is found where it s expected the pointer pointed to by the p argument will be set to point to the decoded type The space for the type will be allocated and owned by the ODR stream and it will live until you call odr_reset on the stream You cannot use free 2 to release the memory You can decode several data elements by repeated calls to odr_setbuf and your decoding function and new memory will be allocated each time When you do call odr_reset everything decoded since the last call to odr_reset will be released Example 8 2 Encoding and decoding of an integer The use of the double indirection can be a little confusing at first its purpose will become clear later on hopefully so an example is in order We ll encode an integer value and immediately decode it again using a different stream A useless but informative operation void do_nothing_useful Odr_int value ODR encode decode Odr_int xvalp resvalp char xbufferp YAZ User s Guide and Reference 101 184 bae Lea allocate streams x if encode odr_createmem ODR_ENCODE return if decode odr_createmem ODR_DECODE return va
149. in o p sizeof xxp name 0 return optional amp amp odr_ok o LS cuca CL imceger Oo El gt veut Op ama tes Cele loa E DONNE COINS ET odr_sequence_end o The definition of the structure MySequence would be the same 8 3 4 2 Explicit Tagging Explicit tagging of constructed types is a little more complicated since you are in effect adding a level of construction to the data Assume the definition MySequence 10 IMPLICIT SEQUENCE intval INTEGER boolval BOOLEAN OPTIONAL Since the new type has an extra level of construction two new functions are needed to encapsulate the base type int odr_constructed_begin ODR o void xp int class int tag const char xname int odr_constructed_end ODR o Assume that the IMPLICIT in the type definition above were replaced with EXPLICIT or that the IM PLICIT keyword were simply deleted which would be equivalent The structure definition would look the same but the function would look like this int mySequence ODR o MySequence xxp int optional const char name if odr_constructed_begin o p ODR CONTEXT 10 name 0 return optional amp amp odr_ok o ai gt ae Catone OD Rea ES ODE xp odr_malloc o sizeof xxp if odr sequence begin o p sizeof xxp 0 0 xp 0 x this is almost certainly a protocol error x recule Op return Clie arsgen o 5319 bave 07 Marc fxs sel Jal CG
150. in tagset TAGSET et Z3950_PREFIX 14 1000 81 2 yaz_oid_tagset_zthes_tagset Zthes tagset TAGSET 73950 PREFIX 14 8 yaz_oid_negot_charset_3 Sharat HEGO Z3950_PREFIX 15 3 yaz_oid_negot_charset_4 Chaser Ne Z3950_PREFIX 15 4 yaz_oid_negot_charset_id chassi NESHI Z3950_PREFIX 15 1000 81 1 yaz_oid_userinfo_cql Ch ERS Z3950_PREFIX 16 2 yaz_oid_general_ucs_2 LES GENRE 1 0 10646 1 0 2 z yaz_oid_general_ucs_4 aoe cis 1 0 10646 1 0 4 E yaz_oid_general_utf_16 bie CNE 1 0 10646 1 0 5 A yaz_oid_general_utf_8 eas GENERAR 1 0 10646 1 0 8 yaz_oid_userinfo_oclc_useri OCLC userInfo USERINFO nfo Z3950_PREFIX 10 1000 17 1 XML ES EXTSERV yaz_oid_extserv_xml_es Name Class Constant OID Z3950_PREFIX 9 1000 105 4 YAZ User s Guide and Reference 169 184 Appendix B Bib 1 diagnostics List of Bib 1 diagnostics that are known to YAZ Code Text 1 Permanent system error 2 Temporary system error 3 Unsupported search 4 Terms only exclusion stop words 5 Too many argument words 6 Too many boolean operators 7 Too many truncated words 8 Too many incomplete subfields 9 Truncated words too short 10 Invalid format for record number search term 11 Too many characters in search statement 12 Too many records retrieved 13 Present request out of range 14 System error in presenting records 1
151. ing int protocol COMSTACK cs create host const char x str int blocking void xxvp int cs bind COMSTACK handle int mode int cs connect COMSTACK handle void xaddress int cs_rcevconnect COMSTACK handle int cs _ listen COMSTACK handle COMSTACK cs_accept COMSTACK handle int cs_put COMSTACK handle char buf int len int cs_get COMSTACK handle char xxbuf int x size int cs_more COMSTACK handle void cs_close COMSTACK handle int cs_look COMSTACK handle void cs_straddr COMSTACK handle const char x str const char cs_addrstr COMSTACK h YAZ User s Guide and Reference 125 184 Chapter 10 Future Directions We have a new and better version of the front end server on the drawing board Resources and external commitments will govern when we ll be able to do something real with it Features should include greater flexibility greater support for access resource control and easy support for Explain possibly with Zebra as an extra database engine YAZ is a BER toolkit and as such should support all protocols out there based on that We d like to see running ILL applications It shouldn t be that hard Another thing that would be interesting is LDAP Maybe a generic framework for doing IR using both LDAP and Z39 50 transparently The SOAP implementation is incomplete In the future we hope to add more features to it Perhaps make a WSDL XML Schema compiler The author
152. isplaycharset If displaycharset is given it specifies name of the character set of the output on the terminal on which YAZ client is running u auth If specified the auth string will be used for authentication v level Sets the LOG level to level Level is a sequence of tokens separated by comma Each token is a integer or anamed LOG item one of fatal debug warn log malloc all none V Prints YAZ version x Makes the YAZ client print hex dumps of packages sent and received on standard output COMMANDS The YAZ client accepts the following commands open zurl Opens a connection to a server The syntax for zuri is the same as described above for connecting from the command line Syntax tcp ssll unix http host port base quit Quits YAZ client YAZ User s Guide and Reference 129 184 find query Sends a Search Request using the query given By default the query is assumed to be PQF See command querytype for more information delete setname Deletes result set with name setname on the server base basel base2 Sets the name s of the database s to search One or more databases may be specified separated by blanks This commands overrides the database given in zur1 show start number Fetches records by sending a Present Request from the start position given by start a number of records given by number If start is not given then the client will fetch from position of the last retrieved re
153. it The pointer returned by statserv_getcontrol points to a static area You are allowed to change the contents of the structure but the changes will not take effect until you call void statserv_setcontrol statserv_options_block xblock Note You should generally update this structure before calling statserv_main 4 5 The Backend Functions For each service of the protocol the backend interface declares one or two functions You are required to provide implementations of the functions representing the services that you wish to implement 4 5 1 Init bend_initresult bend_init bend_initrequest xr This handler is called once for each new connection request after a new process thread has been created and an Initialize Request has been received from the client The pointer to the bend_init handler is passed in the call to statserv_start This handler is also called when operating in SRU mode when a connection has been made even though SRU does not offer this service Unlike previous versions of YAZ the bend_init also serves as a handler that defines the Z39 50 services that the backend intends to support Pointers to all service handlers including search and fetch must be specified here in this handler The request and result structures are defined as YAZ User s Guide and Reference 37 184 typedef struct bend_initrequest xx brief user name password to be read Z_IdAuthentication x auth
154. ked with parameters in a server proxy The retrieval facility matches the parameters a set of supported retrieval types If there is no match the retrieval signals an error syntax and or schema not supported For a successful match the backend is invoked with the same or altered retrieval parameters syntax schema If a record is received from the backend it is converted to the frontend name syntax The resulting record is sent back the client and tagged with the frontend syntax schema The Retrieval facility is driven by an XML configuration The configuration 1s neither Z39 50 ZeeRex or SRU ZeeRex But it should be easy to generate both of them from the XML configuration unfortunately the two versions of ZeeRex differ substantially in this regard YAZ User s Guide and Reference 91 184 7 6 1 Retrieval XML format All elements should be covered by namespace http indexdata com yaz The root element node must be retrievalinfo The retrievalinfo must include one or more retrieval elements Each retrieval defines specific combination of syntax name and identifier supported by this retrieval service The retrieval element may include any of the following attributes syntax REQUIRED Defines the record syntax Possible values is any of the names defined in YAZ OID database or a raw OID in n n n name OPTIONAL Defines the name of the retrieval format This can be any string For SRU the value is equiv
155. lell p pfile d config I ludedir m module filename includeout i inc YAZ User s Guide and Reference 143 184 DESCRIPTION yaz asncomp is an ASN 1 compiler that reads an ASN 1 specification in filename and produces C C definitions and BER encoders decoders for it The produced C C code and header files uses the ODR module of YAZ which is a library that encodes de codes prints BER packages yaz asncomp allows you to specify name of resulting source via options Al ternatively you can specify a DEFINISIONS file which provides customized output to many output files if the ASN 1 specification file consists of many modules This utility is written in Tcl Any version of Tel should work OPTIONS v Makes the ASN 1 compiler print more verbose about the various stages of operations c cfile Specifies the name of the C C file with encoders decoders h hfile Specifies the name of header file with definitions p pfile Specifies the name of the a private header file with definitions By default all definitions are put in header file option h d dfile Specifies the name of a definitions file I out Specifies first part of directory in which header files are written i idir Specifies second part of directory in which header files are written m module Specifies that ASN 1 compiler should only process the module given If this option is not specified all modules in the ASN 1 file are processed D
156. leveal LAgASeQ9 Z3 iL Alo lte vela 149432 292233 11 Loculswel 4 44 13 23 11 yaz ztest session 4 44 13 23 11 yaz ztest server 14 44 13 23 11 yaz ztest 14 44 20 23 11 yaz ztest session 14 44 20 23 11 yaz ztest request 14 44 20 23 11 yaz ztest requestdetail 14 44 20 23 11 yaz ztest 14 44 20 23 11 yaz ztest se EIC sale Bale EL ELG BLG ELE U ep Ur URU USU ELE amic amic level level glevel level level level level level See the details of the requests for yaz ztest bi bi bi bi bi bi bi bi bi bi ESC 0 0 log log log log log log log log log log OF er cr Cr wr amp Ginn Gal 0 0 al TEREI rn returni ting log level to 4096 0000001 0000002 0000004 0000008 0000080 0000800 0001000 0002000 0004000 0008000 ng log gz G LOS Ie Stma debug warn LA Log mall ESS Loc email server is off session request 0x4000 f 0x000010 is oc 00 ol E tS OFF LS CIE LS Sl LS OIE O E 0x2000 EEE LER EECUEN ESA ISE VICIO EIC a p Fe En NO log loe Igi LOG 194 NO tog Bir NO log bi ort LOR 0x4000
157. lowing queries are all valid dylan Wioyoley chy ileal dylan or zimmerman set 1 dylan and bob or set 1 DO MEE CINE E Mo RUN con singlechar mask Assuming that the qualifiers ti au and date are defined we may use ti self portrait au bob dylan and slow train coming date gt 1980 and ti self portrait 7 1 2 2 CCL Qualifiers Qualifiers are used to direct the search to a particular searchable index such as title ti and author indexes au The CCL standard itself doesn t specify a particular set of qualifiers but it does suggest a few short hand notations You can customize the CCL parser to support a particular set of qualifiers to reflect the current target profile Traditionally a qualifier would map to a particular use attribute within the BIB 1 attribute set It is also possible to set other attributes such as the structure attribute A CCL profile is a set of predefined CCL qualifiers that may be read from a file or set in the CCL API The YAZ client reads its CCL qualifiers from a file named default bib There are four types of lines in a CCL profile qualifier specification qualifier alias comments and directives 7 1 2 2 1 Qualifier specification A qualifier specification is of the form qualifier name attributeset type val attributeset type val where qualifier name is the name of the qualifier to be used eg ti type is attribute type in the attribute set
158. lp amp value if odr_integer encode amp valp 0 0 0 printf encoding went bad n return bufferp odr_getbuf encode amp len 0 palito q alto Re nico ae ciao ss NOMME ne x now let s decode the thing again x odr_setbuf decode bufferp len 0 if odr_integer decode amp resvalp 0 0 0 printf decoding went bad n TOR ODR_INT_PRINTF format for printf such as d x printi Wehe velms als Y ODR TNE Ador Nal iS svecuio y x clean up odr_destroy encode odr_destroy decode This looks like a lot of work offhand In practice the ODR streams will typically be allocated once in the beginning of your program or at the beginning of a new network session and the encoding and decoding will only take place in a few isolated places in your program so the overhead is quite manageable 8 2 4 Printing When an ODR stream is created of type ODR_PRINT the ODR module will print the contents of a PDU in a readable format By default output is written to the stderr stream This behavior can be changed however by calling the function odr_setprint ODR o FILE xfile before encoders or decoders are being invoked It is also possible to direct the output to a buffer of indeed another file by using the more generic mechanism void odr set _stream ODR o void xhandle void xstream_write ODR o void xhandle int type const char x buf
159. lr Solr Web Service Using the facility for embedding options in target strings a connection can be forced to use SRU rather the SRW the default by prefixing the target string with sru get like this sru get http sru miketaylor org uk 80 sru pl Solr protocol support was added to YAZ in version 4 1 0 as a dialect of a SRU protocol since both are HTTP based protocols The lack of a simple 239 50 client API for YAZ has become more and more apparent over time So when the first ZOOM specification became available an implementation for YAZ was quickly developed For the first time it is now as easy or easier to develop clients as it is to develop servers with YAZ This chapter describes the ZOOM C binding Before going further please reconsider whether C is the right programming language for the job There are other language bindings available for YAZ and still more are in active development See the ZOOM web site for more information In order to fully understand this chapter you should read and try the example programs zoomtst1 c zoomtst2 c inthe zoom directory The C language misses features found in object oriented languages such as C Java etc For example you Il have to manually destroy all objects you create even though you may think of them as temporary Most objects have a_create and a_destroy variant All objects are in fact pointers to internal stuff but you don t see that because of typedefs All destroy method
160. nal gt lt host gt server2 mydomain lt host gt lt directory gt var www s2 lt directory gt lt config gt config cfg lt config gt CP etc pgi properties lt cql2rpi gt lt explain xmlns http explain z3950 org dtd 2 0 gt lt serverInfo gt lt host gt server2 mydomain lt host gt lt port gt 9900 lt port gt lt database gt a lt database gt lt serverInfo gt lt explain gt lt server gt lt server id server3 listenref internal gt lt directory gt var www s3 lt directory gt lt config gt config cfg lt config gt lt server gt lt yazgfs gt There are three configured backend servers The first two servers server1 and server2 can be reached by both listener addresses serverl is reached by all two since no listenref attribute is specified server2 1s reached by the two listeners specified In order to distinguish between the two a virtual host has been specified for each server in the host elements For server2 elements for CQL to RPN conversion is supported and explain information has been added a short one here to keep the example small The third server server3 can only be reached via listener internal YAZ User s Guide and Reference 49 184 Chapter 5 The Z39 50 ASN 1 Module 5 1 Introduction The Z39 50 ASN 1 module provides you with a set of C struct definitions for the various PDUs of the Z39 50 protocol as well as for the complex typ
161. ncoding e MARCXML records for element set marcxml Dublin core records for element set dc 7 6 3 API It should be easy to use the retrieval systems from applications Refer to the headers yaz retrieval h and yaz record_conv h 7 7 Sorting This chapter describes sorting and how it is supported in YAZ Sorting applies to a result set The 239 50 sorting facility takes one or more input result sets and one result set as output The most simple case is that the input set is the same as the output set 739 50 sorting has a separate APDU service that is thus performed following a search two phases In SRU Solr however the model is different Here sorting is specified during the the search operation Note however that SRU might perform sort as separate search by referring to an existing result set in the query result set reference 7 7 1 Using the Z39 50 sort service yaz client and the ZOOM API supports the Z39 50 sort facility In any case the sort sequence or sort critiera is using a string notation This notation is a one line notation suitable for being manually entered or generated and allows for easy logging one liner For the ZOOM API the sort is specified in the call to ZOOM_query_sortby function For yaz client the sort is performed and specified using the sort and sort commands For description of the sort criteria notation refer to the sort command in the yaz client manual The ZOOM API might choose one
162. nd 71 Unsupported record packing 72 XPath retrieval unsupported 73 XPath expression contains unsupported feature 74 Unable to evaluate XPath expression 80 Sort not supported 81 Unsupported sort type 82 Unsupported sort sequence YAZ User s Guide and Reference 177 184 Code Text 83 Too many records to sort 84 Too many sort keys to sort 85 Duplicate sort keys 86 Cannot sort incompatible record formats 87 Unsupported schema for sort 88 Unsupported path for sort 89 Path unsupported for schema 90 Unsupported direction value 91 Unsupported case value 92 Unsupported missing value action 93 Sort ended due to missing value 100 Explain not supported 101 Explain request type not supported SOAP vs GET 102 Explain record temporarily unavailable 110 Stylesheets not supported 111 Unsupported stylesheet 120 Response position out of range 121 Too many terms requested 235 Database does not exist 236 Access to specified database denied 1015 Init AC Maximum number of simultaneous sessions for Userid 1074 Proxy failure YAZ User s Guide and Reference 179 184 Appendix D License D 1 Index Data Copyright Copyright 1995 2015 Index Data All rights reserved Redistribution and use in source and binary forms with or without modification are permitted provided that the following conditions are met e Redistrib
163. nd right left and right operand respectively modifiers proximity arguments The sort node represents both the SORTBY clause 7 1 3 3 COL to PQF conversion Conversion to PQF and 239 50 RPN is tricky by the fact that the resulting RPN depends on the Z39 50 target capabilities combinations of supported attributes In addition the CQL and SRU operates on index prefixes URI or strings whereas the RPN uses Object Identifiers for attribute sets The CQL library of YAZ defines a cq1_transform_t type It represents a particular mapping between CQL and RPN This handle is created and destroyed by the functions cql_transform_t cql_transform_open_FILE FILE xf cql_transform_t cgql_transform_open_fname const char x fname void cql_transform_close cql_transform_t ct YAZ User s Guide and Reference 79 184 The first two functions create a tranformation handle from either an already open FILE or from a filename respectively The handle is destroyed by cql_transform close in which case no further reference of the handle is allowed Whena cql_transform_t handle has been created you can convert to RPN int cql_transform_ buf cql_transform_t ct struct cql_node cn char out int max This function converts the CQL tree cn using handle ct For the resulting PQF you supply a buffer out which must be able to hold at at least max characters If conversion failed cql_transform_buf returns a
164. nd this chapter useful Chapter 5 documents the most commonly used Z39 50 C data structures offered by the YAZ API Client developers using ZOOM and non Z39 50 implementors may skip this Chapter 6 describes how SRU and SOAP is used in YAZ Only if you re developing SRU applications this section is a must Chapter 7 contains sections for the various tools offered by YAZ Scan through the material quickly and see what s relevant to you SRU implementors might find the CQL section particularly useful Chapter 8 goes through the details of the ODR module which is the work horse that encodes and de codes BER packages Implementors using ZOOM only do not need to read this Most other 239 50 implementors only need to read the first two sections Section 8 1 and Section 8 2 Chapter 9 describes the network layer module COMSTACK Implementors using ZOOM or the generic frontend server may skip this Others presumably handling client server communication on their own should read this 1 2 The API The YAZ toolkit offers several different levels of access to the 15023950 Z39 50 ILL and SRU protocols The level that you need to use depends on your requirements and the role server or client that you want to implement If you re developing a client application you should consider the ZOOM API It is by far the easiest way to develop clients in C Server implementers should consider the generic frontend server None of those high level APIs suppor
165. ne option c YAZ User s Guide and Reference 47 184 element directory optional Specifies a working directory for this backend server If specified the YAZ frontend changes current working directory to this directory whenever a backend of this type is started backend handler bend start stopped backend handler hand stop and initialized bend_init element host optional Specifies the virtual host for this server If this is specified a client must specify this host string in order to use this backend element cq12rpn optional Specifies a filename that includes CQL to RPN conversion for this backend server See Section 7 1 3 4 If given the backend server will only see a Type 1 RPN query element ccl2rpn optional Specifies a filename that includes CCL to RPN conversion for this backend server See Section 7 1 2 2 If given the backend server will only see a Type 1 RPN query element stylesheet optional Specifies the stylesheet reference to be part of SRU HTTP responses when the client does not specify one If none is given then if the client does not specify one then no stylesheet reference is part of the SRU HTTP response element client_query_charset optional If specified a conversion from the character set given to UTF 8 is performed by the generic frontend server It is only executed for Z39 50 search requests SRU Solr are assumed to be UTF 8 encoded already element docpath optional Specifies a path
166. not create shared libraries also known as shared objects so By default shared libraries are created equivalent to enable shared disable shared The make process will not create static libraries a By default static libraries are created equivalent to enable static with iconv prefix Compile YAZ with iconv library in directory prefix By default configure will search for iconv on the system Use this option if it doesn t find iconv Alternatively with out iconv can be used to force YAZ not to use iconv with xslt prefix Compile YAZ with libxslt in directory prefix Use this option if you want XSLT and XML support By default configure will search for libxslt on the system Use this option if libxslt is not found automatically Alternatively without xslt can be used to force YAZ not to use libxslt with xml2 prefix Compile YAZ with libxml in directory prefix Use this option if you want YAZ to use XML and support SRU Solr By default configure will search for libxm12 on the system Use this option if libxml is not found automatically Alternatively without xm12 can be used to force YAZ not to use libxml2 Note that option with xs1t also enables libxml12 with gnut1s prefix YAZ will be linked with the GNU TLS libraries and an SSL COMSTACK will be provided By default configure enables SSL support for YAZ if the GNU TLS development libraries are found on the system with icul prefix Y
167. nsists of mapping specifications one per line Lines starting with are ignored comments Each line is of the form COL pattern RPN equivalent An RPN pattern is a simple attribute list Each attribute pair takes the form set type value The attribute set is optional The t ype 1s the attribute type value the attribute value The character asterisk has special meaning when used in the RPN pattern Each occurrence of is substituted with the CQL matching name index relation qualifier etc This facility can be used to copy a CQL name verbatim to the RPN result The following CQL patterns are recognized index set name This pattern is invoked when a CQL index such as dc title is converted set and name are the context set and index name respectively Typically the RPN specifies an equivalent use attribute For terms not bound by an index the pattern index cql serverChoice is used Here the prefix cal is defined as http www loc gov zing cql cql indexes vl1 0 If this pattern is not defined the mapping will fail The pattern index set is used when no other index pattern is matched qualifier set name DEPRECATED For backwards compatibility this is recognised as a syn onym of index set nam relation relation This pattern specifies how a CQL relation is mapped to RPN pattern is name of relation operator Since is used as separator between CQL pattern and RPN CQL relations including cannot be us
168. nsole application See chapter YAZ client for more information bin yaz icu exe This program exposes the ICU wrapper library if that is enabled for YAZ Only if ICU is available this program is built bin zoomsh exe Simple console application implemented on top of the ZOOM functions The ap plication is a command line shell that allows you to enter simple commands to perform ZOOM operations bin zoomtst1 exe bin zoomtst2 exe Several small applications that demonstrate the ZOOM API 2 3 2 How to make apps using YAZ on Windows This section will go though the process of linking your Windows applications with YAZ Some people are confused by the fact that we use the nmake tool to build YAZ They think they have to do that too in order to make their Windows applications work with YAZ The good news is that you don t have to You can use the integrated environment of Visual Studio if desired for your own application When setting up a project or Makefile you have to set the following include path Set it to the include directory of YAZ import library yaz5 1ib You must link with this library It s located in the sub directory lib of YAZ If you want to link with the debug version of YAZ you must link against yaz5d 1ib instead dynamic link library yaz5 d11 This DLL must be in your execution path when you invoke your appli cation Specifically you should distribute this DLL with your application 2 3 3 Compiling Libxml2 an
169. nt x size void odr_setbuf ODR o char buf int len int can grow void odr_malloc ODR o int size NMEM odr_extract_mem ODR o int odr_geterror ODR o void odr_perror ODR o const char message extern char odr_errlist 8 3 Programming with ODR The API of ODR is designed to reflect the structure of ASN 1 rather than BER itself Future releases may be able to represent data in other external forms Tip There is an ASN 1 tutorial available at this site This site also has standards for ASN 1 X 680 and BER X 690 online The ODR interface is based loosely on that of the Sun Microsystems XDR routines Specifically each function which corresponds to an ASN 1 primitive type has a dual function Depending on the settings of the ODR stream which is supplied as a parameter the function may be used either to encode or decode data The functions that can be built using these primitive functions to represent more complex data types share this quality The result is that you only have to enter the definition for a type once and you have the functionality of encoding decoding and pretty printing all in one unit The resulting C source code is quite compact and is a pretty straightforward representation of the source ASN 1 specification In many cases the model of the XDR functions works quite well in this role In others it is less elegant Most of the hassle comes from the option
170. o convert the CCL RPN tree type struct ccl_rpn_ node to the Z RPNQuery of YAZ the func tion ccl_rpn_query must be used This function which is part of YAZ is implemented in yaz ccl c After calling this function the CCL RPN tree is probably no longer needed The ccl_rpn delete destroys the CCL RPN tree A CCL profile may be destroyed by calling the cc1_qual_rm function The token names for the CCL operators may be changed by setting the globals all type char ccl_to ken_and ccl_token_or ccl_token_not and ccl_token_set An operator may have aliases i e there may be more than one name for the operator To do this separate each alias with a space character 7 1 3 CQL CQL Common Query Language was defined for the SRU protocol In many ways CQL has a similar syntax to CCL The objective of CQL is different Where CCL aims to be an end user language CQL is the protocol query language for SRU Tip If you are new to CQL read the Gentle Introduction The CQL parser in YAZ provides the following It parses and validates a CQL query It generates a C structure that allows you to convert a CQL query to some other query language such as SQL e The parser converts a valid CQL query to PQF thus providing a way to use CQL for both SRU servers and Z39 50 targets at the same time e The parser converts CQL to XCQL XCQL is an XML representation of CQL XCQL is part of the SRU specification However since SRU supports
171. o optimize retrieval of multiple records int bend_search void handle bend_search_rr x rr typedef struct char xsetname name to give to this set x int replace_set replace set if it already exists x int num_bases number of databases in list x char basenames x databases to search Z_Referenceld referenceld x reference ID x Z Query xquery x query structure x ODR stream encode stream ODR decode x decode stream ODR print print stream bend_request request bend_association association int fd int hits number of hits x int errcode x 0 0K x char xerrstring x system error string or NULL x Z_OtherInformation search_info additional search info x char srw_sortKeys x holds SRU SRW sortKeys info x char srw_setname holds SRU SRW generated resultsetID x int srw_setnamelIdleTime x holds SRU SRW life time x int estimated_hit_count x if hit count is estimated x int partial_resultset x if result set is partial x bend search rr The bend search handler is a fairly close approximation of a protocol Z39 50 Search Request and Response PDUs The setname is the resultSetName from the protocol You are required to establish a mapping between the set name and whatever your backend database likes to use Similarly the repla ce_set is a boolean value corresponding to
172. of each sort specification must consist of s for case sensitive or i for case insensitive and lt for ascending order or gt for descending order sort Same as sort but stores the sorted result set in a new result set authentication openauth Sets up a authentication string if a server requires authentication v2 OpenStyle The authentication string is first sent to the server when the open command is issued and the Z39 50 Initialize Request is sent so this command must be used before open in order to be effective A common convention for the authopen string is that the username and password is separated by a slash e g myusername mysecret sru method version Selects Web Service method and version Must be one of post get soap default or solr Version should be either 1 1 1 2 or 2 0 for SRU Other versions are allowed for testing purposes version negotiation with SRU server The version is currently not used for Solr Web Services list all This command displays status and values for many settings lslbn Sets the limit for when no records should be returned together with the search result See the 739 50 standard on set bounds for more details ssub n Sets the limit for when all records should be returned with the search result See the 739 50 standard on set bounds for more details mspn n Sets the number of records should be returned if the number of records in the result set is between the values of 1s1b and ssub S
173. often containing fatal warn log and some application specific values The default list can be cleared with the word none or individual bits can be removed by prefixing them with a dash gt LOG LEVELS TO CONTROL LOGGING Some of the log levels control the way the log is written flush causes the log to be flushed after every write This can have serious implications to performance and should not be used in production On the other hand when debugging a program crash this can be extremely useful The option debug implies flush as well notime prevents the writing of time stamps This is intended for automatic test scripts which should produce predictable log files that are easy to compare YAZ User s Guide and Reference 149 184 GENERAL LOG LEVELS IN YAZ ITSELF YAZ itself uses the following log levels fatal for fatal errors that prevent further execution of the program warn for warnings about things that should be corrected debug for debugging This flag may be used temporarily when developing or debugging yaz or a program that uses yaz It is practically deprecated you should be defining and using your own log levels see below all turns on almost all hard coded log levels loglevel logs information about the log levels used by the program Every time the log level is changed lists all bits that are on Every time a module asks for its log bits this is logged This can be used for getting an idea of what log
174. ogramming with ODR 104 8 3 1 The Primitive ASN 1 Types 104 83L INTEGER pi a wt a O AAA RA A ES 104 8 3 2 BOOLEAN s seg aad ra rara 105 Bole REA 2 2G Bw II OA 105 Bale NUEL idad BO eke O eS ee OS od BRR BRS 105 8 3 1 5 OCTET STRING 105 Bole BUS ERING ss ui De ee oe EE SREY ee EE oS 106 8 3 1 7 OBJECTIDENTIFIER 0 coses s NON ood A ORCA RR ORS 106 8 3 2 Tagging Primitive Types e 107 8 3 3 Constructed Types 107 8 3 4 Tagging Constructed Types 108 8 3 4 1 Implicit Tagging 108 8 3 4 2 Explicit Tage 2 21 4 2 goats csata dowti a ee Boe ge bd A 109 8 33 SEQUENCE OF e sesos ne SOs es SOS Se RIRE ST Rise ages 110 8 3 6 CHOICE Types 111 AE AA aa a a A ee ee a eee YAA WA 113 9 The COMSTACK Module 115 9 1 Synopsis blocking mode 115 A a III 116 9 3 Common Functions 117 9 3 1 Managing Endpoints 117 9 3 2 Data Exchange 117 OL Chent Side m ari e on a a AA A 119 YAZ User s Guide and Reference 10 11 95 Server Side 9 6 Addresses 97 SSL coros 9 8 Diagnostics 9 9 Summary and Synopsis Future Directions Reference
175. ogus rpn context set is also the default so we can make queries such as title a which is converted to attr 2 3 attr 4 1 attr 3 3 attr l title a Example 7 12 CQL to RPN using Bath Profile The file etc pqf properties has mappings from the Bath Profile and Dublin Core to RPN If YAZ is installed as a package it s usually located in usr share yaz etc and part of the development package such as 1ibyaz dev 7 1 3 5 CQLto XCQL conversion Conversion from CQL to XCQL is trivial and does not require a mapping to be defined There three func tions to choose from depending on the way you wish to store the resulting output XML buffer containing XCQL int cql_to_xml_buf struct cal _ node cn char vout int max void cql_to_xml struct cgl_node cn void xpr const char buf void xclient_data void xclient data void cal _to_ xml _ stdio struct cgl node cn FILE xf Function cql_to_xml_buf converts to XCQL and stores result in a user supplied buffer of a given max size cql_to_xml writes the result in a user defined output stream caql_to_xml_stdio writes to a a file YAZ User s Guide and Reference 83 184 7 1 3 6 PQF to CQL conversion Conversion from PQF to CQL is offered by the two functions shown below The former uses a generic stream for result The latter puts result in a WRBUF string container include lt yaz rpn2cql h gt int cql_transform_rpn2cql_stream cql_transform_t
176. on of YAZ YAZ includes a tiny ASN 1 compiler This compiler is written in Tcl But as for Bison you do not need it unless you re using Git version of YAZ or you re using the compiler to build your own codecs for private ASN 1 Generally it should be sufficient to run configure without options like this configure The configure script attempts to use use the C compiler specified by the CC environment variable If not set GNU C will be used if it is available The CF LAGS environment variable holds options to be passed to the C compiler If you re using Bourne compatible shell you may pass something like this to use a particular C compiler with optimization enabled CC opt ccs bin cc CFLAGS O configure To customize YAZ the configure script also accepts a set of options The most important are prefix prefix Specifies installation prefix for YAZ This is only needed if you run make inst all later to perform a system installation The prefix is usr local if not specified YAZ User s Guide and Reference 7 184 enable tcpd The front end server will be built using Wietse s TCP wrapper library It allows you to allow deny clients depending on IP number The TCP wrapper library is often used in GNU Linux and BSD distributions See hosts_access 5 and tcpd 8 enable threads YAZ will be built using POSIX threads Specifically _REENTRANT will be defined during compilation disable shared The make process will
177. onal Specifies a filename that includes CQL to RPN conversion for this backend server See Section 7 1 3 4 If given the backend server will only see a Type 1 RPN query element ccl2rpn optional Specifies a filename that includes CCL to RPN conversion for this backend server See Section 7 1 2 2 If given the backend server will only see a Type 1 RPN query element stylesheet optional Specifies the stylesheet reference to be part of SRU HTTP responses when the client does not specify one If none is given then if the client does not specify one then no stylesheet reference is part of the SRU HTTP response element client _query_charset optional If specified a conversion from the character set given to UTF 8 is performed by the generic frontend server It is only executed for Z39 50 search requests SRU Solr are assumed to be UTF 8 encoded already element docpath optional Specifies a path for local file access using HTTP All URLs with a leading prefix excluded that matches the value of docpath are used for file access For example if the server is to offer access in directory xs1 the docpath would be xs1 and all URLs of the form http host xs1 will result in a local file access element explain optional Specifies SRW SRU ZeeRex content for this server Copied verbatim to the client As things are now some of the Explain content seem redundant because host information etc is also stored elsewhere element maximumrec
178. only consult the which field to determine the type of data You can the access the data directly through the union When constructing data for encoding you set the union pointer to point to the data and set the which field accordingly Remember also to set the direct or indirect reference to the correct OID for the data type For non ASN 1 data such as MARC records use the octet_aligned arm of the union Some servers return ASN 1 structured data values eg database records as BER encoded records placed in the octet aligned branch of the EXTERNAL CHOICE The ASN module will not automatically decode these records To help you decode the records in the application the function Z_ext_typeent z_ext_gettypebyref const oid oid Can be used to retrieve information about the known external data types The function return a pointer to a static area or NULL if no match for the given direct reference is found The Z_ext_typeent is defined as typedef struct Z_ext_typeent inc Gael Ob SIA fs Timo cirect referenca OD x int what discriminator value for the external CHOICE x Oele cum FUM decoder Function j A exit ENS y The what member contains the Z External union discriminator value for the given type For the SUTRS record syntax the value would be Z_External_sutrs The fun member contains a pointer to the function which encodes decodes the given type Again for the SUTRS record syntax the value of fun
179. or condition COMSTACK cs_accept COMSTACK handle This finalizes the server side association establishment after cs_listen has completed successfully It returns a new connection endpoint which represents the new association The application will typically wish to fork off a process to handle the association at this point and continue listen for new connections on the old handle You can use the call const char ces_addrstr COMSTACK on an established connection to retrieve the host name of the remote host Note You may need to use this function with some care if your name server service is slow or unreliable 9 6 Addresses The low level format of the addresses are different depending on the mode of communication you have chosen A function is provided by each of the lower layers to map a user friendly string form address to the binary form required by the lower layers void cs_straddr COMSTACK handle const char xstr YAZ User s Guide and Reference 121 184 The format for TCP IP and SSL addresses is lt host gt lt portnum gt The hostname can be either a domain name or an IP address The port number if omitted defaults to 210 For TCP IP and SSL the special hostnames maps to INGADDR ANY INIT with IPV4 binding as well bindv6only 0 The special hostname 4 binds to INADDR_ANY IPV4 only listener The special hostname 6 binds to INGADDR ANY INIT with bindv6only 1 IPV6 only lis
180. or support only a small subset of the full functionality that can be expressed using the PQF proximity operator Be aware that the ability to express a query in PQF is no guarantee that any given server will be able to execute it The proximity operator prox is a special and more restrictive version of the conjunction operator Rand Its semantics are described in section 3 7 2 Proximity of Z39 50 the standard itself which can be read on line athttp www loc gov z3950 agency markup 09 html 3 7 2 In PQF the proximity operation is represented by a sequence of the form prox exclusion distance ordered relation which code unit code in which the meanings of the parameters are as described in in the standard and they can take the following values e exclusion 0 false i e the proximity condition specified by the remaining parameters must be satisfied or true the proximity condition specified by the remaining parameters must not be satisifed distance An integer specifying the difference between the locations of the operands e g two adjacent words would have distance 1 since their locations differ by one unit e ordered ordered the operands must occur in the order the query specifies them or 0 unordered they may appear in either order relation Recognised values are 1 lessThan 2 lessThanOrEqual 3 equal 4 greaterThanOrEqual 5 greaterThan and 6 notEqual e which code known or k the unit code paramet
181. ordsize optional Specifies maximum record size message size in bytes This value also serves as the maximum size of incoming packages for Record Updates etc It s the same value as that given by the k option element retrievalinfo optional Enables the retrieval facility to support conversions and specifica tions of record formats types See Section 7 6 for more information The XML below configures a server that accepts connections from two ports TCP IP port 9900 and a local UNIX file socket We name the TCP IP server public and the other server internal lt yazgfs gt lt listen id public gt tcp 9900 lt listen gt lt listen id internal gt unix var tmp socket lt listen gt lt server id serverl gt lt host gt serverl mydomain lt host gt lt directory gt var www s1 lt directory gt lt config gt config cfg lt config gt lt server gt lt server id server2 listenref public internal gt lt host gt server2 mydomain lt host gt lt directory gt var www s2 lt directory gt lt config gt config cfg lt config gt lt cql2rpn gt etc pqf properties lt cql2rpn gt lt explain xmlns http explain z3950 org dtd 2 0 gt lt serverInfo gt lt host gt server2 mydomain lt host gt lt port gt 9900 lt port gt lt database gt a lt database gt lt serverInfo gt lt explain gt lt server gt lt server id server3 listenref internal gt lt directory gt var www s3
182. ou should issue this command before command open is used Note MARC records are not covered by Z39 50 character set negotiation so that s why there is a separate character that must be known in order to do meaningful conversion s negcharset charset Specifies character set for negotiation Z39 50 The argument is the same as second argument for command charset displaycharset charset Specifies character set for output display The argument is the same as second argument for command charset marccharset charset Specifies character set for retrieved MARC records so that YAZ client can display them in a character suitable for your display See charset command If auto is given YAZ will assume that MARC21 USMARC is using MARC8 UTF8 and ISO 8859 1 for all other MARC variants The charset argument is the same as third argument for command charset querycharset charset Specifies character set for query terms for Z39 50 RPN queries and Z39 50 Scan Requests termListAndStartPoint This is a pure client side conversion which converts from displayCharset to queryCharset set_cclfile filename Specifies that CCL fields should be read from file file filename This com mand does the thing as option c set_cqlfile filename Specifies that CQL fields should be read from file file filename This com mand does the thing as option q register_oid name class OID This command allows you to register your own object identifier so
183. p away from the term allowing you to associate one or more attributes with an entire query structure The parser will automatically apply the given attributes to each term as required The attr operator is followed by an attribute specification att r spec above The specification consists of an optional attribute set an attribute type value pair and a sub query The attribute type value pair is packed in one string an attribute type an equals sign and an attribute value like this attr 1 1003 The type is always an integer but the value may be either an integer or a string if it doesn t start with a digit character A string attribute value is encoded as a Type 1 complex attribute with the list of values containing the single string specified and including no semantic indicators Version 3 of the Z39 50 specification defines various encoding of terms Use term type string where type is one of general numeric or string for InternationalString If no term type has been given the general form is used This is the only encoding allowed in both versions 2 and 3 of the Z39 50 standard 7 1 1 1 Using Proximity Operators with PQF Note This is an advanced topic describing how to construct queries that make very specific requirements on the relative location of their operands You may wish to skip this section and go straight to the example PQF queries Warning Most 739 50 servers do not support proximity searching
184. package send Option Description Default specialUpdate recordInsert The update action One of specialUpdate for updateVer action recordInsert recordReplace sion 1 which recordDelete elementUpdate does not support speci alUpdate recordldOpaque Opaque Record ID none recordldNumber Record ID number none record The record itself none Specifies an opaque record which is encoded as an ASN 1 ANY type with the OID as tiven by option syntax see below Option copa recordOpaque is an alternative to record MISA and record option above is ignored if recordOpague is set This option is only available in YAZ 3 0 35 and later and is meant to facilitate Updates with servers from OCLC The record syntax transfer syntax Is a string syntax i no syntax that is a known record syntax databaseName Database from connection object Default correlationInfo note Correlation Info Note string none correlationInfo id Correlation Info ID integer none elementSetName Element Set for Record none Record Update version which holds one of the values 1 2 or 3 Each version has a distinct AA OID 1 2 840 10003 9 5 first version 3 3 7 3 Database Create For Database Create type must be set to create in ZOOM package send 3 7 4 Database Drop 1 2 840 10003 9 5 1 second version and 1 2 840 10003 9 5 1 1 third and newest version Table 3 10 Record Update Options For Database Drop type must be set to drop in ZOOM package send
185. portant to realize that the ODR stream will not release this memory when you call odr_reset It will merely update its internal pointers to prepare for the encoding of a new data value When the stream is released by the odr_dest roy function the memory given to it by odr_setbuf will be released only if the can_grow parameter to odr_setbuf was nonzero The can_grow parameter in other words is a way of signaling who is to own the buffer you or the ODR stream If you never call odr_setbuf on your encoding stream which is typically the case the buffer allocated by the stream will belong to the stream by default When you wish to decode data you should first call odr_setbuf to tell the decoding stream where to find the encoded data and how long the buffer is the can_grow parameter is ignored by a decoding stream After this you can call the function corresponding to the data you wish to decode eg odr_int eger odr z_APDU Example 8 1 Encoding and decoding functions int odr_integer ODR o Odr_int lt p int optional const char xname int z_APDU ODR O Z_APDU xxp int optional const char xname If the data is absent or doesn t match the tag corresponding to the type the return value will be either 0 or 1 depending on the optional flag If optional is 0 and the data is absent an error flag will be raised in the stream and yov ll need to call odr_reset before you can use the stream aga
186. ported 245 Type 1 query restriction resultAttr operand not supported 246 Type 1 query complex attribute Value not supported 247 Type 1 query attributeSet as part of AttributeElement not supported 1001 Malformed APDU 1002 ES EXTERNAL form of Item Order request not supported 1003 ES Result set item form of Item Order request not supported 1004 ES Extended services not supported unless access control is in effect 1005 Response records in Search response not supported 1006 Response records in Search response not possible for specified database or database combination 1007 No Explain server Addinfo pointers to servers that have a surrogate Explain database for this server 1008 ES missing mandatory parameter for specified function Addinfo parameter Code Text 1009 ES Item Order unsupported OID in itemRequest Addinfo OID 1010 Init AC Bad Userid 1011 Init AC Bad Userid and or Password 1012 Init AC No searches remaining pre purchased searches exhausted 1013 Init AC Incorrect interface type specified id valid only when used with a particular access method or client 1014 Init AC Authentication System error 1015 Init AC Maximum number of simultaneous sessions for Userid 1016 Init AC Blocked network address 1017 Init AC No databases available for specified userld
187. r It will be reallocated if necessary to contain large packages and will sometimes be moved around internally by the subsystem when partial packages are read Before calling cs_get for the fist time the buffer can be initialized to the null pointer and the length should also be set to O cs_get will perform a malloc 2 on the buffer for you When a full buffer has been read the size of the package is returned which will always be greater than 1 1 indicates an error condition See also the cs_more function below int cs more COMSTACK handle The cs_more function should be used in conjunction with cs_get and select 2 Thecs_get function will sometimes notably in the TCP IP mode read more than a single protocol package off the network When this happens the extra package is stored by the subsystem After calling cs_get and before waiting for more input You should always call cs_more to check if there s a full protocol package already read If cs_more returns 1 cs_get can be used to immediately fetch the new package For the mOSI subsystem the function should always return 0 but if you want your stuff to be protocol independent you should use it Note The cs_more function is required because the RFC1729 method does not provide a way of separating individual PDUs short of partially decoding the BER Some other implementations will carefully nibble at the packet by calling read 2 several times This w
188. r functions ZOOM_connecton_new and ZOOM_co nnection_connect acts as a database at least for the YAZ SRU server YAZ User s Guide and Reference 21 184 3 4 Records A record object is a retrieval record on the client side created from result sets void ZOOM resultset records ZOOM resultset r ZOOM record recs size t start size t count ZOOM_record ZOOM_resultset_record Z00M_resultset s size_t pos const char ZOOM_record_get ZOOM record rec const char xtype size_t x len int ZOOM_record_error ZOOM_record rec const char x msg const char xaddinfo const char xxdiagset ZOOM record ZOOM record_clone ZOOM record rec void ZOOM_record_destroy ZOOM_record rec References to temporary records are returned by functions ZOOM_resultset_records or ZOOM re sultset_record If a persistent reference to a record is desired ZOOM_record_clone should be used It returns a record reference that should be destroyed by a call to ZOOM record destroy A single record is returned by function ZOOM_ resultset_ record that takes a position as argument First record has position zero If no record could be obtained NULL is returned Error information for a record can be checked with ZOOM_record_error which returns non zero error code if record is in error called Surrogate Diagnostics in Z39 50 Function ZOOM_resultset_records retrieves a number of records from a result set Parameter
189. r in the structure belonging to the enclosing type and you won t need to fiddle with memory allocation to create a separate structure to wrap the discriminator and union The corresponding function is somewhat nicer in the Sun XDR interface Most of the complexity of this interface comes from the possibility of declaring sequence elements including CHOICES optional The ASN 1 specifications naturally requires that each member of a CHOICE have a distinct tag so they can be told apart on decoding Sometimes it can be useful to define a CHOICE that has multiple types that share the same tag You 1l need some other mechanism perhaps keyed to the context of the CHOICE type In effect we would like to introduce a level of context sensitiveness to our ASN 1 specification When encoding an internal representation we have no problem as long as each CHOICE member has a distinct discriminator value For decoding we need a way to tell the choice function to look for a specific arm of the table The function void odr_choice bias ODR o int what provides this functionality When called it leaves a notice for the next call to odr_choice to be called on the decoding stream o that only the arm entry with a which field equal to what should be tried The most important application perhaps the only one really is in the definition of application specific EX TERNAL encoders decoders which will automatically decode an ANY member given the direct o
190. r indirect reference 8 4 Debugging The protocol modules are suffering somewhat from a lack of diagnostic tools at the moment Specifically ways to pretty print PDUs that aren t recognized by the system We ll include something to this end in a not too distant release In the meantime what we do when we get packages we don t understand is to compile the ODR module with ODR_DEBUG defined This causes the module to dump tracing information as it processes data units With this output and the protocol specification 239 50 it is generally fairly easy to see what goes wrong YAZ User s Guide and Reference 115 184 Chapter 9 The COMSTACK Module 9 1 Synopsis blocking mode COMSTACK stack char xbuf 0 Lart size 0 lengt OMAN cicle Seras socress sim 11 Llocalmosrt WA void server_address_ip int status har protocol_package GET HTTP 1 0 r n r n nt protocol_package_length strlen protocol_package H Q stack cs_create tcpip type 1 PROTO_HTTP e racial perror cs_ create x use perror here since we have no stack yet x ceuta ile server_address_ip cs_straddr stack server address str if server_address_ip fprintf stderr cs_straddr address could not be resolved n suda ils status cs_connect stack server_address_ip ESAS A 4 orcos Sicilia Wes Commascrs sal ESES EnEn roni S rack Sica 4 status Ccs_rcvconnect stack Le Si ASA
191. r serves as a supplement for bend_fetch and need not to be defined in order to support search and retrieve 4 5 3 Delete For back ends that supports delete of a result set only one handler must be defined int xbend_delete void xhandle bend_delete_rr xrr typedef struct bend_delete_rr int function int num_setnames char xxsetnames Z Referenceld x referenceld int delete_status status for the whole operation x int statuses status each set indexed as setnames x ODR stream ODR print bend delete rr Note The delete set function definition is rather primitive mostly because we have had no practical need for it as of yet If someone wants to provide a full delete service we d be happy to add the extra parameters that are required Are there clients out there that will actually delete sets they no longer need 4 5 4 Scan For servers that wish to offer the scan service one handler must be defined int bend_scan void handle bend_scan_rr rr typedef enum BEND SCAN SUCCESS ok x BEND_SCAN_PARTIAL x not all entries could be found x bend_scan_status typedef struct bend_scan_rr int num_bases number of elements in databaselist x char basenames x databases to search x Odr_oid xattributeset Z_Referenceld x referenceld reference ID x YAZ User s Guide and Reference 43 184 Z AttributesPlusTerm xterm
192. rd in a WRBUF handle WRBUF is a simple string type Example 7 18 Display of MARC record The following program snippet illustrates how the MARC API may be used to convert a MARC record to the line by line format voici print marce Const Chiat smarre our ine marc owr size char result fee ror result bur size result Lens Je tOr S126 OE result 2 yaz_ marc t mt yaz marc create yaz_marc_xml mt YAZ MARC_LINE yaz_marc_decode_buf mt marc_buf marc buf_size amp result amp result_len MINES MES lem i Sieclouic e yaz_marc_destroy mt x note that result is now freed 7 5 1 TurboMARC TurboMARC is yet another XML encoding of a MARC record The format was designed for fast processing with XSLT Applications like Pazpar2 uses XSLT to convert an XML encoded MARC record to an internal representa tion This conversion mostly check the tag of a MARC field to determine the basic rules in the conversion This check is costly when that is tag is encoded as an attribute in MARCXML By having the tag value as the element instead makes processing many times faster at least for Libxslt TurboMARC is encoded as follows Record elements is part of namespace http www indexdata com turbomarc A record is enclosed in element r A collection of records is enclosed in element collection The leader is encoded as element 1 with the leader content as its text val
193. re in current working directory e yazclientre in the user s home directory The value of the HOME is used to determine the home directory Normally HOME is only set on POSIX systems such as Linux FreeBSD Solaris OPTIONS a filename If specified logging of protocol packages will be appended file given If filename is spec ified as the output is written to stdout b filename If specified YAZ will dump BER data in readable notation to the file specified If filename is specified as the output is written to stdout C filename If specified CCL configuration will be read from the file given d dump If specified YAZ will dump BER data for all PDUs sent and received to individual files named dump DDD raw where DDD is 001 002 003 f cmdfile Reads commands from cmdfile When this option is used YAZ client does not read yaz clientre from current directory or home directory k size Sets preferred messages and maximum record size for Initialize Request in kilobytes Default value is 65536 64 MB m filename If specified retrieved records will be appended to the file given p proxy addr If specified the client will use the proxy at the address given YAZ client will connect to a proxy on the address and port given The actual target will be specified as part of the InitRequest to inform the proxy about actual target q filename If specified CQL configuration will be read from the file given t d
194. rence 147 184 OPTIONS ffrom Specify the character set from of the input file Should be used in conjunction with option t tto Specify the character set of of the output Should be used in conjunction with option v Print more information about the conversion process ENCODINGS The yaz iconv command and the API as defined in yaz yaz iconv his a wrapper for the library system call iconv But YAZ iconv utility also implements conversions on its own The table below lists characters sets or encodings that are supported by YAZ Each character set is marked with either encode or decode If an encoding is encode enabled YAZ may convert to to the designated encoding If an encoding is decode enabled YAZ may convert from the designated encoding marc8 encode decode The MARC 8 encoding as defined by the Library of Congress Most MARC21 USMAR records use this encoding marc8s encode decode Like MARC8 but with conversion prefers non combined characters in the Latin 1 plane over combined characters marc8lossy encode Lossy encoding of MARC 8 marc8lossless encode Lossless encoding of MARC8 utf8 encode decode The most commonly used UNICODE encoding on the Internet iso8859 1 encode decode ISO 8859 1 AKA Latin 1 iso5426 decode ISO 5426 Some MARC records UNIMARC use this encoding iso5428 1984 encode decode ISO 5428 1984 advancegreek encode decode An encoding for Greek in use by some vendors
195. res the PDU This is a simple approach and it provides the most efficient form of memory management While it works well for flat PDUs like the InitReqest it will generally not be sufficient for say the generation of an arbitrarily complex RPN query structure You can individually create the structure and its members using the malloc 2 function If you want to ensure that the data is freed when it is no longer needed you will have to define a function that individually releases each member of a structure before freeing the structure itself You can use the odr_malloc function see Section 8 2 for details When you use odr_malloc you can release all of the allocated data in a single operation independent of any pointers and relations between the data odr_malloc is based on a nibble memory scheme in which large portions of memory are allocated and then gradually handed out with each call to odr_malloc The next time you call odr_reset all of the memory allocated since the last call is recycled for future use actually it is placed on a free list You can combine all of the methods described here This will often be the most practical approach For instance you might use odr_malloc to allocate an entire structure and some of its elements while you leave other elements pointing to global or per session default variables The Z39 50 ASN 1 module provides an important aid in creating new PDUs For each of the PDU types
196. ring If the parse went well p_query_rpn returns a pointer to a Z_RPNQuery structure which can be placed directly into a Z_SearchRequest If parsing failed due to syntax error a NULL pointer is returned The p_query_attset specifies which attribute set to use 1f the query doesn t specify one by the Q attrset operator The p_query_attset returns 0 if the argument is a valid attribute set specifier otherwise the function returns 1 The grammar of the PQF is as follows YAZ User s Guide and Reference 67 184 query top set query struct top set attrset string query struct attr spec simple complex term term gt type query attr spec attr string string query struct complex operator query struct query struct operator and Qor not fprox proximity simple result set term result set set string term string proximity exclusion distance ordered relation which code unit code exclusion 17 07 void distance integer ordered 21 07 relation integer which code known private integer unit code integer term type general numeric string oid datetime null You will note that the syntax above is a fairly faithful representation of RPN except for the Attribute which has been moved a ste
197. rinted to standard error stderr The program returns exit code 0 parsing succeeds and return no output unless p is given see below OPTIONS p Makes the JSON parser echo the JSON result string to standard output if parsing from stdin was successful If p is given twice the output is a multi line output with indentation pretty print SEE ALSO yaz 7 YAZ User s Guide and Reference 161 184 Appendix A List of Object Identifiers These is a list of object identifiers that are built into YAZ Name Class Constant OID BER TRANSYN n Een EN er yaz_oid_transyn_iso2709 1502709 TRANSYN 02709 LI yaz oid general isoill 1 ISOILL 1 GENERAL 01016121 Z APDU ABSYN LIST AN SIN APE Z BASIC APPCTX Yaz 08daappotx 7 pasic yaz_oid_attset_bib_1 Bibal NRE Z3950_PREFIX3 1 yaz_oid_attset_exp 1 Pep APIO RE Z3950_PREFIX 3 2 yaz_oid_attset_ext_1 ae ANIR Z3950_PREFIX 3 3 yaz_oid_attset_ccl_ SER ALIS ee Z3950_PREFIX 3 4 yaz_oid_attset_gils GE ou Z3950_PREFIX 3 5 yaz_oid_attset_gils_attset GILS attset ATTSET 73050 PREFIX3 5 yaz_oid_attset_stas_attset STAS attset ATTSET 73950 PREFIX3 6 yaz_oid_attset_collections_ Collections attset ATTSET attset Z3950_PREFIX 3 7 yaz_oid_attset_cimi_attset CIMI attset ATTSET 73950 PREFIX3 8 yaz_oid_attset_geo_attset
198. rt modify or delete records See Section 3 7 2 e Database Create This a non standard feature Allows a client to create a database See Section 3 7 3 e Database Drop This a non standard feature Allows a client to delete drop a database See Section 3 7 4 e Commit operation This a non standard feature Allows a client to commit operations See Section 3 7 5 To create an extended service operation a ZOOM package must be created The operation is a five step operation The package is created package is configured by means of options the package is sent result is inspected by means of options the package is destroyed ZOOM package ZOOM connection package ZOOM connection cC ZOOM_ options options const char x7O0O0M package option get 7Z00M package p const char xkey void ZOOM_package_option_set ZOOM package p const char x key const char x val void ZOOM_package_send ZOOM_package p const char type void ZOOM package destroy ZOOM_package p The ZOOM_connection_package creates a package for the connection given using the options speci fied Functions ZOOM_package_option_get and ZOOM_package_option_set gets and sets options ZOOM package send sends the package the via connection specified in ZOOM connection pack age The type specifies the actual extended service package type to be sent Type Description itemorder Item Order update Record Update create Database Create drop Database Drop
199. ry because some strings correspond to multiple OIDs An example of such a string is Bib 1 which may either be an attribute set or a diagnostic set Applications using the YAZ database should include yaz oid_db h A YAZ database handle is of type yaz_oid_db_t Actually that s a pointer You need not think deal with that YAZ has a built in database which can be considered constant for most purposes We can get hold that by using function yaz_oid_std YAZ User s Guide and Reference 85 184 All functions with prefix yaz_string_to_oid converts from class string to OID We have variants of this operation due to different memory allocation strategies All functions with prefix yaz_oid_to_string converts from OID to string class Example 7 16 Create OID with YAZ DB We can create an OID for the Bib 1 attribute set on the ODR stream odr with Odr_oid xbibl yaz string o Olic oc yaz oll ste CLASS AIS Biilo Ole y This is more complex than using odr_getoidbystr You would only use yaz_string_to_oid_ odr when the string here Bib 1 is supplied by a user or configuration 7 2 2 Standard OIDs All the object identifers in the standard OID database as returned by yaz_oid_std can referenced directly in a program as a constant OID Each constant OID is prefixed with yaz_oid_ followed by OID class lowercase then by OID name normalized and lowercase See Appendix A for list of all object identifiers built into YAZ
200. s are cleared Typically this string comes from the command line often YAZ User s Guide and Reference 87 184 identified by v The yaz_log_mask_str returns a log level that should be passed to yaz log ini t_level forit to take effect Each module should check what log bits it should be used by calling yaz log module level with a suitable name for the module The name is cleared from a preceding path and an extension if any so it 1s quite possible to use __ FILE_ forit If the name has been passed to yaz_log_mask_str the routine returns a non zero bitmask which should then be used in consequent calls to yaz_log It can also be tested so as to avoid unnecessary calls to yaz_log in time critical places or when the log entry would take time to construct Yaz uses the following dynamic log levels server session request requestdetail for the server functionality zoom for the zoom client api ztest for the simple test server malloc nmem odr eventl for internal debugging of yaz itself Of course any program using yaz is welcome to define as many new ones as it needs By default the log is written to stderr but this can be changed by a call to yaz_log_init_file or yaz_log_init If the log is directed to a file the file size is checked at every write and if it exceeds the limit given in yaz_log_init_max_size the log is rotated The rotation keeps one old version with a 1 appended to the name The si
201. s eme 77 7 1 3 3 COLtoPOFconversion 78 7 1 3 4 Specification of CQL to RPN mappings 80 7 1 3 5 COLtoKCOLconversion 82 7 1 3 6 POFtoCOLconversion 83 1 2 ObjectIdentifiers o ss LS arean A A 83 T2 UD Haaa sss e oau WAA YA WAA at a a Ne 84 7 2 2 Standard OIDs 85 La Nibble MEMOR cse s oe aoi WAA a are Dee Gas wa Slee RAR ne 85 TA LOS EA 86 T MARG Su a otr ie Aea kai Sear EVET corse Do 88 Td TurbBoMARCE ee sete a aa ha a aa Ed o WA 89 140 Retrieval Facility z s sucs ee oci SALSA Wa d E e E 90 7 6 1 Retrieval XML format 91 7 6 2 Retrieval Facility Examples 92 163 BE isidro a a A a o ao exe 93 TI SONS gt ase e e e Da le de de erre Soto Grace Sua Sha Be RR oe D oe 93 7 7 1 UsingtheZ39 50sortservice 94 APA E 22222 Sad nd domi es ets ae Svea Bu tac 94 TO Facets rra ARA AAA OE a M HO at 94 8 The ODR Module 97 Ol UU sa ea bbw ERRE 97 9 2 Se ODR va 2 5260 ole Ko ek OR kankan KER RA RR aa 97 82L DR Streams 3 ven MIA SNA a as VER ai sie 97 8 2 2 Memory Management 98 8 2 3 Encoding and Decoding Data 99 D2 EE 101 8 2 5 Diagnostics 102 8 2 6 SummaryandSynopsis 103 8 3 Pr
202. s of libxml2 are already working on XML Schema RelaxNG compilers so this may not be too hard It would be neat to have a proper module mechanism for the Generic Frontend Server so that backend would be dynamically loaded as shared objects DLLs Other than that YAZ generally moves in the directions which appear to make the most people happy including ourselves as prime users of the software If there s something you d like to see in here then drop us a note and let s see what we can come up with YAZ User s Guide and Reference 127 184 Chapter 11 Reference The material in this chapter is drawn directly from the individual manual entries 11 1 yaz client yaz client Z39 50 SRU client for implementors Synopsis yaz client a apdulog b berdump c cclfilel d dump f cmdfilel k size m marclog p proxy addr q cqlfile t dispcharset u auth v loglevel v x server addr DESCRIPTION yaz client is a Z39 50 SRU client origin with a simple command line interface that allows you to test behavior and performance of Z39 50 targets and SRU servers From YAZ version 4 1 0 yaz client may also operate as a Solr Web Service client If the server addr is specified the client creates a connection to the Z39 50 SRU target at the address given When yaz client is started it tries to read commands from one of the following files e Command file if it is given by option f e yazclient
203. s should gracefully ignore a NULL pointer In each of the sections below you ll find a sub section called protocol behavior that describes how the API maps to the Z39 50 protocol 3 1 Connections The Connection object is a session with a target include lt yaz zoom h gt ZOOM connection ZOOM_ connection _new const char host int portnum ZOOM connection ZOOM connection create ZOOM options options void ZOOM connection connect Z0OM connection c const char xhost int portnum void ZOOM connection destroy ZOOM_connection Cc Connection objects are created with either function ZOOM_connection_new or ZOOM_connectio n_create The former creates and automatically attempts to establish a network connection with the target The latter doesn t establish a connection immediately thus allowing you to specify options before establishing network connection using the function ZOOM_connection_connect If the port number portnum is zero the host is consulted for a port specification If no port is given 210 is used A colon denotes the beginning of a port number in the host string If the host string includes a slash the following part specifies a database for the connection You can prefix the host with a scheme followed by colon The default scheme is t cp Z39 50 protocol The scheme http selects SRU get over HTTP by default but can overridden to use SRU post SRW and the Solr protocol You can prefix the
204. scheme qualified host string with one or more comma separated key value sequences each of which represents an option to be set into the connection structure before the protocol level connec tion is forged and the initialization handshake takes place This facility can be used to provide authentica tion credentials as in host strings such as user admin password halfAm4n tcp localhost 8017 db Connection objects should be destroyed using the function ZOOM connection destroy void ZOOM connection option set ZOOM connection c const char x key const char x val void ZOOM connection option setl1 ZOOM connection c const char xkey const char val int len const char ZOOM_connection_option_get ZOOM_connection c const char xkey const char Z00M_connection_ option _getl ZOOM connection cC const char xkey int lenp The functions ZOOM connection option set and ZOOM_connection_option_set1 allows you to set an option given by key to the value value for the connection For ZOOM connection opt ion set the value is assumed to be a 0 terminated string Function ZOOM connection option s et 1 specifies a value of a certain size len YAZ User s Guide and Reference 15 184 Functions ZOOM_connection_option_get and ZOOM_connection_option_getl returns the value for an option given by key If either option lang or charset is set then Character Set and Language Negotiation is in effect int ZOOM connection error Z
205. services namespaces of the supplied handlers If there is a match a handler function is invoked which decodes that particular SOAP package If successful the returned Z_ SOAP package will be of type Z_SOAP_Generic Member no is set the offset of handler that matched ns 1s set to namespace of matching handler the void pointer p is set to the C data structure assocatiated with the handler When a NULL namespace is met member ns bwlow that specifies end of list Each handler is defined as follows typedef struct char xns void client_data Z_SOAP_ fun f Z_SOAP Handler The ns is namespace of service associated with handler f client data is user defined data which is passed to handler The prototype for a SOAP service handler is int handler ODR o void ptr void x handler_data void client_data const char x ns The o specifies the mode decode encode as usual The second argument ptr is a libxml2 tree node pointer xm1NodePt 1 and is a pointer to the Body element of the SOAP package The handler_data is an opaque pointer to a C definitions associated with the SOAP service client_data is the pointer which was set as part of the Z_SOAP_handler Finally ns the service namespace 6 4 SRU SRU SOAP is just one implementation of a SOAP handler as described in the previous section The en coder decoder handler for SRU is defined as follows include lt yaz srw h gt int yaz_srw_codec ODR o void x pptr
206. st structure you should copy them The errcode should be zero if the initialization of the backend went well Any other value will be interpreted as an error The errst ring isn t used in the current version but one option would be to stick 1t in the initResponse as a VisibleString The handle is the most important parameter It should be set to some value that uniquely identifies the current session to the backend implementation It is used by the frontend server in any future calls to a backend function The typical use is to set 1t to point to a dynamically allocated state structure that is private to your backend module The auth member holds the authentication information part of the Z39 50 Initialize Request Interpret this 1f your server requires authentication The members peer_name implementation_id implementation_name and implementat ion version holds DNS of client ID of implementor name of client 239 50 implementation and version YAZ User s Guide and Reference 39 184 The bend members are set to NULL when bend init is called Modify the pointers by setting them to point to backend functions 4 5 2 Search and Retrieve We now describe the handlers that are required to support search and retrieve You must support two functions one for search and one for fetch retrieval of one record If desirable you can provide a third handler which is called when a present request is received which allows you t
207. t for ISO2709 based inputformats this should be set to the encoding used For MARC21 records a common inputcharset value would be marc 8 outputcharset OPTIONAL Encoding of output If outputformat is XML based it is strongly recommened to use ut f 8 select The select selects one or more text nodes and decodes them as XML The following attributes may be specified path REQUIRED X Path expression for selecting text nodes This conversion is available in YAZ 5 8 0 and later solrmarc The solrmarc decodes solrmarc records It assumes that the input is pure solrmarc text no escaping and will convert all sequences of the form XX to a single character of the hexadecimal value as given by XX The output presumably is a valid ISO2709 buffer This conversion is available in YAZ 5 0 21 and later xslt The xslt element specifies a conversion via XSLT The following attributes may be specified stylesheet REQUIRED Stylesheet file 7 6 2 Retrieval Facility Examples Example 7 19 MARC21 backend A typical way to use the retrieval facility is to enable XML for servers that only supports ISO2709 encoded MARC21 records lt retrievalinfo gt lt retrieval lt retrieval lt retrieval syntax usmarc syntax usmarc syntax xml name F gt name B gt name marcxml identifier info srw schema 1 marcxml v1 1 gt lt backend syntax usmarc lt marc inputformat marc inputcharset marc
208. t the whole protocol but they do include most facilities used in existing 739 50 applications If you re using exotic functionality meaning anything not included in the high level APIs developing non standard extensions to 239 50 or you re going to develop an ILL application you ll have to learn the lower level APIs of YAZ The YAZ toolkit modules are shown in figure Figure 1 1 YAZ User s Guide and Reference 3 184 Client server Application ILL 23350 seu sor ASN 1 ASN 1 COMSTACK Figure 1 1 YAZ layers There are four layers e A client or server application or both This layer includes ZOOM and the generic frontend server e The second layer provides a C represenation of the protocol units packages for Z39 50 ASN 1 ILL ASN 1 SRU The third layer encodes and decodes protocol data units to simple packages buffer with certain length The ODR module encodes and decodes BER whereas the HTTP modules encodes and decodes HTTP ruquests responses e The lowest layer is COMSTACK which exchanges the encoded packages with a peer process over a network The Z39 50 ASN 1 module represents the ASN 1 definition of the Z39 50 protocol It establishes a set of type and structure definitions with one structure for each of the top level PDUs and one structure or type for each of the contained ASN 1 types For primitive types or other types that are defined by the ASN 1 standard itself such as the EXT
209. tener For UNIX sockets the format of an address is the socket filename When a connection has been established you can use const char cs_addrstr COMSTACK h to retrieve the host name of the peer system The function returns a pointer to a static area which is overwritten on the next call to the function A fairly recent addition to the COMSTACK module is the utility function COMSTACK cs_create_host const char xstr int blocking void xvp which is just a wrapper for cs_create and cs_straddr The str is similar to that described for cs_straddr but with a prefix denoting the COMSTACK type Prefixes supported are tcp unix and ssl for TCP IP UNIX and SSL respectively If no prefix is given then TCP IP is used The blocking is passed to function cs_create The third parameter vp is a pointer to COMSTACK stack type specific values Parameter vp is reserved for future use Set it to NULL 9 7 SSL void cs_get_ssl COMSTACK cs Returns the SSL handle SSL for comstack If comstack is not of type SSL NULL is returned int cs_set_ssl_ctx COMSTACK cs void xctx Sets SSL context for comstack The parameter is expected to be of type SSL_CTX This function should be called just after comstack has been created before connect bind etc This function returns 1 for success O for failure int cs_set_ssl certificate file COMSTACK cs const char xfname Sets SS
210. termine which encoder should be used to serialize the data Note If your backend generates structured records it should use odr_malloc on the provided stream for allocating data This allows the frontend server to keep track of the record sizes The format field is mapped to an object identifier in the direct reference of the resulting EXTERNAL representation of the record Note The current version of YAZ only supports the direct reference mode int bend present void xhandle bend_present_rr rr typedef struct char setname x set name x int start int number x record number Odr_oid x format format transfer syntax OID x Z_Referenceld referenceld reference ID Z_RecordComposition comp Formatting instructions ODR stream encoding stream memory source if requir ODR print x printing stream x bend_request request bend_association association int hits number of hits x int errcode 0 0K x char xerrstring system error string or NULL x bend_present_rr The bend present handler is called when the server receives a 239 50 Present Request The setname start and number is the name of the result set start position and number of records to be retrieved respectively format and comp is the preferred transfer syntax and element specifications of the present request Note that this is handle
211. that instead of entering a long dot notation you can use a short name instead The name is your name for the OID class is the class and OID is the raw OID in dot notation Class is one appctx absyn attet transyn diagset recsyn resform accform extserv userinfo elemspec varset schema tagset general If you re in doubt use the general class register_tab command string This command registers a TAB completion string for the command glven sleep seconds This command makes YAZ client sleep be idle for the number of seconds given wait_response number This command makes YAZ client wait for a number of response packages from target If number is omitted is assumed This command is rarely used and is only useful 1f command set_auto_wait 1s set to off xmles OID doc Sends XML Extended Services request using the OID and doc given zversion ver This command sets 239 50 version for negotiation Should be used before open By default 3 version 3 is used options op1 op2 This command sets 239 50 options for negotiation Should be used before open The following options are supported search present delSet resourceReport tri ggerResourceCtrl resourceCtrl accessCtrl scan sort extendedServices level_1Segmentation level_2Segmentation concurrentOperations namedR esultSets encapsulation resultCount negotiationModel duplicationDet ection queryTypel04 pOESCorrection stringSchema YA
212. tion Version 3 only is used If none of the options are set no authentication parameters are set as part of the Initialize Request obviously When option async is 1 it really means that all network operations are postponed and queued until the function ZOOM_event is invoked When doing so it doesn t make sense to check for errors after ZOOM_connection_new is called since that operation connecting and init is still incomplete and the API cannot tell the outcome yet 3 1 2 SRU Solr Protocol behavior The HTTP based protocols SRU SRW Solr do not feature an Inititialize Request so the connection phase merely establishes a TCP IP connection with the HTTP server Most of the ZOOM connection options do not affect SRU Solr and they are ignored However future versions of YAZ might honor implement ationName and put that as part of User Agent header for HTTP requests The charset is used in the Content Type header of HTTP requests Setting authentcationMode specifies how authentication parameters are encoded for HTTP The de fault is basic where user and password are encoded by using HTTP basic authentication Option Description Default implementationName Name of Your client none user Authentication user name none group Authentication group name none password Authentication password none authenticationMode How authentication is encoded b
213. ucts derived from this software without specific prior written permission THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES INCLUDING BUT NOT LIMITED TO THE IMPLIED WAR RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT INDIRECT INCIDENTAL SPECIAL EXEMPLARY OR CONSEQUENTIAL DAMAGES INCLUD ING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE DATA OR PROFITS OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY WHETHER IN CONTRACT STRICT LIABILITY OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE SEE ALSO yaz client 1 yaz ztest 8 yaz config 8 zoomsh 1 bib1 attr 7 YAZ manual usr share doc yaz YAZ home page Z39 50 Maintenance Agency Page YAZ User s Guide and Reference 141 184 11 5 zoomsh zoomsh ZOOM shell Synopsis zoomsh a apdufile e v loglevel commands DESCRIPTION zoomsh is a ZOOM client with a simple command line interface The client demonstrates the ZOOM API and is useful for testing targets You may pass one or more commands to zoomsh These commands are invoked first OPTIONS a apdufile Logs protocol packages into apdufile APDU log e Makes zoomsh stop processin
214. ue A control field is encoded as element c concatenated with the tag value of the control field 1f the tag value matches the regular expression a zA Z0 9 x If the tag value do not match the regular expression a zA Z0 9 x the control field is encoded as element c and attribute code will hold the tag value This rule ensure that in the rare cases where a tag value might result in a non wellformed XML YAZ encode it as a coded attribute as in MARCXML The control field content is the the text value of this element Indicators are encoded as attribute names il i2 etc and corresponding values for each indicator A data field is encoded as element d concatenated with the tag value of the data field or using the attribute code as described in the rules for control fields The children of the data field element is subfield elements Each subfield element is encoded as s concatenated with the sub field code The text of the subfield element is the contents of the subfield Indicators are encoded as attributes for the data field element similar to the encoding for control fields 7 6 Retrieval Facility YAZ version 2 1 20 or later includes a Retrieval facility tool which allows a SRU Z39 50 to describe itself and perform record conversions The idea is the following An SRU Z39 50 client sends a retrieval request which includes a combination of the following parameters syntax format schema or element set name The retrieval facility is invo
215. ul for maintaining short lived constructions such as protocol PDUs If you want to retain a bit of memory beyond the next call to odr_reset you can use the function YAZ User s Guide and Reference 99 184 ODR_MEM odr_extract_mem ODR o This function will give you control of the memory recently allocated on the ODR stream The memory will live past calls to odr_reset until you call the function void odr_release_mem ODR_MEM p The opaque ODR_MEM handle has no other purpose than referencing the memory block for you until you want to release it You can use odr_extract_mem repeatedly between allocating data to retain individual control of separate chunks of data 8 2 3 Encoding and Decoding Data When encoding data the ODR stream will write the encoded octet string in an internal buffer To retrieve the data use the function char odr_getbuf ODR o int xlen int x size The integer pointed to by len is set to the length of the encoded data and a pointer to that data is returned xsize is set to the size of the buffer unless si ze is null signaling that you are not interested in the size The next call to a primitive function using the same ODR stream will overwrite the data unless a different buffer has been supplied using the call void odr_setbuf ODR o char buf int len int can grow which sets the encoding or decoding buffer used by o to buf using the length len Before
216. uld be one if you wish the association to operate in blocking mode zero otherwise The protocol field should be PROTO_Z3950 or PROTO_HTTP Protocol PROTO_SR is no longer supported void cs_close COMSTACK handle Closes the connection as elegantly as the lower layers will permit and releases the resources pointed to by the handle parameter The handle should not be referenced again after this call Note We really need a soft disconnect don t we 9 3 2 Data Exchange int cs put COMSTACK handle char xbuf int len Sends buf down the wire In blocking mode this function will return only when a full buffer has been written or an error has occurred In nonblocking mode it s possible that the function will be unable to send the full buffer at once which will be indicated by a return value of 1 The function will keep track of the number of octets already written you should call it repeatedly with the same values of buf and len until the buffer has been transmitted When a full buffer has been sent the function will return O for success 1 indicates an error condition see below int cs get COMSTACK handle char xxbuf int size Receives a PDU or HTTP Response from the peer Returns the number of bytes read In nonblocking mode it is possible that not all of the packet can be read at once In this case the function returns 1 To simplify the interface the function is responsible for managing the size of the buffe
217. ultset r Function ZOOM_connection_search creates a result set given a connection and query Destroy a result set by calling ZOOM_resultset_destroy Simple clients using PQF only may use the function ZOOM_connection_search_pqf in which case creating query objects is not necessary void ZOOM resultset option set ZOOM_resultset r const char x key const char x val const char ZOOM_resultset_option_get ZOOM_resultset r const char x key size_t ZOOM_resultset_size Z00M_resultset r Functions ZOOM_resultset_options_set and ZOOM resultset_get sets and gets an option for a result set similar to ZOOM_connection_option_get and ZOOM_connection_option_ set The number of hits also called result count is returned by function ZOOM_resultset_size For servers that support Search Info report the following options may be read using ZOOM_resultset_ get This detailed information is read after a successful search has completed This information is a list of of items where each item is information about a term or subquery All items in the list are prefixed by SearchResult no where no presents the item number O first 1 second Read searchresult size to determine the number of items 3 3 1 Z39 50 Result set Sort void ZOOM resultset sort ZOOM resultset r const char xsort_type const char xsort_spec int ZOOM _resultset_sortl1 ZOOM_resultset r const char sort_type const char sort_spec ZOOM_resultset_sort
218. ure Socket Layer support using GnuTLS If enabled YAZ uses HTTPS transport for SOAP or Se cure BER for Z39 50 Offers ZOOM C API implementing 739 50 SRU and Solr Web Service The YAZ library offers a set of useful utilities related to the protocols such as MARC 1502709 parser CCL 1808777 parser CQL parser memory management routines character set conversion Portable code YAZ compiles out of the box on most Unixes and on Windows using Microsoft Visual C Fast operation The C based BER encoders decoders as well as the server component of YAZ is very fast Liberal license that allows for commercial use of YAZ 1 1 Reading this Manual Most implementors only need to read a fraction of the material in this manual so a quick walkthrough of the chapters is in order Chapter 2 contains installation instructions for YAZ You don t need to read this if you expect to download YAZ binaries However the chapter contains information about how to make your application link with YAZ Chapter 3 describes the ZOOM API of YAZ This is definitely worth reading if you wish to develop a Z39 50 SRU client Chapter 4 describes the generic frontend server and explains how to develop server Z39 50 SRU applica tions for YAZ Obviously worth reading if you re to develop a server yaz client 1 describes how to use the YAZ Z39 50 client If you re a developer and wish to test your server or a server from another party you might fi
219. utions of source code must retain the above copyright notice this list of conditions and the following disclaimer e Redistributions in binary form must reproduce the above copyright notice this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution e Neither the name of Index Data nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission THIS SOFTWARE IS PROVIDED BY INDEX DATA AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MER CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY DIRECT INDIRECT INCIDENTAL SPECIAL EX EMPLARY OR CONSEQUENTIAL DAMAGES INCLUDING BUT NOT LIMITED TO PROCURE MENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE DATA OR PROFITS OR BUSI NESS INTERRUPTION HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY WHETHER IN CONTRACT STRICT LIABILITY OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARIS ING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE POSSIBIL ITY OF SUCH DAMAGE YAZ User s Guide and Reference 181 184 Appendix E About Index Data Index Data is a consulting and software development enterprise that specializes in library and information management systems Our interests and expertise span a broad range
220. ves as argument to the conversion step The following conversion elements are available casemap Converts case and rule specifies how l Lowercase using ICU function u_strToLower u Upper case using ICU function u_strToUpper t To title using UCU function u_strToTitle f Fold case using ICU function u_strFoldCase display This is a meta step which specifies that a term token is to be displayed This term is retrieved in an application using function icu_chain_token_display yaz icu h transform Specifies an ICU transform rule using a transliterator Identifier The rule attribute is the translit erator Identifier See CU Transforms for more information transliterate Specifies a rule based transliterator The rule attribute is the custom transformation rule to be used See ICU Transforms for more information tokenize Breaks tokenizes a string into components using ICU functions ubrk_open ubrk_setText The rule is one of l Line ICU UBRK LINE s Sentence ICU UBRK_SENTENCE w Word ICU UBRK_WORD c Character ICU UBRK_CHARACTER t Title ICU UBRK TITLE join Joins tokens into one string The rule attribute is the joining string which may be empty The join conversion element was added in YAZ 4 2 49 EXAMPLES The following command analyzes text in file text using ICU chain configuration chain xml Cac text yvaz icu e Cheb am The chain xml might look as follows lt icu_chain loc
221. vices handler x int bend_esrequest void handle bend esreguest rr x rr Jkr brief 239 50 delete result set handler x int bend_delete void handle bend delete rr rr xx brief 239 50 scan handler Ko int bend_scan void handle bend_scan_rr rr xx brief 739 50 segment facility handler int bend_segment void xhandle bend_segment_rr xrr xx brief SRU explain handler int bend_explain void handle bend_explain_rr xrr xx brief SRU scan handler x int bend_srw_scan void xhandle bend_scan_rr xrr xx brief SRU record update handler x int xbend_srw_ update void xhandle bend_update_rr xrr xx brief whether named result sets are supported 0 disable 1 enabl int named_result_sets bend_initrequest typedef struct bend_initresult int errcode 0 0K x char xerrstring system error string or NULL void x handle private handle to the backend module bend_initresult In general the server frontend expects that the bend result pointer that you return is valid at least until the next call to a bend_ function This applies to all of the functions described herein The parameter structure passed to you in the call belongs to the server frontend and you should not make assumptions about its contents after the current function call has completed In other words if you want to retain any of the contents of a reque
222. wasi wazo LOGEN size abate char prefix mx IE yaz log mask sti Const Char ssri yaz_log_module_level const char xname er Su int The reason for the whole log module is the yaz_1og function It takes a bitmask indicating the log levels a print f like format string and a variable number of arguments to log The log level is a bit mask that says on which level s the log entry should be made and optionally set some behaviour of the logging In the most simple cases it can be one of YLOG_FATAL YLOG_D EBUG YLOG_WARN YLOG_LOG Those can be combined with bits that modify the way the log entry is written YLOG_ERRNO YLOG_NOTIME YLOG_FLUSH Most of the rest of the bits are deprecated and should not be used Use the dynamic log levels instead Applications that use YAZ should not use the LOG_LOG for ordinary messages but should make use of the dynamic loglevel system This consists of two parts defining the loglevel and checking it To define the log levels the main program should pass a string to yaz_log_mask_str to define which log levels are to be logged This string should be a comma separated list of log level names and can contain both hard coded names and dynamic ones The log level calculation starts with YLOG_DEFAULT_LEVEL and adds a bit for each word it meets unless the word starts with a in which case it clears the bit If the string none is found all bit
223. we d use Default search delay 0 1 0 5 amp fetch delay 0 2 GFS CONFIGURATION AND VIRTUAL HOSTS The Virtual hosts mechanism allows a YAZ frontend server to support multiple backends A backend is selected on the basis of the TCP IP binding port listening adddress and or the virtual host A backend can be configured to execute in a particular working directory Or the YAZ frontend may perform CQL to RPN conversion thus allowing traditional Z39 50 backends to be offered as a SRW SRU service SRW SRU Explain information for a particular backend may also be specified For the HTTP protocol the virtual host is specified in the Host header For the 239 50 protocol the virtual host is specified as in the Initialize Request in the OtherInfo OID 1 2 840 10003 10 1000 81 1 Note Not all 239 50 clients allow the VHOST information to be set For those the selection of the backend must rely on the TCP IP information alone port and address The YAZ frontend server uses XML to describe the backend configurations Command line option f specifies filename of the XML configuration The configuration uses the root element yazgfs This element includes a list of Listen elements fol lowed by one or more server elements The Listen describes listener transport end point such as TCP IP Unix file socket or SSL server Con tent for a listener CDATA required The CDATA for the listen element holds the listener string such as tcp
224. y when a protocol package is decoded and turned into a complex of interlinked structures This section deals with this system and how you can use it for your own purposes The next section deals with the memory management which is required when encoding data to make sure that a large enough buffer is available to hold the fully encoded PDU The ODR module has its own memory management system which is used whenever memory is required Specifically it is used to allocate space for data when decoding incoming PDUs You can use the memory system for your own purposes by using the function void odr_malloc ODR o size_t size You can t use the normal free 2 routine to free memory allocated by this function and ODR doesn t provide a parallel function Instead you can call void odr_reset ODR o when you are done with the memory Everything allocated since the last call to odr_reset is released The odr_reset call is also required to clear up an error condition on a stream The function size_t odr_total ODR o returns the number of bytes allocated on the stream since the last call to odr_reset The memory subsystem of ODR is fairly efficient at allocating and releasing little bits of memory Rather than managing the individual small bits of space the system maintains a free list of larger chunks of memory which are handed out in small bits This scheme is generally known as a nibble memory system It is very usef
225. y a slash this it is not possible to specify a user with a slash in it v Makes yaz url dump each HTTP request response to stdout x proxy Specifies a proxy to be used for URL fetch SEE ALSO yaz 7 11 13 Bib 1 Attribute Set bib1 attr Bib 1 Attribute Set DESCRIPTION This reference entry lists the Bib 1 attribute set types and values TYPES The Bib 1 attribute defines six attribute types Use 1 Relation 2 Position 3 Structure 4 Truncation 5 and completeness 6 USE 1 ili Personal name 2 Corporate name 3 Conference name 4 Title 5 Title series 6 Wake Le oa J ISBN 8 ISSN 9 LC card number 0 BNB card number 1 BGF number 2 Local number Ls Dewey classification 14 UE ELL SMIC AEARON 3 BILL SSC LES Sal iesLCeue ion 6 LC call number 17 NIM call number 18 NAL call number LS MOS call number 20 Local classification 24 Sub ject heading 22 Sub ject Rameau 23 BDI index subject 24 INSPEC subject 29 MESH subject 26 PA subject 2 LC subject heading 28 RVM subject heading 29 Local subject index 30 Date Sal Date of publication 32 Date of acquisition 33 Title key 34 riele collective 55 mieke paria 36 Title cover Si Title added title pag 38 Tie LO G eyore Lora Sg Tac Lema 40 Title spine 41 Title other variant 42 Re ROME 43 Title abbreviated 44 Title expanded 45 Subject precis 46 Subject rswk
226. ying success without any further processing If the optional is zero an internal error flag is set in the ODR stream and the function will return 0 No further operations can be carried out on the stream without a call to the function odr_reset If xp is not a null pointer 1t is expected to point to an instance of the data type The data will be subjected to the encoding rules and the result will be placed in the buffer held by the ODR stream The other ASN 1 primitives have similar functions that operate in similar manners 8 3 1 2 BOOLEAN int odr_bool ODR o Odr_bool xxp int optional const char name 8 3 1 3 REAL Not defined 8 3 1 4 NULL int odr_null ODR o Odr_null xxp int optional const char name In this case the value of p is not important If xp is different from the null pointer the null value is present otherwise it s absent 8 3 1 5 OCTET STRING typedef struct odr_oct unsigned char xbuf int len Od OCT int odr_octetstring ODR o Odr_oct p int optional const char xname The buf field should point to the character array that holds the octetstring The len field holds the actual length The character array need not be null terminated To make things a little easier an alternative is given for string types that are not expected to contain embed ded NULL characters eg VisibleString int odr_cstring ODR o char p int optional const char xname Which encode
227. ze defaults to 1GB Setting it to zero will disable the rotation feature A typical yaz log looks like this 1335238 141223141 Wewowicesic 1 session Srarcing Session rrom coos l2 0 0 1 2 pid 30968 133233 LABS lil vera reste 1 Ivecuest tmir Treo de Bil ver 2 028 gt OK 135235 17 23 11_yaz zrest 1 request Search Z attrset Bib 1 foo OK 7 hits 133238 2023 11 Ver rtest 1 request Present 1 2 2 OK 2 records returned 13249 1323 11 er rest request Closs Ox The log entries start with a time stamp This can be omitted by setting the YLOG_NOTIME bit in the loglevel This way automatic tests can be hoped to produce identical log files that are easy to diff The format of the time stamp can be set with yaz log time format which takes a format string just like strftime Next in a log line comes the prefix often the name of the program For yaz based servers it can also contain the session number Then comes one or more logbits in square brackets depending on the logging level set by yaz log init level and the loglevel passed to yaz_log_init_level Finally comes the format string and additional values passed to yaz_log The log level YLOG_LOGLVL enabled by the string loglevel will log all the log level affecting opera tions This can come in handy if you need to know what other log levels would be useful Grep the logfile for loglevel The log system is

YAZ User's Guide and Reference

Contents

Download Pdf Manuals

Related Search

Related Contents