Saltar para o conteúdo principal
Versão: v20

SystemWorker

Os trabalhadores do sistema permitem que o código 4D chame qualquer processo externo (um comando shell, PHP, etc.) na mesma máquina. Os trabalhadores do sistema são chamados assíncronos. Ao utilizar os callbacks, 4D torna possível a comunicação de ambas as maneiras.

A classe SystemWorker está disponível na loja de classes 4D.

Exemplo

    // Exemplo Windows para obter acesso à informação ipconfig
var $myWinWorker : 4D.SystemWorker
var $ipConfig : Text
$myWinWorker:= 4D.SystemWorker.new("ipconfig")
$ipConfig:=$myWinWorker.wait(1).response //timeout 1 second

// exemplo macOS para mudar as permissões de um ficheiro no macOS
// chmod é o comando macOS usado para modificar o acesso a ficheiros
var $myMacWorker : 4D.SystemWorker
$myMacWorker:= 4D.SystemWorker.new("chmod +x /folder/myfile.sh")

Resumo

4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker    cria e devolve um objecto 4D.SystemWorker que executará a commandLine que passou como parâmetro para lançar um processo externo
.closeInput()    fecha o fluxo de entrada (stdin) do processo externo
.commandLine : Text    contém a linha de comando passada como parâmetro para a função new()
.currentDirectory : 4D.Folder    contém o directório de trabalho no qual o processo externo é executado
.dataType : Text    contém o tipo de conteúdo do corpo de resposta
.encoding : Text    contém a codificação do conteúdo do corpo de resposta
.errors : Collection    contém uma coleção de erros 4D em caso de erro(s) de execução, se existirem
.exitCode : Integer    contém o código de saída devolvido pelo processo externo
.hideWindow : Boolean    pode ser usado para esconder a janela da consola DOS ou a janela do executável lançado (Windows somente)
.pid : Integer    contém o identificador único de processo do processo externo a nível do sistema
.postMessage( message : Text)
.postMessage( messageBLOB : Blob)
    permite escrever no fluxo de entrada (stdin) do processo externo
.response : Text
.response : Blob
    contém a concatenação de todos os dados devolvidos quando o pedido é terminado
.responseError : Text    contém a concatenação de todos os erros devolvidos, uma vez terminado o pedido
.terminate()    força o SystemWorker a terminar a sua execução
.terminated : Boolean    contém true se o processo externo for terminado
.timeout : Integer    contém a duração, em segundos, antes de o processo externo ser encerrado, se ainda estiver activo
.wait( {timeout : Real} ) : 4D.SystemWorker    espera até ao final do SystemWorker execução ou o tempo limite especificado **

4D.SystemWorker.new()

Histórico
VersãoMudanças
v19 R4Adicionado

4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker

ParâmetroTipoDescrição
commandLineText->Linha de comando a executar
optionsObject->Parâmetros worker
result4D.SystemWorker<-Novo System worker assíncrono ou nulo se o processo não for iniciado

Descrição

A função 4D.SystemWorker.new() cria e devolve um objecto 4D.SystemWorker que executará a commandLine que passou como parâmetro para lançar um processo externo.

O objecto worker do sistema devolvido pode ser utilizado para postar mensagens ao worker e obter a saída do worker.

Se ocorrer um erro durante a criação do objecto proxy, a função devolve um objecto null e é lançado um erro.

No parâmetro commandLine, passar o caminho completo do arquivo da aplicação a ser executado (sintaxe posix), bem como quaisquer argumentos necessários, se necessário. Se passar apenas o nome da aplicação, 4D utilizará a variável de ambiente PATH para localizar o executável.

Advertência: Esta função só pode lançar aplicações executáveis; não pode executar instruções que fazem parte da shell (intérprete de comandos). Por exemplo, sob Windows não é possível utilizar este comando para executar a instrução dir.

Objecto options

No parâmetro opções , passe um objeto que possa conter as seguintes propriedades:

PropriedadeTipoPor padrãoDescrição
onResponseFormulaindefinidoChamada de retorno para mensagens de worker do sistema. Esta chamada de retorno é chamada assim que a resposta completa é recebida. Recebe dois objectos como parâmetros (ver abaixo)
onDataFormulaindefinidoChamada de retorno para os dados do worker do sistema. Esta chamada de retorno é chamada cada vez que o worker do sistema recebe dados. Recebe dois objectos como parâmetros (ver abaixo)
onDataErrorFormulaindefinidoChamada de retorno para os erros do processo externo (stderr do processo externo). Recebe dois objectos como parâmetros (ver abaixo)
onErrorFormulaindefinidoChamada de retorno para erros de execução, devolvida pelo worker do sistema em caso de condições anormais de tempo de execução (erros de sistema). Recebe dois objectos como parâmetros (ver abaixo)
onTerminateFormulaindefinidoChamada de retorno quando o processo externo é terminado. Recebe dois objectos como parâmetros (ver abaixo)
timeoutNumberindefinidoTempo em segundos antes de o processo ser terminado se ainda estiver vivo
dataTypeText"text"Tipo de conteúdo do corpo da resposta. Valores possíveis: "text" (predefinição), "blob".
encodingText"UTF-8"Sólo si dataType="text". Codificação do conteúdo do corpo da resposta. Para obter a lista de valores disponíveis, consulte a descrição do comando CONVERT FROM TEXT
variablesObjectDefine variáveis de ambiente personalizadas para o system worker. Sintaxe: variables.key=value, onde key é o nome da variável e valor o seu valor. Os valores são convertidos em cordas quando possível. O valor não pode conter um '='. Se não estiver definido, o system worker herda do ambiente 4D.
currentDirectoryFolderDirectório de trabalho no qual o processo é executado
hideWindowParâmetrostrue(Windows) Esconder a janela de aplicação (se possível) ou a consola Windows

Todas as funções de chamada de retorno recebem dois parâmetros de objectos. O seu conteúdo depende do retorno da chamada:

ParâmetroTipoonResponseonDataonDataErroronErroronTerminate
$param1ObjectSystemWorkerSystemWorkerSystemWorkerSystemWorkerSystemWorker
$param2.typeText"response""data""error""error""termination"
$param2.dataText ou Blobdados recebidosdados de erro

Aqui está a sequência de chamadas de retorno:

  1. onData e onDataError são executados uma ou várias vezes
  2. se chamado, onError é executado uma vez (pára o processamento do system worker)
  3. se não ocorreu nenhum erro, onResponse é executado uma vez
  4. onTerminate é sempre executado

Valor retornado

A função devolve um objecto system worker sobre o qual se pode chamar funções e propriedades da classe SystemWorker.

Exemplos no Windows

  1. Para abrir o Bloco de Notas e abrir um documento específico:
var $sw : 4D.SystemWorker
var $options : Object
$options:=New object
$options.hideWindow:= False

$sw:=4D.SystemWorker.new ("C:\\WINDOWS\\notepad.exe C:\\Docs\\new folder\\res.txt";$options)
  1. Executar npm instalar na consola:
var $folder : 4D.Folder
var $options : Object
var $worker : 4D.SystemWorker

$folder:=Folder(fk database folder)
$options:=New object
$options.currentDirectory:=$folder
$options.hideWindow:=False

$worker:=4D.SystemWorker.new("cmd /c npm install";$options)

  1. Para lançar a aplicação Microsoft® Word® e abrir um documento específico:
$mydoc:="C:\\Program Files\\Microsoft Office\\Office15\\WINWORD.EXE C:\\Tempo\\output.txt"
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new($mydoc)
  1. Para lançar um comando com o diretório atual e publicar uma mensagem:
var $param : Object
var $sys : 4D.SystemWorker

$param:=New object
$param.currentDirectory:=Folder(fk database folder)
$sys:=4D.SystemWorker.new("git commit -F -";$param)
$sys.postMessage("This is a postMessage")
$sys.closeInput()
  1. Para permitir que o utilizador abra um documento externo no Windows:
$docname:=Select document("";"*.*";"Choose the file to open";0)
If(OK=1)
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new("cmd.exe /C start \"\" \""+$docname+"\"")
End if

Exemplos em macOS

  1. Editar um arquivo de texto (cat é o comando macOS utilizado para editar arquivos). Neste exemplo, o caminho de acesso completo do comando é passado:

var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new("/bin/cat /folder/myfile.txt")
$sw.wait() /execução síncrona

  1. Para lançar uma aplicação "gráfica" independente, é preferível utilizar o comando do sistema open (neste caso, o código tem o mesmo efeito que um duplo clique na aplicação):
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new ("open /Applications/Calculator.app")
  1. Para obter o conteúdo da pasta "Users" (ls -l é o equivalente em macOS do comando dir em DOS).
var $systemworker : 4D.SystemWorker
var $output : Text
var $errors : Collection

$systemworker:=4D.SystemWorker.new("/bin/ls -l /Users ")
$systemworker.wait(5)
$output:=$systemworker.response
$error:=$systemworker.errors

  1. O mesmo comando que acima, mas usando uma amostra de classe de utilizador "Params" para mostrar como lidar com as funções de callback:

var $systemworker : 4D.SystemWorker
$systemworker:=4D.SystemWorker.new("/bin/ls -l /Users ";cs.Params.new())


// "Params" class

Class constructor
This.dataType:="text"
This.data:=""
This.dataError:=""

Function onResponse($systemWorker : Object)
This._createFile("onResponse"; $systemWorker.response)

Function onData($systemWorker : Object; $info : Object)
This.data+=$info.data
This._createFile("onData";this.data)

Function onDataError($systemWorker : Object; $info : Object)
This.dataError+=$info.data
This._createFile("onDataError";this.dataError)

Function onTerminate($systemWorker : Object)
var $textBody : Text
$textBody:="Response: "+$systemWorker.response
$textBody+="ResponseError: "+$systemWorker.responseError
This._createFile("onTerminate"; $textBody)

Function _createFile($title : Text; $textBody : Text)
TEXT TO DOCUMENT(Get 4D folder(Current resources folder)+$title+".txt"; $textBody)

.closeInput()

Histórico
VersãoMudanças
v19 R4Adicionado

.closeInput()

ParâmetroTipoDescrição
Não exige nenhum parâmetro

|

Descrição

A função .closeInput() fecha o fluxo de entrada (stdin) do processo externo.

Quando o executável espera que todos os dados sejam recebidos através de postMessage(), .closeInput() é útil para indicar ao executável que o envio de dados está terminado e que pode prosseguir.

Exemplo

// Criar alguns dados para gzip
var $input;$output : Blob
var $gzip : Text
TEXT TO BLOB("Hello, World!";$input)
$gzip:="\"C:\\Program Files (x86)\\\GnuWin32\\bin\\gzip.exe\" "

// Criar um system worker assíncrono
var $worker : 4D.SystemWorker
$worker:= 4D.SystemWorker.new($gzip;New object("dataType"; "blob"))

// Enviar o ficheiro comprimido para stdin.
$worker.postMessage($input)
// Note que chamamos closeInput() para indicar que terminámos.
// gzip (e a maioria dos dados de espera do programa stdin) esperará por mais dados até que a entrada seja explícitamente fechada.
$worker.closeInput()
$worker.wait()

$output:=$worker.response

.commandLine

.commandLine : Text

Descrição

A propriedade .commandLine contém a linha de comando passada como parâmetro para a função new().

Essa propriedade é apenas leitura.

.currentDirectory

.currentDirectory : 4D.Folder

Descrição

A propriedade .currentDirectory contém o directório de trabalho no qual o processo externo é executado.

.dataType

.dataType : Text

Descrição

A propriedade .dataType contém o tipo de conteúdo do corpo de resposta. Valores possíveis: "text" ou "blob".

Essa propriedade é apenas leitura.

.encoding

.encoding : Text

Descrição

A propriedade .encoding contém a codificação do conteúdo do corpo de resposta. Esta propriedade só está disponível se o dataType é "text".

Essa propriedade é apenas leitura.

.errors

.errors : Collection

Descrição

A propriedade .erros contém uma coleção de erros 4D em caso de erro(s) de execução, se existirem.

Cada elemento da coleção é um objeto com as seguintes propriedades:

PropriedadeTipoDescrição
[].errorCodenumberCódigo de erro 4D
[].messagetextDescrição do erro 4D
[ ].componentSignaturetextAssinatura da componente interna que devolveu o erro

Se não tiver ocorrido nenhum erro, .errors é indefinido.

.exitCode

.exitCode : Integer

Descrição

A propriedade .exitCode contém o código de saída devolvido pelo processo externo. Se o processo não tiver terminado normalmente, exitCode é undefined.

Essa propriedade é apenas leitura.

.hideWindow

.hideWindow : Boolean

Descrição

A propriedade .hideWindow pode ser usado para esconder a janela da consola DOS ou a janela do executável lançado (Windows somente).

Essa propriedade éapenas escrita.

.pid

.pid : Integer

Descrição

A propriedade .pid contém o identificador único de processo do processo externo a nível do sistema.

Essa propriedade é apenas leitura.

.postMessage()

.postMessage( message : Text)
.postMessage( messageBLOB : Blob)

ParâmetroTipoDescrição
messageText->Texto para escrever no fluxo de entrada (stdin) do processo externo
messageBLOBBlob->Bytes escritos no fluxo de entrada

|

Descrição

A função .postMessage() permite escrever no fluxo de entrada (stdin) do processo externo. No parâmetro message, passar o texto a escrever em stdin.

A função .postMessage() também aceita um valor do tipo Blob em messageBLOB para passar em stdin, para que possa publicar dados binários.

Pode utilizar a propriedade .dataType do objecto options para fazer retornar valores Blob do corpo de resposta.

.response

.response : Text
.response : Blob

Descrição

A propriedade .response contém a concatenação de todos os dados devolvidos quando o pedido é terminadoou seja, a mensagem completa recebida da saída do processo.

O tipo da mensagem é definido de acordo com o atributo dataType.

Essa propriedade é apenas leitura.

.responseError

.responseError : Text

Descrição

A propriedade .responseError contém a concatenação de todos os erros devolvidos, uma vez terminado o pedido.

.terminate()

.terminate()

ParâmetroTipoDescrição
Não exige nenhum parâmetro

|

Descrição

A função .terminate() força o SystemWorker a terminar a sua execução.

Esta função envia a instrução para terminar e devolver o controlo ao guião de execução.

.terminated

.terminated : Boolean

Descrição

A propriedade .terminated contém true se o processo externo for terminado.

Essa propriedade é apenas leitura.

.timeout

.timeout : Integer

Descrição

A propriedade .timeout contém a duração, em segundos, antes de o processo externo ser encerrado, se ainda estiver activo.

Essa propriedade é apenas leitura.

.wait()

Histórico
VersãoMudanças

|v19 R4|Added|

.wait( {timeout : Real} ) : 4D.SystemWorker

ParâmetroTipoDescrição
timeoutReal->Tempo de espera (em segundos)
Resultados4D.SystemWorker<-Objecto SystemWorker

|

Descrição

A função .wait() espera até ao final do SystemWorker execução ou o tempo limite especificado **.

Em timeout, passe um valor em segundos. O script SystemWorker aguardará o processo externo pelo tempo definido no parâmetro timeout. Se omitir o parâmetro timeout, a execução do guião esperará indefinidamente.

Na verdade, .wait() espera até ao fim do processamento da fórmula onTerminate, excepto se o tempo limite * for alcançado. Se timeout* for alcançado, o SystemWorker não é morto.

Durante uma execução .wait(), são executadas funções de callback, especialmente callbacks de outros eventos ou de outros SystemWorker instâncias. Pode sair de um .wait() ligando para terminate() a partir de uma chamada de retorno.

Esta função devolve o objecto SystemWorker.

Esta função não é necessária se tiver criado o SystemWorker a partir de um processo de trabalhador 4D.