5. Mutil : de M(umps) toolkit van de derde generatie

5.1. Inleiding

Dit document beschrijft het gebruik van de toolcat applicatie mutil, een systeem toolkit op één (of meerdere) M databank(en).

5.2. Mutil : het idee

Toen met mutil begonnen werd, hadden wij een aantal betrachtingen :

  • Maak een tool, die operaties uitvoert op de M databank(en).

  • Zorg ervoor, dat de commando's zo eenvoudig en transparant mogelijk zijn

  • Mutil is een schil over de vendor systeemtools, die je het leven makkelijk(er) maakt.

  • Maak enkel gebruik van de core packages van Brocade, zodat mutil ook tot core package kan worden verheven.

  • Zorg ervoor, dat deze tool werkt, zonder voorafgaandelijk inladen van M routines

  • Laat eenvoudiger constructies toe in de commandline

  • Volledige ondersteuning van zowel Caché, YottaDB, als GT.M/YottaDB

Wij zijn hierin uiteindelijk geslaagd. Bij een tweede grote herziening hebben we een aantal betrachtingen toegevoegd :

  • Zorg ervoor, dat deze tool werkt voor meerdere geïnstalleerde M systemen, ook al zijn ze van verschillende origine, of toch voor die toepassingen, waar er nood is, zoals import en export van M objecten.

  • Maak een configuratietool, die je toelaat zo transparant mogelijk je M systeem(en) in kaart te brengen.

  • Maak een toolkit voor journal files. (zowel voor Cache als GT.M/YottaDB, uiteraard)

  • Zorg voor transparante import- en exportprocedures.

  • Maak modifiers optioneel, daar, waar de software ze zelf kan 'raden'.

5.3. Uci's en regions : een andere kijk op M databanken.

Een uci bepaalt de M database omgeving. Binnen een uci staat het vast, waar je globals en routines zich bevinden. Ze wordt steeds geassocieerd met een directory en een acroniem. Voor GT.M/YottaDB databases is deze directory de plaats, waar zich een global configuratiefile glo.gld bevindt. Het acroniem is een arbitrair gekozen afkorting, bepaald binnen de mutil configuratie

Voor Caché en ISM systemen is deze directory de plaats, waar de file CACHE.DAT zich bevindt, die de Caché namespace bevat. Hier is het acroniem ook een arbitrair gekozen afkorting, bepaald binnen de mutil configuratie, doch doorgaans is dit naam van de Caché namespace.

De ingave van het argument namespace is case-ongevoelig. Men gaat ervan uit, dat er steeds een default uci bestaat, en deze wordt gekenmerkt door het acroniem db (= DB) en de directory naam in registry waarde m-db.

  • Voorbeeld : DBX

  • Voorbeeld : /library/database/brocade/base/0/

Een region bepaalt de plaats van een M database segment. Een of meerdere regions vormen samen een uci. Een region wordt bepaald door de naam van een file, die (een deel van) een M database bevat, en de naam van een acroniem, dat uniek is binnen de uci waarin ze wordt gedefinieerd.

Voor Caché systemen is er slechts één region per uci. Haar acroniem is steeds DEFAULT.

Voor GT.M/YottaDB systemen is een mutil region niets anders dan een GT.M/YottaDB region. Haar acroniem wordt bepaald binnen de GT.M/YottaDB configuratie.

  • Voorbeeld : DEFAULT

  • Voorbeeld : /library/database/brocade/base/0/CACHE.DAT

  • Voorbeeld : /library/database/brocade/base/0/mumps.dat

  • Voorbeeld : /library/database/brocade/base/0/x.dat

5.4. Mutil en meerdere M versies : primaire en secundaire M versies

Mutil kan nu ook gebruikt worden voor meerdere M versies. Zo kan je op eenzelfde server zowel een GT.M/YottaDB versie draaien, en tegelijk een Caché versie. Maar gemixte versies, zoals een GT.M/YottaDB release 5.4 naast GT.M/YottaDB release 5.5 zijn ook denkbaar. De door mutil aangeboden functionaliteit is echter begrensd. Daarom spreekt men hier over twee types M versies :

  • Er is steeds één en slechts één primaire M versie, Deze is steeds de versie, die wordt gebruikt voor uci db. Ze is ook degene, waar Brocade toepassingen starten. Er is hier geen beperking op de mutil functionaliteit.

  • Alle andere geïnstalleerde M versies zijn secundair. De ondersteuning van mutil is vooral erop gericht om deze M systemen te benutten als test omgevingen, voor conversie doeleinden, e.a. . Typische ondersteunde mutil operaties zijn import en exports, uitlijsten van M objecten,.. maar niet : het starten/stoppen van het M systeem, backup/restore en dashboards om de actuele status e.d. te controleren.

5.5. Modifiers in mutil : enkele bemerkingen

Je merkt dat mutil een toolcat applicatie van de derde generatie is, want er wordt gretig gebruik gemaakt van modifiers. We lichten er enkele veel voorkomende toe, die steeds dezelfde betekenis hebben :

  • uci

    • Bepaalt de M database omgeving. Zie voorgaande paragraaf.

    • Voorbeeld : uci=DBX

    • Voorbeeld : uci=/library/database/brocade/base/0/CACHE.DAT

  • cwd

    • Bepaalt de 'current working directory', zoals trouwens in elke toolcat applicatie. Niet te verwarren met voorgaande.

    • Voorbeeld : cwd=/library/process/myapp

  • zip

    • Logische modifier. Bepaalt of een resultaat moet gezipt worden.

    • Voorbeeld : zip=Yes

    • Voorbeeld : zip=1

    • Voorbeeld : zip=No

5.6. Vereenvoudiging

Expliciete referenties naar files of directories zijn niet strikt nodig. Zo kan je bij voorbeeld heel kort het volgende doen

mutil gout BPRED

Hier wordt dan in de current working directory een global output gemaakt van de global BPRED in (default) zwr formaat.

Refereren naar files, directories, .. wordt duidelijker:

  • Dit kan : mutil gout BPRED file=/library/process/BCATlvd.mout format=m

  • Maar evengoed kan dit ook : mutil gout BPRED cwd=/library/process file=BCATlvd.mout format=m

Verwijzingen naar M namespace omgevingen kunnen ook met de uci acroniemen :

  • Dit kan : mutil gout XBCAT uci=/library/database/db/basex/0

  • Maar dit doet hetzelfde : mutil gout XBCAT uci=dbx

Al naargelang kan men een resultaat gezipt kiezen of niet, d.m.v. modifier zip.

  • mutil rout '%*' uci=mgr cwd=/backup/somedir zip=yes

En dit zijn slechts enkele voorbeelden ter illustratie.

5.7. Mutil gebruiken binnen python scripts : mtoolkit

Je kan ook alle functionaliteit op volgende manier inbouwen in andere python scripts:

  • Voeg from anet.mutil import mtoolkit toe aan je script.

  • Voor de overige functionaliteit verwijzen we graag naar het script mtoolkit.py zelf.

5.8. Mutil als configuratietool : mutil config

Aan boord van mutil zit nu ook een uitgebreide configuratietool, die je toelaat de verschillende uci's, regions - ook over verschillende M systemen heen - te configureren.

  • mutil config init initialiseert een nieuwe configuratiefile mutil.ini, in de start folder, bepaald door (core) delphi waarde m-db. Het systeem tracht zelf alle informatie over uci's, regions, ... te verzamelen. Het bestand mutil.ini is een asci bestand, met een zodanige layout, dat je makkelijk zelf in een tekst editor kan wijzigen of deze zelfs kan aanmaken.

    De nieuw aangemaakte configuratie bevat enkel de informatie m.b.t. de primaire M versie. Het referentiepunt hiervoor vormt de delphi waarde m-db. Secundaire M versies of meerdere, niet-default namespaces moeten manueel worden toegevoegd.

    Bestaat de file reeds, dan gebeurt er niets, tenzij je uitvoert:

    mutil config init force=yes

  • Het is best mogelijk, om zonder configuratiefile te werken : in dat geval worden - indien nodig - de parameters bepaald a.d.h.v. het levende systeem (net zoals in vorige releases). Eenmaal er een configuratiefile bestaat, wordt met hem rekening gehouden.

  • mutil config delete schrapt gewoon de mutil configuratiefile mutil.ini

  • mutil config show vertelt, waar de configuratiefile zich bevindt, en lijst de configuratie uit. Voorbeeld

    mutil config show

-- uci config --
configfn = /library/database/brocade/base/0/mutil.ini

Uci DB : mdir='/library/database/brocade/base/0', mostype='gtm' :
 region DEFAULT in /library/database/brocade/base/0/mumps.dat :
  - journalling is True, mode=before , journal path=/library/mumps/journal/gtm/default.mjl , purge after 2 days

 region X in /library/database/brocade/base/0/x.dat :
  - journalling is True, mode=before , journal path=/library/mumps/journal/gtm/x.mjl , purge after 2 days

 region Z in /library/database/brocade/base/0/z.dat :
  - journalling is False, mode=nobefore

Uci DBCACHE : mdir='/lv3/db', mostype='cache' , *non-active*:
 region DEFAULT in /lv3/db/CACHE.DAT

  • mutil config install voer je best uit, nadat je de configuratiefile mutil.ini hebt aangepast. Hiermee worden eventuele nieuwe start- en stopscripts aangemaakt. Geen nood, indien je dit vergeet : bij een opstart mutil -start worden deze aangemaakt, indien nodig.

  • mutil config check controleert of het nodig is om nieuwe start- en stopscripts aan te maken, en doet dit ook desgevallend.

  • mutil config refresh voer je best uit, nadat je - via de tools, eigen aan het M systeem - regions hebt gewijzigd of uci's hebt aangemaakt. De aanwezige uci configuratieparameters worden niet gewijzigd : dit laat je toe, om eventueel manuele wijzigingen niet te verliezen. Zo dadelijk daarover meer.

Bekijken we even de parameters binnen mutil.ini : Voorbeeld:

pg /library/database/brocade/base/0/mutil.ini

[uci_DBCACHE]
active = False
stat = True
mostype = cache
mdir = /lv3/db

[reg_DBCACHE_DEFAULT]
journalmode =
journalpurge =
journalpath =
journalling = True
journaluse = 97
file = /lv3/db/CACHE.DAT

[uci_DB]
active = True
stat = True
mostype = gtm
mdir = /library/database/brocade/base/0

[reg_DB_X]
journalmode = before
journalpurge = 2,0
journalpath = /library/mumps/journal/gtm/x.mjl
journalling = True
file = /library/database/brocade/base/0/x.dat

[reg_DB_Z]
journalmode = nobefore
journalpurge =
journalpath =
journalling = False
file = /library/database/brocade/base/0/z.dat

[reg_DB_DEFAULT]
journalmode = before
journalpurge = 2,0
journalpath = /library/mumps/journal/gtm/default.mjl
journalling = True
file = /library/database/brocade/base/0/mumps.dat

[uci_DBBACKUP]
mdir = /library/brocadefull
mostype = gtm
stat = False
active = True
instance =
instname =
logdir = /library/brocadefull
readonly = True

[reg_DBBACKUP_DEFAULT]
file = /library/brocadefull/mumps.dat
journalpath =
journalling = False
journalmode = before
journalpurge = 7
journalbackup =

[replication_originating_DB_DB2]
active = False
destip =
destuci =
destport =
buffsize = 1048576

[replication_replicating_DBBACKUP]
active = False
listenport =
buffsize =

Je vindt vier soorten paragrafen :

  • [uci_*acroniem uci*] bevatten de parameters per uci. Deze worden overschreven bij commando mutil -config init force=yes

    Het *acroniem uci* bepaalt de naam van de uci, zoals ze wordt gebruikt in mutil. Hoewel dit doorgaans dezelfde naam heeft als de M namespace, kan deze toch afwijken ervan. Ze moet in ieder geval uniek zijn binnen eenzelfde mutil.ini configuratie.

  • [reg_*acroniem uci*_*acroniem region*] bevatten de parameters per region. Deze worden overschreven bij commando mutil -config refresh.

    Bij GT.M/YottaDB installaties is acroniem region = de effectieve naam van de region.

    Bij Caché installaties is steeds acroniem region = DEFAULT .

  • [replication_originating_*acroniem uci*_*remote instname*] bevatten de parameters van de replicatie van de data in de uci naar een machine met een bepaalde instance naam. Deze worden nooit overschreven .

    Bij GT.M/YottaDB installaties is remote instname een unieke naam, over alle servers heen. Ze hoort bij de uci op de remote server, die de gerepliceerde data zal ontvangen.

    Bij Caché installaties is dit niet geimplementeerd.

  • [replication_replicating_*acroniem uci*] bevatten de parameters, die beschrijven hoe de uci mirror speelt van een ander systeem. Deze worden nooit overschreven .

    Bij Caché installaties is dit niet geimplementeerd.

De uci parameters zijn:

  • active vertelt of de uci wordt gebruikt. Bevat een Booleaanse waarde. False heeft het zelfde effect, als zou je de paragraaf uitvegen.

  • stat vertelt of er statistieken moeten worden bijgehouden over het verloop van de bezettingsgraad. Bevat een Booleaanse waarde.

  • mostype vertelt het type van M implementatie. Bevat een van volgende woorden : gtm cache ism

  • mdir bevat de naam van de directory, geassocieerd met de uci.

    Voor Caché systemen is dit de directory, waar de file CACHE.DAT zich bevindt.

    Voor GT.M/YottaDB systemen is dit de directory, waar de (kleine) file glo.gld, zich bevindt.

  • readonly Optioneel. Indien dit de waarde True bevat, dan houdt mutil er rekening mee, dat dit een readonly uci is. Dit speelt o.m. ook een rol bij gemirrorde databanken. Default=False.

  • instance Optioneel. Bevat de naam van de replicatie file, die de huishouding van de replicatie voor zich neemt. Voorbeeld : /etc/gtm.repl .

  • instname Optioneel, en enkel belangrijk voor replicatie. Bevat een unieke naam, geassocieerd met de uci. Deze naam moet uniek zijn over alle Brocade servers heen. Van zodra deze waarde is ingevuld, treedt replicatie in werking : zelfs al zijn er geen bestemmingen voor de replicatie, toch wordt de replicatie geactiveerd op alle regions, waar journalling geactiveerd is, en draait een zogenaamde 'dummy' source server, die voornamelijk ervoor zorgt, dat er een journaal buffer pool wordt aangemaakt en onderhouden. Voorbeeld : Oostende . Als je van plan bent om in de toekomst mirrors op te zetten, dan moet je dit voorafgaand invullen.

  • logdir Optioneel. De dircetory naam, waar de logings van M systeemprocedures terechtkomen.

De reg(ion) parameters zijn:

  • file bevat de naam van de database file van de region.

  • journalling vertelt of journalling actief is. Bevat een Booleaanse waarde.

  • journalmode bevat de waarden before of nobefore. Enkel relevant voor GT.M/YottaDB.

  • journalpurge Enkel relevant voor GT.M/YottaDB. In een Cach&ecaute; uci wordt dit geregeld via de huiseigen tools. Bevat het aantal dagen, waarna journal files mogen worden gewist. Dit kan ook twee getallen bevatten, gescheiden door een komma : het tweede getal is dan geldig bij de journal noodprocedure (zie journaluse) .

  • journalpath bevat de posix path naam, waar journal files terechtkomen. Voor GT.M/YottaDB systemen is de naam van de file relevant, voor Caché systemen is de naam van de directory relevant ; de naam van de journal file wijzigt dynamisch binnen dezelfde directory.

  • journalbackup bevat de locatie, waar een backup wordt bijgehouden van de journal files. Deze backup wordt enkel aangevuld. Elk argument dat kan dienen als target van een rsync operatie is geldig. Voorbeelden : /library/archive/journal backup.uantwerpen.be:/library/moto/journal .

  • journaluse (Optioneel). Bevat een geheel getal tussen 1 en 100. Het stelt een maximum gebruikspercentage voor van het filesysteem, dat de journal files bevat. Eenmaal dit percentage bereikt, wordt bij het wissen van de journal files een noodprocedure gebruikt, waarbij de voorkeur wordt gegeven om te vermijden, dat een filesysteem volloopt, boven bvb. de synchronisatie met replicatie servers. Enkel relevant voor GT.M/YottaDB. In een Cach&ecaute; uci wordt dit geregeld via de huiseigen tools. Voorbeeld : 98.

De replication originating parameters zijn:

  • active vertelt of de replicatie actief is. Bevat een Booleaanse waarde.

  • destip ip adres van de mirror

  • destport tcp poort nr van de mirror

  • destuci naam van de ontvangende uci op de mirror. Default = 'db'

  • buffsize buffer size van de replicatiebuffer. Zie GT.M/YottaDB documentatie. Voorbeeld : 33554432

  • filterexe executable, die als filter dient bij de replicatie. Deze filter wordt aan de bron toegepast. Zie GT.M/YottaDB documentatie. Indien deze executable spaties bevat, dient ze tussen quotes te worden gezet. Voorbeeld : "sed '/^.*^BLIST.*$/! s/^.*$//g'"

De replication replicating parameters zijn:

  • active vertelt of de replicatie actief is. Bevat een Booleaanse waarde.

  • listenport poort nummer, waar de replicating service haar updates ontvangt van het originating systeem

  • buffsize buffer size van de replicatiebuffer. Zie GT.M/YottaDB documentatie. Voorbeeld : 33554432

  • filterexe executable, die als filter dient bij de replicatie. Deze filter wordt aan de bestemming toegepast. Zie GT.M/YottaDB documentatie. Indien deze executable spaties bevat, dient ze tussen quotes te worden gezet. Voorbeeld : "sed '/^.*^BLIST.*$/! s/^.*$//g'"

5.9. Statusinformatie over het geinstalleerde M systeem.

''mutil info`` verschaft je allerlei informatie over de configuratie en de geinstalleerde componenten van het M systeem. Het komt in twee varianten:

  • mutil info verschaft algemene informatie over het geïnstalleerde M systeem.

  • mutil info [keyword] verschaft je meer gedetailleerde informatie, en het thema wordt bepaald door keyword. mutil help info verschaft je een up-to-date waaier aan mogelijkheden. We lichten een aantal verrassende dingen toe aan de hand van enkele voorbeelden.

  • mutil info glo BCAT : verschaft je informatie over global BCAT, in welke region deze zich bevindt, statistieken over de grotte en hoeveelheid records,..

  • mutil info file myfile.zwr verschaft je informatie over een file, en hoe mutil hiermee zou omgaan.

  • mutil info var UDuser : verschaft je informatie over M variabele UDuser, en hoe deze wordt gebruikt en gemanipuleerd in de actuele geinstalleerde M routines, op basis van de laatste analyse.

  • mutil info obj project: verschaft je informatie over waar project als identificatie wordt gebruikt in de actuele M installatie; ze tracht ook ineens afgeleide gegevens op te sporen en te tonen. Voorbeeld van een output:

lookup project : Project:
    -history       : project :
    -menuitem      : d %Exec^ugnoizk("pr",$g(RDextra)) :
history project : Project :
mitem project : Nieuw/bewerk project
    -url           : <mcgi routine="Entry:ugnwedit">&FDgntymenu=pr
    -parent        : ir (Institutional repositories) :
    -path          : /ir/project/irproject.b :
mroutine ugnwedit:
    -created       : 15.03.2023 14:16:57 (adescamp) :
    -modified      : 20.09.2023 17:04:28 (adescamp) :
    -path          : /gnoi/app/ugnwedit.m :
mfolder ir : Institutional repositories:

5.10. Statusinformatie over het actuele M systeem.

  • mutil status keyword(s) toont statusinformatie van het actueel draaiende M systeem. Mogelijke keywords zijn (je kan ze ook combineren):

    • locks : de actueel geplaatste M locks

    • jobs : een overzicht van de lopende M processen

    • sys : informatie over het lopende besturingssysteem , met betrekking tot M

    • jou : actuele informatie over journalling

    • repl : actuele informatie over replicatie, zowel receiving als originating

    • qu : de momentele wachtrij van uit te voeren M jobs

    • stats : cijfers over de actuele M database

    • jou : verschaft informatie over de actuele toestand i.v.m. journalling.

    • all : alle voorgaande

    • probe : een commando, speciaal bedoeld om een probe test te kunnen samenstellen op een levend systeem. Zo worden o.m. volgende checks uitgevoerd: - Is M aanspreekbaar ? (Hello World test) - Zijn er geen web-gerelateerde M processen, die te lang duren ? - Is de journal space niet in een noodsituatie ? - Zijn er geen replicatie servers, die te ver achterlopen ? Indien alles ok is, verschijnt de geijkte melding 'M tested succesfully'

  • mutil jobexam [jobnr] verschaft informatie over M proces waarvoor $j=jobnr. Bijkomende modifier var=var of var=* laat je zelfs toe het verloop van de waarde van bepaalde M variabelen te volgen.

  • mutil status db geeft een overzicht van de M databanken en hun grootte en vullingsgraad.

  • mutil chk integrity voert een Integrity check uit op de databank en bericht hierover.

5.11. Import/Export van M routines

Routine export : enkele voorbeelden :

  • mutil rout mroutine leest de broncode van M routine mroutine uit in file mroutine.ro in de current working directory.

  • mutil rout bca* cwd=/library/tmp target=bcaall.ro leest de broncode van alle M routines met prefix bca uit in file /library/tmp/bcaall.ro

  • mutil rout bca* target=/library/tmp/bcaall.ro doet precies hetzelfde.

  • mutil rout '%*' uci=mgr haalt de routines uit manager directory, startend met een %

  • mutil rout '*' cwd=/library/tmp exporteert de broncode van alle routines, waarbij de broncode van mroutine terecht komt in een file /library/tmp/mroutine.ro

  • mutil rout '*' cwd=/library/tmp target=all.ro exporteert de broncode van alle routines in één file /library/tmp/all.ro

  • mutil rout '*' target=/library/tmpall.ro doet precies hetzelfde

Routine import : enkele voorbeelden :

  • mutil rin bcawabc source=/library/tmp leest de broncode van M routines in, die zich in file /library/tmp/bcawabc.ro bevinden.

  • mutil rin /library/tmp/bcawabc.ro doet precies hetzelfde.

  • Ook wildcards van filenamen zijn veroorloofd : mutil -rin /library/tmp/bcaw* . Let wel, verwacht wordt een filenaam, die niet noodzakelijk de naam van een M routine voorstelt.

  • Modifier option=skip laat je toe bestaande M routines te skippen.

5.12. Import/Export van M globals

Voor het importeren en exporteren van M globals kom je toe met twee commando's :

  • mutil gout exporteert globals. Uitgebreide documentatie vind je via mutil help gout.

  • mutil gin importeert globals. Uitgebreide documentatie vind je via mutil help gin.

5.13. Uitvoeren van M code

Vanuit de Unix prompt kan je een M commando uitvoeren met behulp van argument exe. Enkele voorbeelden :

  • Dit roept eenvoudigweg routine routine op, en schrijft het resultaat op standaard output : mutil -exe ^routine

  • Dit kan ook : mutil exe Entry^routine

  • En zelfs met argumenten : mutil exe Entry^routine("a","b")

  • Je kan ook rechtstreeks een M instructie opgeven : mutil exe 'w "Hello",!'

  • De output kan je als volgt opvangen in een bestand : mutil exe 'w "Hello",!' stdout='/library/tmp/hello.out'

Je kan ook argumentloos werken, en dan tuimel je in direct mode :

  • Dit kan : mutil exe

  • En is precies hetzelfde als : mutil direct

  • En dit kan ook : mutil direct uci=dbcache en werkt ook voor secundaire M databanken.

Een file met M lijnen kan je uitvoeren via argument min = 'M(umps) in(put)' (Dit is een synoniem voor gin, trouwens). Gezipte files worden ook uitgelezen zonder dat ze eerst worden uitgepakt.

  • mutil min ZC.mout voert de M code uit, die zich bevindt in file ZC.mout . Eventuele output komt op standaard output terecht.

  • mutil min ZC doet net hetzelfde.

  • Uiteraard kan je explicieter je filenaam aanduiden, en wildcards zijn ook toegelaten :

    • mutil min '/library/process/conversion/BCAT*' en

    • mutil min 'BCAT*' cwd=/library/process/conversion doen net hetzelfde.

Om vanuit een python toepassing M code uit te voeren, val je best terug op de core module mumps. In Interactie tussen Python3 en Mumps gaat men uitgebreid in op dit onderwerp. Volgende constructie in python is evenwel ook geldig, en voert de M instructies uit die zich in file filename bevinden :

  • from anet.mutil import mtoolkit

    mtoolkit.mexefile(filename, stdout=None)

5.14. M backup/restore

De backup faciliteit binnen mutil levert je geen kant-en-klare backup procedure op, maar wel een aantal middelen om deze te verwezenlijken. Het is de bedoeling om via het beheer van automatische processen een aangepaste lijst van backup instructies samen te stellen.

Hier spreekt men naast het begrip uci ook over een region. Daar, waar een uci verwijst naar een directory als referentie naar een database omgeving, verwijst een region steeds naar een database file, die een (deel van een) database bevat. Voor een overzicht kan je beide oplijsten:

  • mutil list uci

  • mutil list reg

Per directory kan er slechts één M systeem actief zijn.

5.15. Uitlijsten van M objecten : mutil list

Volgende typische M objecten kunnen worden uitgelijst op standaard output : (we illustreren met enkele voorbeelden)

  • mutil -list uci : lijst alle uci's uit, die gekend zijn in deze configuratie.

  • mutil -list reg : lijst alle gekende regions uit, die gekend zijn in deze configuratie.

  • mutil -list glo '*' : lijst alle globals uit.

  • mutil -list glo 'BCA*' 'BOJ*' uci=DBCACHE : lijst alle globals uit, gekend in uci DBCACHE, en waarvan de naam begint met 'BCA' of 'BOJ'

  • mutil -list rou 'u*' : lijst alle routines uit, waarvan de naam begint met de letter 'u'.

5.16. Schrappen van M objecten

De vier types M objecten, die kunnen geschrapt worden, zijn routines, globals, M jobs en Cache globals. Een toelichting aan de hand van enkele voorbeelden :

  • mutil kill rou 'za*' schrapt de routines, waarvan de naam begint met za

  • mutil kill rou 'za*' test=yes toont op stdout de namen van de routines, die zouden geschrapt worden.

  • mutil kill rou 'za*' test=yes toont op stdout de namen van de routines, die zouden geschrapt worden.

  • mutil kill glo 'ZAD*' 'ZMUTIL' schrapt de globals, waarvan de naam begint met ZAD, en de global ZUTIL.

  • mutil kill glo 'ZAD*' 'ZMUTIL' uci=dbx doet hetzelfde in namespace dbx

Enkele doordenkertjes :

  • mutil kill glo ZAD*.zwr zoekt de files, die beantwoorden aan de match ZAD*.zwr in de huidige directory, en houdt dan die namen over, waar de basename van de file toevallig een bestaande global is

  • mutil kill glo ZAD* doet hetzelfde met de match ZAD*

  • mutil kill glo 'ZAD*' killt alle globals, waarvan de naam met ZAD begint. Dit is dus wezenlijk verschillend van het vorige.

  • mutil kill glo /library/process/someplace/ZAD*.gof is ook een zinnige constructie

5.17. Import van csv bestanden

Dit illustreren we met enkele stichtende voorbeelden :

  • mutil csvin test.csv ZCSV node1 node2 schrapt global node k ^ZCSV("node1","node2"), en leest de inhoud van de file test.csv in de current directory in de global. De inhoud van de verschillende cellen komen terecht in ^ZCSV("node1","node2",rijnummer,kolomnummer)=inhoud Alle argumenten, buiten het eerste, worden samengerijgd om de global tak te definiëren.

  • Volgende twee manieren verwijzen expliciet naar de directory , waar de csv file staat (en doen precies hetzelfde) :

    • mutil csvin /library/tmp/test.csv ZCSV node1 node2

    • mutil csvin test.csv ZCSV node1 node2 cwd=/library/tmp

  • Uiteraard kan je een andere namespace definiëren : mutil csvin test.csv ZCSV node1 node2 cwd=/library/tmp uci=dbx

  • De aangeboden csv bestanden worden geacht te zijn in het gebruikelijke csv formaat.

5.18. Import van JSON bestanden

Zeer analoog aan wat je met csv bestanden kan, kan je dit nu ook met JSON gestructureerde files.

  • mutil jsin test.json ZCSV node1 node2 schrapt global node k ^ZCSV("node1","node2"), en leest de inhoud van de file test.json in de current directory in de global. De inhoud van de verschillende cellen komen terecht in ^ZCSV("node1","node2",...)=inhoud, die de structuur volgen van de JSON file.

5.19. Starten/stoppen van M

  • mutil start start het M systeem. Dit commando is bedoeld om in een service opstartscript te plaatsen

  • mutil stop stopt het M systeem. Zelfde opmerking. Bij zowel GT.M/YottaDB als Caché systemen gebeurt dit in twee fazen :

    • Er wordt eerst getracht het M systeem op een normale manier te stoppen

    • Als dit mislukt, dan wordt het stoppen geforceerd.

    • Let in het bijzonder op modifier iamservice, waar - voor noodgevallen en debugging - het start- of stopscript wordt uitgevoerd rechtstreeks door jouw proces.

5.20. Brocade's global lister : mutil gl

De global lister is een uitgebouwd instrument om globals of delen van globals uit te lijsten.

Je kan haar niet alleen oproepen via de Unix prompt, maar tevens :

  • In de M omgeving : d ^ugl

  • In de Brocade interface, via menu optie Global lister [link]

  • In Brocade applicaties via macro m4_stdUrlMGlobal

  • Geldige argumenten zijn:

    • Geen enkel argument. In dat geval wordt naar een argument gevraagd.

      Voorbeeld : mutil gl

    • Een open referentie naar een global.

      Voorbeeld : mutil gl 'BMETA(' : De volledige inhoud van deze global wordt dan getoond.

    • Een deel van een global, met vaste subscripts.

      Voorbeeld : mutil gl 'BCAT("lvd",,"au",'

      of in promptvriendelijke notatie : mutil gl BCAT/lvd//au

    • Een gesloten referentie naar een deel van een global. Voorbeeldmutil gl 'BCAT("lvd",,"au",)'

      In dit geval worden enkel de subscripts t.e.m. niveau 4 getoond.

    • Een deel van een global, waarbij bepaalde subscripts beperkt blijven tot een range.

      Voorbeeld : mutil gl 'BCAT("biomed","20000":,"re"' (Subcript 2 = vanaf waarde 20000 ) Voorbeeld : mutil gl 'BCAT("biomed","20000":"100000","re"' ( Subcript 2 = vanaf waarde 20000 tot 10000 )

      Let hier op het gebruik van de quotes, om een onderscheid te maken tussen waarden, die een subscript kan aannemen, en scheidingstekens.

    • Een deel van een global, met vooropgestelde patronen voor bepaalde subscripts.

      Voorbeeld : mutil gl 'BCAT("biomed",20000:,"re",r*,,??biomed:*'

      Let op het verschil met : mutil gl 'BCAT("biomed",20000:,"re","r*",,??biomed:*', waarbij hier wel degelijk gezocht wordt naar subscript met waarde r* op niveau 4.

    • Een Linkable Object Identifier, ofte loi:

      Voorbeelden :

      • mutil gl c:lvd:6876336

      • mutil gl rq:impala:888

      • mutil gl 'm:bibrecview'

      • mutil gl 'm:i:5788'

      • mutil gl e:UA:75884

      • mutil gl 'lt:UA:567893455'

      • mutil gl 'job:123456

    • Een Linkable Object Identifier, met extra restricties:

      Voorbeelden :

      • mutil gl 'c:lvd:6876336(pk,UA*' is hetzelfde als

      • mutil gl 'c:lvd:6876336,pk,UA*'

  • Geldige modifiers zijn :

    • uci zoals gebruikelijk. (Opmerking : voor secundaire globals werkt dit, voor zover de nodige routines zijn geinstalleerd.)

    • max : het maximum aantal output lijnen. Oneindig bij ontstentenis.

    • order : de volgorde, waarin de global moet worden doorlopen. order=-1 = in omgekeerde volgorde, order=+1 (default) = in gewone volgorde.

5.21. Debuggen van M code : mutil trace

mutil trace laat je toe, van M variabelen de waarden te tonen, die ze tijdens de uitvoering van M code aannemen. Dit gebeurt op wens, en wordt aangezet door het inbouwen van de macro m4_trace in de software code. Meer informatie over het gebruik hiervan vind je bij de documentatie van deze macro. Je kan mutil trace als volgt gebruiken :

  • Geldige argumenten zijn:

    • de naam van een (getracete) M variabele. Voorbeeld : mutil trace FDlnsys

    • een patroon van M variabelen. Voorbeeld : mutil trace 'FD*'

    • of gewoon alles, wat voorhanden is. Voorbeeld : mutil trace '*'

  • Geldige modifiers zijn :

    • user=brocade user id beperkt je output tot de processen, uitgevoerd onder brocade user id. Voorbeeld : mutil trace FDtrans user=rphilips

De output vermeldt ook een timestamp , en geeft alle aangenomen waarden van de M variabelen weer in volgorde van oud naar nieuw. Voorbeeld :

mutil trace 'RDr*'

( adescamp, blnwrshw, 16.08.2012 15:28:05 ):
RDrloi=r:UA:8883
( adescamp, blnwrshw, 16.08.2012 15:28:05 ):
RDrloi=r:UA:8980
( adescamp, blnwrshw, 16.08.2012 15:28:05 ):
RDrloi=r:UA:8980
( adescamp, blnwrshw, 16.08.2012 15:28:05 ):
RDrloi=r:UA:8990

5.22. Checken van geinstalleerde M code : mutil chk rou

mutil chk rou laat je toe, de M parser los te laten op een set van M routines, en een rapport te genereren, dat zowel syntax fouten oplijst, als overtredingen tegen de styleguide. Ze duiden op mogelijke problemen bij het opstarten van de code, en interferentie met andere code. De parser werkt op de geinstalleerde M routine, die enkel M instructies zou moeten bevatten, en waarbij alle macro's zijn vertaald.

Je kan mutil chk rou als volgt gebruiken :

  • Geldige argumenten zijn:

    • de naam van een geinstalleerde M routine(getracete) M variabele. Voorbeeld : mutil chk rou uwwwscr

    • een patroon van M routine namen. Voorbeeld : mutil chk rou 'uwww*'

  • Geldige extra argumenten zijn :

    • after:[datum] beperkt je output tot de routines, gewijzigd na een gegeven datum. De datum kan ook relatief worden gegeven, bvb : after:-1

    • production:[1/0] beperkt je output tot de routines, die 'in productie' zijn, of net niet. (zie macro getMRoutineTech)

5.23. Opzetten van een online mirror

Om een online mirror van je M databank op te zetten, volg volgende procedure :

  • Configureer op primary en secundary server de .ini bestanden : (zie ook mutil configuratie`_ ) .

  • Lanceer op de primary een backup in mirror mode ; dit kan op een levend systeem . Voorbeeld:

    • mutil backup '*' cwd=/library/tmp/mybackup mode=mirror Hierbij is het belangrijk, dat je de wildcard "*" gebruikt. Er wordt in de folder niet alleen een backup geschreven van de verschillende databank segmenten, maar ook de zgn. replication instance file.

  • Leg het M systeem stil op de secundary server:

    • mutil stop

  • copieer de databank segmenten naar de secundary server, op de plaats, waar de configuratie ze voorzien heeft

  • copieer de replication instance file naar de secundary, op de plaats, waar de configuratie ze voorzien heeft

  • voer uit op primary en secondary server:

    • mutil stop

    • mutil start

  • controleer de werking van de replicatie :

    • mutil status repl