FS_READ_DATA_TEXT

Lê uma linha de texto de um arquivo aberto no cartão SDCARD, retornando os caracteres lidos em uma STRING; exige que o arquivo esteja previamente aberto no modo OPEN_FILE_READ. É um bloco de função (mantém estado entre scans; requer instância).

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

Bloco de função

           FS_READ_DATA_TEXT
         +-------------------+
BOOL ----|START          DONE|---- BOOL
         |                   |
 INT ----|FD           READED|---- INT
         |                   |
 INT ----|DATA_LEN     RESULT|---- INT
         |                   |
     ----|DATA_VALUE --------|----
         +-------------------+

A leitura é iniciada com START em TRUE e conclui-se com um pulso de DONE (ativo por apenas um ciclo de scan); nesse instante RESULT traz o código de retorno e READED a quantidade de caracteres efetivamente lidos. A leitura para ao atingir DATA_LEN caracteres ou ao encontrar o fim da linha corrente ('\n', linefeed), o que ocorrer primeiro — portanto READED pode ser menor que DATA_LEN. Ao atingir o máximo, o último caractere é reservado para o delimitador de fim de string ('\0'). Se START voltar a FALSE antes do término, o bloco é resetado.

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.

Nota

O tamanho máximo de uma STRING é 246 caracteres; DATA_LEN não deve excedê-lo.

Parâmetros

Nome	Direção	Tipo	Padrão	Faixa / Unidade	Descrição
START	IN	BOOL	FALSE	—	Ativa a leitura (TRUE); voltar a FALSE antes do fim reseta o bloco.
FD	IN	INT	0	—	Descritor do arquivo (aberto em OPEN_FILE_READ) a ser lido.
DATA_LEN	IN	INT	0	1 .. 246 (bytes)	Quantidade máxima de caracteres a ler por ciclo de leitura.
DATA_VALUE	IN_OUT	ANY	—	—	STRING que recebe os caracteres lidos do arquivo.
DONE	OUT	BOOL	FALSE	—	Pulso (1 scan) de término da execução; consulte RESULT em seguida.
READED	OUT	INT	0	bytes	Quantidade de caracteres efetivamente lidos.
RESULT	OUT	INT	0	RET_CODE	Código de retorno da execução (ver Códigos de retorno).

Códigos de retorno

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

Código	Identificador	Significado
0	SUCCESS	Leitura 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	Recurso não disponível (sem suporte a sistema de arquivos ou SDCARD não detectado).
27	RE_RES_EMP	Buffer do recurso vazio.
31	RE_READ_ERR	Falha na leitura do recurso, ou fim de arquivo.
33	RE_NOT_INIT	Recurso não inicializado.
167	FS_CORRUPT	Sistema de arquivos corrompido.
168	FS_INV_OPER_MODE	Modo de operação incompatível com o estado do arquivo.
177	FS_INVALID_HANDLE	Handle de arquivo aberto inválido.

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

Pré-condições

• O controlador deve ter suporte a sistema de arquivos no SDCARD.

• O arquivo deve estar aberto no modo OPEN_FILE_READ (ver FS_OPEN_FILE) e FD conter o descritor válido correspondente.

• DATA_VALUE deve ser uma STRING com capacidade compatível com DATA_LEN.

Observações

• A leitura é orientada a linha: cada ativação retorna até o fim da linha corrente ou até DATA_LEN caracteres. Linhas mais longas exigem leituras sucessivas.

• Utilize funções de manipulação de string para processar dinamicamente o texto lido.

Ver também

FS_OPEN_FILE, FS_CLOSE_FILE, FS_READ_DATA_FILE, FS_WRITE_DATA_TEXT

Exemplo

Clique aqui para baixar a tabela de variáveis

Código ST

VAR
    STR_DATA  : STRING;                 (* String para armazenar o texto lido do arquivo *)
    MY_START  : BOOL := FALSE;          (* Ativação da função *)
    FILE_FD   : INT;                    (* Descritor do arquivo a ser lido *)
    READ_FILE : HILS.FS_READ_DATA_TEXT; (* Instância do bloco "FS_READ_DATA_TEXT" *)
END_VAR

//============================================================================
// Exemplo de ativação da função FS_READ_DATA_TEXT, para leitura de uma
// string do arquivo
//============================================================================

// Preenche parâmetros para a chamada do bloco de função
FILE_FD  := 0;      // Descritor do arquivo
MY_START := TRUE;   // Ativação do bloco da função

(* ... *)

// Ativação do bloco de função FS_READ_DATA_TEXT
READ_FILE(  // FS_READ_DATA_TEXT
  START      := MY_START,  // [BOOL] Ativação da função
  FD         := FILE_FD,   // [INT] Descritor do arquivo
  DATA_VALUE := STR_DATA,  // [ANY] String para armazenar os dados lidos do arquivo
  DATA_LEN   := 246        // [INT] Tamanho máximo em bytes dos caracteres a serem lidos
  );

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

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

  // Testa código de retorno da execução da função
  if (READ_FILE.RESULT = HILS.SUCCESS) then
    // ... Função executada com sucesso

    // Exemplo de string retornada lida do arquivo:
    //
    //   '21/11/2021 09:13:32; 28.5 oC; 53.0 %;'
    //
    // OBS.: Utilizar funções de manipulação de string para processar
    //       dinamicamente o texto lido do arquivo.

  else
    // ... Erro na execução da função
  end_if;

end_if;

(* ... *)