FS_OPEN_FILE

Abre um arquivo de dados no sistema de arquivos do SDCARD e retorna um identificador (FD) para o arquivo aberto, usado nas operações subsequentes de leitura, escrita e posicionamento. Requer suporte a sistema de arquivos no controlador. É 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_OPEN_FILE
                           +--------------+
                  BOOL ----|START     DONE|---- BOOL
                           |              |
HILS.FS_OPEN_FILE_MODE ----|MODE    RESULT|---- INT
                           |              |
                           |            FD|---- INT
                           |              |
                STRING ----|NAME -------- |----
                           +--------------+

A execução inicia na ativação de START (TRUE). Se START retornar a FALSE antes do fim da operação, o bloco é resetado. A conclusão é sinalizada por um pulso de um único scan em DONE; nesse instante RESULT traz o código de retorno e, em caso de sucesso, FD traz o descritor do arquivo aberto.

É possível abrir o mesmo arquivo várias vezes (obtendo diferentes FD) para operações de leitura. Cada FD obtido deve, ao término do uso, ser encerrado com FS_CLOSE_FILE.

Nota

O parâmetro MODE (tipo HILS.FS_OPEN_FILE_MODE) admite os modos:

OPEN_FILE_READ [1] — leitura de dados binários.
OPEN_FILE_WRITE [2] — escrita de dados binários (a partir do início do arquivo).
OPEN_FILE_APPEND [3] — acréscimo de dados binários ao final do arquivo.
OPEN_FILE_WRITE_TXT [5] — escrita de dados texto.
OPEN_FILE_APPEND_TXT [6] — acréscimo de dados texto ao final do arquivo.

Parâmetros

Nome	Direção	Tipo	Padrão	Faixa / Unidade	Descrição
START	IN	BOOL	FALSE	—	Ativa (TRUE) a execução; voltar a FALSE antes do fim reseta o bloco.
MODE	IN	HILS.FS_OPEN_FILE_MODE	0	OPEN_FILE_READ .. OPEN_FILE_APPEND_TXT	Modo de abertura do arquivo (ver nota acima).
NAME	IN_OUT	STRING	—	= 64 caracteres	Caminho completo do arquivo a abrir; deve iniciar com `/` (raiz).
DONE	OUT	BOOL	FALSE	—	Pulso de um scan indicando o fim da execução.
RESULT	OUT	INT	0	RET_CODE	Código de retorno da execução (ver Códigos de retorno).
FD	OUT	INT	0	—	Descritor do arquivo aberto (File Descriptor), válido em caso de sucesso.

Códigos de retorno

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

Código	Identificador	Significado
0	SUCCESS	Função executada com sucesso.
5	GL_INV_PAR	Parâmetro(s) inválido(s).
7	GL_UNA_CMD	Comando não disponível ou não implementado.
8	GL_INV_STT	Estado corrente inválido.
10	GL_CMD_TMO	Timeout na execução do comando.
11	GL_CMD_CAN	Comando cancelado.
16	GL_CMD_PEND	Tratamento do comando pendente.
24	RE_NOT_AVA	Sem suporte para o sistema de arquivos ou SDCARD não detectado.
25	RE_INV_LEN	Tamanho especificado no parâmetro `NAME` inválido.
27	RE_RES_EMP	Buffer do recurso vazio.
31	RE_READ_ERR	Falha no processo de leitura do recurso.
32	RE_WRITE_ERR	Falha no processo de escrita do recurso.
33	RE_NOT_INIT	Recurso não inicializado.
167	FS_CORRUPT	Sistema de arquivos pode estar corrompido.
168	FS_INV_OPER_MODE	Modo de operação incompatível com o estado do arquivo.
170	FS_WRITE_LOCK	Arquivo já está aberto para escrita.
173	FS_INVALIDNAME	Texto especificado no parâmetro `NAME` inválido.
174	FS_NOTFOUND	O arquivo não foi encontrado.
175	FS_DUPLICATED	O arquivo já existe.
176	FS_OPEN_LIMIT	Número máximo de arquivos abertos alcançado.
178	FS_INVALID_DIR	O diretório não existe.

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.
NAME deve conter o caminho completo, iniciando com /, e ter no máximo 64 caracteres.
Cada FD obtido deve ser posteriormente encerrado com FS_CLOSE_FILE.

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”

Observações

DONE fica ativo por apenas um ciclo de scan; consulte RESULT nesse mesmo scan.
No modo OPEN_FILE_WRITE a escrita começa no início do arquivo (pode sobrescrever dados existentes); use FS_SEEK_FILE para reposicionar.
No modo OPEN_FILE_APPEND a escrita ocorre a partir do final dos dados existentes.

Ver também

FS_CLOSE_FILE, FS_READ_DATA_FILE, FS_WRITE_DATA_FILE, FS_SEEK_FILE, FS_CREATE_FILE

Exemplo

Clique aqui para baixar a tabela de variáveis

Código ST

VAR
    FILE_DADOS : STRING := '/DADOS.DAT';      (* Nome do arquivo no diretório raiz *)
    MY_START   : BOOL := FALSE;               (* Ativação da função *)
    OPEN_MODE  : HILS.FS_OPEN_FILE_MODE;      (* Modo de abertura do arquivo *)
    FILE_NAME  : STRING;                      (* Nome do arquivo a ser aberto (máx. 64 caracteres) *)
    OPEN_FILE  : HILS.FS_OPEN_FILE;           (* Instância do bloco "FS_OPEN_FILE" *)
END_VAR

//============================================================================
// Exemplo de parametrização 1 : Abertura no modo OPEN_FILE_READ
//============================================================================
// Abertura de um arquivo para leitura.
// OBS: É possível abrir um arquivo várias vezes, realizando operações de
// leitura a partir de diferentes FD (File Descriptor)

// Preenche parâmetros para a chamada do bloco de função
FILE_NAME := FILE_DADOS;            // Nome do arquivo '/DADOS.DAT'
OPEN_MODE := HILS.OPEN_FILE_READ;   // Modo de abertura do arquivo

(* ... *)

//============================================================================
// Exemplo de parametrização 2 : Abertura no modo OPEN_FILE_WRITE
//============================================================================
// Abre arquivo para escrever dados.
// OBS: Ao abrir um arquivo nesse modo, os valores começam a ser
// escritos a partir do início do arquivo. Caso o arquivo
// já tenha dados, seus valores podem ser rescritos.
// Para reposicionar o local onde os dados serão escritos utilizar a função
// FS_SEEK_FILE.

// Preenche parâmetros para a chamada do bloco de função
FILE_NAME := '/Pasta_1/Dados.dat';  // Nome do arquivo 'Dados.Dat' dentro do diretório "/Pasta_1"
OPEN_MODE := HILS.OPEN_FILE_WRITE;  // Modo de abertura do arquivo

(* ... *)

//============================================================================
// Exemplo de parametrização 3 : Abertura no modo OPEN_FILE_APPEND
//============================================================================
// Abre arquivo para adicionar dados.
// OBS: Ao abrir um arquivo nesse modo, os valores serão
// escritos a partir da última posição dos dados no arquivo.

// Preenche parâmetros para a chamada do bloco de função
FILE_NAME := '/P1/P2/P3/Setup.cfg'; // Nome do arquivo 'Setup.cfg' dentro do diretório "/P1/P2/P3"
OPEN_MODE := HILS.OPEN_FILE_APPEND; // Modo de abertura do arquivo

(* ... *)

//============================================================================
// Trata função FS_OPEN_FILE
//============================================================================

// Preenche parâmetros para a chamada do bloco de função
MY_START := TRUE;        // Ativação do bloco da função
(* ... *)

// Exemplo de ativação do bloco de função FS_OPEN_FILE
OPEN_FILE(
  START := MY_START,  // [BOOL] Ativação da função
  NAME  := FILE_NAME, // [STRING] Path com o nome do arquivo a ser aberto
  MODE  := OPEN_MODE  // [FS_OPEN_FILE_MODE] Modo de abertura do arquivo
  );

// Aguarda término da execução da função do sistema de arquivos
if (OPEN_FILE.DONE) then

  MY_START := FALSE;     // reseta ativação da função

  // Testa código de retorno da execução da função
  if (OPEN_FILE.RESULT = HILS.SUCCESS) then
    // ... Função executada com sucesso
  else
    // ... Erro na execução da função
  end_if;

end_if;

(* ... *)