$ZF(-1)

Synopsis

$ZF(-1,program)

説明

$ZF(-1) は、Caché プロセスによるホスト・オペレーティング・システムのプログラムやコマンドの呼び出しを許可します。program で指定されたプログラムまたはコマンドを、現在のコンソールから生成された子プロセスとして実行します。この関数は同期的に実行されます。プロセスが返されるのを待機します。$ZF(-1) は子プロセスの終了状態を返します。

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

• 子プロセスの実行に成功した場合は 0 を返します。

• オペレーティング・システム・シェルによって発行された終了ステータス・エラー・コードに基づいて、正の整数を返します。この終了ステータス・コード整数値は、ホスト・オペレーティング・システムによって決定されます。例えば、ほとんどの Windows コマンドの構文エラーに対して、$ZF(-1) は 1 を返します。

• 子プロセスがフォークできない場合は -1 を返します。

$ZF(-1) は、生成された子プロセスからの応答を待機するので、子プロセスの実行中は Cache を正常にシャットダウンすることができません。

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

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

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

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

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

ターミナルで、実行するオペレーティング・システム・コマンドの最初の文字に感嘆符 (!) またはドル記号 ($) を使用して、$ZF(-1) と同様の操作を実行できます。! または $ のコマンド行接頭語によりオペレーティング・システム・コマンドが実行され、呼び出されたプロセスからの結果が返され、ターミナルにそれらの結果が表示されます。$ZF(-1) は、オペレーティング・システム・コマンドの結果を返さずに、オペレーティング・システム・コマンドの実行後、呼び出されたプロセスの終了ステータス・コードを返します。詳細は、"コールアウト・ゲートウェイの使用法" の “オペレーティング・システム・コマンドの発行” を参照してください。

監査

$ZF(-1) 呼び出しごとに、OS コマンド監査レコードが監査ログに追加されます。このレコードには、次のような情報が含まれます。

Execute O/S command Directory: c:\182u5\mgr\ 
Command: ls -lt 4002

例

以下の Windows の例は、ユーザが記述したプログラムを実行します。この場合、.txt ファイルのコンテンツが表示されます。また、$ZF(-1) のパス名の処理に NormalizeFilenameWithSpaces() を使用しています。スペースを含むパス名がホスト・プラットフォームに合わせて処理されます。スペースを含まないパス名は、変更されずに渡されます。$ZF(-1) は、指定されたファイルにアクセスできた場合は、Windows シェルの終了状態 0 を返します。アクセスに失敗した場合は、1 を返します。

   SET fname="C:\My Test.txt"
   WRITE fname,!
   SET x=##class(%Library.File).NormalizeFilenameWithSpaces(fname)
   WRITE x,!
   WRITE $ZF(-1,x)

以下の Windows の例では、Windows のオペレーティング・システム SOL コマンドを呼び出します。SOL は、Windows オペレーティング・システムで提供されているソリティア・ゲームを表示するウィンドウを開きます。ソリティアのインタラクティブ・ウィンドウを閉じると、$ZF(-1) は Windows シェルの終了状態 0 を返します。これは、処理が成功したことを示します。

   SET x=$ZF(-1,"SOL")
   WRITE x

以下の Windows の例では、存在しない Windows のオペレーティング・システム・コマンドを呼び出します。$ZF(-1) は、Windows シェルの終了ステータス 1 を返します。これは、構文エラーを示します。

   WRITE $ZF(-1,"SOX")

以下の Windows の例では、Windows のオペレーティング・システム・コマンドを呼び出して、存在しないネットワーク名を指定します。$ZF(-1) は、Windows シェルの終了エラー 2 を返します。

   WRITE $ZF(-1,"NET USE :k \\bogusname")

関連項目

• $ZF(-2) 関数

• $ZF(-100) 関数

• "コールアウト・ゲートウェイの使用法" の "オペレーティング・システム・コマンドの発行"