Funciones de Ejecución de Consultas

Una vez que se ha establecido correctamente una conexión con un servidor de base de datos, se utilizan las funciones que se muestran a continuación para realizar consultas y comandos de SQL.

• PQexec Emite una consulta a Postgres y espera el resultado.

  PGresult *PQexec(PGconn *conn, const char *query);

  Devuelve un puntero PGresult o, posiblemente, un puntero NULL. Generalmente devolverá un puntero no nulo, excepto en condiciones de "fuera de memoria" (out-of-memory) o errores serios tales como la incapacidad de enviar la consulta al servidor. Si se devuelve un puntero nulo, se debería tratar de la misma forma que un resulado PGRES_FATAL_ERROR. Para conseguir más información sobre el error, utilice PQerrorMessage.

La estructura PGresult encapsula el resultado devuelto por el servidor a la consulta. Los programadores de aplicaciones con libpq deberían mostrarse cuidadosos de mantener la abstracción de PGresult. Prohiban la referencia directa a los campos de la estructura PGresult, porque están sujetos a cambios en el futuro. (Incluso a partir de la versión 6.4 de Postgres, ha dejado de proporcionarse la definición de PGresult en libpq-fe.h. Si tiene usted código antíguo que accede directamente a los campos de PGresult, puede mantenerlo utilizando libpq-int.h también, pero le recomendamos que ajuste pronto el código).

• PQresultStatus Devuelve la situación (status) resultante de una consulta.

  ExecStatusType PQresultStatus(const PGresult *res)

  PQresultStatus puede devolver uno de los siguentes valores:

  • PGRES_EMPTY_QUERY -- La cadena enviada al servidor estaba vacía.

  • PGRES_COMMAND_OK -- El comando se ha ejecutado con éxito sin devolver datos.

  • PGRES_TUPLES_OK -- La consulta se ha ejecutado con éxito.

  • PGRES_COPY_OUT -- Se ha arrancado la transmisión de datos desde el servidor (Copy Out)

  • PGRES_COPY_IN -- Se ha arrancado la transmisión de datos hacia el servidor (Copy In)

  • PGRES_BAD_RESPONSE -- El servidor ha dado una respuesta desconocida.

  • PGRES_NONFATAL_ERROR

  • PGRES_FATAL_ERROR

  Si al situación del resultado es PGRES_TUPLES_OK, las rutinas descritas más abajo se pueden utilizar para recuperar las tuplas devueltas por la consulta. Tengase en cuenta que una SELECT que intente recuperar 0 (cero) tuplas también mostrará PGRES_TUPLES_OK. PGRES_COMMAND_OK es para comandos que nunca devuelven tuplas (INSERT, UPDATE, etc). Una respuesta PGRES_EMPTY_QUERY indica que hay un error en el programa cliente.

• PQresStatus Convierte los tipos enumerados devueltos por PQresultStatus en una cadena constante que describe el código de la situación.

  char *PQresStatus(ExecStatusType status);

• PQresultErrorMessage Devuelve el mensaje de error asociado con la consulta, o una cadena vacía si no hay error.

  char *PQresultErrorMessage(const PGresult *res);

  Siguiendo inmediatamente a una llamada a PQexec o PQgetResult, PQerrorMessage (sobre la conexión) devolverá la misma cadena que PQresultErrorMessage (sobre el resultado). Sin embargo, un PGresult mantendrá su mensaje de error hasta que sea destruido, mientras que el mensaje de error de la conexión cambiará cuando se realicen subsiguientes operaciones. Utilice PQresultErrorMessage cuando quiera conocer la situación asociada a un PGresult particular; utilice PQerrorMessage cuando quiera conocer la situación de la última operación en la conexión.

• PQntuples Devuelve el númerod de tuplas (instancias) del resultado de la consulta.

  int PQntuples(const PGresult *res);

• PQnfields Devuelve el número de campos (atributos) de cada tupla del resultado de la consulta.

  int PQnfields(const PGresult *res);

• PQbinaryTuples Devuelve 1 si PGresult contiene datos binarios en las tuplas, y 0 si contiene datos ASCII.

  int PQbinaryTuples(const PGresult *res);

  Actualmente, los datos binarios de las tuplas solo los puede recuperar una consulta que extraiga datos de un cursor BINARY.

• PQfname Devuelve el nombre del campo (atributo) asociado con el indice de campo dado. Los índices de campo empiezan con 0.

  char *PQfname(const PGresult *res, int field_index);

• PQfnumber Devuelve el índice del campo (atributo) asociado con el nombre del campo dado.

  int PQfnumber(const PGresult *res, const char *field_name);

  Se devuelve -1 si el nombre de campo dado no se corresponde con ningún campo.

• PQftype Devuelve el tipo de campo asociado con el índice del campo dado. El entero devuelto es una codificación interna del tipo. Los índices de campo empiezan con 0.

  Oid PQftype(const PGresult *res, int field_num);

  Puede usted consultar la tabla de sistema pg_type para obtener el nombre y propiedades de los diferentes tipos de datos. Los OID,s de los tipos de datos incluidos por defecto están definidos en src/include/catalog/pg_type.h, en el árbol de fuentes del producto.

• PQfsize Devuelve el tamaño en bytes del campo asociado con el índice de campo dado. Los índices de campo empiezan con 0.

  int PQfsize(const PGresult *res, int field_index);

  Qfsize devuelve el espacio reservado para este campo en una tupla de base de datos, en otras palabras, el tamaño de la representación binaria del tipo de datos en el servidor. Se devuelve -1 si el campo es de tamaño variable.

• PQfmod Devuelve los datos de la modificación específica del tipo del campo asociado con el índice del campo dado. Los índices de campo empiezan en 0.

  int PQfmod(const PGresult *res, int field_index);

• PQgetvalue Devuelve un valor de un único campo (atributo) de una tupla de PGresult. Los índices de tuplas y de campos empiezan con 0.

  char* PQgetvalue(const PGresult *res, int tup_num, int field_num);

  Para la mayoría de las consultas, el valor devuelto por PQgetvalue es una cadena ASCII terminada en un valor NULL que representa el valor del atributo. Pero si el valor de PQbinaryTuples() es 1, es valor que devuelve PQgetvalue es la representación binaria del tipo en el formato interno del servidor (pero no incluye la palabra del tamaño, si el campo es de longitud variable). Es entonces responsabilidad del programador interpretar y convertir los datos en el tipo C correcto. El puntero devuelto por PQgetvalue apunta a una zona de almacenaje que forma parte de la estructura PGresult. No se la debería modificar, sino que se debería copiar explicitamente el valor a otra estructura de almacenamiento si se pretende utilizar una vez pasado el tiempo de vida de la estructura PGresult misma.

• PQgetlength Devuelve la longitud de un campo (atributo) en bytes. Los índices de tupla y de campo empiezan en 0.

  int PQgetlength(const PGresult *res, int tup_num, int field_num);

  Esta es la longitud de los datos actuales para el valor de datos particular, es decir, el tamaño del objeto apuntado por PQgetvalue. Notese que para valores representados en ASCII, este tamaño tiene poco que ver con el tamaño binario indicado por PQfsize.

• PQgetisnull Prueba un campo por si tiene un valor NULL. Los índices de tupla y de campo empiezan con 0.

  int PQgetisnull(const PGresult *res, int tup_num, int field_num);

  Esta función devuelve 1 si el campo contiene un NULL, o 0 si contiene un valor no nulo.(Tenga en cuenta que PQgetvalue devolverá una cadena vacía, no un puntero nulo, para un campo NULL).

• PQcmdStatus Devuelve la cadena de la situación del comando para el comando SQL que generó el PGresult.

  char * PQcmdStatus(const PGresult *res);

• PQcmdTuples Devuelve el número de filas afectadas por el comando SQL.

  char * PQcmdTuples(const PGresult *res);

  Si el comando SQL que generó el PGresult era INSERT, UPDATE o DELETE, devolverá una cadena que contiene el número de filas afectadas. Si el comando era cualquier otro, devolverá una cadena vacía.

• PQoidValue Devuelve el identificador de objeto (oid) de la tupla insertada, si el comando SQL era una INSERT. En caso contrario, devuelve InvalidOid.

  Oid PQoidValue(const PGresult *res);

  Tanto el tipo Oid como la constante Invalid se definirán cuando incluya usted el fichero de cabeceras libpq. Ambos serán de tipo entero (integer).

• PQoidStatus Devuelve una cadena con el identificador de objeto de la tupla insertada si el comando SQL era una INSERT. En otro caso devuelve una cadena vacía.

  char * PQoidStatus(const PGresult *res);

  Esta función se ha despreciado en favor de PQoidValue y no asegura la hebra.

• PQprint Imprime todas las tuplas y, opcionalmente, los nombres de los atributos en la salida especificada.

  void PQprint(FILE* fout, /* output stream */ const PGresult *res, const PQprintOpt *po); struct { pqbool header; /* Imprime las cabeceras de los campos de salida y el contador de filas. */ pqbool align; /* Fija la alineación de los campos. */ pqbool standard; /* old brain dead format */ pqbool html3; /* tabula la salida en html */ pqbool expanded; /* expande las tablas */ pqbool pager; /* Usa el paginador para la salida si se necesita. */ char *fieldSep; /* separador de campos */ char *tableOpt; /* lo inserta en <tabla ...> de HTML */ char *caption; /* HTML <caption> */ char **fieldName; /* cadena terminada en null de nombres de campo alternativos. */ } PQprintOpt;

  psql utilizaba anteriormente esta función para imprimir los resultados de las consultas, pero este ya no es el caso, y esta función ya no se soporta activamente.

• PQclear Libera la zona de almacenamiento asociada con PGresult. Todas los resultados de las consultas deberían liberarse con PQclear cuando ya no son necesarios.

  void PQclear(PQresult *res);

  Puede usted conserar un objeto PGresult tanto tiempo como lo necesite; no se conservará si realiza una nueva consulta, e incluso si se pierde la conexión. Para evitar esto, debe usted llamar a PQclear. No hacerlo, repercute en pérdidas de memoria en la aplicación cliente.

• PQmakeEmptyPGresult Construye un objeto PGresult vacío con la situación que se propone.

  PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

  Esta es una rutina interna de libpq para reservar e inicializar un objeto PGresult vacío. Está exportada porque algunas aplicaciones consideran interesante generar objetos resultado (particularmente objetos con situaciones de error) por si mismas. Si conn no es NULL y status indica un error, el mensaje de error (errorMessage) de la conexión en curso se copia en el PGresult. Recuerde que debería llamar a PQclear para este objeto también, del mismo modo que para un PGresult devuelto por la libpq misma.