Tekniikka Hakuohjelmat (tekniikka) Kun palvelu (aineisto) ei tue Z39.50-hakuja, mutta tarjoaa vaihtoehtoisen hakurajapinnan tai sopivan Web-hakuliittymän, saadaan WEBCONFIG-hakuja parempi tuki Nelli-hauille tekemällä ns. hakuohjelma. Hakuohjelma voi sovittaa MetaLibin hakusyntaksin tarkemmin palvelun käyttämään hakusyntaksiin, jolloin tiettyihin kenttiin kohdennetut haut toimivat pelkän sanahaun sijaan. Hakuohjelmalla voidaan myös näyttää hakutulokset Nellissä natiiviliittymään siirtymisen sijaan. Tavalliset hakuohjelmat hakevat tekstimuotoista dataa HTTP-protokollan yli, joten ohjelmien tekeminen ei yleensä ole erittäin haastavaa. MetaLib-haun sovittaminen palvelun hakusyntaksiin ja tulosten konvertointi MetaLibin viitemuotoon on yleensä vaikein tehtävä. Ohjelmat voidaan tehdä millä tahansa kielellä, kunhan ne on ajettavissa Nellin ympäristössä (Perl, Python, C/C++, Java, COBOL?). Käytännössä kaikki hakuohjelmat tehdään tekstimuotoisen datan käsittelyyn kätevimmällä Perl-kielellä, mikä on Ex Libriksen suositus. Toiminta MetaLib Resource Management Guide -manuaalista löytyy virallinen dokumentaatio, joka kannattaa lukea ensin. Tässä esitetyt asiat (omat havainnot ja kokemukset) ovat epävirallista lisädokumentaatiota. Hakuohjelma lukee MetaLibin syöttämät ohjaustiedot stdin-striimistä ja ohjelma tulostaa tulokset stdout-striimiin. Ohjelma tekee MetaLibin syntaksista sovitetun haun ja odottaa saavansa tulosten määrän. Jos tuloksia löytyy, voidaan ne hakea ja muuttaa MetaLibin viitteiksi. Toiminta voidaan jakaa kolmeen eri osaan, joista ensimmäinen on aina toteutettava. 3. find - Tulosten määrän selvittäminen present - Tulosten muuttaminen MetaLibin viitemuotoon present_single - Yksittäisen viitteen tarkentaminen Palvelun hakuliittymän toiminta lopulta rajaa toteutettavat osat. Jos vain find-toiminto toteutetaan, on ohjelman tulostettava linkki, jolla pääsee suoraan hakutuloksiin ( search and link -tyyppinen aineisto, jolla on EXTERNAL_JUMP-konfiguraatio). Tavallisesti sekä find- että present -toiminnot toteutetaan. Hakuohjelma jaetaan tyypillisesti toimintojen mukaan itsenäisesti ajettaviin ohjelmatiedostoihin ja konfiguraatiotiedoston ( EXTERNAL-tyyppi) General-välilehdellä määritelläänkin Find Module ja Present Module. Vain harvoin voidaan yksittäisiä viitteitä tarkentaa pr esent_single-toiminnolla. Syötteet ja tulosteet Ohjelmien syötteet (ja tulosteet) ovat erilaisia toimintojen mukaan. find saa syötteensä vain MetaLibilta ja se sisältää hakupyynnön lisäksi erinäisiä konfigurointitietoja. present saa MetaLibilta vain konfigurointitietoja ja on riippuvainen find-toiminnon tulostamasta vapaamuotoisesta FIND- REQUEST-parametrista, jonka avulla on voitava hakea tuloksia. present_single ei saa MetaLibilta lainkaan parametreja ja present-toiminnon on huolehdittava kaiken tarpeellisen tiedon välityksestä. MetaLib syöttää ja lukee tiedot muodossa <AVAIN>=<ARVO><RIVINVAIHTO> (ilman hakasulkeita). Seuraavassa taulukossa on find- ( F) ja present ( P) -toimintojen saamat syötteet MetaLibin versiossa 4.2 SP = saa syötteen, = ei saa syötettä. Lihavoidut syötteet ovat virallisen dokumentaation mukaiset syötteet ja kaikki muut voivat muuttua päivitysten myötä. INPUT F P Selitys AUTHEN-ADDRESS AUTHEN-MODULE BASE tyhjä - ExL sisäinen (separate program name of an authentication program) tyhjä - ExL sisäinen (separate program name of an authentication program) Konfiguraatiokoodi, esim. L_ DATABASE
COOKIE-JAR Kts. pidempi selitys alla FIND-REQUEST Hakusyntaksi, linkki find ja present välillä FORMAT MAX-RECORD METALIB-USERNAME PROXY-ADDRESS PROXY-CREDENTIALS tyhjä - ExL sisäinen (konf. External Record Format?) MetaLib haluaa enintään tämän verran viitteitä ( aina 0 00010) Käyttäjän yksilöivä tunniste, esim. PATRON12345, GUEST 12345 Hakuproxyn osoite, jos Use search proxy server on asetettu Hakuproxyn tunnukset, jos U se search proxy server on asetettu PROXY-TYPE Hakuproxyn tyyppi ( SQUID, EZPROXY tai WAM) jos Use search proxy server on asetettu SEARCH-ADDRESS SEARCH-AUTHENTICATION SEARCH-DATABASE SESSION-QUOTA SET-ENTRY SET-NUMBER Host name:port-kenttä Auth entication-kenttä Data base Code -kenttä Num ber of Sessions -kenttä MetaLib haluaa viitteitä tästä numerosta alkaen, esim. 00 0001 Tuki hakuseteille, oletusarvo 000000 OUTPUT F P Selitys COOKIE-JAR ERROR ERROR-CODE Kts. pidempi selitys alla Virheen sattuessa virheteksti Nelinumeroinen virhekoodi, jonka avulla saadaan vakioviesti V-liittymään. Koodit./tab /www_heading.lng tiedostossa FIND-REQUEST Pakollinen - Linkki find, pr esent ja present_single välillä ( present: kts. prese nt_single alla) SET-NUMBER Tuki hakuseteille SET-RESULT Pakollinen - Tulosten märä. Viitteet tulostetaan kaikkien muiden tulosteiden jälkeen.
Viiteformaatti RECORD-FORMAT="PLAIN" RECORD <koodi, enintään 5 merkkiä> $$<osakentän koodi, oletus a> 100## $$asmith, John 856## $$uhttp://www.example.com/ $$yexample... END-RECORD RECORD... END-RECORD... END-OF-DATA COOKIE-JAR parametri on alkanut toimimaan omien EXTERNAL-hakuohjelmien kanssa vasta jonkun MetaLib 4 servicepackin jälkeen. Ohjelma saa sen syötteenä ja voi tulostaa sille uuden arvon. Arvo on käyttäjäkohtainen eikä riipu istunnosta - uloskirjautuminen, selaimen sulkeminen ja uusi kirjautuminen ei tyhjennä arvoa, vaan se tyhjenee itsestään tuntemattoman timeoutin jälkeen (enintään puoli tuntia). Erityisesti on huomattava, että arvo ei ole sidottu konfiguraatiokoodiin ja ka ikki hakuohjelmat jakavat saman arvon. Tämä ja metahaku ikävä kyllä rajaa käytön seuraavasti: Toinen hakuohjelma voi muuttaa arvon "yllättäen", esimerkiksi kun metahaussa haetaan lisää viitteitä. Arvoon on pakko koodata tunniste, jonka avulla present-ohjelma voi tietää, että arvo tulee vielä samalta hakuohjelmalta. Kertakäyttöinen linkki ohjelmien välillä ( find- present, present- present), istuntoja ei voi säilyttää. Arvo on tulostettava aina, jos sitä ylipäätään haluaa käyttää. find 3. 4. 5. Muunna MetaLibin hakusyntaksi ( FIND-REQUEST) natiiviliittymän hakusyntaksiin Tee haku natiiviliittymästä Parsi tulosten määrä Tulosta tulosten määrä ( SET-RESULT) ym. ja jos tuloksia > 0, tulosta tarvittavat tiedot prese nt-ohjelmalle ( FIND-REQUEST - arvona olevan merkkijonon maksimipituus on 2000 merkkiä) Parsi ja tulosta viitteitä (vapaaehtoinen) Alkaen MetaLib Version 3.13, Service Pack 168 hakuohjelma voi myös suoraan tulostaa viitteitä, jos niitä on mukana haun vastauksessa. Näin vältytään turhilta present-ohjelman hauilta ja kuormitus vähenee sekä MetaLibissa että haun kohteena olevassa palvelussa. Nopeuden takaamiseksi find-ohjelman ei tule hakea enempää viitteitä, kuin mitä vastaus sisältää. Koska technically, there isn't any limit for the number of records fetched kannattaa haun aikana pyytää mahdollisimman paljon viitteitä (tosin muutama sata riittänee mainiosti). present Tee FIND-REQUEST-parametrin avulla hakupyyntö natiiviliittymään Parsi ja tulosta viitteitä Näyttöohjelman tehtävänä on tarjoilla ne viitteet, mitä MetaLib haluaa. MetaLib haluaa viitteitä SETnumerosta alkaen enintään MAX-RECORD kappaletta ja jos käytössä on hakusetit, setistä ENTRY numero SET-NUMBER. Käytännössä MetaLib haluaa aina viitteitä enintään 10 kappaletta ja sivutus rajaa viitteiden alut aina 10n+1, missä n=0, 1, 2,... Riippuen sivutuksen asetuksista MetaLib kutsuu näyttöohjelmaa peräkkäin niin monta kertaa, että se saa tarvittavan määrän viitteitä. Jos
yhdellä sivulla näytetään kolmekymmentä viitettä, haetaan viitteitä 3 kertaa 10 kappaleen erissä (tai kunnes viimeinen viite on saatu). On huomattava, että kaikki tulostetut viitteet menevät MetaLibin omaan välivarastoon ja jo tulostettuja viitteitä ei haeta uudelleen (ehkä?). Lisäksi käyttäjän hypätessä viitteiden yli ( Siirry) jättää myös MetaLib hypätyn välin viitteet noutamatta. Esimerkiksi jos tuloksia on 85 kappaletta ja 30 ensimmäistä on noudettu, käyttäjän hypätessä viimeiseen viitteeseen pyytää MetaLib viitteitä alkaen viitteestä 81, jättäen 31-80 noutamatta. Kun käyttäjä siirtyy edelliselle sivulle, haetaan viitteitä alkaen numerosta 81-3*10 = 51, kolme kertaa viitteeseen 80 asti (huom. sivutuksen ollessa 30 viitettä / sivu). Kun käyttäjä selaa viitteitä Koko tietue -näytössä, hakee MetaLib tarvittaessa vain 10 ( MAX- RECORD) viitettä. present_single Tee present-ohjelman asettaman parametrin mukaan hakupyyntö natiiviliittymään Parsi ja tulosta yksittäinen viite Yksittäisen viitteen näyttöohjelmaa kutsutaan, kun käyttäjä katsoo koko tietuetta tai klikkaa SFX- painiketta. Ohjelman tehtävänä on täydentää present-ohjelman tulostamaa viitettä - jo tulostettuja kenttiä ei pidä tulostaa uudelleen. Tarkemmin ottaen present_single voi olla jopa viitekohtainen ohjelma, koska present_single aktivoidaan vain jos present-ohjelma on tulostanut kyseiseen viitteeseen erikoisen MORE-kentän. MO RE-kentän osakenttä a määrää ajettavan ohjelman (joka voi vaikka vaihdella viitekohtaisesti) ja osakentällä b annetaan ohjelmalle stdin kautta syöte. Kaikissa viitteissä ei tarvitse olla MORE-kenttää. Ohjelman nimen perässä (osakenttä a) ei voi olla argumentteja. Osakenttä b on tavallisesti ja ohjeiden mukaan FIND-REQUEST=jokuarvo, mutta mikä tahansa yhden rivin merkkijono kelpaa ja se syötetään sellaisenaan present_single- ohjelmalle. Kaikki ohjelman syötteet tulevat osakentästä b, MetaLib ei anna mitään muita syötteitä, kuten esimerkiksi proxyn tietoja. MORE-kentän arvon maksimipituus on 1500-merkkiä (eli rivin maksimipituus on 1505 jos 'MOR E '-osa lasketaan mukaan). Toteutuksesta Omat hakuohjelmat laitetaan instanssin hakemistossa olevaan vir_ext-hakemistoon ja niille annetaan ug+x suoritusoikeudet. Konfiguroitaessa Find Module ja Present Module -kenttiin laitetaan ohjelmien nimen eteen instanssin hakemiston nimi ja kenoviiva ( xxxxx/database_find.pl). Tämä edellyttää, että MetaLibin virallisessa hakuohjelmien hakemistossa on linkki oman instanssin vi r_ext-hakemistoon (Nelli-toimisto tekee linkin). Samalla tavalla löytyy present_single-ohjelma: MORE $$axxxxx/database_present_single.pl$$bfind-request=... palvelun kuormituksen minimointi temp-hakemisto(t) debug Ympäristömuuttuja aleph_ext TMPDIR VIR_EXT_DEBUG Selitys Hakuohjelmien hakemisto temp-hakemisto.../jotain/tmp MetaLibin debug flag true/false EXTERNAL_TIMEOUT Pyynnön aikaraja sekunneissa ( LWP timeout) ML_VERSION MetaLibin versio, esim. 4 - jos jokin ominaisuus vaatii tietyn version, voidaan näitä käyttää ML_REVISION Revisio, esim. 2 ML_SERVICE_PACK SP, esim. 1 ML_SERVICE_PACK_ITEM SP... esim. 383 Jos teet hakuohjelman MetaLibin asennuksen mukana tulleella perlillä, laita shebang riviksi #!/usr/bin/env perl - näin ohjelma ei ole sidottu tiettyyn asennushakemistoon.
Virhetilanteet Ohjelmalla ei ole (paljon) aikaa odottaa ulkoisia resursseja ja virhetilanteita tulee joskus eteen. Ohjelman tulisi loppua hallitusti ja tulostaa stdout-striimiin virheteksti ( ERROR=Unknown error! ) ja /tai virhekoodi ( ERROR-CODE=0216) - MetaLib käyttää vain viimeisenä tulostetun arvon. Koodeissa on etuna käännetyt virheviestit (./tab/www_heading.lng). Muun muassa seuraavia koodeja käytetään: ERROR-CODE ERROR 0001 General communication error 0002 Target server not responding 0206 Cannot parse XML result 0209 The database does not support this search attribute 0210 Cannot create find request 0211 Failed to connect to host 0213 Failed to retrieve number-of-hits 0216 Internal error (parser program cannot run in current mode) 0219 Failed to establish session. Muitakin koodeja on käytössä, mutta koodien käyttö on rajattu (mitä tahansa www_heading- tiedostosta löytyvää koodia ei voi käyttää, sillä ne näkyvät <koodi> Missing line -ilmoituksena... missä nämä koodit on määritelty?). Virheviesti näkyy asiakasliittymässä vain hetken aikaa, kunnes MetaLib lataa sivun, jossa kerrotaan haun epäonnistumisesta. Virheviestin voi nähdä myös klikkaamalla Monihaussa Näytä tulokset aineistoittain. Search Katso myös: Tekniikka Kirjastotietokantojen konfigurointi Hakuohjelmat (eksternaalit)