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.

1. find - Tulosten määrän selvittäminen
2. present - Tulosten muuttaminen MetaLibin viitemuotoon
3. 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 present_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 SP1. = 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			tyhjä - ExL sisäinen (separate program name of an authentication program)
AUTHEN-MODULE			tyhjä - ExL sisäinen (separate program name of an authentication program)
BASE			Konfiguraatiokoodi, esim. L_DATABASE
COOKIE-JAR			Kts. pidempi selitys alla
FIND-REQUEST			Hakusyntaksi, linkki find ja present välillä
FORMAT			tyhjä - ExL sisäinen (konf. External Record Format?)
MAX-RECORD			MetaLib haluaa enintään tämän verran viitteitä (aina 000010)
METALIB-USERNAME			Käyttäjän yksilöivä tunniste, esim. PATRON12345, GUEST12345
PROXY-ADDRESS			Hakuproxyn osoite, jos Use search proxy server on asetettu
PROXY-CREDENTIALS			Hakuproxyn tunnukset, jos Use search proxy server on asetettu
PROXY-TYPE			Hakuproxyn tyyppi (SQUID, EZPROXY tai WAM) jos Use search proxy server on asetettu
SEARCH-ADDRESS			Subscription-välilehden Hostname:Port-kenttä
SEARCH-AUTHENTICATION			Subscription-välilehden Authentication-kenttä
SEARCH-DATABASE			Subscription-välilehden Database Code -kenttä
SESSION-QUOTA			Subscription-välilehden Number of Sessions -kenttä
SET-ENTRY			MetaLib haluaa viitteitä tästä numerosta alkaen, esim. 000001
SET-NUMBER			Tuki hakuseteille, oletusarvo 000000

OUTPUT	F	P	Selitys
COOKIE-JAR			Kts. pidempi selitys alla
ERROR			Virheen sattuessa virheteksti
ERROR-CODE			Nelinumeroinen virhekoodi, jonka avulla saadaan vakioviesti V-liittymään. Koodit ./tab/www_heading.lng tiedostossa
FIND-REQUEST			Pakollinen - Linkki find, present ja present_single välillä (present: kts. present_single alla)
SET-NUMBER			Tuki hakuseteille
SET-RESULT			Pakollinen - Tulosten märä.

Viitteet tulostetaan kaikkien muiden tulosteiden jälkeen.

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 kaikki 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

1. Muunna MetaLibin hakusyntaksi (FIND-REQUEST) natiiviliittymän hakusyntaksiin
2. Tee haku natiiviliittymästä
3. Parsi tulosten määrä
4. Tulosta tulosten määrä (SET-RESULT) ym. ja jos tuloksia > 0, tulosta tarvittavat tiedot present-ohjelmalle (FIND-REQUEST - arvona olevan merkkijonon maksimipituus on 2000 merkkiä)
5. 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

1. Tee FIND-REQUEST-parametrin avulla hakupyyntö natiiviliittymään
2. Parsi ja tulosta viitteitä

Näyttöohjelman tehtävänä on tarjoilla ne viitteet, mitä MetaLib haluaa. MetaLib haluaa viitteitä SET-ENTRY numerosta alkaen enintään MAX-RECORD kappaletta ja jos käytössä on hakusetit, setistä 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

1. Tee present-ohjelman asettaman parametrin mukaan hakupyyntö natiiviliittymään
2. 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. MORE-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 'MORE '-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 vir_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

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:

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.

Katso myös: