Vera-päiväkirjatietojen siirtoformaatti

VERA TOIMINTAOHJEET Vera-päiväkirjatietojen siirtoformaatti Rev./pvm 2.00 Hyväksytty 15.6.2014 Sisältö Käyttö Vastuuhenkilö Tiedonsiirtoformaatti automaatio- ja ohjelmistojärjestelmistä Tietojen siirto Vera-käyttöpäiväkirjaan ohjelmallisesti. Hannu Sippola FCG SUUNNITTELU JA TEKNIIKKA OY 15.6.2014

Toimintaohje I Hyväks. 15.6.2014 SISÄLLYSLUETTELO 1 YLEISTÄ... 1 2 SIIRTOTIEDOSTON RAKENNE... 2 Yleistä 2 3 SIIRTOTIEDOSTON YKSITYISKOHTAINEN RAKENNE... 3 3.1 Yleistä... 3 3.2 Rivi 1... 3 3.3 Rivi 2.... 4 3.4 Rivi 3.... 5 3.5 Rivi 4... 5 3.6 Rivi 5.... 7 3.7 Rivit 6-N... 8 3.8 Esimerkki siirtotiedostosta automaatiojärjestelmästä... 9 3.9 Esimerkki päivätietojen siirtämisestä toisesta tietojärjestelmästä... 9 MUUTOKSET

Toimintaohje 1 (9) 1 Yleistä a) Siirrettävät tiedot, esimerkiksi automaatiojärjestelmästä tai toisesta tietokannasta, kirjoitetaan tekstitiedostoon, jonka tyyppi on vtf (siirtotiedosto). Tiedoston nimi on vapaa, eikä VeRa käytä sitä mihinkään. Nimessä ei suositella käytettävän pisteitä. b) Tiedoston nimen tarkoitus on helpottaa siirtotiedoston etsimistä häiriötilanteissa, siksi nimeen on hyvä lisätä aikaleima. Aikaleima on hyvä lisätä sellaisessa muodossa, että tiedostot aakkostuvat vanhimmasta tuoreimpaan. c) Jokaisen siirtotiedoston nimen tulee olla yksilöllinen ja se sisältää vain tietoja yhden ajanjakson, esimerkiksi päivän tietoja, jäljempänä määritellyt tiedot. d) Jokaiselle päiväkirjalle on oma hakemistonsa siirtotiedostoja varten, johon siirtotiedostot (vtf-tiedostot) siirretään. e) Kaikkia siirrettäviä tietoja ei tarvitse koota samaan tiedostoon, vaan niitä voi olla useampiakin. Esim. kultakin tietolähteeltä omansa. f) Jos samalta tietolähteeltä tulee tietoja useampaan päiväkirjapohjaan, niin kullekin päiväkirjapohjalle täytyy lähettää oma siirtotiedostonsa. g) Siirtotiedostossa saa olla mittauksia, joita kyseinen päiväkirjapohja ei käytä. Näin ollen on mahdollista kerätä kaikki tietolähteen tiedot yhteen tiedostoon ja lähettää se kaikille päiväkirjoille, jotka tarvitsevat jotain tietoa ko. tietolähteeltä. On myös mahdollista tehdä kullekin päiväkirjalle oma siirtotiedosto, jossa on vain ko. päiväkirjaa kiinnostavat tiedot. h) VeRa huolehtii luettujen tiedostojen poistosta ja mahdollisesta varmuuskopioinnista. i) Lähetettäessä korjattuja tietoja, kirjataan uudet tiedot vanhojen tilalle. j) Ajatuksena on, että jokainen siirtotiedosto sisältää riittävän informaation sen tulkitsemiseen myös myöhemmin. k) Jokainen siirtotiedosto alkaa määrittelyosalla, joka pysyy käytännössä samana ja sitä seuraa siirrettävien mittausten tiedot. l) Tiedostossa ei saa olla samalle tiedolle (sama tunniste ja aikaleima) kahta arvoa (duplikaatti). Tieto voidaan korjata lähettämällä uusi tieto eri tiedostossa.

Toimintaohje 2 (9) 2 Siirtotiedoston rakenne Yleistä Tiedot ovat riveittäin tiedostossa. Jokaisen rivi loppuu merkkeihin <CR><LF> Siirtotiedoston sisältö riveittäin on seuraava: 1. Yleistunniste ja listaerotin 2. Aikaleiman määrittelyt 3. Desimaalierottimen määrittely 4. Siirrettävien tietojen tyyppimäärittelyt 5. Siirrettävä tietojen aikaleima ja lukumäärä 6. -N Siirrettävät tiedot Tiedosto jakautuu siis kahteen osaan: otsikko-osaan ja tieto-osaan, jossa ensimmäisessä määritellään siirrettävät tiedot ja niiden esitystapa sekä aikaleima. Jälkimmäisessä osassa on varsinaiset mittaustiedot.

Toimintaohje 3 (9) 3 Siirtotiedoston yksityiskohtainen rakenne 3.1 Yleistä 3.2 Rivi 1 Rivit 1-5 alkavat tunnisteella, joka kertoo mitä tietoa riviltä löytyy. Jos rivillä on useampi tieto, niin rivillä olevat tiedot erotetaan toisistaan listaerottimella (esimerkiksi pilkku), joka määritellään tiedoston ensimmäisellä rivillä (ks. kohta Rivi 1). Merkkitieto annetaan ilman lainausmerkkejä. Tietoa ympäröivät eli edeltävät ja seuraavat välilyönnit eivät sisälly tietoon vaan ne ohitetaan. Rivillä kirjoitetaan tietojen tunniste ja määritellään listaerotin DATAFORVERA <erottimen ascii numero> VER 2.00 Erottimen ascii numero pitää olla välillä 0-128. Erotin erottelee rivillä olevat tiedot toisistaan, joten numeroa, kirjainta tai desimaalierotinta ei pidä valita erottimeksi. Suositeltavia erottimia esim. ovat puolipiste tai pilkku, jos sitä ei käytetä desimaalierottimena. Välilyönti (ascii numero 32) ei voi toimia erottimena, Ei myöskään <CR> tai <LF>. Välilyönnit arvojen alussa ja lopussa ohitetaan. VER sana jälkeen tulee käytettävän siirtotiedostoformaatin numero ESIMERKKI: Erottimena pilkku DATAFORVERA 44 VER 2.00 Jos käytetään desimaalipilkkua, niin pilkku ei voi toimia erottimena. Erottimen jälkeen saa olla luettavuutta parantava välilyönti.

Toimintaohje 4 (9) 3.3 Rivi 2. Rivillä määritellään käytetyn aikaleiman formaatti ja viittaustapa. STAMP <Tyyppi> [<Erotin> <Ajankohta>] jossa <Tyyppi> on Aikaleiman formaatti, esimerkiksi jokin seuraavista YYYYMMDDHH YYMMDDHH YYMMDD YYMM (oletusarvo) ( päivätiedoille) ( kuukausitiedoille) Aikaleimaa voidaan vielä tarkennetaan ilmaisemalla tarkoitetaanko alku- vai loppuhetkeä. Oletusarvona on alkuhetki. Ajankohdan tarkennus on suositeltavaa erityisesti siirrettäessä tuntitason tietoja. <Erotin> on <Ajankohta> on Rivillä 1 määritelty listaerotin 0 jos aikaleima on ajanjakson (tunnin) alkuhetki (oletusarvo) 1 jos aikaleima on ajanjakson (tunnin) loppuhetki Aikaleimalla tarkoitetaan sen ajankohdan tunnistetta, miltä siirrettävät tiedot ovat ja sitä voidaan tarvittaessa tarkentaa <Ajankohta> Aikaleima voidaan antaa tarkemmin kuin itse tiedon aikaskaala. Esimerkiksi päivätiedolle voidaan antaa aikaleima tunnin tarkkuudella, vaikka itse tieto edustaa kyseistä päivää, esimerkiksi pitoisuusmittaus tai ohitusvirtaama. Esimerkiksi 2006022712 voi tarkoittaa seuraavia tunteja Ajankohta Tunti 0 12-13 1 11-12 Tunnit saavat olla välillä 00-24. Esimerkiksi 20060227 voi tarkoittaa seuraavia ajanjaksoja Ajankohta Ajanjakso 0 27.2.2006 klo 0-24 : koko päivä 1 26.2.2006 klo 0-24 : koko päivä ESIMERKKI: Tiedon aikaleima tunnin loppuhetken mukaan. STAMP YYYYMMDDHH, 1 ESIMERKKI: Aikaleima päivän tarkkuudella STAMP YYYYMMDD

Toimintaohje 5 (9) 3.4 Rivi 3. Rivillä määritellään käytetty desimaalierotin. DECIMAL <Arvo> tai DECIMAL <Desimaalierotin> jossa <Arvo> on 0 tai 46 jos käytetään desimaalipistettä (oletusarvo) 1 tai 44 jos käytetään desimaalipilkkua <Desimaalierotin> on. (piste) tai, (pilkku) ESIMERKKI: Desimaalierottimena on piste (3 tapaa). DECIMAL 0 DECIMAL 46 DECIMAL. 3.5 Rivi 4 Rivillä määritellään minkä tyyppistä tietoja ollaan siirtämässä. Sen tyyppistä tietoa, jota ei ole saatavilla, ei pidä määritellä myöskään siirrettäväksi. ID <Erotin> UNIT <Erotin> <Laji1> <Erotin> <Laji2> <Erotin> <Laji3> <Erotin><Laji4> jne. jossa <Laji> on jokaisesta mittauksesta siirrettävien tietojen laji kuten: LAST, MIN, MAX, AVG, SUM, CUMD jne. Laji kuvaa mitä arvoja jokaisesta mittauksesta siirretään. Ajatuksena on, että tietolähteestä siirretään kustakin mittauksesta kaikki tällä rivillä määritellyt tiedot, joista VeRa käyttää niitä, joita tarvitsee.

Toimintaohje 6 (9) Käytettävissä olevat lajit: Tunniste ja yksikkö ID Mittauksen tunniste (merkkijono, max 128 merkkiä) UNIT Mittauksen yksikkö (merkkijono) Mitattu arvo VALUE yksittäinen mittausarvo AVG keskiarvo MIN pienin arvo MAX suurin arvo LAST viimeisin arvo CUM0 laskurin arvo eli muutos aikojen alusta CUMY laskurin muutos vuoden alusta CUMM laskurin muutos kuukauden alusta CUMD laskurin muutos päivän alusta SUM kumulatiivinen arvo siirtovälille eli sama tuntitason tiedoille sama kuin CUMH ja päivätason tiedoille sama kuin CUMD. Mittauksen lisätieto PERIOD mittausaika tunteina: Kerta-arvoille nolla, vuorokausiarvoille 24. DELTA mittaustarkkuus, joko absoluuttisena tai prosentteina, jolloin luvun perässä on % merkki. GOOD onnistuneiden mittausten lukumäärä mittausaikana COMMENT tietoon liittyvä kommentti (merkkijono, max 250 merkkiä) TYPE tiedon tyyppi (merkkijono) SUBTYPE tiedon alatyyppi (merkkijono) Tietolähteen tiedot SOURCEID tiedon tuottajan tunniste (merkkijono/numero). LOGTIME tiedon tallennusajankohta (aikaleima, rivin 2 formaatti) DATAID tiedon tunniste tietolähteessä (merkkijono/numero). HUOM1. HUOM2. SUM kohtaan ei saa määrämittauksissa, kuten virtaama, kirjata hetkellisten mittausarvojen summaa vaan se on varattu kumulatiiviselle arvolle. Mitattaessa virtaamaan liittyvää pitoisuutta, lämpötilaa tms. huomioidaan vain ne mittaukset, jolloin virtausta tapahtuu. ESIMERKKI: Siirrettävien tietojen tyyppien määrittelyjä ID, UNIT, MIN, AVG, MAX, SUM, LAST ID, UNIT, AVG, SUM, COMMENT ID, UNIT, VALUE Neljä ensimmäistä riviä pysyy normaalisti samana joka tiedostossa.

Toimintaohje 7 (9) 3.6 Rivi 5. Rivillä annetaan siirrettävien tietojen aikaskaala, aikaleima ja lukumäärä. <aikaskaala> <aikaleima> <Erotin> <siirrettävien mittausten lkm>, missä <aikaskaala> on tuntitiedoille ONEHOURDATA päivätiedoille ONEDAYDATA kuukausitiedoille ONEMONTHDATA Aikaskaalan avulla Vera päättelee siirretäänkö tunti- päivä ja kuukausitason tietoja. Aikaleima voi olla tarkempi kuin aikaskaala. Esimerkiksi kerran kuukaudessa mitattavan pitoisuuden aikaleima voi olla tunnin tarkkuudella. Aikaleima on rivillä 2 määritellystä muodossa. Lukumäärän sijasta voidaan kirjoittaa myös LIST. Tällöin aikaleiman osoittamien tietojen anto lopetetaan komennolla ENDLIST omalle rivilleen kirjoitettuna. ESIMERKKI: Aikaleiman ja mittausten ilmoittaminen ONEHOURDATA 2014020115, 5 ONEDAYDATA 20140201, LIST

Toimintaohje 8 (9) 3.7 Rivit 6-N Riviltä alkaen annetaan siirrettävät tiedot yksi mittaus per rivi. <ID> <Erotin> <Laatu> <Erotin> <Arvo1> <Erotin> <Arvo2> jne. jossa <ID> on Mittauksen yksikäsitteinen tunniste. <Laatu> on Mittauksen laatu <Arvo> on Mittauksen arvo ID on mittauksen tunniste, jonka avulla VeRa tunnistaa mittauksen. Se on merkkijono, jossa ei saa esiintyä valittua lista- (rivi 1) tai desimaalierotinta (rivi 3) eikä välilyöntiä. Merkkijonon alussa ja lopussa olevat välilyönnit poistetaan eikä niitä sisällytetä ID:hen. ID maksimipituus on 128 merkkiä. Mittauksen arvot annetaan annetussa järjestyksessä (rivi 4). Esimerkki ID:stä: R1052_M11455_FI1234_VIRTAUS_LÄHTEVÄ_VESI. Laatu kertoo mittauksen laadun. Laaduttoman mittauksen laatuna on joko tyhjä tila erottimien välissä tai #NULL#. VeRan tunnistamat laadut löytyvät liitteestä X. Mikäli siirrettävien tietojen lukumäärän sijasta on annettu LIST, tulee siirrettävien tietojen loppuun omalle rivilleen kirjoittaa ENDLIST. Sama mittaus (ID) saa esiintyä vain kerran. Rivien (ID) keskinäisellä järjestyksellä ei ole merkitystä. Puuttuva arvo ilmaistaan joko välilyönnillä eli tyhjällä tila erottimien välillä tai kirjoittamalla FAIL tai #NULL#. Tiedon puuttumisen syy voidaan ilmaista seuraavasti: välilyönti FAIL #NULL# Tieto puuttuu syystä tai toisesta, mutta voidaan mahdollisesta vielä saada. Esimerkiksi kun kyseessä on tiedonsiirto-ongelma tai kun syytä ei tiedetä. Tietoa ei mittarivirheen tms. syyn tähden tällä kertaa saada. Esimerkiksi kun mittari on rikki tai muuten poissa käytöstä. Tietoa ei ole saatavilla lainkaan tai on merkityksetön. Esimerkiksi ph arvojen summa tai tietyn ominaisuuden puuttuminen mittarista tai järjestelmästä. Jos jollekin mittaukselle ei saada lainkaan arvoja, niin sen voi jättää siirtotiedostosta pois. Toinen vaihtoehto on antaa #NULL#, FAIL tai välilyönti kaikille tiedoille. ESIMERKKI: Virtausmittauksen tiedot FI-123, m3/h, 220.4, 235.5, 240.23, 1450.23, 231.5

Toimintaohje 9 (9) 3.8 Esimerkki siirtotiedostosta automaatiojärjestelmästä Ohessa esimerkki, jossa erottimena toimii pilkku (44) ja desimaalierottimena piste (0). Vakiona pysyvä tiedoston alku (4 riviä) on merkitty vahvennettuna. Siirrettävien tietojen aikaleima (2006022610) ja lukumäärä (5) löytyvät seuraavalta riviltä. Puuttuvan tiedon ilmaisemiseen on käytetty sekä puuttuvaa arvoa että #NULL# merkintää rivillä 6. Merkityksetön summa ja kumulatiivista arvo on annettu ph:lle rivillä 9. DATAFORVERA 44 VER 2.00 STAMP YYYYMMDDHH, 1 DECIMAL 0 ID, UNIT, MIN, AVG, MAX, SUM, LAST, CUM0 ONEHOURDATA 2006022610, 5 TI_5001_LEHTO_ULKOILMA_T, C, -12.1, -12.4,-12,8,,-2.8, #NULL# FQ_5001_LEHTO_Q, m3/h, 1230, 1312, 1410, 1312, 1311, 12412345 TI_5000_LEHTO_TULEVA_T, C, 4.0, 4.1, 4.2,#NULL#, 4.1, QRA_5000_LEHTO_TULEVA_PH,, 7.1, 7.5, 7.8, 25560, 7.7, 123456789.1 FQ_5308_OHITUS, m3/h, 0, 0, 0, 0, 0, 1234.1 Sama tiedosto, mutta siirrettävien tietojen lukumäärää ei ole määritelty. Merkityksettömät arvot on korvattu välilyönnillä tai #NULL# :lla DATAFORVERA 44 VER 2.00 STAMP YYYYMMDDHH, 1 DECIMAL 0 ID, UNIT, MIN, AVG, MAX, SUM, LAST, CUM0 ONEHOURDATA 2006022610, LIST TI_5001_LEHTO_ULKOILMA_T, C, -12.1, -12.4,-12,8,,-2.8, #NULL# FQ_5001_LEHTO_Q, m3/h, 1230, 1312, 1410, 1312, 1311, 12412345 TI_5000_LEHTO_TULEVA_T, C, 4.0, 4.1, 4.2,#NULL#, 4.1, QRA_5000_LEHTO_TULEVA_PH,, 7.1, 7.5, 7.8, #NULL#, 7.7, #NULL# FQ_5308_OHITUS, m3/h, 0, 0, 0, 0, 0, 1234.1 ENDLIST 3.9 Esimerkki päivätietojen siirtämisestä toisesta tietojärjestelmästä DATAFORVERA 44 VER 2.00 STAMP YYYYMMDD DECIMAL 0 ID, UNIT, SUM ONEDAYDATA 20160227, 4 OHITUS_HERVANTA, m3/d, 123.0 OHITUS_HATANPÄÄ, m3/d, 12.0 OHITUS_KALEVA, m3/d, 30.0 OHITUS_PISPALA, m3/d, 0.0