El comando COPY en PostgreSQL tiene opciones para leer o escribir en la conexi�n de red utilizada para libpq. Por ello, se necesitan funciones para acceder a su conexi�n de red directamente, de forma que las aplicaciones puedan obtener ventajas de esta capacidad.
Estas funciones s�lo se deber�an utilizar tras obtener un objeto resultado PGRES_COPY_OUT o PGRES_COPY_IN a partir de PQexec o PQgetResult.
PQgetline Lee una l�nea de caracteres terminada con un caracter "newline" (transmitida por el servidor) en una cadena de almacenamiento de tama�o "length".
int PQgetline(PGconn *conn, char *string, int length) |
Observese que la aplicaci�n deber� comprobar si la nueva l�nea consiste en los dos car�cteres "\.", lo que indicar�a que el servidor ha terminado de enviar los resultados del comando copy. Si la aplicaci�n deber�a recibir l�neas que son m�s largas de longitud-1, deber� tener cuidado de reconocer la l�nea "\." correctamente (y no confunde, por ejemplo, el final de una larga l�nea de datos con la l�nea de terminaci�n). El c�digo de src/bin/psql/copy.c contiene rutinas de ejemplo que manipulan correctamente el protocolo copy.
PQgetlineAsync Lee una l�nea de car�cteres terminada con "newline" (transmitida por el servidor) en una zona de almacenamiento sin bloquear.
int PQgetlineAsync(PGconn *conn, char *buffer, int bufsize) |
La rutina devuelve -1 si reconoce el marcador end-of-copy-data, 0 si no tiene datos disponibles, o un n�mero positivo que la el n�mero de bytes de datos devueltos. Si se devuelve -1, la aplicaci�n que realiza la llamada deber� llamar a PQendcopy, y volver despu�s al procesado normal. Los datos devueltos no se extender�n m�s all� de un car�cter "newline". Si es posible, se devolver� una l�nea completa cada vez. Pero si el almacenamiento ofrecido por la aplicaci�n que realiza la llamada es demasiado peque�o para recibir una l�nea enviada por el servidor, se devolver�n datos parciales. Se puede detectar esto comprobando si el �ltimo byte devuelto es "\n" o no. La cadena devuelta no se termina con un car�cter nulo. (Si quiere usted a�adir un NULL de terminaci�n, asegurese de pasar una longitud del almacenamiento m�s peque�a que el tama�o del almacenamiento de que realmente dispone).
PQputline Env�a una cadena terminada en car�cter nulo al servidor. Devuelve 0 si todo funciona bien, y EOF si es incapaz de enviar la cadena.
int PQputline(PGconn *conn, const char *string); |
PQputnbytes Env�a una cadena terminada en un car�cter no nulo al servidor. Devuelve 0 si todo va bien, y EOF si es incapaz de enviar la cadena.
int PQputnbytes(PGconn *conn, const char *buffer, int nbytes); |
PQendcopy Sincroniza con el servidor. Esta funci�n espera hasta que el servidor ha terminado la copia. Deber�a utilizarse bien cuando se ha enviado la �ltima cadena al servidor utilizando PQputline o cuando se ha recibido la �ltima cadena desde el servidor utilizando PGgetline. Debe utilizarse, o el servidor puede recibir "out of sync (fuera de sincron�a)" con el cliente. Una vez vuelve de esta funci�n, el servidor est� preparado para recibir la siguiente consulta. El valor devuelto es 0 si se completa con �xito, o diferente de cero en otro caso.
int PQendcopy(PGconn *conn); |
Como un ejemplo:
PQexec(conn, "create table foo (a int4, b char(16), d float8)"); PQexec(conn, "copy foo from stdin"); PQputline(conn, "3\thello world\t4.5\n"); PQputline(conn,"4\tgoodbye world\t7.11\n"); ... PQputline(conn,"\\.\n"); PQendcopy(conn); |
Cuando se est� utilizando PQgetResult, la aplicaci�n deber�a responder a un resultado PGRES_COPY_OUT ejecutando repetidamente PQgetline, seguido de PQendcopy una vez se detecta la l�nea de terminaci�n. Deber�a entonces volver al bucle PQgetResult loop until hasta que PQgetResult devuelva NULL. Similarmente, un resultado PGRES_COPY_IN se procesa por una serie de llamadas a PQputline seguidas por PQendcopy, y volviendo entonces al bucle PQgetResult. Esta organizaci�n asegurar� que un comando de copia de entrada o de salida embebido en una serie de comandos SQL se ejecutar� correctamente.
Las aplicaciones antiguas habitualmente emiten una copia de entrada o de salida a trav�s de PQexec y asumen que la transacci�n ha terminado tras el PQendcopy. Este mecanismo trabajar� adecuadamente s�lo si la copia de entrada/salida es el �nico comando SQL de la cadena de consulta.