SystemWorker
システムワーカーを使うことで、4Dコードは同じマシン上で任意の外部プロセス (シェルコマンド、PHPなど ) を呼び出すことができます。 システムワーカーは非同期で呼び出されます。 コールバックを使用することで、4D は双方向の通信を可能にします。
SystemWorker クラスは、4D クラスストアにて提供されています。
例題
// ipconfig 情報へのアクセスを取得する Windows での例
var $myWinWorker : 4D.SystemWorker
var $ipConfig : Text
$myWinWorker:= 4D.SystemWorker.new("ipconfig")
$ipConfig:=$myWinWorker.wait(1).response //timeout 1 second
// ファイルのパーミッションを変更する macOS での例
// chmod はパーミッションを変更するための macOS コマンドです
var $myMacWorker : 4D.SystemWorker
$myMacWorker:= 4D.SystemWorker.new("chmod +x /folder/myfile.sh")
概要
| 4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker 外部プロセスを開始するために commandLine に渡したコマンドラインを実行する 4D.SystemWorker オブジェクトを作成し、返します |
| .closeInput() 外部プロセスの入力ストリーム (stdin) を閉じます |
.commandLine : Textnew() 関数に引数として渡したコマンドライン |
| .currentDirectory : 4D.Folder 外部プロセスが実行される作業ディレクトリ |
| .dataType : Text レスポンス本文のデータ型 |
| .encoding : Text レスポンス本文のエンコーディング |
| .errors : Collection 実行エラーの場合、4Dエラー (あれば) のコレクション |
| .exitCode : Integer 外部プロセスから返される終了コード |
| .hideWindow : Boolean 実行ファイルや DOSコンソールのウィンドウを隠すのに使用できます (Windows のみ) |
| .pid : Integer 外部プロセスの、システムレベルでの一意的な識別子 |
| .postMessage( message : Text) .postMessage( messageBLOB : Blob) 外部プロセスの入力ストリーム (stdin) への書き込みをおこないます |
| .response : Text .response : Blob リクエストが終了した時点で、返された全データの結合 |
| .responseError : Text リクエストが終了した時点で、返された全エラーの結合 |
.terminate()SystemWorker の実行を強制終了します |
| .terminated : Boolean 外部プロセスが終了された場合に true |
| .timeout : Integer 外部プロセスが生きている場合、キルされるまでの秒数 |
| .wait( {timeout : Real} ) : 4D.SystemWorker waits until the end of the SystemWorker execution or the specified timeout |
4D.SystemWorker.new()
履歴
| リリース | 内容 |
|---|---|
| 19 R4 | 追加 |
4D.SystemWorker.new ( commandLine : Text { ; options : Object } ) : 4D.SystemWorker
| 引数 | 型 | 説明 | |
|---|---|---|---|
| commandLine | Text | -> | 実行するコマンドライン |
| options | Object | -> | ワーカーパラメーター |
| 戻り値 | 4D.SystemWorker | <- | 非同期の新規システムワーカー (プロセスが開始されなかった場合は null) |
説明
4D.SystemWorker.new() 関数は、外部プロセスを開始するために commandLine に渡したコマンドラインを実行する 4D.SystemWorker オブジェクトを作成し、返します。
返されたシステムワーカーオブジェクトは、ワーカーにメッセージを送信したり、ワーカーの結果を取得するために使用できます。
プロキシオブジェクトの生成中に問題があった場合、この関数は null オブジェクトを返し、エラーが生成されます。
commandLine には、実行するアプリケーションのファイルのフルパス (POSIX シンタックス)、および必要に応じて追加の引数を渡します。 アプリケーション名だけを渡すと、4Dは 実行ファイルを探すために PATH 環境変数を使用します。
警告: この関数は、実行可能なアプリケーションを起動するだけで、シェル (コマンドインタープリター) の一部である命令を実行することはできません。 たとえば Windows で、このコマンドを使用して dir 命令を実行することはできません。
options オブジェクト
options に渡すオブジェクトは、次のプロパティを持つことができます:
| プロパティ | 型 | デフォルト | 説明 |
|---|---|---|---|
| onResponse | Formula | undefined | システムワーカーメッセージ用のコールバック。 完全なレスポンスを受け取り次第、このコールバックが呼び出されます。 コールバックは 2つのオブジェクトを引数として受け取ります (後述参照) |
| onData | Formula | undefined | システムワーカーデータ用のコールバック。 システムワーカーがデータを受け取る度に、このコールバックが呼び出されます。 コールバックは 2つのオブジェクトを引数として受け取ります (後述参照) |
| onDataError | Formula | undefined | 外部プロセスエラー用のコールバック (外部プロセスの stderr)。 コールバックは 2つのオブジェクトを引数として受け取ります (後述参照) |
| onError | Formula | undefined | 実行エラー用のコールバック。異常なランタイム条件 (システムエラー) の場合にシステムワーカーによって返されます。 コールバックは 2つのオブジェクトを引数として受け取ります (後述参照) |
| onTerminate | Formula | undefined | 外部プロセスが終了されたときのコールバック。 コールバックは 2つのオブジェクトを引数として受け取ります (後述参照) |
| timeout | Number | undefined | プロセスが生きている場合、キルされるまでの秒数。 |
| dataType | Text | "text" | レスポンス本文のデータ型。 可能な値: "text" (デフォルト), "blob"。 |
| encoding | Text | "UTF-8" | dataType="text" の場合のみ。 レスポンス本文のエンコーディング。 利用可能な値については、CONVERT FROM TEXT コマンドの説明を参照ください。 |
| variables | Object | システムワーカー用のカスタム環境変数を設定します。 シンタックス: variables.key=value (key は変数名、value はその値)。 値は、可能な限り文字列に変換されます。 値に '=' を含めることはできません。 定義されていない場合、システムワーカーは 4D環境を継承します。 | |
| currentDirectory | Folder | プロセスが実行される作業ディレクトリ | |
| hideWindow | Boolean | true | (Windows) アプリケーションウィンドウを隠す (可能な場合)、または Windowsコンソールを隠す |
すべてのコールバック関数は、2つのオブジェクト引数を受け取ります。 その内容は、コールバックに依存します:
| 引数 | 型 | onResponse | onData | onDataError | onError | onTerminate |
|---|---|---|---|---|---|---|
| $param1 | Object | SystemWorker | SystemWorker | SystemWorker | SystemWorker | SystemWorker |
| $param2.type | Text | "response" | "data" | "error" | "error" | "termination" |
| $param2.data | Text または Blob | 取得データ | エラーデータ |
以下は、コールバック呼び出しの流れです:
onDataおよびonDataErrorは 1回または複数回実行されます。- 呼ばれた場合、
onErrorは 1回実行されます (システムワーカーの処理を停止します)。 - エラーが発生しなかった場合、
onResponseが 1回実行されます。 onTerminateは常に実行されます。
wait() を使用しない場合 (非同期呼び出し) にコールバック関数が呼び出されるためには、そのプロセスは CALL WORKER で作成された ワーカー である必要があります (New process は使えません)。
戻り値
この関数はシステムワーカーオブジェクトを返します。このオブジェクトに対して、SystemWorker クラスの関数やプロパティを呼び出すことができます。
Windows の例
- 特定のドキュメントをメモ帳で開きます:
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)
- コンソールで npm install を実行します:
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)
- 特定のドキュメントを Microsoft® Word® アプリケーションで開きます:
$mydoc:="C:\\Program Files\\Microsoft Office\\Office15\\WINWORD.EXE C:\\Tempo\\output.txt"
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new($mydoc)
- カレントディレクトリでコマンドを実行し、メッセージそ送信します:
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()
- ユーザーが Windows上で外部ドキュメントを開くのを許可します:
$docname:=Select document("";"*.*";"開くファイルを選択してください";0)
If(OK=1)
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new("cmd.exe /C start \"\" \""+$docname+"\"")
End if
macOS の例
- テキストファイルを編集します (
catはファイルを編集するための macOS コマンドです)。 この例題では、コマンドのフルアクセスパスを渡しています:
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new("/bin/cat /folder/myfile.txt")
$sw.wait() //同期的実行
- 独立した "グラフィック" アプリケーションを起動するには、
openシステムコマンドの使用が推奨されます (これは、アプリケーションをダブルクリックするのと同じ効果を持ちます)。
var $sw : 4D.SystemWorker
$sw:=4D.SystemWorker.new ("open /Applications/Calculator.app")
- "Users" フォルダーの中身を取得します (ls -l は、DOS の dir に相当する macOS のコマンドです)。
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
- 上記と同じコマンドで、"Params" ユーザークラスを使ったコールバック関数の処理方法を示しています:
var $systemworker : 4D.SystemWorker
$systemworker:=4D.SystemWorker.new("/bin/ls -l /Users ";cs.Params.new())
// "Params" クラス
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()
履歴
| リリース | 内容 |
|---|---|
| 19 R4 | 追加 |
.closeInput()
| 引数 | 型 | 説明 | |
|---|---|---|---|
| 引数を必要としません |
説明
.closeInput() 関数は、外部プロセスの入力ストリーム (stdin) を閉じます。
.closeInput() は、postMessage() を介した全データの受信を待機している実行ファイルに、データ送信が終了したことを知らせるのに便利です。
例題
// gzip するデータを作成します
var $input;$output : Blob
var $gzip : Text
TEXT TO BLOB("Hello, World!";$input)
$gzip:="\"C:\\Program Files (x86)\\GnuWin32\\bin\\gzip.exe\" "
// 非同期のシステムワーカーを作成します
var $worker : 4D.SystemWorker
$worker:= 4D.SystemWorker.new($gzip;New object("dataType";"blob"))
// stdin に圧縮ファイルを送信します
$worker.postMessage($input)
// 終了したことを明確にするため closeInput() を呼び出します
// gzip (および stdin からのデータを待機する多数のプログラム) は入力ストリームが明示的に閉じられるまで待機します
$worker.closeInput()
$worker.wait()
$output:=$worker.response
.commandLine
.commandLine : Text
説明
.commandLine プロパティは、new() 関数に引数として渡したコマンドラインを格納します。
このプロパティは 読み取り専用 です。
.currentDirectory
.currentDirectory : 4D.Folder
説明
.currentDirectory プロパティは、外部プロセスが実行される作業ディレクトリを格納します。
.dataType
.dataType : Text
説明
.dataType プロパティは、レスポンス本文のデータ型を格納します。 とりうる値: "text" または "blob"。
このプロパティは 読み取り専用 です。
.encoding
.encoding : Text
説明
.encoding プロパティは、レスポンス本文のエンコーディングを格納します。 このプロパティは dataType が "text" のときにのみ利用できます。
このプロパティは 読み取り専用 です。
.errors
.errors : Collection
説明
.errors プロパティは、実行エラーの場合、4Dエラー (あれば) のコレクションを格納します。
コレクションの各要素は、以下のプロパティを持つオブジェクトです:
| プロパティ | 型 | 説明 |
|---|---|---|
| [].errorCode | number | 4Dエラーコード |
| [].message | テキスト | 4Dエラーの詳細 |
| [ ].componentSignature | テキスト | エラーを返した内部コンポーネントの署名 |
エラーが発生しなかった場合、.errors は undefined です。
.exitCode
.exitCode : Integer
説明
.exitCode プロパティは、外部プロセスから返される終了コードを格納します。 プロセスが正常に終了しなかった場合、exitCode は undefined です。
このプロパティは 読み取り専用 です。
.hideWindow
.hideWindow : Boolean
説明
.hideWindow プロパティは、実行ファイルや DOSコンソールのウィンドウを隠すのに使用できます (Windows のみ)。
読み書き可能 プロパティです。
.pid
.pid : Integer
説明
.pid プロパティは、外部プロセスの、システムレベルでの一意的な識別子を格納します。
このプロパティは 読み取り専用 です。
.postMessage()
.postMessage( message : Text)
.postMessage( messageBLOB : Blob)
| 引数 | 型 | 説明 | |
|---|---|---|---|
| message | Text | -> | 外部プロセスの入力ストリーム (stdin) に書き込むテキスト |
| messageBLOB | BLOB | -> | 入力ストリームに書き込むバイト |
説明
.postMessage() 関数は、外部プロセスの入力ストリーム (stdin) への書き込みをおこないます。 message には stdin に書き込むテキストを渡します。
.postMessage() 関数は、stdin に渡す BLOB型の messageBLOB 引数も受け取るため、バイナリデータを送信することもできます。
options オブジェクト の .dataType プロパティを使って、レスポンス本文が BLOB を返すようにできます。
.response
.response : Text
.response : Blob
説明
.response プロパティは、リクエストが終了した時点で、返された全データの結合を格納します (つまり、プロセスの出力から取得された全メッセージ)。
メッセージのデータ型は dataType 属性によって定義されています。
このプロパティは 読み取り専用 です。
.responseError
.responseError : Text
説明
.responseError プロパティは、リクエストが終了した時点で、返された全エラーの結合を格納します。
.terminate()
.terminate()
| 引数 | 型 | 説明 | |
|---|---|---|---|
| 引数を必要としません |
説明
.terminate() 関数は、SystemWorker の実行を強制終了します。
この関数は、システムワーカーを終了して実行中のスクリプトに制御を戻す命令を送ります。
.terminated
.terminated : Boolean
説明
.terminated プロパティは、外部プロセスが終了された場合に true を格納します。
このプロパティは 読み取り専用 です。
.timeout
.timeout : Integer
説明
.timeout プロパティは、外部プロセスが生きている場合、キルされるまでの秒数を格納します。
このプロパティは 読み取り専用 です。
.wait()
履歴
| リリース | 内容 |
|---|
|19 R4|追加|
.wait( {timeout : Real} ) : 4D.SystemWorker
| 引数 | 型 | 説明 | |
|---|---|---|---|
| timeout | Real | -> | 待機時間 (秒単位) |
| 戻り値 | 4D.SystemWorker | <- | SystemWorker オブジェクト |
説明
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. タイムアウトに達した場合、SystemWorker はキルされません。
During a .wait() execution, callback functions are executed, especially callbacks from other events or from other SystemWorker instances. コールバックから terminate() を呼び出すことで、.wait() を終了することができます。
この関数は、SystemWorker オブジェクトを返します。
SystemWorkerを 4D のワーカープロセスから作成した場合、この関数は必要ありません。