7.2 Deyimler

<< İçindekileri Görüntülemek İçin Tıklayın >>

Yer:  Teknik Kılavuzlar > Netsim System Agent İstemci Protokolü Referansı > 7. IVEDI oturum protokolü (/ivedi) >

7.2 Deyimler

Komut Alanlar Yanıt
execute sql (tek deyim; PSQL bloğu olabilir), params? (dizi = konumsal ?, nesne = adlı :ad, harf duyarsız; eksik parametre NULL, bilinmeyen ad hata), fetchSize?, metadata? kind (query / command / ddl / transaction / privilege / block / other), affectedRows, results[], closedCursors[]?, autocommitted?, inTransaction, elapsedMs
script sql (çok deyimli betik), maxErrors? (öndeğer 0), fetchSize?, metadata?, stream? (akış kipi, aşağıda), file? (betiğin kaynak adı, client:<mutlak yol> - hata satırları ve göreli #include çözümü bu ada göre), allowEmpty? (deyimsiz gövde - yalnız #define - hata değil), bootstrap? (yalnız LSP geliştirme kipi, §7.9) execute ile aynı + errorCount, warningCount; hatalar results[] içinde error öğesi olarak toplanır, ok = errorCount 0 (parametre yok; msql, yönetim arayüzünün betik kipi ve dil sunucusu)
prepare sql statementId, kind, params[{index, name}], columns[] (DML'de derlemede bilinen dönüş kolonları)
executePrepared statementId, params?, fetchSize?, metadata? execute ile aynı
free statementId freed

İlerleme bildirimi: uzun bir deyim (ALTER DATABASE … UPGRADE LEVEL, UPGRADE, ADOPT LEVEL) koşarken motor her adımda sunucu kaynaklı bir çerçeve gönderir: {"notification": "progress", "phase", "done", "total" (0 = bilinmiyor), "object", "elapsedMs"} (execute / executePrepared / script sırasında, yanıttan önce; kodlama oturumunki). Koşan deyim POST /ivedi/cancel ile iptal edilirse yükseltme durur, raporu CANCELED satırıyla biter ve veritabanı ACTIVE durumuna döner. Yükseltme raporunun beşinci kolonu ELAPSED_MS deyim başına süreyi, özet (APPLY) satırı evre toplamlarını taşır.

Akış kipi (script stream: true, msql'in kullandığı): her deyimin yanıtı hazır olunca hemen {"notification": "results", "results": [...]} çerçevesiyle gider (öğe düzeni yanıttakiyle aynı; sonuç kümeleri bütün satırlarıyla, imleç kurulmaz; kök olmayan alt isteklerden yalnız durum iletileri), betik bitince yanıt sayaçları ve varsa kalan öğeleri taşır.

Konsol yönlendirmesi: bir komut (execute, executePrepared, script) koşarken motorun konsol yazıları (Console.PrintF) sunucunun stdout'una değil istemciye gider: tam satırlar halinde {"notification": "console", "text": "..."} çerçeveleri, deyim sonucundan önce ve komut bitiminde kalan parça.

Çıktı yönlendirmesi (notification: output): betikteki #OUTPUT <dosya> / #OUTPUT_REPLACE <dosya> / #OUTPUT STDOUT sunucuda dosya açmaz; deyim sırasında, o ana kadarki konsol metni gönderildikten sonra {"notification": "output", "name": "&lt;dosya> | STDOUT", "replace": bool} yazılır. İstemci bundan sonraki sonuçları ve konsol metnini o dosyaya yazar (replace false ise sonuna ekler, yeni dosyaya UTF-8 BOM), STDOUT ile kendi varsayılan çıktısına döner. Ad client: önekini taşımaz; göreli ad istemcinin çalışma dizinine göredir. server:<dosya> sunucunun dosya sistemine yazdırır.

Çıktı eşzamanlaması (request: outputSync): istemci script / execute çerçevesinde "outputSync": true bildirirse ve komutta çıktı istemciye yönlendirildiyse, sunucu #SHELL (ve türevleri) koşmadan önce {"request": "outputSync", "id": n} gönderir ve {"reply": n, "ok": true} yanıtını bekler (120 s). İstemci çerçeveleri sırayla işlediği için yanıtı verdiğinde önceki #OUTPUT dosyası yazılmış ve #OUTPUT STDOUT ile kapatılmış olur; açık bir #OUTPUT dosyası varsa yanıttan önce diske boşaltılır. Bildirmeyen istemciye bu istek hiç gönderilmez. Yanıt gelmezse komut koşmaz (hata, ERRORLEVEL 126).

İstemci dosyası (request: file): betikte #include 'client:<yol>' (ya da client: kaynaklı bir gövdenin göreli #include'u, SET STARTUP SCRIPT FROM FILE) geçtiğinde sunucu aynı sokete {"request": "file", "id": n, "name": "client:&lt;mutlak yol>"} yazar ve istemcinin {"reply": n, "ok": true, "content": "&lt;UTF-8 metin>"} ya da {"reply": n, "ok": false, "error": "..."} çerçevesini bekler (120 s); bu arada istemci başka komut göndermez. server:&lt;yol> sunucunun dosya sistemini açıkça seçer; öneksiz yol içinde bulunduğu dosyanın kaynağını miras alır.

Parçalı okuma: #include 'client:<yol>' dosyayı parça parça ister: istekte "offset": <bayt> ve "length": <bayt> (4 MB) vardır. İstemci o aralığı {"reply": n, "ok": true, "offset": <istenen offset>, "size": <dosyanın toplam bayt boyu>, "contentBase64": "..."} olarak döner; parça bayttır (bir UTF-8 karakterinin ortasından bölünebilir), dosyanın sonundan sonrası boş döner. Sunucu offset + parça >= size olunca durur; dosya boyu sınırı yoktur, bellekte bir parça durur. offset'i yankılamayan yanıt (alanları tanımayan istemci) bütün dosya sayılır. SET STARTUP SCRIPT FROM FILE dosyayı parçasız, tek istekle ister. msql 16 MB'ı aşan bir -f betiğini gövdesiyle değil tek satırlık #include 'client:<mutlak yol>' metniyle gönderir; satır numaraları ve dosya adı aynı kalır.

İkili istemci dosyası: ALTER DATABASE … UPGRADE LEVEL n FROM 'client:<yol>' paketi istemciden {"request": "file", "id": n, "name": "client:<yol>", "binary": true} ile ister; istemci içeriği {"reply": n, "ok": true, "contentBase64": "..."} olarak döner. EXPORT LEVEL n TO 'client:<yol>' paketi sunucuda üretip {"request": "writeFile", "id": n, "name": "client:<yol>", "contentBase64": "..."} ile gönderir; istemci dosyayı yazar ve {"reply": n, "ok": true} ya da {"reply": n, "ok": false, "error": "..."} döner (var olan dosyanın üstüne yazılmaz). Base64 JSON ve BSON oturumlarında aynıdır. Göreli yol istemcinin çalışma dizinine göredir.

İleti dili: hata öğelerinin message'ı ile uyarı / bilgi öğelerinin text'i oturumun dilindedir (open.language, yoksa ajanın conf language'i; durumsuz POST /ivedi/execute'ta gövdedeki language, yoksa Accept-Language). Metin, yönetim arayüzünün dil dosyalarındaki (i18n/<dil>.json) messages bölümünden gelir: anahtar, iletinin kaynak koddaki İngilizce şablonudur (template, ör. NOT NULL constraint failed: column {0} of {1}), {n} yer tutucuları params[] ile doldurulur. messageId durum adıdır (ör. NOT_NULL_VIOLATION); bir ailenin genel hatası (SYNTAX_ERROR, INVALID_PARAMETER, APPLICATION_ERROR ...) dış şablonunu (Syntax error '{0}') kendi anahtarıyla çevirir ve içine template + params'tan kurulan iç metni koyar. İstemci template ve params ile metni kendi kataloğundan da üretebilir. Parametreler çevrilmez. Kataloğunda karşılığı olmayan ileti İngilizce kalır; depo kısıt ihlali (UNIQUE_VIOLATION, FOREIGN_KEY_VIOLATION) deponun kendi iletisini taşır, template ve params göndermez. Yükseltme / benimseme raporunun DETAIL kolonu ve notification: progress evre metni de oturumun dilindedir; yükseltme geçmişinin (ivd$upgrade_history) raporu yükseltmeyi çalıştıran oturumun dilinde saklanır. Sunucu günlüğü ve yükseltme günlüğü ajanın conf logLanguage'inin dilindedir (öndeğer tr); PSQL'deki ERROR.MESSAGE her zaman İngilizcedir.

results[] öğeleri (type alanıyla): resultSet (columns[]: name, type - start00types.sql yerleşik adı, charLen, precision, scale, nullable; kolon bir tablo / görünüm kolonuna dayanıyorsa kökeni relation (tablo adı), schema, baseName (temel kolon adı) - ifade kolonlarında yok; rows[][] konumsal, ENUM üye adıyla; rowCount; done; cursorId - kalan satır varsa; truncated - maxRows aşıldıysa), message / warning / info / hint / debug (text, line, column), text / sql / sqlNative / json / xml (text - çevrim kipinin çıktıları), value (value), error (yalnız script; name, code, sqlState, message, messageId?, template?, params?, line, column, file?, statement?, callInfo? - SQL çağrı yığını, her zaman; stackTrace? - sunucunun yerel yığın izi, yalnız open.stackTrace istendiğinde ya da ajanın günlük düzeyi debug / diag iken).