ecpg [-v] [-t] [-I caminho_de_inclusão] [-o arquivo_de_saída] arquivo...
O ecpg aceita os seguintes argumentos de linha de comando:
Exibe informação da versão.
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.
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.
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.
Os arquivos a serem processados.
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 (<linus@epact.se>) foi o autor original do ecpg (até a versão 0.2). Michael Meskes (<meskes@debian.org>) é o atual autor e mantenedor do ecpg. Thomas Good (<tomg@q8.nrnet.org>) é o autor da última revisão do man page do ecpg, no qual este documento se baseia.
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.
O pré-processador adiciona duas diretivas ao código fonte:
#include <ecpgtype.h> #include <ecpglib.h>
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];
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).
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]
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;