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](#currentdirectory) contiene el directorio de trabajo en el que se ejecuta el proceso externo |
| .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 puede utilizarse para ocultar la ventana de la consola DOS o la ventana del ejecutable lanzado (sólo Windows) |
| .pid : Integer contiene el identificador único del proceso externo a nivel de sistema |
| .postMessage( message : Text) .postMessage( messageBLOB : Blob) permite escribir en el flujo de entrada (stdin) del proceso externo |
| .response : Text .response : Blob contiene la concatenación de todos los datos devueltos una vez finalizada la petición |
| .responseError : Text contiene la concatenación de todos los errores devueltos, una vez finalizada la petición |
| .terminate() fuerza al SystemWorker a terminar su ejecución |
| .terminated : Boolean contiene true si el proceso externo está terminado |
| .timeout : Integer contiene la duración en segundos antes de que el proceso externo sea eliminado si sigue vivo |
| .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:
onDatayonDataErrorse ejecutan una o varias veces- si se llama,
onErrorse ejecuta una vez (detiene el procesamiento del system worker) - si no se ha producido ningún error,
onResponsese ejecuta una vez onTerminatese ejecuta siempre una vez
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
- 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)
- 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)
- 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)
- 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()
- 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
- Modificar un archivo texto (
cates 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
- 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")
- 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
- 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
La propiedad .currentDirectory contiene el directorio de trabajo en el que se ejecuta el proceso externo.
.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 |
Si no se ha producido ningún error, .errors es indefinido.
.exitCode
.exitCode : Integer
Descripción
La propiedad .exitCode contiene el código de salida devuelto por el proceso externo. Si el proceso no terminó normalmente, exitCode es undefined.
Esta propiedad es de solo lectura.
.hideWindow
.hideWindow : Boolean
Descripción
La propiedad .hideWindow puede utilizarse para ocultar la ventana de la consola DOS o la ventana del ejecutable lanzado (sólo Windows).
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 escritos en el flujo de entrada |
Descripción
La función .postMessage() permite escribir en el flujo de entrada (stdin) del proceso externo. En el parámetro mensaje, pase el texto a escribir en stdin.
La función .postMessage() también acepta un valor de tipo Blob en messageBLOB para pasar en stdin, de forma que se pueden publicar datos binarios.
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
La propiedad .response contiene la concatenación de todos los datos devueltos una vez finalizada la petición, es decir, el mensaje completo recibido de la salida del proceso.
El tipo del mensaje se define en función del atributo dataType.
Esta propiedad es de solo lectura.
.responseError
.responseError : Text
Descripción
La propiedad .responseError contiene la concatenación de todos los errores devueltos, una vez finalizada la petición.
.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
La propiedad .timeout contiene la duración en segundos antes de que el proceso externo sea eliminado si sigue vivo.
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) |
| Result | 4D.SystemWorker | <- | Objeto SystemWorker |
Descripción
La función .wait() espera hasta el final de la ejecución del SystemWorker o el timeout especificado.
En timeout, pase un valor en segundos. El script SystemWorker esperará al proceso externo durante el tiempo definido en el parámetro timeout. Si omite el parámetro timeout, la ejecución del script esperará indefinidamente.
En realidad, .wait() espera hasta el final del procesamiento de la fórmula onTerminate, excepto si se alcanza el timeout. Si se alcanza el timeout, no se elimina el SystemWorker.
Durante una ejecución de .wait() se ejecutan las funciones de retrollamada, especialmente las retrollamadas provienen de otros eventos o de otras instancias de SystemWorker. 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
SystemWorkerdesde un proceso worker 4D.