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](#currentdirectory) 外部プロセスが実行される作業ディレクトリ |
| .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.SystemWorkerSystemWorker の実行終了まで、または 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 | text | 4Dエラーの詳細 |
| [ ].componentSignature | text | エラーを返した内部コンポーネントの署名 |
エラーが発生しなかった場合、.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 オブジェクト |
説明
.wait() 関数は、SystemWorker の実行終了まで、または timeout で指定した時間が経過するまで待機します。
timeout には、秒単位の値を渡します。 SystemWorker スクリプトは、timeout に指定された時間だけ、外部プロセスを待ちます。 timeout を省略した場合、スクリプトの実行は無期限に待機します。
実際には、.wait() はタイムアウトに達した場合を除き、onTerminate フォーミュラのプロセス終了まで待ちます。 タイムアウトに達した場合、SystemWorker はキルされません。
.wait() の実行中、コールバック関数、とくに他のイベントや他の SystemWorker インスタンスからのコールバックは実行されます。 コールバックから terminate() を呼び出すことで、.wait() を終了することができます。
この関数は、SystemWorker オブジェクトを返します。
SystemWorkerを 4D のワーカープロセスから作成した場合、この関数は必要ありません。