Se não pode deslocar-se até ao fim do texto abaixo, clica aqui.

Especificações do formato dos ficheiros cyloop

Este documento descrito a estrutura dos ficheiros utilizados pelo software livre Cyloop desenvolvido por Bernard Chardonneau (França) para armazenar as informações que este software permite tratar.

Os ficheiros cujo formato é descrito neste documento são chamados "ficheiros cyloop".

A reprodução deste texto ao idêntico, sua tradução em outras línguas e sua divulgação são livre.

Em caso de diferenças de significado entre 2 versões do texto escrito em línguas diferentes, é a versão francesa é a que constitui a referência.

Sufixo dos ficheiros e formatos de dados utilizados

Os ficheiros cyloop são do ficheiro cujo nome se termina pelo sufixo .cyl ou .CYL .
Trata-se de ficheiros binários. As informações que contêm são gravadas nos formatos seguintes :

byte	:	inteiro 8 bits não assinados, valor de 0 a 255
uint16	:	inteiro 16 bits não assinados, valor de 0 a à 65535
uint32	:	inteiro 32 bits não assinados, valor de 0 a 4294967295
int16	:	inteiro 16 bits assinados, valor de -32768 a 32767
int32	:	inteiro 32 bits assinados, valor de -2147483648 a 2147483647
float	:	número flotante mero precisão armazenado sobre 4 bytes.

É possível de armazenar os valores numéricos dos bytes de importância forte aos bytes de pesos baixo (big endian) ou dos bytes de pesos baixo aos bytes de importância forte (little endian).
Não obstante, a ordem dos bytes nos valores numéricos é indicado no ficheiro cyloop.

Se os valores numéricos são armazenado do byte de importância baixo ao byte de importância forte como é o caso sobre os PC (microprocessador Intel ou compatível), o nome dos ficheiros cyloop se termina pelo sufixo .cyl e os 3 primeiros bytes do ficheiro cyloop são cyl (em cartas minúsculas).

Se os valores numéricos são armazenado do byte de importância forte ao byte de importância baixo, o nome dos ficheiros cyloop termina-se pelo sufixo .CYL e os 3 primeiros bytes do ficheiro cyloop são CYL (em cartas maiúsculas).

Finalmente, se o sistema de exploração utilizado não permite de escolher entre cartas minúsculas ou das cartas maiúsculas para os nomes de ficheiros, é a assinatura do ficheiro cyloop (constituída por seus 3 primeiros bytes) que permite definir a ordem dos bytes nos valores numéricos.

Estrutura de um ficheiro cyloop

Os ficheiros cyloop têm a estrutura geral seguinte :

Encabeçamento do ficheiro

Pronta das variávels

Encabeçamento da variável 1

Dados da variável 1

Encabeçamento da variável 2

Dados da variável 2

........

........

Encabeçamento da a última variável

Dadas da última variável

Há um caso particular para os ficheiros cyloop que não armazenam que uma sozinha variável sem nome.
Neste caso, os ficheiros cyloop têm a estrutura seguinte :

Encabeçamento do ficheiro

Encabeçamento da variável

Dados da variável

O encabeçamento do ficheiro cyloop

O encabeçamento de um ficheiro cyloop é constituída de 16 bytes e contém na ordem os campos seguintes :

Tipo	Nomeie	Descrição
3 bytes	signature	Permite verificar que o ficheiro é bem um ficheiro cyloop ao bom formato. Contém na ordem : as carácteres cyl se os valores numéricos são armazenado do byte de importância baixo ao byte de importância forte (é o caso sobre os PC), as carácteres CYL se os valores numéricos são armazenado do byte de importância forte ao byte de importância baixo.
byte	nb_var	Número de variávels armazenado no ficheiro cyloop. Se nb_var = 0, o ficheiro cyloop armazena uma sozinha variável que não possui de nome. Se nb_var > 0 (valor entre 1 e 255), o ficheiro cyloop armazena nb_var variávels. A cada uma pode ser identificada por seu nome ou por um número correspondente em sua posição na lista das variávels descritas ao parágrafo seguinte.
byte	caract_gen	Campo de bits que define os características gerais do ficheiro cyloop. A cada indicação é armazenado sobre um bit.
bit 0	cycle_decl	Ciclo activado. Se cycle_decl = 0, a cada novo ciclo começa imediatamente ao finalizar o precedente (funcionamento por defeito de Cyloop). Se cycle_decl = 1, é necessário de lançar manda-a cyldecl para arrancar um novo ciclo.
bit 1	temps_utc	Começo de ciclos calculados em tempo universal (UTC ou GMT). Se temps_utc = 0, os começos de ciclo são calculados por relatório pontualmente local (que pode se adiar se a hora de verão é aplicada uma parte do ano). Se temps_utc = 1, os começos de ciclo são calculados por relatório pontualmente em tempo universal (UTC ou GMT).
bit 2	cycle_ireg	Utilização ciclo de duração irregular baseada no calendário. Se cycle_ireg = 0, todos os ciclos têm a mesma duração que é fixada pelo valor de duree_cycle. Se cycle_ireg = 1, utiliza-se um ciclo de duração irregular, mensal ou anual.
bit 3	cycle_annuel	Eleição entre um ciclo mensal ou anual. Este bit não é significativo que se o bit cycle_ireg é a 1 Se cycle_annuel = 0, o ficheiro cyloop funciona segundo um ciclo mensal que começa no primeiro dia do mês. Se cycle_annuel = 1, o ficheiro cyloop funciona segundo um ciclo anual que começa no primeiro dia do ano.
bits 4 a 7 não usados		Têm que ser deixados a 0.
byte	etat_cyloop	Bits de estado do ficheiro cyloop.
bit 0	heure_ete	Este bit armazena se estava-se pontualmente de verão (bit a 1) ou de inverno durante a última actualizado dos dados. Não é significativo que se o bit temps_utc = 0 (hora local).
bits 1 a 7 não usados		Têm que ser deixados a 0.
uint16	nb_don_cycle	Nombre de données par cycle de mesure. É o número de pedaços de duração idêntica (eventualmente a um segundo cerca de) no qual a cada ciclo é recortado
uint32	deb_cycle	Instante de começo do ciclo corrente. É o valor voltado pela função time() no momento do começo deste ciclo (número de segundos fluídos desde o 1.ou de janeiro de 1970 em 0 H UTC).
uint32	duree_cycle	Durado em segundos do ciclo corrente.

A lista das variávels

Esta lista não existe que se o valor nb_var do encabeçamento doficheiro cyloop não é a 0. Neste caso, a lista comporta nb_var elementos que têm a estrutura seguinte :

Nome da variável 16 bytes

Posição int32



• O nome da variável comporta 1 a 16 carácteres. Os nomes mais longos se serão truncados. Se este nome comporta menos 16 carácteres, os últimos bytes do nome são a 0.
  
  As carácteres de controle (código ASCII < 32) e as carácteres " são proibidos em um nome de variável.
  
  Os espaços são proibidos igualmente e substituídos por de os _
  
  O uso das carácteres ! $ & | ; ' ` \ < > ( ) que inclusive juntado a outros, podem ser interpretados de maneira especial on-line de comandos é por agora desaconselhado. Certos destas carácteres poderão ser proibidos mas tarde.
  
  O trabalho de carácteres de código ASCII >= 80h fará o objecto de uma advertência e de uma demanda de confirmação. Sua utilização treina um resultado não portátil, mas como é a sozinha maneira de expressar nomes de variávels em um alfabeto não europeu, sua utilização poderá ser aceitada.



• O campo Posição é um inteiro 32 bits que precisa o número do primeiro byte do encabeçamento desta variável no ficheiro Cyloop.

O encabeçamento de uma variável

A encabeçamento de uma variável é constituída de 6 ou 8 bytes e contém na ordem os campos seguintes :

Tipo	Nomeie	Descrição
uint16	der_enreg	Número do último dado actualizada no ciclo actual. Se der_enreg = 0, se não tem ainda actualizado o dado no ciclo actual. No caso contrário, der_enreg é compreendido entre 1 e nb_don_cycle.
byte	typedon	Campo de bits que define os características da variável. A cada indicação é armazenado sobre um bit.
bit 0	cmoy_sep	Coeficiente coef_moy diferente para a cada instante do ciclo. Por defeito, (cmoy_sep = 0) o cálculo do valor médio para a cada dado de um ciclo é feito por relatório ao valor do campo coef_moy definido ao finalizar esta encabeçamento. O campo coef_moy contém um valor em relação com o número de ciclos efectuados. Se cmoy_sep = 1, à cada uma dos dados que correspondem em um instante do ciclo é associada um valor coef_moy diferente.
bit 1	cpt_cycle_vide	Consideração em conta dos ciclos vazios nos cálculos de ponderação. Este bit não é significativo que se o valor do campo ponderation é diferente de 0. Por defeito (cpt_cycle_vide = 0), se um ou vários ciclos se fluem sem nenhuma gravação de dados, são ignorados durante o próximo cálculo de ponderação dos dados já gravados. Se este bit é a 1, o cálculo de ponderação é realizado mantendo conta dos ciclos vazios.
bit 2	cumul_donnees	Autorizar várias postas em dias em todo momento do ciclo. Por defeito, durante um ciclo, a cada uma dos dados que correspondem em um instante do ciclo não pode ser actualizada que uma vez. Se este bit é a 1, um mesmo dado pode ser actualizada várias vezes de continuação.
bit 3	compteur	Eleição entre uma variável que contém valores ou um contador de bilhete. Por defeito (compteur = 0) é necessário de introduzir um valor para actualizar o dado que corresponde em um instante do ciclo. Se compteur = 1, a variável é um contador de bilhetes que é incrementado automaticamente.
bit 4	donnees_32bits	Formato dos dados para uma variável contadora. Este bit não é significativo que se o bit compteur é a 1. Por defeito (donnees_32bits = 0), os dados do contador são armazenado sobre 2 bytes (uint16). Se donnees_32bits = 1, os dados do contador são armazenado sobre 4 bytes (uint32).
bit 5	val_float	Formato dos dados para uma variável clássica. Este bit não é significativo que se o bit compteur é a 0. Por defeito (val_float = 0), os dados da variável são então valores inteiros sobre 4 bytes de tipo int32. Se val_float = 1, os dados da variável são armazenado em valores de tipo float.
bit 6	mem_min_max	Memorização dos valores mínimo e máximo dos dados introduzidos em todo momento do ciclo. Este bit não é significativo que se o bit compteur é a 0. Por defeito (mem_min_max = 0), armazena-se só uma ordena eventualmente ponderada dos dados para a cada instante do ciclo, bem como uma indicação para calcular seu valor médio. Se mem_min_max = 1, os valores mínimo e máximo dos dados introduzidos para a cada um dos instantes do ciclo são igualmente armazenado.
bit 7	cpt_toute_don	Este bit não é significativo que se cmoy_sep = 1 e cumul_donnees = 1. Se ademais, cpt_toute_don = 1, o valor coef_moy associada em todo momento do ciclo é incrementada durante a cada actualizada do dado correspondente. Se cpt_toute_don = 0, o incremento não tem lugar que durante a primeira actualizada do dado para este instante do ciclo.
byte	ponderation	Coeficiente de ponderação para os valores dos ciclos precedentes. Se ponderation = 0, nenhuma operação não é realizada sobre os dados já armazenado durante uma mudança de ciclo. Tem a cada novo ciclo, os novos dados acrescentam-se àquelas dos ciclos precedentes. No caso contrário (ponderation compreendido entre 1 e 255), os dados saídos dos ciclos precedentes são multiplicadas por (ponderation / 256). É assim mesmo para o ou os coeficiente(s) coef_moy armazenado(s). Assim, os dados dos últimos ciclos tomam mais de importância no cálculo do valor médio que aquelas dos ciclos mais antigos. Se o bit cpt_cycle_vide do campo typedon é a 1 e que vários ciclos se fluíram sem actualizada dos dados, o cálculo de ponderação é efectuado para a cada um destes ciclos.
uint16	extention	Campo disponível para uma eventual utilização ulterior. A 0 enquanto.
uint16	coef_moy	(opcional) Coeficiente que permite calcular o valor médio dos dados memorizados para a cada instante do ciclo. Se o bit cmoy_sep do campo typedon é a 0, este coeficiente contém um valor actualizado ao princípio da cada ciclo que permite o cálculo dos valores médios dos dados para a cada um dos instantes do ciclo. Se o bit cmoy_sep do campo typedon é a 1, este coeficiente não existe no encabeçamento da variável cyloop, mas um coeficiente assim mesmo natureza é armazenado separadamente no ficheiro cyloop para a cada um dos instantes do ciclo.

Estrutura dos dados de uma variável

Após o encabeçamento de uma variável, os dados associados nesta variável são implantadas na continuação.

Encontra-se primeiramente o conjunto dos dados relativos ao primeiro instante do ciclo, depois aquelas que implicam o instante seguinte, e assim sucessivamente.

Em funções do valor dos bits cmoy_sep, compteur, donnees_32bits, val_float e mem_min_max do campo typedon que figura no encabeçamento da variável, pode ter uma ou vários valores armazenado para a cada instante do ciclo, e vários formatos de armazenamento para a cada uma destes valores.

Um grupo de valores que correspondem em um instante do ciclo comporta na ordem :

• se cmoy_sep = 1, o coeficiente que permite calcular o valor médio do dado para este instante do ciclo,
• o dado para este instante do ciclo,
• se mem_min_max = 1, o valor mínimo, depois o valor máximo do dado introduzido para este instante do ciclo.

Ao total, este grupo valioso aparece nb_don_cycle vez (valor definido no encabeçamento do ficheiro) para memorizar o ciclo completo.

Estrutura dos dados para o variável contador

• Se compteur = 1, donnees_32bits = 0 e cmoy_sep = 0, tem-se para a cada instante do ciclo o dado seguinte :



Contador uint16



• Se compteur = 1, donnees_32bits = 1 e cmoy_sep = 0, tem-se para a cada instante do ciclo o dado seguinte :



Contador uint32



• Se compteur = 1, donnees_32bits = 0 e cmoy_sep = 1, tem-se para a cada instante do ciclo os dados seguintes :



coef_moy uint16

Contador uint16



• Se compteur = 1, donnees_32bits = 1 e cmoy_sep = 1, tem-se para a cada instante do ciclo os dados seguintes :



coef_moy uint16

Contador uint32

Estrutura dos dados para as variávels "valor"

• Se compteur = 0, val_float = 0, cmoy_sep = 0 e mem_min_max = 0, tem-se para a cada instante do ciclo o dado seguinte :



Valor int32



• Se compteur = 0, val_float = 1, cmoy_sep = 0 e mem_min_max = 0, tem-se para a cada instante do ciclo o dado seguinte :



Valor float



• Se compteur = 0, val_float = 0, cmoy_sep = 1 e mem_min_max = 0, tem-se para a cada instante do ciclo o dados seguintes :



coef_moy uint16

Valor int32



• Se compteur = 0, val_float = 1, cmoy_sep = 1 e mem_min_max = 0, tem-se para a cada instante do ciclo o dados seguintes :



coef_moy uint16

Valor float



• Se compteur = 0, val_float = 0, cmoy_sep = 0 e mem_min_max = 1, tem-se para a cada instante do ciclo o dados seguintes :



Valor int32

Mínimo int32

Máximo int32



• Se compteur = 0, val_float = 1, cmoy_sep = 0 e mem_min_max = 1, tem-se para a cada instante do ciclo o dados seguintes :



Valor float

Mínimo float

Máximo float



• Se compteur = 0, val_float = 0, cmoy_sep = 1 e mem_min_max = 1, tem-se para a cada instante do ciclo o dados seguintes :



coef_moy uint16

Valor int32

Mínimo int32

Máximo int32



• Se compteur = 0, val_float = 1, cmoy_sep = 1 e mem_min_max = 1, tem-se para a cada instante do ciclo o dados seguintes :



coef_moy uint16

Valor float

Mínimo float

Máximo float