|PostgreSQL Reference Manual - Volume 2 - Programming Guide|
by The PostgreSQL Global Development Group
Paperback (6"x9"), 408 pages
RRP £19.95 ($34.95)
Sales of this book support the PostgreSQL project! Get a printed copy>>>
1.8.3 Obsolete Functions for COPY
These functions represent older methods of handling
Although they still work, they are deprecated due to poor error handling,
inconvenient methods of detecting end-of-data, and lack of support for binary
or nonblocking transfers.
Reads a newline-terminated line of characters
(transmitted by the server) into a buffer
string of size
int PQgetline(PGconn *conn, char *buffer, int length);This function copies up to
length-1 characters into the buffer and converts the terminating newline into a zero byte.
EOFat the end of input, 0 if the entire line has been read, and 1 if the buffer is full but the terminating newline has not yet been read. Note that the application must check to see if a new line consists of the two characters
\., which indicates that the server has finished sending the results of the
COPYcommand. If the application might receive lines that are more than
length-1 characters long, care is needed to be sure it recognizes the
\.line correctly (and does not, for example, mistake the end of a long data line for a terminator line).
Reads a row of
COPYdata (transmitted by the server) into a buffer without blocking.
int PQgetlineAsync(PGconn *conn, char *buffer, int bufsize);This function is similar to
PQgetline, but it can be used by applications that must read
COPYdata asynchronously, that is, without blocking. Having issued the
COPYcommand and gotten a
PGRES_COPY_OUTresponse, the application should call
PQgetlineAsyncuntil the end-of-data signal is detected. Unlike
PQgetline, this function takes responsibility for detecting end-of-data. On each call,
PQgetlineAsyncwill return data if a complete data row is available in libpq's input buffer. Otherwise, no data is returned until the rest of the row arrives. The function returns -1 if the end-of-copy-data marker has been recognized, or 0 if no data is available, or a positive number giving the number of bytes of data returned. If -1 is returned, the caller must next call
PQendcopy, and then return to normal processing. The data returned will not extend beyond a data-row boundary. If possible a whole row will be returned at one time. But if the buffer offered by the caller is too small to hold a row sent by the server, then a partial data row will be returned. With textual data this can be detected by testing whether the last returned byte is
\nor not. (In a binary
COPY, actual parsing of the
COPYdata format will be needed to make the equivalent determination.) The returned string is not null-terminated. (If you want to add a terminating null, be sure to pass a
bufsizeone smaller than the room actually available.)
Sends a null-terminated string to the server.
Returns 0 if OK and
EOFif unable to send the string.
int PQputline(PGconn *conn, const char *string);The
COPYdata stream sent by a series of calls to
PQputlinehas the same format as that returned by
PQgetlineAsync, except that applications are not obliged to send exactly one data row per
PQputlinecall; it is okay to send a partial line or multiple lines per call.
Note: Before PostgreSQL protocol 3.0, it was necessary for the application to explicitly send the two characters
\.as a final line to indicate to the server that it had finished sending
COPYdata. While this still works, it is deprecated and the special meaning of
\.can be expected to be removed in a future release. It is sufficient to call
PQendcopyafter having sent the actual data.
Sends a non-null-terminated string to the server.
Returns 0 if OK and
EOFif unable to send the string.
int PQputnbytes(PGconn *conn, const char *buffer, int nbytes);This is exactly like
PQputline, except that the data buffer need not be null-terminated since the number of bytes to send is specified directly. Use this procedure when sending binary data.
Synchronizes with the server.
int PQendcopy(PGconn *conn);This function waits until the server has finished the copying. It should either be issued when the last string has been sent to the server using
PQputlineor when the last string has been received from the server using
PGgetline. It must be issued or the server will get “out of sync” with the client. Upon return from this function, the server is ready to receive the next SQL command. The return value is 0 on successful completion, nonzero otherwise. (Use
PQerrorMessageto retrieve details if the return value is nonzero.) When using
PQgetResult, the application should respond to a
PGRES_COPY_OUTresult by executing
PQgetlinerepeatedly, followed by
PQendcopyafter the terminator line is seen. It should then return to the
PQgetResultreturns a null pointer. Similarly a
PGRES_COPY_INresult is processed by a series of
PQputlinecalls followed by
PQendcopy, then return to the
PQgetResultloop. This arrangement will ensure that a
COPYcommand embedded in a series of SQL commands will be executed correctly. Older applications are likely to submit a
PQexecand assume that the transaction is done after
PQendcopy. This will work correctly only if the
COPYis the only SQL command in the command string.
|ISBN 0954612035||PostgreSQL Reference Manual - Volume 2 - Programming Guide||See the print edition|