Cross Segmento - TOTVS Backoffice (Linha Protheus) - ADVPL - Diferenças entre as funções WaitRun e ShellExecute

Tempo aproximado para leitura: 00:03:00 min
 

Dúvida
Qual é a diferença de comportamento entre as funções WaitRun e ShellExecute e como utilizá-las?

Ambiente
Cross Segmento - TOTVS Backoffice (Linha Protheus) - ADVPL - A partir da versão 12.

Solução
As funções WaitRun e ShellExecute são utilizadas para acionar aplicações ou comandos externos através do sistema operacional da estação onde o TOTVS SmartClient/WebApp está sendo executado.
A principal diferença entre elas está no comportamento de aguardar ou não a finalização do processo e no escopo da chamada suportada.

Abaixo estão as características e exemplos de cada função:

WaitRun

• Executa e aguarda pelo término de um programa externo (arquivo executável).

• A função interrompe o processamento do código AdvPL aguardando o término da aplicação.
  Retorna 0 (zero) em caso de sucesso da execução do processo.

Exemplo de código com a WaitRun:

User Function ExWaitRun()
    Local nRet := 0
    
    // Executa a calculadora e aguarda seu encerramento
    // O parâmetro SW_SHOWNORMAL (1) indica que a janela abrirá normalmente
    MsgInfo("Vou executar a calculadora e aguardar o fechamento.")
    
    nRet := WaitRun("CALC.EXE", SW_SHOWNORMAL)
    
    If nRet == 0
        MsgInfo("A calculadora foi encerrada pelo usuário.")
    Else
        MsgStop("Falha ao executar ou erro do SO. Retorno: " + cValToChar(nRet))
    EndIf
Return

Observação:

• No Windows, aplicações UWP (Universal Windows Platform) podem não respeitar o bloqueio do WaitRun. Isso significa que a função pode retornar o controle de execução ao AdvPL antes da aplicação externa ser de fato finalizada.

• Algumas aplicações possuem mais de um processo (um para iniciar e outro para a interface gráfica). Essas aplicações podem não respeitar os parâmetros de visibilidade (como tentar esconder a janela com SW_HIDE ), ficando sempre visíveis e em primeiro plano, como é o caso da calculadora do Windows (calc.exe).

ShellExecute:

• Executa uma função, arquivo ou linha de comando no sistema operacional e não aguarda pelo seu retorno ou término.

• Pode ser utilizada para abrir URL de sites em navegadores ou outras abas.

• Se a função for bem-sucedida, retornará um valor maior que 32.

Exemplo de código com a ShellExecute:

User Function ExShellExec()
    Local nRet := 0
    Local nRet2 := 0
    
    // Exemplo 1: Abrindo uma URL no Windows
    // Sintaxe: ShellExecute(Acao, Arquivo, Parametros, Diretorio, OpcaoExibicao)
    nRet := ShellExecute("open", "http://tdn.totvs.com", "", "", 1)
    
    If nRet <= 32
        MsgStop("Falha ao abrir a URL. Código de Erro: " + cValToChar(nRet))
    EndIf

    // Exemplo 2: Executando no Linux
    // nRet := ShellExecute("Browser", "/usr/bin/firefox", "http://tdn.totvs.com", "/", 1)
     
    If nRet2 <= 32
        MsgStop("Falha ao abrir a URL. Código de Erro: " + cValToChar(nRet2))
    EndIf
Return

Observação:

• Diferente das outras funções, o ShellExecute está disponível apenas para ambientes Windows e Linux (ambos os Sistemas Operacionais devem estar homologados conforme a documentação  https://tdn.totvs.com/display/tec/SmartClient).

• A função possui suporte nativo para resolver variáveis de ambiente do sistema operacional diretamente nos parâmetros de arquivo e diretório, como o uso de "%PROGRAMFILES%".

• Caso a função falhe, ela não retorna apenas um erro genérico, mas sim um valor de erro entre 0 e 32. Por exemplo, o retorno 2 indica que o arquivo não foi encontrado (SE_ERR_FNF), e o retorno 5 indica acesso negado (SE_ERR_ACCESSDENIED).
   

Dica: Pode-se utilizar a função ShellExecute para realizar a abertura de um arquivo ou executável de um aplicativo;

Exemplo de código execução de um aplicativo com a ShellExecute:

User Function exteste()

	nRet := ShellExecute("open", "EXCEL.EXE" , "", "C:\" , 1)

	If nRet > 32
		ConOut("Comando enviado ao sistema operacional com sucesso.")
	Else
		ConOut("Falha na execução. Código de erro: " + cValToChar(nRet))
	EndIf
Return

Exemplo de código abertura de arquivo com a ShellExecute:

User Function xmlteste()
 
    nRet := ShellExecute("open", "C:\teste\teste.xml", "", "", 1)

    If nRet > 32
		ConOut("Comando enviado ao sistema operacional com sucesso.")
	Else
		ConOut("Falha na execução. Código de erro: " + cValToChar(nRet))
	EndIf
Return

Observações gerais:

• Para a WaitRun, é obrigatório o uso de aspas duplas adicionais caso o caminho do executável contenha espaços. Exemplo de Código: 

  WaitRun('"C:\my folder name\App.exe"').  

• Comportamento em JOB: Nenhuma destas funções (ShellExecute e WaitRun )pode ser executada a partir de um processo em JOB, visto que precisam ser iniciadas a partir de uma conexão do TOTVS SmartClient/WebApp.

• O WebApp e WebAgent precisam estar devidamente atualizados e habilitados na máquina local.

Saiba Mais
WaitRun
ShellExecute
Função ShellExecute para MacOS
Diferenças SmartClient DeskTop e SmartClient HTML (WebApp)
TOTVS | WebAgent