ETTerms/docs/ttl-script-reference.md

TTL Script Reference — ETTerms

ETTerms 的 TTL（Tera Term Language）腳本引擎移植自 MyTeraTerm，改為驅動原生 ISessionChannel（SSH / Serial 皆可）。在 Scripts 檢視載入 .ttl 腳本，對 目前 active session 執行（先在 Terminal 檢視開好連線）。

執行於背景執行緒，可隨時按 Stop 中止；wait / pause 期間皆可取消。

---

語法規則

• 一行一個指令；前後空白會被去除。
• 註解：; 之後到行尾視為註解。
• 字串引號 '...' 或 "..." 皆可，送出時引號會被去除。
• 變數以 名稱 = 值 指派；名稱須符合 ^[a-zA-Z_][a-zA-Z0-9_]*$。
• 內建變數 result：wait 命中為 1、逾時為 0。
• 換行：sendln 自動附加 \r\n。

---

指令對照表

指令	語法	說明
send	send '文字'	送出文字（不加換行）到 active session。
sendln	sendln '文字'	送出文字並附加 \r\n。
wait	wait '字串'	一直等到接收緩衝出現指定字串才往下；預設無限等待（可按 Stop 取消）。命中後會再確認裝置「安靜」約 300ms（無新資料）才接受，以排除夾在輸出中途的回顯（如 SVOS> help），並消費到該字串最後一次出現（含）之前的內容，result=1。
pause	pause 秒數	暫停指定秒數（可被 Stop 中止）。
timeout	timeout = 秒數	設定 wait 的逾時秒數。預設 0＝無限等待；若設為 N>0，wait 超過 N 秒仍未命中會中止整個腳本並報錯（不會略過 wait 往下做）。
flushrecv	flushrecv	清空接收緩衝區。
logopen	logopen '檔名'	開啟 log 檔（覆寫）；send 與 logwrite 會寫入。
logwrite	logwrite '文字'	寫一行到 log 檔。
logclose	logclose	關閉 log 檔（腳本結束時自動關閉）。
messagebox	messagebox '訊息'	跳出訊息對話框。
sprintf2	sprintf2 變數 格式 [引數 ...]	C printf 風格格式化，結果存入字串變數。詳見下方說明。
if / elseif / else / endif	見下	條件分支（可巢狀）。
while / endwhile	見下	迴圈（可巢狀，可被 Stop 中止）。
名稱 = 值	idx = 0	變數指派，支援 + - * / 整數運算與字串。

注意： PDU 控制指令（pductrl / pduconnect）屬 Phase 7，本階段尚未提供。

---

Group 同步指令

以下指令只能在 Run Group 模式下使用（toolbar 的 ▶ Group1 / ▶ Group2 / ▶ Group3）。 若在 ▶ Script（分頁個別執行）或 ▶ Run All 使用，會跳 Warning 並拒絕執行。

Group 內的成員依加入順序編為 A, B, C, D...，顯示在 cell footer（如 [Group1-A]）。

指令	語法	說明
waitall	waitall '字串'	各成員各自 wait 到指定字串出現後，再等其他成員也完成，全員到齊才繼續下一步。
sendlnall	sendlnall '文字'	等所有成員到達此行後，每人各自對自己的 channel sendln 同一段文字。
sendlngroup	sendlngroup A '文字'	只有指定 member（A/B/C...）會 sendln，其他成員跳過。用於 Group 內各設備需送不同指令的情境。

Group 範例：同步升級多台交換機

; Group1 有 A=SW1, B=SW2, C=SW3
; 每台各自等到 prompt 再同步
waitall '#'

; 各送不同指令
sendlngroup A 'copy tftp://10.0.0.1/sw1.bin flash:'
sendlngroup B 'copy tftp://10.0.0.1/sw2.bin flash:'
sendlngroup C 'copy tftp://10.0.0.1/sw3.bin flash:'

; 等所有人下載完畢
waitall '#'

; 全員一起 reload
sendlnall 'reload'
waitall 'confirm'
sendlnall 'y'

Group 設定方式

1. 在分頁 Tab 上右鍵 → 選擇 Group 1 / Group 2 / Group 3（或 No Group 取消）
2. 設定後 cell footer 會顯示 [Group1-A]、[Group1-B] 等標籤
3. 點 toolbar 的 ▶ Group1 載入 .ttl 檔，Group 內所有成員平行執行同一份腳本

---

條件運算子

if / elseif / while 條件支援：

運算子	類型	範例
>= <= > <	數值	if idx >= 3 then
== !=	字串 / 數值	if result == 1 then
=	數值或字串相等	if result = 0 then
（無運算子）	非零為真	if result then

then 關鍵字可省略。

---

sprintf2 格式化

sprintf2 變數 格式字串 [引數 ...] 以 C 語言 printf 規則格式化，結果存入指定字串變數，與 Tera Term 的 sprintf2 行為一致。

sprintf2 ver 'Tera Term 4.%d' 51            ; ver = "Tera Term 4.51"
sprintf2 win 'Windows %d (+%s)' 2000 'SP4'   ; win = "Windows 2000 (+SP4)"
sprintf2 test '%s=%d %s=0x%x' 'dec' 10 'hex' 33   ; test = "dec=10 hex=0x21"
messagebox test

• 轉換型別：c d i o u x X e E f g G a A s
• 旗標：-（靠左）、+（顯示正負號）、0（補零）、#（替代格式，如 0x）、空白（正數前空格）
• 寬度／精度：十進位整數，或用 * 從引數動態取得（如 %*d、%.*f）
• 浮點數須以字串傳入（TTL 無浮點型別），例 sprintf2 s '%.2f' '3.14159'
• 格式字串不展開變數（保持字面值），僅各引數會展開變數，故可累加自身： sprintf2 s '%s,' s 會把 s 接上 ,

執行後設定系統變數 result：

值	狀態
0	格式化成功
1	缺少格式字串
2	格式無效
3	引數無效（缺少或無法解析）
4	目的變數名稱無效

---

範例：SSH 自動登入 + 收 log

; 等提示字元，逐步登入並收集輸出
timeout = 15

wait 'login:'
sendln 'admin'
wait 'Password:'
sendln 'secret'
wait '$'

logopen 'session.log'
sendln 'uname -a'
wait '$'
sendln 'uptime'
wait '$'
logclose

messagebox 'Done'

範例：while 迴圈下命令

idx = 0
while idx < 5
    sendln 'echo loop'
    wait '$'
    idx = idx + 1
endwhile

範例：if / elseif / else

sendln 'whoami'
wait '$'
if result == 1 then
    logwrite 'prompt matched'
elseif result == 0 then
    logwrite 'timed out'
else
    logwrite 'unknown'
endif