$ZF(-100) を使用したプログラムまたはシステム・コマンドの実行

はじめに

$ZF(-100) は、コマンド行インタフェースの機能と同様の機能を提供します。これを使用すると、ホスト・オペレーティング・システムの実行可能プログラムまたはコマンドを呼び出すことができます。この関数の構文は次のとおりです。

    sc = $ZF(-100, keywords, command, arguments )

最初の引数はリテラル -100 である必要があります。その他の 3 つの引数には、以下の情報を指定します。

• keywords — さまざまなオプションを指定するキーワードが含まれる文字列。例えば、文字列 "/ASYNC/LOGCMD" は、プログラムを非同期に実行し、コマンド行をログ・ファイルに書き込む必要があることを指定します。

• command — 呼び出すプログラムまたはシステム・コマンドを指定する文字列。実行可能プログラムのフル・パスを指定しないと、オペレーティング・システムでは標準の検索パス・ルールが適用されます。

• arguments — コマンドの引数は一連のコンマ区切り式として指定されます (以下の例で示しています)。

$ZF(-100) 関数は、オペレーティング・システムおよび呼び出されたプログラムによって判断された終了状態コードを返します。

以下の例では、3 つの文字列が echo コマンドに渡された後、状態コードが表示されます。この例ではキーワードは使用されていないので、keywords 引数は空の文字列になっています。最後のコマンド引数は、引用符付き文字列を指定します (標準の ObjectScript 文字列ルールに従っています)。

   USER>set status = $ZF(-100,"","echo","hello","world","""goodbye now""")
   hello world "goodbye now"

   USER>write status
   0

以下のセクションでは、さらに、さまざまな $ZF(-100) オプションの例を示しています。キーワードおよびその他のオプションの概要は、"コールアウトのクイック・リファレンス" の章の “$ZF(-100) ： プログラムまたはシステム・コマンドの実行” を参照してください。

プログラムの実行

$ZF(-100) を使用すると、同期的または非同期的に、オペレーティング・システム・シェルを呼び出してまたは呼び出さずに、プログラムまたはコマンドを実行できます。既定では、シェルを呼び出さずに同期的に実行されます。既定の実行は、関数呼び出しでオプションのキーワードを指定することによってオーバーライドできます。

以下のキーワードを使用して、プログラム実行を制御できます。

• /ASYNC — プログラムを非同期で実行する必要があることを示します。これにより $ZF(-100) の呼び出しから、プログラムの完了を待たずに値が返されます。

• /SHELL — プログラムをオペレーティング・システム・シェル内で実行する必要があることを示します。

前のセクションで触れたように、これらのオプションのいずれも使用しない場合は、keyword パラメータに空の文字列を指定できます。この例では、エラー・コード 1 が生成されるように、存在しないファイルを意図的にリストしようとしています。

   USER>set status = $ZF(-100,"", "ls","*.scala")
   ls: cannot access *.scala: No such file or directory

   USER>write st
   1

同じコマンドを非同期で実行すると、エラー・コードが返されるため、出力は表示されず、st は未定義になります。

   USER>kill st
   USER>set status = $ZF(-100,"/ASYNC", "ls","*.scala")
   USER>write st

   WRITE st
   ^
   <UNDEFINED> *st

このような状況でエラー出力をリダイレクトする方法は、次のセクションの “入出力リダイレクトの使用法” を参照してください。

コマンドの記録と出力のリダイレクト

以下のキーワードによって、ログへの記録と入出力リダイレクトが制御されます。

• /LOGCMD — プログラム・コマンドおよび引数がコンソール・ログに送信されるようにします。

• /STDIN、/STDOUT、および /STDERR — これらを使用して、呼び出されたプログラムの標準の入力、標準の出力、および標準のエラーをリダイレクトします。これらのキーワードの後ろには、ファイルの指定を付ける必要があります (以下の “入出力リダイレクトの使用法” を参照してください)。

コマンド引数のログへの記録

/LOGCMD キーワードによって、コマンド引数および終了状態コードがコンソール・ログ (<install-dir>\mgr\messages.log) に記録されるようになります。これは主に、$ZF(-100) に渡された式が実際にどのように評価されたかを確認するためのデバッグ・ツールになることを目的としています。

ほとんどの場合、コマンドおよびその引数は 1 行に記録され、次の行に戻り値が記録されます。例えば、Windows では set st=$ZF(-100,"/LOGCMD","echo","hello","world") によって以下のログ・エントリが生成されます。

   03/28/18-11:49:51:898 (26171) 0 $ZF(-100) cmd=echo "hello" "world"
   03/28/18-11:49:51:905 (26171) 0 $ZF(-100) ret=0

ただし、UNIX® では、/SHELL が指定されていない場合、以下のように値は 1 行に 1 つずつ記録されます。

   03/28/18-12:09:22:243 (26171) 0 $ZF(-100) argv[0]=echo
   03/28/18-12:09:22:500 (26171) 0 $ZF(-100) argv[1]=hello
   03/28/18-12:09:22:559 (26171) 0 $ZF(-100) argv[2]=world
   03/28/18-12:09:22:963 (26171) 0 $ZF(-100) ret=0

いずれの場合でも、引数はプログラムで受け取られるとおりに記録されます。

入出力リダイレクトの使用法

以下のキーワードとファイル指定子は、入出力リダイレクトを制御します。

• /STDIN=input-file

• /STDOUT=output-file または /STDOUT+=output-file

• /STDERR=error-file または /STDERR+=error-file

入出力リダイレクト・キーワードの後ろには、演算子 ( = または += ) と、ファイル名またはファイル・パスが続きます。演算子の前後にスペースを入れることができます。標準の入力は、既存のファイルを指す必要があります。標準の出力および標準のエラー・ファイルは、存在しない場合は作成され、既に存在する場合は切り捨てられます。ファイルを作成または切り捨てるには = 演算子を使用し、既存のファイルに追加を行うには += 演算子を使用します。標準のエラーと標準の出力が同一のファイルに送信されるようにするには、両方のキーワードに同じファイルを指定します。

次の例の最初の行では echo コマンドからファイル temp.txt に標準の出力がリダイレクトされ、2 つ目の行に結果のファイル・コンテンツが表示されています。

   USER>set st = $ZF(-100,"/STDOUT=""temp.txt""","echo","-e","three\ntwo\none\nblastoff")  
   USER>set st = $ZF(-100,"","cat","temp.txt")
   three
   two
   one
   blastoff

次の例では、ファイル temp.txt を標準の入力にリダイレクトすることによって、このファイルの 2 行を別の方法で表示しています。tail コマンドが入力を受け入れ、最後の 2 行を表示します。

   USER>set st=$ZF(-100,"/STDIN=""temp.txt""","tail","-n2")
   one
   blastoff

次の最後の例では、標準のエラーが temp.txt にリダイレクトされ、存在しないファイルの表示を試行しています。ここでは、コマンドを非同期で実行するために /ASYNC キーワードも使用されており、$ZF(-100) 呼び出しが値を返してから、エラー・メッセージを表示できるようになっています。ここでも 2 つ目の行 (前の例とまったく同じ) にファイルの最後の 2 行が表示されており、リダイレクトされたエラー・メッセージが含まれています。

   USER>set st = $ZF(-100,"/ASYNC /STDERR+=""temp.txt""","cat","nosuch.file")

   USER>set st=$ZF(-100,"/STDIN=""temp.txt""","tail","-n2")
   blastoff
   cat: nosuch.file: No such file or directory

%System_Callout:USE 特権の追加

InterSystems セキュリティ設定が最低 (0) よりも高い場合は、$ZF(-100) に %System_Callout:USE 特権が必要です。

%System_CallOut リソースは、インストール時に開発者設定を選択した場合に持つ %Developer ロールに既に割り当てられています。以下の手順では、まだこのリソースを持っていない場合に、これを割り当てる方法を説明しています。