27.3. Funções de execução de comando

Submete um comando ao servidor e aguarda pelo resultado.

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

Retorna um ponteiro para PGresult, ou um ponteiro nulo. Geralmente é retornado um ponteiro não nulo, exceto nas condições de falta de memória ou erros graves, como a impossibilidade de enviar o comando para o servidor. Caso seja retornado um ponteiro nulo, este deve ser tratado como um resultado PGRES_FATAL_ERROR. Deve ser utilizada a função PQerrorMessage para obter informações adicionais sobre erros deste tipo.

Submete um comando ao servidor e aguarda pelo resultado, com a capacidade de passar parâmetros separadamente do texto do comando SQL.

PGresult *PQexecParams(PGconn *conn,
                       const char *command,
                       int nParams,
                       const Oid *paramTypes,
                       const char * const *paramValues,
                       const int *paramLengths,
                       const int *paramFormats,
                       int resultFormat);

A função PQexecParams é semelhante à função PQexec, mas oferece uma funcionalidade adicional: os valores dos parâmetros podem ser especificados separadamente da cadeia de caracteres do comando, e pode ser solicitado que o resultado do comando retorne no modo texto ou binário. A função PQexecParams é suportada apenas pelas conexões que utilizam o protocolo 3.0 ou mais recente; falha quando é utilizado o protocolo 2.0.

Quando são utilizados parâmetros, estes são referenciados na cadeia de caracteres do comando como $1, $2, etc. nParams é o número de parâmetros fornecidos; é o comprimento das matrizes paramTypes[], paramValues[], paramLengths[] e paramFormats[] (Os ponteiros para as matrizes podem ser NULL quando nParams for zero). paramTypes[] especifica, por OID, os tipos de dado a serem atribuídos aos símbolos dos parâmetros. Se paramTypes for NULL, ou algum determinado elemento da matriz for zero, o servidor atribui o tipo de dado para o símbolo do parâmetro da mesma maneira que faria para um literal cadeia de caracteres sem tipo. paramValues[] especifica os valores dos parâmetros. Nesta matriz um ponteiro nulo significa que o parâmetro correspondente é nulo; senão o ponteiro aponta para uma cadeia de caracteres de texto terminada por zero (para o formato texto), ou dados binários no formato esperado pelo servidor (para formato binário). paramLengths[] especifica o comprimento dos dados dos parâmetros com formato binário. É ignorado para parâmetros nulos e parâmetros com formato texto. O ponteiro para a matriz pode ser nulo quando não há parâmetros binários. paramFormats[] especifica se os parâmetros são do tipo texto (colocando-se o valor zero na matriz), ou binário (colocando-se o valor um na matriz). Se o ponteiro para a matriz for nulo, presume-se que todos os parâmetros sejam do tipo texto. resultFormat é zero para os resultados serem recebidos no formato texto, ou um para os resultados serem recebidos no formato binário (Atualmente não há como receber colunas de resultado diferentes com formatos diferentes, embora isto seja possível no protocolo subjacente).

Submete uma solicitação para criar uma declaração preparada com os parâmetros fornecidos, e aguarda completar.

PGresult *PQprepare(PGconn *conn,
                    const char *stmtName,
                    const char *query,
                    int nParams,
                    const Oid *paramTypes);

A função PQprepare cria uma declaração preparada para execução posterior através de PQexecPrepared. Esta funcionalidade permite que comandos a serem utilizados repetidas vezes sejam analisados e planejados somente uma vez, em vez de cada vez que são utilizados. A função PQprepare é suportada apenas pelas conexões que utilizam o protocolo 3.0 ou mais recente; falha quando é utilizado o protocolo 2.0.

Esta função cria uma declaração preparada chamada stmtName a partir da cadeia de caracteres query, que deve conter um único comando SQL. stmtName pode ser igual a "" para ser criada uma declaração sem nome, caso em que uma declaração sem nome pré-existente é substituída automaticamente; de outra forma, ocasiona erro se o nome da declaração já estiver definida na sessão corrente. Se for usado algum parâmetro, estes devem ser referenciados no comando como $1, $2, etc. nParams é o número de parâmetros para os quais os tipos são previamente especificados na matriz paramTypes[] (O ponteiro para a matriz pode ser nulo quando NULL quando nParams for zero). paramTypes[] especifica, por OID, os tipos de dado a serem atribuídos aos símbolos dos parâmetros. Se paramTypes for NULL, ou algum determinado elemento da matriz for zero, o servidor atribui o tipo de dado para o símbolo do parâmetro da mesma maneira que faria para um literal cadeia de caracteres sem tipo. Além disso, o comando pode utilizar símbolos de parâmetro com números maiores que nParams; os tipos de dado para estes símbolos também serão inferidos.

Da mesma forma que na função PQexec, o resultado normalmente é um objeto PGresult cujo conteúdo indica sucesso ou falha do lado servidor. Um resultado nulo indica falta de memória ou incapacidade enviar o comando. Deve ser utilizada a função PQerrorMessage para obter mais informações sobre erros deste tipo.

No presente momento não há nenhuma forma de determinar o verdadeiro tipo de dado inferido para qualquer parâmetro cujo tipo não foi especificado através de paramTypes[]. Esta é uma omissão da libpq que, provavelmente, será corrigida em uma versão futura.

Envia uma solicitação para executar uma declaração preparada com determinados parâmetros, e aguarda pelo resultado.

PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);

A função PQexecPrepared é semelhante à função PQexecParams, mas o comando a ser executado é especificado fornecendo-se o nome de uma declaração previamente preparada, em vez de fornecer a cadeia de caracteres do comando. Esta funcionalidade permite que comandos a serem utilizados repetidas vezes sejam analisados e planejados somente uma vez, em vez de cada vez que são utilizados. A declaração deve ter sido preparada anteriormente na sessão corrente. A função PQprepare é suportada apenas pelas conexões que utilizam o protocolo 3.0 ou mais recente; falha quando é utilizado o protocolo 2.0.

Os parâmetros são idênticos aos da função PQexecParams, exceto que é fornecido o nome da declaração preparada em vez da cadeia de caracteres do comando, e o parâmetro paramTypes[] não está presente (não é necessário, uma vez que os tipos dos parâmetros da declaração preparada foram determinados quando esta foi criada).

Retorna o status do resultado do comando.

ExecStatusType PQresultStatus(const PGresult *res);

A função PQresultStatus pode retornar um dos seguintes valores:

Se o status do resultado for PGRES_TUPLES_OK, então podem ser utilizadas as funções descritas abaixo para obter as linhas retornadas pela consulta. Deve ser observado que um comando SELECT que não retorna nenhuma linha ainda assim mostra PGRES_TUPLES_OK. PGRES_COMMAND_OK é utilizado em comandos que nunca retornam linhas (INSERT, UPDATE, etc.). Uma resposta do tipo PGRES_EMPTY_QUERY pode indicar um erro no programa cliente.

Um resultado com o status PGRES_NONFATAL_ERROR nunca será retornado diretamente por PQexec ou outra função de execução de comandos; em vez disso, os resultados deste tipo são passados para o processador de observações (consulte a Seção 27.10).

Converte o tipo enumerado retornado pela função PQresultStatus em uma constante cadeia de caracteres que descreve o código do status. Quem chama não deve liberar o resultado.

char *PQresStatus(ExecStatusType status);

Retorna a mensagem de erro associada ao comando, ou uma cadeia de caracteres vazia caso não tenha havido erro.

char *PQresultErrorMessage(const PGresult *res);

Caso tenha havido um erro, a cadeia de caracteres retornada inclui um caractere de nova-linha no final. Quem chama não deve liberar o resultado diretamente. O resultado será liberado quando o tratador PGresult associado for passado para a função PQclear.

Uma chamada a PQerrorMessage imediatamente após a chamada a PQexec ou PQgetResult (na mesma conexão), retorna a mesma cadeia de caracteres que PQresultErrorMessage (no resultado). Entretanto, a estrutura PGresult retém a mensagem de erro até ser destruída, enquanto a mensagem de erro da conexão muda quando as operações seguintes são realizadas. Deve ser utilizada a função PQresultErrorMessage quando se deseja conhecer o status associado a uma determinada estrutura PGresult; deve ser utilizada a função PQerrorMessage quando se deseja conhecer o status da última operação na conexão.

Retorna um campo individual de um relato de erro.

char *PQresultErrorField(const PGresult *res, int fieldcode);

O parâmetro fieldcode é um identificador de campo de erro; devem ser vistos os símbolos listados abaixo. Retorna NULL quando PGresult não é um resultado de erro ou de advertência, ou não inclui o campo especificado. Os valores dos campos normalmente não incluem o caractere de nova-linha no final. Quem chama não deve liberar o resultado diretamente. O resultado será liberado quando o tratador da estrutura PGresult associado for passado para a função PQclear.

Estão disponíveis os seguintes códigos de campo:

O cliente é responsável pela formatação da informação mostrada, conforme suas necessidades; em particular, as linhas longas devem ser quebradas conforme seja necessário. Os caracteres de nova-linha que aparecem nos campos de mensagem de erro devem ser tratados como quebra de parágrafo, e não como quebra de linha.

As mensagens de erro geradas internamente pela libpq possuem mensagem primária e severidade, mas tipicamente nenhum outro campo. Os erros retornados por um servidor com protocolo pré-3.0 incluem mensagem primária e severidade, e algumas vezes mensagem de detalhe, mas nenhum outro campo.

Deve ser observado que os campos de erro estão disponíveis apenas nos objetos PGresult, e não nos objetos PGconn; não existe nenhuma função chamada PQerrorField.

Libera o armazenamento associado a PGresult. Todo resultado de comando deve ser liberado através de PQclear quando não for mais necessário.

void PQclear(PGresult *res);

O objeto PGresult pode ser mantido pelo tempo que for necessário; não precisa ir embora quando se submete um novo comando, nem mesmo quando se fecha a conexão. Para liberá-lo, deve ser chamada a função PQclear. Caso não seja feito acarreta perda de memória pelo aplicativo.

Constrói um objeto PGresult vazio com o status fornecido.

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

Esta é uma função interna da libpq para alocar e inicializar um objeto PGresult vazio. É exportado porque alguns aplicativos encontram utilidade na geração de objetos de resultado (em particular objetos com status de erro). Se conn não for nulo, e status indica um erro, a mensagem de erro corrente da conexão especificada é copiada para PGresult. Deve ser observado que no final a função PQclear deverá ser chamada para o objeto, da mesma forma que com a estrutura PGresult retornada pela própria libpq.

Retorna o número de linhas (tuplas) presentes no resultado do comando.

int PQntuples(const PGresult *res);

Retorna o número de colunas (campos) de cada linha presente no resultado do comando.

int PQnfields(const PGresult *res);

Retorna o nome da coluna associado a um determinado número de coluna. Os números das colunas começam por zero. Quem chama não deve liberar o resultado diretamente. O resultado é liberado quando o tratador de PGresult associado é passado para a função PQclear.

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

Retorna NULL quando o número da coluna está fora do intervalo.

Retorna o número da coluna associado a um determinado nome de coluna.

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

Retorna -1 se o nome fornecido não corresponder a nenhuma coluna.

O nome fornecido é tratado da mesma maneira que um identificador de um comando SQL, ou seja, as letras são convertidas em minúsculas a menos que estejam entre aspas. Por exemplo, dada a saída da consulta gerada pelo comando SQL

select 1 as FOO, 2 as "BAR";

seriam obtidos os seguintes resultados:

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1

Retorna o OID da tabela da qual a coluna especificada foi trazida. Os números das colunas começam por 0.

Oid PQftable(const PGresult *res,
             int column_number);

Retorna InvalidOid se o número da coluna estiver fora do intervalo, ou se a coluna especificada não for uma referência simples a uma coluna de tabela, ou quando é utilizado um protocolo anterior ao 3.0. Pode ser consultada a tabela pg_class para determinar exatamente qual tabela é referenciada.

O tipo Oid e a constante InvalidOid são definidas quando é incluído o arquivo de cabeçalho da libpq. Ambos serão algum tipo inteiro.

Retorna o número da coluna (dentro de sua tabela), da coluna que produz a coluna de resultado da consulta especificada. Os números de coluna dos resultados das consultas começam por 0, mas as colunas das tabela possuem números diferentes de zero.

int PQftablecol(const PGresult *res,
                int column_number);

Retorna zero se o número da coluna estiver fora do intervalo, ou se a coluna especificada não for uma referência simples a uma coluna de tabela, ou quando é utilizado um protocolo anterior ao 3.0.

Retorna o código do formato que indica o formato de uma determinada coluna. Os números das colunas começam por 0.

int PQfformat(const PGresult *res,
              int column_number);

Código de forma zero indica representação textual dos dados, enquanto o código de formato um indica representação binária (os outros códigos estão reservados para definições futuras).

Retorna o tipo de dado associado com o número de coluna especificado. O inteiro retornado é o número de OID interno do tipo. Os números de coluna começam por 0.

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

Pode ser consultada a tabela do sistema pg_type para obter os nomes e propriedades de vários tipos de dado. Os OIDs dos tipos de dado nativos estão definidos no arquivo src/include/catalog/pg_type.h na árvore do código fonte.

Retorna o modificador de tipo da coluna associada com o número de coluna especificado. Os números de coluna começam por 0.

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

A interpretação dos valores de modificador é específica do tipo; tipicamente indicam os limites de precisão ou de tamanho. O valor -1 é utilizado para indicar "nenhuma informação disponível". A maior parte dos tipos de dado não utilizam modificadores, e neste caso o valor é sempre -1.

Retorna o tamanho, em bytes, da coluna associada ao número de coluna especificado. Os números de coluna começam por 0.

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

A função PQfsize retorna o espaço alocado para esta coluna na linha do banco de dados ou, em outras palavras, o tamanho da representação interna do servidor do tipo de dado (Na verdade, não é muito útil para os clientes). Um valor negativo indica que o tipo de dado é de tamanho variável.

Retorna 1 se a estrutura PGresult contém dados binários, e 0 se contém dados na forma de texto.

int PQbinaryTuples(const PGresult *res);

Esta função está em obsolescência (exceto para uso na conexão com COPY), porque é possível que uma única estrutura PGresult contenha dados na forma de texto para algumas colunas, e dados binários em outras colunas. É preferida a função PQfformat. A função PQbinaryTuples retorna 1 somente se todas as colunas do resultado forem binárias (formato 1).

Retorna um único valor de campo de uma linha de PGresult. Os números das linhas e das colunas começam por 0. Quem chama não deve liberar o resultado diretamente. O resultado será liberado quando o tratador de PGresult associado for passado para a função PQclear.

char *PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);

Para os dados no formato texto, a representação dos valores retornados por PQgetvalue é uma cadeia de caracteres terminada por nulo do valor do campo. Para os dados no formato binário, o valor está na representação binária determinada pelas funções typsend e typreceive do tipo de dado (Na verdade, neste caso o valor é seguido por um byte zero também, mas normalmente isto não é útil, uma vez que o valor pode conter nulos incorporados).

É retornada uma cadeia de caracteres vazia se o valor do campo for nulo. Deve ser vista a função PQgetisnull para distinguir valores nulos de cadeias de caracteres vazias.

O ponteiro retornado por PQgetvalue aponta para um armazenamento que faz parte da estrutura PGresult. O dado apontado não deve ser modificado, e os dados devem ser explicitamente copiados para outro local de armazenamento se forem ser utilizados após o tempo de vida da própria estrutura PGresult.

Testa o campo com relação ao valor nulo. Os números de linha e de coluna começam por 0.

int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);

Esta função retorna 1 se o campo for nulo, e 0 se contiver um valor não nulo (Deve ser observado que a função PQgetvalue retorna uma cadeia de caracteres vazia, e não um ponteiro nulo, para um campo nulo).

Retorna o verdadeiro comprimento do valor do campo em bytes. Os números de linha e de coluna começam por 0.

int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);

Este é o verdadeiro comprimento dos dados para o valor de dado em particular, ou seja, o tamanho do objeto apontado por PQgetvalue. Para dados no formato texto, é o mesmo que strlen(). Para o formato binário, esta é uma informação essencial. Deve ser observado que não se deve depender da função PQfsize para obter o verdadeiro comprimento de dado.

Imprime todas as colunas e, opcionalmente, os nomes das colunas, para um fluxo de saída especificado.

void PQprint(FILE *fout,      /* fluxo de saída */
             const PGresult *res,
             const PQprintOpt *po);

typedef struct {
    pqbool  header;      /* print output field headings and row count */
    pqbool  align;       /* fill align the fields */
    pqbool  standard;    /* old brain dead format */
    pqbool  html3;       /* output HTML tables */
    pqbool  expanded;    /* expand tables */
    pqbool  pager;       /* use pager for output if needed */
    char    *fieldSep;   /* field separator */
    char    *tableOpt;   /* attributes for HTML table element */
    char    *caption;    /* HTML table caption */
    char    **fieldName; /* null-terminated array of replacement field names */
} PQprintOpt;

Esta função era anteriormente utilizada por psql para imprimir os resultados das consultas, mas este não é mais o caso. Deve ser observado que esta função assume que todos os dados estão no formato texto.

Retorna a marca de status do comando SQL que gerou PGresult.

char *PQcmdStatus(PGresult *res);

Normalmente é apenas o nome do comando, mas pode incluir dados adicionais como o número de linhas processadas. Quem chama não deve liberar o resultado diretamente. O resultado será liberado quando o tratador de PGresult associado for passado para a função PQclear.

Retorna o número de linhas afetadas pelo comando SQL.

char *PQcmdTuples(PGresult *res);

Esta função retorna a cadeia de caracteres que contém o número de linhas afetadas pela declaração SQL que gerou PGresult. Esta função pode ser utilizada apenas após a execução dos comandos INSERT, UPDATE, DELETE, MOVE e FETCH, ou em um EXECUTE de uma declaração preparada que contenha um comando INSERT, UPDATE ou DELETE. Se o comando que gerou PGresult for alguma coisa diferente, a função PQcmdTuples retorna uma cadeia de caracteres vazia. Quem chama não deve liberar o valor retornado PGresult associado for passado para a função PQclear.

Retorna o OID da linha inserida, se o comando SQL foi um INSERT que inseriu exatamente uma linha numa tabela que possui OIDs, ou um EXECUTE de uma declaração preparada contendo um comando INSERT apropriado. Senão, esta função retorna InvalidOid. Esta função também retorna InvalidOid se a tabela afetada pelo comando INSERT não contiver OIDs.

Oid PQoidValue(const PGresult *res);

Retorna uma cadeia de caracteres com o OID da linha inserida, se o comando SQL foi um INSERT que inseriu exatamente uma linha, ou um EXECUTE de uma declaração preparada contendo um comando INSERT apropriado (A cadeia de caracteres será 0 se o comando INSERT não inserir exatamente uma linha, ou se a tabela de destino não possuir OIDs). Se o comando não for um INSERT, é retornada uma cadeia de caracteres vazia.

char *PQoidStatus(const PGresult *res);

Esta função está em obsolescência em favor da função PQoidValue. Não é segura quanto a vários fluxos de execução (threads).

Faz escape em dados binários a serem utilizados dentro de comandos SQL com o tipo bytea. Assim como em PQescapeString, somente é utilizada ao inserir dados diretamente na cadeia de caracteres do comando SQL.

unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);

Certos valores de byte devem receber escape (mas todos os valores de byte podem receber escape) quando utilizados como parte de um literal bytea em uma declaração SQL. Em geral, para fazer o escape de um byte, este é convertido em um número octal de três dígitos igual ao valor do octeto, e precedido por duas contrabarras. Os caracteres apóstrofo (') e contrabarra (\) possuem alternativas especiais de seqüência de escape. Para obter informações adicionais deve ser consultada a Seção 8.4. A função PQescapeBytea realiza esta operação, fazendo escape apenas do menor número de bytes necessários.

O parâmetro from aponta para o primeiro byte da cadeia de caracteres que vai receber os escapes, e o parâmetro from_length fornece o número de bytes nesta cadeia binária (Um byte zero terminador não é necessário nem contado). O parâmetro to_length aponta para uma variável que conterá o comprimento da cadeia de caracteres com escapes resultante. O comprimento da cadeia de caracteres resultante inclui o byte zero terminador do resultado.

A função PQescapeBytea retorna uma versão com escapes da cadeia binária do parâmetro from na memória alocada pela função malloc(). Esta memória deve ser liberada através da função PQfreemem quando o resultado não for mais necessário. A cadeia retornada possui todos os caracteres especiais substituídos para que possam ser adequadamente processados pelo analisador de literal cadeia de caracteres do PostgreSQL, e pela função de entrada de bytea. O byte zero terminador também é adicionado. Os apóstrofos que devem envolver os literais cadeia de caracteres do PostgreSQL não fazem parte da cadeia de caracteres do resultado.

Converte a representação com escapes dos dados binários em dados binários — o inverso da função PQescapeBytea. Isto é necessário ao receber dados bytea no formato texto, mas não quando for recebido no formato binário.

unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

O parâmetro from aponta para uma cadeia de caracteres com escapes como a que pode ser retornada pela função PQgetvalue quando esta é aplicada a uma coluna bytea. A função PQunescapeBytea converte esta representação em cadeia de caracteres na representação binária. É retornado um ponteiro para um buffer alocado pela função malloc(), ou nulo se ocorrer um erro, e coloca o tamanho do buffer no parâmetro to_length. O resultado deve ser liberado através da função PQfreemem quando não for mais necessário.

Libera a memória alocada pela libpq.

void PQfreemem(void *ptr);

Libera a memória alocada pela libpq, em particular pelas funções PQescapeBytea, PQunescapeBytea, e PQnotifies. É necessária pelo Microsoft Windows, que não consegue liberar memória entre DLLs, a menos que sejam utilizadas DLLs com vários fluxos de execução (multithreaded) (/MD no VC6). Nas outras plataformas, esta função é a mesma função da biblioteca padrão free().