ESQL (Embedded SQL for COBASE) 程式設計完整手冊

什麼是 ESQL？

ESQL（Embedded SQL）是將 SQL 陳述式嵌入 C 程式碼中，經由預編譯器（ETE）轉換為標準 C/C++ 程式碼（呼叫 CCI 函式庫），再由 C 編譯器編譯連結成可執行檔。COBASE RDBMS 提供 ESQL 介面，結合 SQL 的集合操作與 C 的流程控制，開發高效能資料庫應用。

ESQL 程式架構

/* 1. 宣告區：定義主變數 */
EXEC SQL BEGIN DECLARE SECTION;
  int    sno;
  char   sname[20];
  short  status;
EXEC SQL END DECLARE SECTION;

/* 2. 通訊區：錯誤處理必備 */
EXEC SQL INCLUDE USERCA;

/* 3. 主程式 */
int main() {
  /* 3.1 連線 */
  EXEC SQL CONNECT "cobase:cobase";

  /* 3.2 執行 SQL：DML、DDL、游標操作 */
  EXEC SQL CREATE TABLE S_TEST (SNO CHAR(9), SNAME CHAR(20), STATUS INT, CITY CHAR(10));
  EXEC SQL INSERT INTO S_TEST VALUES (:sno, :sname, :status, :city);

  /* 3.3 提交/斷線 */
  EXEC SQL COMMIT;
  EXEC SQL DISCONNECT;
  return 0;
}

關鍵語法規則

• 所有嵌入 SQL 以 EXEC SQL 開頭，以分號 ; 結束。
• 主變數在 SQL 中使用時前綴冒號 :（如 :sno），純 C 程式碼中不加。
• 主變數必須在 DECLARE SECTION 定義，型態需與資料庫欄位相容。
• 每個預編譯單元僅允許一組 BEGIN/END DECLARE SECTION。

查詢與游標操作

單列查詢（INTO 子句）

EXEC SQL SELECT sname, status INTO :sname, :status
  FROM supplier WHERE sno = :sno;

多列查詢：游標四步驟

1. DECLARE CURSOR：EXEC SQL DECLARE c1 CURSOR FOR SELECT * FROM S_TEST FOR UPDATE;
2. OPEN CURSOR：EXEC SQL OPEN c1; 建立作用集合
3. FETCH：EXEC SQL FETCH c1 INTO :sno, :sname, :status, :city; 逐列取出
4. CLOSE CURSOR：EXEC SQL CLOSE c1; 釋放資源

FETCH 迴圈判斷 USERCA.sqlcode == 2000 表示無更多資料。

定位更新/刪除（WHERE CURRENT OF）

EXEC SQL DELETE FROM S_TEST WHERE CURRENT OF c1;
EXEC SQL UPDATE S_TEST SET status = :new_status WHERE CURRENT OF c1;

需在 DECLARE CURSOR 時加 FOR UPDATE。

交易控制

• EXEC SQL COMMIT; 提交目前邏輯工作單元
• EXEC SQL ROLLBACK; 回滾並還原
• DDL 執行會隱含 COMMIT，結束目前交易
• 程式正常結束自動 COMMIT，異常結束自動 ROLLBACK
• EXEC SQL DISCONNECT; 釋放所有資源並斷線

錯誤處理：USERCA 結構

每個執行性 SQL 結束後，COBASE 將執行狀態寫入 USERCA：

struct user_com_area {
  char  caid[10];       // "USERCA"
  long  calen;          // 結構長度
  long  sqlcode;        // 0=成功, 2000=無資料/結束, <0=錯誤
  long  sqltype;        // SQL 陳述式類型
  int   sqlerrmlen;     // 錯誤訊息長度
  char  sqlerrmtext[80];// 錯誤訊息文字
  // ... 其他警告旗標、統計計數等
} userca;

最佳實務：每條 SQL 執行後檢查 userca.sqlcode，非零即處理錯誤或記錄日誌。

建置流程（Visual C++ 環境）

1. 以 .ec 為副檔名編寫 ESQL 原始檔。
2. 執行預編譯器：ETE filename（不含副檔名），產生 .cpp。
3. 建立 VC++ 專案，加入產生的 .cpp。
4. 專案設定 → Link → Object/Library Modules 加入：wetelib.lib wccilib.lib。
5. Tools → Options → Directories 設定庫檔路徑。
6. 啟動 COBASE DBA（Cobase.exe），初始化、選擇 Network Share 連線。
7. 執行應用程式測試。
8. 結束時執行 Normal/Immediate Shutdown，再 Exit 離開 COBASE。

常見注意事項

• ISQL 與 ESQL 應用程式不可同時啟動。
• 源檔必須用 VC++ 編輯器存為 .ec，記事本預設 .txt 會導致預編譯器找不到檔案。
• COBASE 目錄需放在磁碟根目錄，應用程式需在同一分區。
• 若缺 msflxgrd.ocx，請複製至 C:\Windows\System32\。
• 磁碟空間不足會導致初始化失敗。

結語

ESQL 讓 C 開發者以熟悉的流程控制撰寫資料庫應用，配合 COBASE 的 USERCA 錯誤機制，能建構穩健的企業級系統。掌握預編譯流程、游標操作與交易控制，是高效開發的關鍵。