Razporeditev in formati izvornih datotek

<name>.acproj
source/
  queries/<name>.query.txt   modules/<name>.bas        classes/<name>.cls
  forms/<name>.form.txt      reports/<name>.report.txt macros/<name>.macro.txt
                             reports/<name>.print.json
  tables/<name>.table.json   data/<name>.jsonl         relations/relations.json
                             data/<name>.files/<key>/...
  references.json            application/properties.json
  themes/<name>/...          resources/images/<name>.png
  ribbons/<name>.xml         ribbons/ribbon.json       navigation/navpane.json
  application/app-model.json (+ its icon)
  texts/<lang>.json          texts/terms.<lang>.json
build/<configuration>/       (results, not sources)
obj/wkl-state.json           (change tracking, per workstation, not sources)

Vsak del aplikacije Access ima privzeto pod korensko mapo izvornih datotek natanko eno mesto, ki ga uporabljajo izvoz, gradnja, preverjanja in sledenje spremembam. Postavke izvornih datotek v projektni datoteki lahko vrsto izvornih datotek postavijo drugam (Projektna datoteka: postavke izvornih datotek). Vse izvorne datoteke so v kodiranju UTF-8. Če ime objekta vsebuje znake, ki v imenu datoteke niso dovoljeni, so ti kodirani (%2F …).

tables/<table>.table.json vsebuje en objekt s temi ključi; vsak drug ključ SDK zavrne:

{
  "version": 1,
  "name": "tblStranka",
  "fields": [
    { "name": "Id", "type": "Long", "autoNumber": true },
    { "name": "Name", "type": "Text", "size": 80, "required": true, "allowZeroLength": true },
    { "name": "Credit", "type": "Decimal", "precision": 12, "scale": 2 },
    { "name": "Active", "type": "Boolean", "properties": { "DisplayControl": "106" } }
  ],
  "indexes": [
    { "name": "PrimaryKey", "fields": [ "Id" ], "primary": true },
    { "name": "ByName", "fields": [ "Name", { "name": "Id", "descending": true } ], "unique": true }
  ]
}

Indeks sestavljajo name, fields (ime polja za naraščajoči vrstni red ali { "name": ..., "descending": true }) ter zastavice primary, unique (izpuščena pri primarnem ključu, ki je tako ali tako enoličen) in ignoreNulls, vsaka s privzeto vrednostjo false.

Vsak vnos v fields je objekt s temi ključi; ključi s privzeto vrednostjo se ne zapišejo.

Lastnosti iskanja nimajo lastnih ključev, temveč se zapišejo pod properties z imenom, ki ga uporablja Access, in z vrednostjo kot besedilom. Primer polja Da/Ne, ki ga Access v podatkovnih listih tabel in poizvedb prikaže kot potrditveno polje:

{ "name": "Assigned", "type": "Boolean", "properties": { "DisplayControl": "106" } }

DisplayControl sprejme številko vrste kontrolnika Access (106 potrditveno polje, 109 polje z besedilom, 110 polje s seznamom, 111 kombinirano polje). Ključ displayControl poleg type SDK zavrne kot neznan.

Selitve nastavijo allowZeroLength na true za vsako besedilno polje tabel, ki jih prenesejo (DATEC SDK, orodje za gradnjo WKL Forms Object Library), ker so stare gradnje ustvarjale polja, ki so sprejemala prazno besedilo.

Vsak zapis je en objekt JSON v svoji vrstici, ključi so v vrstnem redu sheme tabele, zapisi pa so urejeni po primarnem ključu. Vsak zapis mora vsebovati vsa polja sheme; manjkajoče polje je napaka. Vsaka vrednost je zapisana v obliki svojega tipa, neodvisno od jezikovnih in regionalnih nastavitev računalnika:

Znaki zunaj nabora ASCII so zapisani takšni, kot so (UTF-8), ne kot ubežna zaporedja. Dolgi binarni podatki (predmet OLE) in priloge so v ločenih datotekah, v eni mapi na zapis, poimenovani po njegovem primarnem ključu: data/<table>.files/<key>/<field>.bin in data/<table>.files/<key>/<field>/<file name>. Datoteka priloge vsebuje natanko bajte priložene datoteke. Polje z več vrednostmi je polje (array) njegovih vrednosti, razvrščeno, ker jih Access hrani kot množico. Pri tabeli brez primarnega ključa se mapa imenuje po položaju zapisa (row000001), ki se spremeni, ko se pred zapis vstavijo drugi zapisi. Podatkovna datoteka se ne more sklicevati na datoteko zunaj podatkovne mape.

references.json je polje (array) v prednostnem vrstnem redu projekta VBA; vsak vnos ima natanko name, guid (v zavitih oklepajih, z velikimi črkami), major in minor (različica, ki jo potrebuje aplikacija):

[ { "name": "WklForms", "guid": "{A37D549E-FCD0-48EC-8B14-C7323B747E4F}", "major": 2, "minor": 0 } ]

Gradnja vsak sklic doda s to različico. Access pa zapiše najvišjo različico knjižnice tipov z istim major, ki je registrirana na računalniku za gradnjo: če je tam registrirana WKL Forms Object Library 2.3, vsebujeta ACCDB in ACCDE pri "minor": 0 sklic na 2.3. export ohrani minor iz izvornih datotek, dokler podatkovna zbirka navaja isti major in ne nižjega minor; sicer zapiše različico iz podatkovne zbirke. references.json tako še naprej navaja, kaj aplikacija potrebuje, zgrajena podatkovna zbirka pa zahteva različico, ki je bila registrirana na računalniku za gradnjo.

application/properties.json je polje (array), urejeno po imenu; vsak vnos ima name, value (vedno niz) in za vsak tip razen besedila še type z imenom tipa lastnosti DAO (Boolean, Byte, Integer, Long, …):

[ { "name": "AppTitle", "value": "Stranke" }, { "name": "AllowBypassKey", "value": "False", "type": "Boolean" } ]

relations/relations.json je objekt z version (1) in relations, urejenimi po imenu; vsaka relacija ima name, table (primarna tabela), foreignTable, fields (pari field in foreignField) in attributes, imena nastavljenih zastavic relacij DAO (Unique, DontEnforce, Inherited, UpdateCascade, DeleteCascade, Left, Right); prazen seznam pomeni relacijo z referenčno integriteto brez kaskadnih sprememb.

V vseh treh datotekah SDK vsak drug ključ zavrne.

Besedila, ki jih aplikacija prikazuje prek WklTexts iz knjižnice WKL Forms Object Library (1.67 ali novejše) – sporočila, napise in vprašanja –, so v mapi texts/, po ena datoteka za vsak jezik. neutral.json jih vsebuje v jeziku, v katerem je aplikacija napisana; med izvajanjem ključ brez besedila v jeziku seje prikaže nevtralno besedilo, nato angleško. <code>.json vsebuje prevod za katero koli dvo- ali tričrkovno kodo jezika (de.json, fr.json, pl.json). Datoteka neutral.json ali en.json je obvezna, brž ko obstaja katera koli datoteka z besedili; prva obstoječa je izhodišče preverjanj. Vsaka datoteka vsebuje en objekt JSON brez gnezdenja, v katerem je vsakemu ključu prirejeno besedilo, ključi so razvrščeni ordinalno, kodiranje je UTF-8 brez oznake vrstnega reda bajtov:

{
  "orders.count": "{0} orders",
  "orders.title": "Orders"
}

• Ključi so napisani z malimi črkami in s pikami razvrščeni po obrazcu ali temi (orders.title); pri primerjanju se velike in male črke ne razlikujejo, ključ, ki se v datoteki pojavi dvakrat, pa ustavi gradnjo. Ključi, ki se začnejo z wkl., so standardna besedila komponent, zato jih aplikacija ne more določiti.
• Ograde {0}, {1:N2} se napolnijo z argumenti metode WklTexts.Text.
• Gradnja besedila zapiše v ustvarjeno tabelo USysWklTexts (ID, TextKey, Language, TextValue) datotek ACCDB in ACCDE; izvoz tabele nikoli ne zapiše nazaj. Tabela USysWklTexts v mapi tables/ poleg datotek z besedili ustavi gradnjo.
• Nevtralni jezik (izbirno): lastnost projekta NeutralLanguage (projektna datoteka) navede jezik datoteke neutral.json, na primer sl. Ta jezik tedaj ne potrebuje lastne datoteke, ključi, ki v njem manjkajo, pa se ne javljajo.
• Preverjanja (opozorila, gradnja se nadaljuje): ključi izhodišča, ki v drugem jeziku manjkajo, ključi brez nevtralnega ali angleškega besedila, prevodi z drugačnimi ogradami kot v izhodišču, ključi, ki jih zahteva koda VBA, pa nimajo nevtralnega ali angleškega besedila, prevodi, označeni za pregled, in datoteke z besedili jezika zunaj mape texts/ (gradnja jih ne prebere; upoštevajo se le datoteke z imenom neutral ali s kodo po ISO 639-1, ki vsebujejo en objekt besedil, mape, katerih ime se začne s piko, pa se ne preiščejo).
• Ključe, ki jih zahteva koda, preverjanje najde v modulih, modulih razredov, obrazcih in poročilih v dveh oblikah: .Text("a.b") na katerem koli objektu (WklTexts ali pomožni funkciji aplikacije, na primer Tx.Text("a.b", n)) ter Text("a.b") ali Texts("a.b") (privzeti član), ne glede na velike in male črke. Upošteva se le dobesedni ključ z vsaj eno piko; ključa, sestavljenega med izvajanjem (texts.Text(prefix & ".title")), preverjanje ne preveri. Komentarji se preskočijo: opuščaj zunaj niza, Rem in vrstice komentarja, ki se nadaljujejo z _.
• Terminologija (izbirno): texts/terms.<lang>.json prednostnemu izrazu priredi različice, ki naj se ne uporabljajo, { "podatkovna zbirka": [ "zbirka podatkov" ] }; besedilo z različico sproži opozorilo.
• Oznake za pregled: texts/review.<code>.json ključu priredi nevtralno (ali angleško) besedilo, iz katerega je nastal njegov prevod, kadar se je to besedilo medtem spremenilo. texts import oznake zapiše in odstrani; vsaka sproži opozorilo, dokler se ne vrne prevod trenutnega besedila.
• Za prevajalce wkl-office texts export --language <code> zapiše paket za prevod enega jezika, texts import pa naenkrat združi poljubno število vrnjenih paketov (ukazna vrstica).

SaveAsText tiskalnik poročila zapiše kot binarne bloke (PrtMip, PrtDevMode, PrtDevNames in njihove različice W). Ti vsebujejo ime, gonilnik in zasebne podatke gonilnika tiskalnika na računalniku, ki je poročilo shranil, zato so na vsakem računalniku drugačni. Skrajšan blok Access prebere z nesmiselnimi podatki v imenu naprave in obrazca, zato blokov ni mogoče zgolj očistiti. Izvoz jih izpusti iz besedila poročila in poleg njega zapiše nastavitve strani:

{
  "useDefaultPrinter": true,
  "orientation": 2,
  "paperSize": 11,
  "leftMargin": 1440,
  "topMargin": 1440,
  "rightMargin": 1440,
  "bottomMargin": 1440,
  "itemsAcross": 2,
  "columnSpacing": 360,
  "rowSpacing": 0,
  "defaultSize": true,
  "itemSizeWidth": 0,
  "itemSizeHeight": 0,
  "itemLayout": 1953,
  "dataOnly": false
}

Vrednosti so vrednosti objekta Printer programa Access: robovi, razmiki in velikost elementa v twipih (1440 na palec); orientation 1 pokončno, 2 ležeče; paperSize kot AcPrintPaperSize (9 A4, 11 A5, 1 Letter); itemLayout 1953 najprej vodoravno in nato navzdol, 1954 najprej navzdol in nato vodoravno. Gradnja jih nastavi prek objekta Printer poročila. Ime določenega tiskalnika se ne ohrani, ker je odvisno od računalnika. Z "useDefaultPrinter": true se poročilo natisne na trenutno privzetem tiskalniku; z false ga gradnja shrani z določenim tiskalnikom, in sicer s privzetim tiskalnikom računalnika, na katerem poteka gradnja. Poročilo brez te datoteke se zgradi s privzetimi vrednostmi programa Access. check neveljaven JSON sporoči kot napako, datoteko .print.json brez njenega poročila pa kot opozorilo.

1. check (izvorne datoteke in računalnik); če najde napako, gradnja ne ustvari ničesar.
2. Nova podatkovna zbirka s končnim imenom v build/<configuration>/.building/; v build/<configuration>/ se premakne šele, ko uspejo vsi koraki.
3. Sklici v vrstnem redu iz references.json, lastnosti podatkovne zbirke z njihovimi tipi, tabele z indeksi, podatki tabel SeedData in FullData, besedila aplikacije (USysWklTexts), relacije.
4. Tema (podatkovna zbirka se znova odpre, ker Access temo dodeli samo obrazcem, ustvarjenim pozneje), skupne slike, ročno napisani trakovi, model traku z modulom za povratne klice.
5. Poizvedbe, standardni moduli, moduli razredov, obrazci (z nadomeščenimi ogradami), poročila (z uporabljenimi nastavitvami strani), makri.
6. Dodelitve priročnih menijev, model podokna za krmarjenje, zagonske lastnosti, model aplikacije, povezave profila povezave konfiguracije, zaključna funkcija.
7. Prevajanje in preverjanje: projekt VBA se prevede, noben sklic ni prekinjen, vsaka tabela in vsak objekt izvornih datotek je v podatkovni zbirki.
8. ACCDE, če jo konfiguracija izdeluje, z zagonskimi lastnostmi iz AppMode.

Modele uveljavi WKL Forms Object Library sama (s svojima metodama Save in Apply) prek pomožnega modula, ki je v podatkovni zbirki samo med gradnjo.

• Tabele: shemo vsake lokalne tabele (ne sistemskih, začasnih ali povezanih tabel; za povezane tabele izvoz ne opozori) in podatke tabel s pravilnikom SeedData ali FullData; tabelo s pravilnikom Ignore izpusti. Uporabnikovo stanje podatkovnega lista (širine in vrstni red stolpcev, razvrščanje, filter, pisave) se ne izvozi. Lastnost tabele ali polja, ki je ni na seznamu izvornih lastnosti in ni znana kot uporabnikovo stanje, se ne izvozi: izvoz jo sporoči kot opozorilo (“Lastnost še ni vir in ni bila izvožena.”), podatkovna zbirka, zgrajena iz izvornih datotek, pa je nima. Enako velja za lastnost podatkovne zbirke tipa DAO, ki ga properties.json ne more vsebovati. Ta opozorila ne povzročijo neuspeha izvoza, gradnje ali krožne preverbe; vsako obravnavajte kot izgubo podatkov, ki jo morate razrešiti.
• Gesla (PWD, Password) v parametrih vrstic povezav upravitelja povezav (Linked Tables Manager) se odstranijo, vsako z opozorilom.
• Sklici: sklic ohrani različico, ki jo references.json že zahteva, če se podatkovna zbirka sklicuje na isto glavno različico in na različico, ki ni starejša. Access sklic veže na različico, registrirano na računalniku; če bi izvoz prevzel njeno številko, bi se zahteva zvišala ob vsaki posodobitvi računalnika za gradnjo.
• Lastnosti podatkovne zbirke: vrednosti pogona podatkovne zbirke, uporabnikovo stanje podokna za krmarjenje, privzete vrednosti vsake nove podatkovne zbirke ter vrednosti, ki pripadajo temi ali jih nastavi model, se izpustijo.
• Tema: tema, ki jo navaja podatkovna zbirka (ne tema “Office”, ki jo ima vsaka podatkovna zbirka).
• Modeli: datoteke modelov so edini vir; tabele, ki jih hranijo (USysWklApp, USysWklNavPane, USysWklRibbon, USysRibbons), se ne izvozijo kot tabele, prav tako ne USysWklTexts, ki jo gradnja zapiše iz datotek z besedili. Tudi USysWklLayout (razporeditev, ki jo je izbral posamezni uporabnik) in ustvarjeni modul basWklRibbon nista izvorni datoteki.

Datoteka se prepiše samo, če se je njena vsebina spremenila. Datoteke v mapah, ki jih upravlja SDK, se izbrišejo, če njihovega objekta ni več, izvoz pa jih navede; druge datoteke (na primer README ob obrazcih) ostanejo. Če izvoz ne uspe, ne izbriše ničesar.

Prvi izvoz po migrate obrazce in module enkrat prepiše tako, kot jih zapiše Access: VBA vsak identifikator v celotnem projektu zapiše z enakimi velikimi in malimi črkami, Access pa obrazcem doda lastnosti, kot je PublishOption. Od takrat export po build ne spremeni nobene datoteke.

Vrednosti, ki so videti kot šum, vendar so stanje objekta, ostanejo: LayoutCached* (Access jih po nalaganju ne zapiše znova) in PublishOption (Access znova zapiše isto vrednost).

OleData kontrolnika ActiveX (njegove shranjene lastnosti) je shramba OLE in ostane do bajta enak, razen obeh časovnih žigov, ki ju izvoz nastavi na 0 (glejte tabelo). Obrazec, ki ga znova ustvarite iz njegovega besedila, se zato ob naslednjem izvozu izvozi v enako besedilo. Access takšno besedilo naloži brez napake, ohrani lastnosti kontrolnika, ničle pa ob naslednjem izvozu zapiše nespremenjene.

Poleg zgornjih vrednosti, ki jih izvoz odstrani namenoma, v izvorne datoteke nikoli ne pridejo naslednji deli aplikacije Access. Podatkovna zbirka, zgrajena iz izvornih datotek, jih nima, roundtrip pa njihove odsotnosti ne more opaziti.

• Če želite zgrajeno podatkovno zbirko z zagonskim obrazcem pregledati iz skripta, je ne odpirajte z OpenCurrentDatabase: zagonski obrazec se izvede, tudi če je AutomationSecurity nastavljen na onemogočanje makrov. Preberite jo z DBEngine.OpenDatabase.
• Besedilno polje z več vrednostmi v izvornih datotekah nima velikosti: DAO zanj sporoča 4 (širino njegovega ključa), njegove vrednosti pa sprejmejo 255 znakov, ne glede na velikost, s katero je bilo ustvarjeno.

• Projektna mapa – katera datoteka je kje in kaj je pod nadzorom različic
• Referenčni priročnik projektne datoteke
• Referenčni priročnik ukazne vrstice