ecpg

Name

ecpg  --  pré-processador de SQL embutido para a linguagem C

Synopsis

ecpg [-v] [-t] [-I caminho_de_inclusão] [-o arquivo_de_saída] arquivo...

Entradas

O ecpg aceita os seguintes argumentos de linha de comando:

-v

Exibe informação da versão.

-t

Ativa a auto-efetivação (auto-commit) das transações. Neste modo, cada comando é automaticamente efetivado, a menos que esteja dentro de um bloco de transação explícito. No modo padrão, os comandos só são efetivados quando o exec sql commit é executado.

-I caminho_de_inclusão

Especifica um caminho de inclusão adicional. Por padrão os seguintes: . (o diretório atual), /usr/local/include, o caminho de inclusão que foi definido na hora da compilação do PostgreSQL (por padrão, /usr/local/pgsql/include) e /usr/include.

-o arquivo_de_saída

Especifica que o ecpg deve escrever toda a sua saída no arquivo_de_saída. Se esta opção não for fornecida, a saída é escrita em nome.c, assumindo-se que o arquivo de entrada se chama nome.pgc. Se o arquivo de entrada não tiver o sufixo esperado .pgc, então o arquivo de saída terá .pgc apensado ao nome do arquivo de entrada.

arquivo

Os arquivos a serem processados.

Saídas

O ecpg cria um arquivo ou escreve em stdout.

Valor retornado

O ecpg retorna 0 se terminar a execução com sucesso, ou um valor diferente de 0 se ocorrer algum erro.

Descrição

O ecpg é um pré-processador de SQL embutido para a linguagem C e o PostgreSQL. Permite o desenvolvimento de programas C com código SQL embutido.

Linus Tolke () foi o autor original do ecpg (até a versão 0.2). Michael Meskes () é o atual autor e mantenedor do ecpg. Thomas Good () é o autor da última revisão do man page do ecpg, no qual este documento se baseia.

Utilização

Pré-processamento para Compilação

Um arquivo fonte com SQL embutido deve ser pré-processado antes de ser compilado:

ecpg [ -d ] [ -o arquivo ] arquivo.pgc

onde o sinalizador opcional -d ativa a depuração. A extensão .pgc é uma maneira arbitrária de caracterizar um fonte ecpg.

Pode-se desejar redirecionar a saída do pré-processador para um arquivo de log.

Compilação e Ligação

Assumindo-se que os binários do PostgreSQL estão em /usr/local/pgsql, será necessário compilar e ligar (link) o arquivo fonte pré-processado usando:

gcc -g -I /usr/local/pgsql/include [ -o arquivo ] arquivo.c -L /usr/local/pgsql/lib -lecpg -lpq

Gramática

Bibliotecas

O pré-processador adiciona duas diretivas ao código fonte:

#include <ecpgtype.h>
#include <ecpglib.h>

Declaração das Variáveis

As variáveis declaradas dentro do código fonte ecpg devem estar precedidas por:

EXEC SQL BEGIN DECLARE SECTION;

Analogamente, a seção de declaração das variáveis deve terminar por:

EXEC SQL END DECLARE SECTION;

Note: Antes da versão 2.1.0 cada variável tinha que ser declarada em uma linha separada. A partir da versão 2.1.0 múltiplas variáveis podem ser declaradas em uma única linha:

char  foo[16], bar[16];

Tratamento de Erros

A área de comunicação SQL é definida pelo:

EXEC SQL INCLUDE sqlca;

Note: A palavra sqlca deve ser escrita em letras minúsculas. Enquanto a convenção SQL pode ser seguida, ou seja, usar letras maiúsculas para separar o SQL embutido das declarações C, o sqlca (que inclui o arquivo de cabeçalho sqlca.h) deve estar em letras minúsculas, devido ao fato do prefixo EXEC SQL indicar que esta inclusão será feita pelo ecpg. O ecpg diferencia letras maiúsculas de minúsculas (SQLCA.h não será encontrado). O EXEC SQL INCLUDE pode ser utilizado para incluir outros arquivos de cabeçalho desde que a diferença entre as letras maiúsculas e minúsculas seja observada.

O comando sqlprint é utilizado junto com a declaração EXEC SQL WHENEVER para ativar o tratamento de erros ao longo do programa:

EXEC SQL WHENEVER sqlerror sqlprint;

e

EXEC SQL WHENEVER not found sqlprint;

Note: Este não é um exemplo exaustivo da utilização da declaração EXEC SQL WHENEVER. Outros exemplos de utilização podem ser encontrados em manuais do SQL (por exemplo, The LAN TIMES Guide to SQL por Groff and Weinberg).

Conectar ao Servidor de Banco de Dados

Pode-se conectar ao banco de dados através de:

EXEC SQL CONNECT TO nome_bd;

onde o nome do banco de dados não é escrito entre apóstrofos ('). Antes da versão 2.1.0 o nome do banco de dados tinha que vir entre apóstrofos.

Também é possível especificar o nome do servidor e a porta no comando de conexão. A sintaxe é:

nome_bd[@servidor][:porta]

ou

<tcp|unix>:postgresql://servidor[:porta][/nome_bd][?opções]

Comandos

Em geral, os comandos SQL aceitos por outros aplicativos como o psql podem ser embutidos no código C. Abaixo estão alguns exemplos de como fazer.

Criar Tabela:

EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
EXEC SQL CREATE UNIQUE index num1 on foo(number);
EXEC SQL COMMIT;

Incluir:

EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT;

Excluir:

EXEC SQL DELETE FROM foo WHERE number = 9999;
EXEC SQL COMMIT;

Seleção de uma única linha:

EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';

Seleção usando Cursor:

EXEC SQL DECLARE foo_bar CURSOR FOR
    SELECT number, ascii FROM foo
    ORDER BY ascii;
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
...
EXEC SQL CLOSE foo_bar;
EXEC SQL COMMIT;

Atualização:

EXEC SQL UPDATE foo
    SET ascii = 'foobar'
    WHERE number = 9999;
EXEC SQL COMMIT;

Notas

A definição completa da estrutura DEVE estar listada dentro da seção de declaração.

Consulte o arquivo TODO (a fazer) no fonte para conhecer outras funcionalidades que estão faltando.