WebSphere Message Broker バージョン 8.0.0.5 オペレーティング・システム: AIX、HP-Itanium、Linux、Solaris、Windows、z/OS

製品の最新バージョンについては、IBM Integration Bus バージョン 9.0 をご覧ください。

CREATE PROCEDURE ステートメント

CREATE PROCEDURE ステートメントは、呼び出し可能な関数またはプロシージャーを定義します。

CREATE FUNCTION ステートメントを使用して、呼び出し可能な関数またはプロシージャー (ルーチンともいう) を定義することもできます。

個々のルーチンには名前があり、この名前はそのルーチンが属するスキーマ内で固有でなければなりません。したがって、ルーチン名は多重定義できません。ルーチン名が多重定義であることをブローカーが検出すると、例外が生じます。

構文

構文図を読む構文図をスキップする
>>-CREATE--| RoutineType |--RoutineName------------------------->

>--(--| ParameterList |--)--+----------------+------------------>
                            '-| ReturnType |-'   

>--+--------------+--+---------------+--| RoutineBody |--------><
   '-| Language |-'  '-| ResultSet |-'                    

RoutineType

|--+-FUNCTION--+------------------------------------------------|
   '-PROCEDURE-'   

ParameterList

   .-,-----------------.   
   V                   |   
|----+---------------+-+----------------------------------------|
     '-| Parameter |-'     

パラメーター

        (1)                                                
|--+-IN-----+--ParameterName--+-+----------+--DataType-+-------->
   +-OUT----+                 | '-CONSTANT-'           |   
   '-INOUT--'                 |           (2)          |   
                              +-NAMESPACE--------------+   
                              '-NAME-------------------'   

   .-NULLABLE-.   
>--+----------+-------------------------------------------------|
   '-NOT NULL-'   

ReturnType

                      .-NULLABLE-.   
|--RETURNS--DataType--+----------+------------------------------|
                      '-NOT NULL-'   

言語

|--LANGUAGE--+-ESQL---------+-----------------------------------|
             |          (3) |   
             +-DATABASE-----+   
             +-.NET---------+   
             +-CLR----------+   
             '-JAVA---------'   

ResultSet

|--DYNAMIC RESULT SETS--integer---------------------------------|

RoutineBody

|--+-Statement-------------------------------------------------------+--|
   '-EXTERNAL--NAME--ExternalRoutineName--+------------------------+-'   
                                          +-.NetTypeInfo-----------+     
                                          '-JavaClassLoaderService-'     

.NetTypeInfo

|--ASSEMBLY--AssemblyName--------------------------------------->

   .----------------------------------------.   
   V  (4)                                   |   
>--------+--------------------------------+-+-------------------|
         +-APPDOMAIN--DomainName----------+     
         +-VERSION--Version---------------+     
         +-CULTURE--Culture---------------+     
         '-PUBLICKEYTOKEN--PublicKeyToken-'     

JavaClassLoaderService

|--CLASSLOADER--ClassLoaderConfigurableServiceName--------------|

注:
  1. ルーチンのタイプが FUNCTION の場合、方向標識 (IN、OUT、または INOUT) はパラメーターごとにオプションです。 しかし、文書化の目的上、新しいルーチンすべてに方向標識を指定することは適切なプログラミング手法です。方向を指定しない場合、デフォルト値 IN が使用されます。
  2. NAMESPACE または NAME 文節を使用すると、その値は暗黙的にタイプ CHARACTER の CONSTANT になります。 CONSTANT 変数の使用に関する情報については、DECLARE ステートメントを参照してください。
  3. ルーチンのタイプが FUNCTION の場合には、DATABASE の LANGUAGE を指定することはできません。
  4. それぞれ一度だけ指定可能です。

パラメーターの方向

ルーチンに渡されるパラメーターには、方向が常に関連付けられます。この方向は以下のいずれかのタイプになります。
IN
ルーチンによってこのパラメーターの値を変更できません。 このパラメーターには NULL 値を使用でき、ルーチンに渡せます。
OUT
呼び出し先ルーチンで受け取られた場合、そのルーチンに渡されたこのパラメーターには常に正しいデータ・タイプの NULL 値があります。 この値は、ルーチンが呼び出される前の値に関係なく設定されます。 ルーチンで、このパラメーターの値を変更できます。
INOUT
INOUT とは IN パラメーターと OUT パラメーターの両方のことです。 このパラメーターは値をルーチンに渡し、渡された値はルーチンで変更できます。 このパラメーターには NULL 値を使用でき、ルーチンとの間で受け渡しできます。
NULLABLE
このオプションの文節は、パラメーターの値に NULL 値を含めることが許可されることを示します。 この文節を省略した場合、NOT NULL 文節が指定されていない限り、NULL がデフォルト文節になります。
NOT NULL
このオプションの文節は、パラメーターの値に NULL 値を含めることができないことを示します。 パラメーターに NOT NULL というマークが付いている場合、呼び出しで NULL 値が渡されると例外がスローされます。 注: 現在、この文節は LANGUAGE CLR または LANGUAGE .NET でのみ使用可能であることに注意してください。

ルーチンのタイプが FUNCTION の場合、方向標識 (IN、OUT、INOUT) はパラメーターごとにオプションです。 しかし、文書化の目的上、タイプにかかわらず新しいルーチンすべてに方向標識を指定することは適切なプログラミング手法です。

CONSTANT と宣言される ESQL 変数 (または CONSTANT と宣言される変数の参照) は、方向として OUT または INOUT を持つことはできません。

ESQL ルーチン

ESQL ルーチンは ESQL で書かれていて、LANGUAGE 文節として ESQL があります。 ESQL ルーチンの本体は、通常は BEGIN … END 形式の複合ステートメントで、ルーチンに渡されるパラメーターの処理用のステートメントが複数含まれています。

ESQL の例 1

次の例は、データベース・ルーチンの例 1 と同じプロシージャーですが、ストアード・プロシージャーではなく ESQL ルーチンとしてインプリメントされます。 このルーチンの CALL 構文と結果は、以下に示すものと同じです。
CREATE PROCEDURE swapParms (
  IN parm1 CHARACTER,
  OUT parm2  CHARACTER,
  INOUT parm3 CHARACTER )
BEGIN
   SET parm2 = parm3;
   SET parm3 = parm1;
 END; 

ESQL の例 2

この例のプロシージャーでは、ESQL ルーチンの再帰的使用が示されています。 この例は、ツリーを解析し、指定された開始点とそれより下のすべての場所を訪問し、それが見つけたものを報告します。

SET OutputRoot.MQMD = InputRoot.MQMD;

  DECLARE answer CHARACTER;
  SET     answer = '';

  CALL navigate(InputRoot.XMLNS, answer);
  SET OutputRoot.XMLNS.Data.FieldNames = answer;


  CREATE PROCEDURE navigate (IN root REFERENCE, INOUT answer CHARACTER)
  BEGIN
    SET answer = answer || 'Reached Field... Type:' 
    || CAST(FIELDTYPE(root) AS CHAR)||
    ': Name:' || FIELDNAME(root) || ': Value :' || root || ': ';

    DECLARE cursor REFERENCE TO root;
    MOVE cursor FIRSTCHILD;
    IF LASTMOVE(cursor) THEN
      SET answer = answer || 'Field has children... drilling down ';
    ELSE
      SET answer = answer || 'Listing siblings... ';
    END IF;

    WHILE LASTMOVE(cursor) DO
      CALL navigate(cursor, answer);
      MOVE cursor NEXTSIBLING;
    END WHILE;

    SET answer = answer || 'Finished siblings... Popping up ';
  END;

次の入力メッセージを与えた場合、

<Person>
  <Name>John Smith</Name>
  <Salary period='monthly' taxable='yes'>-1200</Salary>
</Person>

プロシージャーは次の出力を生成します。この出力は手操作でフォーマット設定されています。

  Reached Field... Type:16777232: Name:XML: Value :: Field has children... 
  drilling down 
  Reached Field... Type:16777216: Name:Person: Value :: Field has children...
  drilling down 
  Reached Field... Type:16777216: Name:Name: 
  Value :John Smith: Field has children... drilling down 
  Reached Field... Type:33554432: Name:: 
  Value :John Smith: Listing siblings... Finished siblings... Popping up
  Finished siblings... Popping up 
  Reached Field... Type:16777216: Name:Salary:
  Value :-1200: Field has children... drilling down 
  Reached Field... Type:50331648: Name:period: 
  Value :monthly: Listing siblings... Finished siblings... Popping up
  Reached Field... Type:50331648: Name:taxable: 
  Value :yes: Listing siblings... Finished siblings... Popping up 
  Reached Field... Type:33554432: Name:: 
  Value :-1200: Listing siblings... Finished siblings... Popping up 
  Finished siblings... Popping up 
  Finished siblings... Popping up 
  Finished siblings... Popping up

.NET ルーチン

.NET ルーチンは .NET メソッドとしてインプリメントされ、LANGUAGE 文節として .NET または CLR があります。 .NET ルーチンの場合、呼び出される .NET メソッドのクラス名とメソッド名が ExternalRoutineName に含まれていなければなりません。 以下の例のように ExternalRoutineName を指定します。

>>--"-- className---.---methodName--"--------------><
className はメソッドを含むクラスを識別し、methodName は起動するメソッドを識別します。 クラスが名前空間に含まれるか、ネスト・クラスである場合には、名前空間およびネスト・クラスの名前がすべてクラス ID 部分に含まれる必要があります (例えば "IBM.Broker.test.MyOuterClass.MyNestedClass.MyMethod")

.NET クラスを見つけるために、ブローカーは GAC および AppDomain 基本ロケーションで、指定されたアセンブリーを検索します。

呼び出される .NET メソッドは、すべて public 静的メソッドでなければなりません。 さらに、すべてのパラメーターが、ESQL から .NET へのデータ・タイプのマッピング表でリストされている必要があります。 また、メソッドに戻りの型がある場合、IN データ・タイプ・マッピング表にその戻りの型がリストされている必要があります。

.NET メソッドのシグニチャーは、メソッドの ESQL ルーチンの宣言と一致している必要があります。 以下の規則も守る必要があります。
  • (クラス名と名前空間修飾子を含む) .NET メソッド名が ESQL プロシージャーの EXTERNAL NAME と一致することを確認してください。
  • .NET メソッドに戻りの型がない場合、ESQL ルーチン定義に RETURNS 文節を入れないでください。 逆に、.NET メソッドに戻りの型がある場合は、ESQL ルーチン定義に RETURNS 文節を入れる必要があります。
  • 各パラメーターのタイプおよび方向が、ESQL から .NET へのデータ・タイプのマッピング表にリストされている規則に従い、ESQL 宣言と一致するようにしてください。
  • メソッドの戻りタイプが、RETURNS 文節のデータ・タイプと一致するようにしてください。
  • EXTERNAL NAME には少なくとも "Class.Method" を含める必要があるため、EXTERNAL NAME を引用符で囲んでください。
  • 多重定義の .NET メソッドを起動する場合、多重定義メソッドごとに別々の ESQL 定義を作成し、個々の ESQL 定義に固有のルーチン名を付ける必要があります。
.NET Type Info
.NET Type Info セクションの中の文節は、LANGUAGE .NET ルーチンにのみ適用されます。
ASSEMBLY
ASSEMBLY は、呼び出されるメソッドが格納されている .NET アセンブリーを示します。 アセンブリーが GAC に存在する場合、単にアセンブリー名 (例えば “MyAssembly”) だけにすることができます。 アセンブリーが GAC に存在しない場合は、アセンブリーの完全修飾パスを含める必要があります。
APPDOMAIN
このパラメーターは、アセンブリーをロードしてメソッドを実行する APPDOMAIN の名前を示します。 この節が省略されると、APPDOMAIN は、フローが属するアプリケーションの名前に設定されます。 フローがアプリケーションに属していない場合には、APPDOMAIN はメッセージ・フローの名前に設定されます。
VERSION
これは、ロードされるアセンブリーの正確なバージョンを示します。 バージョンを省略した場合、指定されたアセンブリーの最初に見つかったバージョンが使用されます。
CULTURE
これを使用すると、アセンブリーの国別情報を正確に指定することができます。 デフォルトでは「中立的な」国別情報が使用されます。
PUBLICKEYTOKEN
ロードされるアセンブリーが GAC に存在する場合、その公開鍵トークンを提供する必要があります。 アセンブリーが GAC に存在しない場合、この文節はオプションです。 アセンブリーを検索するときの検索順序は .NET フレームワークで定義され、その詳細は MSDN にリストされています。 ただし要約版では次のように述べられています。「アセンブリー名が完全修飾されていない場合、AppDomain のベースが使われます。 アセンブリー名が完全修飾されている場合 (つまりバージョンと公開鍵トークンが指定されている場合)、App Domains ベース・フォルダーより前に GAC が検索されます。」

.NET ルーチンの例 1

.NET メソッドを表すプロシージャーを定義します。これは System:String を戻し、方向の異なる 3 つのパラメーターがあります。
CREATE PROCEDURE Swap ( 
       IN a INT NOT NULL, 
       OUT b INT NOT NULL, 
       INOUT c INT NOT NULL ) RETURNS CHARACTER NOT NULL
LANGUAGE .NET
EXTERNAL NAME "FunctionTests.SwapString"
ASSEMBLY "C:¥coding¥test projects¥MyAssembly"
APPDOMAIN "MyDomain";
以下の ESQL を使って Swap を呼び出すことができます。
CALL Swap( intVar1, intVar2, intVar3 ) INTO ReturnVar;
-- or
SET ReturnVar = Swap ( intVar1, intVar2, intVar3);

.NET ルーチンの例 2

.NET メソッドを表すプロシージャーを定義します。戻り値はなく、方向の異なる 3 つの NULL 可能パラメーターがあります。

CREATE PROCEDURE SwapNullable ( 
       IN a INTEGER NULLABLE, 
       OUT b INTEGER NULLABLE, 
       INOUT c INTEGER NULLABLE )
LANGUAGE CLR
EXTERNAL NAME "FunctionTests.SwapStringNullable"
ASSEMBLY "MyAssembly2"
APPDOMAIN "MyDomain";
以下の ESQL を使って SwapNullable を呼び出す必要があります。
CALL SwapNullable(intVar1, intVar2, intVar3);

両方の例のメソッドを提供するさまざまな .NET 言語のコード例

C#

public class FunctionTests
{

  public static string Swap(int pIn, out int pOut, ref int pInout)
  {
    pOut = pInout;
    pInout = pIn;
    return "Finished";
  }

  public static void SwapNullable(long? pIn, out long? pOut, ref long? pInout)
  {
    pOut = pInout;
    pInout = pIn;
  }

}

VB

Public Class FunctionTests

  Shared Function Swap(ByVal pIn As Integer, <Out()> ByRef pOut As Integer, ByRef pInout As Integer) As String
    pOut = pInout
    pInout = pIn
    Return "Finished"
  End Function

  Shared Sub SwapNullable(ByVal pIn As Long?, ByRef pOut As Long?, ByRef pInout As Long?)
    pOut = pInout
    pInout = pIn
  End Sub

End Class

F#

module FunctionTests

  let Swap( pIn : int, [<Out>] pOut : byref<int> ,  pInOut : byref<int> ) = (
    pOut <- pInout
    pInout <- pIn
    let temp = "Finished"
    temp
  )

  let SwapNullable(  pIn : Nullable<int64>, [<Out>] pOut : byref<Nullable<int64>> ,  pInOut : byref<Nullable<int64>> ) = (
    pOut <- pInout
    pInout)
  )

C++ / CLi

public ref class FunctionTests
{
public:

  static String^ Swap(int pIn, [Out] int% pOut, int% pInout)
  {
    pOut = pInout;
    pInout = pIn;
    String^ temp = "Finished";
    return temp;
  }

  static void SwapNullable(Nullable<long long> pIn, [Out] Nullable<long long>% pOut, Nullable<long long>% pInout)
  {
    pOut = pInout;
    pInout = pIn;
  }
}

Java ルーチン

Java™ ルーチンは、Java メソッドとしてインプリメントされ、LANGUAGE 文節として JAVA があります。 Java ルーチンの場合、呼び出される Java メソッドのクラス名とメソッド名が ExternalRoutineName に含まれていなければなりません。 以下の例のように ExternalRoutineName を指定します。
>>--"-- className---.---methodName--"--------------><
className はメソッドを含むクラスを識別し、methodName は起動するメソッドを識別します。 クラスがパッケージの一部である場合、クラス ID 部分には、完全なパッケージ接頭部を含める必要があります。例えば、『com.ibm.broker.test.MyClass.myMethod』のようにします。

Java クラスを検出するために、ブローカーは、Java クラスのデプロイで説明されている検索方式を使用します。

起動する Java メソッドには、次の基本的なシグニチャーが必要です。
public static <return-type> <method-name> (< 0 - N parameters>)

<return-type> は、ESQL から Java データ・タイプへのマッピングの表にある Java IN データ・タイプのリストに含まれるもの (ただし戻り値として許可されていない REFERENCE タイプを除く)、または Java void データ・タイプでなければなりません。 また、パラメーター・データ・タイプは、ESQL から Java データ・タイプへのマッピングの表に含まれるものでなければなりません。 さらに、Java メソッドのシグニチャーとして exception throws 文節は使用できません。

Java メソッドのシグニチャーは、メソッドの ESQL ルーチンの宣言と一致している必要があります。 以下の規則も守る必要があります。
  • クラス名やパッケージ修飾子を含め、Java メソッド名がプロシージャーの EXTERNAL NAME と一致するようにしてください。
  • Java 戻りタイプが void であれば、ESQL ルーチンの定義に RETURNS 文節を入れないでください。 逆に、Java 戻りタイプが void でない場合は、ESQL ルーチンの定義に RETURNS 文節を入れる必要があります。
  • 各パラメーターのタイプおよび方向が、ESQL から Java データ・タイプへのマッピングの表にリストされた規則に従い、ESQL 宣言と一致するようにしてください。
  • メソッドの戻りタイプが、RETURNS 文節のデータ・タイプと一致するようにしてください。
  • EXTERNAL NAME に少なくとも "class.method" を組み込まなければならないので、EXTERNAL NAME を引用符で囲んでください。
  • 多重定義の Java メソッドを起動する場合、多重定義メソッドごとに別々の ESQL 定義を作成し、個々の ESQL 定義に固有のルーチン名を付ける必要があります。

JavaClassLoader セクションの中の文節は、LANGUAGE JAVA ルーチンにのみ適用されます。 CLASSLOADER 文節はオプションです。この文節を指定しなかった場合、Java クラスは EGShared クラス・ローダーによってロードされます。 詳しくは、JavaCompute ノードのクラス・ロードおよびJavaClassLoader 構成可能サービスを参照してください。

Java メソッド内で Java ユーザー定義ノード API を使用できます (ただし、Java ルーチンに関する制約事項に文書化されている制限を守る場合に限られます)。 Java API の使用の詳細については、Java ユーザー定義ノードのコンパイルを参照してください。

Java ルーチンの例 1

このルーチンには方向の違う 3 つのパラメーターが含まれており、Java 戻りタイプ java.lang.Long にマップする整数を戻します。

CREATE FUNCTION  myProc1( IN P1 INTEGER, OUT P2 INTEGER, INOUT P3 INTEGER )
 RETURNS INTEGER
 LANGUAGE JAVA 
 EXTERNAL NAME "com.ibm.broker.test.MyClass.myMethod1";

次の ESQL を使用して、myProc1 を起動できます。

CALL myProc1( intVar1, intVar2, intVar3) INTO intReturnVar3;
-- or
SET intReturnVar3 = myProc1( intVar1, intVar2, intVar3);

Java ルーチンの例 2

このルーチンには方向の違う 3 つのパラメーターが含まれており、Java 戻りタイプ void があります。

CREATE PROCEDURE myProc2( IN P1 INTEGER, OUT P2 INTEGER, INOUT P3 INTEGER )
 LANGUAGE JAVA 
 EXTERNAL NAME "com.ibm.broker.test.MyClass.myMethod2";

次の ESQL を使用して、myProc2 を起動する必要があります。

CALL myProc2(intVar1, intVar2, intVar3);

次の Java クラスでは、前述の Java の例ごとのメソッドが用意されています。

package com.ibm.broker.test;

class MyClass {
public static Long myMethod1( Long P1, Long[] P2 Long[] P3) { ... }
public static void myMethod2( Long P2, Long[] P2 Long[] P3) { ... }

 /* When either of these methods is called:
    P1 might or might not be NULL (depending on the value of intVar1).
    P2[0] is always NULL (whatever the value of intVar2).
    P3[0] might or might not be NULL (depending on the value of intVar3).  
    This is the same as with LANGUAGE ESQL routines. 
    When these methods return:
         intVar1 is unchanged
         intVar2 might still be NULL or might have been changed
         intVar3 might contain the same value or might have been changed.
     This is the same as with LANGUAGE ESQL routines.
     
    When myMethod1 returns: intReturnVar3 is either  NULL (if the
    method returns NULL) or it contains the value returned by the 
    method.
 */
}

Java ルーチンの例 3

次の例には JAVA の LANGUAGE 文節が含まれており、クラス com.ibm.broker.test.MyClassmyMethod1 という名前の Java メソッドの EXTERNAL NAME を指定します。 また、Java クラス com.ibm.broker.test.MyClass のロードに使用する myClassLoader という名前の JavaClassLoader 構成可能サービスも指定します。
CREATE FUNCTION myMethod1 ( IN P1 INTEGER, IN P2 INTEGER )
  RETURNS INTEGER
  LANGUAGE JAVA
  EXTERNAL NAME "com.ibm.broker.test.MyClass.myMethod1"
  CLASSLOADER "myClassLoader";

ESQL から Java データ・タイプへのマッピング

以下の表は、ESQL から Java へのマッピングを要約しています。
注:
  • Java スカラー・ラッパーだけが Java に渡されます。
  • ESQL スカラー型は、プロシージャー・パラメーターの向きに応じて、オブジェクト・ラッパーまたはオブジェクト・ラッパー配列として、Java データ・タイプにマップされます。 個々のラッパー配列には厳密に 1 つのエレメントが含まれます。
  • スカラー・オブジェクト・ラッパーは、ヌル値を Java メソッドとやり取りできるようにするために使用されます。
ESQL データ・タイプ 1 Java IN データ・タイプ Java INOUT および OUT データ・タイプ
INTEGER、INT java.lang.Long java.lang.Long []
FLOAT java.lang.Double java.lang.Double[]
DECIMAL java.math.BigDecimal java.math.BigDecimal[]
CHARACTER、CHAR java.lang.String java.lang.String[]
BLOB byte[] byte[][]
BIT java.util.BitSet java.util.BitSet[]
DATE com.ibm.broker.plugin.MbDate com.ibm.broker.plugin.MbDate[]
TIME 2 com.ibm.broker.plugin.MbTime com.ibm.broker.plugin.MbTime[]
GMTTIME 2 com.ibm.broker.plugin.MbTime com.ibm.broker.plugin.MbTime[]
TIMESTAMP 2 com.ibm.broker.plugin.MbTimestamp com.ibm.broker.plugin.MbTimestamp[]
GMTTIMESTAMP 2 com.ibm.broker.plugin.MbTimestamp com.ibm.broker.plugin.MbTimestamp[]
INTERVAL サポートされません サポートされません
BOOLEAN java.lang.Boolean java.lang.Boolean[]
REFERENCE (メッセージ・ツリーへの) 3 4 5 6 com.ibm.broker.plugin.MbElement com.ibm.broker.plugin.MbElement[] (INOUT についてはサポートするが、 OUT についてはサポートしない)
ROW サポートされません サポートされません
LIST サポートされません サポートされません
  1. CONSTANT と宣言される変数 (または CONSTANT と宣言される変数の参照) は、向き INOUT または OUT を持つことはできません。
  2. Java 変数のタイム・ゾーン・セットは重要ではありません。出力 ESQL の必須タイム・ゾーンを取得します。
  3. この参照パラメーターは、Java メソッドに渡された場合はヌルにできません。
  4. 参照は、Java メソッドに渡されるときは向きを OUT にすることはできません。
  5. MbElement が Java から ESQL に INOUT パラメーターとして戻される場合、呼び出された Java メソッドに渡された MbElement が指していたのと同じメッセージ・ツリーの場所を指していなければなりません。

    例えば、OutputRoot.XML.Test に対する ESQL 参照が、Java メソッドに INOUT MbElement として渡されたが、呼び出しが戻されるときに別の MbElement が ESQL に戻される場合、その別のエレメントも OutputRoot ツリーのいずれかの場所を指していなければなりません。

  6. ESQL ルーチンは参照を戻すことができないので、MbElement は RETURNS 文節のある Java メソッドから戻ることはできません。 ただし、ポイント 5 で説明した条件に従って、MbElement は向きが INOUT のパラメーターとして戻すことができます。

スカラー変数への REFERENCE を、Java メソッドの CALL の中で使用できます。ただし、参照先の変数のデータ・タイプが、Java プログラムのシグニチャー内の対応するデータ・タイプと一致している場合に限ります。

Java ルーチンに関する制約事項

以下の制約事項が、ESQL から呼び出された Java ルーチンに適用されます。
  • Java メソッドはスレッド・セーフ (再入可能) でなければなりません。
  • データベース接続は JDBC タイプ 2 またはタイプ 4 でなければなりません。 さらに、データベース操作はブローカー・トランザクションの一部ではありません。したがって、データベース操作を外部リソース・コーディネーターによって制御することはできません (XA 環境ではこれが可能)。
  • Java ユーザー定義ノード API の使用は、Java メソッドを呼び出したのと同じスレッドだけに限る必要があります。

    メソッド内にスレッドを作成することができます。 ただし、作成したスレッドは Java API を使用してはならず、制御をブローカーに戻す必要があります。

    Java API の使用法に適用されるすべての制限は、ESQL から呼び出された Java メソッドにも適用されます。

  • ESQL から呼び出された Java メソッドは MbNode クラスを使用してはなりません。 したがって、MbNode タイプのオブジェクトを作成できず、また既存の MbNode オブジェクトのメソッドを呼び出すこともできません。
  • ESQL から呼び出された Java メソッドの内部で行われる WebSphere® MQ または JMS 処理は、ユーザー定義ノード内で WebSphere MQ および JMS 処理を実行するためのガイドラインに従って行われなければなりません。 ユーザー定義の入力ノードの計画を参照してください。

Java クラスのデプロイ

以下の 2 つの方式のいずれかを使用して、Java クラスを Java アーカイブ (JAR) ファイル中のブローカーにデプロイすることができます。
  1. JAR ファイルをブローカー・アーカイブ (BAR) ファイルに追加する

    ブローカーにデプロイするための最も効率的かつ柔軟な方式は、JAR ファイルを BAR ファイルに追加することです。 これは、WebSphere Message Broker Toolkit を使用して、手動または自動で実行できます。

    ワークスペース内に開いている、参照される Java プロジェクト内の適切な Java クラスをWebSphere Message Broker Toolkit が検出すると、それは自動的に Java クラスを JAR ファイル内にコンパイルして、それを BAR ファイルに追加します。 これは、ユーザー定義ノードのクラス・ロードで説明されている、JAR 内に JavaCompute ノードをデプロイするときに従う手順と同じです。

    WebSphere Message Broker Toolkit から JAR ファイルをデプロイするとき、再デプロイされたフローによって、BAR ファイルに含まれる JAR ファイルが再ロードされます。

    Java クラスを参照するメッセージ・フローを停止して再始動した場合も、ファイルが再ロードされます。 更新対象の JAR ファイルを参照するすべてのフローを、必ず停止および再始動 (または再デプロイ) してください。 このアクションにより、一部のフローが古いバージョンの JAR ファイルを使って実行され、他のフローが新しいバージョンを使用するという問題を防ぐことができます。

    WebSphere Message Broker Toolkit は JAR ファイルのみをデプロイし、スタンドアロン Java クラス・ファイルはデプロイしません。

  2. 以下のいずれかの場所に JAR ファイルを格納する
    1. ブローカーを実行しているマシンの workpath/shared-classes/ フォルダー
    2. ブローカーを実行しているコンピューターの CLASSPATH 環境変数

    このアクションはWebSphere Message Broker Toolkit を使用して実行できないため、手動で行う必要があります。

    この方法では、メッセージ・フローを再デプロイしたり、メッセージ・フローを停止/再始動しても、参照される Java クラスは再ロードされません。 この場合、クラスを再ロードする唯一の方法は、ブローカー自体を停止および再始動することです。

ブローカーが Java クラスを検出できるようにするには、必ず上記のいずれかの場所に格納してください。 ブローカーが指定されたクラスを検出できない場合は、例外を生成します。

JAR ファイルをデプロイするときには上記のような複数の選択肢がありますが、WebSphere Message Broker Toolkit を使って BAR ファイルをデプロイすることにより、JAR ファイルを再デプロイするときに最大の柔軟性が得られます。

データベース・ルーチン

データベース・ルーチンは、データベース・ストアード・プロシージャーとしてインプリメントされます。 データベース・ルーチンには LANGUAGE 文節として DATABASE があり、ルーチン・タイプは PROCEDURE でなければなりません。

ストアード・プロシージャーを C のような言語で書くときには、NULL 標識を使用して、プロシージャーが確実にデータを正しく処理できるようにする必要があります。

ストアード・プロシージャーのデータベース定義はデータベースによって違いますが、それらの定義の起動に使用する ESQL は違いません。 ESQL でパラメーターに与えられる名前は、データベース側で与えられる名前と必ずしも一致している必要はありません。 しかしながら、ルーチンが持つ外部名は、パッケージまたはコンテナー指定も含めて、データベースで定義された名前と一致している必要があります。

DYNAMIC RESULT SETS 文節は、データベース・ルーチン専用です。 この分節は、ストアード・プロシージャーが 1 つ以上の結果セットを戻す場合にのみ必要です。 この文節に対する integer パラメーターは 0 (ゼロ) 以上でなければならず、戻される結果セットの数を指定します。

オプションの RETURNS 文節は、ストアード・プロシージャーが単一のスカラー値を戻す場合に必要です。

EXTERNAL NAME 文節は、データベースがルーチンの認識に使用する名前を指定します。 修飾名または非修飾名のどちらも可能です。この場合の修飾子は、プロシージャーが定義されているデータベース・スキーマの名前です。 スキーマ名を指定しない場合、プロシージャーを探すスキーマとしてデータベース接続ユーザー名が使用されます。 そのスキーマに必要なプロシージャーが存在しない場合には、ルーチン定義または実行時にルーチンを呼び出す CALL に明示的なスキーマ名を指定する必要があります。 ルーチンを含むスキーマを動的に選択することについての詳細は、CALL ステートメントを参照してください。 修飾名を使用する場合は、名前を引用符で囲まなければなりません。

完全修飾ルーチンは通常、以下のような形式を取ります。
 EXTERNAL NAME "mySchema.myProc";
しかし、プロシージャーが Oracle パッケージに属する場合には、そのパッケージはプロシージャーの名前の一部として扱われます。 したがって、 パッケージ名およびスキーマ名は、以下の形式で提供しなければなりません。
EXTERNAL NAME "mySchema.myPackage.myProc";  

この形式の場合、CALL ステートメント中でパッケージ名ではなくスキーマを動的に選択できます。

プロシージャーの名前に SQL ワイルドカード文字 (パーセント (%) 文字および下線 (_) 文字) が含まれる場合、ブローカーは、データベース・エスケープ文字が各ワイルドカードの直前に組み込まれるように、プロシージャー名を変更します。 この技法により、データベースはワイルドカードを必ずリテラル文字として受け取ります。 例えば、データベース・エスケープ文字が円記号である場合、下記の文節がブローカーによって変更されて、『mySchema.Proc¥_』がデータベースに渡されます。
EXTERNAL NAME "mySchema.Proc_";  
すべての外部プロシージャーには、次の制約事項があります。
  • データベース側でストアード・プロシージャーを多重定義できない。 同じデータベース・スキーマに同じ名前のプロシージャーが複数ある場合に、ストアード・プロシージャーは多重定義であると見なされます。 プロシージャーが多重定義であることをブローカーが検出すると、例外が生じます。
  • パラメーターは ESQL REFERENCE、ROW、LIST、または INTERVAL データ・タイプであってはならない。
  • ユーザー定義タイプをパラメーターや戻り値として使用できない。
LANGUAGE DATABASE ルーチンでは、ExternalRoutineName はオプションでなく、呼び出されるルーチンのスキーマ名、パッケージ名、およびプロシージャー名を含んでいます。 以下のように ExternalRoutineName を指定します。
>>--"schemaName---.---packageName---.---procedureName--"--------------><
ここで、
  • schemaName はオプションです。
  • packageName はオプションで、Oracle データ・ソースにのみ適用されます。 packageName を指定する場合、schemaName も指定する必要があります。
  • procedureName はオプションではありません。

データベース・ルーチンの例 1

以下の例は、単一のスカラー値と OUT パラメーターを戻す、ストアード・プロシージャーの ESQL 定義を示しています。

CREATE PROCEDURE myProc1(IN P1 INT, OUT P2 INT)
RETURNS INTEGER
LANGUAGE DATABASE
EXTERNAL NAME "myschema.myproc";

myProc1 ルーチンを起動するには、この ESQL を使用します。

/*using CALL statement invocation syntax*/
CALL myProc1(intVar1, intVar2) INTO intReturnVar3;

/*or using function invocation syntax*/
SET intReturnVar3 = myProc1(intVar1, intVar2);

データベース・ルーチンの例 2

以下の ESQL コードは、DB2® のストアード・プロシージャーの定義と呼び出しの方法を示します。

ESQL 定義:
DECLARE inputParm CHARACTER;
DECLARE outputParm CHARACTER;
DECLARE inputOutputParm CHARACTER;

SET inputParm = 'Hello';
SET inputOutputParm = 'World';
CALL swapParms( inputParm, outputParm, inputOutputParm );

CREATE PROCEDURE swapParms (
  IN parm1 CHARACTER,
  OUT parm2  CHARACTER,
  INOUT parm3 CHARACTER
)
LANGUAGE DATABASE
EXTERNAL NAME dbSwapParms;

このストアード・プロシージャーを DB2 に登録するには、以下のスクリプトをファイル (例えば、test1.sql) にコピーします。

-- DB2 Example Stored Procedure
DROP PROCEDURE dbSwapParms @                   
CREATE PROCEDURE dbSwapParms
( IN in_param CHAR(32), 
  OUT out_param CHAR(32),
  INOUT inout_param CHAR(32))
LANGUAGE SQL
BEGIN   
SET out_param = inout_param;  
    SET inout_param = in_param;
END @
このファイルを DB2 コマンド・プロンプトから以下のように実行します。
db2 -td@ -vf test1.sql 
このコードを実行すると、以下の結果が予期されます。
  • IN パラメーターの値は変更されない (定義により変更できない)。
  • OUT パラメーターの値は「World」になる。
  • INOUT パラメーターの値は「Hello」に変更される。

データベース・ルーチンの例 3

以下の ESQL コードは、Oracle のストアード・プロシージャーの定義と呼び出しの方法を示します。

ESQL 定義:
DECLARE inputParm CHARACTER;
DECLARE outputParm CHARACTER;
DECLARE inputOutputParm CHARACTER;

SET inputParm = 'Hello';
SET inputOutputParm = 'World';
CALL swapParms( inputParm, outputParm, inputOutputParm );

CREATE PROCEDURE swapParms (
  IN parm1 CHARACTER,
  OUT parm2  CHARACTER,
  INOUT parm3 CHARACTER
)
LANGUAGE DATABASE
EXTERNAL NAME dbSwapParms;

このストアード・プロシージャーを Oracle に登録するには、以下のスクリプトをファイル (例えば、test1.sql) にコピーします。

CREATE OR REPLACE PROCEDURE dbSwapParms  
( in_param IN VARCHAR2,
  out_param OUT VARCHAR2,
  inout_param IN OUT VARCHAR2 ) 
AS 
BEGIN 
  out_param := inout_param;
  inout_param := in_param; 
END; 
/
このファイルを以下のように実行します。
sqlplus userID/password  @test1.sql
このコードを実行すると、以下の結果が予期されます。
  • IN パラメーターの値は変更されない (定義により変更できない)。
  • OUT パラメーターの値は「World」になる。
  • INOUT パラメーターの値は「Hello」に変更される。

データベース・ルーチンの例 4

以下の ESQL コードは、SQL サーバー のストアード・プロシージャーの定義と呼び出しの方法を示します。

ESQL 定義:
DECLARE inputParm CHARACTER;
DECLARE outputParm CHARACTER;
DECLARE inputOutputParm CHARACTER;

SET inputParm = 'Hello';
SET inputOutputParm = 'World';
CALL swapParms( inputParm, outputParm, inputOutputParm );

CREATE PROCEDURE swapParms (
  IN parm1 CHARACTER,
  INOUT parm2  CHARACTER,
  INOUT parm3 CHARACTER
)
LANGUAGE DATABASE
EXTERNAL NAME dbSwapParms;

このストアード・プロシージャーを SQL Server に登録するには、以下のスクリプトをファイル (例えば、test1.sql) にコピーします。

-- SQLServer Example Stored Procedure 
DROP PROCEDURE dbSwapParms 
go                                                   
CREATE PROCEDURE dbSwapParms 
 @in_param     CHAR(32), 
 @out_param    CHAR(32) OUT, 
 @inout_param  CHAR(32) OUT 
AS 
  SET NOCOUNT ON
  SET @out_param   = @inout_param 
  SET @inout_param = @in_param 
go 
ファイルを以下のように実行します。
isql -UuserID -Ppassword -Sserver -ddatasource -itest1.sql

SQL Server は、ストアード・プロシージャーからの OUTPUT パラメーターを INPUT/OUTPUT パラメーターとして考慮します。 ESQL 内でこれらを OUT パラメーターとして宣言した場合、実行時にタイプ・ミスマッチ・エラーが発生します。 このミスマッチを回避するには、SQL Server の OUTPUT パラメーターを、ESQL 内で INOUT として宣言する必要があります。

SQL ストアード・プロシージャーでは、次の理由により、前述の例に示されるように SET NOCOUNT ON オプションを使用してください。
  1. SQL Server からブローカーに戻されるデータ量を制限する。
  2. 結果セットを正しく戻すことができるようにする。
このコードを実行すると、以下の結果が予期されます。
  • IN パラメーターの値は変更されない (定義により変更できない)。
  • OUT パラメーターの値は「World」になる。
  • INOUT パラメーターの値は「Hello」に変更される。

データベース・ルーチンの例 5

以下の ESQL コードは、Sybase のストアード・プロシージャーの定義と呼び出しの方法を示します。

ESQL 定義:
DECLARE inputParm CHARACTER;
DECLARE outputParm CHARACTER;
DECLARE inputOutputParm CHARACTER;

SET inputParm = 'Hello';
SET inputOutputParm = 'World';
CALL swapParms( inputParm, outputParm, inputOutputParm );

CREATE PROCEDURE swapParms (
  IN parm1 CHARACTER,
  INOUT parm2  CHARACTER,
  INOUT parm3 CHARACTER
)
LANGUAGE DATABASE
EXTERNAL NAME dbSwapParms;

このストアード・プロシージャーを Sybase に登録するには、以下のスクリプトをファイル (例えば、test1.sql) にコピーします。

-- SYBASE Example Stored Procedure 
DROP PROCEDURE dbSwapParms 
go                                                   
CREATE PROCEDURE dbSwapParms 
 @in_param     CHAR(32), 
 @out_param    CHAR(32) OUT, 
 @inout_param  CHAR(32) OUT 
AS 
  SET @out_param   = @inout_param 
  SET @inout_param = @in_param 
go 
ファイルを以下のように実行します。
isql -U<userID> -P<password> -S<server> -D<datasource> -itest1.sql

Sybase は、ストアード・プロシージャーからの OUTPUT パラメーターを INPUT/OUTPUT パラメーターとして考慮します。 ESQL 内でこれらを OUT パラメーターとして宣言した場合、実行時にタイプ・ミスマッチ・エラーが発生します。 このミスマッチを回避するには、Sybase の OUTPUT パラメーターを、ESQL 内で INOUT として宣言します。

このコードを実行すると、以下の結果が予期されます。
  • IN パラメーターの値は変更されない (定義により変更できない)。
  • OUT パラメーターの値は「World」になる。
  • INOUT パラメーターの値は「Hello」に変更される。

データベース・ルーチンの例 6

以下の ESQL コードは、Informix® のストアード・プロシージャーの定義と呼び出しの方法を示します。

ESQL 定義:
DECLARE inputParm CHARACTER 'Hello';
DECLARE outputParm CHARACTER;
DECLARE inputOutputParm CHARACTER 'World';
CALL swapParms( inputParm, outputParm, inputOutputParm );

CREATE PROCEDURE swapParms (
  IN parm1 CHARACTER,
  INOUT parm2  CHARACTER,
  INOUT parm3 CHARACTER
)
LANGUAGE DATABASE
EXTERNAL NAME dbSwapParms;

このストアード・プロシージャーを Informix に登録するには、以下のスクリプトをファイル (例えば、test1.sql) にコピーします。

DROP SPECIFIC PROCEDURE dbSwapParms;
CREATE PROCEDURE dbSwapParms
  (       inParm     CHAR(20),
   OUT    outParm    CHAR(20),
   INOUT  inoutParm  CHAR(20))

   SPECIFIC dbSwapParms

    LET outParm   = inoutParm;
    LET inoutParm = inParm;
END PROCEDURE; 
ファイルを以下のように実行します。

Informix サーバー・シェル環境から以下を入力します。

dbaccess <dataBaseName> <fully qualified path/test1.sql>
このコードを実行すると、以下の結果が予期されます。
  • IN パラメーターの値は変更されない (定義により変更できない)。
  • OUT パラメーターの値は「World」になる。
  • INOUT パラメーターの値は「Hello」に変更される。

以下の制約事項が Informix ストアード・プロシージャーに適用されます。

データベース・ルーチンの例 7

次の例は、out パラメーターに加えて 2 つの結果セットを戻すストアード・プロシージャーを呼び出す方法を示します。

CREATE PROCEDURE myProc1 (IN P1 INT, OUT P2 INT)
  LANGUAGE DATABASE
  DYNAMIC RESULT SETS 2
  EXTERNAL NAME "myschema.myproc";

myProc1 を起動するには、次の ESQL を使用してください。

/* using a field reference */
CALL myProc1(intVar1, intVar2, Environment.RetVal[], OutputRoot.XMLNS.A[])
/* using a reference variable*/
CALL myProc1(intVar1, intVar2, myReferenceVariable.RetVal[], myRef2.B[])
特記事項 | 商標 | ダウンロード | ライブラリー | サポート | フィードバック

Copyright IBM Corporation 1999, 2014Copyright IBM Corporation 1999, 2014.

        
        最終更新:
        
        最終更新: 2015-02-28 17:47:21


参照トピック参照トピック | バージョン 8.0.0.5 | ak04970_