Передает данные на сервер во время выполнения операции COPY_IN состоянии.

int PQputCopyData(PGconn *conn,
                  const char *buffer,
                  int nbytes);

Передает COPY данные из указанного bufferдлиной nbytesна сервер. Результат равен 1, если данные были помещены в очередь, и 0, если данные не были помещены в очередь вследствие переполнения буферов (это происходит только в неблокирующем режиме), или -1 при возникновении ошибки. (Используйте соответствующие средства PQerrorMessage для получения подробных сведений, если возвращаемое значение равно -1. Если значение равно нулю, дождитесь готовности к записи и повторите попытку.)

Приложение может разделить COPY поток данных на порции буфера любого удобного размера. Границы порций буфера не имеют семантического значения при отправке. Содержимое потока данных должно соответствовать формату данных, который ожидает COPY команда; см. COPY для получения подробных сведений.

Отправляет на сервер индикатор завершения передачи данных в процессе COPY_IN состоянии.

int PQputCopyEnd(PGconn *conn,
                 const char *errormsg);

Завершает COPY_IN операцию успешно, если же errormsg имеет значение NULL значение NULL. Если errormsg не является значение NULL то она COPY принудительно завершается с ошибкой, а в качестве сообщения об ошибке используется строка, на которую указывает errormsg параметр errormsg. (Не следует полагать, что от сервера вернется именно это сообщение об ошибке, однако, так как сервер уже мог завершить со сбоем COPY по собственным причинам.)

Результат равен 1, если сообщение о завершении было отправлено; либо в неблокирующем режиме это может означать лишь то, что сообщение о завершении было успешно поставлено в очередь. (В неблокирующем режиме, чтобы быть уверенным в отправке данных, следует дождаться состояния готовности к записи и вызвать функцию PQflush, повторяя вызов до тех пор, пока она не вернёт ноль.) Ноль означает, что функция не смогла поставить в очередь сообщение о завершении из-за переполнения буферов; это возможно только в неблокирующем режиме. (В этом случае следует дождаться готовности к записи и повторить PQputCopyEnd вызов функции снова.) При возникновении критической ошибки возвращается -1; можно использовать PQerrorMessage для получения подробных сведений.

После успешного вызова функции PQputCopyEnd, вызовите функцию PQgetResult для получения окончательного статуса результата COPY команда. Можно дождаться, когда этот результат будет станут доступны обычным способом. После этого следует вернуться к штатному режиму работы.

В ходе выполнения операции данные от сервера получает функция COPY_OUT состоянии.

int PQgetCopyData(PGconn *conn,
                  char **buffer,
                  int async);

В ходе выполнения операции попытка получения очередной строки данных от сервера осуществляется функцией COPY. Данные всегда возвращаются по одной строке за раз; в случае доступности только части строки она не возвращается. Успешный возврат строки данных предполагает выделение фрагмента памяти для хранения данных. buffer параметр должен быть не-значение NULL. *buffer устанавливается в значение указывать на выделенную область памяти или на значение NULL в тех случаях, когда буфер не возвращается. Значение,значение NULL результат отличное от значения NULL, следует освободить с помощью функции PQfreemem когда оно больше не требуется.

При успешном возврате строки возвращаемым значением является количество байтов данных в строке (данное значение всегда будет больше нуля). Возвращаемая строка всегда завершается нулем, хотя это, вероятно, полезно только для текстовых данных COPY. Результат равный нулю, указывает на то, что COPY операция все еще находится в процессе выполнения, но строка еще не доступна (это возможно только в случае, когда параметр async имеет значение true). Результат, равный -1, указывает на то, что выполнение COPY завершено. Значение -2 указывает на то, что произошла ошибка (обратитесь к PQerrorMessage для выяснения причины).

Когда async имеет значение true (не ноль), PQgetCopyData не будет блокироваться в ожидании ввода; функция вернет ноль, если COPY все еще выполняется но полная строка недоступна. (В этом случае дождитесь готовности дескриптора к чтению и затем вызовите функцию PQconsumeInput перед вызовом функции PQgetCopyData снова.) Когда async имеет имеет значение false (ноль), PQgetCopyData будет блокироваться до тех пор, пока данные не станут доступны или операция не завершится.

После того как функция PQgetCopyData вернет -1, вызовите функцию PQgetResult для получения окончательного статуса результата COPY команда. Можно дождаться, когда этот результат будет станут доступны обычным способом. После этого следует вернуться к штатному режиму работы.

Считывает переданную сервером строку символов, завершающуюся символом новой строки, в строковый буфер, имеющий размер length.

int PQgetline(PGconn *conn,
              char *buffer,
              int length);

Данная функция копирует до length-1 символов в буфер и преобразует завершающий символ новой строки в нулевой байт. PQgetline возвращает EOF при достижении конца входных данных, 0, если была считана вся строка, и 1, если буфер заполнен, но завершающий символ новой строки ещё не был считан.

Следует отметить, что приложение должно проверять, состоит ли новая строка из двух символов \., что указывает на информацию о том, что сервер завершил отправку результатов COPY команда. Если приложение может получать строки, длина которых превышает length-1 символов, необходимо убедиться, что оно правильно распознает \. эту строку (и, например, не принимает окончание длинной строки данных за строку-терминатор).

Считывает строку COPY данных (передаваемых сервером) в буфер без блокировки.

int PQgetlineAsync(PGconn *conn,
                   char *buffer,
                   int bufsize);

Данная функция аналогична PQgetline, однако она может использоваться в приложениях, которые должны выполнять чтение COPY данные асинхронно, то есть без блокировки. После выполнения COPY команды и получения PGRES_COPY_OUT ответа, приложение должно вызвать PQconsumeInput и PQgetlineAsync до тех пор, пока не будет обнаружен сигнал завершения передачи данных.

В отличие от PQgetline, данная функция берет на себя задачу по обнаружению завершения передачи данных.

При каждом вызове PQgetlineAsync будет возвращать данные, если доступна полная строка данных во libpqвходном буфере. В противном случае данные не будут возвращены до тех пор, пока не поступит оставшаяся часть строки. Функция возвращает -1, если был распознан маркер завершения копирования данных, 0, если данные недоступны, или положительное число, указывающее количество возвращенных байтов данных. Если возвращается значение -1, вызывающая сторона должна затем вызвать функцию PQendcopy, после чего следует вернуться к обычной обработке.

Возвращаемые данные не будут выходить за границы строки данных. По возможности вся строка будет возвращена за один раз. Однако если буфер, предоставленный вызывающей стороной, слишком мал для размещения строки, отправленной сервером, будет возвращена частичная строка данных. В случае текстовых данных это можно определить путем проверки того, является ли последний возвращенный байт символом \n или нет. (В двоичном формате COPYдля принятия аналогичного решения COPY потребуется фактический разбор формата данных.) Возвращаемая строка не завершается значением NULL. (Если требуется добавить завершающее значение NULL, обязательно передайте в параметре bufsize значение на единицу меньше фактически доступного объема памяти.)

Отправляет серверу строку, завершающуюся нулевым символом. Возвращает 0, если операция завершена успешно, и EOF если отправить строку не удалось.

int PQputline(PGconn *conn,
              const char *string);

Параметр COPY поток данных, отправляемый серией вызовов, равным PQputline имеет тот же формат, что и данные, возвращаемые функцией PQgetlineAsync, за исключением того, что приложения не обязаны отправлять ровно одну строку данных за один PQputline вызов; допускается отправка части строки или нескольких строк за один вызов.

Отправляет на сервер строку, не завершающуюся нулевым символом. Возвращает значение 0 в случае успеха и EOF если отправить строку не удалось.

int PQputnbytes(PGconn *conn,
                const char *buffer,
                int nbytes);

Эта функция работает точно так же, как PQputline, за исключением того, что буфер данных не обязательно должен завершаться нулевым символом, так как количество байтов для отправки указывается напрямую. Данную процедуру следует использовать при отправке двоичных данных.

Выполняет синхронизацию с сервером.

int PQendcopy(PGconn *conn);

Данная функция ожидает завершения процесса копирования сервером. Ее следует вызывать либо после того, как была отправлена последняя строка серверу с помощью PQputline либо когда от сервера была получена последняя строка с помощью PQgetline. Функцию необходимо вызвать, иначе сервер перейдет в состояние «рассинхронизации» с клиентом. После возврата из данной функции сервер будет готов к приему следующей SQL-команды команды. При успешном завершении возвращаемое значение равно 0, в противном случае оно отлично от нуля. (Используйте PQerrorMessage для для получения подробных сведений, если возвращаемое значение не равно нулю.)

При использовании параметра PQgetResult, приложению следует реагировать на PGRES_COPY_OUT результат путем выполнения PQgetline многократно, после чего следует PQendcopy после обнаружения строки-терминатора. Затем управление должно вернуться в PQgetResult цикл до тех пор, пока PQgetResult функция не вернет значение NULL. Аналогичным образом PGRES_COPY_IN результат обрабатывается посредством ряда PQputline вызовов, за которыми следует PQendcopy, после чего необходимо вернуться в PQgetResult цикл. Такой порядок обеспечит, чтобы COPY команда, встроенная в последовательность параметра SQL команд, выполнялась корректно.

В устаревших приложениях, вероятнее всего, отправляется COPY посредством PQexec и предполагается, что транзакция завершается после PQendcopy. Это будет работать корректно только в том случае, если COPY является единственной SQL командой в командной строке.