SystemWorker

Os System workers 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 no class store 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 retorna um objeto 4D.SystemWorker que executará o commandLine que você passou como parâmetro para iniciar 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 diretó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 da resposta
.errors : Collection contém uma coleção de erros 4D em caso de erro(s) de execução(ões) se algum
.exitCode : Integer contém o código de saída retornado pelo processo externo
.hideWindow : Boolean pode ser usado para ocultar a janela do console DOS ou a janela do executável (apenas Windows)
.pid : Integer contém o identificador exclusivo do processo externo no nível do sistema
.postMessage( message : Text) .postMessage( messageBLOB : Blob) permite que você escreva no fluxo de entrada (stdin) do processo externo
.response : Text .response : Blob
.responseError : Text contém a concatenação de todos os erros retornados, uma vez que a solicitação é encerrada
.terminate()
.terminated : Boolean contém true se o processo externo for encerrado
.timeout : Integer contém a duração em segundos antes que o processo externo seja encerrado se ainda estiver ativo
.wait( {timeout : Real} ) : 4D.SystemWorker aguarda até o final da execução do SystemWorker ou até o timeout especificado

4D.SystemWorker.new()

História

Release	Mudanças
19 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
resultado	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 retorna um objeto 4D.SystemWorker que executará o commandLine que você passou como parâmetro para iniciar 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 objeto proxy, a função retornará um objeto null e um erro será lançado.

No parâmetro commandLine, passe o caminho completo do arquivo do aplicativo a ser executado (sintaxe posix), bem como os argumentos necessários, se for o caso. Se você passar apenas o nome da aplicação, o 4D usará 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, no Windows não é possível usar este comando para executar a instrução dir.

Objeto options

No parâmetro options, 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	Callback 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"	Somente se 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: variáveis.key=valor, onde chave é o nome da variável e valor 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 uma vez

info

Para as funções de callback serem chamadas quando você não usa wait() (chamada assíncrona), o processo deve ser um worker criado com CALL WORKER, NÃO New process.

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 os 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ória

Release	Mudanças
19 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 por postMessage(), .closeInput() é útil para indicar ao executável que o envio de dados foi concluído e ele poder prosseguir.

Exemplo

// Crie 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"))

// Envie o arquivo compactado para stdin.
$worker.postMessage($input)
// Observe que chamamos closeInput() para indicar que terminamos.
// O gzip (e a maioria dos programas que aguardam dados do stdin) aguardará mais dados até que a entrada seja explicitamente 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 é somente leitura.

.currentDirectory

.currentDirectory : 4D.Folder

Descrição

A propriedade .currentDirectory contém o diretó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 é somente leitura.

.encoding

.encoding : Text

Descrição

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

Essa propriedade é somente leitura.

.errors

.errors : Collection

Descrição

A propriedade .errors contém uma coleção de erros 4D em caso de erro(s) de execução(ões) se algum.

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 ocorrer nenhum erro, .errors será undefined.

.exitCode

.exitCode : Integer

Descrição

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

Essa propriedade é somente leitura.

.hideWindow

.hideWindow : Boolean

Descrição

A propriedade .hideWindow pode ser usado para ocultar a janela do console DOS ou a janela do executável (apenas Windows).

Essa propriedade é leitura-escrita.

.pid

.pid : Integer

Descrição

A propriedade .pid contém o identificador exclusivo do processo externo no nível do sistema.

Essa propriedade é somente 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 que você escreva no fluxo de entrada (stdin) do processo externo. No parâmetro message, passe o texto a ser escrito em stdin.

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

Você pode usar a propriedade .dataType do objeto options para fazer o corpo da resposta retornar valores Blob.

.response

.response : Text
.response : Blob

Descrição

A propriedade .response contém a concatenação de todos os dados retornados assim que o pedido for encerrado, ou seja, a mensagem completa recebida da saída do processo.

O tipo da mensagem é definido conforme o atributo dataType.

Essa propriedade é somente leitura.

.responseError

.responseError : Text

Descrição

A propriedade .responseError contém a concatenação de todos os erros retornados, uma vez que a solicitação é encerrada.

.terminate()

.terminate()

Parâmetro	Tipo		Descrição
			Não exige nenhum parâmetro

Descrição

A função .terminate() força o SystemWorker a encerrar 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 encerrado.

Essa propriedade é somente leitura.

.timeout

.timeout : Integer

Descrição

A propriedade .timeout contém a duração em segundos antes que o processo externo seja encerrado se ainda estiver ativo.

Essa propriedade é somente leitura.

.wait()

História

Release	Mudanças

|19 R4|Adicionado|

.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() aguarda até o final da execução do SystemWorker ou até o timeout especificado.

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

Na verdade, .wait() aguarda até o final do processamento da fórmula onTerminate, exceto se o timeout for atingido. Se timeout for alcançado, o SystemWorker não é morto.

Durante uma execução .wait(), as funções de retorno de chamada são executadas, especialmente retornos de chamada de outros eventos ou de outras instâncias do SystemWorker. Você pode sair de um .wait() chamando terminate() de um retorno de chamada.

Esta função devolve o objecto SystemWorker.

Esta função não é necessária se você criou o SystemWorker de um processo de trabalho 4D.