z/OS Unicode Services プログラミング・インターフェースを使用する場合の一般概念

z/OS Unicode Services は、プログラミング・インターフェースの形式でサービスを提供します。これらは、アプリケーション・プログラミング・インターフェースまたは API と呼ばれることがあります。一例は、「文字変換サービス」です。

これらのインターフェースの多くは、次のような同じ概念およびフィールド・タイプを使用します。

パラメーター域: 各プログラミング・インターフェースは、呼び出し側によって指定され、データをサービスに受け渡してサービスから結果を取得するために使用されるパラメーター域またはストレージ域を定義します。
パラメーター域のデフォルト: 各サービスは、パラメーター域をデフォルト値に初期化する定数を定義します。
注: デフォルト値は、必ずしもすべてが 2 進ゼロではありません。

デフォルトの初期化指定子定数の代表的な用途は、要求された特定の入力を反映するためにパラメーター域を変更する前に初期化することです。
動的データ域 (DDA) が必要: 一部のサービスでは、呼び出し側が、サービスがその機能の実行に使用する必要な DDA またはストレージ域を定義する必要があります。このストレージはワード境界上になければなりませんが、サービスによって変更されるため初期設定の必要はありません。必要な DDA のサイズは、使用されるパラメーター域のバージョン、選択された関数、およびソース・バッファーの文字データなどの詳細によって異なります。大半のサービスは、すべての要求に適応した十分な DDA の長さを定義します。この長さを使用することをお勧めします。
パラメーター域のバージョン: 大半のパラメーター域は、「バージョン」パラメーターを定義します。初期バージョンは通常 1 で、さらに多くのパラメーターを入れるためにパラメーター域が増大するにつれてバージョンが徐々に上がります。バージョン・レベルは、パラメーター域の大きさ、必要な DDA の量、使用可能な関数、および有効なパラメーター値といったことを制御します。新しいアプリケーションは、最新の Unicode Services のパラメーター域のバージョンを使用するように作成することをお勧めします。
ALET サポート: z/OS Unicode Services インターフェースは、一般的に、その DDA およびバッファーがアクセス・リスト項目トークン (ALET) によって配置された任意のアドレス・スペースに常駐できるようにします。
抽象文字データ: 抽象文字データは、抽象文字を表すバイトのストリームです。例えば、EBCDIC CCSID では、抽象文字データ・バイト x'C9C2D4' は抽象文字「IBM」を表します。抽象文字データは、通常、文字データまたは文字ストリングと呼ばれます。
バッファー: 抽象文字データに作用する z/OS Unicode Services には、ソース・バッファーまたはターゲット・バッファーのパラメーターがあります。一部のサービスでは、中間結果を保管するための作業バッファーも必要になります。各バッファーは、バッファーへのポインター、バッファーの ALET、およびバッファーの長さ (バイト単位) の 3 つのパラメーターによって定義されます。
注: z/OS Unicode Services は、通常、使用されたバッファーの量を示すためにポインターを増やして長さを減らします。
バッファー・サイズ: 抽象文字データに作用する z/OS Unicode Services には、ターゲット・バッファー・サイズに対するさまざまな要件があります。推奨されるターゲット・バッファー・サイズは、通常は、ソース・バッファー・サイズの関数および要求された関数です。例えば、1 バイトのユニコードから 2 バイトのユニコードに変換する場合、ターゲット・バッファーは通常、ソース・バッファーの 2 倍のサイズです。それぞれの API は、そのバッファー・サイズ要件を文書化します。同じ例が、作業バッファーに必要なサイズにも適用されます。最大バッファー・サイズは、システム・リソースによってのみ制限されます。
変換データ: 変換データは、z/OS Unicode Services が変換を実行する必要があるデータ (ASCII から EBDCIC にマップするテーブルなど) を参照します。呼び出し側のソース・バッファーは参照しません。例えば、CCSID 00037 から CCSID 00437 に変換するために文字変換サービスが呼び出される場合、変換に関する情報 (例えば、両方の CCSID が 1 バイトであるという情報) が入った制御ブロック、および文字データを変換するための 256 バイトのテーブルが必要です。変換データは、通常は Unicode Services によって公開されません。変換データはユニコード環境の中で保管され、さまざまなインターフェースが「変換ハンドル」を使用して変換データを参照します。
戻りコードおよび理由コード: 一般的に、z/OS Unicode Services は、戻りコードおよび理由コードのパラメーターを設定することによって通信します。API が制御を戻すときに、これらの値を常に検査する必要があります。
注: プログラム割り込みがある場合、パラメーター域が不整合の状態のままになる可能性があります。
戻りコードおよび理由コードについては、ユニコード戻りコードおよび理由コードを参照してください。
パラメーターは検証されない: z/OS Unicode Services は、パラメーター域を使用前に検証しません。パラメーター域に適切に入力されなかった場合、間違った結果、不正な戻りコード、またはプログラム割り込みなどの予期しない結果が発生する可能性があります。Unicode Services は、一般的に内部エラーをモニターしません。呼び出し側がエラーを処理する必要があります。
ページ固定ストレージ: キー 0 から 7 を使用して実行する呼び出し側は、ページ不在の回数を減らすことによってパフォーマンスを改善する方法として、変換データがユニコード環境の中のページ固定ストレージにロードされるように要求できます。ただし、変換要求の結果として変換データがロードされるという保証はありません。変換データが既に非ページ固定ストレージにロードされている可能性があるためです。変換が確実にページ固定ストレージにロードされるようにするには、システム・プログラマーと PARMLIB メンバーを使用して実装する必要があります。
ページ固定ストレージの使用は推奨されません。変換がページ固定である場合にパフォーマンスが改善されるという保証はありません。
注: 呼び出し側は、z/OS Unicode Services API に受け渡すストレージを自由にページ固定することができます。また、z/OS Unicode Services モジュール自体はページ固定されておらず、z/OS Unicode Services が動的アドレス変換 (DAT) をオフにして実行されることは保証されません。
z/OS Unicode Services インターフェースの呼び出し: 通常、z/OS Unicode Services の呼び出しは、スタブ・ルーチンをアプリケーション・コードにリンクすることによって提供されるルーチンを呼び出すことで行われます。これらのスタブ・ルーチンは、SYS1.CSSLIB にあります。システム制御オフセットで示されているように、一部のインターフェースは、制御オフセットにブランチすることによって呼び出すことができます。この技法により、一部のパラメーター検査がなくなるためパフォーマンスが改善される可能性があります。大半のお客様は、提供されるスタブ・ルーチンを使用することをお勧めします。