コールイン・インタフェース

8 ビットの文字列データ型

Caché は、ローカルの 8 ビット文字列エンコーディングを使用する以下のデータ型をサポートします。

• CACHE_ASTR — 8 ビット文字の計算文字列

• CACHE_ASTRP — 8 ビット計算文字列へのポインタ

タイプ定義は以下のとおりです。

#define CACHE_MAXSTRLEN 32767
typedef struct {
   unsigned short  len;
   Callin_char_t   str[CACHE_MAXSTRLEN];
} CACHE_ASTR, *CACHE_ASTRP;

CACHE_ASTR 構造体と CACHE_ASTRP 構造体には以下の 2 つの要素が含まれています。

• len — 整数。入力として使われる場合、この要素は、値が str 要素で供給されている文字列の実際の長さを指定します。出力として使われる場合、この要素は、str 要素に対して許容される最大の長さを指定します。値が返され次第、str の実際の長さと置換されます。

• str — 入力または出力文字列。

CACHE_MAXSTRLEN は、受け取る、あるいは返される文字列の最大長です。パラメータ文字列は、CACHE_MAXSTRLEN の長さである必要はなく、プログラムにそれほど多くの領域を割り当てる必要もありません。

2 バイト Unicode データ型

Caché は、2 バイトの Unicode 文字を使用するプラットフォーム上で、以下の Unicode 関連データ型をサポートしています。

• CACHEWSTR — Unicode 計算文字列

• CACHEWSTRP — Unicode 計算文字列へのポインタ

タイプ定義は以下のとおりです。

typedef struct { 
   unsigned short len; 
   unsigned short str[CACHE_MAXSTRLEN]; 
} CACHEWSTR, *CACHEWSTRP;

CACHEWSTR 構造体と CACHEWSTRP 構造体には以下の 2 つの要素が含まれています。

• len — 整数。入力として使われる場合、この要素は、値が str 要素で供給されている文字列の実際の長さを指定します。出力として使われる場合、この要素は、str 要素に対して許容される最大の長さを指定します。値が返され次第、str の実際の長さと置換されます。

• str — 入力または出力文字列。

CACHE_MAXSTRLEN は、受け取る、あるいは返される文字列の最大長です。パラメータ文字列は、CACHE_MAXSTRLEN の長さである必要はなく、プログラムにそれほど多くの領域を割り当てる必要もありません。

Caché の Unicode 対応バージョンでは、データ型 CACHE_WSTRING もあります。これは、2 バイトのプラットフォーム上でネイティブな文字列型を表します。CacheType はこの型を返します。さらに、CacheConvert では、返り値のデータ型として CACHE_WSTRING を指定できます。この型が要求された場合、結果は CACHEWSTR バッファ内の計算 Unicode 文字列として渡されます。

4 バイト Unicode データ型

Caché は、4 バイトの Unicode 文字を使用するプラットフォーム上で、以下の Unicode 関連データ型をサポートしています。

• CACHEHSTR — 拡張 Unicode 計算文字列

• CACHEHSTRP — 拡張 Unicode 計算文字列へのポインタ

タイプ定義は以下のとおりです。

typedef struct {
   unsigned int len;
   wchar_t str[CACHE_MAXSTRLEN];
} CACHEHSTR, *CACHEHSTRP;

CACHEHSTR 構造体と CACHEHSTRP 構造体には以下の 2 つの要素が含まれています。

• len — 整数。入力として使われる場合、この要素は、値が str 要素で供給されている文字列の実際の長さを指定します。出力として使われる場合、この要素は、str 要素に対して許容される最大の長さを指定します。値が返され次第、str の実際の長さと置換されます。

• str — 入力または出力文字列。

CACHE_MAXSTRLEN は、受け取る、あるいは返される文字列の最大長です。パラメータ文字列は、CACHE_MAXSTRLEN の長さである必要はなく、プログラムにそれほど多くの領域を割り当てる必要もありません。

Caché の Unicode 対応バージョンでは、データ型 CACHE_HSTRING もあります。これは、4 バイトのプラットフォーム上でネイティブな文字列型を表します。CacheType はこの型を返します。さらに、CacheConvert では、返り値のデータ型として CACHE_HSTRING を指定できます。この型が要求された場合、結果は CACHEHSTR バッファ内の計算 Unicode 文字列として渡されます。

システム中立の記号定義

一部の関数では、8 ビット・システムまたは Unicode システムで実行されるかどうかによって、許容される入力と出力が異なります。“A” (ASCII) 関数の多くでは、CACHESTR、CACHE_STR、CACHESTRP、または CACHE_STRP の各型を受け入れるものとして引数が定義されています。“A”、“W”、および “H” のいずれも使用しない記号の定義は、記号 CACHE_UNICODE および CACHE_WCHART がコンパイル時に定義されるかどうかによって、8 ビット名または Unicode 名のいずれかと条件付きで関連付けることができます。この方法により、ローカルの 8 ビット・エンコーディングあるいは Unicode エンコーディングのいずれかで動作する中立なシンボルを持つソース・コードを記述できます。

以下の callin.h からの引用は概念を示しています。

#if defined(CACHE_UNICODE) /* Unicode character strings */
#define   CACHESTR      CACHEWSTR
#define   CACHE_STR     CACHEWSTR
#define   CACHESTRP     CACHEWSTRP
#define   CACHE_STRP    CACHEWSTRP
#define   CACHE_STRING  CACHE_WSTRING

#elif defined(CACHE_WCHART)  /* wchar_t character strings */
#define   CACHESTR      CACHEHSTR
#define   CACHE_STR     CACHEHSTR
#define   CACHESTRP     CACHEHSTRP
#define   CACHE_STRP    CACHEHSTRP
#define   CACHE_STRING  CACHE_HSTRING

#else                  /* 8-bit character strings */
#define   CACHESTR      CACHE_ASTR
#define   CACHE_STR     CACHE_ASTR
#define   CACHESTRP     CACHE_ASTRP
#define   CACHE_STRP    CACHE_ASTRP
#define   CACHE_STRING  CACHE_ASTRING
#endif

スレッドおよび UNIX® のシグナル処理

UNIX® では、Caché は多くのシグナルを使用します。Caché で使用するシグナルと同じシグナルをアプリケーションでも使用する場合は、Caché でこれらがどのように処理されるのかを認識しておく必要があります。すべてのシグナルには、OS で指定された既定のアクションがあります。アプリケーションでは、既定のアクションをそのまま実行できるほか、シグナルを処理または無視することもできます。シグナルを処理する場合は、そのシグナルをブロックするスレッドと受信するスレッドをアプリケーションで選択できます。シグナルの中には、ブロック、無視、処理のいずれも不可能なものがあります。多くのシグナルの既定のアクションはプロセスの停止なので、この既定のアクションをそのままにしておくことはできません。以下のシグナルは捕捉も無視もできず、これらのシグナルが発生すればプロセスが終了します。

アプリケーションでシグナルごとに確立するアクションはプロセス全体で有効です。シグナルを各スレッドに送信できるかどうかは、スレッドに固有です。各スレッドでは、他のスレッドとは無関係にシグナルの処理方法を指定できます。あるスレッドではすべてのシグナルをブロックし、別のスレッドではすべてのシグナルを受信できるといった指定が可能です。シグナルをスレッドに送信したときの動作は、そのシグナルに対してプロセス規模で設定した処理によって決まります。

すべてのコールイン・プログラム用のヒント

外部プログラムは、Caché のデータ構造を破損しないように、特定の規則に従う必要があります。データ構造が破損すると、システムが停止する可能性があります。

• 開いているファイル数の制限

  Caché で必要なデータベースや他のファイルを開くことができるように、プログラムで大量のファイルを開かないように注意する必要があります。通常、Caché は使用中の開いているファイルの割り当てを検索し、データベース用に一定のファイル数を確保し、それ以外を Open コマンドに割り当てます。割り当てによって異なりますが、Caché には、同時に開くデータベース・ファイルが 6 ～ 30 個、また、Open コマンドで開くファイルが 0 ～ 36 個あると考えられます。

• コールイン・アプリケーションのディレクトリ名の最大文字列長

  コールイン・アプリケーションを持つディレクトリには、232 文字未満のフル・パスが必要です。 例えば、アプリケーションが C:\CacheApps\Accounting\AccountsPayable\ ディレクトリにある場合、このディレクトリの文字数は 40 文字であるため有効です。

• 停止する前に、CacheStart の後に CacheEnd を呼び出す

  CacheStart の呼び出しにより Caché 接続が確立した場合、接続完了後、CacheEnd を呼び出す必要があります。必要な数だけコールイン関数を呼び出すことが可能です。

  接続が切断されている場合でも、CacheEnd を呼び出す必要があります。接続は、RESJOB パラメータを持つ CacheAbort を呼び出すことで切断できます。

  CacheEnd は、別の CacheStart 呼び出しの準備に必要なクリーンアップ処理を実行します。(接続が切断された場合) CacheEnd を呼び出さずに再度 CacheStart を呼び出すと、CACHE_CONBROKEN コードが返されます。

• 終了する前に、ObjectScript の実行が完了するまで待機する

  プログラムを終了する場合、ObjectScript があらゆる未処理の要求を完了していることを確認する必要があります。コールイン関数 CacheContext を使用して、ObjectScript 内にいるかどうかを判断します。この呼び出しは、終了ハンドラと Ctrl-C、あるいは Ctrl-Y ハンドラで特に重要です。CacheContext がゼロ以外の値を返す場合、CacheAbort を呼び出すことができます。

• コールイン・セッションでのマージンの維持

  コールイン・セッション内ではマージンの設定が可能ですが、そのマージン設定は現在のコマンド行の残りに対してのみ保持されます。プログラム (ダイレクト・モードと同様) に、以下の行が含まれる場合、

  :Use 0:10 Write x
  

  

  コマンド行の有効期間に対してマージン 10 が確立されます。

  一部の呼び出しはコマンド行に影響を与え、それに伴ってマージンも影響を受けます。 これらは、関数の説明で "Caché にコールインする" という注釈が付いている呼び出しです。

• CacheStart() を使用する場合は、シグナル処理を実行しないでください。

  CacheStart によってさまざまなシグナルにハンドラが設定されるので、呼び出し元のアプリケーションで設定したシグナル・ハンドラとこれらのハンドラが競合する可能性があります。

Windows 用のヒント

これらのヒントは、Windows にのみ適用されます。

• キャッシュ共有ライブラリ (cache.dll) を使用してコールイン・アプリケーションを構築する際の制約

  静的オブジェクト (cache.obj) ではなく、キャッシュ共有ライブラリ (cache.dll) を使用してコールイン・アプリケーションを構築する場合、グローバル・バッファ・プールが大きいと、コールインの初期化 (CacheStart 内) が失敗して下記のエラーが発生する可能性があります。

  <Cache Startup Error: Mapping shared memory (203)>

  この原因は、Windows でロードするシステム DLL の動作にあります。Win 32 API または Microsoft Foundation Class (Microsoft Visual C++ 開発をサポートする主要ライブラリ) を使用してコード作成したアプリケーションの場合、初期化した後、直ちにその Windows コード用の DLL を OS でロードする必要があります。これらの DLL は仮想ストレージの先頭 (上位アドレス) からロードされるので、ヒープとして利用できる領域が減少します。ほとんどのシステムでは、他の DLL (例えば、表示グラフィックをサポートする DLL など) も多数あり、Windows プロセスごとに、仮想ストレージのかなり上位のアドレスに自動的にロードされます。これらの DLL は、主に 0X10000000 (256 MB) などの特定のアドレス領域を要求する傾向があるので、仮想ストレージの下位アドレスにある数百メガバイトの連続メモリが分断されます。その結果、コールイン実行可能プログラムでは、キャッシュ共有メモリ・セグメントをマッピングする仮想メモリ領域が不足します。

UNIX®、Linux、および Mac OS 用のヒント

これらのヒントは、UNIX®、Linux および Mac OS にのみ適用されます。

• UNIX® 上では割り込みを無効にしない

  UNIX® は割り込みを使用します。割り込みの受け渡しを妨げないでください。

• 適切なバージョンの XCode を使用する

  2010.2 より前の Caché for Mac OS X (32 ビット) のバージョンは、Xcode 2.5 のコンパイラを使用して構築されていました。これらのバージョンの Caché コールイン・プログラムは、これと同一のコンパイラを使用して構築する必要があります。開発プラットフォームに Mac OS X 10.5 (Leopard) またはそれ以降を使用している場合、既定の Xcode 3.0 のコンパイラの代わりに Xcode 2.5 をロードして使用する必要があります。

• 予約済みのシグナルの使用を避ける

  UNIX® では、Caché は多くのシグナルを使用します。可能であれば、Caché にリンクしたアプリケーション・プログラムでは、以下の予約済みシグナルの使用を避けてください。

  SIGABRT	SIGDANGER	SIGILL	SIGQUIT	SIGTERM	SIGVTALRM
  SIGALRM	SIGEMT	SIGINT	SIGSTOP	SIGTRAP	SIGXCPU
  SIGBUS	SIGFPE	SIGKILL	SIGSEGV	SIGUSR1	SIGXFSZ
  SIGCHLD	SIGHUP	SIGPIPE	SIGSYS	SIGUSR2

  アプリケーションでこれらのシグナルを使用する場合は、Caché でこれらがどのように処理されるのかを認識しておく必要があります。詳細は、"スレッドおよび UNIX® のシグナル処理" を参照してください。

OpenVMS 用のヒント

これらのヒントは、OpenVMS にのみ適用されます。

• OpenVMS 上でのコールインの終了

  OpenVMS STOP/ID コマンドを発行して、コールイン・プログラムを終了する場合、実害のないゴースト・プロセスが生じる場合があります。

  Caché のプロセスとしてプログラム実行中、OpenVMS が STOP/ID を受け取った場合、コマンドは無視され、ユーザはプロセスを削除できないというメッセージを受け取ります。

  しかし、STOP/ID を受け取る際、プログラムが Caché プロセスでない場合、このような保護機能はありません。このようなプロセスは即座に終了し、%SS でゴースト・プロセスのように表示されます。しかし、ゴースト・プロセスは、終了時に Caché リソースを占有しないため、システム停止の危険はありません。

• OpenVMS へのイベント・フラグの割り当て

  OpenVMS は、特定のローカル・イベント・フラグ番号を予約します。同じイベント・フラグ番号を使用しないように、ご自身のプログラムでイベント・フラグ番号を返す LIB$GETEF 関数を使用し、番号を割り当てます。

• 終了ハンドラは、OpenVMS に返す必要がある

  OpenVMS 環境では、終了ハンドラは、他の宣言済み終了ハンドラを完了させる必要があります。

• AST の使用

  OpenVMS は、非同期システム・トラップ (AST) を使用します。AST の配布を妨げないでください。

提供されるファイル

Caché コールイン・インタフェースに関する配布媒体のファイルには、以下が含まれています。

• callin.h — コールイン・データ構造と関数のプロトタイプを伴うヘッダ・ファイル

• sampcallin.c — コールイン・サンプル・ルーチン

• CLINK.OPT — リンカ・オプションの指定

Alpha システム上での CLINK.OPT の使用

OpenVMS Alpha システム用の LINK コマンドで CLINK.OPT を使用します。CLINK.OPT は、以下の行を記述したリンカ・オプション・ファイルです。

CACHE.EXE/SHAREABLE
SYS$LIBRARY:VAXCTRL/LIBRARY

以下を入力して、sampcallin.c オブジェクトを CLINK.OPT にリンクします。

$ LINK MYCALLIN,CLINK/OPT,SYS$LIBRARY:VAXCRTL/LIB

または

$ LINK/EXE=MYCALLIN SYS$INPUT/OPTION MYCALLIN.OBJ 
    SYS$LIBRARY:VAXCRTL/LIB CACHESYS:CACHE/SHARE <CTRL-Z>

複数の Caché バージョンを同時にサポートするために、ユーザ定義のコールイン実行可能プログラムは、適切な CACHE.EXE の場所と対応する Caché マネージャ・ディレクトリの位置の両方を認識する必要があります。現在の構造では、実行可能プログラムはインストール・ディレクトリの bin サブディレクトリに位置し、マネージャ・ディレクトリは mgr サブディレクトリになります。

コールイン実行可能プログラムを適切にロードおよび実行するには、以下の 2 つの論理プロセスを定義します。

• CACHE — CACHE.EXE ファイルの場所

• CACHESYS — マネージャ・ディレクトリの場所

以下はその例です。

DEFINE CACHE DKA0:[CACHESYS.BIN]CACHE.EXE
DEFINE CACHESYS DKA0:[CACHESYS.MGR]

既定の構成の場合、あるいはマシンに初めてインストールする場合、ファイルを示すこのシステム論理名を使用できます。システム論理名 CACHESYS により、マネージャ・ディレクトリの場所が既に提供されているため、ユーザは、実行可能プログラムの場所のみを提供する必要があります。

DEFINE CACHE CACHEBIN:CACHE.EXE

CACHE 論理で指定されているのとは違う CACHE.EXE に対してリンクされているコールイン・プログラムを呼び出すと、予測できない結果を生じる可能性があります。

リンクするために CACHE.EXE の位置を指定するには、以下のオプションがあります。

• 配布された CLINK.OPT ファイルを編集し、適切な CACHE.EXE の位置を指定します。

• LINK コマンド用のコマンド行で位置を指定します。

以下の例は、CACHE.EXE が DKA0:[CACHESYS.BIN] にあり、mycallin.c に呼び出されたユーザ・ソース・ファイルがあると仮定したものです。ソースをコンパイルするには以下のコマンドを使用します。

$ CC MYCALLIN

実行可能ファイルにリンクするには以下のコマンドを使用します。

$ LINK/EXECUTABLE=MYCALLIN MYCALLIN,  SYS$INPUT:/OPTIONS
DKA0:[CACHESYS.BIN]CACHE.EXE/SHAREABLE
SYS$LIBRARY:VAXCRTL/LIBRARY
<Ctrl-Z>

あるいは、読み取るために CLINK.OPT を編集します。

DKA0:[CACHESYS.BIN]CACHE.EXE/SHAREABLE
SYS$LIBRARY:VAXCRTL/LIBRARY

以下のように LINK を呼び出します。

$ LINK/EXECUTABLE=MYCALLIN MYCALLIN,  CLINK/OPTIONS

Itanium システム上での CLINK.OPT の使用

OpenVMS Itanium システム用の LINK コマンドで CLINK.OPT を使用します。CLINK.OPT は、以下の行を記述したリンカ・オプション・ファイルです。

CKERNEL.EXE/SHAREABLE

(CKERNEL.EXE は共有ライブラリ・イメージです。CACHE.EXE ファイルは、CKERNEL.EXE に対してリンクしたスタブを含む実行可能プログラム・イメージです。) 以下を入力して、sampcallin.c オブジェクトを CLINK.OPT にリンクします。

$ LINK MYCALLIN,CLINK/OPT

または

$ LINK/EXE=MYCALLIN SYS$INPUT/OPTION MYCALLIN.OBJ 
    CACHESYS:CKERNEL/SHARE <CTRL-Z>

複数の Caché バージョンを同時にサポートするために、ユーザ定義のコールイン実行可能プログラムは、適切な CKERNEL.EXE の場所および対応する Caché マネージャ・ディレクトリの場所の両方を認識する必要があります。現在の構造では、実行可能プログラムはインストール・ディレクトリの bin サブディレクトリに位置し、マネージャ・ディレクトリは mgr サブディレクトリになります。

コールイン実行可能プログラムを適切にロードおよび実行するには、以下の 2 つの論理プロセスを定義します。

• CKERNEL — CKERNEL.EXE ファイルの場所

• CACHESYS — マネージャ・ディレクトリの場所

以下はその例です。

DEFINE CKERNEL DKA0:[CACHESYS.BIN]CKERNEL.EXE
DEFINE CACHESYS DKA0:[CACHESYS.MGR]

既定の構成の場合、あるいはマシンに初めてインストールする場合、ファイルを示すこのシステム論理名を使用できます。システム論理名 CACHESYS により、マネージャ・ディレクトリの場所が既に提供されているため、ユーザは、実行可能プログラムの場所のみを提供する必要があります。

DEFINE CKERNEL CACHEBIN:CKERNEL.EXE

CKERNEL 論理で指定したものとは違う CKERNEL.EXE にリンクしたコールイン・プログラムを呼び出すと、予測できない結果を生じる可能性があります。

リンク対象の CKERNEL.EXE の位置を指定するには、以下のオプションがあります。

• 配布された CLINK.OPT ファイルを編集し、適切な CKERNEL.EXE の位置を指定します。

• LINK コマンド用のコマンド行で位置を指定します。

以下の例では、CKERNEL.EXE が DKA0:[CACHESYS.BIN] にあり、mycallin.c というユーザ・ソース・ファイルが 1 つあると仮定しています。ソースをコンパイルするには以下のコマンドを使用します。

$ CC MYCALLIN

実行可能ファイルにリンクするには以下のコマンドを使用します。

$ LINK/EXECUTABLE=MYCALLIN MYCALLIN,  SYS$INPUT:/OPTIONS
DKA0:[CACHESYS.BIN]CKERNEL.EXE/SHAREABLE
<Ctrl-Z>

あるいは、読み取るために CLINK.OPT を編集します。

DKA0:[CACHESYS.BIN]CKERNEL.EXE/SHAREABLE

以下のように LINK を呼び出します。

$ LINK/EXECUTABLE=MYCALLIN MYCALLIN,  CLINK/OPTIONS