31.9. kèo bóng đá pháp được liên kết vớiCopylệnh

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, độ dàinbytes, đến máy chủ. kèo bóng đá pháp quả là 1 nếu dữ liệu được xếp hàng, 0 nếu nó không được xếp hàng vì bộ đệm đầy đủ (điều này sẽ chỉ xảy ra ở chế độ không chặn) hoặc -1 nếu xảy ra lỗi. (Sử dụngpqerrormessageĐể truy xuất 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ể chiaCopyluồng dữ kèo bóng đá pháp thành tải bộ đệm của bất kỳ kích thước thuận tiện nào. Ranh giới tải bộ đệm không có ý nghĩa ngữ nghĩa khi gửi. Nội dung của luồng dữ kèo bóng đá pháp phải khớp với định dạng dữ kèo bóng đá pháp được dự kiến ​​bởiCopylệnh; nhìn thấyCopyĐể biết chi tiết.

Gửi chỉ báo cuối cùng vào 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ếuerrormsglànull. 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 thông báo lỗi. (Tuy nhiên, người ta không nên cho rằng thông báo lỗi chính xác này sẽ quay lại từ máy chủ, vì 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-giao thức.)

17713_17980PQFLUSH, lặp lại cho đến khi nó trả về 0.) Số 0 chỉ ra rằng chức năng không thể xếp hàng thông báo chấm dứt vì bộ đệm đầy đủ; Điều này sẽ chỉ xảy ra trong chế độ không chặn. (Trong trường hợp này, hãy đợi để viết sẵn và thửpqputcopyendgọi lại.) Nếu xảy ra lỗi khó xảy ra, -1 được trả về; Bạn có thể sử dụngpqerrormessage18392_18415

Sau khi gọi thành côngpqputcopyend, gọiPQGetResultĐể có được trạng thái kèo bóng đá pháp quả cuối cùng củaCopylệnh. Người ta có thể chờ kèo bóng đá pháp quả này có sẵn theo cách thông thường. Sau đó trở lại hoạt động bình thường.

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 thời gianCopy. Dữ kèo bóng đá pháp luôn được trả về một hàng dữ kèo bóng đá pháp tại một thời điểm; Nếu chỉ có một hàng một phần có sẵn, nó không được trả lại. Trả về 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. The19777_19785tham số phải khôngnull. *bộ đệmđược đặt để trỏ đến bộ nhớ được phân bổ hoặc chonullTrong trường hợp không có bộ đệm nào đượ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ụngPQFreemem20100_20125

Khi một hàng được trả về thành công, giá trị trả về là số byte dữ kèo bóng đá pháp trong hàng (điều này sẽ luôn lớn hơn 0). Chuỗi được trả về luôn được chấm dứt, mặc dù điều này có lẽ chỉ hữu ích cho văn bảnCopy. kèo bóng đá pháp quả của 0 chỉ ra rằngCopyvẫn đang được tiến hành, nhưng chưa có hàng nào có sẵn (điều này chỉ có thể khiAsynclà đúng). kèo bóng đá pháp quả của -1 chỉ ra rằngCopyđược thực hiện. kèo bóng đá pháp quả của -2 chỉ ra rằng xảy ra lỗi (tham khảopqerrormessageVì lý do).

khiAsynclà đúng (không phải bằng không),PQGetCopydatasẽ 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 nào có sẵn. (Trong trường hợp này, hãy đợi sẵn sàng đọc và sau đó gọiPQConsumeInputTrước khi gọiPQGetCopydataMột lần nữa.) KhiAsynclà sai (không),PQGetCopydataSẽ 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 trạng thái kèo bóng đá pháp quả cuối cùng củaCopylệnh. Người ta có thể chờ kèo bóng đá pháp quả này có sẵn theo cách thông thường. Sau đó trở lại hoạt động bình thường.

22244_22349LEGN.

int PQGetLine (PGConn *Conn,
              Char *bộ đệm,
              int length);

Hàm này sao chép lênLEGN-1 ký tự thành bộ đệm và chuyển đổi dòng mới kèo bóng đá pháp thúc 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 chưa được đọc.

Lưu ý rằng ứng dụng phải kiểm tra xem một dòng mới có bao gồm hai ký tự\., trong đó chỉ ra rằng máy chủ đã gửi xong 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ơnlength-1 ký tự dài, cần quan tâm để chắc chắn rằng nó nhận ra\.dòng chính xác (và không, ví dụ, nhầm lẫn cuối dòng dữ kèo bóng đá pháp dài cho dòng Terminator).

Đọc một hàngCopyDữ kèo bóng đá pháp (được truyền bởi máy chủ) vào bộ đệm mà không 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. Đã phát hànhCopylệnh và nhận đượcPGRES_COPY_OUTPhản hồi, ứng dụng nên gọiPQConsumeInputvàPQGetLineAsyncCho đến khi phát hiện tín hiệu cuối cùng của dữ kèo bóng đá pháp.

Không giống nhưPQGetLine, chức năng này 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 hàng dữ kèo bóng đá pháp hoàn chỉnh có sẵn tronglibpqbộ đệm đầu vào. Mặt khác, không có dữ kèo bóng đá pháp nào được trả về cho đến khi phần còn lại của hàng đến. Hàm trả về -1 nếu điểm đánh dấu dữ kèo bóng đá pháp cuối sao đã được nhận dạng hoặc 0 nếu không có dữ kèo bóng đá pháp hoặc một số dương đưa số byte dữ kèo bóng đá pháp được trả về. Nếu -1 được trả về, người gọi phải gọi tiếp theoPQENDCOPY, và sau đó trở lại xử lý bình thường.

dữ kèo bóng đá pháp được trả về sẽ không vượt ra ngoài ranh giới hàng dữ kèo bóng đá pháp. Nếu có thể một hàng toàn bộ sẽ được trả lại cùng một lúc. Nhưng nếu bộ đệm do người gọi cung cấp quá nhỏ để giữ một hàng được gửi bởi máy chủ, thì một hàng dữ kèo bóng đá pháp một phần 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 cuối cùng được trả về là\ nhay 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 thiết để đưa ra quyết định tương đương.) Chuỗi được trả về không được chấm dứt. (Nếu bạn muốn thêm NULL chấm dứt, hãy chắc chắn vượt quaBufsize25562_25611

Gửi một chuỗi kèo bóng đá pháp thúc null đến máy chủ. Trả về 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ó cùng định dạ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 cho mỗipqputlinecuộc gọi; Không sao khi gửi một dòng một phần hoặc nhiều dòng cho mỗi cuộc gọi.

Gửi một 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.

int pqputnbytes (pgconn *Conn,
                const char *bộ đệm,
                int nbytes);

Đ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.

Đồng bộ hóa với máy chủ.

int pqendcopy (pgconn *Conn);

27755_27902pqputlinehoặc khi chuỗi cuối cùng được nhận từ máy chủ bằng cách sử dụngPQGetLine. Nó phải được cấp 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. Giá trị trả về là 0 khi hoàn thành thành công, khác không. (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 thiPQGetLineCứu, theo sau làPQENDCOPYSau khi thấy dòng Terminator được nhìn thấy. Sau đó nó sẽ trở lạiPQGetResultvòng lặp cho đếnPQGetResultTrả về một con trỏ null. Tương tự APGRES_COPY_INkèo bóng đá pháp quả được xử lý bởi một loạtpqputlinecuộc gọi theo sau làPQENDCOPY, sau đó quay 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 thực thi chính xác.

kèo bóng đá pháp ứng dụng cũ có khả năng gửi ACopyViaPQEXECvà 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ấtSQLLệnh trong chuỗi lệnh.