FS_LIST_DIR

Lista os arquivos e pastas de um diretório do sistema de arquivos (SDCARD), retornando um item (arquivo ou pasta) a cada execução. É um bloco de função (mantém estado entre scans; requer instância).

Biblioteca: HI_STD · Namespace: HILS · Tipo: bloco de função

Nota

Antes de utilizar este bloco de função, consulte no manual do controlador utilizado se o mesmo possui suporte para sistema de arquivos no SDCARD.

Bloco de função

              FS_LIST_DIR
           +----------------+
           |            DONE|---- BOOL
           |                |
           |          RESULT|---- INT
           |                |
           |            NAME|---- STRING
           |                |
           |             ATR|---- WORD
           |                |
           |            DATE|---- DT
           |                |
  BOOL ----|RESTART --------|----
           |                |
  BOOL ----|GET ----------- |----
           |                |
STRING ----|DIR ----------- |----
           +----------------+

O bloco lê o diretório indicado em DIR de forma incremental. Ative RESTART para abrir o diretório e posicionar o leitor no primeiro item; ative GET para ler o item corrente e avançar o leitor para o próximo. Os dois comandos podem ser enviados juntos, posicionando e lendo o primeiro item em sequência. Ao final da execução, RESTART e GET são zerados automaticamente.

O pulso DONE (ativo por um único ciclo de scan) sinaliza o término da execução; somente após esse pulso os valores de RESULT, NAME, ATR e DATE devem ser consultados.

Nota

Quando GET atinge o fim do diretório, RESULT retorna HILS.FS_NOTFOUND (174), indicando que não há mais itens a listar.

O caminho em DIR só é utilizado no comando RESTART. Para acessar o diretório atual, informe uma string nula (''); para acessar diretamente o diretório raiz, informe uma string com '/'.

Parâmetros

Nome	Direção	Tipo	Padrão	Faixa / Unidade	Descrição
RESTART	IN_OUT	BOOL	FALSE	—	Abre o diretório indicado em `DIR` e posiciona o leitor no primeiro item. Zerado ao final da execução.
GET	IN_OUT	BOOL	FALSE	—	Lê o item corrente (arquivo/pasta) do diretório aberto e incrementa a posição do leitor. Zerado ao final da execução.
DIR	IN_OUT	STRING	—	—	Caminho completo do diretório a listar (usado apenas no `RESTART`). `''` = diretório atual; `'/'` = raiz.
DONE	OUT	BOOL	FALSE	—	Pulso (1 scan) que indica o término da execução do bloco.
RESULT	OUT	INT	0	RET_CODE	Código de retorno da execução (ver Códigos de retorno).
NAME	OUT	STRING	—	—	Nome do arquivo ou pasta retornado. No raiz retorna `'/'`; em subdiretórios pode retornar `'.'` (atual) e `'..'` (pai).
ATR	OUT	WORD	0	bitmap	Atributos do arquivo ou pasta (ver Observações).
DATE	OUT	DT	—	UTC	Data e hora de alteração do arquivo ou pasta (referência UTC).

Códigos de retorno

RESULT é do tipo RET_CODE. Use os identificadores com o namespace HILS (ex.: HILS.FS_NOTFOUND). Códigos mais comuns deste bloco:

Código	Identificador	Significado
0	SUCCESS	Item lido com sucesso.
5	GL_INV_PAR	Parâmetro(s) inválido(s).
167	FS_CORRUPT	Sistema de arquivo corrompido.
173	FS_INVALIDNAME	Nome de arquivo/diretório inválido.
174	FS_NOTFOUND	Fim do diretório ou item não encontrado.
178	FS_INVALID_DIR	Diretório inválido ou inexistente.

Lista completa dos códigos de retorno: RET_CODE - Códigos de retorno do firmware G5.

Pré-condições

O controlador deve possuir suporte a sistema de arquivos no SDCARD.
O diretório informado em DIR deve existir (aberto via RESTART) antes de ler itens com GET.

Observações

Consulte RESULT apenas após o pulso DONE.
RESTART e GET podem ser combinados na mesma chamada.
DATE está associada ao relógio calendário do controlador, com fuso de referência UTC (o horário oficial de Brasília está -3:00 h do UTC).

Atributos no sistema de arquivos G5

Os atributos são mapeados em bits onde o significado de cada bit é descrito na tabela a seguir.

BIT	Descrição do Atributo
0	Arquivo oculto.
1	Arquivo com acesso apenas de leitura.
3	Arquivo de sistema. Gerenciado pelo HIstudio.
5	Arquivo de projeto do HIstudio.
7	Arquivo de dados gerênciado pela aplicação do PLC.
10	Atributo de diretório.

Recomendações para nomes de arquivos e diretórios:

Apesar do sistema de arquivos aceitar qualquer caracter para definição de um nome de arquivo ou diretório, recomenda-se utilizar apenas os tipos:

Caracteres alfabéticos de A-Z ou a-z

Caracteres numéricos de 0 - 9

Caracteres especiais . (ponto decimal) ou _ (underline)

O tamanho máximo permitido para nome do arquivo ou diretório é de 64 caracteres.

Apesar de permitir caracteres em minúscula e maiúscula na nomenclatura, o sistema não é “case sensitive”, ou seja, os nomes ‘DADOS.DAT’, ‘Dados.Dat’ e ‘dados.dat’ referem-se ao mesmo arquivo.

Essa recomendação é sugerida, pois quando o arquivo for eventualmente transferido para o computador, o arquivo/diretório deve obedecer as regras de nomeação do sistema operacional do PC.

Exemplos de nomes recomendados:

‘PASTA’

‘/Pasta_1/Pasta_2’

‘dados.dat’

‘abc_123.txt’

Exemplos de nomes não recomendados:

‘teste abc’

‘áãç’

‘abc’ e ‘ABC’ (considerados como o mesmo arquivo pelo sistema operacional windows)

Instruções de acesso para arquivos e diretórios:

O diretório inicial default do sistema de arquivo é o diretório raiz.

Para acessar diretamente o diretório raiz, utilizar ‘/’ antes do nome do arquivo ou diretório.

Exemplos de caminho completo para diretórios:

‘/’ : Diretório raiz do sistema de arquivo
‘/PASTA_1’ : Diretório “PASTA_1” localizado na raiz do sistema de arquivo
‘/PASTA_1/PASTA_2’ : Caminho completo para diretório “PASTA_2” a partir da “PASTA_1” localizado na raiz do sistema de arquivo
‘/p1/p2/p3’ : Caminho completo para diretório “p3” a partir dos diretórios “/p1/p2”

Exemplos de caminho completo para arquivos:

‘/dados.dat’ : Arquivo “dados.dat” localizado na raiz do sistema de arquivo
‘/PASTA_1/Log.dat’ : Arquivo “Log.dat” localizado dentro do diretório “/PASTA_1”
‘/DADOS/Jan/Dados.bak’ : Arquivo “Dados.bak” localizado dentro dos diretórios “/DADOS/Jan”
‘/P1/P2/P3/SETUP.CFG’ : Arquivo “SETUP.CFG” localizado dentro dos diretórios “/P1/P2/P3”

Ver também

FS_DIR_INFO, FS_CHANGE_DIR, FS_GET_CUR_DIR, FS_CREATE_DIR

Exemplo

Clique aqui para baixar a tabela de variáveis

Código ST

VAR
    DIR_SEC    : STRING := '/DIR2'; (* Nome do diretório a ser acessado na raiz *)
    DIR_ROOT   : STRING := '/';     (* String para acesso ao diretório raiz *)
    MY_RESTART : BOOL := FALSE;     (* Abre diretório e posiciona leitor no primeiro item *)
    MY_GET     : BOOL := FALSE;     (* Lê item do diretório aberto e incrementa a posição do leitor *)
    MY_DIR     : STRING;            (* Nome do diretório a ser lido *)
    LIST_DIR   : HILS.FS_LIST_DIR;  (* Instância do bloco "FS_LIST_DIR" *)
END_VAR

//==============================================================
// Exemplo para a leitura do diretório '/DIR2'
// que está dentro do diretório atual
//==============================================================

// Preenche parâmetros para a chamada do bloco de função
MY_DIR := DIR_SEC;        // Nome para acessar o diretório 'DIR2'
MY_RESTART := TRUE;       // Abre diretório e posiciona leitor no primeiro item
MY_GET := TRUE;           // Lê item do diretório aberto e incrementa a posição do leitor

(* ... *)

// Exemplo de ativação do bloco de função FS_LIST_DIR
LIST_DIR(
  RESTART := MY_RESTART,       // [BOOL] Abre diretório e posiciona leitor no primeiro item
  GET := MY_GET,               // [BOOL] Lê item do diretório aberto e incrementa a posição do leitor
  DIR := MY_DIR                // [STRING] Nome do diretório
  );

// Aguarda término da execução da função do sistema de arquivos
if (LIST_DIR.DONE) then
  // Testa código de retorno da execução da função
  if (LIST_DIR.RESULT = HILS.SUCCESS) then
    // ... Função executada com sucesso.
    //     Resultado da leitura do primeiro arquivo ou pasta disponível em:
    //     LIST_DIR.NAME          // [STRING] Nome do arquivo ou pasta retornado
    //     LIST_DIR.ATR           // [WORD] Atributos do arquivo ou pasta
    //     LIST_DIR.DATE          // [DT] Data e hora de criação do arquivo ou pasta
    //
    // ... Para continuar a leitura deste diretório utilizar
    //     RESTART := FALSE;
    //     GET := TRUE;
  else
    // ... Erro na execução da função
    //     ou fim do diretório (LIST_DIR.RESULT = HILS.FS_NOTFOUND)
  end_if;

end_if;

(* ... *)

//==============================================================
// Exemplo para a leitura do diretório raiz
//==============================================================

// Para ler os arquivos e pastas do diretório raiz especificar
// uma string com '/' na variável "DIR".

// Preenche parâmetros para a chamada do bloco de função
MY_DIR := DIR_ROOT;         // Nome para acessar o diretório raiz
MY_RESTART := TRUE;         // Abre diretório e posiciona leitor no primeiro item
MY_GET := TRUE;             // Lê item do diretório aberto e incrementa a posição do leitor

(* ... *)

// Exemplo de ativação do bloco de função FS_LIST_DIR
LIST_DIR(
  RESTART := MY_RESTART,         // [BOOL] Abre diretório e posiciona leitor no primeiro item
  GET := MY_GET,                 // [BOOL] Lê item do diretório aberto e incrementa a posição do leitor
  DIR := MY_DIR                  // [STRING] Nome do diretório
  );

// Aguarda término da execução da função do sistema de arquivos
if (LIST_DIR.DONE) then
  // Testa código de retorno da execução da função
  if (LIST_DIR.RESULT = HILS.SUCCESS) then
    // ... Função executada com sucesso
    //     Resultado da leitura do primeiro arquivo ou pasta disponível em:
    //     LIST_DIR.NAME          // [STRING] Nome do arquivo ou pasta retornado
    //     LIST_DIR.ATR           // [WORD] Atributos do arquivo ou pasta
    //     LIST_DIR.DATE          // [DT] Data e hora de criação do arquivo ou pasta
    //
    // ... Para continuar a leitura deste diretório utilizar
    //     RESTART := FALSE;
    //     GET := TRUE;
  else
    // ... Erro na execução da função
    //     ou fim do diretório (LIST_DIR.RESULT = HILS.FS_NOTFOUND)
  end_if;

end_if;

(* ... *)