SENIOR HCM: CONFIGURAÇÃO DE RELATÓRIOS EM TEXTO, MANIPULAÇÃO DE DATAS E FILTROS DINÂMICOS

A extração de dados no Senior HCM frequentemente ultrapassa a necessidade de visualização gráfica em tela ou impressos formatados. Muitas integrações corporativas, sistemas de folha, bancos e operadoras de benefícios exigem a exportação de informações cadastrais em formatos estruturados como TXT ou CSV delimitado.

Nesse cenário, a correta parametrização do modelo no Gerador de Relatórios exige atenção redobrada à estrutura de colunas, às regras de seleção e à manipulação de dados sensíveis, como variáveis do tipo data e códigos multiempresa.

Neste artigo, serão detalhados os procedimentos para configuração de relatórios em formato texto, a conversão segura de campos de data para comandos SQL e a injeção dinâmica de cláusulas de filtro por meio de código.

Por padrão, novos modelos no Gerador de Relatórios são criados sob a tipologia gráfica, voltada para impressão em formulários e visualização convencional. No entanto, o sistema disponibiliza a conversão direta do modelo para o modo Arquivo Texto, ajustando a régua de caracteres e os parâmetros da grade.

Principais distinções entre os dois modelos:

- Modo Gráfico: opera com medições em milímetros ou pixels, permitindo sobreposição visual, formatação avançada de fontes, cores e caixas decorativas.

- Modo Arquivo Texto: utiliza coordenadas rígidas de linhas e colunas de texto puro, dimensionando os campos estritamente pela quantidade de caracteres.

- Configuração de Altura: a altura da seção no modo texto é simplificada para a quantidade de linhas físicas impressas, reduzindo margens automáticas.

A escolha do modo texto é mandatória quando o objetivo final consiste no envio de remessas para outros softwares ou integração com interfaces de dados externas.

A manipulação de datas no Senior HCM possui particularidades que demandam cuidado no momento da escrita de regras e consultas SQL. No banco de dados e nos mecanismos internos da ferramenta, o formato de armazenamento pode divergir da representação textual habitual.

Ao comparar variáveis de entrada do tipo Data com comandos SQL diretos, ocorrem incompatibilidades de tipo entre dados alfanuméricos e numéricos internos:

- Armazenamento interno: internamente, o sistema trata datas sob contagem sequencial de dias, comportando-se matematicamente como um número.

- Incompatibilidade de concatenação: instruções SQL são montadas como sequências de caracteres (Alfa), exigindo a conversão expressa da variável de data antes da inclusão no comando.

- Função ConverteDataBanco: rotina nativa responsável por transformar o valor de data interna em uma cadeia textual compatível com a sintaxe do banco de dados (exemplo: YYYY-MM-DD).

A ausência dessa conversão resulta em erros graves de execução durante a montagem das diretivas de pesquisa no banco de dados.

Para evitar que consultas sejam enviadas ao banco com dados inconsistentes ou filtros em branco, é recomendável incluir validações prévias na regra de pré-seleção do modelo. A verificação do conteúdo digitado previne a extração incorreta de dados ou a lentidão decorrente da ausência de limitadores.

Boas práticas para consistência de parâmetros:

- Verificação de campos vazios: campos do tipo data recebem internamente o valor zero quando não preenchidos na tela de entrada.

- Uso de mensagens de retorno: funções de aviso, como Mensagem com parâmetro de retorno, comunicam o usuário sobre a obrigatoriedade do preenchimento.

- Cancelamento seguro: a aplicação do comando Cancel(1) encerra o processamento antes do envio da consulta ao servidor de banco de dados.

Essa blindagem assegura que relatórios críticos só sejam disparados mediante preenchimento adequado dos parâmetros operacionais.

O Gerador de Relatórios permite alterar dinamicamente a cláusula WHERE das seções por meio da função InsClauSql (Inserir Cláusula SQL). Com esse recurso, o desenvolvedor pode complementar a consulta nativa da seção com base nos filtros preenchidos na tela de entrada.

Aspectos importantes sobre a injeção dinâmica:

- Identificação da seção: a função requer a indicação exata do nome da seção de processamento, como a seção Detalhe_1.

- Concatenação do operador lógico: ao adicionar condições suplementares, deve-se incluir explicitamente os operadores lógicos, como AND, para evitar erros de sintaxe SQL.

- Flexibilidade de filtros opcionais: permite que determinados filtros só sejam adicionados à pesquisa caso o usuário preencha o campo respectivo na tela.

Essa técnica confere grande modularidade aos modelos, dispensando a criação de múltiplos relatórios para cenários de filtragem parecidos.

A extração de registros em intervalos temporais, como admissões ocorridas em um determinado mês, exige a combinação de limitadores de data inicial e final. Caso o usuário omita a data de término, é possível atribuir valores padrão de forma automática via regra.

Recursos úteis para preenchimento de períodos:

- Variável DatSis: variável de sistema que armazena a data corrente do servidor, ideal para preencher lacunas quando a data final não for informada.

- Condição de faixa de valores: estruturação de cláusulas no formato de data inicial maior ou igual e data final menor ou igual no comando SQL.

- Variáveis de referência: definição de parâmetros de entrada configurados como data de referência para carregar calendários automáticos.

A definição de regras inteligentes de contingência para campos em branco melhora a experiência de uso e diminui chamados de suporte.

Um erro frequente na elaboração de listagens no Senior HCM ocorre no relacionamento com cadastros compartilhados, como a tabela de centros de custo (R018CCU). Como o código do centro de custo pode se repetir entre diferentes empresas cadastradas, a ausência da empresa no vínculo distorce as descrições.

Cuidados ao correlacionar tabelas cadastrais filhas:

- Chave primária composta: atentar-se para relacionamentos que exigem o código da empresa (NumEmp) aliado ao identificador do objeto (CodCcu).

- Inclusão do campo da empresa na tela: manter a empresa disponível no relatório ou na tela de entrada para isolar com clareza o contexto dos dados.

- Visibilidade de campos: caso o dado da empresa seja usado apenas para relacionamento interno, a propriedade de impressão pode ser definida como Falso.

A correta correlação de chaves compostas garante a fidedignidade dos nomes e hierarquias corporativas emitidas na listagem.

A exportação de dados para planilhas ou sistemas legados comumente exige a separação de colunas por delimitadores, como ponto e vírgula (;). Em modelos de arquivo texto, a inserção desses separadores pode ser feita diretamente no layout da seção.

Diretrizes para montagem de arquivos delimitados:

- Alinhamento do cabeçalho: criação de seção do tipo Cabeçalho de Coluna com literais idênticos aos campos da seção Detalhe.

- Inserção de caracteres separadores: inclusão de campos de texto contendo apenas o delimitador (ponto e vírgula) posicionados entre cada coluna de informação.

- Saída em arquivo: configuração do formato de saída para disco ou geração em vídeo com posterior gravação com extensão .CSV.

Com esse dimensionamento detalhado de posições, o arquivo gerado abre perfeitamente tabulado em suítes de escritório como Microsoft Excel ou LibreOffice Calc.

Veja como esse conteúdo foi abordado na aula:

Acompanhe o roteiro passo a passo para configurar um relatório em arquivo texto com filtro dinâmico de admissão e exportação estruturada:

1. No Gerador de Relatórios, crie um novo modelo e utilize a opção de menu para salvá-lo no formato Arquivo Texto.

2. Adicione a tabela base de colaboradores (R034FUN) e a seção de tipo Detalhe_1.

3. Na Tela de Entrada do modelo, crie as variáveis do tipo Data denominadas EDatIni e EDatFim, representando o período de admissão desejado.

4. Crie uma variável Alfa para filtro de empresa (ENumEmp) e habilite o recurso de abrangência na tela de entrada.

5. Na regra de Pré-Seleção do relatório, declare as variáveis auxiliares alfanuméricas para conversão de dados e montagem de SQL.

6. Implemente a validação condicional: caso a variável EDatIni seja igual a zero, exiba mensagem de obrigatoriedade e interrompa com Cancel(1).

7. Se a variável EDatFim estiver vazia (igual a zero), atribua a ela o valor da variável de sistema DatSis para garantir o fechamento do período.

8. Converta as duas datas para o formato de banco por meio da função ConverteDataBanco, gravando os resultados em variáveis alfanuméricas.

9. Monte a cadeia de caracteres SQL contendo o intervalo da coluna DatAdm e injete na consulta utilizando a função InsClauSql("Detalhe_1", XSql).

10. No layout do relatório, insira as colunas de dados intercaladas com literais de ponto e vírgula, executando a emissão para gerar o arquivo CSV final.

O domínio sobre a criação de relatórios em modo texto amplia expressivamente o leque de soluções possíveis dentro do ecossistema Senior HCM. A capacidade de produzir arquivos estruturados elimina a dependência de processos manuais de exportação e formatação em planilhas eletrônicas.

A atenção ao tratamento de variáveis do tipo data e à injeção segura de cláusulas SQL por código garante flexibilidade sem comprometer a estabilidade do banco de dados relacional.

Por fim, respeitar a integridade das chaves compostas e a correta aplicação de delimitadores assegura a integração limpa de dados entre o Senior HCM e quaisquer ferramentas corporativas externas.