MQCRTMH - メッセージ・ハンドルの作成

MQCRTMH 呼び出しは、メッセージ・ハンドルを戻します。

アプリケーションは後続のメッセージ・キューイング呼び出しで、MQCRTMH 呼び出しを使用できます。

  • MQSETMP 呼び出しを使用して、メッセージ・ハンドルのプロパティーを設定します。
  • MQINQMP 呼び出しを使用して、メッセージ・ハンドルのプロパティーの値を照会します。
  • MQDLTMP 呼び出しを使用して、メッセージ・ハンドルのプロパティーを削除します。

メッセージ・ハンドルを MQPUT および MQPUT1 呼び出し上で使用して、メッセージ・ハンドルのプロパティーを、書き込まれるメッセージのプロパティーと関連付けることができます。 同様に、メッセージ・ハンドルを MQGET 呼び出し上で指定して、MQGET 呼び出しの完了時にメッセージ・ハンドルを使用して、取り出されるメッセージのプロパティーにアクセスできます。

メッセージ・ハンドルを削除するには、 MQDLTMH を使用します。

構文

MQCRTMH（ホーコン、クリックメッセージHOpts 、うーん、コンプコード、理由）

パラメーター

Hconn
タイプ: MQHCONN - 入力

このハンドルは、キュー・マネージャーに対する接続を表します。 Hconn の値は、先行の MQCONN または MQCONNX 呼び出しによって戻されたものです。 キュー・マネージャーへの接続が有効でなくなり、メッセージ・ハンドルで IBM® MQ 呼び出しが実行されていない場合は、メッセージを削除するために MQDLTMH が暗黙的に呼び出されます。

あるいは、以下の値を指定することができます。
MQHC_UNASSOCIATED_HCONN
接続ハンドルは特定のキュー・マネージャーに対する接続を表しません。

この値を使用する場合、メッセージ・ハンドルに割り振られているストレージを解放するために、 MQDLTMH を明示的に呼び出してメッセージ・ハンドルを削除する必要があります。 IBM MQ がメッセージ・ハンドルを暗黙的に削除することはありません。

メッセージ・ハンドルを作成するスレッド上に、キュー・マネージャーへの有効な接続が少なくとも 1 つ確立されていることが必要です。確立されていない場合、呼び出しは MQRC_HCONN_ERROR で失敗します。

単一システム上に複数のインストールがある環境では、プロセスにロードされる最初のインストールでのみ MQHC_UNASSOCIATED_HCONN の値が使用されるという制限があります。 それ以外のインストールに対してメッセージ・ハンドルが提供されている場合、理由コード MQRC_HMSG_NOT_AVAILABLE が返されます。

z/OS® for CICS® アプリケーションでは、MQCONN 呼び出しを省略できます。 Hconn には以下の値を指定できます。
MQHC_DEF_HCONN
デフォルトの接続ハンドル。
CrtMsgHOpts
タイプ: MQCMHO - 入力

MQCRTMH のアクションを制御するオプション。 詳しくは、 MQCMHO を参照してください。

Hmsg
タイプ: MQHMSG - 出力

出力で、メッセージ・ハンドルのプロパティーの設定、照会、および削除に使用できるメッセージ・ハンドルが戻されます。 当初、メッセージ・ハンドルにプロパティーは含まれていません。

メッセージ・ハンドルには、メッセージ記述子も関連付けられます。 初期状態では、デフォルト値が入っています。 関連付けられたメッセージ記述子フィールドの値は、MQSETMP および MQINQMP 呼び出しを使用して設定および照会できます。 MQDLTMP 呼び出しは、メッセージ記述子のフィールドをリセットして、デフォルト値に戻します。

Hconn パラメーターが値 MQHC_UNASSOCIATED_HCONN として指定されている場合、戻されるメッセージ・ハンドルは、MQGET、MQPUT、または MQPUT1 呼び出しで、処理単位内の任意の接続で使用できますが、一度に 1 つの IBM MQ 呼び出しでしか使用できません。 2 番目の IBM MQ 呼び出しが同じメッセージ・ハンドルを使用しようとしたときにハンドルが使用中の場合、2 番目の IBM MQ 呼び出しは失敗し、理由コード MQRC_MSG_HANDLE_IN_USE が戻ります。

Hconn パラメーターが MQHC_UNASSOCIATED_HCONN でない場合、戻されるメッセージ・ハンドルは、指定された接続のみで使用できます。

このメッセージ・ハンドルが使用される以下に示す MQI 呼び出しでは、同じ HCONN パラメーター値を使用する必要があります。
  • MQDLTMH
  • MQSETMP
  • MQINQMP
  • MQDLTMP
  • MQMHBUF
  • MQBUFMH

戻されるメッセージ・ハンドルは、このメッセージ・ハンドルに MQDLTMH 呼び出しが発行されたとき、またはハンドルの有効範囲を定義する処理の単位が終了したときに無効になります。 メッセージ・ハンドルの作成時に特定の接続が提供され、キュー・マネージャーに対するこの接続が無効になった場合 (例えば、MQDBC が呼び出された場合)、MQDLTMH が暗黙的に呼び出されます。

CompCode
タイプ: MQLONG - 出力
完了コード。以下のいずれかです。
MQCC_OK
正常終了。
MQCC_FAILED
呼び出し失敗。
理由
タイプ: MQLONG - 出力
CompCodeが MQCC_OK の場合:
MQRC_NONE
(0, X'000') レポートする理由コードはありません。
CompCodeが MQCC_FAILED の場合:
MQRC_ADAPTER_NOT_AVAILABLE
(2204, X'089C') アダプターが利用できません。
MQRC_ADAPTER_SERV_LOAD_ERROR
(2130, X'852') アダプター・サービス・モジュールをロードできません。
MQRC_ASID_MISMATCH
(2157, X'86D') 1 次 ASID とホーム ASID が異なっています。
MQRC_CALL_IN_PROGRESS
(2219, X'08AB') 前の呼び出しが完了する前に MQI 呼び出しが入力された。
MQRC_CMHO_ERROR
(2461, X'099D') メッセージ・ハンドル作成オプションの構造が無効です。
MQRC_CONNECTION_BROKEN
(2273, X'7D9') キュー・マネージャーへの接続が失われました。
MQRC_HANDLE_NOT_AVAILABLE
(2017, X'07E1') 使用可能なハンドルがなくなりました。
MQRC_HCONN_ERROR
(2018, X'7E2') 接続ハンドルが無効です。
MQRC_HMSG_ERROR
(2460, X'099C') メッセージ・ハンドル・ポインターが無効。
MQRC_OPTIONS_ERROR
(2046, X'07FE') オプションが無効であるか、矛盾しています。
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') ストレージが不足しています。
MQRC_UNEXPECTED_ERROR
(2195, X'893') 予期しないエラーが発生しました。

これらのコードについて詳しくは、 メッセージおよび理由コードを参照してください。

C

MQCRTMH (Hconn, &CrtMsgHOpts, &Hmsg, &CompCode, &Reason);
パラメーターを次のように宣言します。
MQHCONN  Hconn;       /* Connection handle */
MQCMHO   CrtMsgHOpts; /* Options that control the action of MQCRTMH */
MQHMSG   Hmsg;        /* Message handle */
MQLONG   CompCode;    /* Completion code */
MQLONG   Reason;      /* Reason code qualifying CompCode */

COBOL

CALL 'MQCRTMH' USING HCONN, CRTMSGHOPTS, HMSG, COMPCODE, REASON.
パラメーターを次のように宣言します。
**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Options that control the action of MQCRTMH
 01  CRTMSGHOPTS.
     COPY CMQCMHOV.
**   Message handle
 01  HMSG    PIC S9(18) BINARY.
**   Completion code
 01  COMPCODE  PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON    PIC S9(9) BINARY.

PL/I

call MQCRTMH (Hconn, CrtMsgHOpts, Hmsg, CompCode, Reason);
パラメーターを次のように宣言します。
dcl Hconn       fixed bin(31);  /* Connection handle */
dcl CrtMsgHOpts like MQCMHO;    /* Options that control the action of MQCRTMH */
dcl Hmsg        fixed bin(63);  /* Message handle */
dcl CompCode    fixed bin(31);  /* Completion code */
dcl Reason      fixed bin(31);  /* Reason code qualifying CompCode */

High Level Assembler

CALL MQCRTMH,(HCONN,CRTMSGHOPTS,HMSG,COMPCODE,REASON)
パラメーターを次のように宣言します。
HCONN          DS        F  Connection handle
CRTMSGHOPTS    CMQCMHOA  ,  Options that control the action of MQCRTMH
HMSG           DS        D  Message handle
COMPCODE       DS        F  Completion code
REASON         DS        F  Reason code qualifying COMPCODE