msql, MQL betiklerini ve tek tek deyimleri çalışan bir ajana veren komut satırı istemcisidir. İçinde motor yoktur: ajanın /ivedi oturum protokolüne (bkz. 5.4) WebSocket ile bağlanır, betiğin metnini gönderir; sonuçları, motorun konsol yazılarını ve hataları aynı bağlantıdan geri alır. Veritabanı kaydı, login ve rol tanımı, başlangıç betiği, IoT cihaz satırları, yükseltme betikleri — bu kılavuzda MQL ile yapılan her iş msql ile ve hizmet ayaktayken yapılır.

msql.exe (Linux'ta msql) ajanın yanında, aynı dizinde durur ve o dizindeki kitaplıkları (ICU) paylaşır; ajan dağıtımıyla birlikte kopyalanır. İki ön koşul vardır:

• Ajanın yapılandırmasında IVEDI işlemcisi (/ivedi yolu) etkin olmalıdır — dağıtım conf'unda vardır.
• Bağlanılan login MASTER'da SYSADMIN rolünde ya da SYSDBA olmalıdır (/ivedi kapısı). Bir veritabanı seçmek için login'in o veritabanında kullanıcı eşlemesi (CREATE USER … FOR LOGIN) bulunmalıdır.

msql [seçenekler] [veritabanı]

3.6.1 PSQL hata ayıklayıcısı (msql)

Ajanın debugMode anahtarı açık ve login DEBUGGER rolünde (ya da SYSDBA) ise msql oturumu kendi deyimlerinin PSQL kodunu ayıklar (sözleşme: protokol belgesi §7.10). İstemci komutları etkileşimde ve -c ile toplu kipte işlenir:

Deyim bir durağa gelince msql konumu yazar (-- debugger stopped: breakpoint at procedure APP.P line 4, istisnada -- exception ... satırı) ve (dbg) istemine geçer; komutlar standart girdiden okunur, boş satır sonuncuyu yineler: n üstünden adım, s içine, o dışına, c devam, q deyimi sonlandır (DEBUG_TERMINATED), bt çağrı yığını, v [params|locals|returns|new|old|exception] değişkenler, p ifade değer (v, new.x, v * 10 + a), b ŞEMA.AD:SATIR [if koşul] yeni durma noktası, h yardım. Toplu kipte girdi biterse deyim kendiliğinden sürer. Hata ayıklama açıkken Ctrl+C deyimi iptal etmez, bir sonraki PSQL deyiminde durdurur. Durak boyunca işlem ve kilitler açık kalır, deyim süre sınırı askıdadır.

3.6.2 Sonuçlar, konsol yazıları ve biçimler

Sonuç kümeleri deyim deyim, hazır oldukça gelir. Motorun konsol yazıları (Console.PrintF, #OUTPUT) komut koşarken ajanın standart çıktısına değil istemciye gelir ve sonuçlarla birlikte ekrana ya da -o dosyasına yazılır. Biçimler (--format, etkileşimde \f):

Hatalar ve uyarılar standart hataya şu biçimde yazılır (renk yalnız standart hata bir uçbirimken; Windows konsolunda ANSI yorumlaması msql tarafından açılır, NO_COLOR ortam değişkeni rengi her yerde kapatır). Bütün metin UTF-8'dir: Windows konsolunda msql kod sayfasını her iki yönde UTF-8'e alır, yönlendirilmiş çıktı UTF-8 baytlarıdır (BOM yok):

ERROR: <ileti>
  file: client:C:\kurulum\kayit.sql(12,5)
  sqlState: 42601
WARNING: <ileti>
  lineNum: 3, charPos: 1

file: satırı betik dosyasından gelen bir deyimde yol, satır ve sütunu verir; -c ile verilen metinde onun yerine lineNum / charPos yazılır.

3.6.3 Etkileşimli kip

-c, -f ve borulanmış stdin yoksa msql etkileşimli bir oturum açar: geçmişi, tamamlaması ve çok satırlı düzenlemesi olan bir satır düzenleyici. Deyimler ; ile gönderilir; PSQL gövdeleri (execute block, create procedure / function / trigger / package / type / metacommand / sqlmacro / operator, declare) kapanan END'e kadar bekletilir. SET TERM x; yalnız istemcinin gönderme kuralını değiştirir, motora gitmez. Ctrl+C koşan deyimi iptal eder (POST /ivedi/cancel); oturum açık kalır.

Satır başındaki \ad arg … satırları motorun meta-komutlarıdır ve sunucuda koşar: \help listeler; \d [nesne], \dt, \dv, \df, \dp, \dn, \l yerleşiktir, CREATE METACOMMAND ile yenileri tanımlanır (SQL kılavuzu). İstemcinin kendisinde işlenenler:

3.6.4 Dosyalar: istemcinin mi, sunucunun mu

msql betiğin metnini gönderir ve kaynak adı olarak client:<mutlak yol> verir. Betikteki #include (ve ALTER DATABASE … SET STARTUP SCRIPT FROM FILE) bu ada göre, yani istemcinin dosya sisteminde çözülür: ajan dosyayı aynı bağlantı üzerinden msql'den ister. Kaynak açıkça da seçilebilir: #include 'client:<yol>' istemcinin, #include 'server:<yol>' sunucunun dosya sistemidir; öneksiz bir yol, içinde bulunduğu dosyanın kaynağını miras alır (istemciden gelen betiğin göreli include'ları istemciden, sunucudaki bir betiğinkiler sunucudan). Çalışma zamanında açılan dosyalar bu kuralın dışındadır: öneksiz yolları her zaman sunucunun yollarıdır (UPGRADE LEVEL … FROM '<paket>', EXPORT LEVEL … TO, BACKUP TO, CREATE EXTERNAL TABLE). Seviye paketleri açık 'client:<yol>' önekiyle istemci makinesinde kalabilir: UPGRADE LEVEL … FROM 'client:…' paketi msql'den okur, EXPORT LEVEL … TO 'client:…' ona yazar.

İstemciden #include edilen dosya 4 MB'lık parçalarla okunur; dosya boyu sınırı yoktur, ajanın belleğinde aynı anda bir parça durur. msql 16 MB'ı aşan bir -f betiğini de bu yoldan gönderir; hata satırlarındaki dosya adı ve satır numarası değişmez.

3.6.5 Örnekler

-- Kurulum betigini calisan hizmete ver; sonuclar dosyaya, hatalar stderr'e
msql -U SYSDBA -W masterkey -f kurulum.sql -o kurulum.out.sql 2> kurulum.err
echo %ERRORLEVEL%

-- Parolayi ortam degiskeninden al, tek deyim kostur
set IVD_PASSWORD=masterkey
msql -U SYSDBA -c "select ivd$object_name from master.sys.ivd$objects where ivd$type = 'DATABASE' and ivd$object_id > 0"

-- Etkilesimli oturum, NETSIM veritabani secili
msql -U SYSDBA NETSIM
SYSDBA parolasi:
NETSIM=> \dt
NETSIM=> select count(*) from ns_firma;
NETSIM=> \help
NETSIM=> \q