MQSUB - サブスクリプションの登録

HCONN (10 桁の符号付き整数) - 入力

このハンドルは、キュー・マネージャーに対する接続を表します。 HCONNの値は、先行の MQCONN または MQCONNX 呼び出しによって戻されたものです。

互換モードで実行するアプリケーションの IBM® i では、MQCONN 呼び出しを省略できます。また、 HCONN には以下の値を指定できます。

HCDEFH

デフォルトの接続ハンドル。

重要: まだ互換モードを使用している場合は、アプリケーションを再コンパイルし、代わりに静的バインド呼び出しを使用することを検討してください。 IBM iでの RPG アプリケーションの互換モード を参照してください。

SUBDSC (MQSD) - 入出力

これは、アプリケーションによって使用法が登録されているオブジェクトを識別する構造です。 詳しくは、 MQSD-サブスクリプション記述子 を参照してください。

HOBJ (10 桁の符号付き整数) - 入出力

このハンドルは、このサブスクリプションに送信されたメッセージを取得するために設定されたアクセスを表します。 これらのメッセージを特定のキューに保管することもできますし、それらの保管の管理をキュー・マネージャーに依頼することもできます (後者の場合には特定のキューを必要としません)。

オブジェクト・ハンドル

特定のキューを使用する場合、それは作成時にサブスクリプションに関連付けられる必要があります。 次の 2 つの方法でこの作業を行うことができます。

• SDCRT オプションを指定して MQSUB を呼び出すときにこのハンドルを指定する方法。 このハンドルが呼び出しの入力パラメーターとして指定される場合、それは、OOINP*、OOOUT (例えばリモート・キューである場合)、または OOBRW オプションの少なくとも 1 つを使用したキューに対する前の MQOPEN 呼び出しで返された、有効なオブジェクト・ハンドルである必要があります。 そうでない場合、呼び出しは RC2019 で失敗します。 このハンドルは、トピック・オブジェクトに解決される別名キューへのオブジェクト・ハンドルにすることはできません。 その場合、呼び出しは RC2019 で失敗します。
• DEFINE SUB MQSC コマンドを使用し、そのコマンドにキュー・オブジェクトの名前を提供する。

キュー・マネージャーがこのサブスクリプションに送信されたメッセージの保管を管理するようにする場合、そのことをサブスクリプションの作成時に示す必要があります。これは、SOMAN オプションを使用し、パラメーター値を HONONE に設定することにより行います。 キュー・マネージャーは、呼び出しの出力パラメーターとしてハンドルを返します。返されるハンドルは管理対象ハンドルと呼ばれます。 HONONE が指定されても SOMAN は指定されていない場合、呼び出しは RC2019 で失敗します。

キュー・マネージャーにより戻される管理対象ハンドルは、MQGET または MQCB 呼び出し (ブラウズ・オプションありなしの両方)、MQINQ 呼び出し、または MQCLOSE で使用できます。 これは MQPUT、MQSET、または後続の MQSUB では使用できません。これらで使用しようとすると、MQPUT の場合は RC2039、MQSET の場合は RC2040、MQSUB の場合は RC2038 で失敗します。

MQSD 構造体の OPTS フィールドで SORES オプションを使用してこのサブスクリプションを再開すると、HONONE が指定されている場合には、このパラメーターでハンドルをアプリケーションに返すことができます。 このオプションは、サブスクリプションが管理対象ハンドルを使用しているかどうかに関係なく使用できます。 サブスクリプション・キューへのハンドルを DEFINE SUB コマンドで定義する場合、DEFINE SUB を使用して作成されたサブスクリプションでこのオプションが役立つ場合があります。 管理用に作成されたサブスクリプションが再開される場合には、キューは OOINPQ および OOBRW でオープンされます。 他のオプションが必要である場合、アプリケーションで明示的にサブスクリプション・キューをオープンし、呼び出しでオブジェクト・ハンドルを指定する必要があります。 キューのオープンに問題がある場合、呼び出しは RC2522 で失敗します。 HOBJ が指定された場合、それは元の MQSUB 呼び出しの HOBJ と同等でなければなりません。 つまり、MQOPEN 呼び出しで返されたオブジェクト・ハンドルが指定される場合、ハンドルは前に使用されたキューと同じキューに対するものでなければなりません。そうでない場合、呼び出しは RC2019 で失敗します。

MQSD 構造体の OPTS フィールドで SOALT オプションを使用することによりこのサブスクリプションが変更される場合、別の HOBJ を指定できます。 このパラメーターを使用して以前に識別されたキューに送達されたすべてのパブリケーションはそのキューに残るので、HOBJ パラメーターが別のキューを示すようになった場合、アプリケーションの側でこれらのメッセージの取得を行う必要があります。

以下の表には、このパラメーターの使用法と、さまざまなサブスクリプション・オプションが要約されています。

オプション	Hobj	説明
SOCRT + SOMAN	入力では無視される	キュー・マネージャーでメッセージの保管を管理するサブスクリプションを作成する。
SOCRT	有効なオブジェクト・ハンドル	メッセージの宛先として特定のキューを提供して、サブスクリプションを作成します。
SORES	HONONE	以前に作成されたサブスクリプション (管理対象とそれ以外の両方) を再開し、アプリケーションで使用するためのオブジェクト・ハンドルをキュー・マネージャーが返すようにする。
SORES	有効で一致するオブジェクト・ハンドル	特定のキューをメッセージの宛先として使用する、以前に作成されたサブスクリプションを再開し、オブジェクト・ハンドルを特定のオープン・オプションを指定して使用する。
SOALT + SOMAN	HONONE	以前に特定のキューを使用していた既存のサブスクリプションを管理対象になるように変更する。
SOALT	有効なオブジェクト・ハンドル	既存のサブスクリプションが特定のキューを使用するように変更する (管理対象または別の特定のキューのいずれかから)。

パブリケーションを受け取る以降の MQGET 呼び出しでは、HOBJ が提供されたか返されたかにかかわらず、それを指定する必要があります。

HOBJ ハンドルは、それに対して MQCLOSE 呼び出しが発行されたとき、またはハンドルの有効範囲を定義する処理の単位が終了したときに、無効になります。 戻されるオブジェクト・ハンドルの有効範囲は、呼び出しで指定される接続ハンドルの有効範囲と同じです。 ハンドルの有効範囲については、 HCONN を参照してください。 HOBJ ハンドルの MQCLOSE は、HSUB ハンドルには影響を与えません。

HSUB (10 桁の符号付き整数) - 出力

このハンドルは、作成されたサブスクリプションを表します。 以下の 2 つの後続操作で使用できます。

• 後続の MQSUBRQ 呼び出しで使用して、サブスクリプション作成時に SOPUBR オプションが使用されている場合にパブリケーションを送信するように要求できます。
• 後続の MQCLOSE 呼び出しで使用して、作成されているサブスクリプションを除去できます。 HSUB ハンドルは、MQCLOSE 呼び出しが発行されたとき、またはハンドルの有効範囲を定義する処理の単位が終了したときに、無効になります。 戻されるオブジェクト・ハンドルの有効範囲は、呼び出しで指定される接続ハンドルの有効範囲と同じです。 HSUB ハンドルの MQCLOSE は、HOBJ ハンドルには影響を与えません。

このハンドルを MQGET または MQCB 呼び出しに渡すことはできません。 HOBJ パラメーターを使用する必要があります。 このハンドルを他の IBM MQ 呼び出しに渡すと、 RC2019になります。

CMPCOD (10 桁の符号付き整数) - 出力

完了コード。以下のいずれかです。

CCOK

正常終了。

CCWARN

警告 (部分完了)

CCFAIL

呼び出し失敗

REASON (10 桁の符号付き整数) - 出力

CMPCOD を説明する理由コード。

CMPCOD が CCOK の場合

RCNONE

(0, X'000') レポートする理由コードはありません。

CMPCOD が CCFAIL の場合

RC2019

(2019 X'07E3') オブジェクト・ハンドルが無効です。

RC2046

(2046 X'07FE') オプションが無効または矛盾しています。

RC2085

(2085 X'0825') 識別されたオブジェクトが見つかりません。

RC2161

(2161 X'0871') キュー・マネージャーが静止しています。

RC2298

(2298 X'08FA') 関数はサポートされていません。

RC2424

(2424 X'0978') サブスクリプション記述子 (MQSD) が無効です。

RC2425

(2441 X'979') トピック・ストリングが無効です。

RC2428

(2428 X'097C') 指定されたサブスクリプション名は既存のサブスクリプションと一致しません。

RC2429

(2429 X'097D') サブスクリプション名が存在し、別のアプリケーションが使用中です。

RC2431

(2431 X'097F') SubUserData フィールドが無効です。

RC2432

(2432 X'0980') サブスクリプションが存在します。

RC2434

(2434 X'0982') サブスクリプション名は既存のサブスクリプションと一致します。

RC2440

(2440 X'0988') SubName フィールドが無効です。

RC2441

(2441 X'0989') Objectstring フィールドが無効です。

RC2435

(2435 X'0983') SDALT を使用して属性を変更できないか、またはサブスクリプションが SDIMM で作成されました。

RC2436

(2436 X'0984') SODUR オプションは無効です。

RC2459

(2459, X'99B') 選択ストリング構文エラー。

RC2503

(2503 X'09C7') 現在 MQSUB 呼び出しはサブスクライブ先のトピックでは使用禁止になっています。

RC2519

(2519, X'9D7') 選択ストリングは、MQCHARV 構造体の使用方法についての記述で指定されているものと異なります。

RC2551

(2551, X'9F7') 指定された選択ストリングを使用できません。

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQSUB            PR                  EXTPROC('MQSUB')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Subscription descriptor
     D SUBDSC                       400A
     D* Object handle for queue
     D HOBJ                          10I 0
     D* Subscription object handle
     D HSUB                          10I 0
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CompCode
     D REASON                        10I 0