12. Meta-informatie in Brocade
12.1. Inleiding
12.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 gedraagt t.o.v de gebruiker.
Meta-informatie is verantwoordelijk voor het grootste gedeelte van de Brocade programmatuur.
12.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
12.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 lay-out 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.
12.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 (alsliteral
) voorkomen in software. Goede keuzes zijncatsys
(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 zijnlvd
voor catalografische systemen enUA
voor eindgebruikerssystemen. Je kan in een b-file de concretisering aanspreken m.b.v. de parameterRDcg
.- 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.
Warning
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.
12.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.
12.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.
12.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, isat
False
, dan blijftat
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 bekijkencanwrite
Type attribuut: toegangsslot (
ak-loi
) dat aangeeft wie een concretisering mag aanpassencd
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.
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, hoofdletters en kleine letters bevatten. De beste praktijk is echter dat een identifier begint met een kleine letter en 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, anders alleen in de taal van de gebruiker.
nmspace
Type attribuut. Bevat de
namespace
van alle verwoordingen in verband met de type definitie. De waarde van dit attribute bestaat standaard uit de prefixmeta
en de identifier van het attribuut waarbij de eerste letter in hoofdletter staat. Voorbeeld: alle concretiseringen van het typecatsys
hebben als namespace attribuut de waardemetaCatsys
.
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
. Detemplate
wordt getoond met sleutels uitkeys
.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$attribute: reportgen 2 $$content: _system 3 $$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 bijnamespace
. Voorbeeld: alle concretiseringen van het typecatsys
hebben als set attribuut de waardemetaCatsys
.
sideeffect
Type attribuut. Dit is een M executable string die werkt met 2 standaardvariabelen
RDtype
(type) enRDcg
(concretisering). Is deze string verschillend van leeg, dan wordt deze uitgevoerd als allerlaatste stap van het updatingsproces.1$attribute: sideeffect // M instructie die wordt uitgevoerd na het filen. RDtype is het type, RDcg is de concretisering 2 $$content: _system 3 $$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) enCAkvsinp(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 desayText
macro passend omgezet) 1$attribute: test // test op de ganse structuur: leeg: test lukt; anders: type..overallTestError 2 $$content: _system 3 $$value: d %TstSide^gusersid(RDmtloi,.CAkvsinp)
- Type attribuut. Overall M routine die test op een concretisering: gegeven
testdelete
Type attribuut. Overall M routine die test op een concretisering: gegeven
RDmtloi
(LOI concretisering),RDerror
wordt gegenereerd. Is deze waarde leeg, dan kan er worden geschrapt. In het andere geval is dit een foutboodschap (wordt door desayText
macro passend omgezet)1$attribute: testdelete // RDerror leeg: test lukt en schrappen kan; anders: foutboodschap 2 $$content: _system 3 $$value: d %TstDel^gusersid(RDmtloi)
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, istp
False
, dan blijfttp
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 opgeroepen 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 beperken/verhinderen. Waarde=1 verhindert het exporteren, waarde=2 exporteert enkel de data, en niet de benamingen en scope notes. 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.
12.4. Verantwoordelijkheden bij meta-informatie
12.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 qtechng
ontwikkeltools zorgen ervoor dat dit efficiënt en foutvrij kan gebeuren.
12.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
.
12.5. Interne aspecten aan meta-informatie nieuwe stijl
Er zijn een aantal keuzes gemaakt om deze nieuwe vorm van meta-informatie vlot te organiseren.
12.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.
12.5.2. Standaard attributen
Er zijn een aantal attributen die steeds opnieuw voorkomen en die nu ook steeds dezelfde naam hebben.
12.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.
12.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.
12.5.5. Export
Er is een automatische export van de meta-informatie in 3 formaten:
Python
CSV
JSON
Er moeten dus geen ujson
modules worden gespecificeerd. Anderzijds is het wel zo dat metaman update
nieuwe versies genereert 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 tijdkritische taak.
Opmerking : deze automatische export kan men verhinderen via een te definiëren parameter (zie meta-preventexport )
12.6. Contents en meta-informatie
Key/Value stores
werkt met attributen die gegroepeerd zijn in contents
. Een content
is niets anders dan een samen horende 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 structurerende elementen: behalve de opslag worden de attributen ook per content 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
.
Important
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.
12.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 situaties 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.
12.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.
Note
Groepattributen kunnen zowel enkelvoudig als meervoudig zijn.
12.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:
12.9.1. bool
Laat toe om een attribuut met 1 van 2 mogelijke waarden te specificeren.
12.9.2. choice
Is een uitbreiding op de natuur bool
: meerdere, op voorhand gedefinieerde, waarden zijn mogelijk. Het attribuut heeft 1 van deze waarden.
12.9.3. float, integer
Het attribuut stel een getal voor.
12.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.
12.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.
12.9.6. multi
Net zoals bij choice
zijn er meerdere, op voorhand gedefinieerde, waarden mogelijk. Het attribuut kan echter meerdere van deze waarden dragen.
12.9.7. string
De waarde van het attribuut is een karakterrij.
12.9.8. table
Het attribuut stelt een tabel voor.
12.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.
Keuze van een passende identifier van het
type
Aanmaak/openen van een (bestaande)
*.b
fileInvullen van de type attributen
Specificatie van de diverse attributen
Plaats het
menuitem
in de standaard menu structuur.Vul de
lgcodes
in
12.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 woordje demosys
ziet, moet je dit vervangen door je zonet gekozen identifier.
12.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 editor 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
12.11.2.1. Het meta
object
Laten we een en ander bespreken aan de hand van een voorbeeld:
1meta demosys:
2 $attribute: tp // transaction processing
3 $$content: _system
4 $$value: 1
5 $attribute: at // audit trail
6 $$content: _system
7 $$value: 1
8 $attribute: canfreeze // slot op bevriezen
9 $$content: _system
10 $$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 /meta/application/meta.l
).
Eens de type attributen gedefinieerd (het editor 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
.
Note
De content identifier kan op volgende manieren aangevuld worden met extra informatie:
'?': de content wordt toegeklapt getoond
'?' gevolgd door een M-expressie die voorwaarden berekent om de content al dan niet te tonen. Ze moet daarvoor
RDcntShw
op 1 of 0 zetten.Indien de content onder voorwaarden en toegeklapt moet getoond worden, moeten 2 '?' gebruikt worden
Bvb.:
$$content: cat?
= toon content 'cat' toegeklapt
$$content: cat?s RDcntShw=$$%Show^bacsord
= toon content 'cat' indien aan voorwaarden voldaan
$$content: cat??s RDcntShw=$$%Show^bacsord
= toon content 'cat' toegeklapt indien aan voorwaarden voldaan
$$content: cat?s RDcntShw=$$%Show^bacsord?
= hetzelfde als voorgaande lijn
Het textadept sjabloon
om verschillende soorten attributen te definiëren. Het volgende voorbeeld toont dit:
1meta demosys:
2 $attribute: tp
3 $$content: _system
4 $$value: 1
5
6 $attribute: errorwrongcg
7 $$content: _system
8 $$value:
9
10 $attribute: typeactioncopy
11 $$content: _system
12 $$value: d %Do^baction(RDmtloi)
13
14 $attribute: yesno
15 $$content: usage
16 $$group:
17 $$isemptying: 0
18 $$nature: bool
19 $$iskey: 0
20
21 $attribute: colorchoice
22 $$content:
23 $$group: characteristics
24 $$isemptying: 0
25 $$nature: choice
26 $$iskey: 0
27 $$isrepeatable: 0
28 $$choices: green | blue | red
29 $$isselect: auto
30
31 $attribute: weight
32 $$content: characteristics
33 $$group:
34 $$isemptying: 0
35 $$nature: float
36 $$iskey: 0
37 $$isrepeatable: 0
38 $$min: 0
39 $$max: 200
40 $$size: 3
41 $$default: 0
42
43 $attribute: numberparticipants
44 $$content:
45 $$group:
46 $$isemptying: 0
47 $$nature: integer
48 $$iskey: 0
49 $$isrepeatable: 0
50 $$min: 0
51 $$max: 1000000
52 $$size: 10
53 $$default: 0
54
55 $attribute: hobbies
56 $$content:
57 $$group:
58 $$isemptying: 0
59 $$nature: multi
60 $$iskey: 0
61 $$isrepeatable: 0
62 $$choices: chess | reading | running
63
64 $attribute: country
65 $$content:
66 $$group:
67 $$isemptying: 0
68 $$nature: string
69 $$iskey: 0
70 $$isrepeatable: 2
71 $$size: 64
72 $$istextarea: 1
73 $$pattern:
74 $$ismpattern: 0
75 $$ispypattern: 0
76 $$ismarkdown: 0
77 $$lookup:
78
79 $attribute: testcase
80 $$content:
81 $$group:
82 $$nature: label
83 $$template: $RDmtloi: {$name|upper}
84 $$keygen: s RAkeyref("name")="Richard"
85 $$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
enweight
- lijn 23
voor colorchoice worden 3 mogelijke waarden bepaald.
- lijn 67
het country attribuut is herhaalbaar, de waarden worden door een
;
gescheiden.
12.11.2.2. Het history
object
Het history
object wordt compleet gegenereerd door het editor sjabloon
. De identifier is dezelfde van het meta object.
12.11.2.3. Het search
object
Het search
object wordt compleet gegenereerd door het editor 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
attribuutfilter 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 concretisering zijn. Een voorbeeld om dit duidelijk te maken: is het meta typemt: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).
Caution
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.
12.11.2.4. Het lookup
object
Het lookup
object wordt compleet gegenereerd door het editor sjabloon
. De identifier is dezelfde van het meta object.
12.11.3. Aanmaak van de lgcodes
Met een meta object worden diverse lgcodes
aangemaakt. Deze worden ook automatisch gegeneerd door de editor 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 del-files
staan initiële waarden.Verwoording voor het type
sayMetaDemosys
Voor elke
content
(vb.usage
) worden er 2 lgcodes gegenereerd:metaDemosys.titlemetaDemosysUsage
: verwoording van decontent
. Kies een korte duidelijke naam.metaDemosys.titlemetaDemosysUsage.scope
: uitgebreide beschrijving van decontent
in markdown
Een belangrijke lgcode (content
_system
) ismetaDemosys.titlemetaSystem.scope
. Deze beschrijft de meta-informatie zelf.Voor elke
attribuut
(vb.yesno
) worden er 2 lgcodes gegenereerd:metaDemosys.yesno
: verwoording van hetattribuut
. Kies een korte duidelijke naam. Het is niet nodig hier een omschrijving van het attribuut in te vullen.metaDemosys.yesno.scope
: uitgebreide beschrijving van hetattribuut
in markdown
Voor elke
groep
(vb.characteristics
) worden er 2 lgcodes gegenereerd:metaDemosys.characteristics
: verwoording van hetgroepsattribuut
. Kies een korte duidelijke naam. Het is niet nodig hier een omschrijving van het attribuut in te vullen.metaDemosys.characteristics.scope
: uitgebreide beschrijving van hetgroepsattribuut
in markdown
Voor elke optie uit
choices
(vb.red
uitcolorchoice
) worden er opnieuw 2 codes gegenereerd:metaDemosys.colorchoiceRed
: verwoording van de keuze. Kies een korte duidelijke naam. Het is niet nodig hier een omschrijving van het attribuut in te vullen.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)
metaDemosys.metaFormatTyepactioncopy
: dit is een label bij de corresponderende actiemetaDemosys.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 specifieke situatie. gebruik daartoe de instrumenten van namespaces en tekstfragmenten.
12.12. Diensten geleverd door de meta-informatie nieuwe stijl
12.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 alleloi
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
12.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.
12.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, $export=0):
'''
$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. 'eusys').
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. 'UA')
Kan ook als mt-loi worden opgegeven.
$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 de concretisering
bestaat, anders is $D(meta) = 0
2: zowel de concretisering als het attribuut moeten bestaan
$export: 1 (=meta informatie is bedoeld voor export) | 0
$example: m4_getMeta(RAeusys, "eusys", "UA")
$example: m4_getMeta(FDineu,"staff",UDuser,"inbyuser")
$example: m4_getMeta(RAdata,"mt:acqexpfilter:inopac")
'''
«d %GetCg^gbmetad(.$meta,$type,$cg,$att,$valid,$export)»
12.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:
1meta demosys:
2 $attribute: typeactioncopy
3 $$content: _system
4 $$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:
1meta demosys:
2 $attribute: typeactionname
3 $$content: _system
4 $$value: d %Do^baction(RDmtloi)
5 $$input: 1
6 $$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 )
12.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, $export=0):
'''
$synopsis: Zet extra data bij een mt-loi
$extra: M array
$ref: referentie voor deze data
$type: Meta type (vb. eusys).
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
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)
$export: 0 | 1 (exporteer ook deze extra data). In dat geval wordt aan array $extra een node '_export_')=1 toegevoegd.
$example: m4_setMetaExtra(RAdata, "myref", RDmtloi)
$example: m4_setMetaExtra(RAdata, "myref", RDmtloi, export=1)
'''
«d %SetExtr^gbmetad(.$extra,$ref,$type,$cg,$overwrite,$export)»
macro getMetaExtra($extra, $ref, $type="", $cg=""):
'''
$synopsis: Zet extra data bij een mt-loi
$extra: M array. Ingeval de $extra("_export_")=1, dan is de extra data ook voor export bestemd.
$ref: referentie voor deze data. Indien leeg, dan bevat $extra(ref)=een M array voor alle voorkomende referenties.
$type: Meta type (vb. eusys).
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
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)
$example: m4_getMetaExtra(RAdata, "smeta", "server", "moto")
'''
«d %GetExtr^gbmetad(.$extra,$ref,$type,$cg)»
macro delMetaExtra($ref, $type="", $cg=""):
'''
$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. eusys).
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
Kan ook als mt-loi worden opgegeven.
Indien $cg leeg is, dan wordt de meta informatie van het type opgespoord
$example: m4_delMetaExtra("myref", RDmtloi)
$example: m4_delMetaExtra("myref", RDtype, RDcg)
'''
«d %DelExtr^gbmetad($ref,$type,$cg)»
12.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 vantype
te capitaliseren. (vb.Demosys
)
12.12.7. Controleer of meta-informatie bestaat
macro isMeta($xis, $type="", $cg=""):
'''
$synopsis: Bestaat de meta data ?
$xis: 0 (=metadata bestaat en is actief)
1 (=metadata bestaat niet)
$type: Meta type (vb. eusys)
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
Kan ook als mt-loi worden opgegeven.
$example: m4_isMeta(xis, "eusys", "UA") 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)»
12.12.8. Standaard test op meta-informatie
macro checkMeta($error, $type="", $cg="", $min=0, $max=0, $lg="", $accepted=MDaccept):
'''
$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. eusys)
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, "eusys", "UA;UH")
'''
«k MDaccept s $error=$$%Error^gbmetad($type,$cg,$min,$max,$lg,.$accepted)»
12.12.9. Verwoordingen van meta-informatie
macro sayMeta($say, $type="", $cg="", $lg="", $enc="", $default=«" "»):
'''
$synopsis: Verwoord de meta data
$say: Verwoording
$type: Meta type (vb. eusys)
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
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, "eusys", "UA")
'''
«s $say=$$%Say^gbmetad($type,$cg,$lg,$enc,$default)»
12.12.10. Wildcard selectie op concretiseringen
macro globMeta($array, $glob="*", $onlyreadable=0, $onlywriteable=0, $staff="", $select=0):
'''
$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) | 2 (2= maak een array met enkel de id's ($p(mtloi,":",3))
$example: m4_globMeta(RAlist, "mt:eusys:l*")
'''
«d %Glob^gbmetad(.$array,$glob,$onlyreadable,$onlywriteable,$staff,$select)»
12.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):
'''
$synopsis: Bereken een array met als subscripts de concretiseringen met een gegeven patroon
$select: string met de <option>s
$type: Meta type (vb. eusys)
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(select,$type="dialog",$template="say",$default="",$lg="N",$cgonly=1)
'''
«k MDli s $select=$$%Select^gbmetad($type,$template,$glob,$default,$lg,$onlyreadable,$onlywriteable,$staff,.$list,$cgonly,$prefix,$withempty)»
12.12.12. Toegang tot een meta object van een Brocade gebruiker nagaan
macro isMetaReadable($xis, $type="", $cg="", $staff=""):
'''
$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. eusys)
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
Kan ook als mt-loi worden opgegeven.
$staff: personeelslid (default: UDuser)
$example: m4_isMetaReadable(xis, "eusys", "UA", staff="rphilips" ) i xis w "rphilips mag niet lezen"
'''
«s $xis=$$%Xisread^gbmetad($type,$cg,$staff)»
macro isMetaWriteable($xis, $type="", $cg="", $staff=""):
'''
$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. eusys)
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
Kan ook als mt-loi worden opgegeven.
$staff: personeelslid (default: UDuser)
$example: m4_isMetaWriteable(xis, "eusys", "UA", staff="rphilips" ) i xis w "rphilips mag niet aanpassen"
'''
«s $xis=$$%Xiswrit^gbmetad($type,$cg,$staff)»
macro isMetaCreateable($xis, $type="", $staff=""):
'''
$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. eusys)
Kan ook als mt-loi worden opgegeven.
$staff: personeelslid (default: UDuser)
$example: m4_isMetaCreateable(xis, "eusys", staff="rphilips" ) i xis w "rphilips mag niet aanmaken"
'''
«s $xis=$$%Xiscrea^gbmetad($type,$staff)»
macro isMetaFreezable($xis, $type="", $cg="", $staff=""):
'''
$synopsis: Kan een personeelslid de data bevriezen
$xis: 0 (=metadata mag bevroren worden)
=metadata bestaat niet of is biet actief)
=metadata is reeds bevroren)
=personeelslid heeft niet voldoende pivileges)
$type: Meta type (vb. eusys)
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
Kan ook als mt-loi worden opgegeven.
$staff: personeelslid (default: UDuser)
$example: m4_isMetaFreezable(xis, "eusys", "UA", staff="rphilips" ) i xis w "rphilips mag niet bevriezen"
'''
«s $xis=$$%Xisfrz^gbmetad($type,$cg,$staff)»
macro isMetaThawable($xis, $type="", $cg="", $staff=""):
'''
$synopsis: Kan een personeelslid de data ontdooien
$xis: 0 (=metadata mag ontdooid worden)
=metadata bestaat niet of is niet actief)
=metadata is niet bevroren)
=personeelslid heeft niet voldoende privileges)
$type: Meta type (vb. eusys)
Kan ook als mt-loi worden opgegeven.
$cg: Identifier voor de concretisering (vb. UA)
Kan ook als mt-loi worden opgegeven.
$staff: personeelslid (default: UDuser)
$example: m4_isMetaThawable(xis, "eusys", "UA", staff="rphilips" ) i xis w "rphilips mag niet ontdooien"
'''
«s $xis=$$%Xisthw^gbmetad($type,$cg,$staff)»
12.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.
12.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.
12.12.15. Importeer meta data
Voor software engineers is een menu optie voorzien : Importeer metadata [link] . De juistheid van de data wordt gecheckt, de toegang wordt via de menu-ingang geregeld.
12.12.16. Valideer de inhoud van (alle) aanwezige meta data
Dit kan via gebruiksproces : Check metadata [link] . Een lijst van fouten wordt gegenereerd.
12.13. Voorbeelden uit de praktijk
Dit hoofdstuk beschrijft (vindingrijke) oplossingen voor diverse problemen die zich voordoen in de praktijk.
12.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:
1meta mytype:
2 $attribute: idfree
3 $$content: _system
4 $$value: 1
5 $attribute: skiplanguages
6 $$content: _system
7 $$value: 1
8 ...
Er wordt dan geen test gedaan op de naam van de identifier en er worden ook geen namen gevraagd.
12.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 voor een tekstfragment. Dit tekstfragment kan dan elders worden aangepast.
Dit kan eenvoudig zoals in het volgende voorbeeld:
1meta mytype:
2 ...
3 $attribute: opacname
4 $$content:
5 $$group:
6 $$isemptying: 0
7 $$nature: string
8 $$iskey: 0
9 $$isrepeatable: 0
10 $$size: 64
11 $$istextarea: 0
12 $$pattern:
13 $$ismpattern: 0
14 $$ispypattern: 0
15 $$ismarkdown: 0
16 $$extratemplate: ${value|textfragment}
17 $$test:
18 $$lookup:
Meer geavanceerd (en beter) is evenwel de volgende manier:
1meta mytype:
2 ...
3 $attribute: opacname
4 $$content:
5 $$group:
6 $$nature: label
7 $$template: {|ng}{pkgenreform${sys}.opacname|textfragment FDedmode|? sys}
8 $$keygen: k RAkeyref s RAkeyref("sys")=$P(RDmtloi,":",3)
12.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.
12.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.
12.16. Upload elementen in het webformulier
Indien het webformulier één of meerdere upload-elementen bevat, dan moet het FORM
element het attribuut enctype="multipart/form-data"
krijgen.
Dit kan geforceerd worden door in het keygen attribuut van het upload-element de variabele FDmtupload=1
te zetten.
12.17. 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.
12.17.1. Stappenplan
Onderstaande is een guideline. De volgorde is zeker niet heiligmakend en veel processen gebeuren door elkaar.
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 voorkeursinstellingen 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.
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$attribute: absent 2 $$content: 3 $$nature: group 4 $$isrepeatable: 0 5$attribute: absentfrom 6 $$content: 7 $$group: absent 8 $$nature: date 9 $$min: 10 $$max: 11$attribute: absentuntil 12 $$content: 13 $$group: absent 14 $$nature: date 15 $$min: 16 $$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.)
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 ).
Backup global met daarin alles wat in de oude global(s) staat, vb: ^USERS("users") kopieer je naar ^USERS("backup","users").
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)
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$attribute: startmenu 2 $$content: 3 $$group: 4 $$isemptying: 0 5 $$nature: string 6 $$iskey: 0 7 $$isrepeatable: 0 8 $$size: 64 9 $$istextarea: 0 10 $$pattern: 11 $$ismpattern: 0 12 $$ispypattern: 0 13 $$ismarkdown: 0 14 $$extratemplate: {|menu:value blank} 15 $$test: d %TstMenu^gusersid 16 $$lookup: menufolderStel 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).
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.
...
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 vooraleer 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 voorkeursinstellingen 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