C# - MS SQL tárolt eljárások

MS SQL tárolt eljárások 15. rész

forráskód letöltése
Ebben a részben az MS SQL hibaüzeneteivel, pontosabban a saját hibaüzenetek megjelenítésével, létrehozásával foglalkozunk. A saját hibaüzeneteinket akár több nyelven is tárolhatjuk az adatbázisban, és szükség szerint rendelkezhetünk arról is, hogy megjelenjen az Alkalmazásnaplóban is. Továbbá részletesen megvizsgáljuk azt az SQL utasítást, amivel az üzeneteket megjeleníthetjük.
Mielőtt saját üzeneteket hoznánk létre, nézzük meg, hogy melyik az az SQL utasítás, amivel az üzeneteket megjeleníthetjük, illetve amelynek hatására az üzenet bekerül az Alkalmazásnaplóba. Az üzeneteket megjelenítő SQL utasítás a RAISERROR. Ennek szintaktikája a következő:
RAISERROR ( { msg_id | msg_str } { , severity , state }     [ , argument [ ,...n ] ] )     [ WITH option [ ,...n ] ]
Az eljárás paraméterei a következők:
msg_id
A megjelenítendő üzenet egyedi azonosító kódja. A felhasználó által létrehozott üzenetek kódjának 50000-nél nagyobbnak kell lennie.
msg_str
Az üzenet szövege, amely speciális karaktereket is tartalmazhat. A sztring formátuma a PRINTF utasításban használható formátummal megegyezik. Az üzenet akár 400 karakternél is hosszabb lehet, de ekkor csak az első 397 karakter jelenik meg, valamint három pont karakter, ami azt jelzi, hogy az üzenet vége hiányzik.
severity
Minden üzenetnek lehet egy „súlyossági” szintje, amit ebben a paraméterben adhatunk meg. Értéke egy 1-25 közötti szám lehet, de általában a 11-16 értékek használatosak, ezeket kifejezetten az sp_addmessage eljáráshoz tervezték (lásd lejjebb). A 19-nél magasabb súlyossági szintet csak akkor használhatjuk, ha rendszergazdaként vagyunk bejelentkezve. A 17-19 szintek súlyos szoftver, vagy hardver hibát jelölnek, lehetséges, hogy ezután nem lehet folytatni a munkát. A 19-nél magasabb súlyossági szint már kizárja a további SQL utasítások végrehajtását. Az alapértelmezett érték 16.
state
Ez a paraméter egy 1-127 közötti tetszőleges szám lehet, ami a hiba jelenlegi állapotát hivatott jelezni.
argument
Ez tulajdonképpen nem egy, hanem tetszőleges számú paraméter lehet. Ez itt felsorolt értékeket fogja beilleszteni az üzenet szövegébe a szövegben elhelyezett kódok helyére.
01_sp_addmessage.sql: Új felhasználói hibaüzenet létrehozása
A hibaüzenetek a sysmessages rendszertáblában vannak tárolva. Új üzenetet az sp_addmessage eljárással tudunk felvenni, aminek szintaxisa a következő:
sp_addmessage [ @msgnum = ] msg_id ,     [ @severity = ] severity ,     [ @msgtext = ] 'msg'     [ , [ @lang = ] 'language' ]     [ , [ @with_log = ] 'with_log' ]     [ , [ @replace = ] 'replace' ]
Fontos, hogy ha több nyelven is létre akarjuk hozni az üzenetet, akkor először mindig az angol (U.S.English) verziót kell létrehozni. Ha az üzenetben kódokat is alkalmazunk (pl. %s), akkor ezt a más nyelvű üzeneteknél sorszámmal kell megadni. A sorszám mondja meg, hogy az adott paraméter az eredeti angol nyelvű üzenetben hányadik helyen áll (pl. %2).
Példa:
Angol változat Magyar változat
„Day %d. month: %s” „Hónap: %2, nap: %1”
Az eljárás paraméterei:
msgnum
Az üzenet egyedi azonosító kódja. A kódnak 50001 és 2147486647 közé kell esnie. Az 50000 alatti kódok a rendszerüzeneteknek vannak fenntartva. Igazából a kód a language paraméterrel együtt alkot egy egyedi kulcsot, tehát lehet több azonos kóddal rendelkező üzenet, de akkor mindegyik más nyelven van megadva (lásd language paraméter).
severity
Az üzenet súlyossági szintje (lásd fent a RAISERROR utasításnál).
msg
Az üzenet szövege. A szöveg hossza maximum 256 karakter lehet.
lang
Ebben a paraméterben adhatjuk meg az üzenet nyelvét. Mivel a szerver alapvetően többnyelvű, így az üzeneteket is megadhatjuk több nyelven. Ha nem adjuk meg, akkor az alapértelmezett nyelvet fogja használni.
with_log
Ebben a paraméterben adhatjuk meg, hogy az üzenet megjelenjen-e a Windows NT Alkalmazásnaplójában, valamint az MS SQL Server hibanaplójában. Ha a paraméter érték e „true”, akkor megjelenik, ha „false”, akkor nem. Csak a sysadmin csoportban szereplő felhasználóknak van joga ezt a tulajdonságot beállítani.
replace
Ha az üzenet már létezik, de módosítani szeretnénk, akkor meg kell adnunk ezt a paramétert. Értéke csak a „REPLACE” sztring lehet. Ha ezt nem adjuk meg, és az üzenet már létezik, akkor hibaüzenetet kapunk. Ellenkező esetben módosíthatjuk az üzenet paramétereit. Ha a severity tulajdonság értékét változtatjuk meg, akkor az az összes olyan üzenetnél megváltozik, amelyeknek az msg_id kódja megegyezik az adott üzenet kódjával.
03_sp_dropmessage.sql: Üzenet törlése
Ha már nincs szükségünk tovább az általunk létrehozott üzenetre, akkor az sp_dropmessage eljárással törölhetjük azt. Az eljárás szintaxisa a következő:
sp_dropmessage [ @msgnum = ] message_number     [ , [ @lang = ] 'language' ]
Paraméterek:
msgnum
Az üzenet azonosító kódja. Mivel csak felhasználó által létrehozott üzeneteket törölhetünk, ezért ennek értéke nagyobb lesz 50000-nél.
lang
Ebben a paraméterben adhatjuk meg a törlendő üzenet nyelvének nevét. Az angol változat törlése előtt a más nyelven tárolt üzeneteket törölni kell, vagy ha az adott kóddal rendelkező összes üzenetet törölni szeretnénk, akkor ebben a paraméterben megadhatjuk az „all” értéket.

MS SQL tárolt eljárások cikksorozat