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ão	Mudanças
v19 R4	Adicionado

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

Parâmetro	Tipo		Descrição
commandLine	Text	->	Linha de comando a executar
options	Object	->	Parâmetros worker
result	4D.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:

Propriedade	Tipo	Por padrão	Descrição
onResponse	Formula	indefinido	Chamada 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)
onData	Formula	indefinido	Chamada 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)
onDataError	Formula	indefinido	Chamada de retorno para os erros do processo externo (stderr do processo externo). Recebe dois objectos como parâmetros (ver abaixo)
onError	Formula	indefinido	Chamada 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)
onTerminate	Formula	indefinido	Chamada de retorno quando o processo externo é terminado. Recebe dois objectos como parâmetros (ver abaixo)
timeout	Number	indefinido	Tempo em segundos antes de o processo ser terminado se ainda estiver vivo
dataType	Text	"text"	Tipo de conteúdo do corpo da resposta. Valores possíveis: "text" (predefinição), "blob".
encoding	Text	"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
variables	Object		Define 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.
currentDirectory	Folder		Directório de trabalho no qual o processo é executado
hideWindow	Parâmetros	true	(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âmetro	Tipo	onResponse	onData	onDataError	onError	onTerminate
$param1	Object	SystemWorker	SystemWorker	SystemWorker	SystemWorker	SystemWorker
$param2.type	Text	"response"	"data"	"error"	"error"	"termination"
$param2.data	Text ou Blob		dados recebidos	dados 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)

2. 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)

3. 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)

4. 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()

5. 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

2. 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")

3. 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

4. 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ão	Mudanças
v19 R4	Adicionado

.closeInput()

Parâmetro	Tipo		Descriçã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:

Propriedade	Tipo	Descrição
[].errorCode	number	Código de erro 4D
[].message	text	Descrição do erro 4D
[ ].componentSignature	text	Assinatura 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âmetro	Tipo		Descrição
message	Text	->	Texto para escrever no fluxo de entrada (stdin) do processo externo
messageBLOB	Blob	->	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âmetro	Tipo		Descriçã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ão	Mudanças

|v19 R4|Added|

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

Parâmetro	Tipo		Descrição
timeout	Real	->	Tempo de espera (em segundos)
Resultados	4D.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.