SystemWorker

Los System workers permiten que el código 4D llame a cualquier proceso externo (un comando shell, PHP, etc.) en la misma máquina. Los trabajadores del sistema se llaman de forma asíncrona. Mediante el uso de retrollamadas, 4D hace posible la comunicación en ambos sentidos.

La clase SystemWorker está disponible en el class store 4D.

Ejemplo

    // Ejemplo Windows para acceder a la información de ipconfig
var $myWinWorker : 4D.SystemWorker
var $ipConfig : Text
$myWinWorker:= 4D.SystemWorker.new("ipconfig")
$ipConfig:=$myWinWorker.wait(1).response //timeout 1 segundo

    // ejemplo macOS para cambiar los permisos de un archivo en macOS
    // chmod es el comando macOS utilizado para modificar el acceso a los archivos
var $myMacWorker : 4D.SystemWorker
$myMacWorker:= 4D.SystemWorker.new("chmod +x /folder/myfile.sh")

Resumen

4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker crea y devuelve un objeto 4D.SystemWorker que ejecutará el commandLine que pasó como parámetro para lanzar un proceso externo
.closeInput() cierra el flujo de entrada (stdin) del proceso externo
.commandLine : Text contiene la línea de comandos pasada como parámetro a la función new()
.currentDirectory : 4D.Folder contains the working directory in which the external process is executed
.dataType : Text contiene el tipo de contenido del cuerpo de la respuesta
.encoding : Text contiene la codificación del contenido del cuerpo de la respuesta
.errors : Collection contiene una colección de errores 4D en caso de error(es) de ejecución si los hubiera
.exitCode : Integer contiene el código de salida devuelto por el proceso externo
.hideWindow : Boolean can be used to hide the window of the DOS console or the window of the launched executable (Windows only)
.pid : Integer contiene el identificador único del proceso externo a nivel de sistema
.postMessage( message : Text) .postMessage( messageBLOB : Blob) allows you to write on the input stream (stdin) of the external process
.response : Text .response : Blob contains the concatenation of all data returned once the request is terminated
.responseError : Text contains the concatenation of all the errors returned, once the request is terminated
.terminate() fuerza al SystemWorker a terminar su ejecución
.terminated : Boolean contiene true si el proceso externo está terminado
.timeout : Integer contains the duration in seconds before the external process will be killed if it is still alive
.wait( {timeout : Real} ) : 4D.SystemWorker espera hasta el final de la ejecución del SystemWorker o el timeout especificado

4D.SystemWorker.new()

Historia

Lanzamiento	Modificaciones
19 R4	Añadidos

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

Parámetros	Tipo		Descripción
commandLine	Text	->	Línea de comando a ejecutar
options	Object	->	Parámetros worker
resultado	4D.SystemWorker	<-	Nuevo System worker asíncrono o null si el proceso no se ha iniciado

Descripción

La función 4D.SystemWorker.new() crea y devuelve un objeto 4D.SystemWorker que ejecutará el commandLine que pasó como parámetro para lanzar un proceso externo.

El objeto system worker devuelto puede utilizarse para enviar mensajes al worker y obtener los resultados del worker.

Si se produce un error durante la creación del objeto proxy, la función devuelve un objeto null y se lanza un error.

En el parámetro commandLine, pase la ruta completa del archivo de la aplicación a ejecutar (sintaxis posix), así como los argumentos necesarios, si es el caso. Si sólo pasa que el nombre de la aplicación, 4D utilizará la variable de entorno PATH para localizar el ejecutable.

Atención: esta función sólo puede lanzar aplicaciones ejecutables; no puede ejecutar las instrucciones que formen parte del shell (intérprete de comandos). Por ejemplo, en Windows no es posible utilizar este comando para ejecutar la instrucción dir.

Objeto options

En el parámetro options, pase un objeto que puede contener las siguientes propiedades:

Propiedad	Tipo	Por defecto	Descripción
onResponse	Formula	indefinido	Retrollamada para los mensajes del system worker. Esta retrollamada se llama una vez que se recibe la respuesta completa. Recibe dos objetos como parámetros (ver más abajo)
onData	Formula	indefinido	Retrollamada para los datos del system worker. Esta retrollamada se llama cada vez que el system worker recibe los datos. Recibe dos objetos como parámetros (ver más abajo)
onDataError	Formula	indefinido	Callback para los errores del proceso externo (stderr del proceso externo). Recibe dos objetos como parámetros (ver más abajo)
onError	Formula	indefinido	Retrollamada para los errores de ejecución, devueltos por el system worker en caso de condiciones de ejecución inusuales (errores del sistema). Recibe dos objetos como parámetros (ver más abajo)
onTerminate	Formula	indefinido	Retrollamada cuando el proceso externo se termina. Recibe dos objetos como parámetros (ver más abajo)
timeout	Number	indefinido	Tiempo en segundos antes de que el proceso sea eliminado si aún está activo
dataType	Text	"text"	Tipo de contenido del cuerpo de la respuesta. Valores posibles: "text" (por defecto), "blob".
encoding	Text	"UTF-8"	Sólo si dataType="text". Codificación del contenido del cuerpo de la respuesta. Para la lista de valores disponibles, consulte la descripción del comando CONVERT FROM TEXT
variables	Object		Define las variables de entorno personalizadas para el system worker. Sintaxis: variables.clave=valor, donde key es el nombre de la variable y value su valor. Los valores se convierten en cadenas de caracters cuando es posible. El valor no puede contener un '='. Si no se define, el system worker hereda del entorno 4D.
currentDirectory	Folder		Directorio de trabajo en el que se ejecuta el proceso
hideWindow	Boolean	true	(Windows) Ocultar la ventana de la aplicación (si es posible) o la consola Windows

Todas las funciones de retrollamada reciben dos parámetros objeto. Su contenido depende de la retrollamada:

Parámetros	Tipo	onResponse	onData	onDataError	onError	onTerminate
$param1	Object	SystemWorker	SystemWorker	SystemWorker	SystemWorker	SystemWorker
$param2.type	Text	"response"	"data"	"error"	"error"	"termination"
$param2.data	Text o Blob		datos recibidos	datos de error

Esta es la secuencia de llamadas de retorno:

1. onData y onDataError se ejecutan una o varias veces
2. si se llama, onError se ejecuta una vez (detiene el procesamiento del system worker)
3. si no se ha producido ningún error, onResponse se ejecuta una vez
4. onTerminate se ejecuta siempre una vez

info

Para que las funciones de retrollamada se llamen cuando no utilice wait() (llamada asíncrona), el proceso debe ser un worker creado con CALL WORKER, NO New process.

Valor devuelto

La función devuelve un objeto system worker sobre el que se pueden llamar las funciones y las propiedades de la clase SystemWorker.

Ejemplos en Windows

1. Para abrir el Bloc de notas y abrir un 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. Ejecutar npm install en la 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 lanzar la aplicación Microsoft® Word® y abrir un 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 lanzar un comando con el directorio actual y publicar un mensaje:

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 al usuario abrir un documento externo en 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

Ejemplos en macOS

1. Modificar un archivo texto (cat es el comando macOS utilizado para editar archivos). En este ejemplo, se pasa la ruta de acceso completa del comando:

var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new("/bin/cat /folder/myfile.txt")
$sw.wait() /ejecución síncrona

2. Para lanzar una aplicación "gráfica" independiente, es preferible utilizar el comando sistema open (en este caso, el código tiene el mismo efecto que hacer doble clic en la aplicación):

var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new ("open /Applications/Calculator.app")

3. Para obtener el contenido de la carpeta "Users" (ls -l es el equivalente en macOS del comando dir en 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. El mismo comando que el anterior, pero utilizando un ejemplo de clase usuario "Params" para mostrar cómo manejar las funciones de retrollamada:

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

Historia

Lanzamiento	Modificaciones
19 R4	Añadidos

.closeInput()

Parámetros	Tipo		Descripción
			No requiere ningún parámetro

Descripción

La función .closeInput() cierra el flujo de entrada (stdin) del proceso externo.

Cuando el ejecutable espera a recibir todos los datos a través de postMessage(), .closeInput() es útil para indicar al ejecutable que el envío de datos ha terminado y que puede continuar.

Ejemplo

// Crear algunos datos para gzip
var $input;$output : Blob
var $gzip : Texto
TEXT TO BLOB("¡Hola, Mundo!";$input)
$gzip:="\"C:\\Program Files (x86)\\GnuWin32\bin\gzip.exe\" "

// Crear un system worker asíncrono
var $worker : 4D.SystemWorker
$worker:= 4D.SystemWorker.new($gzip;New object("dataType"; "blob"))

// Envía el archivo comprimido en stdin.
$worker.postMessage($input)
// Observe que llamamos a closeInput() para indicar que hemos terminado.
// gzip (y la mayoría de los programas que esperan datos de stdin) esperarán más datos hasta que se cierre explícitamente la entrada.
$worker.closeInput()
$worker.wait()

$output:=$worker.response

.commandLine

.commandLine : Text

Descripción

La propiedad .commandLine contiene la línea de comandos pasada como parámetro a la función new().

Esta propiedad es de solo lectura.

.currentDirectory

.currentDirectory : 4D.Folder

Descripción

The .currentDirectory property contains the working directory in which the external process is executed.

.dataType

.dataType : Text

Descripción

La propiedad .dataType contiene el tipo de contenido del cuerpo de la respuesta. Valores posibles: "text" o "blob".

Esta propiedad es de solo lectura.

.encoding

.encoding : Text

Descripción

La propiedad .encoding contiene la codificación del contenido del cuerpo de la respuesta. Esta propiedad sólo está disponible si el dataType es "text".

Esta propiedad es de solo lectura.

.errors

.errors : Collection

Descripción

La propiedad .errors contiene una colección de errores 4D en caso de error(es) de ejecución si los hubiera.

Cada elemento de la colección es un objeto con las siguientes propiedades:

Propiedad	Tipo	Descripción
[].errorCode	number	Código de error 4D
[].message	text	Descripción del error 4D
[ ].componentSignature	text	Firma del componente interno que ha devuelto el error

If no error occured, .errors is undefined.

.exitCode

.exitCode : Integer

Descripción

La propiedad .exitCode contiene el código de salida devuelto por el proceso externo. If the process did not terminate normaly, exitCode is undefined.

Esta propiedad es de solo lectura.

.hideWindow

.hideWindow : Boolean

Descripción

The .hideWindow property can be used to hide the window of the DOS console or the window of the launched executable (Windows only).

Esta propiedad está en lectura-escritura.

.pid

.pid : Integer

Descripción

La propiedad .pid contiene el identificador único del proceso externo a nivel de sistema.

Esta propiedad es de solo lectura.

.postMessage()

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

Parámetros	Tipo		Descripción
message	Text	->	Texto a escribir en el flujo de entrada (stdin) del proceso externo
messageBLOB	Blob	->	Bytes write on the input stream

Descripción

The .postMessage() function allows you to write on the input stream (stdin) of the external process. In the message parameter, pass the text to write in stdin.

The .postMessage() function also accepts a Blob type value in messageBLOB to pass in stdin, so that you can post binary data.

Puede utilizar la propiedad .dataType del objeto options para hacer que el cuerpo de la respuesta devuelva valores Blob.

.response

.response : Text
.response : Blob

Descripción

The .response property contains the concatenation of all data returned once the request is terminated, i.e. the full message received from the process output.

El tipo del mensaje se define en función del atributo dataType.

Esta propiedad es de solo lectura.

.responseError

.responseError : Text

Descripción

The .responseError property contains the concatenation of all the errors returned, once the request is terminated.

.terminate()

.terminate()

Parámetros	Tipo		Descripción
			No requiere ningún parámetro

Descripción

La función .terminate() fuerza al SystemWorker a terminar su ejecución.

Esta función envía la instrucción de terminar y devolver el control al script en ejecución.

.terminated

.terminated : Boolean

Descripción

La propiedad .terminated contiene true si el proceso externo está terminado.

Esta propiedad es de solo lectura.

.timeout

.timeout : Integer

Descripción

The .timeout property contains the duration in seconds before the external process will be killed if it is still alive.

Esta propiedad es de solo lectura.

.wait()

Historia

Lanzamiento	Modificaciones

|19 R4|Añadido|

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

Parámetros	Tipo		Descripción
timeout	Real	->	Tiempo de espera (en segundos)
Resultado	4D.SystemWorker	<-	Objeto SystemWorker

Descripción

La función .wait() espera hasta el final de la ejecución del SystemWorker o el timeout especificado.

In timeout, pass a value in seconds. The SystemWorker script will wait for the external process for the amount of time defined in the timeout parameter. If you omit the timeout parameter, the script execution will wait indefinitely.

Actually, .wait() waits until the end of processing of the onTerminate formula, except if the timeout is reached. Si se alcanza el timeout, no se elimina el SystemWorker.

During a .wait() execution, callback functions are executed, especially callbacks from other events or from other SystemWorker instances. Puede salir de un .wait() llamando a terminate() desde un callback.

Esta función devuelve el objeto SystemWorker.

Esta función no es necesaria si creó el SystemWorker desde un proceso worker 4D.