Exibir código-fonte para Pacote de troca de dados

Para que se possa efetivar algum tipo de cooperação ou intercâmbio de serviços, seja no tratamento ou uso das informações, como no caso de BIREME e SciELO, um processo seguro de intercâmbio de dados deve ser suprido, o que resulta neste '''pacote de troca de dados'''.

Como a experiência mostrou que, o uso simplório do FTP (protocolo e ferramenta) não garante que os dados tenham a qualidade desejada após sua ''viagem'' pelos meios de comunicação, por vezes melhor seria continuar, ou concluir, determinados processamentos com um conjunto de dados desatualizado, mas não deteriorado.


__TOC__

== Objetivos ==
* Viabilizar a independência de intervenção humana nas trocas de dados entre BIREME e SciELO
* Garantir o intercâmbio de dados livre de falhas
* Prover o suprimento de dados mesmo na ausência de conectividade
* Definir um protocolo de troca de dados entre entidades

== Recursos e Tecnologias Necessários ==
* Conexão ativa com Internet para consulta a URL http://homolog.webservices.scielo.org/scieloorg/_design/couchdb/_view/network, que reporta instâncias SciELO e seus respectivos ''status'';
* Servidor de FTP próprio de cada instituição (SciELO e BIREME);
* Espaço de disco dos servidores de ao menos 100G bytes;
* Ambiente operacional Linux (interpretador bash versao 3 ou superior);
** Pacotes mínimos: tar; gzip; md5sum; cisis*; python (com módulo JSON).

 * utilitários cisis do 'sabor' necessário em diretório que conste no 'path' da máquina

== Delimitações Gerais ==
* Operação humana ou automática (por crontab)
* Rotinas de Envio e Recepção separadas (formando um pacote)
* Arquivos de configuração (do tipo texto plano)
* Possibilidade de uso de ''argumentos'' de chamada
* Auto-ajuste da operação por sensoriamento de ambiente (inclusão / exclusão de diretórios de dados)

== Padrões aplicáveis ==
São aplicáveis os padrões internos de desenvolvimento de shell-scripts, prevendo chamadas ao mecanismo de LOG (source log ou . log) e interrupção de fluxo por falha/erro de execução, além do cabeçalho padronizado no arquivo de modelo de shell existente no diretório de miscelâneas do caminho /usr/local/bireme/misc

== Aplicabilidade ==
Este pacote poderá ser utilizado em duas situações de troca de dados a saber:
# trocas de dados entre BIREME e SciELO;
# trocas de dados entre SciELO e componentes de sua rede.
Para tanto basta efetuar ajustes no arquivo de configuração anteriormente citado.

Atualmente emprega-se Envia2Medline.bat para efetuar parte do descrito aqui e será substituído por envia2ORG.sh, que passará a ser parte integrante do pacote de distribuição.

== Descrição do Protocolo Básico ==
O protocolo de envio e recepção de pacotes de dados a ser implementado tem por objetivo garantir a entrega de dados do enviador para o recebedor, de tal forma que se alguma disfunção no processo ocorrer, e for possível detectá-la, o último pacote de dados enviado com sucesso será entregue no lugar do atual, ficando assim garantida a operação dos processos onde se inclue a recepçao de dados pelo uso deste protocolo.

Para tanto uma sequência de ações deve ser executada de cada lado do meio de transmissão. São tarefas do enviador:
# Verificar se o diretório de destino existe;
## Caso não exista deve cria-lo;
# Testar se no diretório de destino o semáforo "IN-USE" está ativo;
## Caso esteja, testar esta condição até "X" (configurável) vezes;
### Caso continue "IN-USE" termina a execução com saída de erro;
# Eliminar (caso exista) o semáforo "DATA-READY";
# Para cada item da "SEND-LIST" gerar um arquivo MD5;
# Empacotar os componentes da lista de envio com os arquivos MD5 gerados em um tar-ball compactado (tgz);
# Escrever o tar-ball compactado no diretório do servidor de ftp;
# Ativar o semáforo "DATA-READY";
# Fim de tarefa de envio.
São tarefas do recebedor:
# Testar se existe o diretório esperado para receber os dados (informado por parâmetro de chamada);
## Caso não exista termina a execução com saída de erro;
# Testa se existe semáforo "DATA-READY" ativo no diretório
## Caso não exista, testar esta condição até "Y" (configurável) vezes;
### Caso continue não existindo termina execução com saída de erro;
# Ativar semáforo "IN-USE"
# Elimina o flag "DATA-READY" (não implementado por haver dois receptores de dados);
# Le o tar-ball compactado disponível no diretório;
# Após a leitura do tar-ball compactado, eliminar o semáforo "IN-USE";
# Descompactar e abrir o tar-ball;
# Testar o MD5 de cada componente recebido;
## Aqueles que tiverem resultado Ok devem ser enviados para o servidor de ftp em subdiretório específico para reserva de dados;
## Aqueles que tiverem resultado Nok devem ser eliminados e subtituídos pelos correspondentes encontrados no subdiretório de reserva de dados existente no servidor de ftp.

== Interface de Usuário ==
Como chamadas de linha de comando podem ser utilizadas opções e parâmetros nas chamadas tanto do envio quanto da recepção de dados, como se observa na sintaxe a seguir:

=== Envio de Dados ===
  envia2.sh <nowiki>[[-h|--help]|[-v|--version]|[-c config_file]]</nowiki> <Sigla3_SciELO> <arquivo_controle>

envia2.sh : script-shell que desempenha todas as tarefas de envio de pacote de dados, como cálculo de MD5 e empacotamento compactado em arquivo tar

 opções:
  -h | --help    - tela de ajuda para uso do comando
  -v | --version - exibe a versão do comando em execução, sua data e responsável
  -c <arquivo>   - aplica as configurações do arquivo indicado ao invés daquelas do arquivo padrão (vaivem.conf)
 
 parâmetros:
  Sigla3_SciELO    - (mandatório) uma das diversas siglas de três letras que identificam instâncias do SciELO
                     (scl=Brasil; spa=Saúde Pública; sss=Social Sciences; sza=África do Sul; ...)
  arquivo_controle - (mandatório) arquivo texto com o nomes dos arquivos a serem enviados, um por linha

=== Recepção de Dados ===
  recebf.sh <nowiki>[[-h|--help]|[-v|--version]|[-c config_file]]</nowiki> <Sigla3_SciELO>

recebf.sh : script-shell que desempenha todas as tarefas de recebimento de pacote(s) de dados, com descompactação e desempacotamento de arquivo tar mais a conferência de MD5

 opções:
  -h | --help    - tela de ajuda para uso do comando
  -v | --version - exibe a versão do comando em execução, sua data e responsável
  -c <arquivo>   - aplica as configurações do arquivo indicado ao invés daquelas do arquivo padrão (vaivem.conf)
 
 parâmetros:
  Sigla3_SciELO - (mandatório) uma das diversas siglas de três letras que identificam instâncias do SciELO
                  (scl=Brasil; spa=Saúde Pública; sss=Social Sciences; sza=África do Sul; ...)

== Plano de Desenvolvimento ==
O desenvolvimento do par de rotinas será dividido em três etapas:
* Etapa 1 - Comando de Envio de Dados;
* Etapa 2 - Comando de Recepção de Dados;
* Etapa 3 - Atividades complementares.
===Etapa 1 - Comando de Envio de Dados===
O desenvolvimento do comando de envio de dados teve três (3) fases (cada qual com sua bateria de testes funcionais):
* Fase 1 - implementação de funções acessórias;
* Fase 2 - núcleo básico de empacotamento;
* Fase 3 - automação de envio.
====Fase 1 - Implementação de funções acessórias====
Aqui foram implementadas as capacidades de interpretação de opções, ou seja, utilização de um arquivo de configuração diverso do padrão por omissão (vaivem.conf), exibição de ajuda ao uso do comando, além do exibidor de versão.

====Fase 2 - Núcleo Básico de Empacotamento====
Nesta fase ocorre a interpretação do parâmetro dois da chamada (Arquivo Lista de Controle: 'arquivo_controle') que indica as peças de dados a serem enviadas, testa a disponibilidade das peças, calcula o MD5 de cada uma, empacota e compacta o conjunto de dados.

====Fase 3 - Automação de Envio====
Nesta fase foi contemplada a interpretação do parâmetro 1 (um) da chamada (instância alvo) a conexão ftp, envio do pacote de dados, e garantia de colocação em servidor.

====Estado Atual====
Em 29 de junho de 2.011 foi dado como concluído o desenvolvimento das rotinas de envio de dados face ao teste conjunto com as rotinas de recepção.

(Em 20 de junho de 2.011 foi dado como concluído o desenvolvimento das rotinas relacionadas com o envio de dados, restando aguardar a conclusão do desenvolvimento das rotinas de recepção para iniciar testes funcionais massivos (teste de stress).)

===Etapa 2 - Comando de Recepção de Dados===
O desenvolvimento do comando de envio de dados teve cinco (5) fases (cada qual com sua bateria de testes funcionais):
* Fase 1 - interpretação de opções;
* Fase 2 - delimitação de instância;
* Fase 3 - recepção de pacotes;
* Fase 4 - desempacotamento dos dados;
* Fase 5 - ativação da reserva de dados e sinalização de saída.
====Fase 1 - Interpretação de Opções====
Aqui foram implementadas (por reprodução do pacote de envio, respeitadas as diferenças devidas) as capacidades de interpretação de opções, ou seja utilização de um arquivo de configuração diverso do padrão por omissão (vaivem.conf), exibição de ajuda ao uso do comando, além do exibidor de versão.
====Fase 2 - Delimitação de Instância====
Nesta fase ocorre a interpretação do parâmetro da chamada (Sigla3_SciELO) que limita a recepção de pacote de dados a instância especificada na chamada.
====Fase 3 - Recepção de Pacotes====
Nesta fase foi contemplada a recepção de pacote da instância avaliada como devida na Fase 2. Toda a sinalização e tratamento de semáforos foi contemplada aqui.
====Fase 4 - Desempacotamento dos Dados====
Nesta fase foram providas verificações de descompressão de dados com sucesso, conferência de códigos MD5 e comparação com dados do último conjunto recebido com sucesso.
====Fase 5 - Ativação da Reserva de dados e Sinalização de Saída====
Conforme a Fase 4 determine o pacote de dados como válido, estes são gravados na reserva e o código de retorno com sucesso é provido.
Se por outro lado a Fase 4 determina o pacote de dados como não válido serão tomados da reserva o último conjunto ali gravado e o código de retorno com erro é provido.

====Estado Atual====
Em 29 de junho  de 2.011 foi dado como concluído o desenvolvimento das rotinas de recepção e efetuada bateria de testes em conjunto com as rotinas de envio de dados.

(Em 21 de junho de 2.011 será iniciado o desenvolvimento das rotinas de recepção de dados, para posterior teste modular e então teste funcional massivo em conjunto com as rotinas de envio.)

===Etapa 3 - Atividades complementares===
O desenvolvimento das atividades complementares (montagem de chamadas pré-configuradas; documentação complementar; empacotamento; teste geral nas máquinas 'destino'; etc.) resultou nas seguintes chamadas para uso final:
* bir2sci.sh - enviador de dados no sentido BIREME -> SciELO
* envia2ORG.sh - substituto da atual Envia2Medline.bat
* envia2.sh - enviador de dados genérico configurado por default para o sentido SciELO -> rede
* recebf.sh - receptor de dador genérico
* seguro.sh - codificador de arquivo de senhas
* segura.sh - decodificador de arquivo de senhas para base de dados CDS-ISIS (para fins de verificação)
Resultou também no documento ''README.1st'' que descreve tecnicamente os componentes do pacote de troca de dados via FTP, e finalmente no arquivo tar-ball compactado '''tr_x.tgz''' que contém todas as partes e componentes necessários para a implantação do pacote.

==Implantação e Configuração==
As instruções aqui contidas são mínimas e não têm a pretensão de substituir um manual técnico para o pacote, mas sim servir de guia rápido para colocar em uso o pacote.
===Implantação===
Ao tomar o tar-ball (tr_x.tgz) do pacote este deve ser ''aberto'' e seus componentes devem ser transferidos para o diretório de uso, nos termos das rotinas praticadas em ''Operação de Fontes de Informação'', tipicamente, num tpl.xxx.
Por princípio, todos os componentes devem estar em um mesmo diretório e não podem (sem customização dos ''shell-scripts'') ser separados em diferentes diretórios.

A única operação a ser realizada que se assemelha a uma instalação (além da cópia referida) é a recriação de um ''Master-File'' (M/F) da base de dados gizmo denominada '''gunians''' que deve ser efetuada com o utilitário ''id2i'' do CISIS como mostra o comando a seguir (assumindo que os utilitários do CISIS estão no ''path'' de execução da máquina):
 id2i gunians.id create=gunians

===Configuração===
A configuração do pacote é simples e baseada em um arquivo texto sem formatação (''plain text file''), seguindo o estilo de arquivo de configuração empregado no Apache, onde temos uma declaração (''statment'') associando um termo a um valor através de um sinal de igualdade (TERMO = valor). Comentários podem permear o arquivo como forma de documentação se desejado, mas não são obrigatórios, assim como as próprias declarações são opcionais assumindo, em caso de ausência, valores ''default'', previamente, programados nos ''shell-scripts''.

{| border="1" width="100%"
|+ Termos para uso no Arquivo de Configuração (''case-sensitive'')
|-
! Termo
! Explanação
! valor ''Default''
! Limites / Escopo
|-
! PY
| Permite o uso de ''lescielos.py'' (mais rápido)
| (não declarado)
| TRUE ou não declarado
|-
! HOSTSERVER
| Identificação do servidor de execução do comando
| SciELO
| BIREME / SciELO / NETWORK
|-
! TXTIMO
| Número máximo de tentativas para controlar o canal de transmissão
| 31
| valor inteiro maior que zero
|-
! RXTIMO
| Número máximo de tentativas para obter leitura de ''data-ready'' no canal de recepção
| 6
| valor inteiro maior que zero
|-
! TXSERVER
| URL do servidor de FTP usado no canal de transmissão
| ftp.scielo.br
| qqr URL de FTP válida
|-
! RXSERVER
| URL do servidor de FTP usado no canal de recepção
| ftp.scielo.br
| qualquer URL de FTP válida
|-
! TXUSER
| ''Username'' para conexão ao servidor FTP de envio
| usr.bireme
| qualquer username válido
|-
! TXPASS
| ''Password'' do usuário do servidor FTP de envio
| 123deoliveira4
| qualquer senha válida
|-
! RXUSER
| ''Username'' para conexão ao servidor FTP de recepção
| joao.silva
| qualquer username válido
|-
! RXPASS
| ''Password'' do usuário do servidor FTP de recepção
| b!r3n3
| qualquer senha válida
|-
! USER
| ''Username'' para conexão ao servidor FTP (transmissão e recepção)
| jane.doe
| qualquer username válido
|-
! PASS
| ''Password'' do usuário do servidor FTP (transmissão e recepção)
| #s3nh@f0rt3!
| qualquer senha válida
|}

No pacote estão contidos oito (8) arquivos de configuração, identificados pela extensão '''.conf''' (não obrigatória), que podem/devem ser tomados como exemplos para a criação de outros arquivos de configuração, na utilização do pacote de troca de dados via FTP.

Abaixo é mostrado o conteúdo do arquivo de configuração '''''vaivem.conf''''', que é o arquivo assumido na falta de indicação de outro específico, pela utilização da opção '''-c''' na chamada do ''shell-script'' de envio ou de recepção de dados:
 # Categoria de servidor executando o servico de troca de dados (TX ou RX)
 HOSTSERVER = SciELO
 
 # Time-out para a tentativa de envio com 'canal' ocupado em segundos
 TXTIMO = 31
 
 # Time-out para tentativa de recepcao com 'canal' indisponivel em segundos
 RXTIMO = 6
 
 # Endereco do servidor de FTP a ser utilizado
 TXSERVER = ftp.scielo.br
 RXSERVER = ftp.scielo.br

==Conclusão==
Ao término do ciclo de desenvolvimento será enviado um e-mail para a "lista OFI" dando ciência da conclusão da tarefa e início da vida útil do produto do desenvolvimento com sua inclusão na sistemática de versionamento da instituição.

[[Category:Processamento de dados]]
[[Category:Operação de Fontes de Informação]]