Caché インターネット・ユーティリティの使用法
IBM WebSphere MQ メッセージの送受信
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Caché は、IBM WebSphere MQ へのインタフェースを提供しており、それを使用して、Caché と IBM WebSphere MQ のメッセージ・キューとの間でメッセージをやり取りできます。このインスタンスを使用するには、IBM WebSphere MQ サーバにアクセスでき、IBM WebSphere MQ クライアントが Caché と同じマシン上で稼動している必要があります。

このインタフェースは、%Net.MQSend クラスおよび %Net.MQRecv クラスから構成されています。これらのクラスは共に %Net.abstractMQ のサブクラスです。 これらのクラスは、すべての適切なプラットフォームで Caché によって自動的にインストールされるダイナミック・リンク・ライブラリを使用します(これは、Windows では、MQInterface.dll です。ファイルの拡張子は、その他のプラットフォームでは異なります)。同様に、Caché ダイナミック・リンク・ライブラリは、IBM WebSphere MQ ダイナミック・リンク・ライブラリを必要とします。
インタフェースは、テキスト・データのみの送受信をサポートし、バイナリ・データの送受信はサポートしません。長い文字列を有効化していない場合、ファイル・ストリームを使用して、長いメッセージを送受信できます。
以下の項目について説明します。
IBM WebSphere MQ を使用するには、この製品の正式なドキュメントが必要です。また、IBM WebSphere MQ への Caché インタフェースについての追加情報は、%Net.abstractMQ のクラス・リファレンスを参照してください。
IBM WebSphere MQ への Caché インタフェースの使用
通常、IBM WebSphere MQ への Caché インタフェースを使用するには、次の操作を実行します。
  1. IBM WebSphere MQ v7.x 以降にアクセスできることを確認します。具体的には以下の手順を実行します。
  2. メッセージを送信するのか、受信するのかによって、%Net.MQSend または %Net.MQRecv の新規インスタンスを作成します。
  3. IBM WebSphere MQ サーバに接続します。このためには、以下の情報を指定します。
    IBM WebSphere MQ の認証機能を使用している場合、名前とパスワードも入力できます。
  4. メッセージを送信または受信するには、%Net.MQSend または %Net.MQRecv の適切なメソッドを呼び出します。
Note:
64 ビットの Linux プラットフォームで IBM Websphere MQ を使用するには、MQ ライブラリの場所が含まれるように LD_LIBRARY_PATH を設定する必要があります。このパスは、MQ インタフェースを使用するすべての Caché プロセスに対して設定されていなければならないため、バックグラウンド処理を行う場合は、Caché の起動よりも前に設定する必要があります。また、これはセッションの実行前にすべての UNIX® ターミナルで設定します。
エラー・コードの取得
%Net.MQSend および %Net.MQRecv のメソッドは、成功した場合 1 を返し、成功しない場合 0 を返します。エラーの場合は、%GetLastError() メソッドを呼び出します。このメソッドは、IBM WebSphere MQ によって提供された最後の理由コードを返します。理由コードの詳細は、正式な IBM ドキュメントを参照してください。
Connection オブジェクトの生成
IBM WebSphere MQ によりメッセージを送信または受信する前に、接続オブジェクト (キュー・マネージャへの接続を確立し、チャネルを開き、使用するキューを開くオブジェクトの Caché 用語) を作成する必要があります。これを行うには、以下の 2 つの方法があります。
%Init() メソッドの使用法
%Init() メソッドを使用して、接続オブジェクトを作成する手順は以下のとおりです。
  1. %Net.MQSend (メッセージを送信する場合) または %Net.MQRecv (メッセージを受信する場合) のインスタンスを作成します。この章では、このインスタンスを接続オブジェクトと呼びます。
    Note:
    <DYNAMIC LIBRARY LOAD> エラーが発生した場合、ダイナミック・リンク・ライブラリはなく、詳細は、(システム・マネージャのディレクトリ内の) cconsole.log ファイルに記載されます。
  2. 認証が必要な場合、接続オブジェクトの以下のプロパティを設定します。
  3. 接続オブジェクトの %Init() メソッドを呼び出します。このメソッドは、順番に以下の引数を取ります。
    1. (必須) キュー名を指定する文字列。これは、指定したキュー・マネージャに対して有効なキューである必要があります。
    2. キュー・マネージャを指定する文字列。これは、IBM WebSphere MQ サーバ上で有効なキュー・マネージャである必要があります。
      この引数を省略すると、システムは、IBM WebSphere MQ で構成された既定のキュー・マネージャを使用します。あるいは、キュー名によってキュー・マネージャを決定するように IBM WebSphere MQ を構成した場合、システムは、指定したキュー名に適したキュー・マネージャを使用します。
    3. 以下の形式の、チャネルの仕様を指定する文字列。
      "channel_name/transport/host_name(port)"
      ここで、channel_name は使用するチャネルの名前、transport はチャネルが使用する転送、host_name は IBM WebSphere MQ サーバを実行しているサーバ名 (または IP アドレス)、port はこのチャネルが使用するポートです。
      Transport は、TCPLU62NETBIOSSPX のいずれかです。
      以下はその例です。
      "CHAN_1/TCP/rodan(1401)"
      "CHAN_1/TCP/127.0.0.1(1401)"
      この引数を省略すると、システムは、IBM WebSphere MQ で構成された既定のチャネル仕様を使用します。あるいは、キュー名によってチャネルを決定するようにシステムを構成した場合、システムは、指定したキュー名に適したチャネルを使用します。
    4. エラー・メッセージを書き込むログ・ファイルを指定するオプションの文字列。既定の設定は、ログ記録しない設定です。
  4. %Init() メソッドによって返される値を確認します。メソッドが 1 を返した場合、接続は正常に確立されており、接続オブジェクトを使用して、(使用しているクラスによって) メッセージを送受信することができます。エラー・コードの取得 を参照してください。
%Connect() メソッドの使用法
場合によっては、接続のすべての詳細を個別に指定したいことがあります。このためには、以下のように %Connect() メソッドを使用します。
  1. %Net.MQSend (メッセージを送信する場合) または %Net.MQRecv (メッセージを受信する場合) のインスタンスを作成します。前述のとおり、この章では、このインスタンスを接続オブジェクトと呼びます。
    Note:
    <DYNAMIC LIBRARY LOAD> エラーが発生した場合、ダイナミック・リンク・ライブラリはなく、詳細は、(システム・マネージャのディレクトリ内の) cconsole.log ファイルに記載されます。
  2. 接続オブジェクトの以下のプロパティを設定します。
  3. オプションで、接続オブジェクトの以下のプロパティを設定して、使用するチャネルを指定します。
    これらの引数を省略すると、システムは、IBM WebSphere MQ で構成された既定のチャネル仕様を使用します。あるいは、キュー名によってチャネルを決定するようにシステムを構成した場合、システムは、指定したキュー名に適したチャネルを使用します。
  4. チャネルに認証が必要な場合、接続オブジェクトの以下のプロパティを設定します。
  5. 接続オブジェクトの %ErrLog() メソッドを呼び出します。このメソッドは、この接続オブジェクトに使用するログ・ファイルの名前である、1 つの引数を取ります。
  6. %ErrLog() メソッドによって返される値を確認します。エラー・コードの取得 を参照してください。
  7. 接続オブジェクトの %Connect() メソッドを呼び出します。
  8. %Connect() メソッドによって返される値を確認します。メソッドが 1 を返した場合、接続は正常に確立されており、接続オブジェクトを使用して、(使用しているクラスによって) メッセージを送受信することができます。エラー・コードの取得 を参照してください。
文字セット (CCSID) の指定
メッセージ変換に使用される文字セットを設定するには、接続オブジェクトの %SetCharSet() メソッドを呼び出します。IBM WebSphere MQ で使用される整数のコード化文字セット識別コード (CCSID) を指定します。
現在使用されている CCSID を取得するには、%CharSet() メソッドを呼び出します。このメソッドは、参照によって CCSID を返し、成功したかどうかを示す 1 または 0 を返します。エラー・コードの取得 を参照してください。
指定した文字セットに該当する CCSID の詳細は、正式の IBM ドキュメントを参照してください。
その他のメッセージ・オプションの指定
メッセージ記述子オプションを指定するには、オプションで、接続オブジェクトの以下のプロパティを設定します。
メッセージの送信
メッセージを送信するには、以下の手順を実行します。
  1. Connection オブジェクトの作成 の説明に従って、接続オブジェクトを作成します。この場合、%Net.MQSend のインスタンスを作成します。接続オブジェクトには、メッセージを送信できるメッセージ・キューがあります。
  2. 必要に応じて、以下のメソッドを呼び出します。
  3. 呼び出したメソッドによって返される値を確認します。エラー・コードの取得 を参照してください。
  4. メッセージの取得が完了したら、接続オブジェクトの %Close() メソッドを呼び出して、ダイナミック・リンク・ライブラリへのハンドルを解放します。
例 1 : SendString()
以下のクラス・メソッドは、QM_antigua キュー・マネージャ、および S_antigua という名前のキュー・チャネルを使用して、単純な文字列のメッセージを cachetest キューに送信します。チャネルは 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="cachetest"
 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="cachetest"
 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,!
その他の例については、前のセクションも参照してください。
メッセージの取得
メッセージを取得するには、以下の手順を実行します。
  1. Connection オブジェクトの作成 の説明に従って、接続オブジェクトを作成します。この場合、%Net.MQRecv のインスタンスを作成します。接続オブジェクトには、メッセージを取得できるメッセージ・キューがあります。
  2. 必要に応じて、以下のメソッドを呼び出します。
    両方のメソッドにおいて、2 番目の引数は、ミリ秒単位でのタイムアウトです。これは、サーバへのアクセスに使用される時間を制御します。既定のタイムアウトは 0 です。
  3. 呼び出したメソッドによって返される値を確認します。エラー・コードの取得 を参照してください。IBM WebSphere MQ は、キューが空の場合、2033 を返すことに留意してください。
  4. メッセージの取得が完了したら、接続オブジェクトの %Close() メソッドを呼び出して、ダイナミック・リンク・ライブラリへのハンドルを解放します。
例 1 : ReceiveString()
以下のクラス・メソッドは、cachetest キューからメッセージを取得します。
/// This is useful only if you enable long strings or you are
/// sure that you will receive strings < 32k in length.
///Method returns string or null or error message
ClassMethod ReceiveString() As %String
{
 Set recv=##class(%Net.MQRecv).%New()
 Set queue="cachetest"
 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="cachetest"
 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.MQSend クラスおよび %Net.MQRecv クラスも以下のメソッドを提供します。
%CorId()
最後に読み取ったメッセージの相関 ID を (参照によって) 更新します。
%ReplyQMgrName()
最後に読み取ったメッセージの応答キュー・マネージャ名を (参照によって) 更新します。
%ReplyQName()
最後に読み取ったメッセージの応答キュー名を (参照によって) 更新します。
トラブルシューティング
IBM WebSphere MQ への Caché インタフェースを使用しているときに問題が発生した場合、まず、クライアントが正しくインストールされているか、およびサーバと通信可能であるかを判断する必要があります。そのようなテストを行うには、IBM WebSphere MQ が提供するサンプル・プログラムを使用できます。実行可能プログラムは、IBM WebSphere MQ クライアントの bin ディレクトリにあります。
以下の手順は、これらのサンプル・プログラムを Windows で使用する方法を示します。その他のオペレーティング・システムでは、詳細は異なる場合があります。IBM ドキュメントを参照し、使用しているクライアントにあるファイルの名前を確認してください。
  1. MQSERVER という環境変数を作成します。その値は、channel_name/transport/server の形式である必要があります。ここで、channel_name は使用するチャネルの名前、transport は使用する転送を示す文字列、server は、サーバの名前です。例えば、S_antigua/TCP/antigua です。
  2. コマンド行で、以下のコマンドを入力します。
    amqsputc queue_name queue_manager_name
    queue_name は使用するキューの名前、queue_manager_name はキュー・マネージャの名前です。以下はその例です。
    amqsputc cachetest QM_antigua
    amqsputc コマンドが認識されない場合、PATH 環境変数が IBM WebSphere MQ クライアントの bin ディレクトリを含めるように更新されていることを確認してください。
    その他のエラーの場合は、IBM ドキュメントを参照してください。
  3. 以下のような 2 行が表示されます。
    Sample AMQSPUT0 start
    target queue is cachetest
  4. これでメッセージを送信できます。各メッセージを入力し、各メッセージの後で Enter キーを押すだけです。以下はその例です。
    sample message 1
    sample message 2
  5. メッセージの送信が完了したら、Enter キーを 2 回押します。以下のような行が表示されます。
    Sample AMQSPUT0 end
  6. このテストを完了するには、キューに送信したメッセージを取得します。コマンド行で以下のコマンドを入力します。
    amqsgetc queue_name queue_manager_name
    queue_name は使用するキューの名前、queue_manager_name はキュー・マネージャの名前です。以下はその例です。
  7. その後、開始行が表示されます。それに続いて、以下のような、以前送信したメッセージが表示されます。
    Sample AMQSGET0 start
    message <sample message 1>
    message <sample message 2>
  8. このサンプル・プログラムは、その他のメッセージを受信するために短時間待機し、以下を表示します。
    no more messages
    Sample AMQSGET0 end
    
テストに失敗した場合は、IBM ドキュメントを参照してください。問題の考えられる原因には、以下があります。