OTR GW SOAP szolgáltatás GWSOAPSRV

OTR GW SOAP szolgáltatás GWSOAPSRV Az OTR4 SOAP alapú input és output gateway szolgáltatásának bemutatása adatszolgáltatási szerződéssel NEM rendelkező felhasználók számára v4.1.0.0 2014-04-01. 1.

OTR GW SOAP szolgáltatás -------------------------------------------------------------------------- 2 1.1.

Bevezető ---------------------------------------------------------------------------------------------------- 2

1.2.

Szolgáltatás elérhetősége -------------------------------------------------------------------------------- 2

1.3.

GWSOAPSRV jellemzői ---------------------------------------------------------------------------------- 2

1.3.1. 1.3.2.

1.4. 1.4.1.

1.5. 1.5.1. 1.5.2. 1.5.3. 1.5.4.

1.6. 1.6.1.

Listák, szálak, korlátozások --------------------------------------------------------------------------------------- 3 Tanusítvány --------------------------------------------------------------------------------------------------------- 3

Információk kliens fejlesztők számára ------------------------------------------------------------------ 3 Kliens program vázszerkezet ------------------------------------------------------------------------------------- 4

Metódusok és struktúrák --------------------------------------------------------------------------------- 4 Technikai jellegű metódusok ------------------------------------------------------------------------------------- 5 Input Gateway metódusok ---------------------------------------------------------------------------------------- 6 Output Gateway metódusok -------------------------------------------------------------------------------------- 8 Gateway metódusok argumentumai --------------------------------------------------------------------------- 13

Hibakezelés ----------------------------------------------------------------------------------------------- 13 GWSOAPSRV hibaüzenetek ------------------------------------------------------------------------------------ 14

1.7.

DLL támogatás kliens fejlesztőknek-------------------------------------------------------------------- 14

1.8.

DLL függvénykészlete------------------------------------------------------------------------------------ 15

1.8.1. 1.8.2. 1.8.3. 1.8.4. 1.8.5.

Hiba lekérdező függvény ---------------------------------------------------------------------------------------- 15 Inicializáló függvények ------------------------------------------------------------------------------------------ 15 Technikai jellegű függvények ----------------------------------------------------------------------------------- 17 Input Gateway függvények -------------------------------------------------------------------------------------- 18 Output Gateway függvények ------------------------------------------------------------------------------------ 19

OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 1/24

v4.1.0.0

FGSZ - X_PROMPT

1.

OTR GW SOAP SZOLGÁLTATÁS

1.1. BEVEZETŐ Az OTR GW SOAP szolgáltatás (GWSOAPSRV) a hagyományos IGW (adatfeladó) és OGW (lekérdező) funkciókat biztosítja, mely kizárólag adatszolgáltatási szerződéssel rendelkező partnerek számára elérhető. A szolgáltatás háttere a SOAP elnevezésű XML alapú kommunikációs és üzenetküldő protokoll. A biztonságos hálózati adatforgalmat az SSL protokoll réteg és a digitális tanusítványok alkalmazása biztosítja. A szolgáltató elvárja a partnerektől, hogy a biztonságos https://hostname:port címet használják a szolgáltatás igénybe vételekor (távoli eljárás hívásokkor) és saját digitális tanusítványukkal azonosítsák magukat. A nem ismert, nem hitelesített digitális tanusítvánnyal érkező kéréseket a szerver nem szolgálja ki. Adatszolgáltatási szerződéstől függően nem minden partner rendelkezik egyaránt IGW és OGW jogosultsággal, ezért amennyiben a szolgáltatás igénybe vételekor a partner azonosítása sikeres, a kiszolgálás előtt a szerver ellenőrzi a partner adott eljárás hívási jogosultságát. Kizárólag IGW jogosultsággal rendelkező partner csak az IGW funkciókat használhatja, valamennyi OGW jellegű kérését visszautasítja a szerver. Ugyanígy, a kizárólag OGW jogosultsággal rendelkező partner csak az OGW funkciókat veheti igénybe, IGW jellegű kérései nem kerülnek kiszolgálásra.

1.2. SZOLGÁLTATÁS ELÉRHETŐSÉGE A szolgáltatás az elsődleges és a tartalék központban érhető el, illetve létezik egy teszt környezet is, ami jelenleg csak korlátozottan áll rendelkezésre.

1.3. GWSOAPSRV JELLEMZŐI A szerver itt ismertetett jellemzői nem véglegesek, azok a szolgáltató igényei illetve az üzemszerű működés során kapott statisztikák és visszajelzések alapján a későbbiekben változhatnak. SOAP szerver paraméterek:  MAX_QUEUE = 100  MAX_THREAD = 10  MAX_CONN = 200  CONN_EXP_TIME = 7200 (másodperc)  CERT_WARN_DAYS = 10 (nap)  TIME_LIMIT = 60 (másodperc) OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 2/24

v4.1.0.0

FGSZ - X_PROMPT



MAX_REQUEST = 30

1.3.1. LISTÁK, SZÁLAK, KORLÁTOZÁSOK A szerver maximálisan 100 kérést tud egyidőben fogadni, belső listában tárolni. A kéréseket maximum 10 szálon tudja párhuzamosan feldolgozni. A szerver által eltárolható kliens kapcsolatok, leírások száma maximum 200 lehet. Egy GW partner számára egyidőben maximálisan 10 hely biztosított a 200 férőhelyes kapcsolati tömbben. A távoli eljárás hívások gyakoriságára bevezetett korlátozás 30 db/perc. A kapcsolati lejárati idő korlátozza a 200 férőhelyes kapcsolati tömbben lefoglalt, de nem használt helyek fenntartását. Az szerver felszabadítja azokat a lefoglalt pozíciókat, melyek a vizsgálat időpontját megelőző 120 percben inaktívak voltak. A kialakítás biztosítja, hogy ha már van allokálva pozíció a partner számára, akkor a szolgáltatást folyamatosan igénybe tudja venni, ne fordulhasson elő, hogy felszabaduló pozícióra kelljen várnia, ugyanakkor meg is akadályozza, hogy a belső kapcsolati tömb inaktív kapcsolatokkal telítődjön.

1.3.2. TANUSÍTVÁNY Ha a kliens tanusítványa 10 napon belül lejár, a szerver a kérést kiszolgáló válasz struktúrában erről tájékoztatást küld. Érvénytelen, lejárt tanusítvánnyal érkező kéréseket a szerver nem szolgálja ki.

1.4. INFORMÁCIÓK KLIENS FEJLESZTŐK SZÁMÁRA Az alfejezetben bemutatott példákban a felhasználásával készültek.

gSOAP Tooklit

version 2.8.11 eszköztár

Kliens alkalmazás fejlesztéséhez az alábbi két parancs futtatásával állnak elő a metódusokat, struktúrákat leíró C forráskódú header és egyéb állományok: wsdl2h -c -o myheader GWSOAPSRV.wsdl soapcpp2 -c myheader

ahol myheader egy szabadon megadható header állomány neve (például gwcl.h), a GWSOAPSRV.wsdl fájlt pedig a szolgáltatótól kell igényelni, illetőleg letölthető az OTR portálról (a pontos elérhetőség később kerül megadásra). Mindkét program részét képezi a gSOAP Tooklit eszköztárnak, ami Linux és Windows környezetben egyaránt használható. A programok által generált állományokban az alapértelmezett névtér az „ns2”. Ettől eltérő névtér (namespace) prefix alkalmazásához a fenti két programmal megegyező könyvtárba be kell másolni vagy létre kell hozni a typemap.dat állományt, melybe a következő sort kell beilleszteni: # ns2 helyett gws legyen a prefix gws = "urn:gws" OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 3/24

v4.1.0.0

FGSZ - X_PROMPT

A kliens program forráskódjába az alábbi két sort kell beilleszteni: #indlude "soapH.h" #include "GWSOAPSRV.nsmap"

A elkészült kliens programot az alábbi állományokkal együtt kell fordítani/linkelni: 

soapC.c



soapClient.c



stdsoap2.c

Linux operációs rendszeren SSL használatához valamennyi forráskódot –DWITH_OPENSSL opcióval kell fordítani, linkelésnél pedig a -lssl és -lcrypto kiegészítéseket szükséges használni. Windows operációs rendszer alatti fejlesztés esetén első lépésként OpenSSL-t kell konfigurálni, telepíteni a fejlesztői gépre. A kliens program fordításánál a /D WITH_OPENSSL, linkelésénél pedig fakepath\OpenSSL\lib\libeay32.lib és fakepath\OpenSSL\lib\ssleay32.lib opciókat kell használni, ahol fakepath az OpenSSL telepítési helyének elérési útvonala. A fejlesztői támogatásként készült egy előre konfigurált OpenSSL csomag (OpenSSL.zip), ami minden szükséges elemet tartalmaz SSL kliens fejlesztéséhez, azonban az eltérő architektúrák miatt nem garantált a felhasználhatósága. Amennyiben a fordító program nem tudja értelmezni a csomagban található lib állományokat, úgy elkerülhetetlen az OpenSSL konfigurálása a fejlesztői gépen. Az OpenSSL ingyenesen letölthető a www.openssl.org/source oldalról.

1.4.1. KLIENS PROGRAM VÁZSZERKEZET Kliens program vázszerkezete: 

SOAP SSL inicializálás, kliens kontextus létrehozása. Itt kell megadni a kommunikáció során használt tanusítvány fájlt és a hozzá tartozó jelszót.



Távoli eljárás hívás, melynek egyik paramétere a létrehozott kliens kontextus.



Válasz kiértékelése.



SOAP kontextus lezárása, memória allokációk felszabadítása.

1.5. METÓDUSOK ÉS STRUKTÚRÁK A szerver által biztosított metódusok három csoportba sorolhatók: 

technikai: életjel lekérdező metódus,



input gateway: IGW funkciókat ellátó metódusok,



output gateway: OGW funkciókat ellátó metódosok.

Megjegyzések: 

A metódusok és struktúrák a gws névtér alkalmazásával kerülnek bemutatásra.


v4.1.0.0

FGSZ - X_PROMPT



A metódusok meghívására válaszként érkező struktúrában (Response) megismétlődik a kérdés leírása, amit a Request struktúra tartalmaz. A tényleges választ az Answer struktúra tartalmazza.



A Request struktúra tartalmazza a kliens által használt tanusítvány közelgő lejáratára figyelmeztető mezőt, melyet a kliensnek figyelnie kell annak érdekében, hogy a tanusítványát még időben meg tudja újítani. Lejárt tanusítvánnyal a szolgáltatás nem vehető igénybe. 0 érték esetén nincs figyelmeztetés, nullánál nagyobb egész érték a lejáratig hátralévő napok számát jelenti.



A Request struktúra tartalmaz öt további, a kiszolgáláshoz kapcsolódó technikai jellegű adatot: o kérés fogadásának ideje: azon időpont, amikor a szerverhez eljutott a kérés, o kérés kiszolgálásának kezdete: azon időpont, amikor a szerver megkezdte a kérés kiszolgálását, o kérés kiszolgálásának vége: azon időpont, amikor a szerver befejezte a kérés kiszolgálását, o várakozási idő: a kérés fogadása és a kérés kiszolgálásanak kezdete között eltelt idő, o kiszolgálási idő: kérés kiszolgálásanak kezdete és vége között eltelt idő.

1.5.1. TECHNIKAI JELLEGŰ METÓDUSOK Technikai jellegű metódusok: 

GetLifeSign: szerver életjel lekérdezés.

GETLIFESIGN METÓDUS Leírás: Szerver/szolgáltatás elérhetőségét tesztelő metódus. Az elérhetőség természetesen valamennyi kiajánlott metódussal tesztelhető, az életjel lekérdező metódus azonban annyiban különbözik a többitől, hogy szerver oldalon – a tanusítvány ellenőrzésén túl – semmiféle tevékenységet nem végez. A metódus hívásának lehetséges kimenetei három csoportba sorolhatók: 

A szerver/szolgáltatás elérhetetlensége miatt a kérésre nem érkezik válasz, a metódus hívás „timeout”-tal ér véget.



A szerver/szolgáltatás elérhető, így a kérésre érkezik válasz, de a visszatérési érték vagy szerver (például a szerver túlterhelt) vagy kliens (például hibás tanusítvány) oldali hibát jelez.



A szerver/szolgáltatás elérhető, a kérésre érkezik válasz és a visszatérési érték sikeres végrehajtást jelez. Ebben az esetben a válasz struktúrából is kiolvasható a szerver/szolgáltatás elérhetőségének pozitív státusza.


v4.1.0.0

FGSZ - X_PROMPT

1.5.2. INPUT GATEWAY METÓDUSOK Input Gateway metódusok: 

SendData: adatfeladás OTR-be,



SendMinta: mintaáram adatsor feladása OTR-be.

SENDDATA METÓDUS Leírás: Input Gateway, azaz adatfeladás OTR-be funkciót biztosító metódus. Az adatfeladáshoz kapcsolódóan a kliensnek típus szinten definiálnia kell a célállományt. Adatfolyamként pedig egy, a szerver által definiált struktúrájú dinamikus struktúra tömböt kell küldenie feldolgozásra. Az előírt struktúra és a mezők használata: 

dataid_s: OTR4-ben ismert alfanumerikus karakter sorozat vagy,



dataid_n: OTR4-ben ismert numerikus belső azonosító,



value: az adat értéke,



estat: az adat státusza, érvényes (üres szöveg mező) vagy érvénytelen (”!”),



time_prin: az adat elvi ideje, formátuma YYYY-MM-DD HH:MI:SS (opcionális),



time_prin_tzhour: az adat elvi idejéhez kapcsolódó időzóna információ (opcionális),



time_fr: az adat képzési ideje, formátuma YYYY-MM-DD HH:MI:SS (opcionális),



time_fr_tzhour: az adat képzési idejéhez kapcsolódó időzóna információ (opcionális).

Egy adat rekordban vagy a dataid_s vagy a dataid_n mezőnek kötelezően kitöltöttnek kell lennie, hogy az adat azonosítható legyen. Ha az idő mezők kitöltetlenek, akkor a szerver oldalon az aktuális időt veszik fel értékként. Az időzóna mezők kitöltöttségének akkor van jelentősége, ha a nyári-téli óraállításkor az egymást követő két hajnali 2 órás adatnál a feladó jelezni akarja, hogy a feladott hajnali 2 órás adat a nyári vagy a téli időszámítás szerinti 2 órához kapcsolódik. A szerver a válaszban visszaigazolásként megküldi a kliens által küldött adatfolyamból kiolvasott, illetve a sikeresen feldolgozott rekordok számát. A válasz kérést összegző részében megjelenik a kliens tanusítványának lejáratáig hátralévő napok száma, amennyiben az kevesebb mint a szerver oldalon beállított figyelmeztetés küldési limit, továbbá a kiszolgáláshoz kapcsolódó öt technikai jellegű adat (kérés fogadásának ideje, kérés kiszolgálásának kezdete és vége, várakozási idő, kiszolgálási idő).

SENDMINTA METÓDUS Leírás: Mintaáram adatsor OTR-be történő feladását biztosító metódus. Az adatfeladáshoz kapcsolódóan a kliensnek típus szinten definiálnia kell a célállományt. Adatfolyamként pedig egy, a szerver által definiált struktúrájú dinamikus struktúra tömböt kell küldenie feldolgozásra. Az előírt struktúra és a mezők használata: OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 6/24

v4.1.0.0

FGSZ - X_PROMPT

Mezőnév

Adattípus

Megnevezés

MINTA_KOD

char*

Mintaáram karakteres azonosítója.

MINTALETTER

char*

Mintaáram betűkód.

PERIOD

char*

Adatsor periódus: ”N”, ”O”, ”P”.

CO2

double

CO2 co2 (Szén-dioxid).

N2

double

NIT n2 (Nitrogén).

C1

double

MTH c1 (Metán).

C2

double

ETH c2 (Etán).

C3

double

PRO c3 (Propán).

I_C4

double

IBT i-c4 (iBután).

N_C4

double

NBT n-c4 (nBután).

NEO_C5

double

Neo-Pentán (Neo-C5H12).

I_C5

double

IPN i-c5 (iPentán).

N_C5

double

NPN n-c5 (nPentán).

C6

double

C6P c6+ (Hexan plus).

FUT_15

double

FTR Fűtőérték (száraz, alsó).

RELS_15

double

RSG Relatív sűrűség.

WOBBE_15

double

Wobbe szám.

EGES_15

double

Égéshő.

FUT_25

double

FTR Fűtőérték (száraz, alsó).

RELS_25

double

RSG Relatív sűrűség.

WOBBE_25

double

Wobbe szám.

EGES_25

double

Égéshő.

ESTAT

char*

Összevont státuszból képzett egyszerűsített státusz, érvényes (””) vagy érvénytelen (”!”).

TIME_PRIN

char*

Az adat elvi ideje, időazonosítója, formátuma YYYY-MM-DD HH:MI:SS.

TIME_PRIN_TZHOUR

char*

Az adat elvi idejéhez kapcsolódó időzóna információ (opcionális)1.

TIME_FR

char*

Az adat képzési ideje, formátuma YYYY-MM-DD HH:MI:SS (opcionális).

TIME_FR_TZHOUR

char*

Az adat képzési idejéhez kapcsolódó időzóna információ (opcionális) 1.

1

Az időzóna mezők kitöltöttségének akkor van jelentősége, ha a nyári-téli óraállításkor az egymást követő két hajnali 2 órás adatnál a feladó jelezni akarja, hogy a feladott hajnali 2 órás adat a nyári vagy a téli időszámítás szerinti 2 órához kapcsolódik. OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 7/24

v4.1.0.0

FGSZ - X_PROMPT

A szerver a válaszban visszaigazolásként megküldi a kliens által küldött adatfolyamból kiolvasott, illetve a sikeresen feldolgozott rekordok számát. A válasz kérést összegző részében megjelenik a kliens tanusítványának lejáratáig hátralévő napok száma, amennyiben az kevesebb mint a szerver oldalon beállított figyelmeztetés küldési limit, továbbá a kiszolgáláshoz kapcsolódó öt technikai jellegű adat (kérés fogadásának ideje, kérés kiszolgálásának kezdete és vége, várakozási idő, kiszolgálási idő).

1.5.3. OUTPUT GATEWAY METÓDUSOK Output Gateway metódusok: 

GetSignInfo: jelinformáció lekérdezése OTR-ből,



GetIDHist: azonosító változás lekérdezése OTR-ből,



GetArchive: archívum lekérdezés OTR-ből,



GetMinta: mintaáram adatsor lekérdezés OTR-ből,



GetElszpont: elszámolási pont adatsor lekérdezés OTR-ből.

GETSIGNINFO METÓDUS Leírás: A metódussal a partner a számára hozzáférésre engedélyezett jelek alapinformációt tudja lekérdezni OTR-ből. A lekérdezéshez kapcsolódóan a kliensnek két input paraméter áll rendelkezésre, hogy specifikálhassa a lekérdezést: azonosító maszk és jeltípus (P: elsődleges, mért jelek, C: származtatott jelek). Az azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén egy rekord, üres sztring esetén a hozzáférésre engedélyezett valamennyi rekord, maszk esetén a maszkra illeszkedő rekordok adják az eredmény halmazt, amit a jeltípus paraméterrel még tovább lehet szűkíteni. Üres, vagy nem szabályosan megadott jeltípus esetén a jeltípusra nem történik szűrés. A válaszban a szerver által definiált struktúrájú dinamikus struktúra tömb érkezik, amely a kérésnek megfelelő jellistát tartalmazza. A válasz kérést összegző részében megjelenik a kliens tanusítványának lejáratáig hátralévő napok száma, amennyiben az kevesebb mint a szerver oldalon beállított figyelmeztetés küldési limit, továbbá a kiszolgáláshoz kapcsolódó öt technikai jellegű adat (kérés fogadásának ideje, kérés kiszolgálásának kezdete és vége, várakozási idő, kiszolgálási idő).

GETIDHIST METÓDUS Leírás: A metódussal a partner a számára hozzáférésre engedélyezett jelek azonosító változásait tudja lekérdezni OTR-ből. A lekérdezéshez kapcsolódóan a kliensnek három input paraméter áll rendelkezésre, hogy specifikálhassa a lekérdezést: azonosító maszk, jeltípus (P: elsődleges, mért jelek, C: származtatott jelek) és keresési mód (régi vagy új azonosító szerint). OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 8/24

v4.1.0.0

FGSZ - X_PROMPT

Az azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén egy rekord, üres sztring esetén a hozzáférésre engedélyezett valamennyi rekord, maszk esetén pedig a maszkra illeszkedő rekordok adják az eredmény halmazt, amit a jeltípus paraméterrel még tovább lehet szűkíteni. Üres, vagy nem szabályosan megadott jeltípus esetén a jeltípusra nem történik szűrés. A keresési móddal lehet meghatározni, hogy a feltételeknek megfelelő jelhalmazt a régi vagy az új azonosítók között keresse a kiszolgáló szerver. A válaszban a szerver által definiált struktúrájú dinamikus struktúra tömb érkezik, amely a kérésnek megfelelő jellistát tartalmazza. A válasz kérést összegző részében megjelenik a kliens tanusítványának lejáratáig hátralévő napok száma, amennyiben az kevesebb mint a szerver oldalon beállított figyelmeztetés küldési limit, továbbá a kiszolgáláshoz kapcsolódó öt technikai jellegű adat (kérés fogadásának ideje, kérés kiszolgálásának kezdete és vége, várakozási idő, kiszolgálási idő).

GETARCHIVE METÓDUS Leírás: A metódussal a partner az OTR GW archívum számára hozzáférésre engedélyezett szegmensét tudja lekérdezni. A lekérdezéshez kapcsolódóan a kliensnek hat input paraméter áll rendelkezésre, hogy specifikálhassa a lekérdezést: azonosító maszk, keresési intervallum kezdete és vége, relatív keresési intervallum (napban kifejezve, tört érték használata megengedett), jeltípus (P: elsődleges, mért jelek, C: származtatott jelek) és archív szegmens (L: utolsó adat, P: pillanatérték, O: órás, N: napi, H: havi, R: újraszámított). Az azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén a megadott jel, üres sztring esetén a hozzáférésre engedélyezett valamennyi jel, maszk esetén a maszkra illeszkedő jelek archív adatai adják az eredmény halmazt, amit a jeltípus paraméterrel még tovább lehet szűkíteni. Üres, vagy nem szabályosan megadott jeltípus esetén a jeltípusra nem történik szűrés. A keresési intervallummal a találati halmaz időben szűkíthető. Az időmaszkok formátuma “2012-11-30 00:00:00”, de megadása esetén nem kötelező a teljes maszkot használni, így például a “2012-11-30 00” is elegendő. Az archív szegmenssel kell kijelölni, hogy az adatokat mely forrásból kell kigyűjtenie a szervernek. Az időbeli szűrésre önmagában illetve az időmaszkokkal kombináltan használható a relatív keresési intervallum. A három paraméter használanának lehetséges kombinációi: Intervallum kezdete időmaszk

Intervallum vége Relatív intervallum időmaszk

Szűrés eredménye

üres

üres

0

Nincs időbeli szűrés

üres

üres

n>0

Szűrés az utolsó „n” napra

megadott

üres

0

Szűrés a megadott intervallumnál frissebb adatokra

megadott

üres

n>0

Szűrés a megadott intervallum után, de „n” napon belül képződött adatokra

üres

megadott

0

Szűrés a megadott intervallumnál régebbi adatokra


v4.1.0.0

FGSZ - X_PROMPT

üres

megadott

n>0

Szűrés a megadott intervallum előtti „n” napon belül képződött adatokra

megadott

megadott

0

Szűrés a két intervallum között képződött adatokra

megadott

megadott

n>0

Szűrés a két intervallum között képződött adatokra, a relatív intervallum nincs figyelembe véve

A válaszban a szerver által definiált struktúrájú dinamikus struktúra tömb érkezik, amely a kérésnek megfelelő archívumot tartalmazza. A válasz kérést összegző részében megjelenik a kliens tanusítványának lejáratáig hátralévő napok száma, amennyiben az kevesebb mint a szerver oldalon beállított figyelmeztetés küldési limit, továbbá a kiszolgáláshoz kapcsolódó öt technikai jellegű adat (kérés fogadásának ideje, kérés kiszolgálásának kezdete és vége, várakozási idő, kiszolgálási idő).

GETMINTA METÓDUS Leírás: A metódussal a partner a hozzáférésre engedélyezett mintaáramokhoz kötött adatsorokat tudja lekérdezni OTR-ből. A lekérdezéshez kapcsolódóan a kliensnek hat input paraméter áll rendelkezésre, hogy specifikálhassa a lekérdezést: mintaáram azonosító maszk, mintaáram betűkód, periódusidő, keresési intervallum kezdete és vége, relatív keresési intervallum. A mintaáram azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén a megadott mintaáram, üres sztring esetén a hozzáférésre engedélyezett valamennyi mintaáram, maszk esetén a maszkra illeszkedő mintaáramhoz kötött adatsorok adják az eredmény halmazt. A betűkód maszk paraméter használata megfelel a mintaáram azonosító maszknál leírtakkal. A mintaáramhoz kötött adatok periódusidő alapján három csoportba sorolhatók: pillanatérték (“P”), órás (“O”) illetve napi (“N”) adat. A periódusidő paraméterrel az adatsorok ezen jelleg alapján szűrhetők a lekérdezések során. A kódok tetszőleges kombinációban és sorrendben megadhatók (például a “P” csak pillanatérték adatsorokra szűr, az “ON” megadásával pedig órás és napi adatsorok adják az eredmény halmazt). Ha a paraméter nincs kitöltve, akkor nem történik szűrés periódusidőre. Megegyező eredményt hoz, ha a paraméterben mindhárom karakter megadásra kerül tetszőleges sorrendben (például “NOP”). Nem szabályosan megadott periódusidő esetén a periódusidőre nem történik szűrés. A keresési intervallummal a találati halmaz időben szűkíthető. Az időmaszkok formátuma “2012-11-30 00:00:00”, de megadása esetén nem kötelező a teljes maszkot használni, így például a “2012-11-30 00” is elegendő. Az időbeli szűrésre önmagában illetve az időmaszkokkal kombináltan használható a relatív keresési intervallum. A paraméter értelmezése függ a periódusidő paraméter tartalmától, mindig a legnagyobb periódushoz igazodik. Pillanatérték (“P”) esetén a relatív keresési intervallum értéke percként értelmezendő, órás (“O”) szűrés esetén óraként, napi (“N”) szűrés esetén pedig napként. A periódusidők együttes alkalmazhatósága miatt a keresési intervallumra vonatkozó korlátozás, hogy amennyiben a pillanatérték periódus bármilyen kombinációban szerepel a periódusidő paraméterben, akkor a keresési intervallum nem lehet több 1 napnál. OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 10/24

v4.1.0.0

FGSZ - X_PROMPT

Az időmaszk és relatív intervallum paraméterek használanának lehetséges kombinációi: Intervallum kezdete időmaszk


Szűrés eredménye

üres

üres

0

Nincs időbeli szűrés1

üres

üres

n>0

Szűrés az utolsó „n” periódusra1,2

megadott

üres

0

Szűrés a megadott intervallumnál frissebb adatokra1

megadott

üres

n>0

Szűrés a megadott intervallum után, de „n” perióduson belül képződött adatokra1,2

üres

megadott

0

Szűrés a megadott intervallumnál régebbi adatokra1

üres

megadott

n>0

Szűrés a megadott intervallum előtti „n” perióduson belül képződött adatokra1,2

megadott

megadott

0

Szűrés a két intervallum között képződött adatokra3

megadott

megadott

n>0

Szűrés a két intervallum között képződött adatokra, a relatív intervallum nincs figyelembe véve3

Amennyiben a pillanatérték periódus bármilyen kombinációban szerepel a periódusidő paraméterben, akkor a keresési intervallum nem lehet több 1 napnál. 1

2

A periódus minden esetben a periódusidő paraméter alapján kigyűjtendő legnagyobb periódusú

adatsor mértékegységeként értelmezendő (például “PO” esetén a relatív intervallum 2 értéke 2 órát jelent). 3

Amennyiben a pillanatérték periódus bármilyen kombinációban szerepel a periódusidő

paraméterben, akkor a keresési intervallum nem lehet több 1 napnál, ami az intervallum kezdetéhez igazodik. A válaszban a szerver által definiált struktúrájú dinamikus struktúra tömb érkezik, amely a kérésnek megfelelő mintaáram adatsorokat tartalmazza. A válasz kérést összegző részében megjelenik a kliens tanusítványának lejáratáig hátralévő napok száma, amennyiben az kevesebb mint a szerver oldalon beállított figyelmeztetés küldési limit, továbbá a kiszolgáláshoz kapcsolódó öt technikai jellegű adat (kérés fogadásának ideje, kérés kiszolgálásának kezdete és vége, várakozási idő, kiszolgálási idő).

GETELSZPONT METÓDUS Leírás: A metódussal a partner a hozzáférésre engedélyezett elszámolási ponthoz kötött adatsorokat tudja lekérdezni OTR-ből. A lekérdezéshez kapcsolódóan a kliensnek öt input paraméter áll rendelkezésre, hogy specifikálhassa a lekérdezést: elszámolási pont azonosító maszk, periódusidő, keresési intervallum kezdete és vége, relatív keresési intervallum. OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 11/24

v4.1.0.0

FGSZ - X_PROMPT

Az elszámolási pont azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén a megadott elszámolási pont, üres sztring esetén a hozzáférésre engedélyezett valamennyi elszámolási pont, maszk esetén a maszkra illeszkedő elszámolási pontokhoz kötött adatsorok adják az eredmény halmazt. Az elszámolási ponthoz kötött adatok periódusidő alapján két csoportba sorolhatók: órás (’O’) illetve napi (’N’) adat. A periódusidő paraméterrel az adatsorok ezen jelleg alapján szűrhetők a lekérdezések során. Ha a paraméter nincs kitöltve, akkor nem történik szűrés periódusidőre. A keresési intervallummal a találati halmaz időben szűkíthető. Az időmaszkok formátuma “2012-11-30 00:00:00”, de megadása esetén nem kötelező a teljes maszkot használni, így például a “2012-11-30 00” is elegendő. Az időbeli szűrésre önmagában illetve az időmaszkokkal kombináltan használható a relatív keresési intervallum. A paraméter értelmezése függ a periódusidő paraméter tartalmától, mindig a legnagyobb periódushoz igazodik. Órás (’O’) szűrés esetén óraként, napi (’N’) szűrés esetén pedig napként értelmezendő a relatív keresési intervallum. Ha nem történik szűrés a periódus időre, akkor a napi jelleg a legnagyobb periódus, így a relatív keresési intervallum is napként értelmezendő. Az időmaszk és relatív intervallum paraméterek használanának lehetséges kombinációi: Intervallum kezdete időmaszk


Szűrés eredménye

üres

üres

0

Nincs időbeli szűrés

üres

üres

n>0

Szűrés az utolsó „n” periódusra1

megadott

üres

0

Szűrés a megadott intervallumnál frissebb adatokra

megadott

üres

n>0

Szűrés a megadott intervallum után, de „n” perióduson belül képződött adatokra1

üres

megadott

0

Szűrés a megadott intervallumnál régebbi adatokra

üres

megadott

n>0

Szűrés a megadott intervallum előtti „n” perióduson belül képződött adatokra1

megadott

megadott

0

Szűrés a két intervallum között képződött adatokra

megadott

megadott

n>0

Szűrés a két intervallum között képződött adatokra, a relatív intervallum nincs figyelembe véve

A periódus minden esetben a periódusidő paraméter alapján kigyűjtendő legnagyobb periódusú adatsor mértékegységeként értelmezendő (például “NO” esetén a relatív intervallum 2 értéke 2 napot jelent). 1

A válaszban a szerver által definiált struktúrájú dinamikus struktúra tömb érkezik, amely a kérésnek megfelelő elszámolási pontokhoz kötött adatsorokat tartalmazza. OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 12/24

v4.1.0.0

FGSZ - X_PROMPT

A válasz kérést összegző részében megjelenik a kliens tanusítványának lejáratáig hátralévő napok száma, amennyiben az kevesebb mint a szerver oldalon beállított figyelmeztetés küldési limit, továbbá a kiszolgáláshoz kapcsolódó öt technikai jellegű adat (kérés fogadásának ideje, kérés kiszolgálásának kezdete és vége, várakozási idő, kiszolgálási idő).

1.5.4. GATEWAY METÓDUSOK ARGUMENTUMAI Az előző alfejezetekben bemutatott Input Gateway és Output Gateway metódusok lekérdezést szűkítő argumentumai:  idmask: azonosító maszk (SQL-es LIKE-nak megfelelő formátum),  sigtype: ”P” (elsődleges, mért) vagy “C” (számított/származtatott),  is_oldid: azonosító változás lekérdezésekor annak jelölése, hogy a megadott idmask-ot OLDDATAID-ként (1) van NEWDATAID-ként (0) keresse a metódus,  time_start: elvi idő, aminél frissebb adatokat kell az archívumból kikeresni; formátuma “2011-07-14 00:00:00”, de megadása esetén nem kötelező a teljes maszkot használni, így például a “2011-07-14 00” is elegendő,  time_end: elvi idő, aminél régebbi adatokat kell az archívumból kikeresni; formátuma “2011-07-14 08:00:00”, de megadása esetén nem kötelező a teljes maszkot használni, így például a “2011-07-14 08” is elegendő,  segment: archív szegmens (“L” – utolsó adat, “P” – pillanatérték, “O” – órás, “N” – napi, “H” – havi, “R” – újraszámított),  lettermask: betűkód maszk (SQL-es LIKE-nak megfelelő formátum),  period: mintaáram illetve elszámolási pont adatsor periódus ideje (“P” – pillanatérték, “O” – órás, “N” – napi),  send_to: adatküldés esetén a szerver ORACLE táblába (“T”) vagy nézetbe (“V”) írja az adatokat.

1.6. HIBAKEZELÉS A metódus hívások SOAP státuszkóddal térnek vissza. Ha a státusz kód nem SOAP_OK, akkor vagy a küldés vagy a feldolgozás vagy a fogadás során hiba lépett fel. A hibák ennek megfelelően két csoportba sorolhatók:  SOAP hiba,  GWSOAPSRV hiba. A hiba leírás mindkét esetben a metódus hivások első argumentumaként megadott soap objektumból nyerhető ki. Korábbi fejezetben bemutatott példákban ezen objektum a mysoap: 

mysoap->fault


v4.1.0.0

FGSZ - X_PROMPT

1.6.1. GWSOAPSRV HIBAÜZENETEK KLIENS OLDALI HIBAÜZENETEK Faultstring

Faultdetail

GWS-C-2006 Hibás vagy nem regisztrált email cím GWS-C-2009 Hibás archív szegmens kód GWS-C-2010 A megadott azonosító maszk túl hosszú GWS-C-2011 A megadott kezdő időmaszk túl hosszú vagy 4 karakternél rövidebb GWS-C-2012 A megadott vegső időmaszk túl hosszú vagy 4 karakternél rövidebb GWS-C-2014 Nem érkezett feldolgozandó adat GWS-C-2015 Az azonosító mező értelmezési módja nem egyértelmű: %s, %llu GWS-C-2016 A kliensnek nincs OGW jogosultsága GWS-C-2017 A kliensnek nincs IGW jogosultsága GWS-C-2021 A megadott azonosító maszk üres GWS-C-2022 A küldött RTU rekordban az RTUID üres GWS-C-2026 Lekérdezések száma elérte az engedélyezett limitet. A számláló törléséig hátralévö idő: %d mp GWS-C-2027 A megadott betűkód maszk túl hosszú GWS-C-2028 A küldött MINTA_KOD üres GWS-C-2029 Hibás tanusítvány, nincs megadva email cím az azonosításhoz

SZERVER OLDALI HIBAÜZENETEK Faultstring

Faultdetail

GWS-S-1001

A szerver túlterhelt

GWS-S-1002

Szerver adatbázis hiba

GWS-S-1003

Szerver oldali hiba

GWS-S-1005

A csatornan tul sok kiszolgalas van folyamatban

1.7. DLL TÁMOGATÁS KLIENS FEJLESZTŐKNEK Az XP_SOAP.DLL egy olyan függvénykészletet kínál kliens fejlesztőknek, melyben minden SOAP és SSL vonatkozású elem rejtve van, így a fejlesztés során a SOAP és SSL megoldásokkal nem kell foglalkozni. A DLL használata nem igényel semiféle SOAP OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 14/24

v4.1.0.0

FGSZ - X_PROMPT

eszközkészlet használatot, fordítási, linkelési opciót, nem kell lekérdezni a WSDL-t, struktúrákat kifejteni, elemezni, SOAP hibaüzeneteket kiformázni. A DLL függvénykészletével az OTR GW SOAP szolgáltatásának metódusai egyszerűen használhatók, az esetlegesen kapott hibaüzenetek egyszerűen lekérdezhetők. A DLL C programnyelven készült.

1.8. DLL FÜGGVÉNYKÉSZLETE A DLL függvénykészlete hat csoportba sorolható: 

hiba lekérdező: GWSOAPSRV illetve DLL hibaüzeneteit lekérdező függvény,



inicializáló: a metódusok statikus argumentumait inicializáló és kezelő függvények,



technikai: életjel lekérdező metódust meghívó függvény,



input gateway: IGW funkciót meghívó függvény,



output gateway: OGW funkciókat meghívó függvények.

1.8.1. HIBA LEKÉRDEZŐ FÜGGVÉNY Hiba lekérdező függvény: 

xp_soap_fault: GWSOAPSRV illetve DLL hibaüzeneteit lekérdező függvény.

XP_SOAP_FAULT FÜGGVÉNY

Leírás: GWSOAPSRV illetve a DLL függvények hibaüzeneteit lekérdezéső függvény. A függvény az fstring-ben adja vissza a hibakódot (pl. DLL-E-005), az fdetail-ben pedig a hiba leírását. Sikeres végrehajtás esetén a függvény visszatérési értéke 0. A visszatérési érték 1, ha a megelőző DLL függvény hívása/végrehajtása sikeres volt és így nincs lekérdezhető hibaüzenet.

1.8.2. INICIALIZÁLÓ FÜGGVÉNYEK Inicializáló függvények: 

xp_soap_init: metódusok statikus argumentumainak inicializálása,



xp_soap_getinit: inicializált statikus argumentumok lekérdezése,



xp_soap_saveinit: inicializált statikus argumentumok értékeinek fájlba mentése.

XP_SOAP_INIT FÜGGVÉNY

Leírás: Az SSL kliens kontextus inicializálásnak és a távoli eljárás hívásoknak vannak olyan argumentumai (tanusítvány fájl neve, tanusítványhoz kapcsolódó kliens jelszó, szolgáltatás címe), melyek értékei statikusak vagy legalábbis nagyon ritkán változnak. Azért, hogy ezen OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 15/24

v4.1.0.0

FGSZ - X_PROMPT

elemeket ne kelljen minden egyes DLL függvény híváskor ismételten megadni, ki lettek emelve egy inicalizáló függvénybe, amit elegendő egyszer (esetleges változáskor) meghívni. Az így megadott értékek a DLL-en belül kerülnek felhasználásra akkor, amikor az valóban szükséges (SSL kliens kontextus inicializálás, távoli eljárás hívás). A DLL adminisztratív és Gateway függvényei használatához először az inicializáló függvényt kell meghívni. Inicializálás nélkül a függvények a “DLL-E-016 Az inicializálás még nem történt meg” hibaüzenettel térnek vissza. A függvény három inicializálási opciót kínál fel:  0 – inicializálás fájlból,  1 – inicializálás paraméterekkel. A választott inicializálás opciót az init_type paraméterben kell megadni. A további paraméterek használata/értelmezése a választott opciótól függ. Fájlból történő inicializálás esetén (init_type=0), a par1 paraméterben az inicializáló paramétereket tartalmazó fájl nevét kell megadni (elérési úttal együtt, amennyiben az nem a DLL fájllal megegyező könyvtárban található). Az inicializáló fájl egy szöveges állomány, amely az alábbi sorokat tartalmazza: fejléc, szerver, saját tanusítvány fájl neve. Biztonsági okokból a tanusítványhoz kapcsolódó jelszó nem tárolható az inicializáló állományban, így azt inicializáláskor a par2 paraméterben kell megadni. Paraméterekkel történő inicializálás esetén (init_type=1), a par1 paraméterben a GW SOAP szolgáltatás címét, par2-ben a tanusítvány fájl elérhetőségét, par3-ban pedig a tanusítványhoz kapcsolódó jelszót kell megadni. A fenti két lokális inicializáláshoz kapcsolódik egy életjel lekérdező távoli metódus hívás, aminek célja a tanusítvány érvényességének ellenőrzése és a partner beazonosíthatóságának vizsgálata. Az inicializás csak akkor tekinthető sikeresnek, befejezettnek, ha ezen távoli eljárás hívás végrehajtása sikeres. Sikeres végrehajtás esetén a cert_exp_in_days paraméterben megjelenik a tanusítvány lejáratáig hátralévő napok száma, amennyiben az kisebb-egyenlő mint 10. Sikeres inicializálás esetén a függvény visszatérési értéke 0. Sikeres inicializálás esetén a szerver, tanusítvány fájl elérhetősége és tanusítvány jelszó inicializáló paramétereket a DLL xp_soap_getinit függvényével lehet lekérdezni. Sikertelen végrehajtás során kapott hibaüzenetet az xp_soap_fault függvénnyel lehet lekérdezni. XP_SOAP_GETINIT FÜGGVÉNY

Leírás: Az inicializálás során beállított paraméterek lokális lekérdezése. A függvény a server-ben adja vissza a szolgáltatás címét, cert-ben a tanusítvány fájl nevét és elérhetőségét, pwd-ben pedig a tanusítványhoz tartozó jelszót. Sikeres végrehajtás esetén a függvény visszatérési értéke 0.


v4.1.0.0

FGSZ - X_PROMPT

XP_SOAP_SAVEINIT FÜGGVÉNY

Leírás: Az inicializálás során beállított paraméterek (szolgáltatás elérhetősége, tanusítvány fájl elérhetősége) fájlba mentése. A tanusítványhoz tartozó jelszó fájlba mentése biztonsági okokból nem történik meg. A filename paraméterben kell megadni a mentéshez használni kívánt fájl nevét. Elérési úttal együtt kell megadni, ha a cél könyvtár nem a DLL fájllal megegyező könyvtár. Sikeres végrehajtás esetén a függvény visszatérési értéke 0.

1.8.3. TECHNIKAI JELLEGŰ FÜGGVÉNYEK Technikai jellegű függvények: 

xp_soap_getlifesign: életjel lekérdezés.

XP_SOAP_GETLIFESIGN FÜGGVÉNY

Leírás: Szerver/szolgáltatás elérhetőségének tesztelésére szolgáló függvény. Az elérhetőség természetesen az IGW és OGW funkciókat biztosító függvényekkel is tesztelhető, az életjel lekérdező metódus azonban annyiban különbözik a többitől, hogy szerver oldalon – a tanusítvány ellenőrzésén túl – semmiféle tevékenységet nem végez. A függvény argumentumai mind kimenő paraméterek, amiket sikeres végrehajtás esetén lehet kiértékelni: 

status: sikeres végrehajtás esetén az értéke 1,



cert_exp_in_days: a tanusítvány lejáratáig hátralévő napok száma, amennyiben az kisebb-egyenlő mint 10,



waiting_time: kérés szerver oldali várakozási ideje,



serving_time: kérés kiszolgálási ideje,



time_receive: a kérés szerver oldali fogadásának ideje,



time_serve_start: a kérés kiszolgálásának kezdete,



time_serve_end: a kérés kiszolgálásának befejezési ideje.

Sikeres végrehajtás esetén a függvény visszatérési értéke 0.


v4.1.0.0

FGSZ - X_PROMPT

1.8.4. INPUT GATEWAY FÜGGVÉNYEK Input Gateway függvény: 

xp_soap_senddata: adatfeladás OTR-be,



xp_soap_sendminta: mintaáram adatsor feladása OTR-be.

XP_SOAP_SENDDATA FÜGGVÉNY

Leírás: A függvény az OTR GW SOAP szolgáltatás Input Gateway, azaz adatfeladás OTR-be metódusa meghívásával a paraméterként átadott dinamikus stuktúra tömbben található adatokat adja fel OTR-be. A célállományt az első paraméterben kell definiálni. Sikeres végrehajtás esetén a függvény visszatérési értéke nagyobb-egyenlő mint 0, ami a szerver által feldolgozott adatok számát jelenti. Negatív értéktartományba eső visszatérési érték minden esetben az jelenti, hogy a kérés elküldése vagy kiszolgálása közben hiba lépett fel. A függvény kimenő paraméterei és azok tartalmának értelmezése: 

















XP_SOAP_SENDMINTA FÜGGVÉNY

Leírás: A függvény az OTR GW SOAP szolgáltatás mintaáram adatsor feladás OTR-be metódusa meghívásával a paraméterként átadott dinamikus stuktúra tömbben található adatokat adja fel OTR-be. A célállományt az első paraméterben kell definiálni. Sikeres végrehajtás esetén a függvény visszatérési értéke nagyobb-egyenlő mint 0, ami a szerver által feldolgozott adatok számát jelenti. Negatív értéktartományba eső visszatérési érték minden esetben az jelenti, hogy a kérés elküldése vagy kiszolgálása közben hiba lépett fel. A függvény kimenő paraméterei és azok tartalmának értelmezése: 












v4.1.0.0

FGSZ - X_PROMPT







1.8.5. OUTPUT GATEWAY FÜGGVÉNYEK Output Gateway függvények: 

xp_soap_getsigninfo: jelinformáció lekérdezése OTR-ből,



xp_soap_getidhist: azonosító változás lekérdezése OTR-ből,



xp_soap_getarchive: archívum lekérdezés OTR-ből,



xp_soap_getminta: mintaáram adatsor lekérdezés OTR-ből,



xp_soap_getelszpont: elszámolási ponthoz kötött adatsor lekérdezés OTR-ből.

XP_SOAP_GETSIGNINFO FÜGGVÉNY

Leírás: A függvény az OTR GW SOAP szolgáltatás Output Gateway jelinformáció lekérdező metódusa meghívásával, a partner a számára hozzáférésre engedélyezett jelek közül a paraméterként átadott feltételeknek megfelelő elemeket szolgáltatja. A kigyűjtött jelek alapinformációi dinamikus stuktúra tömbben érkeznek, melyek a függvény harmadik paraméteréből olvashatók ki. A függvény bemenő paraméterei, melyekkel a lekérdezés specifikálható: 

azonosító maszk,



jeltípus (”P”: elsődleges, mért jelek, ”C”: származtatott jelek).

Az azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén egy rekord, üres sztring esetén a hozzáférésre engedélyezett valamennyi rekord, maszk esetén a maszkra illeszkedő rekordok adják az eredmény halmazt, amit a jeltípus paraméterrel még tovább lehet szűkíteni. Üres, vagy nem szabályosan megadott jeltípus esetén a jeltípusra nem történik szűrés. Sikeres végrehajtás esetén a függvény visszatérési értéke nagyobb-egyenlő mint 0, ami a szerver által kigyűjtött adatok számát jelenti. Negatív értéktartományba eső visszatérési érték minden esetben az jelenti, hogy a kérés elküldése vagy kiszolgálása közben hiba lépett fel. A függvény kimenő paraméterei és azok tartalmának értelmezése: 


















v4.1.0.0

FGSZ - X_PROMPT

XP_SOAP_GETIDHIST FÜGGVÉNY

Leírás: A függvény az OTR GW SOAP szolgáltatás Output Gateway jelazonosító változás történetét lekérdező metódusa meghívásával, a partner a számára hozzáférésre engedélyezett jelek közül a paraméterként átadott feltételeknek megfelelő elemeket szolgáltatja. A kigyűjtött adatok dinamikus stuktúra tömbben érkeznek, melyek a függvény negyedik paraméteréből olvashatók ki. A függvény bemenő paraméterei, melyekkel a lekérdezés specifikálható: 

azonosító maszk,



jeltípus (“P“: elsődleges, mért jelek, “C“: származtatott jelek),



keresési mód (1: régi vagy 2: új azonosító szerint).

Az azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén egy rekord, üres sztring esetén a hozzáférésre engedélyezett valamennyi rekord, maszk esetén a maszkra illeszkedő rekordok adják az eredmény halmazt, amit a jeltípus paraméterrel még tovább lehet szűkíteni. Üres, vagy nem szabályosan megadott jeltípus esetén a jeltípusra nem történik szűrés. A keresési móddal lehet meghatározni, hogy a feltételeknek megfelelő jelhalmazt a régi vagy az új azonosítók között keresse a kiszolgáló szerver. Sikeres végrehajtás esetén a függvény visszatérési értéke nagyobb-egyenlő mint 0, ami a szerver által kigyűjtött adatok számát jelenti. Negatív értéktartományba eső visszatérési érték minden esetben az jelenti, hogy a kérés elküldése vagy kiszolgálása közben hiba lépett fel. A függvény kimenő paraméterei és azok tartalmának értelmezése: 

















XP_SOAP_GETARCHIVE FÜGGVÉNY

Leírás: A függvény az OTR GW SOAP szolgáltatás Output Gateway archívum lekérdező metódusa meghívásával, a partner a számára hozzáférésre engedélyezett archív szegmensnek a paraméterként átadott feltételeknek megfelelő elemeit szolgáltatja. A kigyűjtött adatok dinamikus stuktúra tömbben érkeznek, melyek a függvény hatodik paraméteréből olvashatók ki. A függvény bemenő paraméterei, melyekkel a lekérdezés specifikálható: 

azonosító maszk,



keresési időszak kezdete és vége,


v4.1.0.0

FGSZ - X_PROMPT



keresési időszak kezdetéhez vagy végéhez igazított relatív keresési intervallum,



jeltípus (”P”: elsődleges, mért jelek, ”C”: származtatott jelek),



archív szegmens (”L” – utolsó adat, ”P” – pillanatérték, ”O” – órás, ”N” – napi, ”H” – havi, ”R” – újraszámított).

Az azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén a megadott jel, üres sztring esetén a hozzáférésre engedélyezett valamennyi jel, maszk esetén a maszkra illeszkedő jelek archív adatai adják az eredmény halmazt, amit a jeltípus paraméterrel még tovább lehet szűkíteni. Üres, vagy nem szabályosan megadott jeltípus esetén a jeltípusra nem történik szűrés. A keresési időszakkal a találati halmaz időben szűkíthető. Az időmaszkok formátuma “2012-1130 00:00:00”, de megadása esetén nem kötelező a teljes maszkot használni, így például a “201211-30 00” is elegendő. Az interval paraméter, melynek értéke kizárólag pozitív szám lehet, szintén időbeli szűrésre használható, de csak abban az esetben kerül felhasználásra, ha vagy a kezdő vagy a végző vagy mindkét időmaszk üres. A paraméterben megadott szám mértékegysége a „nap” (1.0 így például 1 napot, a 0.25 pedig 6 órát jelent). Nulla érték használata a paraméter figyelmen kívül hagyását jelenti. Ha az interval értéke nagyobb mint nulla és mindkét időmaszk üres, akkor az aktuális időhöz viszonyítva történik visszamenőleges szűrés. Ha az interval mellett csak a kezdő időmaszk van megadva, akkor a kezdő időmaszk által kijelölt időponthoz viszonyítva törtétnik előre mutató szűrés. Ha pedig az interval mellett csak a végző időmaszk van megadva, akkor a végző időmaszk által kijelölt időponthoz viszonyítva törtétnik szintén visszamenőleges szűrés. Ha az interval értéke nulla és mindkét időmaszk üres, akkor időre nem történik szűrés. Az archív szegmenssel kell kijelölni, hogy az adatokat mely forrásból kell kigyűjtenie a szervernek. Az időbeli szűrésről összefoglaló táblázat a GetArchive metódus és kapcsolódó struktúrák alfejezetben található. Sikeres végrehajtás esetén a függvény visszatérési értéke nagyobb-egyenlő mint 0, ami a szerver által kigyűjtött adatok számát jelenti. Negatív értéktartományba eső visszatérési érték minden esetben az jelenti, hogy a kérés elküldése vagy kiszolgálása közben hiba lépett fel. A függvény kimenő paraméterei és azok tartalmának értelmezése: 


















v4.1.0.0

FGSZ - X_PROMPT

XP_SOAP_GETMINTA FÜGGVÉNY

Leírás: A függvény az OTR GW SOAP szolgáltatás mintaáramhoz kötött adatsor lekérdező metódusa meghívásával a partner számára hozzáférésre engedélyezett mintaáram adatsorok paramétereknek megfelelő elemeit szolgáltatja. A kigyűjtött adatok dinamikus stuktúra tömbben érkeznek, melyek a függvény hetedik paraméteréből olvashatók ki. A függvény bemenő paraméterei, melyekkel a lekérdezés specifikálható: 

mintaáram azonosító maszk,



mintaáram betűkód maszk,



periódus (”P” – pillanatérték, ”O” – órás, ”N” – napi),






keresési időszak kezdetéhez vagy végéhez igazított relatív keresési intervallum.

A mintaáram azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén a megadott mintaáram, üres sztring esetén a hozzáférésre engedélyezett valamennyi mintaáram, maszk esetén a maszkra illeszkedő mintaáramhoz kötött adatsorok adják az eredmény halmazt. A betűkód maszk paraméter használata megfelel a mintaáram azonosító maszknál leírtakkal. A mintaáramhoz kötött adatok periódusidő alapján három csoportba sorolhatók: pillanatérték (“P”), órás (“O”) illetve napi (“N”) adat. A periódusidő paraméterrel az adatsorok ezen jelleg alapján szűrhetők a lekérdezések során. A kódok tetszőleges kombinációban és sorrendben megadhatók (például a “P” csak pillanatérték adatsorokra szűr, az “ON” megadásával pedig órás és napi adatsorok adják az eredmény halmazt). Ha a paraméter nincs kitöltve, akkor nem történik szűrés periódusidőre. Megegyező eredményt hoz, ha a paraméterben mindhárom karakter megadásra kerül tetszőleges sorrendben (például “NOP”). Nem szabályosan megadott periódusidő esetén a periódusidőre nem történik szűrés. A keresési intervallummal a találati halmaz időben szűkíthető. Az időmaszkok formátuma “2012-11-30 00:00:00”, de megadása esetén nem kötelező a teljes maszkot használni, így például a “2012-11-30 00” is elegendő. Az időbeli szűrésre önmagában illetve az időmaszkokkal kombináltan használható a relatív keresési intervallum. A paraméter értelmezése függ a periódusidő paraméter tartalmától, mindig a legnagyobb periódushoz igazodik. Pillanatérték (“P”) esetén a relatív keresési intervallum értéke percként értelmezendő, órás (“O”) szűrés esetén óraként, napi (“N”) szűrés esetén pedig napként. A periódusidők együttes alkalmazhatósága miatt a keresési intervallumra vonatkozó korlátozás, hogy amennyiben a pillanatérték periódus bármilyen kombinációban szerepel a periódusidő paraméterben, akkor a keresési intervallum nem lehet több 1 napnál. Az időbeli szűrésről összefoglaló táblázat a GetMinta metódus és kapcsolódó struktúrák alfejezetben található. Sikeres végrehajtás esetén a függvény visszatérési értéke nagyobb-egyenlő mint 0, ami a szerver által kigyűjtött adatok számát jelenti. Negatív értéktartományba eső visszatérési érték minden esetben az jelenti, hogy a kérés elküldése vagy kiszolgálása közben hiba lépett fel. A függvény kimenő paraméterei és azok tartalmának értelmezése: OTR_GW_SOAP_szolgaltatas_SSL_v4.1.0.0_kivonat.doc 22/24

v4.1.0.0

FGSZ - X_PROMPT



















XP_SOAP_GETELSZPONT FÜGGVÉNY

Leírás: A függvény az OTR GW SOAP szolgáltatás elszámolási ponthoz kötött adatsor lekérdező metódusa meghívásával a partner számára hozzáférésre engedélyezett elszámolási pont adatsorok paramétereknek megfelelő elemeit szolgáltatja. A kigyűjtött adatok dinamikus stuktúra tömbben érkeznek, melyek a függvény hatodik paraméteréből olvashatók ki. A függvény bemenő paraméterei, melyekkel a lekérdezés specifikálható: 

elszámolási pont azonosító maszk,



periódus (’O’ – órás, ’N’ – napi),






keresési időszak kezdetéhez vagy végéhez igazított relatív keresési intervallum.

Az elszámolási pont azonosító maszk lehet egy teljes azonosító, ORACLE szintaktikának megfelelő azonosító maszk vagy akár egy üres sztring. Teljes azonosító megadása esetén a megadott elszámolási pont, üres sztring esetén a hozzáférésre engedélyezett valamennyi elszámolási pont, maszk esetén a maszkra illeszkedő elszámolási pontokhoz kötött adatsorok adják az eredmény halmazt. Az elszámolási ponthoz kötött adatok periódusidő alapján két csoportba sorolhatók: órás (’O’) illetve napi (’N’) adat. A periódusidő paraméterrel az adatsorok ezen jelleg alapján szűrhetők a lekérdezések során. Ha a paraméter nincs kitöltve, akkor nem történik szűrés periódusidőre. A keresési intervallummal a találati halmaz időben szűkíthető. Az időmaszkok formátuma “2012-11-30 00:00:00”, de megadása esetén nem kötelező a teljes maszkot használni, így például a “2012-11-30 00” is elegendő. Az időbeli szűrésre önmagában illetve az időmaszkokkal kombináltan használható a relatív keresési intervallum. A paraméter értelmezése függ a periódusidő paraméter tartalmától, mindig a legnagyobb periódushoz igazodik. Órás (’O’) szűrés esetén óraként, napi (’N’) szűrés esetén pedig napként értelmezendő a relatív keresési intervallum. Ha nem történik szűrés a periódus időre, akkor a napi jelleg a legnagyobb periódus, így a relatív keresési intervallum is napként értelmezendő. Az időbeli szűrésről összefoglaló táblázat a GetElszpont metódus és kapcsolódó struktúrák alfejezetben található.


v4.1.0.0

FGSZ - X_PROMPT

Sikeres végrehajtás esetén a függvény visszatérési értéke nagyobb-egyenlő mint 0, ami a szerver által kigyűjtött adatok számát jelenti. Negatív értéktartományba eső visszatérési érték minden esetben az jelenti, hogy a kérés elküldése vagy kiszolgálása közben hiba lépett fel. A függvény kimenő paraméterei és azok tartalmának értelmezése: 


















v4.1.0.0

OTR GW SOAP szolgáltatás GWSOAPSRV

Recommend Documents