PostgreSQL-libpq-与COPY 命令相关的函数

postgres_fan

http://www.wohedb.com/db_html_doc/libpq_api/libpq_7_copy.htm
http://www.wohedb.com  中文数据库管理系统

1.7 与COPY 命令相关的函数
    客户端可以使用COPY命令同服务器交换大量的数据。Libpq提供了相关的函数来实现这个功能。



    应用程序首先用PQexec或其它函数发一个SQL COPY命令给服务器，PQexec返回的PGresult对象的状态应该是PGRES_COPY_OUT或PGRES_COPY_IN。然后应用程序调用后面介绍的函数向服务器发送数据或者从服务器接收数据。当所有的数据都传送完毕后，服务器会返回另外一个PGresult对象，如果COPY命令执行成功，这个PGresult对象的状态PGRES_COMMAND_OK，如果COPY命令执行失败，这个PGresult对象的状态PGRES_COMMAND_ERROR。当一个数据库连接上有COPY命令正在执行的时候，不能在该连接上发送其它的SQL命令给服务器执行，只有在COPY命令执行结束以后，才能执行其它的SQL命令。



    只有在函数PQexec或PQgetResult返回的结果状态是PGRES_COPY_OUT或PGRES_COPY_IN的条件下，才能执行本节介绍的函数。发送SQL COPY命令的函数PQexec返回的PGresult对象还包含其它的与COPY命令有关的信息，可以用下面的两个函数得到这些信息：



PQnfields

返回数据行中列的个数。



PQbinaryTuples

0表示以文本格式传递数据。1表示以二进制格式传递数据。



1.7.1 向服务器发送数据的函数
    在使用COPY FROM STDIN从客户端发送数据到服务器时，客户端使用下面的函数来传送数据。只有在数据库连接的状态是COPY_IN的时候，才能调用这些函数。



PQputCopyData

发送数据给服务器，数据库连接的状态必须是COPY_IN。



        int PQputCopyData(PGconn *conn,
                          const char *buffer,
                          int nbytes);
      
参数buffer指向存放被发送的数据的缓冲区。参数nbytes是被发送的数据的长度，单位是字节。函数返回1表示数据成功地发送给服务器。函数返回0表示没有发送数据因为客户端会进入等待状态（只有在连接是非阻塞状模式时才会出现这种情况），在这种情况下，应该等待一段时间后，重新调用这个函数发送数据。函数返回-1表示遇到错误（调用PQerrorMessage得到详细的错误信息）。



PQputCopyEnd

通知服务器所有的数据都发送完毕，数据库连接的状态必须是COPY_IN。



        int PQputCopyEnd(PGconn *conn,
                         const char *errormsg);
      
如果参数errormsg的值是NULL，函数告诉服务器所有的数据都传送完毕。如果参数errormsg的值不是NULl，函数告诉服务器，传送操作遇到错误，必须终止传送操作，用errormsg指向的字符串作为错误消息。要注意的是，如果传送操作执行失败，服务器返回的错误消息不一定是errormsg指向的错误消息，因为服务器可能在收到errormsg指向的错误消息以前已经遇到了其它的错误，主动终止了传递操作。



函数返回1表示通知成功地发送给服务器。函数返回0表示没有通知给数据库因为客户端会进入等待状态（只有在连接是非阻塞状模式时才会出现这种情况），在这种情况下，应该等待一段时间后，重新调用这个函数发通知给数据库。函数返回-1表示遇到错误（调用PQerrorMessage得到详细的错误信息）。



成功地调用PQputCopyEnd以后，应该调用PQgetResult得到COPY命令的最终结果。



1.7.2 从服务器接收数据的函数
    在使用COPY TO STDOUT从服务器发送数据到客户端时，客户端使用下面的函数来接收数据。只有在数据库连接的状态是COPY_OUT的时候，才能调用这个函数。



PQgetCopyData

从服务器那里接收数据，数据库连接的状态必须是COPY_OUT。



        int PQgetCopyData(PGconn *conn,
                          char **buffer,
                          int async);
      
每次调用这个函数只能得到一个数据行。参数buffer的值不能是NULL。*buffer指向存放得到的数据行的缓冲区，如果没有得到任何数据行，*buffer的值将是NULL。不再使用*buffer指向的缓冲区中的数据时，应该使用Pqfreemem释放缓冲区占用的内存。



如果成功地得到一个数据行，函数的返回值是数据行的大小，单位是字节。返回的数据行存放在*buffer指向的缓冲区里，末尾会被自动加上字符\0。返回值是0表示 COPY命令仍在执行，但还没有返回任何数据行（只有在参数async的值为真的情况下，才可能会返回0）。返回-1表示COPY命令执行结束。返回值是-2表示遇到错误（调用PQerrorMessage得到详细的错误信息）。



如果参数async的值为真（非零），PQgetCopyData如果不能立即得到数据，它不会进入等待状态，而是返回0,在这种情况下，应该等待一段时间后，先调用PQconsumeInput，然后再次调用PQgetCopyData。如果参数async的值为0，PQgetCopyData如果不能立即得到数据，它会进入等待状态，直到服务器返回一个数据行或者COPY命令执行结束。



如果PQgetCopyData 返回-1，应该调用PQgetResult 得到COPY命令的最终执行结果。