SystemWorker
System workers allow the QodlyScript code to call any external process on the server machine. System workers are called asynchronously. By using callbacks, Qodly makes it possible to communicate both ways.
The SystemWorker class is available from the 4D class store.
Summary
4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker creates and returns a 4D.SystemWorker object that will execute the commandLine you passed as parameter to launch an external process |
| .closeInput() closes the input stream (stdin) of the external process |
.commandLine : string contains the command line passed as parameter to the new() function |
| .currentDirectory : 4D.Folder contains the working directory in which the external process is executed |
| .dataType : string contains the type of the response body content |
| .encoding : string contains the encoding of the response body content |
| .errors : collection contains a collection of errors in case of execution error(s) if any |
| .exitCode : integer contains the exit code returned by the external process |
| .pid : integer contains the process unique identifier of the external process at the system level |
| .postMessage( message : string ) .postMessage( messageBLOB : blob ) allows you to write on the input stream (stdin) of the external process |
| .response : string .response : blob contains the concatenation of all data returned once the request is terminated |
| .responseError : string contains the concatenation of all the errors returned, once the request is terminated |
.terminate() forces the SystemWorker to terminate its execution |
| .terminated : boolean contains true if the external process is terminated |
| .timeout : integer contains the duration in seconds before the external process will be killed if it is still alive |
.wait( {timeout : number} ) : 4D.SystemWorker waits until the end of the SystemWorker execution or the specified timeout |
4D.SystemWorker.new()
4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker
| Parameter | Type | Description | |
|---|---|---|---|
| commandLine | Text | → | Command line to execute |
| options | Object | → | Worker parameters |
| result | 4D.SystemWorker | ← | New asynchronous System worker or null if process not started |
Description
The 4D.SystemWorker.new() function creates and returns a 4D.SystemWorker object that will execute the commandLine you passed as parameter to launch an external process.
The returned system worker object can be used to post messages to the worker and get the worker output.
If an error occurs during the creation of the proxy object, the function returns a null object and an error is thrown.
In the commandLine parameter, pass the full path of the application's file to be executed (posix syntax), as well as any required arguments, if necessary. If you pass only the application name, 4D will use the PATH environment variable to locate the executable.
Warning: This function can only launch executable applications; it cannot execute instructions that are part of the shell (command interpreter).
options Object
In the options parameter, pass an object that can contain the following properties:
| Property | Type | Default | Description |
|---|---|---|---|
| onResponse | formula | undefined | Callback for system worker messages. This callback is called once the complete response is received. It receives two objects as parameters (see below) |
| onData | formula | undefined | Callback for system worker data. This callback is called each time the system worker receives data. It receives two objects as parameters (see below) |
| onDataError | formula | undefined | Callback for the external process errors (stderr of the external process). It receives two objects as parameters (see below) |
| onError | formula | undefined | Callback for execution errors, returned by the system worker in case of unusual runtime conditions (system errors). It receives two objects as parameters (see below) |
| onTerminate | formula | undefined | Callback when the external process is terminated. It receives two objects as parameters (see below) |
| timeout | number | undefined | Time in seconds before the process is killed if it is still alive |
| dataType | string | "text" | Type of the response body content. Possible values: "text" (default), "blob". |
| encoding | string | "UTF-8" | Only if dataType = "text". Encoding of the response body content. For the list of available values, see the convertFromString command |
| variables | object | Sets custom environment variables for the system worker. Syntax: variables.key = value, where key is the variable name and value its value. Values are converted into strings when possible. The value cannot contain a ' = '. If not defined, the system worker inherits from the Qodly environment. | |
| currentDirectory | folder | Working directory in which the process is executed |
All callback functions receive two object parameters. Their contents depend on the callback:
| Parameter | Type | onResponse | onData | onDataError | onError | onTerminate |
|---|---|---|---|---|---|---|
| $param1 | Object | SystemWorker | SystemWorker | SystemWorker | SystemWorker | SystemWorker |
| $param2.type | string | "response" | "data" | "error" | "error" | "termination" |
| $param2.data | string or blob | received data | error data |
Here is the sequence of callback calls:
onDataandonDataErrorare executed one or several times- if called,
onErroris executed once (stops the system worker processing) - if no error occured,
onResponseis executed once onTerminateis always executed
Returned value
The function returns a system worker object on which you can call functions and properties of the SystemWorker class.
.closeInput()
.closeInput()
| Parameter | Type | Description | |
|---|---|---|---|
| Does not require any parameters |
Description
The .closeInput() function closes the input stream (stdin) of the external process.
When the executable waits for all data to be received through postMessage(), .closeInput() is useful to indicate to the executable that data sending is finished and that it can proceed.
.commandLine
.commandLine : string
Description
The .commandLine property contains the command line passed as parameter to the new() function.
This property is read-only.
.currentDirectory
.currentDirectory : 4D.Folder
Description
The .currentDirectory property contains the working directory in which the external process is executed.
.dataType
.dataType : string
Description
The .dataType property contains the type of the response body content. Possible values : "text" or "blob".
This property is read-only.
.encoding
.encoding : string
Description
The .encoding property contains the encoding of the response body content. This property is only available if the dataType is "text".
This property is read-only.
.errors
.errors : collection
Description
The .errors property contains a collection of errors in case of execution error(s) if any.
Each element of the collection is an object with the following properties:
| Property | Type | Description |
|---|---|---|
| [].errorCode | number | Qodly error code |
| [].message | text | Description of the Qodly error |
| [ ].componentSignature | text | Signature of the internal component which returned the error |
If no error occured, .errors is undefined.
.exitCode
.exitCode : integer
Description
The .exitCode property contains the exit code returned by the external process. If the process did not terminate normaly, exitCode is undefined.
This property is read-only.
.pid
.pid : integer
Description
The .pid property contains the process unique identifier of the external process at the system level.
This property is read-only.
.postMessage()
.postMessage( message : string )
.postMessage( messageBLOB : blob )
| Parameter | Type | Description | |
|---|---|---|---|
| message | Text | → | Text to write on the input stream (stdin) of the external process |
| messageBLOB | Blob | → | Bytes write on the input stream |
Description
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.
You can use the .dataType property of the options object to make response body return Blob values.
.response
.response : string
.response : blob
Description
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.
The type of the message is defined according to the dataType attribute.
This property is read-only.
.responseError
.responseError : string
Description
The .responseError property contains the concatenation of all the errors returned, once the request is terminated.
.terminate()
.terminate()
| Parameter | Type | Description | |
|---|---|---|---|
| Does not require any parameters |
Description
The .terminate() function forces the SystemWorker to terminate its execution.
This function sends the instruction to terminate and give control back to the executing script.
.terminated
.terminated : boolean
Description
The .terminated property contains true if the external process is terminated.
This property is read-only.
.timeout
.timeout : integer
Description
The .timeout property contains the duration in seconds before the external process will be killed if it is still alive.
This property is read-only.
.wait()
.wait( {timeout : number} ) : 4D.SystemWorker
| Parameter | Type | Description | |
|---|---|---|---|
| timeout | number | → | Waiting time (in seconds) |
| Result | 4D.SystemWorker | ← | SystemWorker object |
Description
The .wait() function waits until the end of the SystemWorker execution or the specified timeout.
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. If timeout is reached, the SystemWorker is not killed.
During a .wait() execution, callback functions are executed, especially callbacks from other events or from other SystemWorker instances. You can exit from a .wait() by calling terminate() from a callback.
This function returns the SystemWorker object.
This function is not necessary if you created the
SystemWorkerfrom a Qodly worker process.