27.4. Processamento de comandos assíncronos

Submete o comando ao servidor sem aguardar pelos resultados. Retorna 1 quando o envio do comando é bem-sucedido, e 0 caso contrário (neste caso, deve ser usada a função PQerrorMessage para obter informações adicionais sobre a falha).

int PQsendQuery(PGconn *conn, const char *command);

Após uma chamada bem-sucedida à função PQsendQuery, deve ser chamada a função PQgetResult uma ou mais vezes para obter os resultados. A função PQsendQuery não deve ser chamada novamente (na mesma conexão), até que a função PQgetResult retorne um ponteiro nulo, indicando que o comando completou.

Submete o comando e os parâmetros em separado para o servidor, sem aguardar pelos resultados.

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

É equivalente à função PQsendQuery, exceto que os parâmetros podem ser especificados separados da cadeia de caracteres do comando. Os parâmetros da função são tratados de forma idêntica aos da função PQexecParams. Da mesma forma que a função PQexecParams, não funciona em conexões com protocolo 2.0, e permite apenas um comando na cadeia de caracteres de comando.

Envia uma solicitação para criar uma declaração preparada com os parâmetros fornecidos, sem aguardar completar.

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

Esta é a versão assíncrona da função PQprepare: retorna 1 se for capaz de enviar a solicitação, e 0 caso contrário. Após uma chamada bem sucedida, deve ser chamada a função PQgetResult para determinar se a criação da declaração preparada no servidor foi bem-sucedida. Os parâmetros desta função são tratados de maneira idêntica aos da função PQprepare. Da mesma forma que a função PQprepare, não funciona em conexões com protocolo 2.0.

Envia solicitação para executar a declaração preparada com os parâmetros fornecidos, sem aguardar pelos resultados.

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

Semelhante à função PQsendQueryParams, mas o comando a ser executado é especificado pelo nome da declaração preparada anteriormente, em vez de fornecer a cadeia de caracteres do comando. Os parâmetros desta função são tratados de maneira idêntica aos da função PQexecPrepared. Da mesma forma que a função PQexecPrepared, não funciona em conexões com protocolo 2.0.

Aguarda o próximo resultado de uma chamada anterior a PQsendQuery, PQsendQueryParams, PQsendPrepare ou PQsendQueryPrepared, e retorna o resultado. Retorna um ponteiro nulo quando o comando está completo e não haverão mais resultados.

PGresult *PQgetResult(PGconn *conn);

A função PQgetResult deve ser chamada repetidas vezes até que retorne um ponteiro nulo, indicando que o comando completou (Se for chamada quando nenhum comando estiver ativo, a função PQgetResult apenas retorna o ponteiro nulo de uma vez). Cada resultado não-nulo da função PQgetResult deve ser processado usando as mesmas funções de acesso a PGresult descritas anteriormente. Não se deve esquecer de liberar cada objeto de resultado através de PQclear após terminar de usá-lo. Deve ser observado que a função PQgetResult somente bloqueia se um comando estiver ativo, e os dados de resposta necessários ainda não foram lidos por PQconsumeInput.

Se estiver disponível uma entrada vinda do servidor, receber esta entrada.

int PQconsumeInput(PGconn *conn);

A função PQconsumeInput normalmente retorna 1, indicando "nenhum erro", mas retorna 0 caso tenha acontecido algum problema (neste caso a função PQerrorMessage pode ser consultada). Deve ser observado que o resultado não informa se algum dado de entrada foi realmente coletado. Após chamar a função PQconsumeInput, o aplicativo pode verificar PQisBusy e/ou PQnotifies para ver se seu estado mudou.

A função PQconsumeInput pode ser chamada mesmo que o aplicativo ainda não esteja preparado para tratar o resultado ou a notificação. A função lê os dados disponíveis e guarda em um buffer, fazendo, portanto, com que uma indicação de pronto-para-ler da função select() desapareça. O aplicativo pode, portanto, utilizar a função PQconsumeInput para limpar a condição da função select() imediatamente, e depois examinar os resultados quando achar melhor.

Retorna 1 se o comando estiver ocupado, ou seja, a função PQgetResult fica bloqueada aguardando pela entrada. O retorno do valor 0 indica que a função PQgetResult pode ser chamada com garantia que não vai bloquear.

int PQisBusy(PGconn *conn);

A função PQisBusy não tenta por si mesma ler os dados do servidor; portanto, a função PQconsumeInput deve ser chamada antes, ou o estado de ocupado nunca vai terminar.

Define o status da conexão como bloqueante ou não.

int PQsetnonblocking(PGconn *conn, int arg);

Define o status da conexão como não bloqueante se arg for igual a 1, ou bloqueante se arg for igual a 0. Retorna 0 se for bem-sucedida, ou -1 se houver um erro.

No estado não bloqueante, a chamada a PQsendQuery, PQputline, PQputnbytes e PQendcopy não bloqueia, mas em vez disso retorna um erro se precisarem ser chamadas novamente.

Deve ser observado que a função PQexec não respeita o modo não bloqueante; se for chamada, age do modo bloqueante de qualquer maneira.

Retorna o status da conexão com o banco de dados como bloqueante ou não.

int PQisnonblocking(const PGconn *conn);

Retorna 1 se a conexão estiver definida no modo não bloqueante, e 0 se bloqueante.

Tenta descarregar qualquer dado de saída enfileirado para o servidor. Retorna 0 se for bem sucedido (ou se a fila de envio estiver vazia), -1 se falhar por alguma razão, ou 1 se não for capaz de enviar todos os dados ainda na fila de envio (este caso somente pode ocorrer se a conexão não for bloqueante).

int PQflush(PGconn *conn);