SystemWorker
Les System workers permettent au code 4D d'appeler n'importe quel process externe (une commande shell, PHP, etc.) sur la même machine. Les System workers sont appelés de manière asynchrone. En utilisant des callbacks, 4D permet de communiquer dans les deux sens.
La classe SystemWorker est disponible dans le class store 4D .
Exemple
// Exemple Windows pour avoir accès aux informations d'ipconfig
var $myWinWorker : 4D.SystemWorker
var $ipConfig : Text
$myWinWorker:= 4D.SystemWorker.new("ipconfig")
$ipConfig:=$myWinWorker.wait(1).response //timeout 1 seconde
// Exemple macOS pour modifier les permissions d'un fichier sous macOS
// chmod est la commande macOS utilisée pour modifier l'accès aux fichiers
var $myMacWorker : 4D.SystemWorker
$myMacWorker:= 4D.SystemWorker.new("chmod x /folder/myfile.sh")
Sommaire
| 4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker crée et renvoie un objet 4D.SystemWorker qui exécutera la commandLine que vous avez passée en paramètre pour lancer un process externe |
| .closeInput() ferme le flux d'entrée (stdin) du process externe |
| .commandLine : Text contient la ligne de commande passée en paramètre à la fonction new() |
| [ |
| .currentDirectory : 4D.Folder](#currentdirectory) contient le répertoire de travail dans lequel le process externe est exécuté |
| .dataType : Text contient le type du contenu du body de la réponse |
| .encoding : Text contient l'encodage du contenu du body de la réponse |
| .errors : Collection contient une collection d'erreurs 4D en cas d'erreur(s) d'exécution, le cas échéant |
| .exitCode : Integer contient le code de sortie renvoyé par le process externe |
| .hideWindow : Boolean peut être utilisée pour cacher la fenêtre de la console DOS ou la fenêtre de l'exécutable lancé (Windows uniquement) |
| .pid : Integer contient l'identifiant unique de process (PID) du process externe au niveau du système |
| .postMessage( message : Text) .postMessage( messageBLOB : Blob) vous permet d'écrire dans le flux d'entrée (stdin) du process externe |
| .response : Text .response : Blob contient la concaténation de toutes les données renvoyées une fois la requête terminée |
| .responseError : Text contient la concaténation de toutes les erreurs renvoyées, une fois la requête terminée |
| .terminate() force le SystemWorker à mettre fin à son exécution |
| .terminated : Boolean contient true si le process externe est terminé |
| .timeout : Integer contient la durée en secondes avant que le process externe soit tué s'il est encore actif |
| .wait( {timeout : Real} ) : 4D.SystemWorker attend la fin de l'exécution du SystemWorker ou le timeout spécifié |
4D.SystemWorker.new()
Historique
| Release | Modifications |
|---|---|
| 19 R4 | Ajout |
4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker
| Paramètres | Type | Description | |
|---|---|---|---|
| commandLine | Text | -> | Ligne de commande à exécuter |
| options | Object | -> | Paramètres du worker |
| result | 4D.SystemWorker | <- | Nouveau System worker asynchrone ou null si le process n'a pas démarré |
Description
La fonction 4D.SystemWorker.new() crée et renvoie un objet 4D.SystemWorker qui exécutera la commandLine que vous avez passée en paramètre pour lancer un process externe.
L'objet system worker retourné peut être utilisé pour envoyer des messages au worker et obtenir les résultats du worker.
Si une erreur se produit pendant la création de l'objet proxy, la fonction renvoie un objet null et une erreur est levée.
Dans le paramètre commandLine , passez le chemin complet du fichier de l'application à exécuter (syntaxe posix), ainsi que les arguments requis, si nécessaire. Si vous ne passez que le nom de l'application, 4D utilisera la variable d'environnement PATH pour localiser l'exécutable.
Attention : Cette fonction ne peut lancer que des applications exécutables ; elle ne peut pas exécuter les instructions qui font partie du shell (interpréteur de commandes). Par exemple, sous Windows, il n'est pas possible d'utiliser cette commande pour exécuter l'instruction dir .
Objet options
Dans le paramètre options, passez un objet qui peut contenir les propriétés suivantes :
| Propriété | Type | Par défaut | Description |
|---|---|---|---|
| onResponse | Formula | undefined | Callback pour les messages du system worker. Ce callback est appelé une fois que la réponse complète est reçue. Elle reçoit deux objets en paramètres (voir ci-dessous) |
| onData | Formula | undefined | Callback pour les données du system worker. Ce callback est appelé chaque fois que le system worker reçoit des données. Elle reçoit deux objets en paramètres (voir ci-dessous) |
| onDataError | Formula | undefined | Callback pour les erreurs du process externe (stderr du processs externe). Elle reçoit deux objets en paramètres (voir ci-dessous) |
| onError | Formula | undefined | Callback pour les erreurs d'exécution, renvoyées par le system worker en cas de conditions d'exécution inhabituelles (erreurs système). Elle reçoit deux objets en paramètres (voir ci-dessous) |
| onTerminate | Formula | undefined | Callback lorsque le process externe est terminé. Elle reçoit deux objets en paramètres (voir ci-dessous) |
| timeout | Number | undefined | Délai en secondes avant que le process soit tué s'il est toujours actif |
| dataType | Text | "text" | Type de contenu du corps de la réponse. Valeurs possibles : "text" (par défaut), "blob". |
| encoding | Text | "UTF-8" | Seulement si dataType="text". Encodage du contenu du corps de la réponse. Pour la liste des valeurs disponibles, consultez la description de la commande CONVERT FROM TEXT |
| variables | Object | Définit des variables d'environnement personnalisées pour le system worker. Syntaxe : variables.key=value, où key est le nom de la variable et value sa valeur. Les valeurs sont converties en chaînes de caractères lorsque cela est possible. La valeur ne peut pas contenir un '='. S'il n'est pas défini, le system worker hérite de l'environnement 4D. | |
| currentDirectory | Folder | Répertoire de travail dans lequel le process est exécuté | |
| hideWindow | Boolean | true | (Windows) Masquer la fenêtre de l'application (si possible) ou la console Windows |
Toutes les fonctions de callback reçoivent deux paramètres objet. Leur contenu dépend du callback :
| Paramètres | Type | 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 | données reçues | données d'erreur |
Voici la séquence des appels de callbacks :
onDataetonDataErrorsont exécutés une ou plusieurs fois- s'il est appelé,
onErrorest exécuté une fois (arrête le traitement du system worker) - si aucune erreur ne s'est produite,
onResponseest exécuté une fois onTerminateest toujours exécuté
Pour que les fonctions de rappel soient appelées lorsque vous n'utilisez pas wait() (appel asynchrone), le process doit être un process worker créé avec CALL WORKER, et NON New process.
Valeur retournée
La fonction renvoie un objet system worker sur lequel vous pouvez appeler les fonctions et les propriétés de la classe SystemWorker.
Exemples sous Windows
- Pour ouvrir le Bloc-notes et ouvrir un document spécifique :
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)
- Exécuter npm install dans la console :
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)
- Pour lancer l'application Microsoft® Word® et ouvrir un document spécifique :
$mydoc:="C:\\Program Files\\Microsoft Office\\Office15\\WINWORD.EXE C:\\Tempo\\output.txt"
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new($mydoc)
- Pour lancer une commande avec le répertoire courant et poster un message :
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()
- Pour permettre à l'utilisateur d'ouvrir un document externe sous Windows :
$docname:=Select document(" ; "*.*" ; "Choisissez le fichier à ouvrir";0)
If(OK=1)
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new("cmd.exe /C start \"\" \""$docname"\"")
End if
Exemples sous macOS
- Modifier un fichier texte (
catest la commande macOS utilisée pour modifier les fichiers). Dans cet exemple, le chemin d'accès complet de la commande est transmis :
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new("/bin/cat /folder/myfile.txt")
$sw.wait() /exécution synchrone
- Pour lancer une application "graphique" indépendante, il est préférable d'utiliser la commande système
open(dans ce cas, le code a le même effet qu'un double-clic sur l'application) :
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new ("open /Applications/Calculator.app")
- Pour obtenir le contenu du dossier "Users" (ls -l est l'équivalent sous macOS de la commande dir sous 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
- Même commande que ci-dessus, mais en utilisant un exemple de classe utilisateur "Params" pour montrer comment gérer les fonctions 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()
Historique
| Release | Modifications |
|---|---|
| 19 R4 | Ajout |
.closeInput()
| Paramètres | Type | Description | |
|---|---|---|---|
| Ne requiert aucun paramètre |
Description
La fonction .closeInput() ferme le flux d'entrée (stdin) du process externe.
Lorsque l'exécutable attend que toutes les données soient reçues par postMessage(), .closeInput() est utile pour indiquer à l'exécutable que l'envoi des données est terminé et qu'il peut continuer.
Exemple
// Créer des données à "gzipper"
var $input;$output : Blob
var $gzip : Text
TEXT TO BLOB("Hello, World !";$input)
$gzip:="\"C:\\Program Files (x86)\\GnuWin32\\bin\\gzip.exe\" "
// Créer un systemworker asynchrone
var $worker : 4D.SystemWorker
$worker:= 4D.SystemWorker.new($gzip;New object("dataType" ; "blob"))
// Envoyez le fichier compressé sur stdin.
$worker.postMessage($input)
// Notez que nous appelons closeInput() pour indiquer que nous avons terminé.
// gzip (et la plupart des programmes qui attendent des données de stdin) attendra d'autres données jusqu'à ce que l'entrée soit explicitement fermée.
$worker.closeInput()
$worker.wait()
$output:=$worker.response
.commandLine
.commandLine : Text
Description
La propriété .commandLine contient la ligne de commande passée en paramètre à la fonction new().
Cette propriété est en lecture seule.
.currentDirectory
.currentDirectory : 4D.Folder
Description
La propriété .currentDirectory contient le répertoire de travail dans lequel le process externe est exécuté.
.dataType
.dataType : Text
Description
La propriété .dataType contient le type du contenu du body de la réponse. Valeurs possibles : "text" ou "blob".
Cette propriété est en lecture seule.
.encoding
.encoding : Text
Description
La propriété .encoding contient l'encodage du contenu du body de la réponse. Cette propriété n'est disponible que si le dataType est "text".
Cette propriété est en lecture seule.
.errors
.errors : Collection
Description
La propriété .errors contient une collection d'erreurs 4D en cas d'erreur(s) d'exécution, le cas échéant.
Chaque élément de la collection est un objet avec les propriétés suivantes :
| Propriété | Type | Description |
|---|---|---|
| [].errorCode | number | Code d'erreur 4D |
| [].message | text | Description de l'erreur 4D |
| [ ].componentSignature | text | Signature du composant interne qui a retourné l'erreur |
Si aucune erreur ne s'est produite, .errors est undefined.
.exitCode
.exitCode : Integer
Description
La propriété .exitCode contient le code de sortie renvoyé par le process externe. Si le process ne s'est pas terminé normalement, exitCode est undefined.
Cette propriété est en lecture seule.
.hideWindow
.hideWindow : Boolean
Description
La propriété .hideWindow peut être utilisée pour cacher la fenêtre de la console DOS ou la fenêtre de l'exécutable lancé (Windows uniquement).
Cette propriété est en lecture-écriture.
.pid
.pid : Integer
Description
La propriété .pid contient l'identifiant unique de process (PID) du process externe au niveau du système.
Cette propriété est en lecture seule.
.postMessage()
.postMessage( message : Text)
.postMessage( messageBLOB : Blob)
| Paramètres | Type | Description | |
|---|---|---|---|
| message | Text | -> | Texte à écrire dans le flux d'entrée (stdin) du process externe |
| messageBLOB | Blob | -> | Octets écrits dans le flux d'entrée |
Description
La fonction .postMessage() vous permet d'écrire dans le flux d'entrée (stdin) du process externe. Dans le paramètre message, passez le texte à écrire dans stdin.
La fonction .postMessage() accepte également une valeur de type Blob dans messageBLOB, de sorte que vous pouvez poster des données binaires dans stdin.
Vous pouvez utiliser la propriété .dataType de l'objet options pour que le corps de réponse renvoie des valeurs Blob.
.response
.response : Text
.response : Blob
Description
La propriété .response contient la concaténation de toutes les données renvoyées une fois la requête terminée, c'est-à-dire le message complet reçu de l'output du process.
Le type de message est défini en fonction de l'attribut dataType.
Cette propriété est en lecture seule.
.responseError
.responseError : Text
Description
La propriété .responseError contient la concaténation de toutes les erreurs renvoyées, une fois la requête terminée.
.terminate()
.terminate()
| Paramètres | Type | Description | |
|---|---|---|---|
| Ne requiert aucun paramètre |
Description
La fonction .terminate() force le SystemWorker à mettre fin à son exécution.
Cette fonction envoie l'instruction de terminer et de redonner le contrôle au script en cours d'exécution.
.terminated
.terminated : Boolean
Description
La propriété .terminated contient true si le process externe est terminé.
Cette propriété est en lecture seule.
.timeout
.timeout : Integer
Description
La propriété .timeout contient la durée en secondes avant que le process externe soit tué s'il est encore actif.
Cette propriété est en lecture seule.
.wait()
Historique
| Release | Modifications |
|---|
|19 R4|Ajouté|
.wait( {timeout : Real} ) : 4D.SystemWorker
| Paramètres | Type | Description | |
|---|---|---|---|
| timeout | Real | -> | Temps d'attente (en secondes) |
| Résultat | 4D.SystemWorker | <- | Objet SystemWorker |
Description
La fonction .wait() attend la fin de l'exécution du SystemWorker ou le timeout spécifié.
Dans timeout, passez une valeur en secondes. Le script SystemWorker attendra le process externe pendant la durée définie dans le paramètre timeout . Si vous omettez le paramètre timeout, l'exécution du script attendra indéfiniment.
En fait, .wait() attend la fin du traitement de la formule onTerminate, sauf si le timeout est atteint. Si le timeout est atteint, le SystemWorker n'est pas tué.
Pendant une exécution .wait(), les fonctions de callback sont exécutées, en particulier les callbacks provenant d'autres événements ou d'autres instances de SystemWorker. Vous pouvez sortir d'un .wait() en appelant terminate() à partir d'une callback.
Cette fonction renvoie l'objet SystemWorker.
Cette fonction n'est pas nécessaire si vous avez créé le
SystemWorkerà partir d'un process worker 4D.