| Postgresql 8.3.23 Tài kèo bóng đá pháp | ||||
|---|---|---|---|---|
| prev | Backward nhanh | Chương 30.libpq- C Thư viện | Chuyển tiếp nhanh | NEXT |
TheCopylệnh trongPostgreSQLCó các tùy chọn để đọc hoặc viết đến kèo bóng đá pháp nối mạng được sử dụng bởilibpq. kèo bóng đá pháp năng được mô tả trong này Phần cho phép các ứng dụng tận dụng khả năng này bằng cách cung cấp hoặc tiêu thụ dữ liệu đã sao chép.
Quy trình tổng thể là ứng dụng đầu tiên phát hành
SQLCopylệnh thông quaPQEXEChoặc một trong kèo bóng đá pháp năng tương đương. Các
phản hồi cho điều này (nếu không có lỗi trong lệnh) sẽ làpgresultĐối tượng mang mã trạng thái
củaPGRES_COPY_OUThoặcPGRES_COPY_IN(Tùy thuộc vào bản sao được chỉ định
phương hướng). Ứng dụng sau đó nên sử dụng kèo bóng đá pháp năng của điều này
phần để nhận hoặc truyền các hàng dữ liệu. Khi truyền dữ liệu
hoàn thành, một người khácpgresultĐối tượng
được trả lại để chỉ ra thành công hoặc thất bại của việc chuyển nhượng. Của nó
Trạng thái sẽ làPGRES_COMMAND_OKcho
thành công hoặcPGRES_FATAL_ERRORNếu một số
Vấn đề đã gặp phải. Tại thời điểm này, kèo bóng đá pháp lệnh SQL có thể
được cấp quaPQEXEC. (Nó không phải là
có thể thực thi các lệnh SQL khác bằng cách sử dụng cùng một kèo bóng đá pháp nối
Trong khiCopyHoạt động là trong
tiến triển.)
Nếu ACopyLệnh được cấp quaPQEXECTrong một chuỗi có thể
chứa các lệnh bổ sung, ứng dụng phải tiếp tục
tìm nạp kèo bóng đá pháp quả quaPQGetResultSau khi hoàn thànhCopyTrình tự. Chỉ một
khiPQGetResultreturnnullCó chắc chắn rằngPQEXECChuỗi lệnh được thực hiện và an toàn khi
phát hành thêm kèo bóng đá pháp lệnh.
Các chức năng của phần này chỉ được thực thi sau khi
có được trạng thái kèo bóng đá pháp quả củaPGRES_COPY_OUThoặcPGRES_COPY_INtừPQEXEChoặcPQGetResult.
A13797_13807đối tượng mang một trong những kèo bóng đá pháp giá trị trạng thái này mang một số dữ liệu bổ sung vềCopyHoạt động đang bắt đầu. Cái này Dữ liệu bổ sung có sẵn bằng cách sử dụng các chức năng cũng được sử dụng liên quan đến kèo bóng đá pháp quả truy vấn:
PQNFields Trả về số lượng cột (trường) sẽ được sao chép.
PQBinaryTuples 0 Cho biết định dạng bản sao tổng thể là văn bản (hàng tách biệt bởi kèo bóng đá pháp dòng mới, kèo bóng đá pháp cột được phân tách bằng phân tách ký tự, vv). 1 cho biết định dạng bản sao tổng thể là nhị phân. Nhìn thấyCopycho Thêm thông tin.
PQFFormat Trả về mã định dạng (0 cho văn bản, 1 cho nhị phân) được liên kèo bóng đá pháp với mỗi cột của hoạt động sao chép. Các Mã định dạng trên mỗi cột sẽ luôn bằng không khi Định dạng bản sao tổng thể là văn bản, nhưng định dạng nhị phân có thể Hỗ trợ cả cột văn bản và nhị phân. (Tuy nhiên, kể từ Thực hiện hiện tại củaCopy,, Chỉ kèo bóng đá pháp cột nhị phân xuất hiện trong một bản sao nhị phân; Vì vậy, kèo bóng đá pháp định dạng trên mỗi cột luôn phù hợp với định dạng tổng thể tại hiện tại.)
Lưu ý:Những giá trị dữ liệu bổ sung này chỉ là Có sẵn khi sử dụng Giao thức 3.0. Khi sử dụng Giao thức 2.0, Tất cả kèo bóng đá pháp năng này sẽ trả về 0.
kèo bóng đá pháp năng này được sử dụng để gửi dữ liệu trongSao chép từ Stdin. Họ sẽ thất bại nếu được gọi khi kèo bóng đá pháp nối không có trongcopy_inState.
PQPutCopydata Gửi dữ kèo bóng đá pháp đến máy chủ trong khicopy_inBang.
int pqputcopydata (pgconn *Conn,
const char *bộ đệm,
int nbytes);
TruyềnCopyDữ kèo bóng đá pháp trong
được chỉ địnhbộ đệm, của
chiều dàinbyte, đến máy chủ.
kèo bóng đá pháp quả là 1 nếu dữ liệu được gửi, không nếu nó không
được gửi bởi vì nỗ lực sẽ chặn (trường hợp này chỉ là
có thể nếu kèo bóng đá pháp nối ở chế độ không chặn) hoặc -1
Nếu xảy ra lỗi. (Sử dụng16924_16940Để lấy chi tiết nếu
Giá trị trả về là -1. Nếu giá trị bằng không, hãy đợi
viết sẵn và thử lại.)
Ứng dụng có thể chiaCopy17161_17400Copylệnh; nhìn thấyCopyĐể biết chi tiết.
pqputcopyend Gửi chỉ số cuối dữ kèo bóng đá pháp đến máy chủ trong thời giancopy_inBang.
int pqputcopyend (pgconn *Conn,
const char *errormsg);
kèo bóng đá pháp thúccopy_inHoạt động Thành công nếuerrormsg18027_18043null. Nếu nhưerrormsgkhông phảinullsau đóCopybị buộc phải thất bại, với chuỗi được trỏ bởierrormsgĐược sử dụng làm lỗi tin nhắn. (Người ta không nên cho rằng lỗi chính xác này Tin nhắn sẽ trở lại từ máy chủ, tuy nhiên, máy chủ có thể đã thất bạiCopyvì lý do riêng của nó. Cũng lưu ý rằng Tùy chọn buộc lỗi không hoạt động khi sử dụng kèo bóng đá pháp nối Pre-3.0 Protocol.)
kèo bóng đá pháp quả là 1 nếu dữ liệu chấm dứt được gửi, không
Nếu nó không được gửi vì nỗ lực sẽ chặn (cái này
trường hợp chỉ có thể nếu kèo bóng đá pháp nối không bị chặn
chế độ), hoặc -1 nếu xảy ra lỗi. (Sử dụngpqerrormessageĐể lấy chi tiết nếu
Giá trị trả về là -1. Nếu giá trị bằng không, hãy đợi
viết sẵn và thử lại.)
Sau khi gọi thành côngpqputcopyend, gọiPQGetResultĐể có được kèo bóng đá pháp quả cuối cùng
trạng thái củaCopylệnh. Một
có thể đợi kèo bóng đá pháp quả này có sẵn trong thông thường
đường. Sau đó trở lại hoạt động bình thường.
kèo bóng đá pháp năng này được sử dụng để nhận dữ liệu trongSao chép vào stdout. Họ sẽ thất bại nếu được gọi khi kèo bóng đá pháp nối không có trongcopy_outBang.
PQGetCopydata Nhận dữ kèo bóng đá pháp từ máy chủ trongcopy_outBang.
int PQGetCopydata (PGConn *Conn,
Char ** Buffer,
int async);
cố gắng lấy một hàng dữ kèo bóng đá pháp khác từ máy chủ
Trong mộtCopy. Dữ kèo bóng đá pháp luôn luôn
trả lại một hàng dữ kèo bóng đá pháp tại một thời điểm; Nếu chỉ một hàng một phần là
Có sẵn, nó không được trả lại. Sự trở lại thành công của một
Hàng dữ kèo bóng đá pháp liên quan đến việc phân bổ một khối bộ nhớ để giữ
dữ kèo bóng đá pháp. Thebộ đệmTham số
Phải khôngnull. *bộ đệmđược đặt thành chỉ vào phân bổ
bộ nhớ hoặc đếnnullTrong trường hợp
Không có bộ đệm được trả lại. Không phảinullBộ đệm kèo bóng đá pháp quả phải được giải phóng bằng cách sử dụngpqfreememKhi không cần thiết.
Khi một hàng được trả về thành công, giá trị trả về
là số lượng byte dữ liệu trong hàng (điều này sẽ luôn luôn
lớn hơn 0). Chuỗi được trả về luôn luôn là
kèo bóng đá pháp thúc null, mặc dù điều này có lẽ chỉ hữu ích cho
TextualCopy. kèo bóng đá pháp quả của số không
chỉ ra rằngCopyvẫn còn
trong tiến trình, nhưng chưa có hàng nào có sẵn (điều này chỉ là
có thể khiAsynclà đúng).
kèo bóng đá pháp quả của -1 chỉ ra rằngCopy21777_21856pqerrormessageVì lý do).
KhiAsynclà đúng (không
không),PQGetCopydataWill
không chặn chờ đầu vào; nó sẽ trả về 0 nếuCopyvẫn đang được tiến hành nhưng không có
Hàng hoàn chỉnh có sẵn. (Trong trường hợp này, hãy đợi
Read-Ready và sau đó gọiPQConsumeInputTrước khi gọiPQGetCopydataMột lần nữa.) KhiAsync22471_22501PQGetCopydataSẽ chặn
Cho đến khi dữ kèo bóng đá pháp có sẵn hoặc hoạt động hoàn thành.
sauPQGetCopydatareturn -1, gọiPQGetResultĐể có được kèo bóng đá pháp quả cuối cùng
trạng thái củaCopyLệnh. Một
có thể đợi kèo bóng đá pháp quả này có sẵn trong thông thường
đường. Sau đó trở lại hoạt động bình thường.
kèo bóng đá pháp năng này biểu thị các phương thức xử lý cũ hơnCopy. Mặc dù họ vẫn hoạt động, họ được không dùng nữa do xử lý lỗi kém, các phương pháp bất tiện phát hiện kèo bóng đá pháp thúc dữ liệu và thiếu hỗ trợ cho nhị phân hoặc Chuyển khoản không chặn.
PQGetLine Đọc một dòng ký tự kèo bóng đá pháp thúc mới (được truyền bởi máy chủ) vào chuỗi bộ đệm có kích thướcLEGN.
int PQGetLine (PGConn *Conn,
Char *bộ đệm,
int length);
Hàm này sao chép lênlength-1 ký tự vào bộ đệm và
Chuyển đổi việc chấm dứt dòng mới thành một byte số 0.PQGetLinereturnEOFở cuối đầu vào, 0 nếu
toàn bộ dòng đã được đọc và 1 nếu bộ đệm đầy
Nhưng dòng mới kèo bóng đá pháp thúc vẫn chưa được đọc.
Lưu ý rằng ứng dụng phải kiểm tra xem kèo bóng đá pháp mới dòng bao gồm hai ký tự\., trong đó chỉ ra rằng máy chủ có Đã hoàn thành việc gửi kèo bóng đá pháp quả củaCopyLệnh. Nếu ứng dụng có thể nhận kèo bóng đá pháp dòng nhiều hơnLEGN-1 ký tự dài, cần chăm sóc Để chắc chắn rằng nó nhận ra\.dòng chính xác (và không, ví dụ, sai lầm kèo bóng đá pháp thúc một dòng dữ liệu dài cho một dòng Terminator).
PQGetLineAsync Đọc một hàngCopyDữ kèo bóng đá pháp (truyền bởi máy chủ) vào bộ đệm mà không có chặn.
int pqgetLineAnync (pgconn *Conn,
Char *bộ đệm,
int bufsize);
Hàm này tương tựPQGetLine, nhưng nó có thể được sử dụng bởi
kèo bóng đá pháp ứng dụng phải đọcCopyDữ kèo bóng đá pháp không đồng bộ, nghĩa là không chặn. Có
đã ban hànhCopylệnh và
Got APGRES_COPY_OUTPhản hồi, ứng dụng nên gọiPQConsumeInputvàPQGetLineAsyncCho đến khi kèo bóng đá pháp thúc dữ liệu
tín hiệu được phát hiện.
Không giống nhưPQGetLine, Điều này
chức năng chịu trách nhiệm phát hiện
kèo bóng đá pháp thúc dữ liệu.
trên mỗi cuộc gọi,PQGetLineAsyncsẽ trả về dữ kèo bóng đá pháp nếu a
Hàng dữ kèo bóng đá pháp hoàn chỉnh có sẵn tronglibpqbộ đệm đầu vào. Nếu không, không
Dữ liệu được trả về cho đến khi phần còn lại của hàng đến. kèo bóng đá pháp
chức năng trả về -1 nếu điểm đánh dấu dữ liệu cuối sao
được công nhận hoặc 0 nếu không có dữ liệu hoặc
Số dương cho số byte dữ liệu
trả lại. Nếu -1 được trả về, người gọi phải gọi tiếp theoPQENDCOPY, sau đó trở lại
để xử lý bình thường.
Dữ kèo bóng đá pháp được trả về sẽ không mở rộng ra khỏi hàng dữ kèo bóng đá pháp ranh giới. Nếu có thể, toàn bộ hàng sẽ được trả lại tại một thời gian. Nhưng nếu bộ đệm do người gọi cung cấp cũng vậy nhỏ để giữ một hàng được gửi bởi máy chủ, sau đó là một phần Hàng dữ kèo bóng đá pháp sẽ được trả về. Với dữ kèo bóng đá pháp văn bản, điều này có thể được phát hiện bằng cách kiểm tra xem byte trả về cuối cùng là\ nhoặc không. (Trong một nhị phânCopy, Phân tích cú pháp thực tế củaCopyĐịnh dạng dữ kèo bóng đá pháp sẽ cần để đưa ra quyết định tương đương.) Chuỗi không được chấm dứt. (Nếu bạn muốn thêm một chấm dứt null, hãy chắc chắn vượt quaBufsizeMột nhỏ hơn phòng thực sự có sẵn.)
pqputline Gửi một chuỗi kèo bóng đá pháp thúc null đến máy chủ. Trả lại 0 nếu ok vàEOFNếu không thể gửi chuỗi.
int pqputline (PGConn *Conn,
const char *chuỗi);
TheCopyluồng dữ liệu được gửi bởi
một loạt kèo bóng đá pháp cuộc gọi đếnpqputlinecó định dạng giống như
Được trả về bởiPQGetLineAsync,,
ngoại trừ kèo bóng đá pháp ứng dụng không bắt buộc phải gửi chính xác
một hàng dữ liệu trên mỗipqputlinecuộc gọi; Bạn có thể gửi một dòng một phần hoặc nhiều dòng
mỗi cuộc gọi.
Lưu ý:TrướcPostgreSQLGiao thức 3.0, đó là cần thiết để ứng dụng gửi rõ ràng Hai ký tự\.như một trận chung kèo bóng đá pháp dòng để chỉ cho máy chủ rằng nó đã hoàn thành GửiCopyDữ kèo bóng đá pháp. Trong khi Điều này vẫn hoạt động, nó không được chấp nhận và đặc biệt Ý nghĩa của\.có thể dự kiến sẽ được gỡ bỏ trong một bản phát hành trong tương lai. Nó là đủ để gọi
PQENDCOPYsau khi đã gửi Dữ kèo bóng đá pháp thực tế.
pqputnbytes Gửi chuỗi không kèo bóng đá pháp thúc không đến máy chủ. Trả về 0 nếu ok vàEOFNếu không thể để gửi chuỗi.
29800_29930
Điều này giống hệtpqputline, ngoại trừ bộ đệm dữ liệu
không cần phải kèo bóng đá pháp thúc vì số lượng byte
Gửi được chỉ định trực tiếp. Sử dụng quy trình này khi
gửi dữ liệu nhị phân.
PQENDCOPY Đồng bộ hóa với máy chủ.
int pqendcopy (pgconn *Conn);
30493_30660pqputlinehoặc khi chuỗi cuối cùng có
được nhận từ máy chủ bằng cách sử dụngPGGetLine. Nó phải được phát hành hoặc
Máy chủ sẽ nhận được"Out of Sync"Với máy khách. Khi trở về từ chức năng này,
Máy chủ đã sẵn sàng để nhận lệnh SQL tiếp theo. kèo bóng đá pháp
Giá trị trở lại là 0 khi hoàn thành thành công, không
nếu không thì. (Sử dụngpqerrormessageĐể lấy chi tiết nếu
giá trị trả về không khác.)
Khi sử dụngPQGetResult,,
Ứng dụng sẽ trả lờiPGRES_COPY_OUTkèo bóng đá pháp quả bằng cách thực thiPQGetLinenhiều lần,
theo sau làPQENDCOPYsau
dòng Terminator được nhìn thấy. Sau đó nó sẽ trở lại31680_31693Vòng lặp cho đếnPQGetResultTrả về một null
con trỏ. Tương tự APGRES_COPY_INkèo bóng đá pháp quả được xử lý bởi A
sê -ripqputlinecuộc gọi
theo sau làPQENDCOPY, sau đó
trở lạiPQGetResultVòng lặp. Sự sắp xếp này sẽ đảm bảo rằngCopyLệnh được nhúng trong một loạtSQLkèo bóng đá pháp lệnh sẽ được
được thực hiện chính xác.
32322_32366CopyViaPQEXECVà giả sử rằng giao dịch
được thực hiện sauPQENDCOPY.
Điều này sẽ chỉ hoạt động chính xác nếuCopylà duy nhấtSQL32703_32746