Tutorial Protheus
Note
Esse tutorial contem informações de como configurar um ambiente básico para desenvolvimento do Protheus utilizando Linux, ele considera a configuração local sendo que o recomendado é a utilização do ambiente com Docker para facilitar a configuração. Essa documentação é mantida como referência para entendimento da instalação do Protheus no Linux e dentro das imagens do Docker.
Para criar um ambiente de desenvolvimento Protheus no Linux alguns passos são necessários:
- Configurar banco de dados (Postgres)
- Configurar o unixODBC
- Configurar o DbAccess
- Configurar o Appserver
A configuração do Postgres pode ser feita de acordo com a distribuição Linux que esta sendo, uma vez instalado e configurado é possível acessar o banco de dados com a ferramenta que vem junto com o banco chamado psql, permitindo testar e configurar o banco de dados.
A configuração do unixODBC é feita instalando o driver ODBC do banco de dados que vai ser utilizado, no caso o Postgres, também efetuando a configuração do arquivo odbc.ini uma vez configurado o ODBC o teste de conexão pode ser feito com a ferramenta isql que conecta no banco passando pela infraestrutura do unixODBC.
Uma vez configurado o ODBC podemos configurar o dbaccess.ini que é o arquivo utilizado pelo DbAccess para conectar no banco através do unixODBC, configurando o dbaccess teremos um "alias" que permite acesso ao banco de dados através do Dbaccess.
Por fim podemos configurar o arquivo appserver.ini esse arquivo é utilizado pelo AppServer para configurar o ambiente de acesso ao Protheus. Esse arquivo possui muitas configurações mas iremos utilizar apenas as mais básicas para que seja possível o acesso.
Arquivos de configuração
A maior parte dos arquivos de configurações utilizados no ambiente Protheus são arquivos de configuração no formato INI, são arquivos de texto simples com uma organização específica, essa organização é simples e é composta de um várias seções, onde cada seção possui vários valores no formato chave e valor.
Aqui temos um exemplo de um arquivo ini de configuração que pode ser utilizado no unixODBC:
[Banco01]
DRIVER=/usr/lib64/psqlodbcw.so
SERVERNAME=localhost
PORT=5432
DATABASE=Protheus
USERNAME=postgres
PASSWORD=Senha.123
A marca no arquivo [Banco01] delimita uma seção no arquivo, todos os valores que estão abaixo da seção são chaves e valores dessa seção, uma seção existe até que outra seção seja encontrada no arquivo ou até o fim do arquivo. Podemos ter mais de uma seção no mesmo arquivo de configuração.
Cada aplicação sabe quais seções e chaves são necessárias para a sua configuração, qualquer seção e chave que a aplicação não conheça simplesmente não afeta seu funcionamento e é ignorada.
Configurando Postgres
A configuração do banco de dados Postgres se dá pela criação de um banco de dados e um usuário para a utilização da aplicação, essa configuração pode ser feita acessando o banco de dados com a sua própria aplicação de administração. Essa aplicação se chama psql no caso do Postgres sendo que outros bancos possuem outras aplicações e outras formas de configuração.
Para criação de um novo usuário e banco de dados na aplicação do Postgres devemos acessar a máquina que o Postgres esta instalado e fazer o acesso no banco pelo usuário postgres
psql -c "CREATE DATABASE protheus ENCODING 'WIN1252' TEMPLATE template0 LC_CTYPE 'C' LC_COLLATE 'C'"
psql -c "CREATE USER protheus WITH LOGIN NOSUPERUSER INHERIT CREATEDB NOCREATEROLE NOREPLICATION CONNECTION LIMIT -1 PASSWORD 'Protheus.123'"
psql -c "GRANT ALL PRIVILEGES ON DATABASE protheus TO protheus"
Para testar a configuração feita no banco de dados apenas informar qual o banco de dados, usuário e senha para o psql e verificar se a conexão com o banco é feita com sucesso.
Sendo o parâmetro -W força a solicitação da senha, primeiro parâmetro o nome do banco de dados, o segundo é o nome do usuário para conectar no banco de dados.
Configurando o unixODBC
A configuração do Unix é apenas a criação do arquivo de configuração /etc/odbc.ini com as informações válidas para conectar no banco de dados.
[Protheus]
DRIVER=/usr/lib64/psqlodbcw.so
SERVERNAME=localhost
PORT=5432
DATABASE=protheus
USERNAME=protheus
PASSWORD=Protheus.123
Para fazer o teste da configuração criada no /etc/odbc.ini apenas tentar conectar utilizando a ferramenta isql:
Caso conectar digitar quit para sair e conexão esta configurado com sucesso.
Configurando DbAccess
A instalação do DbAccess é feita apenas descompactando os binários do DbAccess em uma pasta de sua preferência. A configuração do Dbaccess é feita criando o arquivo dbaccess.ini na mesma máquina que o unixODBC foi configurado, apenas deixar o programa do DbAccess em execução para que o AppServer possa conectar nele.
Note
Diferentes Linux têm diferentes métodos de inicialização de serviços, a grande maioria atualmente utilizam um método chamado systemd para gerenciar os serviços em execução, mas isso é inclusive configurável. Para efeito de testes apenas iremos iniciar o ./dbaccess64 manualmente para ambiente de desenvolvimento.
Caso queria uma execução de longa duração para o DbAccess em sua distribuição, verificar na documentação oficial como configurar os serviços.
O arquivo de configuração dbaccess.ini pode ser criado manualmente em um editor de texto assim como qualquer outro arquivo de configuração, porem esse arquivo conta com uma peculiaridade, a chave password do arquivo de configuração possui uma criptografia o que inviabiliza criar o arquivo de configuração manualmente por um editor
Para a criação do arquivo vamos utilizar uma ferramenta chamada dbaccesscfg que vem junto dos binários do DbAccess, irei passar um exemplo da sua execução colocando quebra de linhas e uma explicação de seus parâmetros.
A linha 2 informa qual o usuário do banco de dados Postgres
A linha 3 informa qual a senha do usuário do banco de dados Postgres
A linha 4 informa qual o nome do alias que será criado no dbaccess.ini esse alias precisa ter o mesmo nome que a seção do odbc.ini
A linha 5 informa qual o tipo de banco que esta sendo utilizado podendo ser postgres/mssql/oracle entre outros documentando no TDN.
A linha 6 informa qual a biblioteca que o DbAccess vai utilizar para conectar no banco de dados.
Uma vez configurado o dbaccess.ini apenas executar o binário do dbaccess que se encontra dentro da pasta multi do pacote, uma vez que o programa estiver executando deixar ele executando sem ser finalizado:
Configurando AppServer
Para configurar o AppServer é necessário um conjunto de arquivos além de um arquivo de configuração appserver.ini, os arquivos necessários são:
- Biblioteca do webapp.so
- Repositório de Objetos (tttm120.rpo)
- Arquivos de dicionário (sxsbra.txt e sx2.unq)
- Arquivos de menu (com extensão .xnu)
- Arquivos de help (hlpeng.txt hlpspa.txt e hlppor.txt)
Antes de discutir onde os arquivos devem ser colocados para configurar o ambiente, vamos ver a configuração do arquivo appserver.ini porque os diretórios que esses arquivos devem ser copiados dependem dos caminhos configurados.
Para copiar os arquivos vamos primeiro criar a seguinte estrutura de arquivos:
mkdir -p /opt/totvs/protheus/apo/
mkdir -p /opt/totvs/protheus/protheus_data/system/
mkdir -p /opt/totvs/protheus/protheus_data/systemload/
O arquivo de biblioteca do WebApp deve ser colocado na mesma pasta que o binário do AppServer no caso o binário appsrvlinux.
Os arquivos sxbra.txt, sx2.unq, hlppor.txt, hlpeng.txt e hlpspa.txt devem ser colocados em um diretório chamado systemload dentro do diretório protheus_data. O diretório protheus_data é configurado dentro do appserver.ini na chave rootpath dentro da seção environment.
Os arquivos de menu com a extensão .xnu devem ser colocados dentro do diretório startpath que foi configurado dentro do appserver.ini, esse é o caminho que foi configurado na chave startpath dentro da seção environment, esse path é relativo à chave rootpath.
Por fim o arquivo de repositório (tttm120.rpo) deve ser colocado na pasta apo, que foi configurada na chave sourcepath dentro da sessão environment, o nome do arquivo.
Algumas informações adicionais devem ser observadas como a configuração do DbAccess que o Appserver ira utilizar, essa informação é configurada na sessão environment e são as chaves iniciadas com db.
Na linha 8 temos a chave dbdatabase que informa qual o tipo de banco que deve ser utilizado (é o mesmo que o parâmetro -d do dbaccesscfg).
Na linha 9 temos a chave dbalias que tem o alias que configuramos no DbAccess (é o mesmo que o parâmentro -a do dbaccesscfg).
Na linha 10 temos o endereço por nome ou ip do servidor do DbAccess, caso senha a mesma máquina pode ser colocado localhost.
Na linha 11 temos a porta que o DbAccess foi configurado, caso não tenha sido especificado é a porta 7890.
Na linha 34 temos o endereço de conexão do lockserver, normalmente em ambiente de desenvolvimento pode ser o endereço ip ou hostname da própria máquina do appserver, não pode ser colocado como localhost.
Com o arquivo de configuração do AppServer foi criado corretamente, apenas iniciar o servidor do AppServer para receber novas conexões:
Apenas utilizar seu browser para acessar a porta 8080 que é a porta do WebApp que foi configurado no appserver.ini