$ZF(-100)

オペレーティング・システム・コマンドまたはプログラムを子プロセスとして実行します。

Synopsis

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

パラメータ

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

説明

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

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

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

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

キーワード・フラグ

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

/ASYNC：program を非同期的に実行します。完了するまで待機しません。既定では、同期的に実行します。
/ASYNC が指定されておらず、かつ /STDIN、/STDOUT、または /STDERR が指定されていない場合、Caché は、これらのファイルに対してオペレーティング・システムの現在の記述子または標準ハンドルを使用しようとします。
/SHELL：シェルを使用して program を実行します。既定では、シェルは使用されません。
/STDIN=filename：入出力リダイレクト入力ファイル。
/STDOUT=filename：入出力リダイレクト標準データ出力ファイル。filename が存在しない場合は、作成されます。filename が存在する場合、/STDOUT=filename は既存のデータを上書きします。/STDOUT+=filename は既存のデータに追加します。
//STDERR=filename：入出力リダイレクト標準エラー出力ファイル。filename が存在しない場合は、作成されます。filename が存在する場合、/STDERR=filename は既存のエラー・ログ・データを上書きします。/STDERR+=filename は既存のエラー・ログ・データに追加します。/STDOUT と /STDERR に同じファイルを指定した場合、両方のタイプのデータがそのファイルに書き込まれます。
/LOGCMD：結果として得られるコマンドラインを cconsole.log に記録します。複雑なコマンドの引数を正しく理解することが難しい場合があります。このような場合、このキーワード・フラグを使用すると、開発者はコマンドに渡された引数が正しく設定されているかどうかを確認することができます (特に引用に関して)。ログ機能では、引用符やその他の区切り文字は追加されません。cconsole.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 ハンドルにリンクされます。これにより、spawned コマンドの stdout 出力を含む新しいファイルが作成されます。
/STDERR=filename：このファイル名を持つファイルがまだ存在しない場合は、作成されます。既存のファイルの場合、/STDERR=filename はそのファイルをゼロ・サイズに切り捨てます。/STDERR+=filename は、既存のファイル・データに追加します。このファイルは、指定された cmd 文字列を実行するプロセスに付与された stderr ハンドルにリンクされます。これにより、spawned コマンドの stderr 出力を含む新しいファイルが作成されます。

/STDIN、/STDOUT、または /STDERR が指定されていない場合：

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

Note:

Windows システムでは、/ASYNC と /STDIN flags は両方とも省略しないでください。

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

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

ユーザ指定値の引用

既定では、$ZF(-100) は自動引用を提供します。/NOQUOTE フラグは、自動引用を禁止します。/NOQUOTE が指定されていない場合は、必要に応じて二重引用符区切り文字が指定されます。この動作を、以下の例に示します。

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

これにより、以下が cconsole.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 を指定すると、自動引用は抑制されます。この場合必要に応じて、独自の引用処理を実行する必要があります。指定された値に / 文字または空白が含まれている場合は、値を二重引用符で囲む必要があります。以下に例を示します。

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

これにより、以下が cconsole.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

filename に / 文字または空白が含まれている場合は、次の例に示すように、二重引用符で filename を囲む必要があります。

  SET status = $ZF(-100,"/stdout=""/home/user/myfile.txt"" /async", "ls", "-l")

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

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

コマンドまたはコマンド引数内で検出された二重引用符は、エスケープされます。Windows では、これらの二重引用符は "" のように二重にすることでエスケープされます (上の例を参照)。UNIX では、\" のようにしてエスケープされます。

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

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

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

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

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 特権を必要とします。詳細は、"コールアウト・ゲートウェイの使用法" の “%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 を設定します。