Agata Report Manual do usuário Pablo Dall'Oglio [pablo@univates.br] [pablo@php.net] Solis/Univates Lajeado - RS - Brasil Fevereiro 2003 http://agata.codigolivre.org.br
Índice geral Conectando ao Banco de Dados...3 Tela Principal: Selecionando as Tabelas...4 Selecionando os campos...5 Restringindo a Consulta...6 Utilizando Parâmetros...7 Ligando as Tabelas...8 Resultado do Relatório...9 Em Tela...9 Em Texto...9 Em PostScript...10 Em HTML...10 Miscelâneas...11 Editando a Consulta...11 Salvando as Consultas...11 Abrindo as Consultas...11 Começando uma nova Consulta...11 Navegando entre Consultas...11 Gerando Diagramas...12 Gerando Etiquetas...13 Relatório com Quebras e Totalizadores...14 Arquivo SQL...15 Gerando a saída do Relatório como Texto...15 Gerando a saída do Relatório como HTML...16 Gerando a saída do Relatório como PS...16 Mesclando o Relatório com um Documento...17 Ferramenta AgataEIS: Geração de Gráficos e Planilhas eletrônicas...19
Conectando ao Banco de Dados Nome do Projeto: Identificação da aba do projeto. IP do Banco de Dados: Endereço IP do computador no qual a Base de Dados está rodando. Nome do Banco de Dados: Nome do Banco de Dados a acessar. Usuário do Banco: Nome do usuário do Banco de Dados. Senha: Senha do respectivo usuário para acessar o banco de dados. Linguagem: Idioma que o Agata irá utilizar na interface. Tipo de Banco de Dados: Tipo do Banco de Dados (Postgres, Oracle...) Tema: Tema das janelas (skin). Visualizador para PostScript: Programa utilizado para Visualizar os arquivos PostScript gerados pelo Agata. Visualizador para Texto: Programa utilizado para Visualizar os arquivos Texto gerados pelo Agata. Browser: Browser para visualizar os arquivos HTML gerados (IE, Mozilla). Planilha: Planilha externa para abrir os arquivos CSV gerados pelo AgataEIS. Visualizador para Diagramas: Programa externo para visualizar os diagramas gerados. Use o Dia, (http://www.lysator.liu.se/~alla/dia). a. botão - : Deleta o projeto. b. botão + : Adiciona um projeto novo. Passo 1: Escolha um projeto dentre as abas na esquerda. Passo 2: Clique no botão Ok, o Agata tentará conectar na Base de Dados com os parâmetros digitados acima e gravará os dados digitados. Se tudo ocorrer com sucesso, a tela principal para consultas será exibida na tela.
Tela Principal: Selecionando as Tabelas Passo 1: Escolha as tabelas do Banco de Dados envolvidas na consulta, você poderá usar a tecla [CNTRL] para selecionar mais do que uma. Passo 2: Cada vez que o botão [Solicita Tabelas] é clicado, disponibilizará as tabelas selecionadas para que você possa utilizá-las no relatório. Passo 3: Todas tabelas requisitadas, poderão ser acessadas pelo usuário no passo 3, através da árvore que contém a estrutura das tabelas e dos campos. Botão Limpar: Limpa a seleção de Tabelas. Possibilita requisitar as tabelas novamente.
Selecionando os campos Passo 1: Selecione os campos que você deseja no relatório. Você poderá usar a tecla [CNTRL] para selecionar mais de um campo. Passo 2: Escolha o que você deseja fazer com os campos selecionados. Botão Select: Simplesmente seleciona o campo para o relatório. Botão Grupo: Agrupa a consulta pelo campo selecionado. Botão Ordem Ascendente: Ordena o relatório de forma ascendente[a-z] pelo campo selecionado. Botão Ordem Descendente: Ordena o relatório de forma descendente[z-a] pelo campo selecionado. Funções Comuns: Aplica uma função ao campo selecionado (max, min, avg, count), para isso é necessário agrupar a consulta. Funções do BD: Aplica uma função do Banco de Dados ao campo selecionado. Estas funções são cadastradas no arquivo DB.fun.
Restringindo a Consulta Nesta fase você irá adicionar várias restrições (filtros) aos dados selecionados para o Relatório final. Poderá restringir quaisquer tipos de colunas (numéricas, caracteres), comparando-as a determinadas expressões. Passo 1: Escolha o campo que você deseja restringir (filtrar). Passo 2: Selecione o operador utilizado para restringir a consulta (<, >, =, like). Passo 3: Digite a expressão de filtragem, poderá ser uma palavra ou um número. Ex: '50'. Passo 4: Use o botão 'Transferir' para adicionar a restrição à consulta.
Utilizando Parâmetros Para restringir uma consulta, é necessário digitar uma expressão de filtragem. Geralmente essa expressão de filtragem é um número ou uma palavra (50, 'Paulo',...). O problema desta concepção e que a expressão de filtragem é gravada junto ao comando SQL. Muitas vezes você deseja utilizar a mesma consulta SQL, mas com expressões de filtragem diferentes. Neste caso, teria de alterar a consulta SQL sempre que desejasse gerar o relatório. Um exemplo, seria emitir um relatório de devedores entre os anos de 2000 e 2001. A consulta SQL é sempre a mesma, mas o intervalo de datas muda; não deve estar gravado junto a consulta e sim ser perguntado para você no momento da geração do relatório. Para tanto, utiliza-se o conceito de parâmetros. Sempre que você deseja introduzir um valor que deve ser indagado no momento da execução do relatório, deve se utilizar uma palavra-chave precedida do sinal $. Por exemplo: $DataDeInicio, $DataDeFinal, $CodigoDaPessoa... Sem utilizar espaços em branco ou caracteres absurdos. Assim, no momento da geração do relatório, uma janela será aberta para que você entre com todos parâmetros detectados na consulta. Assim que pressionar OK, o relatório será gerado e os Parâmetros $Valor, $Xxx serão sutstituídos pelos valores digitados por você.
Ligando as Tabelas Em um relatório você poderá selecionar dados de mais de uma tabela. Nesse caso, é necessário ligar os campos em comum entre elas. Técnicamente falando, tem de ligar as chaves extrangeiras de uma tabela com as chaves primárias de outra tabela. Obs: Se o relatório for composto de apenas uma tabela, isso não se faz necessário. Passo 1: Escolha um campo de uma tabela que você necessita relacionar com algum campo de outra tabela. Passo 2: Escolha o operador que irá relacionar os campos de ambas tabelas (<, >, =). Passo 3: Selecione o campo relacionado da segunda tabela. Passo 4: Use o botão 'Transferir' para adicionar a ligação à consulta.
Em Tela Resultado do Relatório Relatório em tela permite uma visualização rápida do resultado do relatório. Entretanto, não há a possibilidade de editar, imprimir, nem mesmo salvar em disco. Em Texto Permite salvar o relatório em disco, possibilitando editá-lo ou imprimí-lo. O relatório será exibido no editor de texto configurado na tela de entrada do Agata (Conexão com o Banco de Dados).
Em PostScript Permite salvar o relatório em formato PostScript. Um formato elegante, pronto para impressão. O relatório será exibido no visualizador de PostScript configurado na tela de entrada do Agata (Conexão com o Banco de Dados). Em HTML Permite salvar o relatório em formato HTML. O relatório será exibido no browser configurado na tela de entrada do Agata (Conexão com o Banco de Dados).
Editando a Consulta Miscelâneas Todos os elementos que compõem a consulta são editáveis. Você pode clicar sobre qualquer cláusula (Select, From, Where), que automaticamente aparecerá uma janela permitindo que se adicione, delete, ou edite itens da consulta. Salvando as Consultas Permite salvar a consulta SQL realizada como arquivo.sql. O Agata possui em sua estrutura o diretório SQL reservado para isto. Dentro do diretório SQL, podem ser criados inúmeros subdiretórios para organizar as consultas de acordo com o Banco de Dados/Projeto. Abrindo as Consultas Permite ao usuario abrir uma consulta SQL já realizada, armazenada em um arquivo.sql. Começando uma nova Consulta Permite ao usuário reiniciar uma Consulta. Prepara todo o ambiente para uma nova consulta. Navegando entre Consultas Na parte inferior esquerda da tela principal, o Agata oferece uma árvore de consultas salvas. Na verdade, todo diretório SQL é lido e trazido para dentro dessa árvore, incluindo os subdiretórios. Dessa forma, você pode carregar uma consulta já realizada, simplesmente clicando sobre um item. Os subdiretórios podem ser organizados (criados, excluídos) de acordo com cada projeto, banco de dados, ou tipo de informação. Você tem total liberdade para organizá-los da melhor maneira possível.
Gerando Diagramas Uma ferramenta bastante útil para quem desenvolve sistemas ou mesmo para usuários (para entender melhor as relações entre as tabelas), é o gerador de diagramas. Para gerar diagramas, não é necessário passar por todas as etapas de um relatório, basta selecionar as tabelas (solicitar tabelas) e então clicar no botão indicado à esquerda. O diagrama gerado será exibido no software de diagramas configurado na tela de entrada do Agata (Conexão com o Banco de Dados). Geralmente é o Dia. Este diagrama abaixo representa a estrutura das tabelas utilizadas nos exemplos deste tutorial.
Gerando Etiquetas A ferramenta para geração de etiquetas de endereçamento (botão à esquerda), gera etiquetas em duas colunas e dez linhas (Ex.: etiquetas Pimaco - código 6181) no formato para impressão PostScript. Passo 1: Escolha os campos (colunas) que irão integrar a etiqueta. Estes campos são coletados da consulta que você fez na tela principal do Agata. Logo, sempre que você quiser gerar etiquetas, é necessário fazer uma consulta ou carregar uma pré-existente, na tela principal. Passo 2: Ajustes, Livre digitação. Passo 3: Botão que gera as etiquetas em formato PostScript. O resultado gerado será exibido no software de visualização de PostScript configurado na tela de entrada do Agata (Conexão com o Banco de Dados). Obs. a.: Você pode usar os botões Abrir e Salvar para carregar etiquetas pré-formatadas, ou ainda carregá-los através da caixa Etiquetas salvas (Saved Labels). Obs. b.: Você poderá inserir controles especiais para alterar as fontes, o controle $fonte, deve ser inserido em uma linha em separado. Obs. c.: Você poderá inserir símbolos especiais (frações, linhas, etc) através da caixa de controles especiais. Obs. d.: Você poderá ajustar as margens esquerda e topo, além do espaçamento entre uma etiqueta e outra (em pontos).
Relatório com Quebras e Totalizadores O Agata possui o Recurso de Quebras e Totalizadores. Através deste recurso você poderá criar um relatório com múltiplos níveis ou quebras (Agrupamento de Dados). Para cada agrupamento, podemos aplicar determinadas fórmulas (soma, contagem, média, máximo ou mínimo). Não há limite quanto à quantidade de quebras, sendo que você pode envolver diversas tabelas no relatório também. Passo 1: Escolha as tabelas envolvidas na consulta. No exemplo, a tabela principal (a) e a tabela com os detalhes (b). Passo 2: Selecione as colunas envolvidas no relatórios, primeiro as colunas da tabela principal (a) e depois da tabela com os detalhes (b). Passo 3: Crie as restrições de dados e ligue as tabelas envolvidas na consulta. Passo 4: Entre na aba Grupos para definir as quebras e totalizadores. Passo 5: Escolha uma fórmula (contagem, soma, média, máximo, mínimo) a ser aplicada sobre uma determinada coluna (6). Passo 6: Selecione a coluna a qual deseja aplicar a fórmula selecionada no passo (5). Passo 7: Selecione a quebra (agrupamento de dados) na qual será aplicada a fórmula (5) sobre o campo (6). Significa que, toda vez que a coluna ou quebra (7) tiver seu valor alterado no decorrer do relatório, será aplicada a fórmula (5) sobre o campo (6) e os detalhes serão deslocados à direita. Passo 8: Registre a fórmula/quebra. Obs. a.: Tabela principal (mestre).
Obs. b.: Tabela de detalhes (detalhe). Obs. c.: Mostrar colunas de Grupo. Se desligado, não exibe nos detalhes a coluna utilizada para a quebra, pois a mesma se tornaria repetitiva. Obs. d.: Exibir detalhes. Se desligado, não exibe detalhes, somente totalizadores. Obs. e.: Lista de quebras/fórmulas já definidas. Clicando sobre algum item, é possível alterar manualmente as definições. Arquivo SQL Este é o arquivo SQL utilizado para construção deste exemplo. Observe o rótulo da primeira coluna com o as, a ligação entre as tabelas no where e as definições das quebras/fórmulas na cláusula # (contagem da coluna 2, soma e média da coluna 5, sempre que a coluna #1 trocar de valor). Note que foi desabilitada a opção Mostrar colunas de grupo, fazendo com que a coluna 1 não se tornasse repetitiva nos detalhes do relatório. Select: departamentos.nome_dep as "Departamento", empregados.codigo_emp, empregados.nome, empregados.endereco, empregados.valorporhora From: departamentos, empregados Where: departamentos.codigo_dep = empregados.codigo_dep Group by: Order by: 1 #1: count(2),sum(5),avg(5) Gerando a saída do Relatório como Texto ----------------------------------------------------------------------------------------------------------- Relatório com Quebras ----------------------------------------------------------------------------------------------------------- Departamento : CONTABILIDADE ============================= ------------------------------------------------------------------------------------------------------ codigo_emp nome endereco valorporhora ------------------------------------------------------------------------------------------------------ 31 VERA FATIMA DE OLIVEIRA LAJEADO 80,00 32 SANDRA AULER LAJEADO 80,00 33 VIVIANE BERNER LAJEADO 70,00 34 JOICE KAFER LAJEADO 70,00 35 JOSI PETER ESTRELA 70,00 36 ANA PRETA CRUZEIRO 80,00 37 ANA FIGUI LAJEADO 60,00 38 MARIANI STOLL LAJEADO 50,00 39 FABIO WIEBILLING CRUZEIRO 60,00 40 MARCONE THEISEN TEUTONIA 50,00 41 JUNIOR MULINARI LAJEADO 50,00 42 TIAGO GIOVANAZ LAJEADO 50,00 43 MAICO SCHMITZ ARROIO DO MEIO 50,00 ------------------------------------------------------------------------------------------------------ Count: 13,00 Sum: 820,00 Média: 63,08 Departamento : FINANCEIRO ========================== ------------------------------------------------------------------------------------------------------ codigo_emp nome endereco valorporhora ------------------------------------------------------------------------------------------------------ 21 PABLO DALLOGLIO CRUZEIRO 60,00 22 MAURICIO DE CASTRO LAJEADO 70,00 23 JOAO ALEX FRITSCH LAJEADO 60,00 25 PAULO MALLMANN CRUZEIRO 60,00 26 ALEXANDRE SCHMITD ARROIO DO MEIO 40,00 27 CESAR BROD ARROIO DO MEIO 40,00 28 ALEXANDRE TABORDA ESTRELA 60,00 29 NAZAIR JUNIOR BOQUEIRAO 50,00 24 VILSON GARTNER ESTRELA 60,00 30 HENRIQUE GRAVINA LAJEADO 60,00 ------------------------------------------------------------------------------------------------------ Count: 10,00 Sum: 560,00 Média: 56,00
Gerando a saída do Relatório como HTML Gerando a saída do Relatório como PS
Mesclando o Relatório com um Documento A ferramenta de mesclagem permite criar relatórios de dois níveis. Primeiramente você deve fazer um relatório na tela principal do Agata, ou carregar um salvo. Para cada linha retornada do relatório principal, o Agata criará uma página no mesclador. Obs. a.: Através da caixa Inserir, você poderá inserir vários controles, símbolos especiais como o de marca registrada ($reco), copyright ($copy) encontrados na caixa Controles Especiais, além de trocar de fonte no documento clicando na caixa Fontes. Atenção, as variáveis que indicam troca de fonte precisam estar em uma linha isolada (ex: $fan14 = fonte arial normal 14, $fcb10 = fonte courier bold 10). Obs. b.: Através da caixa Consultas Salvas, você poderá abrir um documento já pronto (.rel). Atente para o fato de que o documento carregado precisa condizer com o relatório feito na tela principal. As variáveis nele contidas precisam existir. Obs. c.: Você poderá ligar a caixa Paginação se quiser numeração automática em todas páginas. Também poderá definir o Espaçamento em pontos entre as linhas do documento gerado. Passo 1: Insere campos (colunas) do relatório principal no documento. Note que todos campos provindos do relatório, feito na tela principal, serão carregados na caixa Campos. Assim que você clicar em algum, ele automaticamente aparecerá na posição atual do cursor. Passo 2: Editar à mão livre o documento mesclado. Podendo inserir textos a vontade, assim como controles especiais e fontes (a).
Passo 3: Subconsultas Você pode fazer subpesquisas dentro do documento. Lembre-se de que para cada linha do relatório feito na tela principal, será gerada uma página no mesclador de documentos. Logo, podemos fazer uma nova pesquisa dentro de cada página referenciando alguma variável dessa linha. Incluindo a consulta no documento Para inserir uma seção de subconsulta basta inserir uma Seção de SubPesquisa. Clicando na caixa Controles Especiais. >>>SUB-SQL A partir daí você pode inserir variáveis resultantes da subconsulta enumeradas como $subfield1, $subfield2, $subfield3, e assim por diante. Essa ordem está diretamente ligada à ordem dos campos (colunas) do select da subconsulta. $subfield1 $subfield2 Os dados da seção de subpesquisa serão replicados no documento conforme quantas linhas retornarem do Banco de Dados. (Note que você precisa colocar somente uma vez os $subfield's. Então podemos encerrar a Seção de SubPesquisa clicando na caixa Controles Especiais e selecionando Final da SubPesquisa.) <<<SUB-SQL Passo 4: Digitando a consulta Digite uma instrução SQL qualquer na seção (Sub SQL) que irá trazer dados para a página atual. Você pode referenciar as variáveis do relatório principal, utilizando-as entre aspas simples, '$tabela_campo'. Veja na ilustração acima (4). Select... from... where xxx='$tabela_campo'; Passo 5: Botão que gera o documento em formato PostScript. O resultado gerado será exibido no software de visualização de PostScript configurado na tela de entrada do Agata (Conexão com o Banco de Dados).
Ferramenta AgataEIS: Geração de Gráficos e Planilhas eletrônicas A ferramenta EIS permite a geração de gráficos de linha, barras ou também exportar os dados para uma planilha eletrônica. Ela processa os dados através de várias consultas SQL digitadas no centro da tela. Essas consultas podem ser digitadas ou importadas (carregadas) de arquivos (.sql) ou de relatórios construídos na tela principal do Agata. a. Novo: Cria novo arquivo.eis. Limpa toda área de texto e os campos da tela. b. Salvar: Salva o todo conteúdo da tela (títulos, consultas SQL) em um arquivo.eis. c. HTML ou PS: Define o formato de saída do gráfico. Pode ser HTML (abrirá no browser) ou PostScript (abrirá no visualizador de PostScript). d. (Exibir Valores): Essa opção indica se cada elemento gráfico (linha ou barra) indicará o valor que ele está representando a cada pico. e. (Gráfico + Dados): Se esta opção estiver ligada, logo abaixo do gráfico será exibida uma tabela com os valores utilizados para a montagem do mesmo (valores que retornaram da consulta ao Banco de Dados). f. Dimensão: Escolha as dimensões do gráfico. Em alguns casos em que são exibidas muitas colunas ou muitas linhas, é importante aumentar as dimensões, para evitar o truncamento das informações.
Passo 1: Você poderá importar uma consulta (.sql) preparada na tela principal do Agata. A consulta deve conter apenas colunas numéricas para geração de gráficos. Também pode, através do segundo botão, abrir um arquivo (.eis) que se trata de um conjunto de instruções SQL delimitadas por ;. Os arquivos.eis são os arquivos padrão salvos pelo AgataEIS. Existem duas formas de selecionar os dados para geração de gráficos: Múltiplas colunas: Seleciona-se várias colunas numéricas de uma mesma tabela. Ex a: select coluna_a, coluna_b, coluna_c from tabela where... Neste caso, cada coluna numérica (coluna_a, coluna_b, coluna_c) será projetada como uma linha, ou uma barra ou uma coluna (planilha); Ex b: select valor_total, valor_pago, icms from notas_fiscais where... Esperando retornar várias ocorrências (linhas) desta consulta, cada coluna (valor_total, valor_pago, icms) será projetada como linha, barra ou coluna. Múltiplos selects: Digita-se vários selects, com condições diferentes, para projetar um dado (coluna) da mesma tabela, considerando faixas de dados diferentes. Ex. a: select coluna_a as Maria from tabela where... select coluna_a as Paulo from tabela where... select coluna_a as Joao from tabela where... Neste caso, cada coluna numérica (Maria, Paulo, Joao) será projetada como uma linha, ou uma barra ou uma coluna (planilha); Ex b: select valor_total as Maria from notas_fiscais where pessoa='maria'; select valor_total as Paulo from notas_fiscais where pessoa='paulo'; select valor_total as Joao from notas_fiscais where pessoa='joao'; Esperando retornar várias ocorrências de cada uma das três consultas acima, os Valores Totais de Maria serão projetados como uma linha *, os Valores Totais de Paulo serão projetados como outra linha * e os valores de Valores Totais de Joao serão projetados como uma outra linha *. Passo 2: Você poderá editar livremente os comandos SQL na área de edição de texto no centro da tela. Lembre-se de separar cada comando SQL com um ;. Você poderá utilizar livremene parâmetros nas consultas SQL. Sempre que o Agata detectar um parâmetro do tipo $Data, $Codigo, $AlgumaCoisa, abrirá uma janela para o usuario informar os reais valores no momento da execuçao do relatorio. Passo 3: Espaço reservado para escrever um texto introdutório que será colocado antes do gráfico gerado. Passo 4: Definição do título do Gráfico e da página. Passo 5: Definição do título do eixo X. Passo 6: Definição do título do eixo Y.
Passo 7: Geração do arquivo. Existem 3 tipos de saída: 7.a: Gráfico de Linhas É gerado um arquivo HTML que pode ser visualizado em um browser qualquer (Mozilla, Internet Explorer, Netscape, konqueror, Opera, Galeon), ou mesmo aberto em um aplicativo Office (MS-Office, StarOffice, OpenOffice). Obs. a.: Título do Gráfico. Obs. b.: Texto Introdutório. Obs. c.: Gráfico de Linhas. Obs. d.: Tabela com dados. 7.b : Gráfico de Barras É gerado um arquivo HTML que pode ser visualizado em um browser qualquer (Mozilla, Internet Explorer, Netscape, konqueror, Opera, Galeon), ou mesmo aberto em um aplicativo Office (MS-Office, StarOffice, OpenOffice). Obs. a.: Título do Gráfico. Obs. b.: Texto Introdutório. Obs. c.: Gráfico. Obs. d.: Tabela com dados.
7.c : Planilha Eletrônica É gerado um arquivo CSV (Comma Separated Values ou Valores separados por vírgulas), que pode ser aberto em qualquer planilha eletrônica (Excel, StarCalc, OpenOffice Calc, Gnumeric, Kspread). A planilha eletrônica a ser utilizada é configurada na tela inicial do Agata (Conexão ao Banco de Dados). O exemplo deste manual é com a planilha Kspread do Linux, veja como funciona: Passo 1: Selecionar um delimitador de arquivo. O delimitador normalmente utilizado é o ;, mas o Agata pode ser configurado (veja mais adiante na seção de confguração) para utilizar qualquer delimitador no momento de criar este arquivo. Passo 2: O arquivo é exibido na forma de planilha eletrônica, com separação de linhas e colunas. Veja abaixo, como era o arquivo gerado antes de ser aberto dentro da planilha eletrônica. empregado; valor; horas 20; 60,00; 2; 40,00; 40 3; 50,00; 40 4; 60,00; 40 5; 70,00; 40 6; 80,00; 40 7; 90,00; 40 8; 100,00; 40 9; 110,00; 40 10; 120,00; 40 11; 130,00; 40 12; 140,00; 40 13; 150,00; 40 14; 160,00; 40 15; 170,00; 40 1; 30,00; 40