ok
Direktori : /opt/alt/postgresql11/usr/share/doc/alt-postgresql11-9.2.24/html/ |
Current File : //opt/alt/postgresql11/usr/share/doc/alt-postgresql11-9.2.24/html/libpq-copy.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Functions Associated with the COPY Command</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 9.2.24 Documentation" HREF="index.html"><LINK REL="UP" TITLE="libpq - C Library" HREF="libpq.html"><LINK REL="PREVIOUS" TITLE="Asynchronous Notification" HREF="libpq-notify.html"><LINK REL="NEXT" TITLE="Control Functions" HREF="libpq-control.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2017-11-06T22:43:11"></HEAD ><BODY CLASS="SECT1" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="5" ALIGN="center" VALIGN="bottom" ><A HREF="index.html" >PostgreSQL 9.2.24 Documentation</A ></TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A TITLE="Asynchronous Notification" HREF="libpq-notify.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="libpq.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" >Chapter 31. <SPAN CLASS="APPLICATION" >libpq</SPAN > - C Library</TD ><TD WIDTH="20%" ALIGN="right" VALIGN="top" ><A TITLE="Control Functions" HREF="libpq-control.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="LIBPQ-COPY" >31.9. Functions Associated with the <TT CLASS="COMMAND" >COPY</TT > Command</A ></H1 ><P > The <TT CLASS="COMMAND" >COPY</TT > command in <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > has options to read from or write to the network connection used by <SPAN CLASS="APPLICATION" >libpq</SPAN >. The functions described in this section allow applications to take advantage of this capability by supplying or consuming copied data. </P ><P > The overall process is that the application first issues the SQL <TT CLASS="COMMAND" >COPY</TT > command via <CODE CLASS="FUNCTION" >PQexec</CODE > or one of the equivalent functions. The response to this (if there is no error in the command) will be a <TT CLASS="STRUCTNAME" >PGresult</TT > object bearing a status code of <TT CLASS="LITERAL" >PGRES_COPY_OUT</TT > or <TT CLASS="LITERAL" >PGRES_COPY_IN</TT > (depending on the specified copy direction). The application should then use the functions of this section to receive or transmit data rows. When the data transfer is complete, another <TT CLASS="STRUCTNAME" >PGresult</TT > object is returned to indicate success or failure of the transfer. Its status will be <TT CLASS="LITERAL" >PGRES_COMMAND_OK</TT > for success or <TT CLASS="LITERAL" >PGRES_FATAL_ERROR</TT > if some problem was encountered. At this point further SQL commands can be issued via <CODE CLASS="FUNCTION" >PQexec</CODE >. (It is not possible to execute other SQL commands using the same connection while the <TT CLASS="COMMAND" >COPY</TT > operation is in progress.) </P ><P > If a <TT CLASS="COMMAND" >COPY</TT > command is issued via <CODE CLASS="FUNCTION" >PQexec</CODE > in a string that could contain additional commands, the application must continue fetching results via <CODE CLASS="FUNCTION" >PQgetResult</CODE > after completing the <TT CLASS="COMMAND" >COPY</TT > sequence. Only when <CODE CLASS="FUNCTION" >PQgetResult</CODE > returns <TT CLASS="SYMBOL" >NULL</TT > is it certain that the <CODE CLASS="FUNCTION" >PQexec</CODE > command string is done and it is safe to issue more commands. </P ><P > The functions of this section should be executed only after obtaining a result status of <TT CLASS="LITERAL" >PGRES_COPY_OUT</TT > or <TT CLASS="LITERAL" >PGRES_COPY_IN</TT > from <CODE CLASS="FUNCTION" >PQexec</CODE > or <CODE CLASS="FUNCTION" >PQgetResult</CODE >. </P ><P > A <TT CLASS="STRUCTNAME" >PGresult</TT > object bearing one of these status values carries some additional data about the <TT CLASS="COMMAND" >COPY</TT > operation that is starting. This additional data is available using functions that are also used in connection with query results: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><A NAME="LIBPQ-PQNFIELDS-1" ></A ><CODE CLASS="FUNCTION" >PQnfields</CODE > </DT ><DD ><P > Returns the number of columns (fields) to be copied. </P ></DD ><DT ><A NAME="LIBPQ-PQBINARYTUPLES-1" ></A ><CODE CLASS="FUNCTION" >PQbinaryTuples</CODE > </DT ><DD ><P > 0 indicates the overall copy format is textual (rows separated by newlines, columns separated by separator characters, etc). 1 indicates the overall copy format is binary. See <A HREF="sql-copy.html" >COPY</A > for more information. </P ></DD ><DT ><A NAME="LIBPQ-PQFFORMAT-1" ></A ><CODE CLASS="FUNCTION" >PQfformat</CODE > </DT ><DD ><P > Returns the format code (0 for text, 1 for binary) associated with each column of the copy operation. The per-column format codes will always be zero when the overall copy format is textual, but the binary format can support both text and binary columns. (However, as of the current implementation of <TT CLASS="COMMAND" >COPY</TT >, only binary columns appear in a binary copy; so the per-column formats always match the overall format at present.) </P ></DD ></DL ></DIV ><P> </P ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B > These additional data values are only available when using protocol 3.0. When using protocol 2.0, all these functions will return 0. </P ></BLOCKQUOTE ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-COPY-SEND" >31.9.1. Functions for Sending <TT CLASS="COMMAND" >COPY</TT > Data</A ></H2 ><P > These functions are used to send data during <TT CLASS="LITERAL" >COPY FROM STDIN</TT >. They will fail if called when the connection is not in <TT CLASS="LITERAL" >COPY_IN</TT > state. </P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><A NAME="LIBPQ-PQPUTCOPYDATA" ></A ><CODE CLASS="FUNCTION" >PQputCopyData</CODE > </DT ><DD ><P > Sends data to the server during <TT CLASS="LITERAL" >COPY_IN</TT > state. </P><PRE CLASS="SYNOPSIS" >int PQputCopyData(PGconn *conn, const char *buffer, int nbytes);</PRE ><P> </P ><P > Transmits the <TT CLASS="COMMAND" >COPY</TT > data in the specified <TT CLASS="PARAMETER" >buffer</TT >, of length <TT CLASS="PARAMETER" >nbytes</TT >, to the server. The result is 1 if the data was sent, zero if it was not sent because the attempt would block (this case is only possible if the connection is in nonblocking mode), or -1 if an error occurred. (Use <CODE CLASS="FUNCTION" >PQerrorMessage</CODE > to retrieve details if the return value is -1. If the value is zero, wait for write-ready and try again.) </P ><P > The application can divide the <TT CLASS="COMMAND" >COPY</TT > data stream into buffer loads of any convenient size. Buffer-load boundaries have no semantic significance when sending. The contents of the data stream must match the data format expected by the <TT CLASS="COMMAND" >COPY</TT > command; see <A HREF="sql-copy.html" >COPY</A > for details. </P ></DD ><DT ><A NAME="LIBPQ-PQPUTCOPYEND" ></A ><CODE CLASS="FUNCTION" >PQputCopyEnd</CODE > </DT ><DD ><P > Sends end-of-data indication to the server during <TT CLASS="LITERAL" >COPY_IN</TT > state. </P><PRE CLASS="SYNOPSIS" >int PQputCopyEnd(PGconn *conn, const char *errormsg);</PRE ><P> </P ><P > Ends the <TT CLASS="LITERAL" >COPY_IN</TT > operation successfully if <TT CLASS="PARAMETER" >errormsg</TT > is <TT CLASS="SYMBOL" >NULL</TT >. If <TT CLASS="PARAMETER" >errormsg</TT > is not <TT CLASS="SYMBOL" >NULL</TT > then the <TT CLASS="COMMAND" >COPY</TT > is forced to fail, with the string pointed to by <TT CLASS="PARAMETER" >errormsg</TT > used as the error message. (One should not assume that this exact error message will come back from the server, however, as the server might have already failed the <TT CLASS="COMMAND" >COPY</TT > for its own reasons. Also note that the option to force failure does not work when using pre-3.0-protocol connections.) </P ><P > The result is 1 if the termination data was sent, zero if it was not sent because the attempt would block (this case is only possible if the connection is in nonblocking mode), or -1 if an error occurred. (Use <CODE CLASS="FUNCTION" >PQerrorMessage</CODE > to retrieve details if the return value is -1. If the value is zero, wait for write-ready and try again.) </P ><P > After successfully calling <CODE CLASS="FUNCTION" >PQputCopyEnd</CODE >, call <CODE CLASS="FUNCTION" >PQgetResult</CODE > to obtain the final result status of the <TT CLASS="COMMAND" >COPY</TT > command. One can wait for this result to be available in the usual way. Then return to normal operation. </P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-COPY-RECEIVE" >31.9.2. Functions for Receiving <TT CLASS="COMMAND" >COPY</TT > Data</A ></H2 ><P > These functions are used to receive data during <TT CLASS="LITERAL" >COPY TO STDOUT</TT >. They will fail if called when the connection is not in <TT CLASS="LITERAL" >COPY_OUT</TT > state. </P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><A NAME="LIBPQ-PQGETCOPYDATA" ></A ><CODE CLASS="FUNCTION" >PQgetCopyData</CODE > </DT ><DD ><P > Receives data from the server during <TT CLASS="LITERAL" >COPY_OUT</TT > state. </P><PRE CLASS="SYNOPSIS" >int PQgetCopyData(PGconn *conn, char **buffer, int async);</PRE ><P> </P ><P > Attempts to obtain another row of data from the server during a <TT CLASS="COMMAND" >COPY</TT >. Data is always returned one data row at a time; if only a partial row is available, it is not returned. Successful return of a data row involves allocating a chunk of memory to hold the data. The <TT CLASS="PARAMETER" >buffer</TT > parameter must be non-<TT CLASS="SYMBOL" >NULL</TT >. <TT CLASS="PARAMETER" >*buffer</TT > is set to point to the allocated memory, or to <TT CLASS="SYMBOL" >NULL</TT > in cases where no buffer is returned. A non-<TT CLASS="SYMBOL" >NULL</TT > result buffer should be freed using <CODE CLASS="FUNCTION" >PQfreemem</CODE > when no longer needed. </P ><P > When a row is successfully returned, the return value is the number of data bytes in the row (this will always be greater than zero). The returned string is always null-terminated, though this is probably only useful for textual <TT CLASS="COMMAND" >COPY</TT >. A result of zero indicates that the <TT CLASS="COMMAND" >COPY</TT > is still in progress, but no row is yet available (this is only possible when <TT CLASS="PARAMETER" >async</TT > is true). A result of -1 indicates that the <TT CLASS="COMMAND" >COPY</TT > is done. A result of -2 indicates that an error occurred (consult <CODE CLASS="FUNCTION" >PQerrorMessage</CODE > for the reason). </P ><P > When <TT CLASS="PARAMETER" >async</TT > is true (not zero), <CODE CLASS="FUNCTION" >PQgetCopyData</CODE > will not block waiting for input; it will return zero if the <TT CLASS="COMMAND" >COPY</TT > is still in progress but no complete row is available. (In this case wait for read-ready and then call <CODE CLASS="FUNCTION" >PQconsumeInput</CODE > before calling <CODE CLASS="FUNCTION" >PQgetCopyData</CODE > again.) When <TT CLASS="PARAMETER" >async</TT > is false (zero), <CODE CLASS="FUNCTION" >PQgetCopyData</CODE > will block until data is available or the operation completes. </P ><P > After <CODE CLASS="FUNCTION" >PQgetCopyData</CODE > returns -1, call <CODE CLASS="FUNCTION" >PQgetResult</CODE > to obtain the final result status of the <TT CLASS="COMMAND" >COPY</TT > command. One can wait for this result to be available in the usual way. Then return to normal operation. </P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-COPY-DEPRECATED" >31.9.3. Obsolete Functions for <TT CLASS="COMMAND" >COPY</TT ></A ></H2 ><P > These functions represent older methods of handling <TT CLASS="COMMAND" >COPY</TT >. 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. </P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><A NAME="LIBPQ-PQGETLINE" ></A ><CODE CLASS="FUNCTION" >PQgetline</CODE > </DT ><DD ><P > Reads a newline-terminated line of characters (transmitted by the server) into a buffer string of size <TT CLASS="PARAMETER" >length</TT >. </P><PRE CLASS="SYNOPSIS" >int PQgetline(PGconn *conn, char *buffer, int length);</PRE ><P> </P ><P > This function copies up to <TT CLASS="PARAMETER" >length</TT >-1 characters into the buffer and converts the terminating newline into a zero byte. <CODE CLASS="FUNCTION" >PQgetline</CODE > returns <TT CLASS="SYMBOL" >EOF</TT > at 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. </P ><P > Note that the application must check to see if a new line consists of the two characters <TT CLASS="LITERAL" >\.</TT >, which indicates that the server has finished sending the results of the <TT CLASS="COMMAND" >COPY</TT > command. If the application might receive lines that are more than <TT CLASS="PARAMETER" >length</TT >-1 characters long, care is needed to be sure it recognizes the <TT CLASS="LITERAL" >\.</TT > line correctly (and does not, for example, mistake the end of a long data line for a terminator line). </P ></DD ><DT ><A NAME="LIBPQ-PQGETLINEASYNC" ></A ><CODE CLASS="FUNCTION" >PQgetlineAsync</CODE > </DT ><DD ><P > Reads a row of <TT CLASS="COMMAND" >COPY</TT > data (transmitted by the server) into a buffer without blocking. </P><PRE CLASS="SYNOPSIS" >int PQgetlineAsync(PGconn *conn, char *buffer, int bufsize);</PRE ><P> </P ><P > This function is similar to <CODE CLASS="FUNCTION" >PQgetline</CODE >, but it can be used by applications that must read <TT CLASS="COMMAND" >COPY</TT > data asynchronously, that is, without blocking. Having issued the <TT CLASS="COMMAND" >COPY</TT > command and gotten a <TT CLASS="LITERAL" >PGRES_COPY_OUT</TT > response, the application should call <CODE CLASS="FUNCTION" >PQconsumeInput</CODE > and <CODE CLASS="FUNCTION" >PQgetlineAsync</CODE > until the end-of-data signal is detected. </P ><P > Unlike <CODE CLASS="FUNCTION" >PQgetline</CODE >, this function takes responsibility for detecting end-of-data. </P ><P > On each call, <CODE CLASS="FUNCTION" >PQgetlineAsync</CODE > will return data if a complete data row is available in <SPAN CLASS="APPLICATION" >libpq</SPAN >'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 <CODE CLASS="FUNCTION" >PQendcopy</CODE >, and then return to normal processing. </P ><P > 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 <TT CLASS="LITERAL" >\n</TT > or not. (In a binary <TT CLASS="COMMAND" >COPY</TT >, actual parsing of the <TT CLASS="COMMAND" >COPY</TT > data 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 <TT CLASS="PARAMETER" >bufsize</TT > one smaller than the room actually available.) </P ></DD ><DT ><A NAME="LIBPQ-PQPUTLINE" ></A ><CODE CLASS="FUNCTION" >PQputline</CODE > </DT ><DD ><P > Sends a null-terminated string to the server. Returns 0 if OK and <TT CLASS="SYMBOL" >EOF</TT > if unable to send the string. </P><PRE CLASS="SYNOPSIS" >int PQputline(PGconn *conn, const char *string);</PRE ><P> </P ><P > The <TT CLASS="COMMAND" >COPY</TT > data stream sent by a series of calls to <CODE CLASS="FUNCTION" >PQputline</CODE > has the same format as that returned by <CODE CLASS="FUNCTION" >PQgetlineAsync</CODE >, except that applications are not obliged to send exactly one data row per <CODE CLASS="FUNCTION" >PQputline</CODE > call; it is okay to send a partial line or multiple lines per call. </P ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B > Before <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > protocol 3.0, it was necessary for the application to explicitly send the two characters <TT CLASS="LITERAL" >\.</TT > as a final line to indicate to the server that it had finished sending <TT CLASS="COMMAND" >COPY</TT > data. While this still works, it is deprecated and the special meaning of <TT CLASS="LITERAL" >\.</TT > can be expected to be removed in a future release. It is sufficient to call <CODE CLASS="FUNCTION" >PQendcopy</CODE > after having sent the actual data. </P ></BLOCKQUOTE ></DIV ></DD ><DT ><A NAME="LIBPQ-PQPUTNBYTES" ></A ><CODE CLASS="FUNCTION" >PQputnbytes</CODE > </DT ><DD ><P > Sends a non-null-terminated string to the server. Returns 0 if OK and <TT CLASS="SYMBOL" >EOF</TT > if unable to send the string. </P><PRE CLASS="SYNOPSIS" >int PQputnbytes(PGconn *conn, const char *buffer, int nbytes);</PRE ><P> </P ><P > This is exactly like <CODE CLASS="FUNCTION" >PQputline</CODE >, 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. </P ></DD ><DT ><A NAME="LIBPQ-PQENDCOPY" ></A ><CODE CLASS="FUNCTION" >PQendcopy</CODE > </DT ><DD ><P > Synchronizes with the server. </P><PRE CLASS="SYNOPSIS" >int PQendcopy(PGconn *conn);</PRE ><P> 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 <CODE CLASS="FUNCTION" >PQputline</CODE > or when the last string has been received from the server using <CODE CLASS="FUNCTION" >PGgetline</CODE >. It must be issued or the server will get <SPAN CLASS="QUOTE" >"out of sync"</SPAN > 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 <CODE CLASS="FUNCTION" >PQerrorMessage</CODE > to retrieve details if the return value is nonzero.) </P ><P > When using <CODE CLASS="FUNCTION" >PQgetResult</CODE >, the application should respond to a <TT CLASS="LITERAL" >PGRES_COPY_OUT</TT > result by executing <CODE CLASS="FUNCTION" >PQgetline</CODE > repeatedly, followed by <CODE CLASS="FUNCTION" >PQendcopy</CODE > after the terminator line is seen. It should then return to the <CODE CLASS="FUNCTION" >PQgetResult</CODE > loop until <CODE CLASS="FUNCTION" >PQgetResult</CODE > returns a null pointer. Similarly a <TT CLASS="LITERAL" >PGRES_COPY_IN</TT > result is processed by a series of <CODE CLASS="FUNCTION" >PQputline</CODE > calls followed by <CODE CLASS="FUNCTION" >PQendcopy</CODE >, then return to the <CODE CLASS="FUNCTION" >PQgetResult</CODE > loop. This arrangement will ensure that a <TT CLASS="COMMAND" >COPY</TT > command embedded in a series of <ACRONYM CLASS="ACRONYM" >SQL</ACRONYM > commands will be executed correctly. </P ><P > Older applications are likely to submit a <TT CLASS="COMMAND" >COPY</TT > via <CODE CLASS="FUNCTION" >PQexec</CODE > and assume that the transaction is done after <CODE CLASS="FUNCTION" >PQendcopy</CODE >. This will work correctly only if the <TT CLASS="COMMAND" >COPY</TT > is the only <ACRONYM CLASS="ACRONYM" >SQL</ACRONYM > command in the command string. </P ></DD ></DL ></DIV ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="libpq-notify.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="libpq-control.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Asynchronous Notification</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="libpq.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Control Functions</TD ></TR ></TABLE ></DIV ></BODY ></HTML >