10. Meta informatie in Brocade

10.1. Inleiding

10.1.1. Wat is meta informatie ?

In Brocade wordt het gedrag van alle toepassingen en objecten beschreven en gestuurd door middel van meta informatie. Het is precies deze meta informatie (of parametrisering) die er voor zorgt dat Brocade, met een zelfde software, op heel diverse manieren kan worden opgezet en zich ook op heel verschillende manieren tot de gebruiker komt.

Meta informatie is verantwoordelijk voor het grootste gedeelte van de Brocade programmatuur.

10.1.2. Meta informatie nieuwe stijl

De meeste software die deze meta informatie beheert, zijn afzonderlijke web toepassingen. Typisch worden deze gevormd door 5 bestanden:

m-file
Deze beschrijft de logica achter de toepassing
x-file
Deze verzorgt de schermopbouw (HTML)
l-file
Deze levert de bijhorende teksten aan
d-file
Deze definieert de macro’s waarmee deze meta informatie kan worden gebruikt.
b-file
Deze definieert relevante menu ingangen en history/search/lookup objecten

Na het tot stand komen van drie software pakketten:

  • namespaces
  • templates
  • keyvalue stores

werd een nieuwe aanpak mogelijk. De meta informatie wordt nu beschreven door 2 soorten bestanden aan te passen:

  • b-file
  • l-file

10.1.3. Voordelen van deze nieuwe aanpak

Deze aanpak heeft nogal wat directe voordelen:

  • De tijd nodig om een meta object te definiëren wordt drastisch gereduceerd.
  • Er is geen code meer nodig. Dit betekent ook dat het onderhoudswerk in belangrijke mate vermindert.
  • Aanpassingen gebeuren nu aan de centrale software. Dit betekent nog dat elke aanpassing onmiddellijk effect heeft op alle meta objecten nieuwe stijl. Het is dan ook te denken dat de graad van afwerking belangrijk hoger gaat liggen.
  • De scherm layout is uniform, sober en functioneel. Het feit dat er nu ook contextgevoelige informatie kan worden getoond heeft ook als effect dat de veld labels beknopter kunnen zijn. Samen met het feit dat gebruiksinformatie op vraag en in context gebeurt zorgt ervoor dat de schermen strakker zijn.
  • Documentatie kan nu ook centraal (dit document!)

Er is echter ook een indirect voordeel: meta informatie nieuwe stijl laat introspectie toe. Dit wil zeggen dat er instrumenten kunnen worden ontwikkeld die gebaseerd zijn op kennis omtrent de meta informatie. Sommige van deze instrumenten liggen voor de hand: invulschermen, opvragen van attributen, omvorming van de gegevens naar populaire formaten (CSV, JSON, python). Andere zijn eerder gespecialiseerd: rapporteringssoftware bijvoorbeeld.

10.2. Terminologie

Type
Het type staat voor dat waarover we meta informatie willen definiëren. Voorbeelden hiervan zijn catalografische systemen, eindgebruikersklassen e.d. Types worden gekenmerkt door een identifier. Deze identifier is van de gedaante [a-z][a-z0-9]*. Deze identifier dient goed gekozen te worden: deze gaat voortdurend (als literal) voorkomen in software. Goede keuzes zijn catsys (catalografische systemen), eusys (eindgebruikerssystemen).
Cg
cg staat voor de concretisering van een type. De concretisering wordt eveneens gekenmerkt door een identifier. Deze identifier is van de gedaante [A-Za-z][A-Za-z0-9_]*. Voorbeelden van concretisering zijn lvd voor catalografische systemen en UA voor eindgebruikerssystemen. Je kan in een b-file de concretisering aanspreken m.b.v. de parameter RDcg.
Attribuut
Een attribuut staat voor een bepaalde eigenschap van een concretisering van een gegeven type. De voorkomende attributen worden steeds per type gespecificeerd, hun specifieke waarden worden per concretisering ingevuld. Opnieuw worden attributen geassocieerd met een identifier. Deze heeft als structuur: [a-z][a-z0-9]*.
Waarde
attributen nemen bij een gegeven concretisering van een type een bepaalde waarde aan. Dit is de meta informatie die ons interesseert. Dergelijke waarde kan verschillende vormen aannemen: strings, getallen, lois, arrays. De structuur van de waarden van attributen worden vastgelegd in het type. Als een waarde niet werd ingevuld bij een attribuut, dan wordt steeds de waarde van een lege string verondersteld.

Waarschuwing

Meta informatie werkt met default constructies. Deze zijn gebaseerd op de syntax afspraken rond de voorgestelde identifiers. Afwijken van deze afspraken kan er voor zorgen dat de software slecht functioneert.

Deze syntax restricties lijken zwaar maar deze werden gekozen met een reden: de constructies die op deze wijze mogelijk zijn, zijn in praktische elke programmeertaal geldige identifiers. Ook kunnen ze worden gebruikt als element naam, attribuutnaam en id attribuut in XML en dit zonder enige verdere processing. De praktijk wijst bovendien uit dat met deze restricties best te leven valt.

10.3. Attributen

Het zijn de attributen die de kern uitmaken van de meta informatie.

We kunnen de verzameling attributen bij een gegeven type op verschillende manieren beschrijven.

10.3.1. Gewone attributen versus type attributen

Type attributen worden gedefinieerd ter hoogte van het type en hebben een gemeenschappelijk waarde voor alle concretiseringen. Gewone attributen zijn specifiek voor een concretisering.

Type attributen zijn steeds standaard attributen.

10.3.2. Standaard attributen versus niet-standaard attributen

Er is een collectie van attributen die bij elk type voorkomen: de standaard attributen. De namen van deze attributen mogen NIET worden gegeven aan andere (niet-standaard) attributen.

ad
Datum ($H-formaat) van de laatste aanpassing van de concretisering
ap
Brocade userid die de laatste aanpassing aan de concretisering doorvoerde.
at
Type attribuut: booleaanse waarde die aangeeft of er een audit trail wordt bijgehouden voor veranderingen aan concretisering. Deze waarde kan negatief worden ‘overruled’ door de registry waarde system-at. M.a.w. is at True, dan wordt de registry waarde gehanteerd, is at False, dan blijft at False.
autoid
Staat deze waarde op 1, dan worden de identifiers automatisch gegenereerd (een teller met increment 1)
cancreate
Type attribuut: toegangsslot (ak-loi) dat aangeeft wie een nieuwe concretisering mag aanmaken.
canfreeze
Type attribuut: toegangsslot (ak-loi) dat aangeeft wie een concretisering mag bevriezen (onveranderbaar maken)
canread
Type attribuut: toegangsslot (ak-loi) dat aangeeft wie een concretisering mag bekijken
canwrite
Type attribuut: toegangsslot (ak-loi) dat aangeeft wie een concretisering mag aanpassen
cd
Datum ($H-formaat) van de aanmaak van de concretisering
cp
Brocade userid van de persoon die de concretisering aanmaakte.
doc
Dit veld is optioneel. Het kan de naam bevatten van een reST (restructuredtext) document dat dan weer op het web moet terug te vinden zin in /doc/” + doc + “/html/” + doc + ”.html”
errortoofew
(Zie standaard test-mechanisme voor waarden van attributen) Dit is een template om een fout te melden indien er te weinig waarden bij dit attribuut werden gedefinieerd. Default is dit $saytype: $.errortoofew. $saytype is de verwoording van het type.
errortoomany
(Zie standaard test-mechanisme voor waarden van attributen) Dit is een template om een fout te melden indien er te veel waarden bij dit attribuut werden gedefinieerd. Default is dit $saytype: $.errortoomany. $saytype is de verwoording van het type.
errorunacceptedcg
(Zie standaard test-mechanisme voor waarden van attributen) Dit is een template om een fout te melden indien er waarden bij dit attribuut zijn die weliswaar correct zijn maar toch niet toegelaten worden (bijvoorbeeld: het attribuut is weliswaar een geldige taalcode, maar enkel de talen ‘N’ en ‘F” mogen worden gebruikt. Default is dit $saytype: $.errorunacceptedcg. $saytype is de verwoording van het type.
errorwrongcg
(Zie standaard test-mechanisme voor waarden van attributen) Dit is een template om een fout te melden indien er waarden bij dit attribuut zijn die ongeldig zijn. Default is dit $saytype: $.errorwrongcg. $saytype is de verwoording van het type.
expcsv
Type attribuut. Referentie naar de plaats waar een CSV bestand staat met de meta informatie van alle concretiseringen.
expjs
Type attribuut. Referentie naar de plaats waar een JSON bestand staat met de meta informatie van alle concretiseringen.
exppy
Type attribuut. Referentie naar de plaats waar een python bestand staat met de meta informatie van alle concretiseringen.
extraheader
Brocade template die in het corresponderende search object een extra info veld toont. In het corresponderende search object moet dan wel plaats worden voorzien voor dit veld.
extraheaderkeygen
M routine die werkt met de waarde RDmtloi en de array RAkeys genereert. Deze waarden kunnen als sleutels in extraheader worden gebruikt.
fd
Datum ($H-formaat) van de laatste bevriezing van de concretisering
fp
Brocade userid die de laatste bevriezing van de concretisering doorvoerde.
idfree
Staat deze waarde op 1, dan kan de identifier bij een concretisering ook andere karakters dan nummers, hoofletters en kleine letters bevatten. De beste praktijk is echter dat een identifier begint met een kleine letter an dan eventueel wordt gevolgd door andere kleine letters en nummers.
jshead
Dit is een string met Javascript code. Deze code wordt geplaatst in een <SCRIPT> tag, onderdeel van het <HEAD> element van het web formulier.
lgscope
Staat deze waarde op 1, dan wordt de scope in alle talen gevraagd
nmspace
Type attribuut. Bevat de namespace van alle verwoordingen in verband met de type definitie. De waarde van dit attribute bestaat standaard uit de prefix meta en de identifier van het attribuut waarbij de eerste letter in hoofdletter staat. Voorbeeld: alle concretiseringen van het type catsys hebben als namespace attribuut de waarde metaCatsys.
reportgen

Dit is een M exec en werkt met 1 waarde: RDmtloi (de loi van het stuk meta informatie). Deze executable genereert een array RAport. Deze array is numeriek. Op elk niveau zijn er 2 subscripts: template, keys. De template wordt getoond met sleutels uit keys.

Als je een typeaction gebruikt waar je data wilt tonen, wordt er ook gebruik gemaakt van reportgen om een mumps routine op te roepen. In deze routine vul je RAport(var,”template”) en RAport(var,”keys”) in per typeaction die je wilt sturen. vb:

1
2
3
$attribute: reportgen
  $$content: _system
  $$value: d %Rep^gusersid(.RAport,RDmtloi)

In M kan dit er dan uitzien als:

def %Rep(PAport, PDmtloi):
n x
i $g(FDact("typeactionshowaccesslocks"))=1 d
. d shwALoc(PDmtloi) ;vult PAport(key,"template")=value_"<br>" en PAport(key,"keys") in
. q
i $g(FDact("typeactionshowtrainees"))=1 d
. d shwGChi(PDmtloi)
. q
q

Deze getoonde data kan je dan onderaan de pagina in de Report rubriek bekijken.

searchfilter
Dit is een Brocade template die wordt gebruikt in het filter mechanisme in het geassocieerde search object. Bij elke concretisering wordt de template berekend en het resultaat wordt toegevoegd aan de corresponderende lijn in het search object. De zoekstring wordt dan gezocht in het gecombineerde resultaat. De sleutels die worden gebruikt bij de template komen uit de meta informatie van de betreffende mt-loi: elke sleutel komt overeen met een attribuut. De waarde van de sleutel is dan ook de waarde van het corresponderende attribuut. Deze waarde kan echter meervoudig zijn: in dat geval wordt de waarde beschouwd als een MJSON structuur die wordt omgezet naar een string.
set
Type attribuut. Bevat de set waarin alle attributen worden gedefinieerd. De waarde van dit attribuut is steeds dezelfde waarde als bij namespace. Voorbeeld: alle concretiseringen van het type catsys hebben als set attribuut de waarde metaCatsys.
sideeffect

Type attribuut. Dit is een M executable string die werkt met 2 standaardvariabelen RDtype (type) en RDcg (concretisering). Is deze string verschillend van leeg, dan wordt deze uitgevoerd als allerlaatste stap van het updatingsproces.

1
2
3
$attribute: sideeffect // M instructie die wordt uitgevoerd na het filen. RDtype is het type, RDcg is de concretisering»
    $$content: _system
    $$value: k ^KWKS("wks",RDcg) d %BarcIdx^guwks(RDcg)

In sideeffect wordt ook geschreven wat er extra moet gebeuren als een instance verwijderd wordt. getMeta van de instance is leeg, maar getMetaExtra wordt nadien pas leeggemaakt. Zo kan je oude en nieuwe waarden (van eventueel andere globals) vergelijken en leeg maken. Dit is bijvoorbeeld handig om indexen leeg te maken.

skiplanguages
Indien deze de waarde ‘1’ heeft, dan worden er geen vertalingen gevraagd van de identifiers. Deze fungeren dan eerder als eigennaam in plaats van soortnaam.
test
Type attribuut. Overall M routine die test op een concretisering: gegeven RDmtloi (LOI concretisering) en CAkvsinp(content,attribuut,volgnr) (array met alle inputwaarden), RDerror wordt gegenereerd. Is deze waarde leeg, dan is er geen fout. In het andere geval is dit een foutboodschap (wordt door de sayText macro passend omgezet)
1
2
3
$attribute: test // test op de ganse structuur: leeg: test lukt; anders: type..overallTestError
    $$content: _system
    $$value: d %TstSide^gusersid(RDmtloi,.CAkvsinp)
tp
Type attribuut: booleaanse waarde die aangeeft of er aan transactie processing wordt gedaan bij het wegschrijven van veranderingen aan concretiseringen. Deze waarde kan negatief worden ‘overruled’ door de registry waarde system-tp. M.a.w. is tp True, dan wordt de registry waarde gehanteerd, is tp False, dan blijft tp False.
transformcg
Dit is een optioneel attribuut. Het is een M statement dat een variabele RDid transformeert naar een variabele RDid. Indien de macro getMeta wordt opgeroepen in een attribuut, en het resultaat is niet gedefinieerd, dan wordt RDid gevuld met de concretisering (de derde component van de mt-loi). getMeta wordt dan opnieuw opgeropen in dit attribuut maar nu met de ‘nieuwe’ concretisering. Een goed voorbeeld van dit gebruik kan je vinden bij het type pkgenre.
sortcg

Dit is een optioneel attribuut, dat zorgt voor een alternatieve sortering van de objecten van dit type. Het is een M statement dat een array RAsort genereert op basis van RDmtloi Hierbij bevat RAsort(1) de eerste sorteersleutel, RAsort(2) de tweede,enz.. . Geen enkele sorteersleutel mag leeg zijn, en je mag zoveel sleutels aanmaken als het M systeem toelaat, **zolang je voor alle objecten van dit type evenveel sleutels aanbrengt **. Voorbeeld :

meta pkgenre:
    $attribute: sortcg
        $$content: _system
        $$value: d %Sort^gbpk(.RAsort,RDmtloi)

de M code in gbpk.m kan er dan zo uitzien:

def %Sort(PAsort,PDmtloi):
 n genre,lib,xx
 k PAsort
 m4_getPkIdentifier(lib,genre,PDmtloi)
 s PAsort(1)=$s(lib="":" ",1:lib),PAsort(2)=$s(genre="":" ",1:genre)
 q
preventexport

Dit is een optioneel attribuut, dat het automatisch exporteren van meta data kan verhinderen. Voorbeeld :

meta pkgenre:
    $attribute: preventexport
        $$content: _system
        $$value: 1
ud
Type attribuut. Laatste datum ($H) waarop iemand een eerdere bevriezing heeft ongedaan gemaakt.
up
Brocade userid die de laatste bevriezing heeft ongedaan gemaakt.

10.4. Verantwoordelijkheden bij meta informatie

10.4.1. Ontwikkelaars

De ontwikkelaars definiëren de types.

Dit houdt in:

  • kiezen van een passende identifier voor het type
  • opzetten van de niet-standaard attributen: in het bijzonder wordt hier de toegang opgezet via de toegangssloten.
  • organisatie van de attributen in contents
  • invullen van de type attributen
  • kiezen voor een initiële verwoording en hulpboodschappen
  • plaatsen van de relevante menu ingangen
  • opzetten van de search/history/lookup objecten

De qtech ontwikkeltools zorgen ervoor dat dit efficiënt en foutvrij kan gebeuren.

10.4.2. Beheerders meta informatie

Dit zijn medewerkers van de bibliotheek zelf. Deze mensen hebben een bevoegdheid om bepaalde delen van de meta informatie te gaan afstellen aan de behoeften van hun bibliotheek. Ze gebruiken daartoe de bibliotheeksoftware zelf via een webinterface. Deze webinterface is samengesteld met de instrumenten aangeleverd door de key-value store.

Ook de verwoordingen en hulpboodschappen kunnen worden aangepast. Daartoe kan gebruik worden gemaakt van de instrumenten van de namespaces en tekstfragmenten.

10.5. Interne aspecten aan meta informatie nieuwe stijl

Er zijn een aantal keuzes gemaakt om deze nieuwe vorm van meta informatie vlot te organiseren.

10.5.1. Standaard naamgevingen

De ontwikkelaar kan slechts een beperkt aantal namen vrij kiezen: de codes die dienen om een en ander te verwoorden worden automatisch aangemaakt. Dit geeft niet altijd de best mogelijke code maar het is wel eenvoudig, gemakkelijk en consistent.

De ontwikkelaar kan kiezen:

  • de identifier van het type (mits de beperking [a-z][a-z0-9]*).
  • de identifiers van de attributen (mits de beperking [a-z][a-z0-9]* en dat deze identifiers niet mogen samenvallen met de de namen van de standaard attributen)

Uit deze keuze worden dan alle codes tot verwoording gegeneerd. Deze codes zijn dusdanig dat ze ook kunnen worden gebruikt binnen namespaces en tekstfragmenten.

10.5.2. Standaard attributen

Er zijn een aantal attributen die steeds opnieuw voorkomen en die nu ook steeds dezelfde naam hebben.

10.5.3. Global ^BMETAD

Er werd geopteerd om alle meta informatie (van het type en van de concretisering in 1 global weg te schrijven). Dit maakt het transport van meta informatie tussen gelijke systemen veel gemakkelijker.

10.5.4. Caching

Er is een default caching systeem in de global KACHE("meta"). De K duidt er op dat de global op een speciale manier kan worden behandeld door het database systeem (vb. kan in RAM worden gehouden). Het systeem hanteert een conservatieve aanpak van dit caching mechanisme:

  • de cache wordt compleet automatisch aangemaakt
  • de cache wordt compleet afgebroken indien er twijfel is over het up-to-date zijn van de cache.

10.5.5. Export

Er is een automatische export van de meta informatie in 3 formaten:

  • Python
  • CSV
  • JSON

Er moeten dus geen upython modules worden gespecificeerd. Anderzijds is het wel zo dat upython nieuwe versies genereerd van deze exportformaten.

De aanmaak van deze exportformaten neemt zeker wat tijd in bij het updaten van een concretisering. Het aanpassen van meta informatie is echter geen tijdskritische taak.

Opmerking : deze automatische export kan men verhinderen via een te definieren parameter (zie meta-preventexport )

10.6. Contents en meta informatie

Key/Value stores werkt met attributen die gegroepeerd zijn in contents. Een content is niets anders dan een samenhorende groep van attributen. Ook een content heeft een identifier. Deze heeft als syntax: [a-z][a-z0-9]*.

In Key/Value stores zijn de contents belangrijke structurende elementen: behalve de opslag worden de attributen ook per cont getoond en ingevuld.

Ook in de meta informatie nieuwe stijl spelen de contents een rol: ze zorgen ervoor dat de invulschermen op een georganiseerde wijze worden opgezet. De attributen die bij elkaar horen staan bij elkaar. Onderhuids worden de attributen ook per content opgeslagen.

Echter... in het gebruik van de meta informatie vervalt de rol van de contents: om een stukje meta informatie op te vragen moet je op geen enkel moment de content specificeren waartoe het attribuut behoort. Onderhuids zorgt de software er voor dat er abstractie wordt gemaakt van de content.

Belangrijk

Daar in het gebruik attributen onafhankelijk zijn van de content, moeten hun identifiers ook uniek zijn over alle contents heen. M.a.w. een attribuut identifier is uniek voor het type.

10.7. Attributen en frequentie

Sommige attributen zijn enkelvoudig, andere zijn dan weer meervoudig. De naam van een persoon bijvoorbeeld zal (meestal) enkelvoudig zijn. De landen die een persoon ooit heeft bezocht zal dan meestal wel meervoudig zijn.

Het meta systeem kan met beide sitiuaties werken:

  • bij een enkelvoudig systeem zal de waarde ook enkelvoudig zijn
  • bij een meervoudig attribuut zal de waarde een array (in M een array met numerieke subscripts) zijn.

10.8. Groepen en attributen

Sommige attributen zijn multi-facetted. Een naam van een persoon is enkelvoudig maar kan uit 2 onderdelen bestaan: voornaam en achternaam. Met een groepsattribuut kan men een aantal gewone attributen specificeren die samen dit groepsattribuut beschrijven.

Notitie

Groepattributen kunnen zowel enkelvoudig als meervoudig zijn.

10.9. De natuur van attributen

Geheel comform aan de Key/Value Store, hebben attributen een natuur. Het specificeren van deze natuur laat toe om de presentatie en het automatisch testen beter aan te geven.

De volgende attributen zijn beschikbaar:

10.9.1. bool

Laat toe om een attribuut met 1 van 2 mogelijke waarden te specificeren.

10.9.2. choice

Is een uitbreiding op de natuur bool: meerdere, op voorhand gedefinieerde, waarden zijn mogelijk. Het attribuut heeft 1 van deze waarden.

10.9.3. float, integer

Het attribuut stel een getal voor.

10.9.4. group

Laat toe om een groepsattribuut te specificeren. Het hoeft enkel te worden ingevuld indien men wil aangeven dat het attribuut meervoudig is.

10.9.5. label

Toont een niet-editeerbaar veld. Door middel van een template en een generator van sleutels kan men bijkomende informatie tonen op het scherm. labels kunnen ook op automatische wijze data opslaan: specificeer in store een template. Deze template gaat samen met de sleutelgenerator de data berekenen.

10.9.6. multi

Net zoals bij choice zijn er meerdere, op voorhand gedefinieerde, waarden mogelijk. Het attribuut kan echter meerdere van deze waarden dragen.

10.9.7. string

De waarde van het attribuut is een karakterrij.

10.10. Tags bij de attribuut specificatie

Deze tags helpen bij het specificeren van de attributen.

10.10.1. choices

Deze wordt gebruikt bij een attribuut van de natuur choice en multi. De waarde is een collectie van identifiers van het type [a-z][a-z0-9]*. Deze worden ingevoerd en gescheiden door |.

10.10.2. optexe

Deze wordt gebruikt bij een attribuut van de natuur choice en multi. Het is een M-expressie die de keuzelijst berekent en daarvoor RDkvk met de naam van het attribuut ter beschikking krijgt en RAkvkopt(n)=waarde:tekstfragment teruggeeft.

10.10.3. content

Laat toe om het content van het attribuut aan te geven. Komt voor bij elk attribuut

10.10.4. default

Geeft een startwaarde voor het betreffende attribuut.

10.10.5. dec

Enkel van belang bij een attribuut van de natuur float. De waarde is het aantal decimalen waarop het getal moet afgerond worden.

10.10.6. isemptying

Boolese tag. Enkel van belang voor een attribuut in een groep: men kan dan aanduiden welke van de samenstellende attributen leeg moeten zijn opdat het groepsattribuut zelf verdwijnt.

10.10.7. group

Geeft aan wat de identifier van de groep is.

10.10.8. initonly

Soms is het niet wenselijk dat bestaande waarden voor een attribuut kunnen worden aangepast vanuit een concretisering uit een b-file. Dit doet zich bijvoorbeeld voor bij lokale gegevens (het tijdstip waarop een bepaald automatisch proces moet lopen, is een goed voorbeeld).

Kan 2 mogelijke waarden hebben:

  • 0: (Default) Het attribuut wordt steeds ingevuld bij opladen van de b-file
  • 1: Het gegeven wordt pas ingevuld vanuit de b-file enkel indien de concretisering niet bestaat.

Pas op

Bij groepen is het enkel mogelijk de ganse groep attributen te beschermen.

10.10.9. iskey

Boolese tag die aangeeft - bij meervoudige waarden - of deze attribuutwaarde uniek moet zijn. Enkel van belang als een der samenstellende attributen uit een meervodig groepattribuut.

10.10.10. ismarkdown

Boolese tag die aangeeft of de waarde in markdown mark-up is.

10.10.11. ismpattern

Boolese tag die aangeeft of het patroon een M patroon is.

10.10.12. ispypattern

Boolese tag die aangeeft of het patroon een python glob patroon is.

10.10.13. isrepeatable

Boolese tag die aangeeft of het attribuut meervoudig is. Samenstellende attributen van een groep kunnen niet meervoudig zijn. De groep zelf kan wel meervoudig zijn.

Eigenlijk zijn er 3 waarden:

  • 0: niet herhaalbaar
  • 1: herhaalbaar door verdubbeling van het veld
  • 2: herhaalbaar door gebruik te maken van een ; separator (in text input) of door newlines (in textareas)

10.10.14. isselect

Geeft aan of de keuze moet worden gemaakt via een selectbox.

Er zijn 3 mogelijkheden:

  • 1: selectbox
  • 0: radio buttons
  • lege string: het systeem bepaalt zelf (op nasis van de mogelijkheden) wat de beste oplossing is.

10.10.15. istextarea

Geeft aan of de waarde wordt gespecificeerd via een textarea:

Er zijn 2 mogelijkheden:

  • 1: textarea
  • 0: input text

Merk nog op dat indien isrepeatable op 2 staat, meerdere waarden kunnen worden ingevuld:

  • bij een input text veld, worden de waarden gescheiden door een ‘;’
  • bij een textarea worden de waarden gescheiden door crlf.

10.10.16. keygen

Een M executable die een array RAkeyref vult met sleutels. De variabele RDmtloi bevat de identifier van de meta informatie. Met delimiter :

  • deel 1: steeds mt
  • deel 2: het type van de meta informatie
  • deel 3: de concretisering. Bij een nieuwe concretisering is dit leeg. Deze wordt tevens in de variabele RDcg aangeboden.

Wordt gebruikt bij labels

10.10.17. lookup

Geeft de identifier aan van het lookup object die moet helpen om de karakterrij in te vullen.

10.10.18. max

Maximum waarde

10.10.19. min

Minimum waarde

10.10.20. nature

Natuur van het attribuut

10.10.21. pattern

Patroon waar de karakterrij moet aan voldoen

10.10.22. size

Grootte van de textarea of input text, Het is een getal dat de breedte van de widget bepaald. Deze kan 1 dimensie aannemen breedte of 2 dimensies breedtexhoogte.

Voorbeeld in b-file (verkort)

1
2
3
4
$attribute: catinstmodify
    $$isrepeatable: 2
    $$size: 64x10
    $$istextarea: 1

10.10.23. store

Word gebruikt bij labels. Het is een Brocade template dat samen met keygen kan worden verwerkt to een waarde. Deze waarde wordt dan automatisch opgeslagen bij dit attribuut.

10.10.24. template

Een Brocade template. Wordt gebruikt met het keygen veld.

Wordt gebruikt bij labels: tekent de inhoud van dit veld

10.10.25. extratemplate

Een Brocade template die gebruikt wordt om boven een invulveld extra gegevens door te geven aan de gebruiker. Om de value van het invulveld te gebruiken kan $value gebruikt worden.

10.10.26. test

Dit is een M-routine die wordt uitgevoerd om de invoer van dit attribuut te testen.

In deze M-routine zijn er 4 waarden belangrijk:

  • RDkvv: de waarde van het attribuut
  • RDkvk: de naam van het attribuut
  • RDerror: foutboodschap (slaat gegevens niet op)
  • RDwarn: waarschuwingsboodschap (slaat gegevens op)
Voorbeeld in b-file
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
$attribute: catinstmodify
    $$content:
    $$group:
    $$isemptying: 0
    $$nature: string
    $$iskey: 0
    $$isrepeatable: 2
    $$size: 64
    $$istextarea: 1
    $$pattern:
    $$ismpattern: 0
    $$ispypattern: 0
    $$ismarkdown: 0
    $$extratemplate:
    $$test: d %TstCatM^gusersid
    $$lookup: instelling
Voorbeeld in M:
def %TstCatM:
 ;pragma fos RDkvv,RDwarn,RDerror,RDkvk
 n RDfield,error
 i $g(RDkvv)'="" d
 . m4_isCatLib(error,RDkvv)
 . s:$f(RDkvv,"*") error=0
 . q:'error
 . s RDwarn="invalidmetavalue^"_RDkvv
 . q
 q

10.10.27. value

Wordt enkel gebruikt bij type attributen: deze tag laat toe om de waarde te specificeren.

10.10.28. kvsid

Een identifier die bij de tekening van het element in het HTML-attribuut data-kvsid gezet wordt. Default is dit de naam van het attribuut zelf.

10.11. Opzetten van een nieuw type meta informatie

Laten we nu een overzicht geven over de verschillende stappen die moeten worden doorlopen om een nieuw type meta informatie op te stellen.

  1. Keuze van een passende identifier van het type
  2. Aanmaak/openen van een (bestaande) *.b file
  3. Invullen van de type attributen
  4. Specificatie van de diverse attributen
  5. Specificeer in het menuitem de parent en de sorteercode
  6. Vul de lgcodes in

10.11.1. Keuze van de passende identifier voor het type

Zoals steeds is de keuze van een passende identifier belangrijk voor het goed werken van software. De identifier moet beknopt zijn, goed vangen wat de onderliggende lading is, uitspreekbaar zijn, goed schrijfbaar zijn en bovenal voldoen aan de opgelegde syntaxregels. Een identifier als catsys is te verkiezen boven dogfoodsys.

In de volgende paragrafen gaan we als voorbeeld steeds werken met het type demosys als voorbeeld. M.a.w. telkens je het woorje demosys ziet, moet je dit vervangen door je zonet gekozen identifier.

10.11.2. Aanmaak/openen van een (bestaande) *.b file

Ontwikkelaars definiëren Brocade objecten steeds in een b-file en dus ook meta objecten. Er is niet echt een voorkeur voor een keuze voor de naam van de b-file. Een praktijk - overgenomen uit de Java wereld en waar nogal wat kritiek op is - zou kunnen zijn dat we hier de naam demosys.b kiezen. Het nadeel van dit systeem is wel dat je zo wel heel wat b-files krijgt. Een alternatief zou kunnen zijn dat je als naam de projectnaam kiest en alle meta objecten groepeert in één bestand.

Eens een b-file gekozen, dan is het wel handig om met behulp van de Emacs editor snel een grotendeels ingevuld sjabloon te krijgen: in btech-mode vraagt de editor naar de identifier (demosys) en maakt dan automatisch een passend meta, history, search, lookup en menuitem aan. Elk van deze objecten draagt dezelfde identifier: demosys

10.11.2.1. Het meta object

Laten we een en ander bespreken aan de hand van een voorbeeld:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
meta demosys:
    $attribute: tp // transaction processing
        $$content: _system
        $$value: 1
    $attribute: at // audit trail
        $$content: _system
        $$value: 1
    $attribute: canfreeze // slot op bevriezen
        $$content: _system
        $$value:

Op lijn 1 wordt het met object demosys gedefinieerd. Noteer het afsluitende ‘:’. Op lijnen 2, 5, 8 worden de attributen tp, at en canfreeze gedefinieerd. Dit zijn allen type attributen. Van de ontwikkelaar wordt er verwacht dat meteen ook een waarde wordt gespecificeerd. Vandaar dat er een tag $$value bestaat. Na het dubbel punt kan dan een passende waarde worden ingetikt. Merk nog op dat lijnen 3, 6 en 9 een tag $$content hebben. Merkwaardig genoeg staat daar de identifier _system. Deze structuur is een niet-legale waarde voor een content. Dit is met opzet gedaan: deze komt zo nooit in conflict met de contents van de gewone attributen*. Er hoeft ook niet worden gezorgd voor de verwoordingen van deze content en zijn attributen: het systeem kent deze verwoording reeds (zie /universe/meta/meta.l).

Eens de type attributen gedefinieerd (het Emacs sjabloon zet deze klaar voor u), moeten de gewone attributen worden gedefinieerd.

Zoals reeds eerder aangegeven worden de attributen gegroepeerd in contents. Wordt bij een attribuut deze content niet gespecificeerd, dan wordt de laatst opgegeven content waarde gebruikt. Het is beter om deze content identifier enkel te specificeren indien er van content wordt veranderd: het maakt het eenvoudiger om attributen te verplaatsen van content naar content.

Notitie

Wordt de content identifier aangevuld met een ‘?’, dan wordt deze content in de display toegeklapt getoond.

Het textadept sjabloon om verschillende soorten attributen te definiëren. Het volgende voorbeeld toont dit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
meta demosys:
    $attribute: tp
        $$content: _system
        $$value: 1

    $attribute: errorwrongcg
        $$content: _system
        $$value:

   $attribute: typeactioncopy
        $$content: _system
        $$value: d %Do^baction(RDmtloi)

    $attribute: yesno
        $$content: usage
        $$group:
        $$isemptying: 0
        $$nature: bool
        $$iskey: 0

    $attribute: colorchoice
        $$content:
        $$group: characteristics
        $$isemptying: 0
        $$nature: choice
        $$iskey: 0
        $$isrepeatable: 0
        $$choices: green | blue | red
        $$isselect: auto

    $attribute: weight
        $$content: characteristics
        $$group:
        $$isemptying: 0
        $$nature: float
        $$iskey: 0
        $$isrepeatable: 0
        $$min: 0
        $$max: 200
        $$size: 3
        $$default: 0

    $attribute: numberparticipants
        $$content:
        $$group:
        $$isemptying: 0
        $$nature: integer
        $$iskey: 0
        $$isrepeatable: 0
        $$min: 0
        $$max: 1000000
        $$size: 10
        $$default: 0

    $attribute: hobbies
        $$content:
        $$group:
        $$isemptying: 0
        $$nature: multi
        $$iskey: 0
        $$isrepeatable: 0
        $$choices: chess | reading | running

    $attribute: country
        $$content:
        $$group:
        $$isemptying: 0
        $$nature: string
        $$iskey: 0
        $$isrepeatable: 2
        $$size: 64
        $$istextarea: 1
        $$pattern:
        $$ismpattern: 0
        $$ispypattern: 0
        $$ismarkdown: 0
        $$lookup:

    $attribute: testcase
        $$content:
        $$group:
        $$nature: label
        $$template: $RDmtloi: {$name|upper}
        $$keygen: s RAkeyref("name")="Richard"
        $$store:

De opzet is eenvoudig: de identifiers en waarden staan steeds na het ‘:’ karakter, tags worden ingeleid met een $$.

lijn 10
een nieuwe content (usage) wordt begonnen met attribuut yesno
lijn 17
ook het attribuut colorchoice behoort tot de content usage
lijnen 18, 27
er wordt een attribuut characteristics gedefinieerd met 2 attributen: colorchoice en weight
lijn 23
voor colorchoice worden 3 mogelijke waarden bepaald.
lijn 67
het country attribuut is herhaalbaar, de waarden worden door een ; gescheiden.

10.11.2.2. Het history object

Het history object wordt compleet gegenereerd door het Emacs sjabloon. De identifier is dezelfde van het meta object.

10.11.2.3. Het search object

Het search object wordt compleet gegenereerd door het Emacs sjabloon. De identifier is dezelfde van het meta object.

De informatie die binnen het search object wordt getoond, kan worden aangevuld via het attribuut extraheader.

Het filter mechanisme van het search object kan worden aangestuurd op twee wijzen:

  • door het specificeren van een eigen filter mechanisme via het searchfilter attribuut
  • filter opdrachten waarvan de zoekstring een $ bevatten volgen een eigen weg: ze worden geïnterpreteerd als Booleaanse uitdrukkingen waarvan de variabelen (ingeleid met een $) de attributen van de geïnspecteerde concretrisering zijn. Een voorbeeld om dit duidelijk te maken: is het meta type mt:pkgenre. De zoekstring $etforbidden = 1 selecteert alle concretiseringen waarvan het attribuut etforbidden op 1 staat. Dit is een bijzonder krachtig filter mechanisme dat in de eerste plaats is bedoeld voor ontwikkelaars. Een verkeerd invullen van de zoekstring kan immers een software fout veroorzaken (die overigens helemaal geen schade toebrengt).

Pas op

Als je een filter opdracht geeft met behulp van $, hou er dan rekening mee dat sommige attributen meervoudig kunnen zijn of zelfs een groep kunnen uitmaken. Ook attributen van het type multi zijn meervoudig. Sleutels hebben echter een unieke waarde. In deze gevallen wordt de waarde van de sleutel dan ook geconstrueerd door de samengestelde of meervoudige waarde te serialiseren in een JSON karakterrij. Dit overstappen naar JSON is gebaseerd op de natuur van het attribuut en niet op het al dan niet meervoudig zijn. M.a.w. een meervoudig attribuut dat toevallig slechts 1 enkele waarde heeft, wordt ook naar JSON geserialiseerd.

10.11.2.4. Het lookup object

Het lookup object wordt compleet gegenereerd door het Emacs sjabloon. De identifier is dezelfde van het meta object.

10.11.2.5. Het menuitem object

Hier zijn wel een aantal velden die aandacht vragen:

  • de parent moet worden gespecificeerd
  • de sortkey binnen deze parent moet worden ingevuld

Eventueel moeten ook de parent folders worden gespecificeerd.

10.11.3. Aanmaak van de lgcodes

Met een meta object worden diverse lgcodes aangemaakt. Deze worden ook automatisch gegeneerd door de Emacs software.

Een overzicht van de in te vullen codes (we werken nog steeds met het voorbeeld demosys)

  • Verwoording voor de namespace metaDemosys. (let op het ingesloten .). Elk type (demosys) komt met zijn eigen namespace. Deze namespace is manipuleerbaar door de meta beheerder. In de l-files staan initiële waarden.

  • Verwoording voor het type sayMetaDemosys

  • Voor elke content (vb. usage) worden er 2 lgcodes gegenereerd:

    1. metaDemosys.titlemetaDemosysUsage: verwoording van de content. Kies een korte duidelijke naam.
    2. metaDemosys.titlemetaDemosysUsage.scope: uitgebreide beschrijving van de content in markdown
  • Een belangrijke lgcode (content _system) is metaDemosys.titlemetaSystem.scope. Deze beschrijft de meta informatie zelf.

  • Voor elke attribuut (vb. yesno) worden er 2 lgcodes gegenereerd:

    1. metaDemosys.yesno: verwoording van het attribuut. Kies een korte duidelijke naam. Het is niet nodig hier een omschrijving van het attribuut in te vullen.
    2. metaDemosys.yesno.scope: uitgebreide beschrijving van het attribuut in markdown
  • Voor elke groep (vb. characteristics) worden er 2 lgcodes gegenereerd:

    1. metaDemosys.characteristics: verwoording van het groepsattribuut. Kies een korte duidelijke naam. Het is niet nodig hier een omschrijving van het attribuut in te vullen.
    2. metaDemosys.characteristics.scope: uitgebreide beschrijving van het groepsattribuut in markdown
  • Voor elke optie uit choices (vb. red uit colorchoice) worden er opnieuw 2 codes gegenereerd:

    1. metaDemosys.colorchoiceRed: verwoording van de keuze. Kies een korte duidelijke naam. Het is niet nodig hier een omschrijving van het attribuut in te vullen.
    2. metaDemosys.colorchoiceRed.scope: uitgebreide beschrijving van de keuze` in markdown
  • voor elk attribuut uit de content _system waarvan de naam begint met typeaction moeten er twee codes worden aangemaakt (vb. typeactioncopy)

    1. metaDemosys.metaFormatTyepactioncopy: dit is een label bij de corresponderende actie
    2. metaDemosys.metaFormatTyepactioncopyInfo: dit is een informatieveld bj de corresponderende actie

    Eventueel kan er nog een derde tekstfragment moeten worden aangemaakt. Dit doet zich voor als bij de typeaction nog een extra parameter dient te wordem gespecificeerd. De waarde metaDemosys.metaFormatTyepactioncopyInput stelt dan de verwoording voor van deze parameter.

Het kan niet genoeg worden beklemtoond dat er hier een dubbel opdracht is:

  • ontwikkelaars: geef goede, generieke verwoordingen die toepasbaar zijn voor elke Brocade installatie
  • beheerders van de meta informatie: pas deze verwoording - indien nodig - aan voor specificieke situatie. gebruik daartoe de instrumenten van namespaces en tekstfragmenten.

10.12. Diensten geleverd door de meta informatie nieuwe stijl

10.12.1. Uniforme structuren

Onderhuids vormt deze meta informatie een loi van de gedaante mt:type:cg.

De toegang tot de concretiseringen wordt op 2 wijzen verzekerd:

  • Onder het Brocade Systeembeheer > beheer Brocade objecten >  Object identifiers voor meta informatie kan men alle loi bereiken. Dit is een manier die geschikt is voor ontwikkelaars.
  • De andere toegangen zijn applicatie georiënteerd en zijn vooral geschikt voor beheerders van meta informatie. Een typisch voorbeeld is Brocade > Catalografie > Catalografie - Beheersfuncties > Catalografie - Beheersfunctie voor collectiebeschrijvingen

10.12.2. Automatisch beheer van het history object

Toepassingen die meta informatie nieuwe stijl nodig hebben, hoeven de history niet zelf te updaten. Het systeem doet dat zelf.

10.12.3. Opvragen van meta informatie

Dit is vanzelfsprekend het meest tot de verbeelding sprekende element van meta informatie nieuwe stijl:

macro getMeta($meta, $type="", $cg="", $att="", $valid=0):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Haal de metadata op
    $meta: Resultaat: array/string met de metagegevens
           Er is steeds een resultaat.
           Ook indien het attribuut onbekend is, dan is het resultaat
           steeds de lege string
    $type: Meta type (vb. 'catsys').
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. 'lvd')
         Kan ook als mt-loi worden opgegeven.
         Indien $cg leeg is, dan wordt de meta informatie van het type opgespoord
    $att: Attribuut. Indien dit attribuut ontbreekt,
          dan worden alle metadata teruggegeven.
    $valid: Opties:
            0 (default waarde): geeft steeds een waarde terug,
              ook indien het attribuut,
              de concretisering of zelfs het metatype niet bestaat
            1: geeft enkel iets terug indien het de concretisering
               bestaat, anders is $D(meta) = 0
            2: zowel de concretisering als het attribuut moeten bestaan
    $example: m4_getMeta(RAlm, "catsys", "lvd", "lm")
    '''

    ««d %GetCg^gbmetad(.$meta,$type,$cg,$att,$valid)»»

10.12.4. Acties

Er worden steeds een aantal standaardacties voorzien:

  • schrappen
  • kopiëren
  • toevoegen aan een lijst
  • bekijk mode
  • bevriezen van gegevens

Het is ook mogelijk om specifieke acties op te zetten. Definieer daartoe een $attribute bij de $$content _system waarvan de naam begint met typeaction. $$value is dan een M-uitdrukking die werkt met RDmtloi` (de mt-loi van de huidige meta informatie). Bijvoorbeeld:

1
2
3
4
meta demosys:
   $attribute: typeactioncopy
        $$content: _system
        $$value: d %Do^baction(RDmtloi)

Er moeten ook twee lgcodes worden opgezet (zie de betreffende paragraaf)

Het systeem ondersteunt ook een extra parameter. In dit geval is het tevens mogelijk om een lookup te specificeren. Deze extra parameter kan onder de naam RDparm worden gebruikt in de uit te voeren functie.

Een voorbeeld:

1
2
3
4
5
6
meta demosys:
   $attribute: typeactionname
        $$content: _system
        $$value: d %Do^baction(RDmtloi)
        $$input: 1
        $$lookup: workstation

Bij het aanvinken van de activiteit en het registreren van het formulier wordt eerst de meta informatie weggeschreven en dan worden de aangevinkte activiteiten in volgorde uitgevoerd. Deze activiteiten kunnen eveneens de meta informatie zelf aanpassen.

Als je bij typeaction data wilt laten tonen, dan kan je gebruik maken van reportgen. Het kan dus zijn dat er geen value is ingevuld onder typeaction, maar dat dit door reportgen wordt ingevuld. (zie meta-reportgen )

10.12.5. Extra informatie

Met een meta-loi kan ook extra informatie worden opgeslagen. Deze informatie komt in twee componenten:

  • een referentie string
  • de eigenlijke gegevens (een M array)

Het is aan de ontwikkelaar die wil gebruik maken van deze mogelijkheid om goede waarden te kiezen voor deze gegevens.

Hij heeft 3 macro’s tot zijn beschikking:

macro setMetaExtra($extra, $ref, $type="", $cg="", $overwrite=1):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Zet extra data bij een mt-loi
    $extra: M array
    $ref: referentie voor deze data
    $type: Meta type (vb. catsys).
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
         Indien $cg leeg is, dan wordt de meta informatie van het type opgespoord
    $overwrite: 0 | 1 (schrap vooraleer te schrijven)
    $example: m4_setMetaExtra(RAdata, "myref", RDmtloi)
    '''

    ««d %SetExtr^gbmetad(.$extra,$ref,$type,$cg,$overwrite)»»
macro getMetaExtra($extra, $ref, $type="", $cg=""):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Zet extra data bij een mt-loi
    $extra: M array
    $ref: referentie voor deze data
    $type: Meta type (vb. catsys).
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
         Indien $cg leeg is, dan wordt de meta informatie van het type opgespoord
    $example: m4_getMetaExtra(RAdata, "myref", RDmtloi)
    '''

    ««d %GetExtr^gbmetad(.$extra,$ref,$type,$cg)»»
macro delMetaExtra($ref, $type="", $cg=""):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Verwijdert extra data bij een mt-loi
    $ref: referentie voor deze data
          Als referentie = "", dan wordt alle extra data geschrapt
    $type: Meta type (vb. catsys).
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
         Indien $cg leeg is, dan wordt de meta informatie van het type opgespoord
    $example: m4_delMetaExtra(RDdata, "myref", RDmtloi)
    '''

    ««d %DelExtr^gbmetad($ref,$type,$cg)»»

10.12.6. Automatische python file met meta informatie

Per type, wordt er een python script aangemaakt met de meta informatie van alle concretiseringen.

Een voorbeeld met demosys:

>>> from anet.brocade.demosys import Demosys
>>>
>>> type(Demosys)
<type 'dict'>
>>>

Er gelden steeds de volgende regels:

  • de naam van de script is <type>.py (vb. demosys.py)
  • de dict met de eigenlijke meta informatie is steeds <ctype>. ctype ontstaat door de eerste letter van type te capitaliseren. (vb. Demosys)

10.12.7. Controleer of meta informatie bestaat

macro isMeta($xis, $type="", $cg=""):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Bestaat de meta data ?
    $xis: 0 (=metadata bestaat en is actief)
           1 (=metadata bestaat niet)
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
           Indien cg leeg is, dan wordt getest of meta informatie van het type $type bestaat
                  cg *NIET* leeg is, dan wordt getest of meta informatie voor $cg bestaat
    $example: m4_isMeta(xis, "catsys", "lvd") i xis w "Metadata bestaat niet"
    $example: m4_isMeta(x,"workstation","UA-CST") i xis w "unknown"
    $example: m4_isMeta(x,"mt:workstation","UA-CST")
    $example: m4_isMeta(x,cg="mt:workstation:UA-CST")
    '''

    ««s $xis=$$%Xis^gbmetad($type,$cg)»»

10.12.8. Standaard test op meta informatie

macro checkMeta($error, $type="", $cg="", $min=0, $max=0, $lg="", $accepted=MDaccept):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Test op het gebruik van een concretisering
    $error: Foutboodschap
            - Leeg indien er geen fout is
            - een foutboodschap te berekenen uit de errortemplate
            Er zijn de volgende soorten foutboodschappen:
            - indien er teveel waarden zijn
            - indien er foutieve waarden zijn
            - indien er een ongeldige waarde is
            - indien er een niet toegelaten waarde is (accepted)
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $cg: String die wordt getest
    $min: minimum aantal waarden
    $max: maximum aantal waarden (0: oneinding)
    $lg: taal
    $accepted: array met geldige waarden als subscript. Indien deze array niet bestaat,
               dan wordt deze test niet uitgevoerd
    $example: m4_checkMeta(error, "catsys", "lvd;biomed")
    '''

    ««k MDaccept s $error=$$%Error^gbmetad($type,$cg,$min,$max,$lg,.$accepted)»»

10.12.9. Verwoordingen van meta informatie

macro sayMeta($say, $type="", $cg="", $lg="", $enc="", $default=" "):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Verwoord de meta data
    $say: Verwoording
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
         Indien $cg leeg is, dan wordt de verwoording van $type teruggegeven
    $lg: Taal waarin de verwoording wordt teruggegeven, indien '@' wordt de generieke verwoording terug gegeven
    $enc: encodering (xml | js | ...)
    $default: Default waarde
    $example: m4_sayMeta(say, "catsys", "lvd")
    '''

    ««s $say=$$%Say^gbmetad($type,$cg,$lg,$enc,$default)»»

10.12.10. Wildcard selectie op concretiseringen

macro globMeta($array, $glob="*", $onlyreadable=0, $onlywriteable=0, $staff="", $select=0):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Bereken een array met als subscripts de concretiseringen met een gegeven patroon
    $array: Array (bevat mtlois in subscript)
    $glob: glob patroon (python), default="*"
    $onlyreadable: 0 | 1 (selecteert enkel de leesbare concretiseringen)
    $onlywriteable: 0 | 1 (selecteert enkel de schrijfbare concretiseringen)
    $staff: personeelslid (default: UDuser)
    $select: 0 | 1 (1= maak de Array klaar voor een select in meta informatie)
    $example: m4_globMeta(RAlist, "mt:catsys:l*")
    '''

    ««d %Glob^gbmetad(.$array,$glob,$onlyreadable,$onlywriteable,$staff,$select)»»

10.12.11. Wildcard HTML selectie element op concretiseringen

macro selectMeta($select, $type="", $template="", $default, $glob="*", $lg="", $onlyreadable=0, $onlywriteable=0, $staff="", $list=MDli, $cgonly=0, $prefix="", $withempty=0):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Bereken een array met als subscripts de concretiseringen met een gegeven patroon
    $select: string met de <option>s
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $template: Template of attribuut
               Indien attribuut (bestaat enkel uit letters en cijfers), dan moet dit verwijzen naar ene tekstfragment (ns.textcode)
               Anders is dit een volwaardige template:
                  - (de verwoording wordt automatisch in XML geencodeerd)
                  - default: $cg
                  - sleutels: cg (concretisering identifier), say (verwoording van de concretisering)
    $default: default waarde
    $glob: glob patroon (python), default="*"
    $lg: Taal waarin de verwoording wordt teruggegeven
    $onlyreadable: 0 | 1 (selecteert enkel de leesbare concretiseringen)
    $onlywriteable: 0 | 1 (selecteert enkel de schrijfbare concretiseringen)
    $staff: personeelslid (default: UDuser)
    $list: sequentiele lijst met in de waarden de concretiseringen (dit heeft voorrang op alle andere opties)
    $cgonly: 0 | 1 , indien 1 dat wordt het mt:type gedeelte weggelaten
    $prefix: string die bij het uiteindelijke resultaat wordt voorgeplakt
    $withempty: 0 | 1, indien 1 dan is de eerste optie steeds leeg
    $example: m4_selectMeta(RAlist, "catsys", "l*")
    '''

    ««k MDli s $select=$$%Select^gbmetad($type,$template,$glob,$default,$lg,$onlyreadable,$onlywriteable,$staff,.$list,$cgonly,$prefix,$withempty)»»

10.12.12. Toegang tot een meta object van een Brocade gebruiker nagaan

macro isMetaReadable($xis, $type="", $cg="", $staff=""):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Mag de meta data bekeken worden door een personeelslid
    $xis: 0 (=metadata mag bekeken worden) | 1 (=metadata mag niet worden bekeken)
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
    $staff: personeelslid (default: UDuser)
    $example: m4_isMetaReadable(xis, "catsys", "lvd", staff="rphilips" ) i xis w "rphilips mag niet lezen"
    '''

    ««s $xis=$$%Xisread^gbmetad($type,$cg,$staff)»»
macro isMetaWriteable($xis, $type="", $cg="", $staff=""):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Mag de meta data aangepast worden door een personeelslid
    $xis: 0 (=metadata mag aangepast worden) | 1 (=metadata mag niet worden aangepast)
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
    $staff: personeelslid (default: UDuser)
    $example: m4_isMetaWriteable(xis, "catsys", "lvd", staff="rphilips" ) i xis w "rphilips mag niet aanpassen"
    '''

    ««s $xis=$$%Xiswrit^gbmetad($type,$cg,$staff)»»
macro isMetaCreateable($xis, $type="", $staff=""):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Mag de meta data aangemaakt worden door een personeelslid
    $xis: 0 (=metadata mag aangepast worden) | 1 (=metadata mag niet worden aangepast)
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $staff: personeelslid (default: UDuser)
    $example: m4_isMetaCreateable(xis, "catsys",  staff="rphilips" ) i xis w "rphilips mag niet aanmaken"
    '''

    ««s $xis=$$%Xiscrea^gbmetad($type,$staff)»»
macro isMetaFreezable($xis, $type="", $cg="", $staff=""):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Kan een personeelslid de data bevriezen
    $xis: 0 (=metadata mag bevroren worden)
           1 (=metadata bestaat niet of is biet actief)
           2 (=metadata is reeds bevroren)
           3 (=personeelslid heeft niet voldoende pivileges)
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
    $staff: personeelslid (default: UDuser)
    $example: m4_isMetaFreezable(xis, "catsys", "lvd", staff="rphilips" ) i xis w "rphilips mag niet bevriezen"
    '''

    ««s $xis=$$%Xisfrz^gbmetad($type,$cg,$staff)»»
macro isMetaThawable($xis, $type="", $cg="", $staff=""):
    '''
    $editfile: /universe/meta/meta.d
    $synopsis:  Kan een personeelslid de data ontdooien
    $xis: 0 (=metadata mag ontdooid worden)
           1 (=metadata bestaat niet of is niet actief)
           2 (=metadata is niet bevroren)
           3 (=personeelslid heeft niet voldoende pivileges)
    $type: Meta type (vb. catsys)
           Kan ook als mt-loi worden opgegeven.
    $cg: Identifier voor de concretisering (vb. lvd)
         Kan ook als mt-loi worden opgegeven.
    $staff: personeelslid (default: UDuser)
    $example: m4_isMetaThawable(xis, "catsys", "lvd", staff="rphilips" ) i xis w "rphilips mag niet ontdooien"
    '''

    ««s $xis=$$%Xisthw^gbmetad($type,$cg,$staff)»»

10.12.13. Exporteer meta data

Een mogelijkheid om meta data naar buiten te brengen gaat via het lijstbeheer. Werkwijze:

  • Maak een lijst aan, die mt lois bevat.
  • Kies in het lijstbeheer de bewerking ‘Downloaden’.
  • Selecteer : ‘Genereer extra kolommen via : mtall : Alle meta gegevens’
  • Start de download.

10.12.14. Lijst maken van mt lois

Om makkelijk een selectie te maken van mt lois op basis van identifiers en/of waarden van attributen, kan je gebruik maken van Selectie van meta concretiseringen [link].

Deze toepassing maakt een selectie van meta concretiseringen van één bepaald metatype.
Je kan de selectie filteren op volgende manieren:
  • Een patroon opleggen op de identifier van de concretisering. Bijvoorbeeld ‘Z‘ zal enkel identifiers selecteren die met ‘Z’ beginnen. Laat leeg of vul ‘‘ in als je geen filtering op identifier wilt.
  • Een booleanse expressie op de attributen. Je kan zo concretiseringen selecteren waarbij de attributen een bepaald patroon hebben. Laat leeg indien dit niet wenselijk is.
  • Als er een bronlijst wordt gespecificeerd, dan worden enkel concretiseringen die worden gevonden binnen deze lijst, behandeld. Wordt er geen bronlijst gespecificeerd, dan worden alle concretiseringen van het opgegeven metatype behandeld.

10.12.15. Importeer meta data

  • Voor software engineers is een menu optie voorzien : Systeembeheer ‣ Beheer Brocade objecten ‣ Importeer meta data [link] . De juistheid van de data wordt gecheckt, de toegang wordt via de menu ingang geregeld.

10.12.16. Valideer de inhoud van (alle) aanwezige meta data

  • Dit kan via gebruiksproces : Systeembeheer ‣ Beheer Brocade objecten ‣ Check meta data [link] . Een lijst van fouten wordt gegenereerd.

10.13. Voorbeelden uit de praktijk

Dit hoofdstuk beschrijft (vindingrijke) oplossingen voor diverse problemen die zich voordoen in de praktijk.

10.13.1. De concretiseringen zijn eigennamen

Dit doet zich voor wanneer de identifiers uit zichzelf een betekenis hebben zoals bijvoorbeeld in het geval van namen van werkstations, van organisaties en dergelijke.

Het is dan beter in de b-file de volgende code in te lassen:

1
2
3
4
5
6
7
8
meta mytype:
    $attribute: idfree
        $$content: _system
        $$value: 1
    $attribute: skiplanguages
        $$content: _system
        $$value: 1
    ...

Er wordt dan geen test gedaan op de naam van de identifier en er worden ook geen namen gevraagd.

10.13.2. Opnemen van benamingen in diverse talen

Het gebeurt geregeld dat in de meta informatie diverse benamingen, moeten worden opgenomen.

Een goed voorbeeld hiervan kan je vinden bij het beschrijven van genres plaatskenmerken: daar moet je een tekst aangeven die je moet plaatsen in de publiekscatalogus. In plaats van dan voor elke relevante taal een attribuut te creëren is het beter 1 attribuut aan te maken dat dan staat voro een tekstfragment. Dit tekstfragment kan dan elders worden aangepast.

Dit kan eenvoudig zoals in het volgende voorbeeld:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
meta mytype:
    ...
    $attribute: opacname
       $$content:
       $$group:
       $$isemptying: 0
       $$nature: string
       $$iskey: 0
       $$isrepeatable: 0
       $$size: 64
       $$istextarea: 0
       $$pattern:
       $$ismpattern: 0
       $$ispypattern: 0
       $$ismarkdown: 0
       $$extratemplate: ${value|textfragment}
       $$test:
       $$lookup:

10.14. Beperkt search-resultaat van nieuwe meta

Je kan de search-resultaten van nieuwe meta beperken door m4_startSearch aan te roepen met $mode="filter^d [mumps routine]". De routine die je meegeeft krijgt de vorige concretisering doorgestuurd via de parameter RDpos. Deze routine gaat RDpos overschrijven met de gevonden volgende concretisering of met de lege string indien geen volgende gevonden.

10.15. Het FDstorit element in het webformulier

Het laatste veld in het webformulier van meta informatie is steeds een hidden element met de naam FDstorit. De value van dit element is steeds de waarde van de M variabele FDstorit. Er zijn diverse stukjes software die er voor kunnen zorgen dat dit element wordt gevuld (bijvoorbeeld: het side-effect, of de keygen attributen.

Dit veld heeft diverse toepassingen en kan bijvoorbeeld worden gebruikt samen met het jshead data element.

10.16. Overzetten oude meta-data naar nieuwe meta-data

In de nieuwe meta-data wordt de informatie beschreven in een b-file en een l-file. Deze documentatie is nog in verwerking.

10.16.1. Stappenplan

Onderstaande is een guideline. De volgorde is zeker niet heiligmakend en veel processen gebeuren door elkaar.

  1. Oude, om te zetten data (in deze stap is er nog geen sprake van omzetting)

    • Bekijk de oude data/formulieren: wat doen ze, hoe zijn ze gestructureerd, gebeuren er testen op het formulier, ...

      vb: bij het omzetten van gebruikers naar nieuwe metadata waren er meerdere formulieren die omgezet werden naar 1 formulier.

    • Ga na welke macro’s moeten omgezet worden en in welke bestanden deze staan.

      vb: macro isUser, macro getUserMail, ... De meeste macro’s ivm de gebruikers staan in het users.d bestand. Let wel, meestal staan niet al de om te zetten macro’s in 1 *.d bestand.

    • Ga na welke globals er omgezet gaan worden. Bij oudere toepassingen kunnen deze ook in andere bestanden staan dan enkel de g*.m of *.d bestanden.

      vb: De global ^USERS(“users”) moet omgezet worden. Let op: Sommige globals bevatten subbranches die niet van toepassing zijn bij de conversie naar nieuwe metadata. Bij ^USERS waren dit bijvoorbeeld al de voorkeurinstellingen die in ^USERS(“users”) bleven staan.

    Tip: Het is handig om een soort schema op te stellen van je bevindingen, zodat je naderhand niets vergeet.

  2. Nieuw formulier

    • Bepaal de structuur van het nieuwe formulier op basis van het oude formulier met eventueel nieuwe functionaliteiten.

    • Maak het formulier met de velden aan in een b-file (formulier) en l-file (vertalingen). Zie dat ook de menu entries goed ingesteld zijn, doe dit eventueel in de Brocade interface.

      De onderverdeling van de velden in het formulier is bepalend voor hoe de macro getMeta er gaat uitzien. Daarom is het belangrijk om eerst de structuur van het formulier goed te maken, en naderhand de oude macro’s te converteren .

      vb: je hebt 2 velden, afwezig vanaf en afwezig tot, deze staan in de b-file in de groep ‘absent’.

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      12
      13
      14
      15
      16
      $attribute: absent
          $$content:
          $$nature: group
          $$isrepeatable: 0
      $attribute: absentfrom
          $$content:
          $$group: absent
          $$nature: date
          $$min:
          $$max:
      $attribute: absentuntil
          $$content:
          $$group: absent
          $$nature: date
          $$min:
          $$max:
      

      Als je de gebruiker ophaalt met getMeta, dan krijg je terug:

      macro getMeta(RAmeta,"staff",uid)
      RAmeta("absent","absentfrom")="64115,"
      RAmeta("absent","absentuntil")="64117,"
      

      De from en until staan in de subbranch van de groep absent.

    • Ga na wat je terug krijgt van getMeta als het formulier helemaal is ingevuld of als het leeg is. (Dit is belangrijk om te weten voor 1. het omzetten van de macro’s en 2. voor de conversie.)

  3. Omzetten macro’s/globals

    Vanuit stap 1 weet je welke macro’s en globals er gebruikt worden.

    • Maak 2 tijdelijke globals aan (die je naderhand zelf kan verwijderen, dus geen Zglobals ).

      1. Backup global met daarin alles wat in de oude global(s) staat, vb: ^USERS(“users”) kopieer je naar ^USERS(“backup”,”users”).
      2. Backup global met daarin alles wat je terug krijgt van de oude macro’s, vb: ^USERS(“backups”,”naammacro”,...). Zo kan je steeds terugvallen op de structuur die je data van je nieuwe/aangepaste macro moet krijgen.
    • Beslis per macro wat je ermee gaat doen en zet ze om. De opties zijn:

      • Macro wordt behouden en wordt gewijzigd zodat het verwijst naar een andere macro, zoals getMeta. vb: Stel dat de originele macro op 100 plaatsen gebruikt wordt, dan moet je niet op elke plaats deze gaan aanpassen.

      Dus: *.d bestand wordt aangepast

      • Macro wordt behouden en doet achter de schermen iets anders wat eventueel in een routine uitgeschreven wordt. vb: De macro schrijft in meerdere globals iets weg, dan kan je deze niet zomaar vervangen/verwijderen.

      Dus: *.d bestand wordt aangepast

      • Macro wordt verwijderd en vervangen door een andere macro, vb: getMeta. Al de verwijzingen naar de originele macro moeten aangepast worden.

      Dus: *.m bestand wordt aangepast

      Let op: vergeet niet de macro’s die met r4 (en niet m4) worden opgeroepen.

    • Beslis wat je met de rechtstreeks opgeroepen globals gaat doen (ideaal zijn deze niet aanwezig).

      vb: In een formulier wordt rechtstreeks de global ^USERS(“users”,id,”ugroep”) aangesproken. Afhankelijk van het verwerken van deze global, kan je deze omzetten naar:

      • getMeta die de nieuwe waarde van ugroep ophaalt
      • een omgezette macro die met getMeta omgaat (met eventueel al extra checks zodat deze niet in het formulier moeten gebeuren)
  4. Formulier verder uitbouwen

    • Stel in de b-file de routine (in m-file) in die het sideeffect verwerkt. Hoe werkt sideeffect:

      • Bij opslaan van het formulier wordt sideeffect uitgevoerd na het opslaan van de data. Je moet dus getMeta in sideeffect doen om de nieuwe data te verkrijgen en verder te verwerken.
      • Als je setMeta doet (ook buiten het formulier) dan wordt sideeffect van dat RDtype (vb: staff) uitgevoerd.

      Voorbeelden wat je in sideeffect kan doen:

      • setMetaExtra/getMetaExtra gebruiken om vorige waardes met nieuw ingevulde waardes te vergelijken.
      • externe globals aanvullen of verwijderen, vb: indexen, voorkeursinstellingen, ...
    • Stel de testen in per veld in de b-file, deze verwijzen ook naar een routine in een m-file. Bijvoorbeeld:

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      11
      12
      13
      14
      15
      16
      $attribute: startmenu
        $$content:
        $$group:
        $$isemptying: 0
        $$nature: string
        $$iskey: 0
        $$isrepeatable: 0
        $$size: 64
        $$istextarea: 0
        $$pattern:
        $$ismpattern: 0
        $$ispypattern: 0
        $$ismarkdown: 0
        $$extratemplate: {|menu:value blank}
        $$test: d %TstMenu^gusersid
        $$lookup: menufolder
      
    • Stel eventueel een algemene test in op het gehele formulier. Deze is enkel nodig als je meerdere velden moet testen die afhankelijk zijn van elkaar.

      Vb: Een paswoord en een paswoord herhaal veld, je moet de waarde van het 1ste veld hebben om de waarde van het 2de veld te testen. Als je dit in je sideeffect doet, is het te laat. De waarde is daar al opgeslagen.

    • Stel eventuele andere extra’s in in de b-file (afhankelijk van de noden van het formulier).

  1. Testen

    Test alles wat je gemaakt hebt zeer grondig. Dit is zeker geen overbodige luxe!

    • Test de waardes en het opslaan van het formulier
    • Test wat setMeta met al je data doet.
    • ...
  2. Conversie

    • Maak een file aan in /.../release/current/zfilename.m (= conversie programma).

    • In zfilename.m: zet oude meta data over naar een array die de macro setMeta (of een andere Meta macro) kan verwerken.

      m RAold=^USERS("users",PDuser)
      macro getMeta(RAmeta,"staff",PDuser)
      ;vul RAmeta met de data van RAold
      macro setMeta(RAmeta,"staff",PDuser)
      
    • Test je conversie (zorg ervoor dat er nog geen data verwijderd wordt zodat je meerdere keren kan testen).

      Tip1: Het is niet nodig om setMetaExtra etc te gebruiken in je conversie programma. Als je de goede setMeta gebruikt, wordt er correct naar een Sideeffect verwezen die dit opvangt. (Deze heb je in een eerdere stap aangemaakt).

      Tip2: Om de conversie meerdere malen te kunnen testen zou je de nieuwe metadata moeten verwijderen vooralleer je de conversie nogmaals test. Let op dat je niet delMeta gebruikt als je nog andere globals/macro’s gebruikt. Verwijder liever de specifieke nieuwe metadata van het correcte type.

      vb: De conversie van de gebruikers heeft gelopen, maar er was een veld dat nog niet werd overgezet. De conversie is herschreven, de sideeffect verwerkt het verwijderen van een gebruiker al goed. Dus delMeta zou te veel data verwijderen waardoor de conversie niet meer zou werken (de gebruiker, met de voorkeurinstellingen worden immers al helemaal verwijderd). In mijn conversie programma schrijf ik een routine die enkel de nieuwe instance items van ‘staff’ verwijderd. vb: k ^BMETAD(“cg”,”staff”)

      Tip3: Let op dat je geen gebruik maakt van ‘oude’ macro’s. (Gebruik zo weinig mogelijk macro’s.)

      Tip4: Het is handig om een routine te schrijven die maar 1 metadata element over zet zodat je gericht en snel kan testen.

    • Vul .../release/current/filename.rst aan zodat de uit te voeren scripts die tijdens de release moeten uitgevoerd worden, er duidelijk in staan. Zorg ervoor dat er in je M code 1 lijn response is die duidelijk maakt of je routine juist/fout loopt.

In het kort:

  • Oud formulier -> Nieuwe meta data (formulier): b-file, l-file
  • Oude globals -> in backup global zetten
  • Oude macro’s -> in backup global zetten (om structuur te bekijken van o.a. get macro’s)
  • Oude globals -> nieuwe metadata (worden ingevuld via het formulier, nieuwe global structuur = automatisch)
  • Oude macro’s -> Omzetten of verwijderen
  • Nieuwe meta data -> sideeffect + eventuele testen schrijven (b-file, m-file)
  • Conversie programma maken (geen oude macro’s gebruiken) + werkplan updaten
  • Zelf alles testen + laten testen