SAGE

SISTEMA ABERTO DE GERENCIAMENTO DE ENERGIA

Manual de Aplicativo

AQ_TimeServ
SAGE_ManApl_AQTimeServ.doc

Janeiro de 2013
 Quadro de Revisão

Nº Data Descrição Versão

00 07/01/2013 Versão Inicial

Preparado por:

21.941-911 • Av. Horácio de Macedo, 354 • Rio de Janeiro - RJ

Tel.: (021) 2598-6000 • Fax: (021) 2260-1340

A informação contida neste documento é de propriedade do CEPEL, tendo se originado de trabalho desenvolvido nesta empresa para consulta e
referência dos usuários do sistema SAGE, e não poderá ser reproduzida ou utilizada para quaisquer outros fins sem autorização prévia e
expressa do CEPEL. Este documento baseia-se em informação disponível na data de sua publicação. Embora sejam feitos esforços para
torná-lo preciso, este não se propõe a cobrir todos os detalhes ou particularidades apresentadas pelo sistema. O CEPEL não se responsabiliza
por notificar os usuários deste documento de possíveis alterações feitas posteriormente.
Conteúdo
1 SOBRE ESTE DOCUMENTO ................................................................................. 1

2 O APLICATIVO AQ_TIMESERV ............................................................................. 3

3 FORMATOS DE MENSAGEM................................................................................. 5

4 CHAMADA DO APLICATIVO ................................................................................. 7

5 FORMATO DO ARQUIVO DE CONFIGURAÇÃO ..................................................... 9

iii
CONTEÚDO

iv
 Capítulo

1
1 Sobre este Documento
O presente manual descreve o aplivativo AQ_TimeServ, responsável por obter informações de
hora e de frequência da rede provenientes do servidor de hora Modelo 7001GPS da Hopf Elektronik
GmbH. São descritos a forma de operação do aplicativo, as opções que ele aceita em linha de
comando e o formato de seu arquivo de configuração.

1
1 SOBRE ESTE DOCUMENTO_SAGE

2
 Capítulo

2
2 O aplicativo AQ_TimeServ
O aplicativo AQ_TimeServ, que compõe a suíte de aplicativos do SAGE, é responsável por obter a
frequência da rede, a hora do sistema e a diferença entre a hora da rede e a hora do sistema através
do recebimento de mensagens geradas por um ou mais servidores de hora de modelo 7001 da hopf.
Os formatos das mensagens devem estar de acordo com os gerados pela placa de interface modelo
7201 deste fabricante, placa esta que atua como um módulo de interface para os servidores de hora
em questão.
O aplicativo AQ_TimeServ atua em uma arquitetura cliente-servidor, em que que o aplicativo faz o
papel do cliente. No arquivo de configuração do aplicativo, são especificados o endereço IP e a porta
dos hosts com os quais ele tentará estabelecer conexão no intuito de obter as informações
desejadas. Uma vez estabelecida uma conexão, ele entra em um loop de leitura das mensagens
transmitidas pelo equipamento, extraindo delas as informações desejadas e atualizando a base de
dados do SAGE com seus valores.
Deve ser observado que a placa modelo 7201, que gera as mensagens a serem lidas pelo
aplicativo, não possui interface de rede. As mensagens geradas são transmitidas pela placa através
de uma de suas três interfaces seriais existentes: RS232c, RS422 ou TTY. Assim sendo, para que o
aplicativo AQ_TimeServ possa obter as informações desejadas, é necessário que as ligações de rede
entre o servidor de hora e as máquinas SAGE que rodam o aplicativo se dêem através de terminals
servers, em portas configuradas para aceitar conexões via socket protocol.
A operação do aplicativo se dá da seguinte forma: uma vez inicializado, ele tenta se conectar ao
1
primeiro dos servidores de hora configurados . Em caso de erro na conexão, ele tenta o próximo
servidor, e assim sucessivamente, até que tenham falhado as tentativas com todas as máquinas
2
cadastradas. Quando isso ocorre, o aplicativo aguarda um certo período de tempo , antes de tentar
se conectar novamente, repetindo este processo continuamente.
Em caso de sucesso no estabelecimento de conexão com um dos servidores, o aplicativo passa a
ler as mensagens por ele enviadas. Com base em seu conteúdo, as informações a serem repassadas
3
ao SAGE são atualizadas e repassadas a ele a intervalos de tempo regulares . Esta dissociação
entre a obtenção dos valores de interesse e seu posterior envio ao SAGE é realizada para evitar

1 Especificado na seção [HOSTS] do arquivo de configuração.

2 Especificado através do parâmetro WAIT_SERV.

3 Especificado através do parâmetro UPDT_PER.

3
2 O APLICATIVO AQ_TIMESERV_SAGE

desperdício de recursos caso a frequência de recebimento das mensagens seja muito maior do que a
taxa de atualização especificada.
As informações que podem ser obtidas pelo aplicativo são as seguintes:
4
■ Até 4 valores de frequência da rede.

■ A hora do sistema, no padrão UTC (Coordinated Universal Time). O aplicativo se encarrega

de transformar horas locais na hora universal, caso necessário, podendo até lidar com o
caso de o servidor de hora estar localizado em um fuso horário diferente do da máquina
local.

■ A diferença entre a hora do sistema e a hora da rede (obtida por intermédio da freqüência
medida da linha). Esta diferença de hora é apresentada em milissegundos.

■ A quantidade de mensagens recebidas do servidor no decorrer do último minuto.

■ A quantidade de escritas realizadas na base de dados do SAGE no decorrer do último

minuto.

A leitura das mensagens de um servidor de hora é feita continuamente até a ocorrência de um dos
seguintes eventos:
■ Recebimento de um pedido de finalização do programa;

■ O fechamento da conexão de dados;

■ Um erro na leitura de dados desta conexão;

■ Um timeout no aguardo de mensagens do servidor;

■ O recebimento de algum caracter inválido na mensagem;

■ A incapacidade de se estabelecer um ponto de sincronismo na mensagem (ou seja, de se

definir onde a mensagem começa e onde ela termina);

■ A verificação de erros na estrutura das mensagens recebidas.

À exceção dos cinco primeiros, que bastam ocorrer uma vez para que ocorra o encerramento da
conexão de dados, os dois últimos eventos podem ocorrer até três vezes antes que se tente obter
dados de outro servidor. Fechada a conexão, novas tentativas de conexão são realizadas com os
servidores cadastrados, a partir do servidor posterior a este último, em um processo contínuo.
A finalização do aplicativo se dá quando da chegada de um pedido de término do programa,
enviado através do sinal SIGTERM.

4 Os valores de frequência são obtidos por intermédio de placas de modelo 7515 da hopf presentes no
servidorde hora. Deve haver uma placa para cada frequência informada.

4
 Capítulo

3
3 Formatos de mensagem
5
O aplicativo AQ_TimeServ reconhece os seguintes formatos de mensagem:
■ hopf Net Time A;

■ hopf Net Time B;

■ KIA;

■ ABB Network Manager;

■ FTM-III.

As mensagens são transmitidas em ASCII, com os caracteres codificados em BCD. Diferentes

formatos de mensagem carregam consigo diferentes conjuntos de informação. A título de ilustração,
tem-se que no formato hopf Net Time A são enviados os seguintes dados:
■ Data (horas, minutos, segundos, dia, mês, ano e dia da semana);

■ Estado da hora informada;

■ Frequência da rede;

■ Hora da rede;

■ Diferença entre a hora da rede e a hora do sistema.

Enquanto que o formato KIA contém as seguintes informações:

■ Data (horas, minutos, segundos, dia, mês e ano);

■ Estado da hora informada;

■ Número da placa de leitura de frequência;

■ Frequência da rede.

5 Os formatos de mensagem aqui mencionados podem ser consultados no Manual “7201NET Interface
Board“,da hopf. Na data de confecção deste manual, o documento em questão podia ser obtido no endereço
http://www.hopf.com/manuals/english/pdf_7---/e7201-power-line-supervision_0300.pdf.

5
3 FORMATOS DE MENSAGEM_SAGE

onde os dois últimos campos podem se repetir por até 4 vezes, o que permite a transmissão até 4
6
frequências de rede distintas.
Independentemente do formato de mensagem utilizado, o aplicativo AQ_TimeServ está preparado
para receber mensagens com as seguintes características:
■ Mensagens iniciadas pelo caractere de controle STX (Start of TeXt), e finalizadas pelo
caractere de controle ETX (End of TeXt).

■ Mensagens iniciadas pelo caractere de controle STX, e finalizadas, quando da ocorrência

de um segundo cheio, pelo caractere de controle ETX.

■ Mensagens sem os caracteres de controle STX e ETX.

Além disso, os delimitadores das linhas presentes no corpo das mensagens podem ser de
dois tipos:
■ Formados pelo conjunto CR + LF (Carriage Return e Line Feed), a exemplo do praticado em
sistemas Windows/DOS.

■ Indicados pelo caractere LF, a exemplo do praticado em sistemas do tipo Unix.

As questões relativas ao formato das mensagens recebidas, a presença, ou não, dos caracteres
de controle e a forma de representação de uma nova linha, entre outras, são configuradas para cada
servidor de hora através do arquivo de configuração do aplicativo.

6Estas frequências são medidas através das placas de modelo 7515 presentes no servidor de hora. O
equipamento comporta até 4 placas deste tipo.

6
 Capítulo

4
4 Chamada do Aplicativo
A chamada do aplicativo AQ_TimeServ em linha de comando segue o seguinte formato:
AQ_TimeServ [-d [-d ..]] [-h] [-a <nome>] [-c <config>] [-o <saida>][-l <log>]

Onde:
■ -d – Ativa depuração do aplicativo. Esta opção pode ser especificada mais de uma vez, o
que causa o incremento do nível de depuração do aplicativo, tornando-o cada vez mais
verborrágico. Na atual versão do programa são definidos três níveis de depuração.

■ -h – Imprime tela de ajuda.

■ -a <nome> – Permite a alteração do nome com que o aplicativo tentará se cadastrar junto
ao SAGE. Isso afetará o nome apresentado nas mensagens de log geradas, bem como o
nome do arquivo de configuração a ser utilizado caso a opção -c não seja especificada.

■ -c <config> – Indica o nome do arquivo de configuração a ser utilizado. Caso não seja
especificado, será buscado um arquivo de configuração de nome {\it<nome>}.conf, onde
<nome> representa o nome do aplicativo em questão (que pode ser alterado através da
opção -a, conforme citado anteriormente). Caso o nome indicado não contenha nenhuma
informação de caminho, o arquivo será procurado no diretório apontado pela variável de
ambiente BD, e, se não encontrado, no diretório corrente.

■ -o <saida> – Caso esta opção seja especificada, é criado um arquivo, de nome <saida>,
onde serão escritas as mensagens recebidas pelo programa.

■ -l <log> – Indica o nome do arquivo a ser gerado com mensagens de log. Caso o argumento
seja especificado, e o nome fornecido não contenha informações de caminho, então o
arquivo será criado no diretório indicado pela variável de ambiente LOG.
Independentemente da especificação desta opção, as saídas de log são também
direcionadas para stdout e para o log do sistema.

O aplicativo responde, ainda, ao seguinte sinal:

■ SIG_USR1 – Habilita ou desabilita a impressão, em stdout, dos valores obtidos através das
mensagens recebidas.

7
4 CHAMADA DO APLICATIVO_SAGE

8
 Capítulo

5
5 Formato do Arquivo de
Configuração
A configuração de AQ_TimeServ é dada por um arquivo texto normal. Neste, linhas iniciadas por #
são desconsideradas, podendo ser utilizadas para fins de comentário. O arquivo de configuração é
dividido em seções, iniciadas e finalizadas pelos padrões [<nome>] e [n<nome>] no início de suas
respectivas linhas, onde <nome> representa o nome da seção. Dentro de cada seção são definidas
uma ou mais variáveis, sob a forma
VAR = valor

onde VAR representa a nome da variável e valor, seu valor.

O arquivo de configuração de AQ_TimeServ é dividido em 3 seções: uma de configuração geral do
aplicativo, outra de mapeamento dos valores adquiridos nos pontos do SAGE, e uma terceira de
cadastro dos servidores de hora com os quais o aplicativo deverá se conectar.
A seção de configuração geral é demarcada pelos padrões [CONFIG] e [nCONFIG]. Nesta seção
são definidas as seguintes variáveis:

■ SRV_TOU – Indica o timeout para recebimento de uma mensagem válida de um servidor,

em milissegundos. O valor a ser fornecido deve ser do tipo inteiro. A especificação desta
variável é obrigatória.

■ UPDT_PER – Indica o período de atualização da base do SAGE com as informações

obtidas dos servidores de hora, em milissegundos. O valor a ser fornecido deve ser do tipo
inteiro. A especificação desta variável é obrigatória.

■ INV_TOUT – Indica o timeout para invalidar os últimos dados recebidos de um servidor, em

milissegundos. O valor a ser fornecido deve ser do tipo inteiro. Caso não seja
especificado, é definido para esta variável um valor 4 vezes maior do que o especificado
para UPDT_PER.

■ WAIT_SRV – Indica o tempo a ser esperado, em segundos, antes de o aplicativo prosseguir

com as tentativas de estabelecimento de conexão com os servidores cadastrados. Esta
espera ocorre quando já foram tentadas conexões com todos os servidores, sem sucesso.
O valor para esta variável deve ser do tipo inteiro. Caso não seja especificada, é assumido
para esta variável o valor padrão de 1.

9
5 FORMATO DO ARQUIVO DE CONFIGURAÇÃO_SAGE

■ LINE_FREQ – Indica a frequência nominal da rede, em Hz. Este campo necessita ser
especificado apenas no caso de se utilizar o formato FTM-III e a frequência nominal da
rede ser diferente de 60 Hz. O valor para esta variável deve ser do tipo inteiro.

■ FUSO – Indica o fuso horário da máquina local, em relação ao horário UTC. Caso não seja
especificado, este valor é obtido do próprio sistema local. O valor para esta variável deve
ser uma string de formato [UTC][+][-]h[h][[:]mm].

■ DST – Indica o valor de ajuste da hora local quando no horário de verão. Caso
especidficado, o valor para esta variável deve ser uma string de formato h[h][[:]mm]. Caso
a variável não seja definida, assume-se para esta variável o valor de 01:00, indicando que,
durante o horário de verão, a hora local deverá ser acrescida de 60 minutos.

A segunda seção presente no arquivo de configuração, responsável pelo mapeamento dos valores
obtidos pelo aplicativo nos pontos do SAGE, é delimitada pelos padrões [SAGE] e [nSAGE]. Nesta
seção podem ser definidas as seguintes variáveis:

■ FREQ1_ID – Nome do ponto analógico do SAGE que armazena o valor da frequência

medida pela placa modelo 7515 de identificador 1. O valor desta variável é do tipo string.
Sua especificação não é obrigatória.

■ FREQ2_ID – Nome do ponto analógico do SAGE que armazena o valor da frequência

medida pela placa modelo 7515 de identificador 2. O valor desta variável é do tipo string.
Sua especificação não é obrigatória.

■ FREQ3_ID – Nome do ponto analógico do SAGE que armazena o valor da frequência

medida pela placa modelo 7515 de identificador 3. O valor desta variável é do tipo string.
Sua especificação não é obrigatória.

■ FREQ4_ID – Nome do ponto analógico do SAGE que armazena o valor da frequência

medida pela placa modelo 7515 de identificador 4. O valor desta variável é do tipo string.
Sua especificação não é obrigatória.

■ HORA_ID – Nome do ponto totalizado do SAGE que armazena a hora do sistema. O valor
desta variável é do tipo string. Sua especificação não é obrigatória.

■ DIF_HORA_ID – Nome do ponto analógico do SAGE que armazena a diferença da hora do

sistema para a hora de rede, em quantidade de milissegundos. O valor desta variável é do
tipo string. Sua especificação não é obrigatória.

■ NMSGS_ID – Nome do ponto analógico do SAGE que armazena a quantidade de

mensagens provenientes do servidor recebidas no último minuto. O valor desta variável é
do tipo string. Sua especificação não é obrigatória.

10
5 FORMATO DO ARQUIVO DE CONFIGURAÇÃO_SAGE

■ NWRS_ID – Nome do ponto analógico do SAGE que armazena o número de escritas

realizadas na base de dados do SAGE no decorrer do último minuto. O valor desta
variável é do tipo string. Sua especificação não é obrigatória.

Apesar de não ser necessária a definição de nenhuma variável específica, caso nenhuma delas
seja definida, o programa será finalizado com erro. Caso o nome de um ponto do SAGE seja
fornecido, é necessário que ele esteja presente na base de dados utilizada e possua o tipo correto.
Na terceira e última seção do arquivo de configuração, delimitada pelos padrões [HOSTS] e
[nHOSTS], são cadastrados os servidores com os quais o aplicativo tentará estabelecer conexão.
Podem ser definidos um ou mais servidores de hora, não havendo um limite máximo para o
número de servidores a serem inseridos.
Para cada servidor cadastrado, podem ser especificados os seguintes campos:

■ HOST – Informa o nome ou o endereço IP do host com o qual o aplicativo tentará

estabelecer conexão. Este campo é obrigatório, marcando o início da especificação de um
novo servidor e finalizando a configuração do servidor anterior, se houver. O valor desta
variável é do tipo string.

■ PORT – Informa a porta do servidor pela qual se tentará estabelecer a conexão. Este
campo é opcional, possuindo um valor padrão de 3333. O valor deste campo é do tipo
inteiro.

■ FMT – Indica o formato da mensagem a ser lida. Este campo pode assumir os seguintes
valores:

– HOPF-A – Indica que a mensagem recebida é do formato hopf Net Time A;

– HOPF-B – Indica que a mensagem recebida é do formato hopf Net Time B;

– KIA – Indica que a mensagem recebida é do formato KIA;

– ABB – Indica que a mensagem recebida é do formato ABB Network Manager;

– FTM-III – Indica que a mensagem recebida é d formato FTM-III.

A especificação deste campo é obrigatória.

■ CTRL_CHRS – Indica se os caracteres de controle STX (Start of TeXt) e ETX (End of TeXt)
são enviados no início e no final da mensagem. O valor desta variável é do tipo booleano,
podendo assumir os valores true (verdadeiro) e false (falso). O valor verdadeiro indica que
os caracteres de controle em questão são transmitidos, sendo este o valor assumido caso
o campo não seja especificado.

■ CRLF – Indica se uma mudança de linha na mensagem recebida é caracterizada pelo

padrão CR + LF ou pelo padrão LF. O valor desta variável é do tipo booleano, em que true

11
5 FORMATO DO ARQUIVO DE CONFIGURAÇÃO_SAGE

(verdadeiro) implica a primeira opção, e false (falso), na segunda. Caso não seja
especificada, é assumido para este campo o valor verdadeiro.

■ SEC_CHG_ETX – Indica se o caracter de controle ETX é enviado em todo final de

mensagem ou apenas quando da virada do segundo. O valor desta variável é do tipo
booleano, em que o valor true (verdadeiro) indica envio apenas no segundo cheio, e false
(falso) indica envio constante. Caso não seja especificada, este campo assume o valor
falso. Este campo só faz efeito quando o campo CTRL_CHRS possui valor verdadeiro.

■ NUM_FREQS – Indica o número de frequências apresentadas na mensagem recebida

deste servidor de hora. O valor deste campo é do tipo inteiro; caso não seja definido, é
assumido para ele o valor 1. Este valor é apropriado para todos os formatos de mensagem
suportados, à exceção do formato KIA, que comporta de 1 a 4 valores de frequência
distintos.

■ FUSO – Indica o fuso horário do local em que o servidor de hora está situado em relação ao
horário UTC (Coordinated Universal Time). Caso não seja especificado, é assumido que o
fuso horário do servidor é igual ao da máquina local (cliente). Caso especificado, o valor
desta variável deve ser uma string de formato [UTC][+][-]h[h][[:]mm].

■ DST – Indica o valor de ajuste da hora quando no horário de verão. Caso não seja
especificado, é assumido que seu valor é igual ao do campo DST da máquina local. Este
campo deve ser preenchido com uma string de formato h[h][[:]mm]. Para desabilitar a
variação de hora local do servidor quando no horário de verão, pode-se especificar este
campo com o valor 0.

■ FREQ_BD – Informa o identificador da placa responsável pela obtenção do valor da

freqüência transmitido na mensagem. Este campo só deve ser preenchido se o formato da
mensagem em questão não for do tipo KIA, uma vez que, neste formato, o identificador da
placa é transmitido no corpo da mensagem. O valor para este campo deve ser um número
inteiro compreendido entre 1 e 4. Se o valor não for especificado, é assumido para ele o
valor 1.

Abaixo é mostrado um exemplo de um arquivo de configuração para AQ_TimeServ:

# AQ_TimeServ . conf
#
# Arquivo de configuração de AQ_TimeServ .
#
# ----------------------------------------------------------------------------
# Seção de configuração geral
#
# Programado timeout de 3 segs . para o recebimento de mensagens do
# servidor . O banco de dados do SAGE deve ser atualizado a cada 100
# ms , sendo que, 1 seg . após a última mensagem recebida , os dados

12
5 FORMATO DO ARQUIVO DE CONFIGURAÇÃO_SAGE

# presentes são invalidados . O aplicativo deve aguardar 2 segs . antes

# de tentar nova conexão com os servidores de hora em caso de falha de
# conexão com o conjunto de servidores cadastrados.
#
[CONFIG]
SRV_TOUT = 3000
UPDT_PER = 100
WAIT_SRV = 2
INV_TOUT = 1000
[ \CONFIG]
# # --------------------------------------------------------------------------
# Seção de mapeamento das informações adquiridas nos pontos do SAGE.
#
[SAGE]
FREQ1_ID = PAS_FREQ_BARRA_1
FREQ2_ID = PAS_FREQ_BARRA_2
FREQ3_ID = PAS_FREQ_BARRA_3
FREQ4_ID = PAS_FREQ_BARRA_4
HORA_ID = PTS_HORA_SIS
DIF_HORA_ID = PAS_DIF_HORA_MS
NMSGS_ID = PAS_NMGS
NWRS_ID = PAS_NWRS
[ \SAGE]
# # --------------------------------------------------------------------------
# Seção para o cadastro dos servidores de hora.
#
# Neste exemplo são de finidos dois servidores de hora , tserv1 e
# tserv2 , em configuração de failover , enviando mensagens no formato
# Hopf Net A, com caracteres de controle, final de linha indicado por
# CRLF e transmissão de ETX ao final de cada mensagem.
#
[HOSTS]
HOST = t s e rv1 . domain . br
PORT = 3330
FMT = HOPF_A
CTRL_CHRS = t r u e
CRLF = t r u e
SEC_CHG_ETX = f a l s e
FREQ_BD = 1
HOST = t s e rv2 . domain . br
PORT = 3330
FMT = HOPF_A
CTRL_CHRS = t r u e
CRLF = t r u e
SEC_CHG_ETX = f a l s e
FREQ_BD = 1

13
5 FORMATO DO ARQUIVO DE CONFIGURAÇÃO_SAGE

[ \HOSTS]

14