Caché コールアウト・ゲートウェ イの使用法 Version 2014.1 2014 年 06 月 24 日 InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com Caché コールアウト・ゲートウェイの使用法 Caché Version 2014.1 2014 年 06 月 24 日 Copyright © 2014 InterSystems Corporation All rights reserved. このドキュメントは、 Oracle Corporation、RenderX Inc.、 アドビ システムズ および ワールドワイド・ウェブ・コンソーシアム(www.w3c.org)のツールと 情報を使用して、 Adobe Portable Document Format (PDF)で作成およびフォーマットされました。主要ドキュメント開発ツールは、InterSystemsが構 築したCacheéと Javaを使用した特別目的のXML処理アプリケーションです。 , , , , Caché WEBLINK, および Distributed Cache Protocol は InterSystems Corporation の登録商標です。 and , InterSystems TrakCare, InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP および InterSystems Zen は InterSystems Corporation の 登録商標です。 ここで使われている他の全てのブランドまたは製品名は、各社および各組織の商標または登録商標です。 このドキュメントは、インターシステムズ社(住所:One Memorial Drive, Cambridge, MA 02142)あるいはその子会社が所有する企業秘密および秘密 情報を含んでおり、インターシステムズ社の製品を稼動および維持するためにのみ提供される。この発行物のいかなる部分も他の目的のために使 用してはならない。また、インターシステムズ社の書面による事前の同意がない限り、本発行物を、いかなる形式、いかなる手段で、その全てまたは 一部を、再発行、複製、開示、送付、検索可能なシステムへの保存、あるいは人またはコンピュータ言語への翻訳はしてはならない。 かかるプログラムと関連ドキュメントについて書かれているインターシステムズ社の標準ライセンス契約に記載されている範囲を除き、ここに記載さ れた本ドキュメントとソフトウェアプログラムの複製、使用、廃棄は禁じられている。インターシステムズ社は、ソフトウェアライセンス契約に記載され ている事項以外にかかるソフトウェアプログラムに関する説明と保証をするものではない。さらに、かかるソフトウェアに関する、あるいはかかるソフ トウェアの使用から起こるいかなる損失、損害に対するインターシステムズ社の責任は、ソフトウェアライセンス契約にある事項に制限される。 前述は、そのコンピュータソフトウェアの使用およびそれによって起こるインターシステムズ社の責任の範囲、制限に関する一般的な概略である。完 全な参照情報は、インターシステムズ社の標準ライセンス契約に記され、そのコピーは要望によって入手することができる。 インターシステムズ社は、本ドキュメントにある誤りに対する責任を放棄する。また、インターシステムズ社は、独自の裁量にて事前通知なしに、本ド キュメントに記載された製品および実行に対する代替と変更を行う権利を有する。 インターシステムズ社の製品に関するサポートやご質問は、以下にお問い合わせください: Tel: Fax: Email: InterSystems Worldwide Customer Support +1 617 621-0700 +1 617 374-9391 [email protected] 目次 このドキュメントについて ................................................................................................... 1 1 はじめに ..................................................................................................................... 3 1.1 コールアウト・ゲートウェイの概念および用語 ............................................................. 3 1.2 $ZF 関数の概要 .................................................................................................. 4 1.3 互換性のある言語とコンパイラ ................................................................................ 5 2 オペレーティング・システム・コマンドの発行 ....................................................................... 7 2.1 $ZF(-1) を使用したシステム・コマンドの発行 ............................................................. 7 2.1.1 OpenVMS デバイス・パラメータの使用 ............................................................. 8 2.2 ZF(-2) を使用した同時子プロセスの作成 ................................................................. 9 2.3 %System_Callout:USE 特権の追加 ........................................................................... 9 2.3.1 ユーザへのロールの割り当て ........................................................................ 9 2.3.2 新規ロールの作成 ..................................................................................... 10 3 Caché コールアウト・ライブラリの作成 .............................................................................. 11 3.1 コールアウト・ライブラリの概要 ............................................................................... 11 3.1.1 ZFEntry テーブルの作成 ............................................................................ 13 3.2 ZFEntry リンク・オプション .................................................................................... 14 3.2.1 リンクの概要 .............................................................................................. 14 3.2.2 数値リンクの使用 ....................................................................................... 15 3.2.3 NULL で終了する文字列を C リンク・タイプで渡す .......................................... 16 3.2.4 計算文字列を B リンク・タイプで渡す ............................................................ 17 3.2.5 Caché の長い文字列を J リンク・タイプで渡す ................................................. 18 3.2.6 $ZF ヒープの構成 ...................................................................................... 20 3.3 コールアウト・ライブラリの Runup 関数と Rundown 関数 ............................................. 20 3.4 トラブルシューティング ......................................................................................... 21 4 コールアウト・ライブラリ関数の呼び出し ........................................................................... 23 4.1 コールアウト・ライブラリのインタフェース .................................................................. 23 4.2 単純なライブラリ関数呼び出しでの $ZF(-3) の使用 ................................................. 24 4.3 システム ID によるライブラリへのアクセスでの $ZF(-5) の使用 ................................... 25 4.4 ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用 ......................... 27 4.4.1 ライブラリ関数のカプセル化での $ZF(-6) インタフェースの使用 ......................... 29 4.4.2 テストでのプロセス・インデックスの使用 .......................................................... 31 5 静的にリンクされたコールアウト関数 ............................................................................... 33 5.1 静的にリンクされたコールアウト関数の呼び出し ....................................................... 33 5.2 Windows でのカスタム CACHE.EXE ファイルの作成 ................................................ 34 5.3 UNIX®、Linux、または OS-X でのカスタム CACHE.EXE ファイルの作成 ..................... 35 5.4 OpenVMS でのカスタム CZF.EXE ファイルの作成 ................................................... 36 6 UNIX® に関する特別な考慮事項 .................................................................................. 39 6.1 その他のコールアウト・シグナル処理 ..................................................................... 39 7 OpenVMS に関する特別な考慮事項 .............................................................................. 41 7.1 CZF.M64 の使用 ............................................................................................... 41 7.2 特権レベルを上げる ZFPRIV の使用 ..................................................................... 42 7.3 71 システム・サービスでの V リンクの使用 .............................................................. 42 7.4 DSM に代わる $ZF 関数呼び出し ......................................................................... 43 7.4.1 $ZF 内部関数 ........................................................................................... 44 Caché コールアウト・ゲートウェイの使用法 iii 8 Caché コールアウトのクイック・リファレンス ........................................................................ 53 8.1 静的にリンクされた関数の使用 ............................................................................. 54 8.2 プログラムまたはシステム・コマンドの実行 ............................................................... 54 8.3 インデックスなしのコールアウト・ライブラリの使用 ...................................................... 55 8.4 インデックス付きのコールアウト・ライブラリの使用 ..................................................... 57 iv Caché コールアウト・ゲートウェイの使用法 このドキュメントについて Caché コールアウト・ゲートウェイ (Caché $ZF 関数に実装されている) を使用すると、外部プログラムおよびシステム・ サービスを Caché から呼び出すことができます。また、カスタム・コードを Caché に統合する方法も提供します。 このドキュメントでは、以下の項目について説明します。 • はじめに — Caché コールアウト・ゲートウェイの機能についてまとめ、サンプルおよびその他のリソースへのリンクを 提供します。 • オペレーティング・システム・コマンドの発行 — オペレーティング・システム・コマンドおよびサービスへのアクセスに 使用できる子プロセスを生成する方法を説明します。 • Caché コールアウト・ライブラリの作成 — Caché から呼び出すことができる関数を備えたコールアウト共有ライブラリ の作成方法を説明します。コードは、C/C++ 呼び出し規則をサポートする任意の言語で記述できます。 • コールアウト・ライブラリ関数の呼び出し — コールアウト共有ライブラリから関数を動的に呼び出す方法を説明しま す。 • 静的にリンクされたコールアウト関数 — コールアウト関数を含むカスタマイズ・バージョンの Caché を作成する方法 を説明します。 • UNIX® に関する特別な考慮事項 — UNIX® および関連するオペレーティング・システムのみに関する問題につい て説明します。 • OpenVMS に関する特別な考慮事項 — OpenVMS のみに関する問題について説明します。 • Caché コールアウトのクイック・リファレンス — 各 $ZF 関数の詳細な説明を提供します。 詳細は、目次 を参照してください。 一般的な情報については、InterSystems のドキュメントの使用法 を参照してください。 Caché コールアウト・ゲートウェイの使用法 1 1 はじめに Caché コールアウト・ゲートウェイを使用すると、Caché アプリケーションがシェルまたはオペレーティング・システム・コマ ンドを呼び出し、生成されたプロセスで外部プログラムを実行し、特別に記述された共有ライブラリから関数を呼び出す ことができます。コールアウト・ゲートウェイは、Caché $ZF システム関数内に含まれる一連の関連した関数として実装さ れます。 以下の項目について説明します。 • コールアウト・ゲートウェイの概念および用語 — このドキュメントの以降の部分を読む前に知っておくべき事柄のリス トです。 • $ZF 関数の概要 — コールアウト・ゲートウェイによって提供される機能の概要を説明します。 • 互換性のある言語とコンパイラ — コールアウト・ゲートウェイの利点を最大限に活用するために必要ないくつかのソ フトウェアについて説明します。 1.1 コールアウト・ゲートウェイの概念および用語 このドキュメントの以降の部分を読む前に理解しておく必要がある重要な概念について説明します。 個々の $ZF 関数の識別 $ZF スイート内の個々の関数は、関数呼び出しの最初の引数によって識別されます。これは -1 ~ -6 の負の 数字です。例えば、オペレーティング・システム・コマンドを呼び出す関数は $ZF(-1, <oscommand>) の形 式を持ちます。ここで、<oscommand> は、実行されるコマンドを含む文字列です。この関数について述べる場 合には、$ZF(-1) と示されます。同様に、その他の関数は、実際の関数呼び出しの最初のパラメータのみを使 用して $ZF(-2) ~ $ZF(-6) と示されます。 $ZF(-4) 関数は、実際は最初の 2 つのパラメータ $ZF(-4,1) ~ $ZF(-4,8) によって識別される 8 つのユーティ リティ関数のコンテナであるため、特殊なケースです。 これらの関数の概要については、この章で後述する “$ZF 関数の概要” を参照してください。すべての $ZF 関数の完全なリスト、それらの使用方法に関する情報、および詳細な情報および例へのリンクについては、 “Caché コールアウトのクイック・リファレンス” を参照してください。 コールアウト・ライブラリ このドキュメントでは、共有ライブラリという用語は、動的にリンクされたファイル (Windows の DLL ファイル、 UNIX® および関連オペレーティング・システムの SO ファイル、または OpenVMS の共有可能イメージ・ファイ ル) を示します。コールアウト・ライブラリは、コールアウト・ゲートウェイへのフックを含む共有ライブラリであり、多 Caché コールアウト・ゲートウェイの使用法 3 はじめに 様な $ZF 関数が実行時にロードして、その関数を呼び出すことができるようにします。コールアウト・ライブラリ は、通常は C で記述されますが (“互換性のある言語とコンパイラ” を参照)、ご使用の C コンパイラで認識さ れる呼び出し規則を使用するその他のコンパイル言語で記述される場合もあります。 コールアウト・ライブラリの記述方法の詳細は、“Caché コールアウト・ライブラリの作成” を参照してください。 コールアウト・ライブラリのインタフェース すべての $ZF 関数 ($ZF(-1) および $ZF(-2) を除く) は、コールアウト・ライブラリへのいくつかのアクセス形式 を提供するために使用されます。$ZF(-3)、$ZF(-5)、および $ZF(-6) 関数は、コールアウト・ライブラリ関数の呼 び出しに 3 つの異なるインタフェースを提供します。$ZF(-4) は、$ZF(-5) および$ZF(-6) インタフェースと一緒 に使用される多様なユーティリティ関数のコンテナです。 コールアウト・ライブラリへの多様なアクセス方法の詳細は、“コールアウト・ライブラリ関数の呼び出し” を参照 してください。 1.2 $ZF 関数の概要 $ZF 関数スイートには、以下の関数があります。 $ZF(-1) および $ZF(-2) 関数 $ZF(-1) および $ZF(-2) 関数は、シェル・コマンドおよびオペレーティング・システム・サービスの呼び出しの実 行に使用されます。これらは、コールアウト・ライブラリへのアクセスには使用されず、前の設定なしで呼び出す ことができます。 詳細は、“ オペレーティング・システム・コマンドの発行” を参照してください。 $ZF(-3) 関数 $ZF(-3) 関数は、コールアウト・ライブラリをロードして単一の文でライブラリ関数を呼び出す簡単な方法です。 ライブラリとその関数の両方が名前で指定され、ライブラリは異なるライブラリへの呼び出しによって置き換えら れるまでメモリ内に残ります。 詳細は、“ 単純なライブラリ関数呼び出しでの $ZF(-3) の使用” を参照してください。 $ZF(-4) 関数 $ZF(-4) 関数は、8 つのユーティリティ関数セットのコンテナです。$ZF(-5) 関数インタフェースは、関数 $ZF(-4,1) ~ $ZF(-4,3) を使用し、$ZF(-6) 関数インタフェースは、関数 $ZF(-4,5) ~ $ZF(-4,8) を使用します。詳細は、 以下の説明を参照してください。 $ZF(-5) 関数インタフェース $ZF(-5) 関数およびそのユーティリティ関数を使用すると、複数のライブラリを効率的に処理できます。ライブラ リおよびその関数の両方がシステム定義の ID 値によって識別されます。複数のライブラリを同時に仮想メモリ 内に入れることができます。以下の $ZF(-4) 関数はライブラリのロードやアンロード、およびライブラリや関数 ID 値の取得に使用されます。 • $ZF(-4,1) は、名前によって指定されるライブラリをロードし、ライブラリ ID を返します。 • $ZF(-4,2) は、ライブラリをアンロードします。 • $ZF(-4,3) は、指定されたライブラリ ID および関数名の関数 ID を返します。 詳細は、“ システム ID によるライブラリへのアクセスでの $ZF(-5) の使用” を参照してください。 4 Caché コールアウト・ゲートウェイの使用法 互換性のある言語とコンパイラ $ZF(-6) 関数インタフェース $ZF(-6) 関数およびそのユーティリティ関数は、ハードコード化されたライブラリ名を必要としないコールアウト・ アプリケーションを記述する方法を提供します。代わりに、実際のライブラリ・ファイル名は別のインデックス・テー ブルに含まれます。ここでは、各ライブラリは一意のユーザ定義インデックス番号に関連付けられています。イ ンデックス・テーブルが定義されると、Caché のインスタンス内のすべてのプロセスで利用可能になります。コー ルアウト・アプリケーションは、ライブラリをインデックス番号で識別し、インデックス・テーブルを読み取ることに よってロードします。複数のライブラリを同時にメモリ内に入れることができます。以下の関数は、インデックスの 管理とライブラリのロードまたはアンロードに使用されます。 • $ZF(-6) は、ライブラリ関数を呼び出し、ライブラリがまだメモリ内に無い場合には、ロードします。 • $ZF(-4,4) は、ライブラリをアンロードします。 • $ZF(-4,5) および $ZF(-4,6) は、Caché のインスタンス内のすべてのプロセスでアクセス可能なシステム・イ ンデックス・テーブルを作成および維持するために使用されます。 • $ZF(-4,7) および $ZF(-4,8) は、単一プロセス内のシステム・インデックスをオーバーライドするために使用 できるプロセス・インデックス・テーブルを作成および維持するために使用されます。 詳細は、“ ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用” を参照してください。 $ZF() 関数 通常、C 関数コードは、コールアウト・ライブラリの生成に使用されますが、Caché 実行可能ファイルのカスタム・ バージョンに直接リンクすることもできます。$ZF() 関数 (負の数の引数なし) は、静的にリンクされたコールアウ ト関数を呼び出すためのインタフェースです。$ZF(-3)、$ZF(-5)、または $ZF(-6) とは異なり、外部ライブラリ識 別子を指定する必要はなく、静的にリンクされた関数は関数名および引数を指定するだけで呼び出すことがで きます。 詳細は、“ 静的にリンクされたコールアウト関数” を参照してください。 1.3 互換性のある言語とコンパイラ コールアウト・ゲートウェイを使用して、Caché ObjectScript 以外の言語で記述されたルーチンを呼び出すことができま す。Caché をサポートするすべてのプラットフォーム上で、C 言語で記述されたルーチンを呼び出すことができます。理 論上は、C と互換性がある任意のコンパイル言語で記述されたルーチンを呼び出すことができますが、2 つの互換性の 問題が発生します。1 つは、コンパイラは C と互換性があるアプリケーション・バイナリ・インタフェース (ABI) を使用する 必要があることです。2 つ目は、コンパイラは Caché と互換性がないランタイム・ライブラリ機能に依存しないコードを生 成する必要があることです。 インターシステムズは、すべてのプラットフォーム上で Caché を生成するために使用するのと同じ C コンパイラの使用を サポートします。 Caché コールアウト・ゲートウェイの使用法 5 はじめに プラットフォーム コンパイラ HP HP-UX 11 HP C/aC++ コンパイラ HP OpenVMS Alpha HP C HP Tru64 UNIX Compaq C IBM AIX AIX 用 IBM XL C Mac OS X (Darwin) Xcode Microsoft Windows Microsoft Visual Studio Oracle Solaris Sun C Linux (系列すべて) GNU プロジェクト GCC C ほとんどのプラットフォームは、標準化されたアプリケーション・バイナリ・インタフェース (ABI) を備え、ほとんどのコンパ イラに互換性があります。Intel x86-32 および x86-64 プラットフォームは主な例外であり、これらのプラットフォームには、 複数の呼び出し規則が存在します。これらのプラットフォームでの呼び出し規則については、 (http://en.wikipedia.org/wiki/X86_calling_conventions) を参照してください。 Microsoft Windows の場合、x86-32 プラットフォームでは cdecl インタフェース、x86-64 では (http://msdn.microsoft.com/ja-jp/library/9b372w95(v=vs.80).aspx) で記述されている呼び出し規則を使用します。 多くの C コンパイラでは別の呼び出し規則を使用する外部ルーチンの宣言を許可しているため、異なる呼び出し規則 を使用する言語を呼び出すことは可能です。したがって、C ラッパ・ルーチンを記述するのであれば、他の言語で記述 されたルーチンを呼び出すことができます。 OpenVMS では、すべてのコンパイラが OpenVMS Calling Standard (http://h71000.www7.hp.com/doc/82final/5973/5973pro.html) に従っています。 6 Caché コールアウト・ゲートウェイの使用法 2 オペレーティング・システム・コマンドの発行 Caché $ZF(-1) および $ZF(-2) 関数により、Caché からオペレーティング・システム・コマンドを発行できます。これらは、 特別なコールアウト共有ライブラリなしで使用できる Caché コールアウト関数です (“Caché コールアウト・ライブラリの作 成” を参照)。このセクションで説明する項目は以下のとおりです。 • $ZF(-1) を使用したシステム・コマンドの発行 — $ZF(-1) コマンドは、Windows の MS-DOS コマンド、UNIX® およ び Linux のシェル・コマンドとシステム・サービス、または OpenVMS の DCL コマンドとシステム・サービスを発行す るために使用します。 • $ZF(-2) を使用した同時子プロセスの作成 — $ZF(-2) の操作は、$ZF(-1) と基本的に同じですが、Caché が非同 期子プロセス内でシステム・コマンドを実行し、返りを待機しない点が異なります。 • %System_Callout:USE 特権の追加 — Caché セキュリティ設定が最低よりも高い場合は、$ZF(-1) および $ZF(-2) の 両方で %System_Callout:USE 特権が必要です。 2.1 $ZF(-1) を使用したシステム・コマンドの発行 $ZF(-1) は、ホスト・オペレーティング・システムのコマンドの呼び出しを許可します。指定されたコマンドは、現在のコン ソールから生成された子プロセスとして実行されます。$ZF(-1) は、子プロセスの終了を待機し、子プロセスの実行中は 親 Caché プロセスの終了を許可しません。 子プロセスが終了した後で、$ZF(-1) は、オペレーティング・システム・シェルによって発行された終了ステータス・エラー・ コードを返します。可能な値は、関数呼び出しが正常に実行された場合は 0、エラーが発生した場合は 1、子プロセス が生成されなかった場合は -1 です。 Windows Windows では、以下の ObjectScript コードによって test folder という名前のディレクトリが現在のディレクトリ内 に作成されます (名前にスペースが含まれるため、Windows ではディレクトリ名の前後に引用符を追加する必 要があります)。 SET status = $ZF(-1,"mkdir ""test folder""") UNIX® および Linux 以下の例では、pwd コマンドを実行しています。 SET status = $ZF(-1,"pwd") シェル・ウィンドウに次のような出力が表示されます。 Caché コールアウト・ゲートウェイの使用法 7 オペレーティング・システム・コマンドの発行 /usr/cachesys OpenVMS 以下の例では、DCL SHOW DEF コマンドを実行しています。 SET status = $ZF(-1,"SHOW DEF") シェル・ウィンドウに次のような出力が表示されます。 DUA0:[usr] DCL 呼び出しにいかなる特権レベルが必要であったとしても、呼び出しを実行するプロセスは、コマンドの完 了後、元の特権レベルに戻ります。 注釈 ほとんどの場合、$ZF(-1) はバックグラウンドで有効なコマンドでのみ使用する必要があります。コマンドがユー ザ入力を必要とする場合 (以下の例のようにユーザがメモ帳を終了することが必要)、子プロセスが停止します。 以下の例のコマンドでは、指定されたファイルを .txt ファイルの既定のアプリケーションで開きます。 $ZF(-1) を使用したテキスト・ファイルのオープン SET fname="""C:\My Test.txt""" WRITE fname,! SET status=$ZF(-1,fname) WRITE status /// NOTE: THIS EXAMPLE STARTS A PROCESS THAT WILL NOT RETURN UNTIL YOU /// CLOSE THE PROGRAM (USUALLY NOTEPAD) THAT OPENS THE TEXT FILE. • fname が定義されるとき、パス全体が二重引用符で囲まれています。これは、パスにスペースが含まれてい る場合に、Windows および UNIX® で必須です。OpenVMS の場合はパス名内のスペースに対して特別な 処理は要求されません。 • $ZF(-1,fname) への呼び出しでは、ファイルが .txt ファイルの既定のアプリケーションで開きます。Windows の場合、これは以下の MS-DOS コマンドを発行するのと同等です。 C:\>call "C:\My Test.txt" 既定では、このコマンドではメモ帳でファイルが開きます。子プロセスは、再びメモ帳が閉じられるまで返ら ず、$ZF(-1) は、メモ帳が開いている間は親 Caché プロセスの終了を許可しません。 • 注釈 status の返される値は、関数呼び出しが正常に実行された場合は 0、エラーが発生した場合 (例えば、 C:\My Test.txt が存在しない場合) は 1、子プロセスがフォークできない場合は -1 です。 Caché ターミナルでの $ZF(-1) の使用 $ZF(-1) は、インタラクティブなオペレーティング・システム・シェルを Caché ターミナルにロードするためにも使 用できます ("Caché ターミナルの使用法" の “オペレーティング・システム・シェル” を参照してください)。こ れは、! ターミナル・コマンドのように動作しますが、$ZF(-1) が別のウィンドウで実行される点が異なります。! は、すべてCaché ターミナル・ウィンドウ内で動作します。 2.1.1 OpenVMS デバイス・パラメータの使用 OpenVMS では、$ZF(-1) コマンドは以下のようにオプション・デバイスの入力および出力パラメータを使用できます。 SET status = $ZF(-1,DCLcommand[,outdev[,indev]]) ここで、子プロセスに対して outdev は SYS$OUTPUT を指定し、indev は SYS$INPUT を指定します。 8 Caché コールアウト・ゲートウェイの使用法 ZF(-2) を使用した同時子プロセスの作成 $ZF(-1) 発行時に生成された OpenVMS プロセスが強制終了あるいは停止された場合、返りコードは -1 になります。 親プロセスと同じ SYS$INPUT の使用を試みる子プロセスによってこの問題が発生する場合があります。これは、indev パラメータを指定することにより対処できます。OpenVMS エラー・コードは、SYSLOG ユーティリティを使用して表示でき ます。 2.2 ZF(-2) を使用した同時子プロセスの作成 $ZF(-2) は、指定されたプログラムを現在のコンソールから生成された子プロセスとして実行します。子プロセスを生成し たら直ちに返し、プロセスの終了を待機しません。入力と出力のデバイスは、NULL デバイスが既定になります。 注釈 $ZF(-2) 経由で実行されるコマンドは、主デバイスでの入出力を実行できません。通常、Caché では主デバイ スと NULL デバイスは同等です。 $ZF(-2) は子プロセスの終了状態を返しません。代わりに、子プロセスが正常に作成された場合はゼロを返し、子プロセ スをフォークできなかった場合には -1 を返します。$ZF(-2) は、Caché が終了された場合でも、Caché から呼び出され たプログラムの実行の継続を許可します。 $ZF(-2) は、コマンドを実行する前に親プロセスの主デバイス (Caché 特殊変数 $PRINCIPAL で指定) を終了します。 これは、子プロセスが親プロセスと同時に実行されるためです。$ZF(-2) が $PRINCIPAL を終了しなかった場合は、親 と子からの出力が混ざり合います。$ZF(-2) の使用時に、子プロセスからの出力を回復させる場合は、コマンドで入出力 をリダイレクトします。以下はその例です。 SET x=$ZF(-2,"ls -l > mydir.txt") progname で指定されたパス名にスペース文字が含まれる場合、パス名の処理はプラットフォームによって異なります。 OpenVMS の場合はパス名にスペースを使用でき、特別な処理は要求されません。UNIX® の場合はパス名にスペース 文字を使用することができますが、スペースを含むパス名は、二重引用符 (“) で囲む必要があります。Windows では、 スペースを削除するか、またはスペースを含むパス名を追加の引用符で囲むことが必要です。例えば、スペースがない 場合は、"C:\MyDocuments"、スペースがある場合は、""C:\My Documents"" となります。%Library.File クラスの NormalizeFilenameWithSpaces() メソッドを使用すると、パス名内のスペースがホスト・プラットフォームに合わせて処理さ れるようにできます。 2.3 %System_Callout:USE 特権の追加 Caché セキュリティ設定が最低よりも高い場合は、$ZF(-1) および $ZF(-2) の両方で %System_Callout:USE 特権が 必要です。 %System_CallOut リソースは、Caché のインストール時に開発者設定を選択した場合に持つ %Developer ロールに 既に割り当てられています。以下のセクションは、まだこのリソースを持っていない場合に、これを割り当てる方法を説明 します。 • ユーザへのロールの割り当て — %Developer ロールをユーザに割り当てる方法を説明します。 • 新規ロールの作成 — %System_CallOut:USE 特権のみを付与する新規ロールを作成する方法を説明します。 2.3.1 ユーザへのロールの割り当て 以下の手順を使用して、%Developer ロールを割り当てます。 Caché コールアウト・ゲートウェイの使用法 9 オペレーティング・システム・コマンドの発行 1. SMP を開き、[システム管理] > [セキュリティ管理] > [ユーザ] に移動して、使用するユーザ説明上で [編集] をクリッ クし、[ロール] タブを選択します。 2. %Developer ロールを [使用可能] 列から [選択済み] 列に移動して [割り当てる] をクリックします。このユーザに 割り当てるロールのリストにロールが表示されます (%Developer ロールが [使用可能] 列に表示されない場合は、 ロールのリストをチェックして、既にこのロールを持っているかどうかを確認します)。 3. [プロファイル] ボタンをクリックします。%Developer ロールが [ロール:] 行にリストされます。 2.3.2 新規ロールの作成 $ZF(-1) および $ZF(-2) の使用を許可するが、その他の特権を付与しないロールを持つことが望ましい場合があります。 以下の手順を使用して、%System_CallOut:USE 特権のみを付与する新規ロールを作成します。 1. SMP を開き、[システム管理] > [セキュリティ管理] > [ロール] に移動します。 2. [新規ロール作成] ボタンをクリックして、[ロール編集] ページを開きます。 3. 以下のように名前と説明を入力します。 • 名前: UseCallout • 説明: %System_CallOut [保存] をクリックすると、フォームに [追加] ボタンが表示されます。 4. [追加] ボタンをクリックすると、リソースのスクロール・リストが表示されます。リストから %System_CallOut を選択し て [保存] をクリックします。[ロール編集] フォームの [閉じる] をクリックします。 5. [ロール] ページのロール定義のリストに新しい UseCallout ロールが表示されます。 10 Caché コールアウト・ゲートウェイの使用法 3 Caché コールアウト・ライブラリの作成 Caché コールアウト・ライブラリは、カスタム・コールアウト関数、および Caché がそれらを使用できるようにする使用可能 化コードを含む共有ライブラリです。この章では、コールアウト・ライブラリを作成して実行時にアクセスする方法を説明し ます。 以下の項目について説明します。 • コールアウト・ライブラリの概要 — コールアウト・ライブラリの作成およびアクセス方法を説明します。 • ZFEntry リンク・オプション — 関数引数が渡される方法を決定するリンク・オプションの詳細を説明します。 • コールアウト・ライブラリ Runup 関数と Rundown 関数 — コールアウト・ライブラリがロードまたはアンロードされるとき に自動的に呼び出される 2 つのオプション関数について説明します。 • トラブルシューティング — 避けるべきコーディング作業について説明します。 注釈 共有ライブラリとコールアウト・ライブラリ このドキュメントでは、共有ライブラリという用語は、動的にリンクされたファイル (Windows の DLL ファイル、 UNIX® および関連オペレーティング・システムの SO ファイル、または OpenVMS の共有可能イメージ・ファイ ル) を示します。コールアウト・ライブラリは、コールアウト・ゲートウェイへのフックを含む共有ライブラリであり、 多様な $ZF 関数が実行時にこれをロードし、アクセスできるようにします。 3.1 コールアウト・ライブラリの概要 Caché ObjectScript コードからコールアウト・ライブラリにアクセスするには複数の方法がありますが、一般的には、ライブ ラリ名、関数名、および必要な引数を指定するのが主な方法です (“コールアウト・ライブラリ関数の呼び出し” を参照)。 例えば、以下のコードでは、簡単なコールアウト・ライブラリ関数を呼び出します。 コールアウト・ライブラリ simplecallout.dll からの関数 AddInt の呼び出し 以下の ObjectScript コードは、Caché ターミナルで実行されます。これは、simplecallout.dll という名前のコー ルアウト・ライブラリをロードし、2 つの整数引数を加算して合計を返す AddInt と言う名前のライブラリ関数を呼 び出します。 USER> set sum = $ZF(-3,"simplecallout.dll","AddInt",2,2) USER> write "The sum is ",sum,! The sum is 4 この例では、$ZF(-3) を使用します。これは、単一のコールアウト・ライブラリ関数を呼び出す最も簡単な方法で す。その他のオプションは、“コールアウト・ライブラリ関数の呼び出し” を参照してください。 Caché コールアウト・ゲートウェイの使用法 11 Caché コールアウト・ライブラリの作成 simplecallout.dll コールアウト・ライブラリの複雑さは、それを呼び出すコードとあまり変わりません。すべてのコールアウ ト・ライブラリで必要とされる以下の 3 つの要素を含みます。 1. cdzf.h コールアウト・ヘッダ・ファイルを含めるときに提供される標準コード。 2. パラメータが正しく指定された 1 つ以上の関数。 3. ZFEntry テーブル のマクロ・コード。これは、ライブラリがロードされる際に Caché がコールアウト関数を見つけるた めに使用するメカニズムを生成します (詳細は、“ZFEntry テーブルの作成” を参照してください)。 simplecallout.dll コールアウト・ライブラリを生成するためにコンパイルされたコードは以下のとおりです。 simplecallout.dll のコールアウト・コード #include <cdzf.h> /* Required for all Callout code. */ #define ZF_DLL /* Required only for dynamically linked libraries. */ int AddTwoIntegers(int a, int b, int*outsum) { *outsum = a+b; /* set value to be returned by the $ZF function call */ return 0; /* set the exit status code */ } ZFBEGIN ZFENTRY("AddInt","iiP",AddTwoIntegers) ZFEND • 最初の行は、動的および静的リンク・コードの両方で必要な cdzf.h ファイルを含みます。 • 2 番目の行は、Caché にコードを静的にリンクする (“静的にリンクされたコールアウト関数” で後述) ので はなく、動的にリンクされたコールアウト・ライブラリを作成していることを示すスイッチである ZF_DLL を定 義します。 • AddTwoIntegers() 関数が次に定義されます。これには、以下の機能があります。 – 2 つの入力パラメータである整数 a と b、および 1 つの出力パラメータである整数ポインタ *outsum。 – 出力パラメータ *outsum に値を割り当てる文。これは、$ZF(-3) への呼び出しによって Caché に返さ れる値です。 – return 文は、関数出力値を返しません。代わりに、$ZF 呼び出しが正常に行われた場合に Caché によって受け取られる終了ステータス・コードを指定します。この関数が失敗した場合、Caché はシステ ムによって生成された終了ステータス・コードを受け取ります。 • 最後の 3 行は、Caché がコールアウト・ライブラリ関数を見つけるために使用する ZFEntry テーブルを生 成するマクロ呼び出しです。この例では、単一のエントリのみです。ここで、 – "AddInt" は、$ZF 呼び出し内の関数を識別するために使用される文字列です。 – "iiP" は、2 つの入力値および出力値のデータ型を指定する文字列です。 – AddTwoIntegers は、C 関数のエントリ・ポイント名です。 ZFEntry テーブルは、共有ライブラリをロードし、コールアウト・ゲートウェイによりアクセス可能にするメカニズムです (“ ZFEntry テーブルの作成” を参照)。ZFENTRY 宣言は、C 関数と ObjectScript $ZF 呼び出し間のインタフェースを 指定します。この例では、このインタフェースは、次のように動作します。 • C 関数宣言は、以下の 3 つのパラメータを指定します。 int AddTwoIntegers(int a, int b, int*outsum) パラメータ a および b は入力であり、outsum は、出力値を受け取ります。AddTwoIntegers の返り値は、終了ステー タス・コードであり、出力値ではありません。 • ZFENTRY マクロは、Caché 内での関数の識別方法およびパラメータが渡される方法を定義します。 12 Caché コールアウト・ゲートウェイの使用法 コールアウト・ライブラリの概要 ZFENTRY("AddInt","iiP",AddTwoIntegers) "AddInt" は、$ZF 呼び出し内の C 関数 AddTwoIntegers を指定するために使用されるライブラリ関数識別子で す。リンク宣言 ("iiP") は、パラメータ a および b をリンク・タイプ i (入力のみの整数) として、outsum をリンク・タ イプ P (入力および出力の両方に使用できる整数ポインタ) として宣言します。 • $ZF(-3) 関数呼び出しは、ライブラリ名、ライブラリ関数識別子、および入力パラメータを指定し、出力パラメータの 値を返します。 set sum = $ZF(-3,"simplecallout.dll","AddInt",2,2) パラメータ a および b は、最後の 2 つの引数によって指定されます。3 番目のパラメータ outsum は出力にのみ使 用されるため、引数は必要ありません。outsum の値は、$ZF(-3) 呼び出しが返されたときに sum に割り当てられま す。 3.1.1 ZFEntry テーブルの作成 すべてのコールアウト・ライブラリは、ZFEntry テーブルを定義する必要があり、これにより Caché がコールアウト関数を ロードしてアクセスできるようになります (簡単な例は “コールアウト・ライブラリの概要” を参照してください)。ZFEntry テーブルは ZFBEGIN で始まり ZFEND で終わるマクロ・コードのブロックによって生成されます。これら 2 つのマクロ間 で、関数を公開するごとに 1 回、ZFENTRY マクロを呼び出す必要があります。 各 ZFENTRY 呼び出しは、以下の 3 つの引数をとります。 zfentry(zfname,linkage,entrypoint) ここで、zfname は $ZF 呼び出し内で関数を指定するために使用される文字列、linkage は引数を渡す方法を指定する 文字列、entrypoint は C 関数のエントリ・ポイント名です。 既定では、ZFEntry テーブルは、静的にリンクされている関数にのみ使用できるコードを生成します (詳細は、“静的に リンクされたコールアウト関数” を参照してください)。コールアウト・ライブラリを作成するには、マクロ・コードがライブラリ 関数を見つけるための別のメカニズムを生成するようにするスイッチである #define ZF_DLL 指示文をコードに含める 必要があります。静的ポインタ・テーブルの代わりに、内部 GetZFTable 関数が生成されます。コールアウト・ライブラリが ロードされると、Caché はこの関数を呼び出して後続のライブラリ関数名の検索用にライブラリを初期化します。 注釈 ZFEntry のシーケンス番号 ZFEntry テーブル内のエントリの位置が重要となる場合があります。$ZF(-5) および $ZF(-6) インタフェース (次の章 “コールアウト・ライブラリ関数の呼び出し” で説明します) は、両方ともテーブル内でシーケンス番号 (1 で始まる) を指定することによってライブラリ関数を呼び出します。例えば、$ZF(-6) は以下の呼び出しを使 用して ZFEntry テーブル内の 3 番目の関数を呼び出します。 x = $ZF(-6,libID,3) ここで libID はライブラリ識別子、3 はテーブル内の 3 番目のエントリのシーケンス番号です。 注釈 OpenVMS のみ: ZFPRIV 文 OpenVMS システムでは、ZFENTRY マクロは ZFPRIV で置き換えることができます。これは、特権レベルを指 定する追加パラメータをとります (“特権レベルを上げる ZFPRIV の使用” を参照)。 Caché コールアウト・ゲートウェイの使用法 13 Caché コールアウト・ライブラリの作成 3.2 ZFEntry リンク・オプション 各 ZFENTRY 文 (“ZFEntry テーブルの作成” を参照) では、関数引数が渡される方法を決定する文字列が必要で す。このセクションでは、利用可能なリンク・オプションについて詳細に説明します。 • リンクの概要 — さまざまなリンク・タイプの概要を示し、この章で説明するすべてのリンク・オプションをリストします。 • 数値リンクの使用 — 数値パラメータのリンク・オプションを説明します。 • NULL で終了する文字列を C リンク・タイプで渡す — NULL で終了する文字列のリンク・オプションについて説明 します。 • 計算文字列を B リンク・タイプで渡す — 計算文字配列に ZARRAY 構造を使用するリンクについて説明します。 • Caché の長い文字列を J リンク・タイプで渡す — 計算文字配列に Caché CACHE_EXSTR 構造を使用するリンクに ついて説明します。 • $ZF ヒープの構成 — 文字列パラメータ渡しのメモリ割り当てを制御する Caché システム設定について説明します。 3.2.1 リンクの概要 各 ZFENTRY 文 (“ZFEntry テーブルの作成” を参照) では、引数が渡される方法を説明する文字列が必要です。例 えば、"iP" は、整数と整数へのポインタの 2 つのパラメータを指定します。2 番目の文字は、2 番目の引数が入力と出 力の両方に使用されることを指定するために大文字になっています。コードは、最大で 32 の実パラメータおよび仮パラ メータを持つことができます。 大文字のリンク・タイプを指定する場合 (i を除くすべてのリンク・タイプで許可されている)、入力と出力の両方にこの引 数を使用することができます。1 つの出力引数のみが指定されている場合は、その最終値は関数の返り値として使用さ れます。複数の出力引数が指定されている場合は、すべての出力引数がコンマ区切りの文字列として返されます。 出力引数は入力引数として使用する必要はありません。すべての入力引数の後に出力限定引数を指定する場合、関 数は出力引数のいずれも指定することなく呼び出すことができます (例は、“コールアウト・ライブラリの概要” を参照し てください)。 Caché ObjectScript プログラマの観点からすると、パラメータは入力のみです。実パラメータの値は $ZF 呼び出しによっ て評価され、C ルーチン宣伝内の仮パラメータにリンクされます。C 仮パラメータへの変更は失われるか、または$ZF 返 り値にコピー可能になるかのいずれかです。 ZFENTRY マクロが、仮パラメータを返り値として使用するように指定しない場合は、$ZF 呼び出しは空の文字列 ("") を 返します。リンク宣言は、1 つ以上の出力パラメータを含むことができます。この場合、すべての返り値は単一のコンマ区 切り文字列に変換されます。複数の返り値間に挿入されたコンマと、1 つの返り値内に存在するコンマとを区別する方法 はないため、最後の返り値のみがコンマを含むようにします。 以下のテーブルは、利用可能なオプションを説明しています。 C データ型 Input In/Out メモ int i なし (P を使用) i リンク・タイプは入力のみです。整数タイプを返すには、P (int *) を 使用します。入力引数は数値文字列の場合があります (メモ 1 参照)。 int * p P 入力引数は数値文字列の場合があります (メモ 1 参照)。 double * d D 入力引数は数値文字列の場合があります (メモ 1 参照)。#D を使用し て double * を基数 2 形式で保持します (メモ 2 を参照)。 14 Caché コールアウト・ゲートウェイの使用法 ZFEntry リンク・オプション C データ型 Input In/Out メモ float * f F 入力引数は数値文字列の場合があります (メモ 1 参照)。#F を使用し て float * を基数 2 形式で保持します (メモ 2 を参照)。 char * 1c また はc 1C また はC これは、一般的な C NULL 終了文字列です (メモ 3 を参照)。 unsigned short * 2c また はw 2C また はW これは、C 形式の NULL 終了 UTF-16 文字列です (メモ 3 を参照)。 wchar t * 4c 4C これは、wchar_t 要素のベクトルとして保存される C 形式の NULL 終 了文字列です (メモ 3 および 4 を参照)。 ZARRAYP 1b また はb 1B また はB 最大 32,767 文字の 8 ビット各国語文字列。 ZWARRAYP 2b また はs 2B また はS 最大 32,767 文字の 16 ビット Unicode 文字列。 ZHARRAYP 4b 4B wchar_t によって実装される要素内に保存される、最大 32,767 文字 の Unicode 文字列 (メモ 4 参照)。 CACHE_EXSTR 1j また はj 1J また はJ 8 ビット各国語文字の Caché の長い文字列。 CACHE_EXSTR 2j また はn 2J また はN 16 ビット Unicode 文字の Caché の長い文字列。 CACHE_EXSTR 4j 4J wchar_t 文字の Caché の長い文字列 (メモ 4 参照)。 1. i、p、d、f — 数値引数が指定されると、Caché では文字列の入力引数が許可されます。詳細は、“数値リンクの使 用” を参照してください。 2. #F、#D — 数値を基数 2 浮動小数点形式で保持するには、float * で #F を使用するかまたは double * で #D を使 用します。詳細は、“数値リンクの使用” を参照してください。 3. 1C、2C、4C — このリンクで渡されるすべての文字列は最初の NULL 文字で切り捨てられます。詳細は、“NULL で 終了する文字列を C リンク・タイプで渡す” を参照してください。 4. 4B、4C、4J — wchar_t が一般的に 32 ビットであっても、Caché では 16 ビットのみを使用して各 Unicode 文字を格 納するため、これらのリンクは wchar_t の使用を指定する既存のコードまたはシステム・インタフェースとやり取りする ときにのみ役立ちます。 構造体と引数のプロトタイプ定義 (インターシステムズ内部定義を含む) は、インクルード・ファイル cdzf.h にあります。 注釈 OpenVMS 用の V リンク この章で説明しているリンク・タイプに加えて、OpenVMS システム・サービスを呼び出す際には V リンクを使用 することができます (“システム・サービスでの V リンクの使用” を参照)。 3.2.2 数値リンクの使用 数値リンク・タイプは、以下のデータ型用に提供されています。 Caché コールアウト・ゲートウェイの使用法 15 Caché コールアウト・ライブラリの作成 C データ型 Input In/Out メモ int i なし (P を使 用) i リンク・タイプは入力のみです。整数タイプを返すには、代わりに P を使用します。 int * p P int へのポインタです。 double * d D #D (出力のみ) を使用して double * を基数 2 形式で返します。 float * f F #F (出力のみ) を使用して float * を基数 2 形式で返します。 数値引数が指定されると、Caché では文字列の入力引数が許可されます。文字列が渡されると、先頭の数字が文字列 から解析されて数値が派生します。先頭の数字がない場合は、値 0 が受け取られます。つまり、"2DOGS" は 2.0 とし て受け取られますが、"DOG" は 0.0 として受け取られます。整数の引数は切り捨てられます。例えば、"2.1DOGS" は 2 として受け取られます。詳細は、"Caché ObjectScript の使用法" の “文字列から数値への変換” を参照してくださ い。 注釈 浮動小数点数での精度の保持 出力リンクが F (float *) または D (double *) で指定されている場合、返す数値は Caché の内部基数 10 の数 の形式に変換されます。数値を基数 2 形式で保持するには、float * で #F を使用するかまたは double * で #D を使用します。 入力引数では # 接頭語は許可されていません。変換を回避するには、関数を呼び出す ObjectScript コード 内で $DOUBLE を使用して入力値を作成する必要があり、対応する入力リンクは小文字の f または d として 指定される必要があります。 既定では、Caché は、10 進法で小数を格納します。例えば、数値 1.3 は 13*.10 として格納されます。一方、大半の 高レベル言語は、2 進数の形式で小数を格納します (2 進数と 2 の累乗の積)。引数を f (float *) または d (double *) として記述する場合、Caché は、入力時に 10 進数値を 2 進数値に変換し、出力時に 10 進数値に戻します。この変換 により、値に若干の誤差が生じる可能性があります。 Caché は標準の IEEE 形式の 64 ビット浮動小数点を作成する $DOUBLE 関数をサポートします。これらの数は、精度 を失うことなく外部関数と Caché 間で渡すことができます (外部関数が 64 ビットの double ではなく 32 ビットの float を 使用する場合を除く)。出力では、IEEE 形式の使用は、接頭語 # を F または D の引数タイプへ追加すると、指定でき ます。例えば、"i#D" は整数の入力引数 1 つと、64 ビット浮動小数点出力引数 1 つに引数リストを指定します。 3.2.3 NULL で終了する文字列を C リンク・タイプで渡す このリンク・タイプは、Caché が NULL ($CHAR(0)) 文字を含む文字列を送信しないことがわかっている場合にのみ使用 します。このデータ型を使用する際は、C 関数は、Caché 文字列が長い場合でも、Caché によって渡される文字列を最 初の NULL 文字で切り捨てます。例えば、Caché 文字列 "ABC"_$CHAR(0)_"DEF" は、"ABC" に切り捨てられます。 C データ型 Input In/Out メモ char * 1c または c 1C または C これは、一般的な C NULL 終了文字列です。 unsigned short * 2c または w 2C または W これは、C 形式の NULL 終了 UTF-16 文字列です。 wchar t * 4c 4C これは、wchar_t 要素のベクトルとして保存される C 形式の NULL 終了文字列です。 数値文字列を返すために 3 つすべてのリンク・タイプを使用する短いコールアウト・ライブラリを以下に示します。 16 Caché コールアウト・ゲートウェイの使用法 ZFEntry リンク・オプション C リンクを使用した NULL 終了文字列渡し 以下の 3 つの関数それぞれは、ランダム整数を生成して最大 6 桁の数値文字列に変換し、C リンクを使用し てその文字列を返します。 #define ZF_DLL // Required when creating a Callout library. #include <cdzf.h> #include <stdio.h> #include <wchar.h> // Required for 2-byte and 4-byte strings int get_sample(char* retval) { // 1-byte, null-terminated sprintf(retval,"%d",(rand()%1000000)); return ZF_SUCCESS; } int get_sample_W(unsigned short* retval) { // 2-byte, null-terminated swprintf(retval,6,L"%d",(rand()%1000000)); return ZF_SUCCESS; } int get_sample_H(wchar_t* retval) { // 4-byte, null-terminated swprintf(retval,6,L"%d",(rand()%1000000)); return ZF_SUCCESS; } ZFBEGIN ZFENTRY("GetSample","1C",get_sample) ZFENTRY("GetSampleW","2C",get_sample_W) ZFENTRY("GetSampleH","4C",get_sample_H) ZFEND 3.2.4 計算文字列を B リンク・タイプで渡す cdzf.h コールアウト・ヘッダ・ファイルは、計算文字列構造 ZARRAY、ZWARRAY、および ZHARRAY を定義します。これ らの構造は、文字要素の配列 (それぞれ、8 ビット、16 ビット Unicode、または wchar t) および配列内の要素の数を指 定する整数を含みます。以下はその例です。 typedef struct zarray { unsigned short len; unsigned char data[1]; /* 1 is a dummy value */ } *ZARRAYP; 以下はその説明です。 • len — 配列の長さが格納されます。 • data — 文字データを格納する配列です。要素タイプは、ZARRAY は unsigned char、ZWARRAY は unsigned short、 ZHARRAY は wchar_t です。 B リンクは、3 つの配列構造に対応して、ポインタ型 ZARRAYP、ZWARRAYP、および ZHARRAYP を指定します。 C データ型 Input In/Out メモ ZARRAYP 1b または b 1B または B 8 ビットの最大 32,767 文字を含む各国語文字列。 ZWARRAYP 2b または s 2B または S 16 ビットの最大 32,767 文字を含む Unicode 文字列。 ZHARRAYP 4b 4B 最大 32,767 の wchar_t 文字を含む Unicode 文字列。 返された最大配列サイズは、最大文字列サイズの 32,767 文字です。引数の最大合計長さは、1 文字あたりのバイト数 に依存します (“$ZF ヒープの構成” を参照)。 数値文字列を返すために 3 つすべてのリンク・タイプを使用する短いコールアウト・ライブラリを以下に示します。 Caché コールアウト・ゲートウェイの使用法 17 Caché コールアウト・ライブラリの作成 B リンクを使用した計算文字列渡し 以下の 3 つの関数それぞれは、ランダム整数を生成して最大 6 桁の数値文字列に変換し、B リンクを使用し て文字列を返します。 #define ZF_DLL // Required when creating a Callout library. #include <cdzf.h> #include <stdio.h> #include <wchar.h> // Required for 2-byte and 4-byte strings int get_sample_Z(ZARRAYP retval) { // 1-byte, counted unsigned char numstr[6]; sprintf(numstr,"%d",(rand()%1000000)); retval->len = strlen(numstr); memcpy(retval->data,numstr,retval->len); return ZF_SUCCESS; } int get_sample_ZW(ZWARRAYP retval) { // 2-byte, counted unsigned short numstr[6]; swprintf(numstr,6,L"%d",(rand()%1000000)); retval->len = wcslen(numstr); memcpy(retval->data,numstr,(retval->len*sizeof(unsigned short))); return ZF_SUCCESS; } int get_sample_ZH(ZHARRAYP retval) { // 4-byte, counted wchar_t numstr[6]; swprintf(numstr,6,L"%d",(rand()%1000000)); retval->len = wcslen(numstr); memcpy(retval->data,numstr,(retval->len*sizeof(wchar_t))); return ZF_SUCCESS; } ZFBEGIN ZFENTRY("GetSampleZ","1B",get_sample_Z) ZFENTRY("GetSampleZW","2B",get_sample_ZW) ZFENTRY("GetSampleZH","4B",get_sample_ZH) ZFEND 注釈 複数の値を含む出力引数文字列ではコンマが区切り文字として使用されます。コンマは計算文字列配列の一 部となるため、引数リストの最後にこれらの配列を宣言し、呼び出しごとに 1 つの配列を使用します。 3.2.5 Caché の長い文字列を J リンク・タイプで渡す J リンクは、Caché の長い文字列を渡す方法を提供します。"Caché プログラミング入門ガイド" の “長い文字列演算の サポート” および “長い文字列の制限” を参照してください。長い文字列が既定で有効になります。 C データ型 Input In/Out メモ CACHE_EXSTR 1j また はj 1J また はJ 8 ビット各国語文字の Caché の長い文字列。 CACHE_EXSTR 2j また はn 2J また はN 16 ビット Unicode 文字の Caché の長い文字列。 CACHE_EXSTR 4j 4J wchar_t 文字の Caché の長い文字列。 callin.h ヘッダ・ファイル ("Caché コールイン API の使用法" の “callin.h ヘッダ・ファイル” を参照) は、計算文字列構 造 CACHE_EXSTR を定義します。この構造は、文字要素の配列 (8 ビット、16 ビット Unicode、または wchar t) および 配列内の要素の数を指定する整数を含みます。 18 Caché コールアウト・ゲートウェイの使用法 ZFEntry リンク・オプション typedef struct { unsigned int len; union { Callin_char_t *ch; unsigned short *wch; wchar_t *lch; /* OR unsigned short *lch if } str; } CACHE_EXSTR, *CACHE_EXSTRP; /* length of string */ /* text of the 8-bit string */ /* text of the 2-byte string */ /* text of the 4-byte string */ 4-byte characters are not enabled */ 次の 2 つの Caché コールイン関数 ("Caché コールイン API の使用法" の “コールイン関数リファレンス” を参照) は、 CACHE_EXSTR の作成または削除に使用されます。 • CacheExStrKill — CACHE_EXSTR 文字列に関連付けられているストレージを解放します。 • CacheExStrNew[W][H] — 文字列に対して要求されたストレージの容量を割り当て、CACHE_EXSTR 構造に、構造 の長さおよび構造の値フィールドへのポインタを埋め込みます。 これらの関数の使用方法のデモンストレーションは、以下の例を参照してください。 数値文字列を返すために 3 つすべてのリンク・タイプを使用する短いコールアウト・ライブラリを以下に示します。 J リンク を使用した Caché の長い文字列渡し 以下の 3 つの関数それぞれは、ランダム整数を生成して最大 6 桁の数値文字列に変換し、J リンクを使用して 文字列を返します。 #define ZF_DLL // Required when creating a Callout library. #include <cdzf.h> #include <stdio.h> #include <wchar.h> // Required for 2-byte and 4-byte strings #include <callin.h> // Required for Caché long strings int get_sample_L(CACHE_EXSTRP retval) { // 1-byte, longstring Callin_char_t numstr[6]; size_t len = 0; sprintf(numstr,"%d",(rand()%1000000)); len = strlen(numstr); CACHEEXSTRKILL(retval); if (!CACHEEXSTRNEW(retval,len)) {return ZF_FAILURE;} memcpy(retval->str.ch,numstr,len); // copy to retval->str.ch return ZF_SUCCESS; } int get_sample_LW(CACHE_EXSTRP retval) { // 2-byte, longstring unsigned short numstr[6]; size_t len = 0; swprintf(numstr,6,L"%d",(rand()%1000000)); len = wcslen(numstr); CACHEEXSTRKILL(retval); if (!CACHEEXSTRNEW(retval,len)) {return ZF_FAILURE;} memcpy(retval->str.wch,numstr,(len*sizeof(unsigned short))); return ZF_SUCCESS; } // copy to retval->str.wch int get_sample_LH(CACHE_EXSTRP retval) { // 4-byte, longstring wchar_t numstr[6]; size_t len = 0; swprintf(numstr,6,L"%d",(rand()%1000000)); len = wcslen(numstr); CACHEEXSTRKILL(retval); if (!CACHEEXSTRNEW(retval,len)) {return ZF_FAILURE;} memcpy(retval->str.lch,numstr,(len*sizeof(wchar_t))); // copy to retval->str.lch return ZF_SUCCESS; } ZFBEGIN ZFENTRY("GetSampleL","1J",get_sample_L) ZFENTRY("GetSampleLW","2J",get_sample_LW) ZFENTRY("GetSampleLH","4J",get_sample_LH) ZFEND Caché コールアウト・ゲートウェイの使用法 19 Caché コールアウト・ライブラリの作成 注釈 CACHE_EXSTRP 入力引数の常時削除 前述の例では、CACHEEXSTRKILL(retval) は、メモリから入力引数を削除するために常に呼び出されてい ます。これは、引数が出力に使用されない場合でも常に実行する必要があります。実行しない場合は、メモリ・ リークが発生します。 3.2.6 $ZF ヒープの構成 $ZF ヒープは、すべての $ZF 入力および出力パラメータに割り当てられる仮想メモリ領域です。これは、以下の Caché システム設定によって制御されます。 • ZFString は、1 つの文字列パラメータに対して使用が許可される文字数です。このために実際に必要なバイト数は、 使用している文字が 8 ビット文字か、2 バイトの Unicode 文字か、UNIX® 上の 4 バイト文字かによって異なります。 この設定で許可されている範囲は、0 から 32767 文字です。既定は、0 であり、最大値を使用することを示します。 • ZFSize は、Caché がすべての $ZF 入力および出力パラメータに割り当てる合計バイト数です。この設定で許可され ている範囲は、0 から 270336 バイトです。0 (既定の設定) は、Caché が ZFString の値に基づいて適切な値を計 算することを示します。 以下のように ZFSize (合計バイト数) を ZFString (文字列あたりの最大文字数) に基づいて計算します。 ZFSize = (<bytes per character> * ZFString) + 2050 例えば、ZFString の値が既定の 32767 文字だとします。 • Unicode 2 バイト文字を使用すると、ZFSize の適切な値は (2 * 32767 + 2050) = 67584 バイトになります。 • UNIX® 4 バイト文字を使用すると、ZFSize の適切な値は (4 * 32767 + 2050) = 133118 バイトになります。 これらの設定は、以下のいずれかの場所で変更できます。 • Caché パラメータ・ファイル ("Caché パラメータ・ファイル・リファレンス" の “[config]” セクションの “zfheap” を参 照してください)。 • 管理ポータル ("Caché 追加構成設定リファレンス" の “詳細メモリ設定” にある ZFSize および ZFString のエント リを参照してください)。 3.3 コールアウト・ライブラリの Runup 関数と Rundown 関数 Caché コールアウト・ライブラリは、共有オブジェクトがロードされたとき (runup) またはアンロードされたとき (rundown) に 呼び出されるカスタム内部関数を含むことができます。どちらのケースも引数は渡されません。関数は以下のように使用 されます。 • ZFInit — コールアウト・ライブラリが $ZF(-3)、$ZF(-4,1)、または $ZF(-6) によって最初にロードされたときに呼び出 されます。この関数からの返りコードは、エラーがないことを示すゼロ、もしくはいくつかの障害の存在を示すゼロ以 外の値になります。呼び出しが正常に実行されると、ZFUnload rundown 関数のアドレスが保存されます。 • ZFUnload — コールアウト・ライブラリが $ZF(-3) への呼び出しによってアンロードまたは置換されたとき、あるいは $ZF(-4,2) または $ZF(-4,4) によってアンロードされたときに呼び出されます。プロセスの停止では呼び出されませ ん。エラーが rundown 関数実行中に発生した場合、それ以降、コールアウト・ライブラリのアンロードを許可するた めの呼び出しは無効となります。ZFUnload からの返り値は現在無視されています。 コールアウト・ライブラリを構築する際、リンクを確立するプロシージャの間に、ZFInit と ZFUnload 記号を明示的にエクス ポートする必要がある場合があります。 20 Caché コールアウト・ゲートウェイの使用法 トラブルシューティング 3.4 トラブルシューティング ほとんどすべてのルーチンをコールアウト・ゲートウェイで呼び出すことができますが、そうしなければならないという意味 ではありません。これは、数学関数で使用するのが最適であり、Caché I/O でうまく処理されない外部デバイスへのイン タフェース、または Caché インタフェースが存在しないシステム・サービスの場合に効果的に使用することができます。 以下の動作によって重大な問題が発生する可能性があります。 • 自身に属していないメモリへのアクセス メモリ・アクセス違反は、Caché によって処理され、Caché 内のバグとして扱われます。 • トラップによって処理されるその他のエラーの発生 トラップによって処理されるエラー (ほとんどのプラットフォーム上でのゼロによる除算など) も Caché 内のバグとして 扱われます。 • プロセスの優先度の変更 Caché は、Caché を実行している他のプロセスと相互作用する必要があります。優先度を下げると、上げるのと同様 に問題が発生する場合があります。例えば、プロセスが CPU を解放する直前にスピン・ロックで保護されたリソース を取得することを考えてみましょう。優先度が低すぎると、高い優先度のその他のプロセスがリソースを奪い合い、事 実上、スピン・ロックを解除できるようにするプロセスの実行を妨げます。 • 中断のマスク インターロックを実装するために中断を短時間マスクする場合がありますが、中断をマスクしたままにしないように十 分注意する必要があります。 • 削除できないリソースを作成または開く ファイルを開いて malloc を使用してメモリを割り当てることは問題ありません。それらのリソースはプロセスの終了時 に閉じられるかまたは解放されます。2 番目のスレッドを作成すると、2 番目のスレッドが Caché プロセスの終了前 に正常に終了することを保証できないため、2 番目のスレッドは作成しないでください。 • opaque 以外のオブジェクトを ObjectScript 以外のコードで返す コード内のメモリのブロックを malloc して、それを読み取るために $VIEW(address,−3,size) を使用できると考 えないでください。また、ObjectScript 以外のコードに malloc ブロックを戻さないでください。コードは opaque ハン ドルを返し、後で opaque ハンドルを受け取った時に使用する前に有効であることを確認する必要があります。 • プロセスの終了 exit だけを呼び出すことはしないでください。常に ZF_SUCCESS または ZF_FAILURE のいずれかと共に返しま す (これらの値の実装は Caché プラットフォーム間で異なることに留意してください)。 • exec のいずれかのバージョンの呼び出しによる終了 子プロセス内で fork してから exec を呼び出すことはできますが、必ず親は Caché に返り、子プロセスは Caché に 返らないようにしてください。これは、OpenVMS で LIB$DO_COMMAND を使用する際にも当てはまります。 • プロセスでのエラー処理の振る舞いの変更 OpenVMS および Windows のみが、現在の内部フレームのローカル・エラー処理を確立することを許可するため、 この点においては、これらのシステムは UNIX® システムよりも有利です。 Caché コールアウト・ゲートウェイの使用法 21 4 コールアウト・ライブラリ関数の呼び出し コールアウト・ゲートウェイは、実行時に Caché コールアウト・ライブラリをロードし、そのライブラリから関数を呼び出すた めに使用できる 3 つの異なるインタフェースを提供します。この章では、以下の項目について説明します。 • コールアウト・ライブラリのインタフェース — 3 つのコールアウト・ライブラリのインタフェースの概要とその使用方法を 説明します。 • 単純なライブラリ関数呼び出しでの $ZF(-3) の使用 — 一度に 1 つのライブラリをロードして使用する便利な方法を 提供する $ZF(-3) について説明します。 • システム ID によるライブラリへのアクセスでの $ZF(-5) の使用 — ライブラリをロードして使用するより効率的な方法 を提供する $ZF(-5) および関連する関数について説明します。 • ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用 — ハードコード化されたライブラリ・ファイル 名を指定するのではなくユーザ作成のインデックス・テーブルを読み取ることによってライブラリをロードする点を除 いて $ZF(-5) と類似のインタフェースを提供する $ZF(-6) および関連する関数について説明します。 注釈 共有ライブラリとコールアウト・ライブラリ このドキュメントでは、共有ライブラリという用語は、動的にリンクされたファイル (Windows の DLL ファイル、 UNIX® および関連オペレーティング・システムの SO ファイル、または OpenVMS の共有可能イメージ・ファイ ル) を示します。コールアウト・ライブラリは、コールアウト・ゲートウェイへのフックを含む共有ライブラリであり、 多様な $ZF 関数が実行時にロードして、その関数を呼び出すことができるようにします。コールアウト・ライブラ リを記述する手順については、“Caché コールアウト・ライブラリの作成” を参照してください。 4.1 コールアウト・ライブラリのインタフェース $ZF(-3)、$ZF(-5)、および $ZF(-6) 関数はすべて、コールアウト・ライブラリ関数を呼び出すために使用されますが、これ らの関数のそれぞれが、独自の強さと弱さを持っています。 $ZF(-3) インタフェース $ZF(-3) 関数はコールアウト・ライブラリをロードして、ライブラリ・ファイル・パスと関数名を指定することによって ライブラリ関数を呼び出します。使用は簡単ですが、仮想メモリ内で使用できるのは一度に 1 つのライブラリの みです。その他のインタフェースとは異なり、ライブラリ関数を呼び出す前に初期化を行う必要がありません。詳 細は、“単純なライブラリ関数呼び出しでの $ZF(-3) の使用” を参照してください。 Caché コールアウト・ゲートウェイの使用法 23 コールアウト・ライブラリ関数の呼び出し $ZF(-5) インタフェース $ZF(-5) 関数は、コールアウト・ライブラリおよびライブラリ関数にシステム定義の数値識別子を指定することに よってコールアウト・ライブラリ関数を呼び出します。これは同時にいくつかのライブラリをメモリ内に保持するこ とができ、個々の関数呼び出しは $ZF(-3) よりも効率的です。$ZF(-5) インタフェースもユーティリティ関数 $ZF(-4,1)、$ZF(-4,2)、および $ZF(-4,3) を含みます。これは、ライブラリおよび関数 ID を取得するため、およ びライブラリをロードまたはアンロードするために使用する必要があります。詳細は、“システム ID によるライブ ラリへのアクセスでの $ZF(-5) の使用” を参照してください。 $ZF(-6) インタフェース $ZF(-6) インタフェースは、コールアウト・アプリケーションが実際のライブラリ・ファイル名をハードコード化する ことなくライブラリをロードできる点を除いて $ZF(-5) と類似しています。代わりに、別のインデックス・テーブル がその情報を含み、各インデックス・ライブラリに一意のユーザ定義インデックス番号が指定されます。インデッ クス・テーブルが Caché のインスタンス内で定義されると、そのインスタンス内のすべてのコールアウト・アプリ ケーションで利用可能になります。$ZF(-6) 関数は、インデックス番号および関数 ID を指定することによってラ イブラリ関数を呼び出します。必要に応じて、自動的にインデックス・テーブルを読み取って指定されたライブラ リをロードします。$ZF(-6) インタフェースもユーティリティ関数 $ZF(-4,4) ~ $ZF(-4,8) を含みます。これは、ラ イブラリをアンロードするため、およびインデックスを作成または維持するために使用する必要があります。詳細 は、“ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用” を参照してください。 4.2 単純なライブラリ関数呼び出しでの $ZF(-3) の使用 $ZF(-3) 関数は、コールアウト・ライブラリをロードして、そのライブラリから指定した関数を実行するために使用されます。 $ZF(-3) は、1 つのライブラリのみを使用している場合、またはライブラリのロードのオーバーヘッドを懸念して十分な呼 び出しを行っていない場合に、もっとも役立ちます。これにより、ライブラリ名、関数名、および関数引数のコンマ区切り のリストを指定することによって、任意の利用可能なライブラリ関数を呼び出すことができます。 result = $ZF(-3, library_name[, function_name[, arguments]]) 指定されたライブラリは、$ZF(-3) への前の呼び出しによってロードされていない場合にロードされます。一度にロードで きるのは 1 つのライブラリのみです。後続の $ZF(-3) 呼び出しが、別のライブラリを指定すると、古いライブラリはアンロー ドされ、新しいライブラリが置き換わります。このライブラリは、後続の $ZF(-3) 呼び出しが同じライブラリを指定する限り ロードされたままになります。ライブラリがロードされた後に、後続の呼び出しで、ライブラリ名を NULL 文字列 ("") として 指定できます。 関数を呼び出すことなくライブラリをロードまたはアンロードすることができます。新しいライブラリをロードするには、ライ ブラリ名のみを指定します。新しいライブラリをロードせずに現在のライブラリをアンロードするには、NULL 文字列のみ を指定します。いずれのケースでも、$ZF(-3) は、ロードまたはアンロードが成功したかどうかを示すステータス・コードを 返します。 以下の ObjectScript コードは、2 つの異なるライブラリそれぞれから 2 つの異なる関数を呼び出し、現在のライブラリを アンロードします。 24 Caché コールアウト・ゲートウェイの使用法 システム ID によるライブラリへのアクセスでの $ZF(-5) の使用 ライブラリのロードおよび関数の呼び出しでの $ZF(-3) の使用 // define Callout library paths set libOne = "c:\intersystems\cache\bin\myfirstlibrary.dll" set libTwo = "c:\intersystems\cache\bin\anotherlibrary.dll" //load and call SET result1=$ZF(-3,libOne,"FuncA",123) // loads libOne and calls FuncA SET result2=$ZF(-3,"","FuncB","xyz") // calls FuncB from same library //load, then call with null name SET status=$ZF(-3,libTwo) // unloads libOne, loads libTwo SET result1=$ZF(-3,"","FunctionOne","arg1") SET result2=$ZF(-3,"","FunctionTwo","argA", "argB") //unload SET status=$ZF(-3,"") // unloads libTwo • 簡便性のため、ライブラリ名は文字列 libOne および libTwo に割り当てられます。 • $ZF(-3) への最初の呼び出しは、コールアウト・ライブラリ libOne をロードし、そのライブラリから関数 FuncA を呼び出します。 • 2 番目の呼び出しは、ライブラリ名に NULL 文字列を指定して、現在ロードされている libOne を再び使用 することを示し、そのライブラリから関数 FuncB を呼び出します。 • $ZF(-3) への 3 番目の呼び出しは、ライブラリ名 libTwo のみを指定します。これにより、libOne がアンロー ドされ、libTwo がロードされますが、ライブラリ関数は呼び出されません。この呼び出しは libTwo が正常に ロードされたかどうかを示すステータス・コードを返します。 • 4 番目と 5 番目の呼び出しは、ライブラリ関数 FunctionOne および FunctionTwo を現在ロードされている libTwo から呼び出します。 • 最後の $ZF(-3) 呼び出しは、ライブラリ関数を呼び出さず、ライブラリ名に NULL 文字列を指定します。こ れにより、libTwo がアンロードされ、新しいライブラリはロードされません。この呼び出しは libTwo が正常に アンロードされたかどうかを示すステータス・コードを返します。 この章の以下のセクションでは、一度に複数のライブラリをロードできる $ZF 関数について説明します。これらの関数は $ZF(-3) と競合しません。$ZF(-3) は、いつでもそれ自体のライブラリのプライベート・コピーをロードおよびアンロードし ているかのように使用することができます。 4.3 システム ID によるライブラリへのアクセスでの $ZF(-5) の使 用 $ZF(-5) 関数は、ライブラリ関数の呼び出しにシステム定義のライブラリおよび関数の識別子を使用します。ユーティリ ティ関数 $ZF(-4,1)、$ZF(-4,2) および $ZF(-4,3) は、必要な識別子を取得し、ライブラリをロードまたはアンロードする ために使用されます。複数のライブラリを同時に開くことができます。$ZF(-3) とは異なり (“単純なライブラリ関数呼び出 しでの $ZF(-3) の使用” を参照)、$ZF(-5) は、ライブラリをロードして識別子を取得するためにユーティリティ関数が呼 び出されるまで使用できません。ただし、各ライブラリは、一度のみロードが必要であり、各ライブラリまたは関数識別子 は一度のみ生成する必要があります。多くのライブラリ関数呼び出しを行うアプリケーションでは、これにより処理のオー バーヘッドが大幅に削減できます。 このセクションでは、以下の $ZF 関数について説明しています。 • $ZF(-5) — システム定義のライブラリおよび関数の識別子によって参照されるコールアウト・ライブラリ関数を呼び出 します。 • $ZF(-4,1) — ファイル名によって指定されるコールアウト・ライブラリをロードし、それに対するシステム定義の ID 値 を返します。 Caché コールアウト・ゲートウェイの使用法 25 コールアウト・ライブラリ関数の呼び出し • $ZF(-4,2) — ライブラリ ID によって指定されるコールアウト・ライブラリをアンロードします。 • $ZF(-4,3) — 指定されたライブラリ ID および関数名の関数 ID 値を返します。 $ZF(-4,1) および $ZF(-4,3) 関数は、コールアウト・ライブラリのロードとライブラリおよび関数識別子の取得に使用され ます。$ZF(-4,1) の構文は以下のとおりです。 lib_id = $ZF(-4,1,lib_name) // get library ID ここで lib_name は、共有ライブラリ・ファイルのフルネームとパスであり、lib_id は、返されるライブラリ ID です。$ZF(-4,3) の構文は以下のとおりです。 func_id=$ZF(-4,3,lib_id, func_name) // get function ID ここで lib_id は、ライブラリ ID、func_name は、ライブラリ関数名、func_id は、返される関数 ID 値です。 以下の ObjectScript コードはコールアウト・ライブラリ mylibrary.dll をロードしてライブラリ ID を取得し、"MyFunction" の関数 ID を取得して $ZF(-5) を使用して呼び出します。 $ZF(-5) を使用したライブラリのロードと関数の呼び出し set libID = $ZF(-4,1,"C:\calloutlibs\mylibrary.dll") set funcID = $ZF(-4,3,libID, "MyFunction") set x = $ZF(-5,libID, funcID, "arg1") 識別子が定義されると、ライブラリは $ZF(-4,2) によってアンロードされるまでロードされたままになり、その識別子は $ZF(-4,1) または $ZF(-4,3) へのさらなる呼び出しを行うことなく使用することができます。これにより、複数のライブラリ からの関数が何度も呼び出される際の処理オーバーヘッドが大幅に削減されます。 以下の ObjectScript コードは 2 つの異なるライブラリをロードし、ロング・ループで両方のライブラリから関数を呼び出し ます。inputlibrary.dll 内の関数は、データ・サンプルを取得し、outputlibrary.dll 内の関数は、データをプロットおよび保 存します。 複数ライブラリおよび多くの関数の呼び出しでの $ZF(-5) の使用 Method GraphSomeData(loopsize As %Integer=100000) As %Status { // load libraries and get system-defined ID values set InputLibID = $ZF(-4,1,"c:\intersystems\cache\bin\inputlibrary.dll") set OutputLibID = $ZF(-4,1,"c:\intersystems\cache\bin\outputlibrary.dll") set fnGetSample = $ZF(-4,3,InputLibID,"GetSample") set fnAnalyzeData = $ZF(-4,3,OutputLibID,"AnalyzeData") set fnPlotPoint = $ZF(-4,3,OutputLibID,"PlotPoint") set fnWriteData = $ZF(-4,3,OutputLibID,"WriteData") // call functions from each library until we have 100000 good samples do { set sample = $ZF(-5,InputLibID,fnGetSample) set normalized = $ZF(-5,OutputLibID,fnAnalyzeData,sample) if (normalized>"") { set flatdata($INCREMENT(count)) = normalized } } while (count<loopsize) set status = $ZF(-4,2,InputLibID) //unload "inputlibrary.dll" // plot results of the previous loop and write to output for point=1:1:loopsize { set list = $ZF(-5,OutputLibID,fnPlotPoint,flatdata(point)) set x = $PIECE(list,",",1) set y = $PIECE(list,",",2) set sc = $ZF(-5,OutputLibID,fnWriteData,flatdata(point),x,y,"outputfile.dat") } set status = $ZF(-4,2,OutputLibID) //unload "outputlibrary.dll" quit 0 } • $ZF(-4,1) への呼び出しでは、コールアウト・ライブラリ inputlibrary.dll および outputlibrary.dll を仮想メモ リ内にロードし、それらのシステム定義のライブラリ ID を返します。 26 Caché コールアウト・ゲートウェイの使用法 ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用 • $ZF(-4,3) への呼び出しでは、ライブラリ ID および関数名を使用してライブラリ関数の ID を取得します。 返された関数 ID は実際は ZFEntry テーブル・シーケンス番号 (前の章の “ZFEntry テーブルの作成” を参照) です。 • 最初のループでは、$ZF(-5) を使用して各ライブラリから関数を呼び出します。 – inputlibrary.dll からの GetSample() 関数は、未指定のソースから生のデータを読み取ります。 – outputlibrary.dll からの AnalyzeData() 関数は、生のデータを正規化するかまたは拒否して、空の文字 列を返します。 – 正規化された各サンプルは、flatdata(count) (ここで Caché 関数 $INCREMENT への最初の呼び出し が count を作成し、1 に初期化する) に保存されます。 既定では、ループは 100000 のサンプルを取得します。両方のライブラリがロードされメモリ内に残ってい るため、2 つの異なるライブラリ間を切り替えるための処理オーバーヘッドはありません。 • 最初のループが終了した後に、ライブラリ inputlibrary.dll は必要なくなるため、$ZF(-4,2) が呼び出されて アンロードされます。ライブラリ outputlibrary.dll は、メモリ内に残ります。 • 2 番目のループは、配列 flatdata からの各サンプルを処理し、未指定の場所にあるファイルに書き込みま す。 • – ライブラリ関数 PlotPoint() は、サンプルを読み取り、プロットされる座標を含むコンマ区切り文字列を 返します (ライブラリ関数から複数の出力パラメータが返される方法の説明は、“リンクの概要” を参照 してください)。 – Caché $PIECE 関数は、座標値 x および y を文字列から抽出するために使用されます。 – ライブラリ関数 WriteData() は、サンプルおよび座標を outputfile.dat ファイルに保存します。これは、 グラフを出力するために他のアプリケーションで使用されます。 2 番目のループが終了した後に、$ZF(-4,2) が再び呼び出されてライブラリ outputlibrary.dll がアンロード されます。 以下のセクションでは、$ZF(-6) インタフェースについて説明します。これは、$ZF(-5) インタフェースと同じ仮想メモリ領 域内にライブラリをロードします。 4.4 ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用 $ZF(-6) 関数は、グローバルに定義されたインデックスを介してコールアウト・ライブラリへのアクセスを可能にする、共有 ライブラリ・ファイルの場所を認識していないアプリケーションでも使用可能な効率的なインタフェースを提供します。ユー ザ定義のインデックス・テーブルは、ライブラリ ID 番号と対応するライブラリ・ファイル名で構成されるキーと値のペアを 格納します。指定されたライブラリ ID と関連付けられているファイル名は、ライブラリ・ファイルの名前が変更されたときま たは再配置されたときに変更できます。この変更は、インデックス番号でライブラリをロードするアプリケーションに対して 透過的です。その他の $ZF 関数は、インデックス・テーブルを作成して維持するため、および $ZF(-6) によってロードさ れたライブラリをアンロードするために提供されています。 このセクションでは、以下の $ZF 関数について説明しています。 • $ZF(-6) — ユーザ指定のインデックス番号によって参照されるコールアウト・ライブラリから関数を呼び出します。ライ ブラリがまだロードされていない場合には、自動的にロードします。 • $ZF(-4,4) — インデックス番号によって指定されるコールアウト・ライブラリをアンロードします。 Caché コールアウト・ゲートウェイの使用法 27 コールアウト・ライブラリ関数の呼び出し • $ZF(-4,5) および $ZF(-4,6) — システム・インデックス・テーブル内でエントリを作成または削除します。システム・イ ンデックスは、Caché のインスタンス内のすべてのプロセスでグローバルに利用可能になります。 • $ZF(-4,7) および $ZF(-4,8) — プロセス・インデックス・テーブル内でエントリを作成または削除します。プロセス・テー ブルは、システム・テーブルの前に検索されるため、プロセス内でシステム全体の定義をオーバーライドするために 使用します。 $ZF(-6) インタフェースは、$ZF(-5) (“システム ID によるライブラリへのアクセスでの $ZF(-5) の使用” を参照) によっ て使用されるものと類似していますが、以下の点が異なります。 • $ZF(-6) を使用するには、先にライブラリ・インデックス・テーブルを作成する必要があります。ライブラリ・インデック ス値は、ユーザ定義であり、実行時に変更またはオーバーライドできます。 • ライブラリ名は、インデックス内に格納され、ライブラリをロードするアプリケーションによって定義される必要はありま せん。ライブラリ・ファイルの名前と場所は、インデックス値によって、ライブラリをロードする依存アプリケーションに 影響を与えることなくインデックス内で変更することができます。 • ライブラリをロードする別の $ZF 関数はありません。代わりに、ライブラリはその関数の一つを呼び出す最初の $ZF(-6) 呼び出しによって自動的にロードされます。 • 開発者は既にライブラリ関数 ID (ZFEntry テーブル内の順序によって決定される) を知っていると見なされるため、 指定された名前およびライブラリ・インデックス値に対して関数 ID を返す $ZF 関数はありません。 以下の例は、$ZF(-6) インタフェースの使用方法を示しています。最初の例は、システム・インデックス・テーブル内にラ イブラリ ID を定義し、2 番目の例 (別のアプリケーションから呼び出される場合がある) は、ライブラリ ID を使用してライ ブラリ関数を呼び出します。 $ZF(-4,5) および $ZF(-4,6) を使用したシステム・インデックス・エントリの定義 この例では、システム・インデックス・テーブル内で 100 を mylibrary.dll のライブラリ ID として設定します。その 番号に既に定義が存在している場合は、削除されて置き換えられます。 set LibID = 100 set status = $ZF(-4,6,LibID) // clear any old entries with this ID value set status = $ZF(-4,5,LibID,"C:\calloutlibs\mylibrary.dll") // set system ID • LibID は、開発者によって選択されたインデックス番号です。この番号は、予約済みのシステム値 1024 ~ 2047 を除くゼロよりも大きい任意の整数です。 • システム・インデックスが既にインデックス番号 100 を使用するエントリを含んでいる場合は、$ZF(-4,6) へ の呼び出しによって削除されます。インデックス・エントリは上書きできないため、推奨される方法です。 • $ZF(-4,5) への呼び出しは、インデックス番号 100 をライブラリ・ファイル mylibrary.dll に関連付けます。 ライブラリ ID がシステム・インデックス・テーブルに定義されると、Caché の現在のインスタンス内のすべてのプロセスで グローバルに利用可能になります。 $ZF(-6) を使用した関数の呼び出し この例では、前の例で作成されたシステム・インデックス・テーブルを使用します。$ZF(-6) を使用してライブラリ をロードし、ライブラリ関数を呼び出して、ライブラリをアンロードします。このコードは、システム・インデックス内 でライブラリ ID を定義したのと同じアプリケーションから呼び出す必要はありません。 set set set set • LibID = 100 // library ID in system index table FuncID = 2 // second function in library ZFEntry table x = $ZF(-6,LibID, FuncID, "arg1") // call function 2 status = $ZF(-4,4,LibID) // unload the library LibID は、システム・インデックス内に定義されているライブラリ ID です。このアプリケーションは、ライブラリ 関数を使用するためにライブラリ名またはパスを知っている必要はありません。 28 Caché コールアウト・ゲートウェイの使用法 ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用 • FuncID は、ライブラリ LibID の ZFEntry テーブルにリストされている 2 番目の関数の関数 ID です。開発 者はライブラリ・コードへのアクセス権を持っていると見なされます — $ZF(-6) インタフェースは、ライブラリ 関数名を指定することによって、この番号を取得するための関数を持っていません。 • $ZF(-6) への呼び出しは、100 をライブラリ ID として指定し、2 を関数 ID として指定し、"arg1" を関数 に渡す引数として指定します。この呼び出しは、コールアウト・ライブラリ mylibrary.dll がロードされていない 場合にはロードし、ZFEntry テーブルにリストされている 2 番目の関数を呼び出します。 • $ZF(-4,4) への呼び出しは、ライブラリをアンロードします。$ZF(-6) によってロードされる各ライブラリは、プ ロセスが終了するまでまたは $ZF(-4,4) によってアンロードされるまで常駐したままになります。 4.4.1 ライブラリ関数のカプセル化での $ZF(-6) インタフェースの使用 $ZF(-5) インタフェースの例のように動作する (この章で前述した “システム ID によるライブラリへのアクセスでの $ZF(5) の使用” を参照) $ZF(-6) インタフェースの例を記述するのは簡単ですが、これは $ZF(-6) を使用した利点を示しま せん。代わりに、このセクションでは、エンド・ユーザがコールアウト・ライブラリの内容または場所について知らずにまっ たく同じタスクを実行できるようにする ObjectScript クラスを提供します。 $ZF(-5) の例は、コールアウト・ライブラリ inputlibrary.dll および outputlibrary.dll から関数を呼び出して、いくつかの実 験データを処理してグラフの描画に使用できる 2 次元の配列を生成しました。このセクションの例は、同じタスクを以下 の ObjectScript コードを使用して実行します。 • クラス User.SystemIndex — システム・インデックス・テーブル内でエントリを定義するために使用されるファイル名お よびインデックス番号をカプセル化します。 • クラス User.GraphData — 両方のライブラリから関数をカプセル化するメソッドを提供します。 • メソッド GetGraph() — User.GraphData メソッドを呼び出すエンド・ユーザ・プログラムの一部です。このメソッドのコー ドは、$ZF(-5) の例とまったく同じタスクを実行しますが、$ZF 関数を直接呼び出しません。 User.SystemIndex クラスを使用すると、コールアウト・ライブラリを使用するアプリケーションがインデックス番号またはファ イルの場所をハードコード化することなく、システム・インデックス・エントリを作成してアクセスすることができます。 ObjectScript クラス User.SystemIndex Class User.SystemIndex Extends %Persistent { /// Defines system index table entries for the User.GraphData libraries ClassMethod InitGraphData() As %Status { // For each library, delete any existing system index entry and add a new one set sc = $ZF(-4,6,..#InputLibraryID) set sc = $ZF(-4,5,..#InputLibraryID,"c:\intersystems\cache\bin\inputlibrary.dll") set sc = $ZF(-4,6,..#OutputLibraryID) set sc = $ZF(-4,5,..#OutputLibraryID,"c:\intersystems\cache\bin\outputlibrary.dll") quit 0 } Parameter InputLibraryID = 100; Parameter OutputLibraryID = 200; } • InitGraphData() メソッドは、User.GraphData のライブラリをシステム・インデックス・テーブルに追加します。 これは、Caché のインスタンスが開始されたときに自動的に呼び出され、ライブラリがインスタンス内のすべ てのプロセスで利用可能になります。 • InputLibraryID および OutputLibraryID クラス・パラメータが利用可能になり、依存アプリケーションが (以 下の例の User.GraphData の Init() メソッドによって示されているように) インデックス値をハードコード化す る必要がなくなります。 User.GraphData クラスを使用すると、エンド・ユーザが実際のコールアウト・ライブラリについて何も知らなくてもライブラ リ関数を呼び出すことができます。 Caché コールアウト・ゲートウェイの使用法 29 コールアウト・ライブラリ関数の呼び出し ObjectScript クラス User.GraphData Class User.GraphData Extends %Persistent { /// Gets library IDs and updates the system index table for both libraries. Method Init() As %Status { set InLibID = ##class(User.GraphDataIndex).%GetParameter("InputLibraryID") set OutLibID = ##class(User.GraphDataIndex).%GetParameter("OutputLibraryID") quit ##class(User.SystemIndex).InitGraphData() } Property InLibID As %Integer [Private]; Property OutLibID As %Integer [Private]; /// Calls function "FormatData" in library "inputlibrary.dll" Method FormatData(rawdata As %Double) As %String { quit $ZF(-6,..InLibID,1,rawdata) } /// Calls function "RefineData" in library "outputlibrary.dll" Method RefineData(midvalue As %String) As %String { quit $ZF(-6,..OutLibID,1,midvalue) } /// Calls function "PlotGraph" in library "outputlibrary.dll" Method PlotGraph(datapoint As %String, xvalue As %Integer) As %String { quit $ZF(-6,..OutLibID,2,datapoint,xvalue) } /// Unloads both libraries Method Unload() As %String { set sc = $ZF(-4,4,..InLibID) // unload "inputlibrary.dll" set sc = $ZF(-4,4,..OutLibID) // unload "outputlibrary.dll" quit 0 } } • Init() メソッドは、inputlibrary.dll および outputlibrary.dll のシステム・インデックス・エントリを設定または更 新する User.SystemIndex からクラス・メソッドを呼び出します。また、ライブラリ ID の現在の値も取得しま す。このクラスの開発者は引き続き、コールアウト・ライブラリ・コードについて知っている必要がありますが、 システム・インデックスへの将来の変更は透過的になります。 • メソッド FormatData()、RefineData()、および PlotGraph() はそれぞれ、1 つのライブラリ関数への呼び出し をカプセル化します。これらは無条件 $ZF 関数呼び出しのみを含むため、Caché コンパイラはこれらのメ ソッドを元の $ZF 呼び出しと同じ速さで実行するように最適化することができます。 • Unload() メソッドは、ライブラリのいずれか、または両方をアンロードします。 以下の例は、エンド・ユーザが User.GraphData 内でメソッドを使用する方法を示しています。GetGraph() メソッドは、 コールアウト・ライブラリを使用して $ZF(-5) インタフェース例内の GraphSomeData() メソッドとまったく同じタスクを実行 しますが (この章で前述している “システム ID によるライブラリへのアクセスでの $ZF(-5) の使用” を参照)、$ZF 関数 を直接呼び出しません。 メソッド GetGraph() Method GetGraph(loopsize As %Integer = 100000) As %Status { // Get an instance of class GraphData and initialize the system index set graphlib = ##class(User.GraphData).%New() set sc = graphlib.Init() // call functions from both libraries repeatedly // each library is loaded automatically on first call for count=1:1:loopsize { set midvalue = graphlib.FormatData(^rawdata(count)) set flatdata(count) = graphlib.RefineData(midvalue) } // plot results of the previous loop for count=1:1:loopsize { set x = graphlib.PlotGraph(flatdata(count),0) set y = graphlib.PlotGraph(flatdata(count),x) set ^graph(x,y) = flatdata(count) } 30 Caché コールアウト・ゲートウェイの使用法 ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用 //return after unloading all libraries loaded by $ZF(-6) set status = graphlib.Unload() quit 0 } • User.GraphData クラスは graphlib としてインスタンス化され、Init() メソッドがシステム・インデックスを初期 化するために呼び出されます。システム・インデックスは Caché のインスタンス内のすべてのプロセスに対 して初期化する必要があるのは一度のみのため、このメソッドをここで呼び出す必要はありません。 • 最初のループは、間接的に $ZF(-6) を使用して、各ライブラリから関数を呼び出し、$ZF(-6) は、各ライブ ラリを最初に必要な際に自動的にロードします。ライブラリ inputlibrary.dll は、FormatData() への最初の呼 び出しでロードされ、outputlibrary.dll は、RefineData() への最初の呼び出しでロードされます。 • 2 番目のループは、PlotGraph() を既にロードされているライブラリ outputlibrary.dll から呼び出します。 • Unload() への呼び出しは、両方のライブラリで間接的に $ZF(-4,4) を呼び出します。 4.4.2 テストでのプロセス・インデックスの使用 前に述べたように、プロセス・インデックス・テーブルは、システム・インデックス・テーブルの前に検索されるため、プロセ ス内でシステム全体の定義をオーバーライドするために使用できます。以下の例では、前のセクションで使用されたライ ブラリのうちの 1 つの新しいバージョンをテストするために使用されるプロセス・インデックスを作成します。 "inputlibrary.dll" の新しいバージョンをテストするためのプロセス・インデックスの使用 // Initialize the system index and generate output from standard library set testlib = ##class(User.GraphData).%New() set sc = testlib.Init() set sc = graphgen.GetGraph() // get 100000 data items by default merge testgraph1 = ^graph kill ^graph // create process index and test new library with same instance of testproc set sc = $ZF(-4,4,100) // unload current copy of inputlib set sc = $ZF(-4,8) // delete existing process index, if any set sc = $ZF(-4,7,100, "c:\testfiles\newinputlibrary.dll") // override system index set sc = graphgen.GetGraph() merge testgraph2 = ^graph // Now compare testdata1 and testdata2 • 前の例のように、最初の 3 行で、このテスト・コードはシステム・インデックスを初期化してグラフを生成しま す。グラフは、inputlibrary.dll の標準バージョン (ID 値 100 を持つシステム・インデックス・エントリによって 識別される) を使用してプロットされ、testgraph1 に保存されています。 • $ZF(-4,4) への呼び出しにより inputlibrary.dll がアンロードされます。これはシステム・インデックス・テーブ ル内でライブラリ ID 100 で識別されます。 • $ZF(-4,8) は、ライブラリ ID を指定せずに呼び出され、現在のプロセス・インデックス・テーブル内のすべ てのエントリが削除されることを示します。 • $ZF(-4,7) への呼び出しは、テスト・ライブラリ newinputlibrary.dll に 100 をライブラリ ID として設定するプ ロセス・インデックス・テーブルにエントリを追加します。これにより、システム・インデックス内のその ID のエ ントリがオーバーライドされます。ライブラリ ID 100 は、inputlibrary.dll ではなく newinputlibrary.dll をポイ ントするようになります。 • GetGraph() が User.GraphData の同じインスタンスを使用して再び呼び出されます。標準バージョンの inputlibrary.dll がアンロードされる以外は何も変更されないため、GetGraph() は新しいバージョンのライブ ラリをロードして使用します。その後、テストではグラフ testgraph1 と testgraph2 が比較され、両方のバー ジョンで同じ結果を生成することが確認されます。 Caché コールアウト・ゲートウェイの使用法 31 5 静的にリンクされたコールアウト関数 このドキュメント内の前の章では、実行時にロードできるスタンドアロン・コールアウト・ライブラリを作成する方法を説明し ました。ただし、コールアウト関数をカスタム・バージョンの Caché に静的にリンクして常に利用できるようにすることもで きます。関数が Caché にリンクされているため、関数を呼び出すときにコールアウト・ライブラリを明示的にロードしたり、 ライブラリを指定する必要はありません。 以下の項目について説明します。 • 静的にリンクされたコールアウト関数の呼び出し — 静的にリンクされた関数を使用する利点を説明します。 • Windows でのカスタム CACHE.EXE ファイルの作成 — Visual Studio を使用してコールアウト・コードをカスタム・ バージョンの Caché にリンクする方法を説明します。 • UNIX®、Linux、または OS-X でのカスタム CACHE.EXE ファイルの作成 — コールアウト・コードをカスタム・バージョ ンの Caché にリンクする方法を説明します。 • OpenVMS でのカスタム CZF.EXE ファイルの作成 — OpenVMS バージョンの Caché に組み込まれるコールアウト 関数の標準セットを変更する方法を説明します。静的リンクは、OpenVMS では異なる意味合いを持ちますが、同じ 利点があります。 5.1 静的にリンクされたコールアウト関数の呼び出し 静的にリンクされたコールアウト関数の呼び出し規則は、動的ライブラリの規則と異なります。以下はその例です。 $ZF(-3,"mylibrary","MYFUNC",args...) 上記は以下のようになります。 $ZF("MYFUNC",args...) 関数が静的にリンクされているため、サブ関数番号およびライブラリ名 (この例の、-3,"mylibrary" など) を指定する 必要はありません。 Caché コールアウト・ゲートウェイの使用法 33 静的にリンクされたコールアウト関数 5.2 Windows でのカスタム CACHE.EXE ファイルの作成 #define ZF_DLL 指示文を含まないという点を除いてコールアウト・ライブラリのコードと同一のコードを含む mycallouts.c という名前のファイルがあることを前提とします (“Caché コールアウト・ライブラリの作成” を参照)。これをコンパイルおよ びリンクする手順は、以下のとおりです。 外部関数のコンパイルまたはアセンブル Windows で mycallouts.c をコンパイルするには、以下のコマンドを使用します。 cl -c mycallouts.c これにより、Caché にリンク可能な mycallouts.obj という出力ファイルを生成します。 オブジェクト・ファイルと Caché オブジェクト・ファイルを、新しいバージョンの Caché にリンクします。 以下の方法で、$ZF で使用する C 関数をリンクします。 1. <install-dir>\Dev\Cache\callin ディレクトリ (<install-dir> はユーザの構成のルート・ディレクトリです) で構 築を実行するか、必要なファイルのコピーを使ってプライベート・ディレクトリを作成するかのいずれかです。 以下のファイルをリンクします。 • cache.obj • main.obj • shdir.obj • clink.bat プライベート・ディレクトリで mycallouts.c をコンパイルし、生成された mycallouts.obj ファイルにこれらの ファイルをリンクします。 2. czf.obj ファイルを mycallouts.obj に置き換えます。 3. プロジェクトを構築します。これにより、プライベート・ディレクトリに cache.exe ファイルを生成します。別々 のファイルに C 関数を配置している場合、それらを別々にコンパイルし、mycallouts.c で宣言する必要が あります。しかし、そこには組み込みません。“Unresolved externals...” というメッセージが表示された場 合、他のライブラリを組み込む必要があります。組み込むファイルについてサポートが必要な場合、インター システムズのサポート窓口までお問い合わせください。 4. <install-dir>\bin (<install-dir> はユーザの構成のルート・ディレクトリ) に現在インストールされている cache.exe のバージョンを保存します。これにより、そのファイルをリストアできます。 Caché をシャットダウンし、Caché の実行可能ファイルを新しいファイルに置き換えます。 以下の方法で、Caché を Windows に再インストールします。 1. キューブ・メニューの [Caché の停止] を使用して、Caché を停止します。 2. cache.exe ファイルをプライベート・ディレクトリから <install-dir>/bin にコピーします。<install-dir> は、ユー ザ構成のルート・ディレクトリです。 Caché を再起動すると、関数が使用可能になります。 Caché の再起動 Windows では、Caché キューブから Caché を開始します。 34 Caché コールアウト・ゲートウェイの使用法 UNIX®、Linux、または OS-X でのカスタム CACHE.EXE ファイルの作成 現在の Caché バージョンは C 関数を組み込んでいます。 以下の方法で、(Windows 上の) Caché の管理者ディレクトリにある Caché をオリジナル・バージョンに戻します。 1. Caché をシャットダウンします。 2. 保存されたオリジナルの cache.exe ファイルを <install-dir>\bin にコピーします。<install-dir> は、構成の ルート・ディレクトリです。 5.3 UNIX®、Linux、または OS-X でのカスタム CACHE.EXE ファ イルの作成 #define ZF_DLL 指示文を含まないという点を除いてコールアウト・ライブラリのコードと同一のコードを含む mycallouts.c という名前のファイルがあることを前提とします (“Caché コールアウト・ライブラリの作成” を参照)。これをコンパイルおよ びリンクする手順は、以下のとおりです。 外部関数のコンパイルまたはアセンブル mycallouts.c をコンパイルするには、以下のコマンドを使用します。 cc -c mycallouts.c オブジェクト・ファイルと Caché オブジェクト・ファイルを、新しいバージョンの Caché にリンクします。 以下の方法で、$ZF で使用する C 関数をリンクします。 1. <install-dir>/source/Cache ディレクトリで構築を実行するか、必要なファイルのコピーでプライベート・ディ レクトリを作成するかのいずれかを実行します。以下のファイルをリンクします。 • cache.o (Caché 配布キットで提供されています) • main.o (Caché 配布キットで提供されています) • shdir.o (shdir.c を手動でコンパイルする必要があります) • mycallouts.o (プライベート・ネームスペースに作成されます) 2. プロジェクトを構築します。“Unresolved externals” メッセージを受け取った場合、他のライブラリを組み込 む必要があります。組み込むファイルがわからない場合、インターシステムズのサポート窓口までお問い合 わせください。別々のファイルに C 関数を置く場合、それらを別々にコンパイルし、mycallouts.c で宣言す る必要があります。しかし、そこには組み込みません。 3. /cachesys/bin/ に (あるいは任意の場所のインストール・ディレクトリに) Caché のバージョンを保存します。 これにより、必要に応じて Caché をリストアできます。 Caché をシャットダウンし、Caché の実行可能ファイルを新しいファイルに置き換えます。 Caché 実行可能プログラムを置換するには、以下の手順に従います。 1. 以下を実行し、Caché をシャットダウンします。 ccontrol stop <configname> <configname> は、Caché のインストール名です。 2. cache ファイルをプライベート・ディレクトリから <install-dir>/bin/ にコピーします。<install-dir> は、ユーザ の構成のルート・ディレクトリです。 Caché コールアウト・ゲートウェイの使用法 35 静的にリンクされたコールアウト関数 Caché の再起動 cstart スクリプトを使用して、または以下を呼び出して Caché を開始します。 ccontrol start <configname> <configname> は、起動したい Caché のインストール名です。 以下の方法で、Caché システム管理者のディレクトリにある Caché をオリジナル・バージョンに戻します。 1. Caché をシャットダウンします。 2. 保存されたオリジナルの cache ファイルを <install-dir>/bin にコピーします。<install-dir> は、ユーザ構成 のルート・ディレクトリです。 5.4 OpenVMS でのカスタム CZF.EXE ファイルの作成 既定では、OpenVMS 用の Caché は、既にいくつかのコールアウト関数を含む CZF.EXE という名前のイメージを含みま す (標準 CZF.EXE 関数の説明は、“DSM に代わる $ZF 関数呼び出し” を参照してください)。 OpenVMS 下では (この章で説明しているその他のオペレーティング・システムとは異なり)、コールアウト・ライブラリはカ スタム・バージョンの cache.exe に静的にリンクされません。代わりに、標準バージョンの CZF.EXE をカスタム・バージョ ンと置き換えます (“Caché コールアウト・ライブラリの作成” を参照)。標準バージョンのソース・コードは、カスタム・バー ジョンがそれを含めることができるように提供されています。 CZF.C のコンパイル 外部関数と Caché にリンクする CZF.OBJ ファイルを準備するには、DCL プロンプトから以下のコマンドを発行 することによって CZF.C をコンパイルします。 $ CC CZF.C 注釈 OpenVMS のみ: CZF.M64 のアセンブル CZF.M64 ファイルを使用している場合は、この時点でアセンブルして (“CZF.M64 の使用” を参照) CZF.OBJ を作成します。 オブジェクト・ファイルのリンクによる CZF.EXE の作成 CZFBUILD.com ファイルを使用して、外部関数にリンクします。CZFBUILD.com を編集し、リンクするファイルを 追加します。編集前の CZFBUILD.com は以下のようになります。 LINK/NOTRACE/MAP=CZF/SHAREABLE=CZF SYS$INPUT:/OPTIONS CLUSTER=CZF,,,CZF GSMATCH=ALWAYS,0,0 SYMBOL_VECTOR=(ZFE=DATA) 1. CZFBUILD.COM を編集し、CZF.OBJ と各外部オブジェクト・ファイルを組み込みます。CZF ファイルで定 義した外部関数を含む各ファイル名を、CZFBUILD.COM の 2 行目に追加します。例えば、関数が abc.obj と xyz.obj という 2 つのファイルにある場合、編集後の 2 行目は以下のようになります。 CLUSTER=CZF,,,CZF,ABC,XYZ 2. DCL プロンプトで CZFBUILD.COM を実行します。これにより、CZF.EXE ファイルを生成します。 36 Caché コールアウト・ゲートウェイの使用法 OpenVMS でのカスタム CZF.EXE ファイルの作成 注釈 コードが #include "callin.h" を実行し、Caché にコールバックする場合、Caché 共有可能イメー ジにもリンクする必要があります。 • Alpha システムでは、CACHE /sharable を使用します。 • Itanium システムでは、CKERNEL /sharable を使用します。 コマンドは、コマンド行ではなく、オプション・ファイル内で発行する必要があります。 Caché のシャットダウンと CZF.EXE のインストール 以下のコマンドを発行します。 CCONTROL STOP <configname> <configname> は、シャットダウンしたい Caché のインストール名です。 Caché 実行可能プログラムを共有メモリからアンロードし、CZF.EXE を置き換える必要があります。以下はその コードです。 CCONTROL UNLOAD <configname> <configname> は、アンロードしたい Caché のインストール名です。 プライベート・ディレクトリから <install-dir>:[bin] サブディレクトリに CZF.EXE をコピーします。以下はそのコード です。 COPY CZF.EXE DKA0:[CACHESYS.BIN] Caché の再起動 Caché を再起動するには、以下のコマンドを発行します。 CCONTROL START <configname> <configname> は、起動したい Caché のインストール名です。 Caché コールアウト・ゲートウェイの使用法 37 6 UNIX® に関する特別な考慮事項 システム呼び出しの中には、open、read、write、close、ioctl、pause などのシグナルをプロセスが受け取ると、失敗するも のがあります。 関数がこれらのシステム呼び出しを使用する場合、実際のエラー、Ctrl-C、再起動を必要とする呼び出しと区別できるよ うに、注意してコードを記述する必要があります。生成された小規模な関数セットにより、非同期イベントのチェックや、 $ZF に新規のアラーム・ハンドラを設定できます。 6.1 その他のコールアウト・シグナル処理 関数の宣言は、cdzf.h に組み込まれます。 • int sigrtclr(); — 再試行フラグを消去します。sigrtchk() を使用する前に一度呼び出す必要があります。 • int dzfalarm(); — 新規 SIGALRM ハンドラを構築します。 $ZF にエントリする際に、前のハンドラが自動的に保存されます。終了すると、自動的にリストアされます。ユーザ・ プログラムで、他のシグナル処理を変更しないでください。 • int sigrtchk(); — 非同期イベントをチェックします。これは、open、close、read、write、ioctl、または pause の いずれかのシステム呼び出しが失敗した場合や、プロセスがシグナルを受け取ったときに失敗する呼び出しがある 場合に、必ず呼び出す必要があります。ユーザの次の動作を示すコードを返します。 – -1 — シグナルではありません。入出力エラーを調べてください。errno 変数の内容を参照してください。 – 0 — 他のシグナルです。割り込みが生じた時点から処理を再開してください。 – 1 — SIGINT/SIGTERM。SIGTERM "return 0" で $ZF を終了します。Caché は、これらのシグナルを適切に取 得します。 デバイスを制御する通常の $ZF 関数は、以下のように記述します。 if ((fd = open(DEV_NAME, DEV_MODE)) < 0) { Set some flags Call zferror return 0; } プロセスがシグナルを受け取ると、open システム呼び出しは失敗する可能性があります。通常、これはエラーではない ため、処理を再開できます。しかし、シグナルによっては他の処理が必要な場合もあります。すべての可能性を考慮す るために、以下の C コードを使用することを検討してください。 Caché コールアウト・ゲートウェイの使用法 39 UNIX® に関する特別な考慮事項 sigrtclr(); while (TRUE) { if (sigrtchk() == 1) return 1 or 0; if ((fd = open(DEV_NAME, DEV_MODE)) < 0) { switch (sigrtchk()) { case -1: /* This is probably a real device error */ Set some flags Call zferror return 0; case 0: /* A innocuous signal was received. Restart. */ continue; case 1: /* Someone is trying to terminate the job. */ Do cleanup work return 1 or 0; } } else break; } /* Code to handle the normal situation: open() system call succeeded */ dzfalarm 経由の場合を除き、シグナル・ハンドラを設定してはいけません。 40 Caché コールアウト・ゲートウェイの使用法 7 OpenVMS に関する特別な考慮事項 $ZF を使用して、OpenVMS システム・サービスを呼び出すことができます。CZF.M64 という名前のファイルにある、Caché ObjectScript 以外の各ルーチンにインタフェースを定義します。また、$ZF を使用して、OpenVMS システム・サービス・ ルーチンを呼び出し、DCL コマンド・プロシージャやその他の高水準言語のルーチンを呼び出すこともできます。 以下の項目について説明します。 • CZF.M64 の使用 — コールアウト・コードの作成では C が優先言語ですが、.M64 マクロ・ファイルを使用することも できます。 • 特権レベルを上げる ZFPRIV の使用 — コールアウト関数に呼び出し元の通常の特権レベルだけでなく、SHARE 以外のすべての特権を与える ZFPRIV 文について説明します。 • システム・サービスでの V リンクの使用 — "v" リンク・タイプで OpenVMS 記述子を渡すことによって、OpenVMS シ ステム・サービスおよびライブラリ・ルーチンを呼び出す方法を説明します。 • DSM に代わる $ZF 関数呼び出し — OpenVMS システムに付属している組み込み CZF.EXE コールアウト・ライブラ リのコンテンツを説明します。 7.1 CZF.M64 の使用 コールアウト・コードを記述する優先言語は C ですが (“Caché コールアウト・ライブラリの作成” で説明されているように CZF.C ファイルを作成)、マクロ・ファイル (CZF.M64) を使用することもできます。C コンパイラがある場合、CZF.C を使用 します。それ以外の場合、CZF.M64 を使用します。両方を使用することができません。 CZF.M64 ファイルを使用する際は、.SHOW コマンドと .END コマンドの間に、ZFENTRY 文のみを入力します。この文 は、以下の形式にする必要があります。 ZFENTRY CALLNAME=name,LINKNAME=fname,ARGS=atype,PRIVS=priv • CALLNAME — $ZF 関数呼び出しで、Caché が外部関数を呼び出す名前です。 • LINKNAME — ユーザ記述の外部関数のエントリ・ポイント名です。CZF.C で使用する ZFENTRY 文のエントリ・ポイ ント引数に相当します。 • ARGS— どのように引数を渡すかを記述した文字列です。CZF.C で使用する ZFENTRY 文の argtypes 引数に相当 します (“ZFENTRY の argtypes” を参照)。 構造体と引数のプロトタイプ定義は、インクルード・ファイル cdzf.h にあります。インターシステムズの追加の内部定 義もまた、ここで宣言されています。 Caché コールアウト・ゲートウェイの使用法 41 OpenVMS に関する特別な考慮事項 • PRIVS — 関数を上位特権レベルで実行させるには、“YES” を入力します。呼び出し関数と同じ特権レベルで関数 を実行させるには、“NO” を入力します。 呼び出し形式が異なっても、これは C プログラムで使用される ZFENTRY 文と基本的に同じです (“ZFEntry テーブル の作成” を参照)。 CZF.M64 のアセンブル CZF.M64 をアセンブルするため、以下のコマンドを DCL プロンプトから発行します。 $ MAC /ALPHA CZF.M64 7.2 特権レベルを上げる ZFPRIV の使用 ZFENTRY 文は、呼び出しプロセスの特権レベルで実行します。これに SHARE 特権以外のすべての特権を与える場 合、ZFPRIV 文で外部関数を記述することができます。ZFPRIV 文は、名前と以下の引数リストの最後に追加されている 引数 "privileges" 以外は、ZFENTRY 文と同じ形式です。 ZFPRIV("name","argtypes",entrypoint,privileges) privileges 引数は、以下のいずれかになります。 • PRIV — 関数は上位特権レベルで実行します。 • NOPRIV — 関数は、呼び出しプロセスの特権レベルで実行します。 czf.c ファイルを OpenVMS とその他のシステム (例えば、UNIX® および NT) 間で変更せずに移動できるようにするた めに、これらのマクロには以下の効果があります。 • OpenVMS の ZFENTRY では、呼び出し元の通常の特権レベルで実行する $ZF 関数を定義します。これは、$ZF 関数が UNIX® で動作する方法です。 • ZFPRIV では、プログラマが $ZF 関数を呼び出し元の特権レベルで実行するか、またはプロセスが Caché 内で持 つ上位特権レベル (SHARE 以外のすべての特権) で実行するかを指定できます。UNIX® では、すべての $ZF 関 数が呼び出し元のレベルで実行されるため、この関数は ZFENTRY と同一です。 7.3 71 システム・サービスでの V リンクの使用 OpenVMS システム・サービスとライブラリ・ルーチンの呼び出しに対応するため、OpenVMS 記述子を "v" リンク・タイプ を使用して渡すことができます。 struct dsc$descriptor s * v V OpenVMS のみ: OpenVMS システム・サービスを呼び出すときに 使用します。 ZF_FAILURE および ZF_SUCCESS の実装返り値は、プラットフォームによって異なります。これは一般的なシステム呼 び出しに対応するためです。UNIX® では、返り値がゼロの場合は成功と考えられ、ゼロ以外の場合は失敗です。OpenVMS では、奇数値の場合に成功と考えられ、偶数値は失敗と考えられます。実際の失敗値は、Caché ObjectScript プログラ マには提供されません。これは、^SYSLOG ユーティリティを使用して調査することができます。 この例では、OpenVMS 関数 LIB$TRIM_FILESPEC を Caché ObjectScript に公開します。ObjectScript から、次の呼び 出しが使用可能になります。 SET newfilespec=$ZF("TRIM FILESPEC",oldfilespec,width) 42 Caché コールアウト・ゲートウェイの使用法 DSM に代わる $ZF 関数呼び出し 次のように ZENTRY マクロを使用して単純に定義できれば便利です。 ZFENTRY("TRIM_FILESPEC", "vVp", LIB$TRIM_FILESPEC) 残念ながら、CZF インタフェースは 32 の実パラメータをそれが呼び出すすべての関数に渡します。32 の実パラメータ よりも少ない場合は、それらのパラメータに対して NULL が渡されます。LIB$TRIM_FILESPEC は、多くのライブラリお よびシステム関数と同様に実パラメータの数をカウントするため、簡単なラッパ関数を提供する必要があります。 #ifdef __VMS ZFENTRY("TRIM_FILESPEC","viV",trim_filespec) #endif 簡単なラッパ関数は次のとおりです。 関数 trim_filespec #ifdef __VMS int trim_filespec(struct dsc$descriptor_s*oldfilespec,int width,struct dsc$descriptor_s*newfilespec){ short int resultwidth; int s; if(width> ZFString)return ZF_FAILURE; s= LIB$TRIM_FILESPEC(oldfilespec,newfilespec,&width,&resultwidth); newfilespec->dsc$w_length= resultwidth; return s; } #endif 7.4 DSM に代わる $ZF 関数呼び出し このセクションでは、DSM VMS システム・サービスの Zcall 関数をエミュレートするための $ZF 関数の引数として提供で きる、Caché 提供の (内部) 関数について説明します。これらの関数は、標準 CZF.EXE コールアウト・イメージに含まれ ます。このイメージのカスタマイズの詳細は、“OpenVMS でのカスタム CZF.EXE ファイルの作成” を参照してください。 以下の内部関数について説明します。 • GETJPI — ジョブおよびプロセス情報を取得します。 • GETDVI — デバイス特性を取得します。 • GETSYI — システム情報を取得します。 • SETSYM — DCL シンボル値を設定します。 • GETSYM — DCL シンボル値を返します。 • DELSYM — DCL シンボル値を削除します。 • CRELOG — 論理名を作成します。 • TRNLNM — 論理名を変換します。 • DELLOG — 論理名を削除します。 • GETUAI — アカウントの承認パラメータを返します。 • GETMSG — ステータス・コードのメッセージ・テキストを返します。 • SETPRN — 呼び出しプロセスの名前を設定します。 • SETPRI — プロセスのベース優先度を設定します。 • OPCOM — オペレータにメッセージを送信します。 • MOUNT — デバイスをマウントします。 Caché コールアウト・ゲートウェイの使用法 43 OpenVMS に関する特別な考慮事項 • DISMOUNT — デバイスをディスマウントします。 • DIRECTORY — 既定のディレクトリを返します。 • PARSE — ファイル名を解析します。 • GETFILE — ファイル情報を返します。 7.4.1 $ZF 内部関数 内部関数はすべて、関数名とその後に続くその他のパラメータのみを指定することによって $ZF で呼び出すことができ ます。以下は、GETUAI を関数として使用する例です。 SET x = $ZF("GETUAI","FRED","USERNAME") 注釈 ここでは、関数名はすべて大文字で表記されていますが、実際には大文字と小文字は区別されません。 7.4.1.1 GETJPI ジョブおよびプロセス情報を返します。 SET x = $ZF("GETJPI",pid,item) SET x = $ZF("GETJPI",procname,item) パラメータ : • pid — プロセス ID (10 進数) • item — 返すプロセス情報の項目コード • procname — プロセス名 (pid の代わりに使用) GETJPI の項目コード ACCOUNT DFPFC IMAGECOUNT PHDFLAGS TMBU APTCNT DFWSCNT IMAGNAME PID TQCNT ASTACT DIOCNT IMAGPRIV PPGCNT TQLM ASTCNT DIOLM JOBPRCCNT PRCCNT TT_ACCPORNAM ASTEN DIRIO JOBTYPE PRCLM TT_PHYDEVNAM ASTLM EFCS LOGINTIM PRCNAM UAF_FLAGS AUTHPRI EFCU MASTER_PID PRI UIC AUTHPRIV EFWM MAXDETACH PRIB USERNAME BIOCNT ENQCNT MAXJOBS PROC_INDEX VIRTPEAK BIOLM ENQLM MEM PROCPRIV VOLUMES BUFIO EXCVEC MODE SCHED_POLICY VP_CONSUMER BYTCNT FAST_VP_SWITCH MSGMASK SHRFILLM VP_CPUTIM BYTLM FILCNT NODENAME SITESPEC WSAUTH CLINAME FILLM NODE_CSID SLOW_VP_SWITCH WSAUTHEXT 44 Caché コールアウト・ゲートウェイの使用法 DSM に代わる $ZF 関数呼び出し CPU_ID FINALEXC NOD_VERSION STATE WSEXTENT CPULIM FREP0VA OWNER STS WSPEAK CPUTIM FREP1VA PAGEFLTS STS2 WSQUOTA CREPRC FREPTECNT PAGFILCNT SWPFILLOC WSSIZE FLAGS GPGCNT PAGFILLOC TABLENAME CURPRIV GRP PGFLQUOTA TERMINAL 7.4.1.2 GETDVI デバイス特性を返します。 SET x = $ZF("GETDVI",devname,item,flag) パラメータ : • devname — 物理デバイス名、または物理デバイス名と同等の論理デバイス名 • item — 返すデバイス情報の項目コード • flag — 1 は 1 次的な特性、2 は 2 次的な特性、既定値は 2 です。 GETDVI の項目コード ACPTYPE EXISTS PID TT_AUTOBAUD TT_MODHANGUP ALL FOD RCK TT_AVO TT_NOBRDCST ALLDEVNAM FOR RCT TT_BLOCK TT_NOECHO ALLOCLASS FREEBLOCKS REC TT_BRDCSTMBX TT_NOTYPEAHD ALT_HOST_AVAIL FULLDEVNAM RECSIZ TT_CRFILL TT_OPER ALT_HOST_NAME GEN REFCNT TT_DECCRT TT_PAGE ALT_HOST_TYPE HOST_AVAIL REMOTE_DEVICE TT_DECCRT2 TT_PASTHRU AVL HOST_COUNT RND TT_DIALUP TT_PHYDEVNAM CCL HOST_NAME ROOTDEVNAM TT_DISCONNECT TT_PRINTER CLUSTER HOST_TYPE RTM TT_DMA TT_READSYNC CONCEALED IDV SDI TT_DRCS TT_REGIS CYLINDERS LOCKID SECTORS TT_EDIT TT_REMOTE DEVBUFSIZ LOGVOLNAM SERIALNUM TT_EDITING TT_SCOPE DEVCHAR MAXBLOCK SERVED_DEVICE TT_EIGHTBIT TT_SECURE DEVCHAR2 MAXFILES SHR TT_ESCAPE TT_SETSPEED DEVCLASS MBX SPL TT_FALLBACK TT_SIXEL DEVDEPEND MEDIA_ID SPLDEVNAM TT_HALFDUP TT_SYSPWD DEVDEPEND2 MEDIA_NAME SQD TT_HANGUP TT_TTSYNC Caché コールアウト・ゲートウェイの使用法 45 OpenVMS に関する特別な考慮事項 DEVLOCKNAM MEDIA_TYPE STS TT_HOSTSYNC TT_WRAP DEVNAM MNT SWL TT_INSERT UNIT DEVSTS MOUNTCNT TRACKS TT_LFFILL VOLCOUNT DEVTYPE NET TRANSCNT TT_LOCALECHO VOLNAM DIR NEXTDEVNAM TRM TT_LOWER VOLNUMBER DMT ODV TT_ACCPORNAM TT_MBXDSABL VOLSETMEM DUA OPCNT TT_ALTYPEAHD TT_MECHFORM VPROT ELG OPR TT_ANSICRT TT_MECHTAB WCK ERRCNT OWNUIC TT_APP_KEYPAD TT_MODEM 7.4.1.3 GETSYI システム情報を返します。 SET x = $ZF("GETSYI",item,csid[,nodename]) パラメータ : • item — 引用符付きの文字列として指定される、返すシステム・パラメータ値の項目キーワード・コード • csid — 情報を取得するクラスタ・メンバのノード CSID (クラスタ・ノード ID) パラメータ。 すべてのクラスタ・ノードを検索する場合は -1 を指定します。csid に-1 を指定した以降の各呼び出しで は、クラスタ内の次のノードの item キーワード情報が返されます。すべてのノードの順次処理が完了する と、空文字列 ("") が返されます。csid に -1 以外の値を指定すると、ノードへの順次アクセスが終了しま す。 オプションの nodename パラメータを指定する場合は (プレースホルダとして) 0 を指定します。 • nodename — オプション — 引用符付きの文字列として指定されるクラスタ・ノード。クラスタ・ノードは nodename または csid によって指定できます。クラスタ・ノードを nodename によって指定するときは、csid に値 0 を指 定します。 46 Caché コールアウト・ゲートウェイの使用法 DSM に代わる $ZF 関数呼び出し GETSYI の項目コード ACTIVECPU_CNT CLUSTER_FTIME FREE_GBLPAGES PAGEFILE_FREE PQL_MFILLM ARCHFLAG CLUSTER_MEMBER FREE_GBLSECTS PAGEFILE_PAGE PQL_MENQLM ARCH_NAME CLUSTER_NODES GBLPAGES PQL_DWSDEFAULT SCSNODE ARCH_TYPE CLUSTER_QUORUM GBLPAGFIL PQL_DWSEXTENT SPTREQ AVAILCPU_CNT CPU GBLSECTIONS PQL_DWSQUOTA SRPCOUNTV BALSETCNT CONTIG_GBLPAGES LOCKIDTBL PQL_MWSDEFAULT SWAPFILE_FREE BJOBLIM CPUTYPE LOCKIDTBL_MAX PQL_MWSEXTENT SWAPFILE_PAGE BOOTTIME DECIMAL_EMULATED MAXPROCESSCNT PQL_MWSQUOTA VERSION CHARACTER_EMULATED D_FLOAT_EMULATED MAXSYSGROUP PQL_MASTLM VIRTUALPAGECNT CLUSTER_EVOTES HW_MODEL NODENAME PQL_MBYTLM WSMAX CLUSTER_FSYSID HW_NAME NODE_CSID PQL_MDIOLM 7.4.1.4 SETSYM 特定の値に DCL シンボルを設定します。DCL シンボルはローカル、グローバルのどちらでもかまいません。SETSYM は NULL 文字列を返します。 SET x = $ZF("SETSYM",symbol,value,flag) パラメータ : • symbol — 設定する DCL シンボル • value — DCL シンボルの値 • flag — 1 はローカル、2 はグローバル、既定値は 1 です。 7.4.1.5 GETSYM 指定された DCL シンボルの値を返します。DCL シンボルはローカル、グローバルのどちらでもかまいません。flag 値の 1 を使用して、シンボル・タイプを決定できます。DCL 値は、SETSYM 関数によって設定されます。 SET x = $ZF("GETSYM",symbol[,flag]) パラメータ : • symbol — 値を返す DCL シンボル • flag — オプション — ブーリアン値。1 を指定すると、未定義シンボルには 0、ローカル・テーブルには 1、 グローバル・テーブルには 2 を返します。0 を指定すると、シンボル値を返します。既定値は 0 です。 7.4.1.6 DELSYM 指定された DCL シンボルの値を削除します。DCL シンボルはローカル、グローバルのどちらでもかまいません。DCL 値は、SETSYM 関数によって設定されます。 SET x = $ZF("DELSYM",symbol,flag) Caché コールアウト・ゲートウェイの使用法 47 OpenVMS に関する特別な考慮事項 パラメータ : • symbol — 削除する DCL シンボル • flag — 1 はローカル、2 はグローバル、既定値は 1 です。 7.4.1.7 CRELOG 指定されたモードの指定された論理名テーブルに論理名を作成します。既定では、type=USER モードおよび table= プ ロセスの論理名テーブルです。CRELOG は NULL 文字列を返します。 SET x = $ZF("CRELOG",logname,value[,type[,table]]) パラメータ : • logname — 作成する論理名 • value — 論理名と同等の文字列 • type — オプション — 定義するテーブル・モード。使用できる値の詳細は以下のとおりです。既定は USER モード。 • table — オプション — ユーザ定義の論理名テーブルの名前。type=TABLE の場合、table 値が必要です。 既定はプロセスの論理名テーブル。 使用可能な type の値は、以下のとおりです。 • USER = プロセス・テーブル/USER モード • SUPERVISOR または PROCESS = プロセス・テーブル/Supervisor モード • JOB = ジョブ・テーブル — LNM$JOB • GROUP = グループ・テーブル — LNM$GROUP • SYSTEM = システム・テーブル — LNM$SYSTEM • TABLE = ユーザ定義の論理名テーブルの名前 7.4.1.8 TRNLNM 論理名を変換し、同等の名前文字列または要求された属性を返します。一致が検出されない場合、TRNLNM は NULL 文字列を返します。 SET x = $ZF("TRNLNM",logname,table,index,acmode,trans,item) パラメータ : • logname — 変換する論理名 • table — ユーザ定義の論理名テーブルの名前。既定はプロセスの論理名テーブル。 • index — 複数変換の場合の論理名のインデックス • acmode — アクセス・モード。使用可能な値は、USER、SUPERVISOR、EXECUTIVE、および KERNEL。 • trans — 大文字/小文字変換のタイプ。利用可能な値は CASE_BLIND および CASE_SENSITIVE。 • item — 返す論理名に関する情報のタイプ。使用可能な値は、ACCESS_MODE、CONCEALED、CONFINE、 CRELOG、LENGTH、MAX_INDEX、NO_ALIAS、TABLE、TABLE_NAME、TERMINAL、および VALUE。 48 Caché コールアウト・ゲートウェイの使用法 DSM に代わる $ZF 関数呼び出し 7.4.1.9 DELLOG 指定された論理名テーブルの論理名を削除します。 SET x = $ZF("DELLOG",logname,type,table) パラメータ : • logname — 削除する論理名 • type — 論理名のタイプ • table — ユーザ定義の論理名テーブルの名前。既定はプロセスの論理名テーブル。 7.4.1.10 GETUAI 特定の OpenVMS アカウントの承認パラメータの値を返します。 SET x = $ZF("GETUAI",account,item) パラメータ : • account — アカウント名 • item — 項目コード GETUAI の項目コード ACCOUNT DFWSCNT LASTLOGIN_N PGFLQUOTA UIC ASTLM DIOLM LGICMD PRCCNT USERNAME BIOLM ENQLM MAXACCTJOBS PRI WSEXTENT BYTLM FILLM MAXDETACH PRIV WSQUOTA DEFDEV FLAGS MAXJOBS QUEPRI DEFDIR JTQUOTA OWNER SHRFILLM DEF_PRIV LASTLOGIN_I PBYTLM TQCNT 7.4.1.11 GETMSG 指定されたステータス・コードに対応するメッセージ・テキストを返します。 SET x = $ZF("GETMSG",code) パラメータ : • code — エラーのステータス・コード 7.4.1.12 SETPRN 呼び出し元のプロセスの名前を、指定された OpenVMS プロセス名に設定します。 SET x = $ZF("SETPRN",pname) パラメータ : • pname — 有効な OpenVMS プロセス名 Caché コールアウト・ゲートウェイの使用法 49 OpenVMS に関する特別な考慮事項 7.4.1.13 SETPRI 指定されたプロセスのベース優先度を設定します。対象プロセスは CACHE イメージを実行している必要があります。 SET x = $ZF("SETPRI",pri,pid) パラメータ : • pri — 0 から 15 までの整数 (0 と 15 を含む) で指定されるプロセスのベース優先度 • pid — プロセス ID (10 進数) 7.4.1.14 OPCOM 指定されたメッセージをオペレータのターミナルに送信します。その結果、NULL 文字列を返します。 SET x = $ZF("OPCOM",msg) パラメータ : • msg — オペレータのターミナルに送信するメッセージ文字列 7.4.1.15 MOUNT 指定されたデバイスをマウントします。この関数は、LIB$SPAWN を呼び出して、DCL コマンドの MOUNT を発行します。 SET x = $ZF("MOUNT",devnam,label,options,lognam) パラメータ : • devnam — デバイス名 • label — デバイス・ラベル • options — DCL ディクショナリに指定されている 1 つ以上のマウント・オプション • lognam — デバイスに割り当てる論理名 7.4.1.16 DISMOUNT 指定されたデバイスをディスマウントします。この関数は、LIB$SPAWN を呼び出して、DCL コマンドの DISMOUNT を 発行します。 SET x = $ZF("DISMOUNT",devnam,options) パラメータ : • devnam — デバイス名 • options — DCL ディクショナリに指定されている 1 つ以上のディスマウント・オプション 7.4.1.17 DIRECTORY 現在の OpenVMS 既定ディレクトリを返します。また、オプションとして、OpenVMS 既定ディレクトリを指定されたディレク トリに設定します。 SET x = $ZF("DIRECTORY",dir) 50 Caché コールアウト・ゲートウェイの使用法 DSM に代わる $ZF 関数呼び出し パラメータ : • dir — 新しいディレクトリ名 7.4.1.18 PARSE 指定されたファイル名を解析し、解析されたファイル名を返します。PARSE は RMS $PARSE サービスを呼び出します。 SET x = $ZF("PARSE",filename,defname,relname,keyword,flag) パラメータ : • filename — 解析するファイル名 • defname — 既定のファイル名 • relname — 関連付けられたファイル名 • keyword — 解析されたファイル名から返すフィールド値を指定します。使用可能な値は、NODE、DEVICE、 DIRECTORY、NAME、TYPE、および VERSION。 • flag — I/O チェックを行うかどうかを指定するフラグ。1 は I/O チェックを行いません、0 は I/O チェック を行います。既定値は 0 です。 7.4.1.19 GETFILE 指定されたファイルに関する情報を返します。この関数は、同じキーワードを使用して、F$FILE_ATTRIBUTES 字句関 数をエミュレートします。GETFILE は、OpenVMS の標準フォーマットで UIC を返し、True を 1、False を 0 として返し ます。 SET x = $ZF("GETFILE",filename,keyword) パラメータ : • filename — ファイルの名前 • keyword — 対象ファイルから返す属性を指定します。 GETFILE のキーワード ALQ DEQ GBC NOK RVN BDT DID IBS ORG SIZ BKS DVI LRL PRO UIC BLS EDT LVL PVN WCK CBT EOF MBM RAT CDT FID MRN RCK CTG FSZ MRS RDT DBS GRP NOA RFM Caché コールアウト・ゲートウェイの使用法 51 8 Caché コールアウトのクイック・リファレンス Caché $ZF() 関数は、1 つまたは 2 つの数値引数によって識別される従属関数のセットを提供します (例えば、$ZF(-1) 従属関数は外部プログラムまたはシステム・コマンドを実行し、$ZF(-4,1) 従属関数はコールアウト・ライブラリをロードし ます)。以下のリストは、特有の $ZF() 従属関数を識別する引数のみを示しています。これら関数の大半も、各関数の詳 細エントリに記述されているように追加の引数を取ります。 関数の詳細な説明は、以下の見出しの下に構成されています。 • 静的にリンクされた関数の使用 – • • • $ZF() (従属関数引数なし) — Caché の現在のインスタンスに静的にリンクされているコールアウト関数を呼び出 します。 プログラムまたはシステム・コマンドの実行 – $ZF(-1) — 作成された子プロセスとしてプログラムやシステム・コマンドを実行し、子プロセスの返信を待機しま す。 – $ZF(-2) — 作成された子プロセスとしてプログラムまたはシステム・コマンドを実行し、すぐに返します。 インデックスなしのコールアウト・ライブラリの使用 – $ZF(-3) — コールアウト・ライブラリをロードし、ライブラリ関数を呼び出します。 – $ZF(-4,1) — 名前によって指定されるコールアウト・ライブラリをロードし、それに対する ID 値を返します。 – $ZF(-4,2) — ID 値によって指定されるコールアウト・ライブラリをアンロードするか、またはすべてのライブラリを アンロードします。 – $ZF(-4,3) — 指定されたライブラリ内の関数の ID 値を返します。 – $ZF(-5) — システム定義の ID 値によって参照されるコールアウト・ライブラリから関数を呼び出します。 インデックス付きのコールアウト・ライブラリの使用 – $ZF(-4,4) — インデックス番号によって指定されるコールアウト・ライブラリをアンロードします。 – $ZF(-4,5) — コールアウト・システム・インデックス・テーブル内でエントリを作成します。 – $ZF(-4,6) — コールアウト・システム・インデックス・テーブル内でエントリを削除します。 – $ZF(-4,7) — コールアウト・プロセス・インデックス・テーブル内でエントリを作成します。 – $ZF(-4,8) — コールアウト・プロセス・インデックス・テーブル内でエントリを削除します。 – $ZF(-6) — ユーザ指定のインデックス番号によって参照されるコールアウト・ライブラリから関数を呼び出します。 Caché コールアウト・ゲートウェイの使用法 53 Caché コールアウトのクイック・リファレンス 8.1 静的にリンクされた関数の使用 関数が Caché と静的にリンクされると (“静的にリンクされたコールアウト関数” の説明を参照)、コールアウト・ライブラリ をロードしたりライブラリ名または識別子を指定したりする必要なく直ちに $ZF() で利用可能になります。 $ZF() 静的にリンクされた関数を呼び出します。別のコールアウト・ライブラリをロードおよび識別する必要がないため、 従属 $ZF 関数呼び出しは必要ありません。 retval = $ZF(func_name[, arg1[, ...argN]]) retval = $ZF(func_id[, arg1[, ...argN]]) パラメータ : • func_name — ZFEntry テーブルに指定されているライブラリ関数の名前 (“ZFEntry テーブルの作成” を 参照)。 • func_id — ZFEntry テーブル内のライブラリ関数のシーケンス番号。この番号が既知の場合は、アクセスを 速くするために関数名の代わりに使用されます (エントリは 1 から連番で番号が付けられます)。 • args — (オプション) ライブラリ関数で必要とされる引数を含むコンマ区切りリスト。 これは、以下を返します。 • retval — ライブラリ関数の出力値、またはライブラリ関数が出力値を設定しない場合は NULL。 関連項目 : “Caché コールアウト・ライブラリの作成”、“静的にリンクされたコールアウト関数”、"OpenVMS のみ: DSM に 代わる $ZF 関数呼び出し" 8.2 プログラムまたはシステム・コマンドの実行 このセクション内の $ZF 関数は、子プロセス内の外部プログラムまたはシステム・コマンドを実行するため、またはオペ レーティング・システム・シェルを起動するために使用されます。これらは、コールアウト・ライブラリなしで使用できる $ZF 関数です (“Caché コールアウト・ライブラリの作成” を参照)。 $ZF(-1) 作成された子プロセスとしてプログラムやオペレーティング・システム・コマンドを実行し、子プロセスの返信を待 機する間、現在のプロセスの実行を一時停止します。 status = $ZF(-1, oscommand) 以下の追加シグニチャは、OpenVMS でのみ有効です。 status = $ZF(-1, oscommand, outdev) status = $ZF(-1, oscommand, , indev) status = $ZF(-1, oscommand, outdev, indev) パラメータ : • oscommand — (オプション) 子プロセスとして実行されるコマンドを含む引用符付きの文字列。oscommand を指定しない場合は、オペレーティング・システム・シェルが起動されます。 54 Caché コールアウト・ゲートウェイの使用法 インデックスなしのコールアウト・ライブラリの使用 • outdev — (オプション、OpenVMS のみ) 出力デバイス。子プロセスに対して SYS$OUTPUT を指定するため に使用します。指定されていない場合、現在の SYS$OUTPUT を使用します。 • indev — (オプション、OpenVMS のみ) 入力デバイス。子プロセスに対して SYS$INPUT を指定するために 使用します。指定されていない場合、現在の SYS$INPUT を使用します。 これは、以下を返します。 • status — 作成されたプロセスからのステータス情報。作成されたプロセスの完了時に、終了ステータス・コー ドとして返されます。 – 0 — 呼び出しが正常に行われました – 1 — 子プロセスがエラーを返しました – -1 — 子プロセスを作成できませんでした 関連項目 : “$ZF(-1) を使用したシステム・コマンドの発行” の詳細と例、"Caché ObjectScript リファレンス" の $ZF(-1) の エントリ。 $ZF(-2) 作成された子プロセスとしてプログラム、またはコマンドを実行し、すぐに返します。作成された子プロセスの完 了を待たないので、そのプロセスからのステータス情報は受信できませんが、子プロセスが正常に作成されか どうかを示すステータス・コードを返します。 status = $ZF(-2, oscommand) パラメータ : • oscommand — (オプション) 子プロセスとして実行されるコマンドを含む引用符付きの文字列。oscommand を指定しない場合は、オペレーティング・システム・シェルが起動されます。 これは、以下を返します。 • status — 子プロセスが正常に作成されたかどうかを示すステータス・コード。 – 0 — 呼び出しが正常に行われました – -1 — 子プロセスを作成できませんでした 関連項目 : “$ZF(-2) を使用した同時子プロセスの作成” の詳細と例、"Caché ObjectScript リファレンス" の $ZF(-2) の エントリ。 8.3 インデックスなしのコールアウト・ライブラリの使用 これらの $ZF 関数を使用すると、Caché コールアウト共有ライブラリをロードして実行時にライブラリ関数を呼び出すこと ができます。ライブラリおよびライブラリ関数は名前で識別されます。 Caché コールアウト・ゲートウェイの使用法 55 Caché コールアウトのクイック・リファレンス $ZF(-3) コールアウト・ライブラリをロードし、ライブラリ関数を実行します。一度にロードできるのは 1 つの $ZF(-3) ライ ブラリのみです。$ZF(-3) への呼び出しで、前の呼び出しとは異なるライブラリを指定する場合、前のライブラリ はアンロードされ、置き換えられます。 retval = $ZF(-3, lib_name, func_name[, arg1[, ...argN]]) retval = $ZF(-3, lib_name, func_id[, arg1[, ...argN]]) パラメータ : • lib_name — ZFEntry テーブルに示されているコールアウト・ライブラリの名前 (“ZFEntry テーブルの作成” を参照)。ライブラリが既に前の $ZF(-3) への呼び出しによってロードされている場合は、空の文字列 ("") で現在のライブラリを使用することを指定します。 • func_name — コールアウト・ライブラリ内で検索する関数の名前。 • func_id — ZFEntry テーブル内のライブラリ関数のシーケンス番号。この番号が既知の場合は、アクセスを 速くするために関数名の代わりに使用されます (エントリは 1 から連番で番号が付けられます)。 • args — (オプション) ライブラリ関数で必要とされる引数を含むコンマ区切りリスト。 これは、以下を返します。 • retval — ライブラリ関数の出力値、またはライブラリ関数が出力値を設定しない場合は NULL。 関連項目 : “単純なライブラリ関数呼び出しでの $ZF(-3) の使用” の詳細と例。 $ZF(-4, 1) 名前によって指定されるコールアウト・ライブラリをロードし、それに対する ID 値を返します。 lib_id = $ZF(-4,1, lib_name) パラメータ : • lib_name — ロードされるコールアウト・ライブラリの名前。 これは、以下を返します。 • lib_id — lib_name を参照するために使用されるシステム定義識別子。 関連項目 : “システム ID によるライブラリへのアクセスでの $ZF(-5) の使用” の詳細と例。 $ZF(-4, 2) ID 値によって指定されるコールアウト・ライブラリをアンロードします。ID が指定されていない場合は、$ZF(-4,1) によってロードされたすべてのライブラリがアンロードされます。$ZF(-3) によってロードされたライブラリはアン ロードされません。 $ZF(-4,2[,lib_id]) パラメータ : • lib_id — $ZF(-4,1) によって返されるシステム定義識別子。指定されていない場合は、$ZF(-4,1) によって ロードされたすべてのライブラリがアンロードされます。 関連項目 : 56 Caché コールアウト・ゲートウェイの使用法 インデックス付きのコールアウト・ライブラリの使用 "システム ID によるライブラリへのアクセスでの $ZF(-5) の使用" の詳細と例。 $ZF(-4, 3) 指定されたコールアウト・ライブラリ内の関数の ID 値を返します。 func_id = $ZF(-4,3, lib_id, func_name) パラメータ : • lib_id — $ZF(-4,1) によって返されるシステム定義識別子。 • func_name — コールアウト・ライブラリ内で検索する関数の名前。 これは、以下を返します。 • func_id — 指定されたライブラリ関数の返された ID 値。 関連項目 : "システム ID によるライブラリへのアクセスでの $ZF(-5) の使用" の詳細と例。 注釈 $ZF(-4, 4) から $ZF(-4, 8) については、次のセクション (“インデックス付きのコールアウト・ライブラリの使用”) を参照してください。 $ZF(-5) システム定義の ID 値によって参照されるコールアウト・ライブラリから関数を呼び出します。 retval = $ZF(-5,lib_id,func_id,args) パラメータ : • lib_id — $ZF(-4,1) によって指定されるコールアウト・ライブラリ ID 値。 • func_id — $ZF(-4,3) によって指定されるライブラリ関数 ID 値。 • args — (オプション) ライブラリ関数で必要とされる引数を含むコンマ区切りリスト。 これは、以下を返します。 • retval — ライブラリ関数の出力値、またはライブラリ関数が出力値を設定しない場合は NULL。 関連項目 : "システム ID によるライブラリへのアクセスでの $ZF(-5) の使用" の詳細と例。 8.4 インデックス付きのコールアウト・ライブラリの使用 これらの $ZF 関数を使用すると、Caché コールアウト共有ライブラリのインデックスを作成できます。これは、ロードして実 行時にその関数を呼び出すことができます。ライブラリおよびライブラリ関数は事前定義された番号で識別されます。 注釈 $ZF(-4, 1)、$ZF(-4, 2)、および $ZF(-4, 3) については、前のセクション (“インデックスなしのコールアウト・ラ イブラリの使用”) を参照してください。 $ZF(-4, 4) インデックス番号によって指定されるコールアウト・ライブラリをアンロードします。 Caché コールアウト・ゲートウェイの使用法 57 Caché コールアウトのクイック・リファレンス $ZF(-4,4,lib_index) パラメータ : • lib_index — コールアウト・ライブラリに対するユーザ指定のインデックス ($ZF(-4,5) または $ZF(-4,7) によっ て作成)。 関連項目 : “ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用” の詳細と例。 $ZF(-4, 5) コールアウト・システム・インデックス・テーブル内にエントリを作成します。 $ZF(-4,5,lib_index,lib_name) パラメータ : • lib_index — コールアウト・ライブラリを参照するために使用される一意のユーザ指定番号。 • lib_name — インデックスが付けられるコールアウト・ライブラリの名前。 関連項目 : “ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用” の詳細と例。 $ZF(-4, 6) コールアウト・システム・インデックス・テーブル内のエントリを削除します。 $ZF(-4,6,lib_index) パラメータ : • lib_index — $ZF(-4,5) への呼び出しによって前に定義されたインデックス番号。この引数は必須です (省 略可能な $ZF(-4,8) とは異なります)。 関連項目 : “ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用” の詳細と例。 $ZF(-4,7) コールアウト・プロセス・インデックス・テーブル内にエントリを作成します。 $ZF(-4,7,lib_index,lib_name) パラメータ : • lib_index — コールアウト・ライブラリを参照するために使用される一意のユーザ指定番号。 • lib_name — インデックスが付けられるコールアウト・ライブラリの名前。 関連項目 : “ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用” の詳細と例。 $ZF(-4,8) コールアウト・プロセス・インデックス・テーブル内からエントリを削除します。インデックス番号が指定されていな い場合、すべてのインデックス・エントリが削除されます。 $ZF(-4,8,lib_index) 58 Caché コールアウト・ゲートウェイの使用法 インデックス付きのコールアウト・ライブラリの使用 パラメータ : • lib_index — (オプション) $ZF(-4,7) への呼び出しによって前に定義されたインデックス番号。指定されてい ない場合、すべてのインデックス・エントリが削除されます。 関連項目 : “ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用” の詳細と例。 注釈 $ZF(-5) については、前のセクション (“インデックスなしのコールアウト・ライブラリの使用”) を参照してくださ い。 $ZF(-6) インデックス付きのコールアウト・ライブラリ内の関数を検索して実行します。 retval = $ZF(-6,lib_index,func_id,args) パラメータ : • lib_index — コールアウト・ライブラリに対するユーザ指定のインデックス ($ZF(-4,5) または $ZF(-4,7) によっ て作成)。 • func_id — (オプション) $ZF(-4,3) から提供された、コールアウト・ライブラリ内の関数の ID 値。これを省略し た場合は、呼び出しによって lib_index の妥当性を検証し、ライブラリをロードして、完全なライブラリ・ファイ ル名を返します。 • args — (オプション) ライブラリ関数で必要とされる引数を含むコンマ区切りリスト。 これは、以下を返します。 • retval — ライブラリ関数の出力値、またはライブラリ関数が出力値を設定しない場合は NULL。 関連項目 : “ユーザ・インデックスによるライブラリへのアクセスでの $ZF(-6) の使用” の詳細と例。 Caché コールアウト・ゲートウェイの使用法 59
© Copyright 2024 Paperzz