Externale w SowaSQL

Externale używane w języku skryptowym, specyficzne dla SowaSQL.

Jeśli chcesz wykonać program administratora na DUŻEJ ilości rekordów i masz pewność, że nikt nie będzie wówczas pracował na bazie sugeruję poniższe rozwiązanie.

Logujemy się przy pomocy konsolowego klienta administracyjnego. Uniemożliwiamy logowanie do serwera:

unset CAN_LOGIN

Wyłączamy blokowanie rekordów (rekordy są blokowane, w celu zablokowania możliwości ich edycji przez innego użytkownika), jest to procedura bardzo długotrwała przy dużej ilości rekordów może zająć nawet kilkanaście minut.

set DONT_LOCK

Wykonujemy nasz program administracyjny, po jego zakończeniu, kasujemy zbędne już ustawienia:

set CAN_LOGIN
unset DONT_LOCK

Na tej stronie:

EGZ

Składnia

EGZ<sn_start>|<sn_end>

Kasuje wszystkie egzemplarze z przesłanego zakresu (od sn_start, do sn_end). Operacja kasowania wykonywana jest wyłącznie na tabelach wypożyczalni (obroty, egzemplarze, ubytki, itd). External nie ma wpływu na tabelę z opisem rekordów (tbl_items_idx i tbl_items_full). Format przesłanych sn jest bez znaczenia (mogą być z kreskami, lub bez). Jeśli chcemy wykasować tylko jeden sn, wówczas podajemy go w obu parametrach, aczkolwiek, z punktu widzenia wydajności kasowanie zakresu jest dużo lepszym rozwiązaniem.

WYP

WYP:

WYP:<nowa_agenda_główna>

Zamienia ustawienia prawa wypożyczanie (&W) oraz inne (&I) dla aktualnie zalogowanego użytkownika.

Ustawia przesłaną agendę jako nową agendę główną dla prawa wypożyczanie, jednocześnie przenosząc agendę z tego prawa, do prawa inne.

Przykład

przed: &W=01;&I=00,03,04,05,06
operacja: WYP:03
po: &W=03;&I=00,04,05,06,01

Parametrem externala może być wyłącznie agenda do której aktualnie zalogowany użytkownik ma już prawa (czyli znajduje się w prawie inne).

WYPW

WYPW<identyfikator egzemplarza>

Zwraca informacje na temat egzemplarza o przesłanym identyfikatorze:

<typ rekordu czytelnika>|<id rekordu czytelnika>|<status egzemplarza>|<data wypożyczenia>|<data zwrotu (prawdziwa, bądź planowana)>

WYPX

dostępny od wersji 1.65.19

WYPX<identyfikator egzemplarza>

Zwraca informacje na temat egzemplarza o przesłanym identyfikatorze (identycznie jak WYPW) oraz dodatkowo na końcu pojawia się informacja o ilości automatycznych prolongat

<typ rekordu czytelnika>|<id rekordu czytelnika>|<status egzemplarza>|<data wypożyczenia>|<data zwrotu (prawdziwa, bądź planowana)>|<ilość prolongat automatycznych>

SQL

Wersja aktualna (od SowaSQL 1.74.06)

Nowy model externali SQL znacznie różni się od poprzedniego. Tworzenie zapytań jest o wiele prostsze, a same zapytania, zapisane w czytelniej, sparametryzowanej formie. Operacje są wykonywane w ramach zagnieżdżonej transakcji, a po ich zakonczeniu w SQLUNPREPARE, jest wykonywany rollback, dzięki czemu w ramach jednej pary SQLPREPARE - SQLUNPREPARE, można wykonywać dowolne zapytania, tworzyć tabele tymczasowe, niszczyć je, wszystko na co tylko mamy ochotę, zmiany te i tak nie zostaną ostatecznie zapisane do bazy.

SQLPREPARE - przygotowanie zapytania

 SQLPREPARE

Przygotowanie obiektu do wykonania zapytania SQL

parametry: brak
rezultat: QUERY_ID, lub pusta wartość jeśli operacja się nie udała.

Tego externala NIE WOLNO zagnieżdżać.

Nawet jeśli jako rezultat zostanie zwrócona pusta wartość (operacja nieudana), konieczne jest wywołanie SQLUNPREPARE, inaczej licznik operacji PREPARE i UNPREEPARE nie będzie się zgadzał i cały skrypt zostanie zakończony błędem, a zmiany nie ostaną zapisane do bazy.

SQLUNPREPARE - konieczne do wykonania po zakończeniu operacji

SQLUNPREPARE|<query_id>

Zakończenie operacji SQL i zniszczenie obiektów po stronie serwera.

parametry: query_id
rezultat: komunikat błędu, lub pusty string jeśli OK

Jeśli nie będzie się zgadzała w skrypcie ilość wykonanych SQLPREPARE i SQLUNPREPARE, cały skrypt zostanie zakończony błędem i jego wynik zostanie anulowany przez rollback.

Nawet jeśli jako rezultat zostanie zwrócona pusta wartość (operacja nieudana), konieczne jest wywołanie SQLUNPREPARE, inaczej licznik operacji PREPARE i UNPREEPARE nie będzie się zgadzał i cały skrypt zostanie zakończony błędem, a zmiany nie ostaną zapisane do bazy.

SQLPLAIN - szablon generowanego pytania

SQLPLAIN|<query_id>|<szablon zapytania>

Pozwala sformułować zapytanie SQL otwartym tekstem.

W treści nie należy podawać wartości zmiennych, w ich miejscu powinno się podawać :NAZWA - za który zostanie w momencie wykonania zapytania podstawiona wartość parametru przekazanego dalszym wywołaniem externala SQLPARAM.

UWAGA: w treści zapytania nie wolno używać znaku apostrofu (to zabezpieczenie przed atakiem sql-injection). Natomiast w <zapytanie> mogą się znajdować np. znaki "||" używane np. do konkatenacji łańcuchów.

parametry: query_id, zapytanie
rezultat: komunikat błędu, lub pusty string jeśli OK

Przykład sformatowanego szablonu zapytania SQL

select fld_name from tbl_params where fld_name ilike :name

SQLPARAM - definiujemy parametry użyte w szablonie zapytania

SQLPARAM|<query_id>|<nazwa>|<typ>|<wartość>

Dokonuje podstawienia wartości dla :NAZWA z zapytania w SQLPLAIN.

<nazwa> to nazwa parametru (można używać wielokrotnie)

<typ> to:

i - liczba (podana wartość powinna być numeryczna)
s - łańcuch (podana wartość może być dowolnym napisem)

<wartość> musi być zgodna z typem. W przypadku łańcuchów nie musimy escape'ować żadnych znaków.

rezultat: komunikat błędu (w szczególności gdy podani typ "i" a wartość nie jest liczbowa), lub pusty string jeśli OK

SQLEXECUTE - wykonanie zapytania, które NIE zwraca żadnych danych

SQLEXECUTE|<query_id>

Wykonanie zapytania SQL

parametry: query_id
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLOPEN - wykonanie zapytania, które zwraca dane

SQLOPEN|<query_id>

Wywołanie zapytania, które zwraca dane, po których chcemy się poruszać przy pomocy SQLGET

parametry: query_id
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLGET - pobranie danych uzyskanych przez SQLOPEN

SQLGET|<query_id>

Pobranie pojedynczego rekordu z wyniku

parametry: query_id

rezultat:

0|komunikat błędu
1|lista pól z wynikami (wartości poszczególnych pól są oddzielone pionową kreską)
2|EOF

Przykład

qid = external('SQLPREPARE')
aux = external('SQLPLAIN|'+qid+'|select fld_name, fld_value from tbl_params where fld_name like :name and fld_value is not null')
aux = external('SQLPARAM|'+qid+'|name|s|CFG_ZAM_%')
aux = external('SQLOPEN|'+qid)
(...)
aux = external('SQLUNPREPARE|'+qid)

Wersja przestarzała (wciąż działająca dla celów kompatybilności)

SQLPREPARE

 SQLPREPARE

Przygotowanie obiektu do wykonania zapytania SQL

parametry: brak
rezultat: QUERY_ID

Tego externala NIE WOLNO zagnieżdżać.

SQLSELECT

 SQLSELECT|<query_id>|<lista_pól>

Lista pól jakie mają być zwrócone w ramach zapytania

parametry: query_id, lista pól (nazwy pól oddzielone pionowymi kreskami)
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLFROM

SQLFROM|<query_id>|<nazwa_tabeli>

Nazwa tabeli na której ma być wykonywane zapytanie

parametry: query_id, nazwa tabeli
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLWHERE

SQLWHERE|<query_id>|<warunek_zapytania>

Warunek zapytania SQL

parametry: query_id, warunek
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLORDERBY

SQLORDERBY|<query_id>|<kolejność_sortowania>

Kolejność sortowania

parametry: query_id, kolejność sortowania (nazwy pól oddzielone przecinkami)
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLLIMIT

SQLLIMIT|<query_id>|<oczekiwana_ilość_rekordów>

Ustawienie ilości rekordów które mają być zwrócone w ramach zapytania

parametry: query_id, ilość rekordów
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLEXECUTE

 SQLEXECUTE|<query_id>

Wykonanie zapytania SQL

parametry: query_id
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLGET

SQLGET|<query_id>

Pobranie pojedynczego rekordu z wyniku

parametry: query_id

rezultat:

0|komunikat błędu
1|lista pól z wynikami (wartości poszczególnych pól są oddzielone pionową kreską)
2|EOF

SQLUNPREPARE

SQLUNPREPARE|<query_id>

Zniszczenie obiektu po stronie serwera

parametry: query_id
rezultat: komunikat błędu, lub pusty string jeśli OK

SQLFULL

SQLFULL|<query_id>|<lista_pól>|<nazwa_tabeli>|<warunek_zapytania>|<kolejność_sortowania>|<oczekiwana_ilość_rekordów>

Przygotowanie zapytania

parametry: query_id, lista pól (oddzielona przecinkami), nazwa tabeli, warunek zapytania, kolejność sortowania, ilość rekordów.
rezultat: komunikat błędu, lub pusty string jeśli OK

W celu użycia w SQLFULL ciągu znaków || koniecznych podczas sumowania stringów w PostgreSQL, należy użyć:

+STRING+

Aby użyć pojedynczego znaku | należy użyć (od /wiki/spaces/sqldoc/pages/458807):

+STRING

SKR_SETDONT_CHECK

SKR_SETDONT_CHECK

Wywołanie tego externala, spowoduje, że program wykonywaney na kolekcji NIE zostanie przerwany, jeśli podczas obróbki któregoś z rekordów wystąpi błąd.

Lista wszystkich externali obsługiwanych przez SowaSQL

1. user
2. right
3. statistics
4. users?
5. users#
6. profile
7. hello
8. licence
9. range
10. def
11. replace
12. delete
13. new
14. skr_set
15. wypa
16. wypS
17. wypW
18. wypX
19. wypR
20. wypA
21. wyp#
22. wypB
23. wypC_K
24. wypC_L
25. wypC_W
26. wypC_B
27. wypC_Z
28. wypI
29. wypG
30. wypF
31. wypZ
32. wypD
33. wypN
34. wyp>
35. wypK
36. wyp&
37. wypJ
38. wyp-_Z
39. wyp-_R
40. wyp-_A
41. wyp*
42. wyp:
43. wypO_A
44. wypO_W
45. wypO_H
46. wypO_R
47. wypO_Z
48. wypO_K
49. wypO_P
50. wypO_O
51. egz
52. mail
53. skoU
54. skoS
55. skoQ
56. sko-
57. search
59. sql
60. set
61. bloL
62. bloE
63. bloI
64. bloH
65. bloB
66. bloM
67. bloX
68. bloY
69. indexes
70. ipub!
71. ipub:
72. ipubtr
73. ipubnr
74. obrZ
75. stn+
76. stn-
77. - brak - (stn>)
78. stn!
79. stn*
80. czt
81. cleardb
82. bloD
83. bloN
84. wypO_M
85. regz
86. wrap
87. isbn
88. file
89. bloh
90. pwd*
91. pwd?
92. wypw
93. wypz#
94. wypz+
95. wypr+