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    contient le répertoire de travail dans lequel le process externe est exécuté
.dataType : Text    contient le type du contenu du corps de la réponse
.encoding : Text    contient l'encodage du contenu du corps 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é pour cacher la fenêtre de la console DOS ou la fenêtre de l'exécutable lancé (Windows seulement)
.pid : Integer    contient l'identifiant unique du process externe au niveau du système
.postMessage( message : Text) .postMessage( messageBLOB : Blob)    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 demande 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 vrai si le process externe est terminé
.timeout : Integer    contient la durée en secondes avant que le process externe ne soit tué s'il est toujours en vie
.wait( {timeout : Real} ) : 4D.SystemWorker    attend la fin de l'exécution du SystemWorker ou du 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, voir 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 :

1. onData et onDataError sont exécutés une ou plusieurs fois
2. s'il est appelé, onError est exécuté une fois (arrête le traitement du system worker)
3. si aucune erreur ne s'est produite, onResponse est exécuté une fois
4. onTerminate est toujours exécuté

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

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

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

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

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

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

1. Modifier un fichier texte (cat est 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

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

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

4. 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 quelques 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 system worker asynchrone
var $worker : 4D.SystemWorker
$worker:= 4D.SystemWorker.new($gzip;New object("dataType" ; "blob"))

// Envoyer 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 attendant des données de stdin) attendra plus de 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 corps 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 corps de la réponse. Cette propriété est uniquement disponible 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é pour cacher la fenêtre de la console DOS ou la fenêtre de l'exécutable lancé (Windows seulement).

Cette propriété est en lecture-écriture.

.pid

.pid : Integer

Description

La propriété .pid contient l'identifiant unique 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() 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 demande terminée, c'est-à-dire le message complet reçu à partir de l'output du process.

Le type du message est défini selon 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 vrai 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 ne soit tué s'il est toujours en vie.

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 du 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'un 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.