.\" auto-generated by docbook2man-spec $Revision: 1.1 $
.TH "DECLARE" "7" "2003-11-02" "SQL - Language Statements" "SQL Commands"
.SH NAME
DECLARE \- 定義一個遊標

.SH SYNOPSIS
.sp
.nf
DECLARE \fIname\fR [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
    CURSOR [ { WITH | WITHOUT } HOLD ] FOR \fIquery\fR
    [ FOR { READ ONLY | UPDATE [ OF \fIcolumn\fR [, ...] ] } ]
.sp
.fi
.SH "DESCRIPTION 描述"
.PP
\fBDECLARE\fR 允許使用者建立遊標， 用於在一個大的查詢裡面檢索少數幾行資料。 使用
FETCH [\fBfetch\fR(7)]，遊標可以既可以返回文字也可以返回二進位制格式。
.PP
 通常遊標返回文字格式，和 SELECT 生成的是一樣的。 因為資料在系統內部是用二進位制格式儲存的， 系統必須對資料做一定轉換以生成文字格式。 一旦資料是以文字形式返回，那麼客戶端應用需要把它們轉換成二進位制進行操作。 另外，文字格式一般都比對應的二進位制格式佔的儲存空間大。 二進位制遊標給你返回內部二進位制形態的資料。當然，如果你想以文字方式顯示資料，那麼以文字方式檢索會為你節約很多客戶端的工作。
.PP
 比如，如果查詢從一個整數列返回一個一， 在預設的遊標裡你將獲得一個字串 1，而如果是一個二進位制遊標， 你將得到一個 4-位元組的包含該數值內部形式的數值（大端序）。
.PP
 遊標應該小心使用二進位制遊標。一些使用者應用如 psql 是不識別二進位制遊標的， 而且期望返回的資料是文字格式。
.sp
.RS
.B "Note:"
注意:  如果客戶端應用使用"擴充套件查詢"協議發出 FETCH 命令， 那麼 Bind 協議宣告資料是用文字還是用二進位制格式檢索。 這個選擇覆蓋遊標的定義。因此，在使用擴充套件查詢協議的時候，二進位制遊標的概念已經過時了 － 任何遊標都可以當作文字或者二進位制的格式發出。
.RE
.sp
.SH "PARAMETERS 引數"
.TP
\fB\fIname\fB\fR
 將在隨後FETCH操作中使用的遊標名。
.TP
\fBBINARY\fR
 令遊標以二進位制而不是文字格式獲取資料。
.TP
\fBINSENSITIVE\fR
 表明從遊標檢索出來的資料不應該被其他程序或遊標的更新動作影響。 在 PostgreSQL 裡，所有遊標都是不敏感的，這個關鍵字沒有什麼作用，提供它只是為了和 SQL 標準相容。
.TP
\fBSCROLL\fR
.TP
\fBNO SCROLL\fR
SCROLL 宣告該遊標可以用於以非順序的方式檢索資料行（也就是向後檢索）。 根據查詢的執行計劃的不同，宣告 SCROLL 可能會對查詢的執行時間附加一定的影響。 NO SCROLL 宣告該遊標不能用於以非順序的方式檢索資料行（也就是向後檢索）。
.TP
\fBWITH HOLD\fR
.TP
\fBWITHOUT HOLD\fR
WITH HOLD 宣告該遊標可以在建立它的事務成功提交後繼續使用。 WITHOUT HOLD 宣告該遊標不能在建立它的的事務提交後使用。如果既沒有宣告 WITHOUT HOLD，也沒有宣告 WITH HOLD， 那麼預設是 WITH HOLD。
.TP
\fB\fIquery\fB\fR
 一個SELECT查詢，它提供由遊標返回的行。 請參考 SELECT 語句獲取有關有效查詢的詳細資訊。
.TP
\fBFOR READ ONLY\fR
.TP
\fBFOR UPDATE\fR
FOR READ ONLY 表明遊標將用於只讀模式。 FOR UPDATE 表明遊標將被用於更新表。 因為目前 PostgreSQL 不支援遊標更新， 所以宣告 FOR UPDATE 將產生一個錯誤資訊。而宣告 FOR READ ONLY 沒有作用。
.TP
\fB\fIcolumn\fB\fR
 將被更新的列。因為遊標更新目前不被 PostgreSQL 支援， 所以 FOR UPDATE 子句將產生一個錯誤資訊。
.PP
BINARY，INSENSITIVE，SCROLL 關鍵字可以以任何順序出現。
.PP
.SH "NOTES 注意"
.PP
 如果沒有宣告 WITH HOLD，那麼這個命令建立的遊標只能在當前事務中使用。
Thus, \fBDECLARE\fR without WITH
HOLD is useless outside a transaction block: the cursor would
survive only to the completion of the statement. Therefore
PostgreSQL reports an error if this
command is used outside a transaction block.
使用
BEGIN [\fBbegin\fR(7)],
COMMIT [\fBcommit\fR(7)]
和
ROLLBACK [\fBrollback\fR(7)]
定義一個事務塊。
.PP
 如果聲明瞭 WITH HOLD，並且建立該遊標的事務成功提交， 那麼遊標還可以在同一會話隨後的事務裡訪問。（但如果建立它的事務回滾，那麼遊標被刪除。） 帶著 WITH HOLD 建立的遊標是用一個明確的 CLOSE 命令，或者是會話終止來關閉的。 在目前的實現裡，由一個遊標代表的行是被複製到一個臨時檔案或者記憶體區裡的，這樣他們就仍然可以在隨後的事務中被訪問。
.PP
 在定義一個要用來向後抓取的遊標的時候，我們應該宣告 SCROLL 選項。 這個是 SQL 標準要求的。不過，為了和早期的版本相容， PostgreSQL 在沒有 SCROLL 的時候也允許向後抓取， 只要遊標的查詢計劃簡單得不需要額外的開銷就可以支援它。 不過，我們建議應用開發人員不要依賴於使用沒有帶著 SCROLL  定義的遊標的後向查詢功能。如果聲明瞭 NO SCROLL，那麼不管怎樣都會禁止向後抓取的功能。
.PP
 在 SQL 標準中游標只能在嵌入 SQL （ESQL） 的應用中使用。 PostgreSQL 伺服器沒有一個明確的 OPEN  語句；一個遊標被認為在定義時就已經打開了。 不過，PostgreSQL嵌入的 SQL 預編譯器， ecpg， 支援 SQL92 習慣，包括那些和DECLARE和OPEN相關的語句。
.SH "EXAMPLES 例子"
.PP
 定義一個遊標：
.sp
.nf
DECLARE liahona CURSOR FOR SELECT * FROM films;
.sp
.fi
 參閱 FETCH [\fBfetch\fR(7)] 獲取有關 遊標使用的更多例子。
.SH "COMPATIBILITY 相容性"
.PP
SQL 標準只允許在嵌入的 SQL 中和模組中使用遊標。 PostgreSQL 允許互動地使用遊標。
.PP
SQL 標準允許遊標更新表資料。 所有 PostgreSQL 的遊標都是隻讀的。
.PP
 二進位制遊標是 PostgreSQL 擴充套件。
.SH "譯者"
.B Postgresql 中文網站
.B 何偉平 <laser@pgsqldb.org>
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR