IBM WebSphere MQ メッセージの送受信
InterSystems IRIS® データ・プラットフォームは、IBM WebSphere MQ へのインタフェースを提供しており、これを使用して、InterSystems IRIS と IBM WebSphere MQ のメッセージ・キューとの間でメッセージをやり取りできます。このインスタンスを使用するには、IBM WebSphere MQ サーバにアクセスでき、IBM WebSphere MQ クライアントが InterSystems IRIS と同じマシン上で稼動している必要があります。
このインタフェースは、%Net.MQSendOpens in a new tab クラスおよび %Net.MQRecvOpens in a new tab クラスから構成されています。これらのクラスは共に %Net.abstractMQOpens in a new tab のサブクラスです。 すべての適切なプラットフォームで InterSystems IRIS によって自動的にインストールされるダイナミック・リンク・ライブラリをこれらのクラスは使用します (これは、Windows では、MQInterface.dll です。ファイルの拡張子は、その他のプラットフォームでは異なります)。同様に、InterSystems IRIS ダイナミック・リンク・ライブラリは、IBM WebSphere MQ ダイナミック・リンク・ライブラリを必要とします。
インタフェースは、テキスト・データのみの送受信をサポートし、バイナリ・データの送受信はサポートしません。
IBM WebSphere MQ を使用するには、この製品の正式なドキュメントが必要です。また、IBM WebSphere MQ への InterSystems IRIS インタフェースについての追加情報は、%Net.abstractMQOpens in a new tab のクラス・リファレンスを参照してください。
概要
通常、IBM WebSphere MQ への InterSystems IRIS インタフェースを使用するには、次の操作を実行します。
-
IBM WebSphere MQ v7.x 以降にアクセスできることを確認します。具体的には以下の手順を実行します。
-
IBM WebSphere MQ クライアントが InterSystems IRIS と同じマシンにインストールされている必要があります。インストーラは、PATH 環境変数を更新し、必要に応じてその他のシステム変数を追加します。
-
InterSystems IRIS がクライアントを認識するように、クライアントをインストールした後、マシンをリブートしたことを確認します。
-
クライアントは、IBM WebSphere MQ サーバにアクセスできる必要があります。
-
サーバにアクセスするユーザ名には、キュー・マネージャおよび使用予定のキューを使用する権限が必要です。
-
-
メッセージを送信するのか、受信するのかによって、%Net.MQSendOpens in a new tab または %Net.MQRecvOpens in a new tab の新規インスタンスを作成します。
-
IBM WebSphere MQ サーバに接続します。このためには、以下の情報を指定します。
-
キュー・マネージャの名前。
-
使用するキューの名前。
-
そのキューと通信するチャネル。チャネル名、転送メカニズム、および IBM WebSphere MQ サーバの IP アドレスとポートを指定します。
IBM WebSphere MQ の認証機能を使用している場合、名前とパスワードも入力できます。
-
-
メッセージを送信または受信するには、%Net.MQSendOpens in a new tab または %Net.MQRecvOpens in a new tab の適切なメソッドを呼び出します。
64 ビットの Linux プラットフォームで IBM Websphere MQ を使用するには、MQ ライブラリの場所が含まれるように LD_LIBRARY_PATH を設定する必要があります。このパスは、MQ インタフェースを使用するすべての InterSystems IRIS プロセスに対して設定されていなければならないため、バックグラウンド処理を行う場合は、InterSystems IRIS の起動よりも前に設定する必要があります。また、これは iris terminal の実行前にすべての UNIX® ターミナルで設定します。
エラー・コードの取得
%Net.MQSendOpens in a new tab および %Net.MQRecvOpens in a new tab のメソッドは、成功した場合 1 を返し、成功しない場合 0 を返します。エラーの場合は、%GetLastError() メソッドを呼び出します。このメソッドは、IBM WebSphere MQ によって提供された最後の理由コードを返します。理由コードの詳細は、正式な IBM ドキュメントを参照してください。
Connection オブジェクトの生成
IBM WebSphere MQ によりメッセージを送信または受信する前に、接続オブジェクト (キュー・マネージャへの接続を確立し、チャネルを開き、使用するキューを開くオブジェクト) を作成する必要があります。これを行うには、以下の 2 つの方法があります。
-
%Init メソッドを使用できます。このメソッドは、すべての必要な情報を指定する引数を取ります。
-
すべての必要な情報を指定するプロパティを設定した後、%Connect メソッドを使用できます。
%Init() メソッドの使用法
%Init() メソッドを使用して、接続オブジェクトを作成する手順は以下のとおりです。
-
%Net.MQSendOpens in a new tab (メッセージを送信する場合) または %Net.MQRecvOpens in a new tab (メッセージを受信する場合) のインスタンスを作成します。このトピックでは、このインスタンスを接続オブジェクトと呼びます。
Note:<DYNAMIC LIBRARY LOAD> エラーが発生した場合、ダイナミック・リンク・ライブラリはなく、詳細は、(システム・マネージャのディレクトリ内の) messages.log ファイルに記載されます。
-
接続オブジェクトの %Init() メソッドを呼び出します。このメソッドは、順番に以下の引数を取ります。
-
(必須) キュー名を指定する文字列。これは、指定したキュー・マネージャに対して有効なキューである必要があります。
-
キュー・マネージャを指定する文字列。これは、IBM WebSphere MQ サーバ上で有効なキュー・マネージャである必要があります。
この引数を省略すると、システムは、IBM WebSphere MQ で構成された既定のキュー・マネージャを使用します。あるいは、キュー名によってキュー・マネージャを決定するように IBM WebSphere MQ を構成した場合、システムは、指定したキュー名に適したキュー・マネージャを使用します。
-
以下の形式の、チャネルの仕様を指定する文字列。
"channel_name/transport/host_name(port)"
ここで、channel_name は使用するチャネルの名前、transport はチャネルが使用する転送、host_name は IBM WebSphere MQ サーバを実行しているサーバ名 (または IP アドレス)、port はこのチャネルが使用するポートです。
Transport は、TCP、LU62、NETBIOS、SPX のいずれかです。
以下はその例です。
"CHAN_1/TCP/rodan(1401)"
"CHAN_1/TCP/127.0.0.1(1401)"
この引数を省略すると、システムは、IBM WebSphere MQ で構成された既定のチャネル仕様を使用します。あるいは、キュー名によってチャネルを決定するようにシステムを構成した場合、システムは、指定したキュー名に適したチャネルを使用します。
-
エラー・メッセージを書き込むログ・ファイルを指定するオプションの文字列。既定の設定は、ログ記録しない設定です。
-
-
%Init() メソッドによって返される値を確認します。メソッドが 1 を返した場合、接続は正常に確立されており、接続オブジェクトを使用して、(使用しているクラスによって) メッセージを送受信することができます。"エラー・コードの取得" を参照してください。
%Connect() メソッドの使用法
場合によっては、接続のすべての詳細を個別に指定したいことがあります。このためには、以下のように %Connect() メソッドを使用します。
-
%Net.MQSendOpens in a new tab (メッセージを送信する場合) または %Net.MQRecvOpens in a new tab (メッセージを受信する場合) のインスタンスを作成します。前述のとおり、このトピックでは、このインスタンスを接続オブジェクトと呼びます。
Note:<DYNAMIC LIBRARY LOAD> エラーが発生した場合、ダイナミック・リンク・ライブラリはなく、詳細は、(システム・マネージャのディレクトリ内の) messages.log ファイルに記載されます。
-
接続オブジェクトの以下のプロパティを設定します。
-
QName — (必須) キュー名を指定します。これは、指定したキュー・マネージャに対して有効なキューである必要があります。
-
QMgr — 使用するキュー・マネージャを指定します。これは、IBM WebSphere MQ サーバ上で有効なキュー・マネージャである必要があります。
この引数を省略すると、システムは、IBM WebSphere MQ で構成された既定のキュー・マネージャを使用します。あるいは、キュー名によってキュー・マネージャを決定するように IBM WebSphere MQ を構成した場合、システムは、指定したキュー名に適したキュー・マネージャを使用します。
-
-
オプションで、接続オブジェクトの以下のプロパティを設定して、使用するチャネルを指定します。
-
Connection — IBM WebSphere MQ サーバのホストおよびポートを指定します。例えば、"127.0.0.1:1401" です。
-
Channel — 使用するチャネル名を指定します。これは、IBM WebSphere MQ サーバ上で有効なチャネルである必要があります。
-
Transport — チャネルが使用する転送を指定します。このプロパティは、"TCP"、"LU62"、"NETBIOS"、または "SPX" のいずれかです。
これらの引数を省略すると、システムは、IBM WebSphere MQ で構成された既定のチャネル仕様を使用します。あるいは、キュー名によってチャネルを決定するようにシステムを構成した場合、システムは、指定したキュー名に適したチャネルを使用します。
-
-
接続オブジェクトの %ErrLog() メソッドを呼び出します。このメソッドは、この接続オブジェクトに使用するログ・ファイルの名前である、1 つの引数を取ります。
-
%ErrLog() メソッドによって返される値を確認します。"エラー・コードの取得" を参照してください。
-
接続オブジェクトの %Connect() メソッドを呼び出します。
-
%Connect() メソッドによって返される値を確認します。メソッドが 1 を返した場合、接続は正常に確立されており、接続オブジェクトを使用して、(使用しているクラスによって) メッセージを送受信することができます。"エラー・コードの取得" を参照してください。
文字セット (CCSID) の指定
メッセージ変換に使用される文字セットを設定するには、接続オブジェクトの %SetCharSet() メソッドを呼び出します。IBM WebSphere MQ で使用される整数のコード化文字セット識別コード (CCSID) を指定します。
-
メッセージを送信する場合、これは、それらのメッセージの文字セットである必要があります。文字セットを指定しない場合、MQ システムでは、メッセージは MQ クライアントに対して指定された既定の文字セットを使用するものと見なします。
-
メッセージを取得する場合、これは、これらのメッセージ変換後の文字セットです。
現在使用されている CCSID を取得するには、%CharSet() メソッドを呼び出します。このメソッドは、参照によって CCSID を返し、成功したかどうかを示す 1 または 0 を返します。"エラー・コードの取得" を参照してください。
指定した文字セットに該当する CCSID の詳細は、正式の IBM ドキュメントを参照してください。
その他のメッセージ・オプションの指定
メッセージ記述子オプションを指定するには、オプションで、接続オブジェクトの以下のプロパティを設定します。
-
ApplIdentityData は、アプリケーション ID メッセージ記述子オプションを指定します。
-
PutApplType は、メッセージを入れたアプリケーションのタイプ・メッセージ記述子オプションを指定します。
メッセージの送信
メッセージを送信するには、以下の手順を実行します。
-
"Connection オブジェクトの作成" の説明に従って、接続オブジェクトを作成します。この場合、%Net.MQSendOpens in a new tab のインスタンスを作成します。接続オブジェクトには、メッセージを送信できるメッセージ・キューがあります。
-
必要に応じて、以下のメソッドを呼び出します。
-
%Put() — 文字列を指定すると、このメソッドは、その文字列をメッセージ・キューに書き込みます。
-
%PutStream() — 初期化済みファイルの文字ストリームを指定すると、このメソッドは、その文字列をメッセージ・キューに書き込みます。これを初期化するには、ストリームの Filename プロパティを設定する必要があります。バイナリ・ストリームはサポートされません。
-
%SetMsgId() — 文字列を指定すると、このメソッドは、その文字列を次に送信されるメッセージのメッセージ ID として使用します。
-
-
呼び出したメソッドによって返される値を確認します。"エラー・コードの取得" を参照してください。
-
メッセージの取得が完了したら、接続オブジェクトの %Close() メソッドを呼び出して、ダイナミック・リンク・ライブラリへのハンドルを解放します。
例 1 : SendString()
以下のクラス・メソッドは、QM_antigua キュー・マネージャ、および S_antigua という名前のキュー・チャネルを使用して、単純な文字列のメッセージを mqtest キューに送信します。チャネルは TCP 転送を使用し、IBM WebSphere MQ サーバは antigua と呼ばれるマシンで稼動し、ポート 1401 で待ち受け状態になっています。
///Method returns reason code from IBM WebSphere MQ
ClassMethod SendString() As %Integer
{
Set send=##class(%Net.MQSend).%New()
Set queue="mqtest"
Set qm="QM_antigua"
Set chan="S_antigua/TCP/antigua(1414)"
Set logfile="c:\mq-send-log.txt"
Set check=send.%Init(queue,qm,chan,logfile)
If 'check Quit send.%GetLastError()
//send a unique message
Set check=send.%Put("This is a test message "_$h)
If 'check Quit send.%GetLastError()
Quit check
}
例 2 : SendCharacterStream()
以下のクラス・メソッドは、ファイル文字ストリームのコンテンツを送信します。前の例で使用したキューと同じキューを使用します。
///Method returns reason code from IBM WebSphere MQ
ClassMethod SendCharacterStream() As %Integer
{
Set send=##class(%Net.MQSend).%New()
Set queue="mqtest"
Set qm="QM_antigua"
Set chan="S_antigua/TCP/antigua(1414)"
Set logfile="c:\mq-send-log.txt"
Set check=send.%Init(queue,qm,chan,logfile)
If 'check Quit send.%GetLastError()
//initialize the stream and tell it what file to use
Set longmsg=##class(%FileCharacterStream).%New()
Set longmsg.Filename="c:\input-sample.txt"
Set check=send.%PutStream(longmsg)
If 'check Quit send.%GetLastError()
Quit check
}
例 3 : ターミナルからのメッセージの送信
以下に、IBM WebSphere MQ キューにメッセージを送信するターミナル・セッションの例を示します。これは、IBM WebSphere MQ クライアントで構成されているマシンでのみ機能します。
Set MySendQ = ##class(%Net.MQSend).%New()
Do MySendQ.%Init("Q_1", "QM_1","QC_1/TCP/127.0.0.1(1401)","C:\mq.log")
Do MySendQ.%Put("Hello from tester")
Set MyRecvQ =##class(%Net.MQRecv).%New()
Do MyRecvQ.%Init("Q_1", "QM_1","QC_1","C:\mq.log")
Do MyRecvQ.%Get(.msg, 10000)
Write msg,!
その他の例については、前のセクションも参照してください。
メッセージの取得
メッセージを取得するには、以下の手順を実行します。
-
"Connection オブジェクトの作成" の説明に従って、接続オブジェクトを作成します。この場合、%Net.MQRecvOpens in a new tab のインスタンスを作成します。接続オブジェクトには、メッセージを取得できるメッセージ・キューがあります。
-
必要に応じて、以下のメソッドを呼び出します。
-
%Get() — 最初の引数として文字列メッセージを参照によって返します。
-
%GetStream() — 初期化済みのファイルの文字ストリームを指定すると、このメソッドは、メッセージをキューから取得し、それをそのストリームに関連付けられているファイルに配置します。これを初期化するには、ストリームの Filename プロパティを設定する必要があります。バイナリ・ストリームはサポートされません。
両方のメソッドにおいて、2 番目の引数は、ミリ秒単位でのタイムアウトです。これは、サーバへのアクセスに使用される時間を制御します。既定のタイムアウトは 0 です。
-
-
呼び出したメソッドによって返される値を確認します。"エラー・コードの取得" を参照してください。IBM WebSphere MQ は、キューが空の場合、2033 を返すことに留意してください。
-
メッセージの取得が完了したら、接続オブジェクトの %Close() メソッドを呼び出して、ダイナミック・リンク・ライブラリへのハンドルを解放します。
例 1 : ReceiveString()
以下のクラス・メソッドは、mqtest キューからメッセージを取得します。
///Method returns string or null or error message
ClassMethod ReceiveString() As %String
{
Set recv=##class(%Net.MQRecv).%New()
Set queue="mqtest"
Set qm="QM_antigua"
Set chan="S_antigua/TCP/antigua(1414)"
Set logfile="c:\mq-recv-log.txt"
Set check=recv.%Init(queue,qm,chan,logfile)
If 'check Quit recv.%GetLastError()
Set check=recv.%Get(.msg)
If 'check {
Set reasoncode=recv.%GetLastError()
If reasoncode=2033 Quit ""
Quit "ERROR: "_reasoncode
}
Quit msg
}
例 2 : ReceiveCharacterStream()
以下のメソッドは、%GetStream() を使用しているため、より長いメッセージを取得できます。
/// Method returns reason code from IBM WebSphere MQ
ClassMethod ReceiveCharacterStream() As %Integer
{
Set recv=##class(%Net.MQRecv).%New()
Set queue="mqtest"
Set qm="QM_antigua"
Set chan="S_antigua/TCP/antigua(1414)"
Set logfile="c:\mq-recv-log.txt"
Set check=recv.%Init(queue,qm,chan,logfile)
If 'check Quit recv.%GetLastError()
//initialize the stream and tell it what file to use
//make sure filename is unique we can tell what we received
Set longmsg=##class(%FileCharacterStream).%New()
Set longmsg.Filename="c:\mq-received"_$h_".txt"
Set check=recv.%GetStream(longmsg)
If 'check Quit recv.%GetLastError()
Quit check
}
メッセージ情報の更新
%Net.MQSendOpens in a new tab クラスおよび %Net.MQRecvOpens in a new tab クラスも以下のメソッドを提供します。
最後に読み取ったメッセージの相関 ID を (参照によって) 更新します。
最後に読み取ったメッセージの応答キュー・マネージャ名を (参照によって) 更新します。
最後に読み取ったメッセージの応答キュー名を (参照によって) 更新します。
トラブルシューティング
IBM WebSphere MQ への InterSystems IRIS インタフェースを使用しているときに問題が発生した場合、まず、クライアントが正しくインストールされているか、およびサーバと通信可能であるかを判断する必要があります。そのようなテストを行うには、IBM WebSphere MQ が提供するサンプル・プログラムを使用できます。実行可能プログラムは、IBM WebSphere MQ クライアントの bin ディレクトリにあります。
以下の手順は、これらのサンプル・プログラムを Windows で使用する方法を示します。その他のオペレーティング・システムでは、詳細は異なる場合があります。IBM ドキュメントを参照し、使用しているクライアントにあるファイルの名前を確認してください。
-
MQSERVER という環境変数を作成します。その値は、channel_name/transport/server の形式である必要があります。ここで、channel_name は使用するチャネルの名前、transport は使用する転送を示す文字列、server は、サーバの名前です。例えば、S_antigua/TCP/antigua です。
-
コマンド行で、以下のコマンドを入力します。
amqsputc queue_name queue_manager_name
queue_name は使用するキューの名前、queue_manager_name はキュー・マネージャの名前です。以下はその例です。
amqsputc mqtest QM_antigua
amqsputc コマンドが認識されない場合、PATH 環境変数が IBM WebSphere MQ クライアントの bin ディレクトリを含めるように更新されていることを確認してください。
その他のエラーの場合は、IBM ドキュメントを参照してください。
-
以下のような 2 行が表示されます。
Sample AMQSPUT0 start target queue is mqtest
-
これでメッセージを送信できます。各メッセージを入力し、各メッセージの後で Enter キーを押すだけです。以下はその例です。
sample message 1 sample message 2
-
メッセージの送信が完了したら、Enter キーを 2 回押します。以下のような行が表示されます。
Sample AMQSPUT0 end
-
このテストを完了するには、キューに送信したメッセージを取得します。コマンド行で以下のコマンドを入力します。
amqsgetc queue_name queue_manager_name
queue_name は使用するキューの名前、queue_manager_name はキュー・マネージャの名前です。以下はその例です。
-
その後、開始行が表示されます。それに続いて、以下のような、以前送信したメッセージが表示されます。
Sample AMQSGET0 start message <sample message 1> message <sample message 2>
-
このサンプル・プログラムは、その他のメッセージを受信するために短時間待機し、以下を表示します。
no more messages Sample AMQSGET0 end
テストに失敗した場合は、IBM ドキュメントを参照してください。問題の考えられる原因には、以下があります。
-
セキュリティの問題
-
キューが正しく定義されていない
-
キュー・マネージャが開始されていない