$ZF(-100) (ObjectScript)

オペレーティング・システム・コマンドまたはプログラムを子プロセスとして実行します。この関数は、コールアウト SDK のコンポーネントです。

Synopsis

$ZF(-100,flags,program,args)

引数

引数	説明
flags	1 つ以上のキーワード・フラグを含む引用符付きの文字列。複数のキーワード・フラグは空白で区切られます。キーワード・フラグは、/keyword、/keyword=value、または /keyword+=value という形式を取ることができます。キーワードでは、大文字と小文字は区別されません。flags は、program の実行方法を指定します。
program	子プロセスとして実行されるオペレーティング・システム・コマンドまたはプログラム。引用符付きの文字列として指定されます。パスの指定はフル・パスでもプログラム名でもかまいません。オペレーティング・システムはその規則 (PATH 環境変数など) を使用して、指定されたプログラムを検索します。
args	オプション — program のオプションと引数のコンマ区切りのリスト。null 引数を "" として指定できます。ローカル配列と間接指定の .args または args... 構文を使用して、可変個数の引数を指定できます。

説明

$ZF(-100) は、InterSystems IRIS プロセスによるホスト・オペレーティング・システムの実行可能プログラムまたはコマンドの呼び出しを許可します。例として、ファイルを列挙してコピーする Windows® コマンドの 2 つのサンプルを示します。

set listStatus = $zf(-100,"/SHELL","dir","/q")
set copyStatus = $zf(-100,"/SHELL","copy","myfile.txt","c:\InterSystems")

$ZF(-100) は、program で指定されたプログラムまたはコマンドを、現在のコンソールから生成された子プロセスとして実行します。オペレーティング・システムのシェルを呼び出しても呼び出さなくても、プログラムまたはコマンドを同期または非同期で呼び出すことができます。$ZF(-100) は、$ZF(-1) および $ZF(-2) と類似の機能を提供します。$ZF(-1) または $ZF(-2) (どちらも非推奨の関数) よりも、この関数を使用することをお勧めします。

次の Unix® の例に示すように、ローカル配列と間接指定を使用して、可変個数の args を指定することができます：

  SET args=2
  SET args(1)="-01"
  SET args(2)="myfile.c"
  SET status = $ZF(-100,"/ASYNC", "gcc",.args)

$ZF(-100) は、$ZCHILD を起動プログラムの PID に設定します。

$ZF(-100) は、DO コマンドの引数として実行できます。DO $ZF(-100) は、$ZF(-100) を関数として呼び出す場合と以下の 2 つの点で異なります。

DO は、返される整数ステータス・コードを無視します。
$ZF(-100) に、引数の後置条件式を追加できます。例えば、DO:x $ZF(-100,"", "gcc",.args):y $ZF(-100,"/ASYNC", "gcc",.args):z では、3 つの後置条件を指定しています。これは、x=0 であれば DO コマンドを実行せず、y=0 であれば "gcc" を同期的に実行せず、z=0 であれば "gcc" を非同期的に実行しません。後置条件式によって実行は阻止されますが、引数の評価は阻止されません。

キーワード・フラグ

$ZF(-100) の実行方法は、flags 文字列の値によって異なります。

/ASYNC：program を非同期的に実行します。完了するまで待機しません。既定では、同期的に実行します。
/ASYNC が指定されておらず、かつ /STDIN、/STDOUT、または /STDERR が指定されていない場合、InterSystems IRIS は、これらのファイルに対してオペレーティング・システムの現在の記述子または標準ハンドルを使用しようとします。
/SHELL：シェルを使用して program を実行します。既定では、シェルは使用されません。
/STDIN=filename：入出力リダイレクト入力ファイル。
/STDOUT=filename：入出力リダイレクト標準データ出力ファイル。filename が存在しない場合は、作成されます。filename が存在する場合、/STDOUT=filename は既存のデータを上書きします。/STDOUT+=filename は既存のデータに追加します。
//STDERR=filename：入出力リダイレクト標準エラー出力ファイル。filename が存在しない場合は、作成されます。filename が存在する場合、/STDERR=filename は既存のエラー・ログ・データを上書きします。/STDERR+=filename は既存のエラー・ログ・データに追加します。/STDOUT と /STDERR に同じファイルを指定した場合、両方のタイプのデータがそのファイルに書き込まれます。
/LOGCMD：結果として得られるコマンド行を messages.log に記録します。複雑なコマンドの引数を正しく理解することが難しい場合があります。このような場合、このキーワード・フラグを使用すると、開発者はコマンドに渡された引数が正しく設定されているかどうかを確認することができます (特に引用に関して)。ログ機能では、引用符やその他の区切り文字は追加されません。messages.log エントリは 1000 文字で切り捨てられます。
/NOQUOTE：コマンド、コマンド引数、またはファイル名の自動引用を禁止します。既定で $ZF(-100) は、自動引用、およびほとんどのユーザ指定値に適しているパス内のスペースのエスケープ処理を提供します。必要に応じて、/NOQUOTE を指定することでこの既定をオーバーライドできます。そうすれば、ユーザが適切な引用符を自身で指定できます。"ユーザ指定値の引用" を参照してください。

キーワード・フラグなしで $ZF(-100) を指定するには、この引数に空の文字列を指定します。

  SET status = $ZF(-100,"", "ls", "-l")

入出力リダイレクト

/STDIN=filename、/STDOUT=filename、および /STDERR=filename の入出力リダイレクトでは、UNIX® の規約に従います。UNIX と Windows の両方のシステムで、以下のようになります。

/STDIN=filename ：このファイル名のファイルは、指定した cmd 文字列を実行するプロセスに指定されている stdin ファイル・ハンドルにリンクされます。
/STDOUT=filename ：このファイル名のファイルがまだ存在しない場合は、作成されます。既存のファイルの場合、/STDOUT=filename はファイルをゼロ・サイズに切り捨てます。/STDOUT+=filename は既存のファイルのデータに追加します。このファイルは、指定した cmd 文字列を実行するプロセスに指定されている stdout ハンドルにリンクされます。これにより、生成されたコマンドの stdout 出力が含まれる新しいファイルが作成されます。
/STDERR=filename ：このファイル名のファイルがまだ存在しない場合は、作成されます。既存のファイルの場合、/STDERR=filename はファイルをゼロ・サイズに切り捨てます。/STDERR+=filename は既存のファイルのデータに追加します。このファイルは、指定した cmd 文字列を実行するプロセスに指定されている stderr ハンドルにリンクされます。これにより、生成されたコマンドの stderr 出力が含まれる新しいファイルが作成されます。

/STDIN、/STDOUT、または /STDERR が指定されていない場合は、以下のようになります。

/ASYNC が指定されている場合、未指定のファイルの代わりに NULL デバイスが使用されます。NULL デバイスを参照するハンドルが、指定した cmd 文字列を実行するプロセスに、未指定ファイルのハンドルとして指定されます。
/ASYNC を指定していない場合、$ZF(-100) 関数を実行する InterSystems IRIS ジョブで使用されたハンドルがコピーされ、指定した cmd 文字列を実行するプロセスに未指定ファイルのハンドルとして渡されます。

Note:

Windows システムでは、/ASYNC および /STDIN flags を絶対に省略しないでください。

作成できないファイルや開くことができないファイルを /STDIN、/STDOUT、または /STDERR で指定した場合、そのファイルの代わりに NULL デバイスが使用されます。

/STDOUT=filename および /STDERR=filename (または /STDOUT+=filename および /STDERR+=filename) が同じファイル名を指定した場合、指定されたファイルは、一度だけ開かれる、または作成されます。結果としてファイル・ハンドルが複製され、指定した cmd 文字列を実行するプロセスに stdout ファイル・ハンドルと stderr ファイル・ハンドルの両方として指定されます。$ZF(-100) は、/STDOUT および /STDERR に同じファイルを指定した場合に、一方で +=filename を指定し、もう一方で =filename を指定すると、<ILLEGAL VALUE> エラーを生成します。

ユーザ指定値の引用

既定では、$ZF(-100) は、コマンドと、コマンドの引数に自動引用機能を提供します。これにより、実行可能ファイルがあるディレクトリの名前にスペースが含まれる場合や、コマンド引数で出力対象として指定されたファイルの名前にスペースが含まれる場合、空白スペースが自動的に処理されます。$ZF(-100) は、必要に応じて、区切り二重引用符文字を提供します。この動作を以下の例に示します。

  DO $ZF(-100,"/LOGCMD","c:\sdelete64.exe","-nobanner","c:\dir1\nested directory\deleteme\")

この例では、以下が messages.log に記録されます。$ZF(-100) は、最後の引数を引用符で囲んで、ファイル・パス内のスペースをエスケープしています。

06/14/18-14:25:05:988 (3788) 0 $ZF(-100) cmd=c:\sdelete64.exe -nobanner "c:\dir1\nested directory\deleteme\"
06/14/18-14:25:06:020 (3788) 0 $ZF(-100) ret=0

エスケープ処理する項目が、提供された自動引用で正しく処理されない場合は、/NOQUOTE を使用して処理を上書きできます。

/NOQUOTE フラグを使用すると自動引用が抑制されるため、必要に応じて独自の引用を行う必要があります。指定した値に / 文字または空白が含まれている場合、二重引用符でその値を囲む必要があります。これを以下の例で示しています。

  DO $ZF(-100,"/NOQUOTE /LOGCMD","c:\sdelete64.exe","""-nobanner""","""c:\dir2\""")

この例では、以下が messages.log に記録されます。

06/15/18-09:27:38:619 (3788) 0 $ZF(-100) cmd=c:\sdelete64.exe "-nobanner" "c:\dir2\"
06/15/18-09:27:38:650 (3788) 0 $ZF(-100) ret=0

この動作は、UNIX® システムと Windows システムで異なります。

Windows システムでは、/SHELL が指定されていないと、コマンド行が作成されて渡されます。この場合、いくつかの引数を引用符で囲むことが必要になる場合があります。
どのシステムでも、/SHELL が指定されると、コマンドラインが作成されて渡されます。この場合、いくつかの引数を引用符で囲むことが必要になる場合があります。

コマンドまたはコマンド引数内で見つかった二重引用符はエスケープされます。Windows では、これらの二重引用符は "" のように二重にすることでエスケープされます (前述の例で示しています)。UNIX では、\" のようにしてエスケープされます。

返されるステータス・コード

$ZF(-100) は、以下のステータス・コードを返します。

0：子プロセスが正常に非同期的に起動された場合 (/ASYNC フラグを指定)。program 実行のステータスが不明です。
-1：子プロセスをフォークできない場合。
同期的に起動された場合は整数 (/ASYNC フラグを指定しない)。この終了ステータス・コード整数値は、ホスト・オペレーティング・システムで呼び出されたアプリケーションによって決定されます。通常は正の整数ですが、負の整数を返すアプリケーションもあります。例えば、ほとんどの Windows コマンドの構文エラーに対して、$ZF(-100) は 1 を返します。

/SHELL 引数が指定されている $ZF(-100) は、既定のオペレーティング・システム・シェルを起動します。詳細は、"コールアウト SDK の使用法" の “$ZF(-100) を使用したプログラムまたはシステム・コマンドの実行” を参照してください。

program で指定されたパス名にスペース文字が含まれる場合、パス名の処理はプラットフォームによって異なります。Windows および UNIX® の場合はパス名にスペース文字を使用することができますが、スペースを含むパス名は、追加の二重引用符 () で全体を囲む必要があります。これは、Windows の cmd /c 文に従っています。詳細は、Windows のコマンド・プロンプトで cmd /? を指定してください。

%Library.FileOpens in a new tab クラスの NormalizeFilenameWithSpaces()Opens in a new tab メソッドを使用すると、パス名内のスペースがホスト・プラットフォームに合わせて処理されるようにできます。

$ZF(-100) は、%System_Callout:U 特権を必要とします。詳細は、"コールアウト SDK の使用法" の “%System_Callout:USE 特権の追加” を参照してください。

$ZF(-100) がプロセスを生成できない場合、<FUNCTION> エラーを生成します。

エラー処理

$ZF(-100) は、以下の場合、<NOTOPEN> エラーを生成します。

/STDIN=filename、/STDOUT=filename、または /STDERR=filename を開けない。
指定されたプログラムを起動できない。

エラーが SYSLOG に記録されます。オペレーティング・システムのエラー番号とメッセージは、%SYSTEM.Process.OSError()Opens in a new tab メソッドから取得できます。

監査

$ZF(-100) を呼び出すたびに、OS コマンド監査レコードが監査ログに追加されます。このレコードには、以下のような情報が含まれます。

Command: /Users/myname/IRIS/jlc/bin/clmanager 4002
Flags: /ASYNC/SHELL

$ZF(-100)、$ZF(-1)、および $ZF(-2)

これら 3 つの関数はほとんどの点で同一です。これらは以下の点で異なります。

$ZF(-100) は、同期的または非同期的に実行できます。オペレーティング・システム・シェルを使用して実行することも、シェルを使用せずに実行することもできます。常に $ZCHILD を設定します。$ZF(-1) と $ZF(-2) はどちらも、引数の指定なしで、オペレーティング・システム・シェルを起動します。$ZF(-100) では、オペレーティング・システム・シェルを起動するために program 引数 (および /SHELL フラグ) が必要です。
$ZF(-100) は、すべての目的に適した関数であり、$ZF(-1) と $ZF(-2) の両方の代わりに使用できます。
$ZF(-1) (非推奨) は OS シェルを使用して実行されます。この関数は同期的に実行されます。作成された子プロセスの完了を待つ間、現在のプロセスの実行を中断します。作成されたプロセスからステータス情報を受信し、作成されたプロセスの完了時に、これを終了ステータス・コード (整数値) として返します。$ZF(-1) は、$ZCHILD を設定しません。
$ZF(-2) (非推奨) は OS シェルを使用して実行されます。この関数は非同期的に実行されます。現在のプロセスの実行を中断しません。子プロセスの生成において、直ちにステータスの値を返します。作成された子プロセスの完了を待たないので、そのプロセスからのステータス情報は受信できません。$ZF(-2) は、5 番目の引数が True の場合、$ZCHILD を設定します。