FS_RENAME_FILE_DIR

Renomeia um arquivo ou um diretório no sistema de arquivos do SDCARD; o arquivo alvo não pode ter nenhum acesso de leitura/escrita ativo e o novo nome deve ser informado sem o caminho. É 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_RENAME_FILE_DIR
           +------------------+
  BOOL ----|START         DONE|---- BOOL
           |                  |
           |            RESULT|---- INT
           |                  |
STRING ----|PATH_NAME --------|----
           |                  |
STRING ----|NEW_NAME -------- |----
           +------------------+

O bloco é iniciado ativando START (TRUE). Se START retornar a FALSE antes do término da operação, o bloco é resetado. Ao concluir, DONE emite um pulso de um ciclo de scan e RESULT traz o código de retorno da operação.

PATH_NAME deve conter o caminho completo para o arquivo/diretório existente, iniciando sempre pelo caractere / (raiz). NEW_NAME deve conter apenas o novo nome, sem o caminho — o destino herda o mesmo caminho de PATH_NAME.

Nota

Consulte no manual do controlador utilizado se o mesmo possui suporte para sistema de arquivos no SDCARD.

Importante

Para renomear um arquivo, este não pode possuir nenhum acesso de leitura e/ou escrita ativo. Um diretório, para ser renomeado, não precisa estar vazio.

Parâmetros

Nome	Direção	Tipo	Padrão	Faixa / Unidade	Descrição
START	IN	BOOL	FALSE	—	Ativa (TRUE) a execução; retornar a FALSE antes do fim reseta o bloco.
PATH_NAME	IN_OUT	STRING	—	= 64 caracteres	Caminho completo com o nome atual do arquivo/diretório a renomear (inicia com `/`).
NEW_NAME	IN_OUT	STRING	—	= 64 caracteres	Novo nome do arquivo/diretório, sem o caminho completo.
DONE	OUT	BOOL	FALSE	—	Pulso (um scan) que sinaliza o fim da execução; então consulte `RESULT`.
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.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).
10	GL_CMD_TMO	Timeout na execução do comando.
13	GL_FUNC_FAIL	Falha na execução do comando.
24	RE_NOT_AVA	Sem suporte para o sistema de arquivos ou SDCARD não detectado.
25	RE_INV_LEN	Tamanho especificado em `PATH_NAME` ou `NEW_NAME` inválido.
33	RE_NOT_INIT	Recurso não inicializado.
167	FS_CORRUPT	Sistema de arquivo pode estar corrompido.
170	FS_WRITE_LOCK	Arquivo já está aberto para escrita.
173	FS_INVALIDNAME	Nome inválido em `PATH_NAME` (sem caminho completo) ou `NEW_NAME` (com caminho).
174	FS_NOTFOUND	O arquivo/diretório não foi encontrado.
175	FS_DUPLICATED	O arquivo/diretório de destino já existe.

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

Pré-condições

O controlador deve ter suporte a sistema de arquivos no SDCARD, com o SDCARD detectado e inicializado.
PATH_NAME deve iniciar com / e apontar para um arquivo/diretório existente.
Ao renomear um arquivo, este não pode ter acesso de leitura/escrita ativo.

Observações

NEW_NAME recebe somente o novo nome; o caminho de destino é o mesmo de PATH_NAME.
Recomenda-se restringir os nomes a A-Z, a-z, 0-9, . e _; o sistema não é case sensitive (DADOS.DAT e dados.dat são o mesmo arquivo).
O tamanho máximo do caminho e do novo nome é de 64 caracteres.

Ver também

FS_COPY_FILE, FS_DELETE_FILE_DIR, FS_CREATE_DIR, FS_EXIST_FILE_DIR

Exemplo

Clique aqui para baixar a tabela de variáveis

Código ST

VAR
    FILE_DADOS   : STRING := '/DADOS.DAT'; (* Caminho completo do arquivo, no diretório raiz *)
    FILE_BACKUP  : STRING := 'DADOS.BAK';  (* Novo nome do arquivo (sem caminho) *)
    MY_START     : BOOL := FALSE;          (* Ativação da função *)
    CUR_REN_NAME : STRING;                 (* Nome corrente a renomear, limitado a 64 caracteres *)
    NEW_REN_NAME : STRING;                 (* Novo nome, limitado a 64 caracteres *)
    RENAME_FILE  : HILS.FS_RENAME_FILE_DIR; (* Instancia do bloco "FS_RENAME_FILE_DIR" *)
END_VAR

//======================================================
// Exemplo 1 : Renomeia arquivo no diretorio raiz
//======================================================
// Renomeia o arquivo '/DADOS.DAT' (raiz) para 'DADOS.BAK', resultando em '/DADOS.BAK'.
CUR_REN_NAME := FILE_DADOS;  // caminho completo do arquivo origem, no diretório raiz
NEW_REN_NAME := FILE_BACKUP; // novo nome do arquivo destino

(* ... *)

//======================================================
// Exemplo 2 : Renomeia arquivo dentro de diretórios
//======================================================
// Renomeia '/P1/P2/P3/DADOS.DAT' para 'DADOS.BAK', resultando em '/P1/P2/P3/DADOS.BAK'.
CUR_REN_NAME := '/P1/P2/P3/DADOS.DAT'; // caminho completo do arquivo origem
NEW_REN_NAME := 'DADOS.BAK';           // novo nome do arquivo destino

(* ... *)

//======================================================
// Exemplo 3 : Renomeia Diretório na raiz do sistema de arquivo
//======================================================
// Renomeia o diretorio '/PASTA_1' (raiz) para 'PASTA_2', resultando em '/PASTA_2'.
CUR_REN_NAME := '/PASTA_1'; // caminho completo do diretorio origem
NEW_REN_NAME := 'PASTA_2';  // novo nome do diretorio destino

(* ... *)

//======================================================
// Exemplo 4 : Renomeia Diretório dentro de outros diretórios
//======================================================
// Renomeia o diretorio '/DADOS/MES/JAN' para 'FEV', resultando em '/DADOS/MES/FEV'.
CUR_REN_NAME := '/DADOS/MES/JAN'; // caminho completo do diretorio origem
NEW_REN_NAME := 'FEV';            // novo nome do diretorio destino

(* ... *)

//============================================================================
// Trata função FS_RENAME_FILE_DIR
//============================================================================
MY_START := TRUE;             // Ativação do bloco da função

(* ... *)

// Exemplo de ativação do bloco de função FS_RENAME_FILE_DIR
RENAME_FILE(
  START     := MY_START,        // [BOOL] Ativação da função
  PATH_NAME := CUR_REN_NAME,    // [STRING] Caminho completo com nome atual do arquivo/diretório
  NEW_NAME  := NEW_REN_NAME     // [STRING] Novo nome do arquivo/diretório, sem o caminho completo
  );

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

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

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

end_if;

(* ... *)