Die Anweisung CREATE PROCEDURE

Die Anweisungen CREATE FUNCTION und CREATE PROCEDURE definieren eine aufrufbare Funktion oder Prozedur, die i.d.R. als "Routine" bezeichnet wird.

Syntax

Syntaxdiagramm lesenSyntaxdiagramm überspringen
>>-CREATE--| RoutineType |--RoutineName------------------------->

>--(--| ParameterList |--)--+-----------------+----------------->
                            '-| Rückgabetyp |-'   

>--+-------------+--+--------------+--| Routinehauptteil |-----><
   '-| Sprache |-'  '-| Ergebnis |-'                         

RoutineType

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

Parameterliste

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

Parameter

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

Rückgabetyp

|--RETURNS--Datentyp--------------------------------------------|

Sprache

|--LANGUAGE--+-ESQL---------+-----------------------------------|
             |          (3) |   
             +-DATABASE-----+   
             '-JAVA---------'   

Ergebnis

|--DYNAMIC RESULT SETS--Ganzzahl--------------------------------|

Routinehauptteil

|--+-Anweisung---------------------------+----------------------|
   '-EXTERNAL--NAME--ExternalRoutineName-'   

Anmerkungen:
  1. 1. Hat die Routine den Typ FUNCTION (Funktion), ist der Richtungsanzeiger (IN, OUT, INOUT) für jeden Parameter optional. Wir empfehlen jedoch, einen Richtungsanzeiger für alle neuen Routinen mit beliebigem Typ festzulegen.
  2. 2. Wenn die Klausel NAMESPACE oder NAME verwendet wird, ist ihr Wert implizit konstant und hat den Typ CHARACTER (Zeichen). Informationen zur Verwendung von CONSTANT-Variablen finden Sie in der DECLARE-Anweisung.
  3. 3. Hat die Routine den Typ FUNCTION, kann für LANGUAGE nicht DATABASE angegeben werden.

Übersicht

Die Anweisungen CREATE FUNCTION und CREATE PROCEDURE definieren eine aufrufbare Funktion oder Prozedur, die i. d. R. als "Routine" bezeichnet wird.

Anmerkung: In früheren Produktversionen wurden die Anweisungen CREATE FUNCTION und CREATE PROCEDURE anders eingesetzt und hatten andere Funktionen. Sie sind mittlerweile jedoch weiterentwickelt worden, so dass es nur noch wenige Unterschiede gibt. Die Unterschiede zwischen Funktionen und Prozeduren sind unter 1 und 3 unterhalb des Syntaxdiagramms aufgelistet.

Routinen sind bei der Erstellung wiederverwendbarer Codeblöcke hilfreich, die unabhängig mehrere Male ausgeführt werden können. Sie lassen sich als Reihe von ESQL-Anweisungen, als Java-Methode oder als in einer Datenbank gespeicherte Prozedur implementieren. Diese Vielfalt der Implementierungsmöglichkeiten bedeutet, dass einige der Klauseln im Syntaxdiagramm nicht für alle Routinetypen zutreffen (oder nicht zulässig sind).

Jede Routine hat einen Namen, der innerhalb des Schemas, der die Routine angehört, eindeutig sein muss. Routinenamen können daher nicht überladen werden: wenn der Broker eine überladene Routine feststellt, gibt er eine Ausnahmebedingung aus.

Die LANGUAGE-Klausel gibt die Sprache an, in der der Hauptteil der Routine geschrieben wird. Folgende Optionen stehen zur Verfügung:
DATABASE
Die Prozedur wird als eine in einer Datenbank gespeicherte Prozedur aufgerufen.
ESQL
Die Prozedur wird als eine ESQL-Routine aufgerufen.
JAVA
Die Prozedur wird als eine statische Methode in einer Java-Klasse aufgerufen.
Nicht angegeben
Wenn Sie die LANGUAGE-Klausel nicht angeben, wird als Standardsprache ESQL verwendet, es sei denn, Sie geben die Klausel EXTERNAL NAME an. In diesem Fall wird als Standardsprache DATABASE verwendet.
Die Verwendung der LANGUAGE-Klausel unterliegt Einschränkungen. Folgendes darf nicht verwendet werden:
  • Die ESQL-Option mit einer EXTERNAL NAME-Klausel
  • Die Optionen DATABASE oder JAVA ohne eine EXTERNAL NAME-Klausel
  • Die DATABASE-Option mit dem Routinetyp FUNCTION

Geben Sie den Namen der Routine mit der Klausel RoutineName und die Parameter der Routine mit der Klausel ParameterList an. Wenn die LANGUAGE-Klausel ESQL angibt, muss die Routine unter Verwendung einer einzelnen ESQL-Anweisung implementiert werden. Diese Anweisung ist sehr nützlich, wenn es sich um eine Verbindungsanweisung handelt (BEGIN ... END), da sie dann so viele ESQL-Anweisungen enthalten kann, wie zur Ausübung ihrer Funktionen erforderlich sind.

Alternativ können Sie in der LANGUAGE-Klausel eine andere Sprache als ESQL angeben, anstatt einen ESQL-Hauptteil für die Routine bereitzustellen. Auf diese Weise sind Sie in der Lage, mit der EXTERNAL NAME-Klausel auf den tatsächlichen Hauptteil der Routine zu verweisen, wenn er extern zum Broker lokalisiert ist. Weitere Informationen zur Verwendung der EXTERNAL NAME-Klausel finden Sie unter Gespeicherte Prozeduren aufrufen und Eine Java-Routine aufrufen.

Routinen mit beliebigem LANGUAGE-Typ können die Parameter IN, OUT und INOUT haben. Auf diese Weise kann der Aufrufende mehrere Werte in die Routine einstellen sowie mehrere aktualisierte Werte zurückempfangen. Dies ist ergänzend zu möglichen RETURNS-Klauseln, die die Routine haben kann. Die RETURNS-Klausel ermöglicht der Routine, einen Wert an den Aufrufenden zurückzuleiten.

Routinen, die in verschiedenen Sprachen implementiert sind, haben ihre eigenen Einschränkungen dahingehend, welche Datentypen eingestellt oder zurückgegeben werden können. Sie sind nachfolgend dokumentiert. Der Datentyp des zurückgegebenen Wertes muss dem Datentyp des Wertes entsprechen, der laut Definition von der Routine zurückgegeben werden soll. Wenn eine Routine laut Definition einen Rückgabewert haben soll, kann ihn der Aufrufende der Routine nicht ignorieren. Ausführliche Informationen finden Sie in der Die Anweisung CALL.

Routinen lassen sich in einem Modul oder in einem Schema definieren. In einem Modul definierte Routinen liegen im lokalen Bereich des aktuellen Knotens, d. h. sie können nur von Code aufgerufen werden, der demselben Modul (oder Knoten) angehört. Routinen, die in Schemabereichen definiert sind, können jedoch von einem der folgenden Codes aufgerufen werden:
  • Code im selben Schema.
  • Code in einem anderen Schema, wenn eines der folgenden Szenarios gilt:
    1. Die PATH-Klausel des anderen Schemas enthält den Pfad zur aufgerufenen Routine oder
    2. Die aufgerufene Routine wird unter Verwendung ihres vollständig qualifizierten Namens (bestehend aus ihrem Namen, dem ihr Schemaname - getrennt durch einen Punkt - vorangestellt ist).
Wenn Sie also dieselbe Routine in mehreren Knoten aufrufen möchten, definieren Sie sie in einem Schema.

Bezüglich der Sprache oder des Routinetyps muss die Methode des Aufrufens der Routine der Methode ihrer Deklaration entsprechen. Wenn die Routine eine RETURNS-Klausel besitzt, verwenden Sie entweder die Aufrufsyntax FUNCTION oder eine CALL-Anweisung mit einer INTO-Klausel. Umgekehrt gilt: Hat eine Routine keine RETURNS-Klausel, müssen Sie eine CALL-Anweisung ohne INTO-Klausel verwenden.

Parameterrichtungen

Routinen, die an Parameter übermittelt werden, ist auch stets eine Richtung zugeordnet. Möglich sind jeweils:
IN
Der Wert des Parameters kann nicht von der Routine geändert werden. Ein NULL-Wert für den Parameter ist zulässig und kann an die Routine übermittelt werden.
OUT
Wenn er von der aufgerufenen Routine empfangen wird, hat der in die Routine eingestellte Parameter immer den Wert NULL als korrekten Datentyp. Dies geschieht unabhängig davon, welchen Wert er vor Aufruf der Routine hatte. Die Routine darf den Wert des Parameters ändern.
INOUT
INOUT ist sowohl ein IN-Parameter als auch ein OUT-Parameter. Er stellt einen Wert in die Routine, der dann von ihr geändert werden kann. Ein NULL-Wert für den Parameter ist zulässig und kann sowohl in die Routine eingestellt als auch aus ihr heraus übermittelt werden.

Hat die Routine den Typ FUNCTION (Funktion), ist der Richtungsanzeiger (IN, OUT, INOUT) optional für jeden Parameter. Wir empfehlen jedoch dringend, einen Richtungsanzeiger für alle neuen Routinen mit beliebigem Typ festzulegen.

ESQL-Variablen, die als CONSTANT deklariert sind (oder Verweise auf als CONSTANT deklarierte Variablen) dürfen nicht die Richtung OUT oder INOUT haben.

ESQL-Routinen

ESQL-Routinen sind in ESQL geschrieben, und ihre LANGUAGE-Klausel gibt die Sprache ESQL an. Als Hauptteil einer ESQL-Routine wird für gewöhnlich eine Verbindungsanweisung in der Form von BEGIN … END verwendet, die mehrere Anweisungen zur Verarbeitung der Parameter enthält, die an die Routine übermittelt wurden.

ESQL-Beispiel 1

Im nachfolgenden Beispiel wird dieselben Prozedur wie in Beispiel 1 einer Datenbankroutine angezeigt, allerdings als ESQL-Routine und nicht als eine gespeicherte Prozedur implementiert. Die CALL-Syntax und Ergebnisse dieser Routine sind mit denen in Einschränkungen bei Java-Routinen identisch.
CREATE PROCEDURE swapParms (
  IN parm1 CHARACTER,
  OUT parm2  CHARACTER,
  INOUT parm3 CHARACTER )
BEGIN   
   SET parm2 = parm3;
   SET parm3 = parm1;
              END;

ESQL-Beispiel 2

Diese Beispielprozedur zeigt die rekursive Verwendung einer ESQL-Routine. Sie analysiert die Syntax einer Baumstruktur an sämtlichen Stellen am und unterhalb des angegebenen Ausgangspunkts und dokumentiert anschließend das Ergebnis:

SET OutputRoot.MQMD = InputRoot.MQMD;

  DECLARE answer CHARACTER;
  SET     answer = '';

  CALL navigate(InputRoot.XML, answer);
  SET OutputRoot.XML.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;

Lautet die Eingabenachricht wie folgt:

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

dann erstellt die Prozedur die folgende Ausgabe, die manuell formatiert wurde:

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 

Java-Routinen

Eine Java-Routine ist als Java-Methode implementiert und hat die LANGUAGE-Klausel JAVA. Bei Java-Routinen muss der ExternalRoutineName (externe Routinename) den Klassennamen und den Namen der Java-Methode enthalten, die aufgerufen wird. Geben Sie den ExternalRoutineName wie folgt an:
 >>--"-- Name_der_Klasse---.---Name_der_Methode--"--------------><
dabei steht Name_Klasse für die Klasse, die die Methode enthält, und Name_der_Methode gibt die Methode an, die aufgerufen werden soll. Wenn die Klasse Teil eines Pakets ist, muss der Teil mit dem Klassenbezeichner das komplette Paketpräfix einschließen, z. B. "com.ibm.broker.test.MyClass.myMethod".

Um nach der Java-Klasse suchen, geht der Broker wie im Abschnitt Implementierung von Java-Klassen beschrieben vor.

Jede Java-Methode, die Sie aufrufen möchten, muss die folgende Basissignatur haben:
öffentlich statisch <Rückgabetyp> <Methodenname> (< 0 - N Parameter>)

wobei der <Rückgabetyp> aus der Liste der Java-Datentypen IN aus der Tabelle in derZuordnung von ESQL zum Java-Datentyp stammen muss und sowohl den Typ REFERENCE ausschließen muss, da er als Rückgabetyp nicht zulässig ist, als auch den typenlosen Java-Datentyp. Die Parameterdatentypen müssen ebenfalls aus der Tabelle der Zuordnung von ESQL zum Java-Datentyp stammen. Zudem darf die Java-Methode keine exception throws-Klausel (Ausnahmeauslöser) in ihrer Signatur haben.

Die Signatur der Java-Methode muss der ESQL-Routinedeklaration der Methode entsprechen. Desweiteren müssen Sie folgende Regeln beachten:
  • Stellen Sie sicher, dass der Name der Java-Methode einschließlich Klassenname sowie Paketqualifikationsmerkmale dem externen Namen (EXTERNAL NAME) der Prozedur entsprechen.
  • Stellen Sie sicher, dass die Java-Methode threadsicher ist (simultan verwendbar).
  • Ist der Java-Rückgabetyp typenlos, sollten Sie keine RETURNS-Klausel in die Definition der ESQL-Routine stellen.
  • Geben Sie keinen REFERENCE-Datentyp aus der Java-Methode zurück.
  • Stellen Sie sicher, dass alle Parametertypen und -richtungen gemäß den in der Tabelle in der Zuordnung von ESQL zum Java-Datentyp aufgelisteten Regeln der ESQL-Deklaration entsprechen.
  • Stellen Sie sicher, dass der Rückgabetyp der Methode dem Datentyp der RETURNS-Klausel entspricht.
  • Stellen Sie den EXTERNAL NAME (externen Namen) in Anführungszeichen, da er mindestens “class.method” (Klasse.Methode) enthalten muss.
  • Es sind nur JDBC-Datenbankverbindungen des Typs 4 zulässig.
Sie können in Ihrer Java-Methode die Java-Plug-in-Knoten-API verwenden. Um die Java-Plug-in-Knoten-Api zu verwenden, müssen Sie die Datei jplugin2.jar in eines der folgenden Verzeichnisse verschieben:
  • CLASSPATH des Brokers
  • Brokerarchivdatei (BAR)
Weitere Informationen zur Installation von jplugin2.jar finden Sie im Abschnitt Benutzerdefinierten Java-Knoten kompilieren.

Beispiel 1 einer Java-Routine

Diese Routine enthält drei Parameter unterschiedlicher Richtungen und gibt eine Ganzzahl zurück, die dem Java-Rückgabetyp java.lang.Long entspricht.

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

Sie können für den Aufruf von myProc1 folgenden ESQL-Ausdruck verwenden:

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

Beispiel 2 einer Java-Routine

Diese Routine enthält drei Parameter unterschiedlicher Richtungen und hat den Java-Rückgabetyp void (typenlos).

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

Sie müssen für den Aufruf von myProc2 folgenden ESQL-Ausdruck verwenden:

CALL myProc2(intVar1, intVar2, intVar3);

Die folgende Java-Klasse bietet eine Methode für jedes der Java-Beispiele:

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) { ... }

 /*  Wenn eine der Methoden aufgerufen wird:
    P1 kann den Wert NULL haben oder nicht (abhängig vom Wert von intVar1).
    P2[0] hat stets den Wert NULL (unabhängig vom Wert von intVar2).
    P3[0] kann den Wert NULL haben oder nicht (abhängig vom Wert von intVar3).
    Alles entspricht der Verwendung von LANGUAGE ESQL-Routinen.
    Wenn diese Methoden Werte zurückgeben:
         intVar1 ist unverändert
         intVar2 kann immer noch den Wert NULL oder einen anderen Wert haben
         intVar3 kann denselben Wert oder einen anderen Wert haben
     Alles entspricht der Verwendung von LANGUAGE ESQL-Routinen.
     
    Wenn myMethod1 Folgendes zurückgibt: intReturnVar3 ist entweder NULL (wenn die
    Methode NULL zurückgibt) oder enthält den Wert, den die
    Methode zurückgegeben hat.
 */
}

Zuordnung von ESQL zum Java-Datentyp

In der folgenden Tabelle wird die Zuordnung von ESQL zu Java zusammengefasst.
Anmerkungen:
  • Nur die Java-Skalarwrapper werden an Java übergeben.
  • Die ESQL-Skalartypen werden als Objektwrapper oder Objektwrappergruppen zu Java-Datentypen zugeordnet, je nach Richtung des Prozedurparameters. Jeder Wrapperbereich enthält genau ein Element.
  • Durch die Verwendung von Skalarobjektwrappern können NULL-Werte an Java-Methoden übermittelt und von dort abgerufen werden.
ESQL-Datentypen 1 Datentypen Java IN Datentypen Java INOUT und 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 Nicht unterstützt Nicht unterstützt
BOOLEAN java.lang.Boolean java.lang.Boolean[]
REFERENCE (auf eine Nachrichtenbaumstruktur) 3 4 5 6 com.ibm.broker.plugin.MbElement com.ibm.broker.plugin.MbElement[] (Wird für INOUT unterstützt, nicht für OUT)
ROW Nicht unterstützt Nicht unterstützt
LIST Nicht unterstützt Nicht unterstützt
  1. Als CONSTANT deklarierte Variablen (oder Referenzen auf Variablen, die als CONSTANT deklariert werden) dürfen nicht über die Richtungen INOUT oder OUT verfügen.
  2. Die in der Java-Variablen gesetzte Zeitzone spielt keine Rolle; die erforderliche Zeitzone wird durch die Ausgabe-ESQL abgerufen.
  3. Der Verweisparameter kann bei Übergabe an eine Java-Methode nicht den Wert NULL haben.
  4. Der Verweis kann bei Übergabe an eine Java-Methode nicht die Richtung OUT haben.
  5. Wenn ein MbElement von Java als INOUT-Parameter an ESQL zurückgegeben wird, muss es auf eine Position in derselben Nachrichtenbaumstruktur verweisen wie die, auf die das MbElement bei der Übergabe an die aufgerufene Java-Methode verwies.

    Wenn beispielsweise ein ESQL-Verweis auf OutputRoot.XML.Test als INOUT-MbElement an eine Java-Methode übergeben wird, bei Rückkehr des Aufrufs aber ein anderes MbElement an ESQL zurückgegeben wird, muss dieses andere Element ebenfalls auf eine Position innerhalb der OutputRoot-Baumstruktur verweisen.

  6. Ein MbElement kann nicht mit der RETURNS-Klausel an eine Java-Methode zurückgegeben werden, da dieser Verweis von einer ESQL-Routine nicht zurückgegeben werden kann. Dagegen kann ein MbElement (unter Berücksichtigung der oben unter 5 aufgeführten Bedingungen) als INOUT-Richtungsparameter zurückgegeben werden.

Ein Verweis auf eine Skalarvariable kann im Aufruf einer Java-Methode verwendet wurde, vorausgesetzt, der Datentyp der Variablen, auf die verwiesen wird, entspricht dem entsprechenden Datentyp in der Java-Programmsignatur.

Einschränkungen bei Java-Routinen

Implementierung von Java-Klassen

Es wird empfohlen, die Java-Klassen innerhalb eines Java-Archivs (JAR-Datei) einzusetzen. Es gibt zwei Methoden, um eine JAR-Datei im Broker einzusetzen:
  1. Durch Hinzufügen der Datei zu einer BAR-Datei

    Die Verwendung dieser Methode wird empfohlen.

    Sie können die JAR-Datei manuell oder automatisch unter Verwendung der Tools zur BAR-Datei hinzufügen. Die Verwendung der Tools wird empfohlen.

    Wenn die Tools die korrekte Java-Klasse in einem geöffneten Java-Projekt im Arbeitsbereich finden, wird die Java-Klasse automatisch in eine JAR-Datei kompiliert und zur BAR-Datei hinzugefügt. Diese Prozedur ist mit der Prozedur für die Implementierung eines Java-Rechenknotens in einer JAR-Datei identisch (siehe Klassenladen für benutzerdefinierte Knoten.

    Wenn Sie eine JAR-Datei unter Verwendung der Tools implementieren, werden bei der erneuten Implementierung der BAR-Datei, die die JAR-Datei enthält, die Java-Klassen, auf die verwiesen wird, vom neu implementierten Fluss erneut geladen; dasselbe passiert, wenn ein Nachrichtenfluss, der auf eine Java-Klasse verweist, gestoppt und neu gestartet wird. Stellen Sie sicher, dass Sie alle Flüsse, die auf die zu aktualisierende JAR-Datei verweisen, stoppen und neu starten (bzw. erneut implementieren). Damit verhindern Sie, dass einige Flüsse mit der alten Version der JAR-Datei und andere Flüsse mit der neuen Version ausgeführt werden.

    Hinweis: Von den Tools werden nur JAR-Dateien und keine eigenständigen Java-Klassendateien implementiert.

  2. Durch Hinzufügen zum bzw. zur:
    1. Ordner <Arbeitspfad>/shared-classes/ auf der Maschine, auf der der Broker ausgeführt wird
    2. Umgebungsvariablen CLASSPATH auf der Maschine, auf der der Broker ausgeführt wird

    Diese Prozedur muss manuell ausgeführt werden. Die Tools können für diesen Vorgang nicht verwendet werden.

    Bei diesem Verfahren werden bei einer erneuten Implementierung des Nachrichtenflusses die Java-Klassen, auf die verwiesen wird, nicht erneut geladen, und der Nachrichtenfluss wird nicht gestoppt und neu gestartet. In diesem Fall können die Klassen nur neu geladen werden, indem Sie den Broker stoppen und neu starten.

    Obwohl Sie eine eigenständige Java-Klasse implementieren können, indem Sie sie in eines der oben genannten Verzeichnisse verschieben, wird dennoch die Verwendung einer JAR-Datei empfohlen.

Damit der Broker eine Java-Klasse finden kann, müssen Sie sicherstellen, da sie sich in einem der oben genannten Verzeichnisse befindet. Wenn der Broker die angegebene Klasse nicht finden kann, löst er eine Ausnahme aus.

Obwohl Ihnen die oben genannten Auswählmöglichkeiten für die Implementierung der JAR-Datei zur Verfügung stehen, wird die Anwendung der ersten Methode (Implementierung der BAR-Datei durch die Tools zulassen) empfohlen, da diese Methode die größte Flexibilität für die erneute Implementierung der JAR-Datei bietet.

Datenbankroutinen

Datenbankroutinen sind Routinen, die als in Datenbank gespeicherte Prozeduren implementiert werden. Ihre LANGUAGE-Klausel lautet DATABASE, und sie müssen den Routinetyp PROCEDURE haben.

Beim Schreiben gespeicherter Prozeduren in Sprachen wie C müssen Sie NULL-Anzeiger verwenden, um zu gewährleisten, dass Ihre Prozedur die Daten ordnungsgemäß verarbeiten kann.

Obwohl die Datenbankdefinitionen einer gespeicherten Prozedur zwischen den Datenbanken variieren, ist dies für die ESQL, gilt dies nicht für die ESQL, mit der sie aufgerufen werden. Die Namen, die Parametern im ESQL-Ausdruck zugeordnet werden, müssen nicht mit den in der Datenbank angegebenen Namen übereinstimmen. Der externe Name der Routine - einschließlich aller Paket- oder Containerspezifikationen - muss jedoch seinem definiertem Namen in der Datenbank entsprechen.

Die Klausel DYNAMIC RESULT SET ist nur für Datenbankroutinen zulässig. Sie ist nur erforderlich, wenn eine gespeicherte Prozedur mehrere Ergebnismengen zurückgibt. Der Ganzzahlparameter für diese Klausel muss 0 (Null) oder mehr sein und die Anzahl der Ergebnismengen angeben, die zurückgegeben werden sollen.

Die optionale RETURNS-Klausel ist erforderlich, wenn eine gespeicherte Prozedur einen einzelnen skalaren Wert zurückgibt.

Die Klausel EXTERNAL NAME gibt den Namen an, unter dem die Datenbank die Routine kennt. Dies kann ein qualifizierter oder ein nicht qualifizierter Name sein, wobei das Qualifikationsmerkmal der Name des Datenbankschemas ist, in dem die Prozedur definiert ist. Wenn Sie keinen Schemanamen angeben, wird der Benutzername der Datenbankverbindung als das Schema verwendet, in dem sich die Prozedur befindet. Ist die erforderliche Prozedur nicht in diesem Schema vorhanden, müssen Sie einen expliziten Schemanamen angeben - entweder in der Routinedefinition oder in der Anweisung zum Aufrufen der Routine bei Laufzeit. Weitere Informationen zur dynamischen Auswahl des Schemas, das die Routine enthält, finden Sie in der Die Anweisung CALL. Wenn ein qualifizierter Name verwendet wird, muss der Name in Anführungszeichen gesetzt werden.

Eine vollständig qualifizierte Routine hat normalerweise folgende Form:
 EXTERNAL NAME "mySchema.myProc";
Gehört die Prozedur jedoch zu einem Oracle-Paket, wird das Paket als Teil des Prozedurnamens behandelt. Geben Sie daher wie folgt einen Schemanamen sowie den Paketnamen an:
EXTERNAL NAME "mySchema.myPackage.myProc";  

Auf diese Weise kann zwar das Schema, aber nicht der Paketname, in der CALL-Anweisung dynamisch gewählt werden.

Wenn der Name der Prozedur SQL-Platzhalter enthält (das Prozentzeichen (%) und der Unterstrich (_)), wird die Prozedur vom Broker so geändert, dass sie das Datenbank-Escapezeichen direkt vor dem Platzhalter aufführen. Damit wird sichergestellt, dass die Datenbank die Platzhalter als Literale empfängt. Beispielsweise wurde die nachfolgende Klausel vom Broker geändert, und “mySchema.Proc\_” wird an die Datenbank übermittelt (vorausgesetzt, dass es sich bei dem Datenbank-Escapezeichen um einen Backslash (umgekehrter Schrägstrich) handelt). ;
EXTERNAL NAME "mySchema.Proc_";  
Für alle externen Prozeduren gelten folgende Einschränkungen:
  • Eine gespeicherte Prozedur kann in der Datenbank nicht überladen werden. Sie gilt als überladen, wenn mehrere Prozeduren mit identischem Namen im selben Datenbankschema existieren. Wenn der Broker eine überlappende Prozedur findet, wird eine Ausnahme ausgegeben.
  • Parameter dürfen nicht den Datentyp ESQL REFERENCE, ROW, LIST oder INTERVAL haben.
  • Benutzerdefinierte Namen können nicht als Parameter oder als Rückgabewerte verwendet werden.

Beispiel 1 einer Datenbankroutine

Nachfolgend sehen Sie die einfache ESQL-Definition einer gespeicherten Prozedur, die einen einzelnen skalaren Wert und einen OUT-Parameter zurückgibt:

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

Rufen Sie die Routine myProc1 mit folgender ESQL auf:

/*mittels der Aufrufsyntax der CALL-Anweisung*/
CALL myProc1(intVar1, intVar2) INTO intReturnVar3;

/*oder mittels der Funktionsaufrufsyntax*/
SET intReturnVar3 = myProc1(intVar1, intVar2);

Beispiel 2 einer Datenbankroutine

Der nachfolgende ESQL-Code zeigt, wie in DB2 und Oracle gespeicherte Prozeduren definiert und aufgerufen werden:

ESQL-Definition:
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
) EXTERNAL NAME dbSwapParms;

Um diese gespeicherte Prozedur in DB2 einzutragen, kopieren Sie das folgende Script in eine Datei (z. B. test1.sql), und führen Sie an der DB2-Befehlseingabeaufforderung Folgendes aus:

db2 -td@ -vf 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 @

Um diese gespeicherte Prozedur in Oracle einzutragen, kopieren Sie das folgende Script in eine Datei (z. B. test1.sql), und führen Sie Folgendes aus:

sqlplus <Benutzer-ID>/<Kennwort>  @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;
/
Erwarten Sie von der Ausführung dieses Codes folgende Ergebnisse:
  • Der Wert des IN-Parameters ändert sich nicht (und kann sich laut Definition nicht ändern).
  • Der Wert des OUT-Parameters wird zu "World".
  • Der Wert des INOUT-Parameters wird zu "Hello".

Beispiel 3 einer Datenbankroutine


Dieses Beispiel zeigt, wie Sie eine gespeicherte Prozedur aufrufen, die zwei Ergebnismengen und einen OUT-Parameter zurückgibt:

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

Rufen Sie myProc1 mit folgender ESQL auf:

/* using a field reference */
CALL myProc1(intVar1, intVar2, Environment.RetVal[], OutputRoot.XML.A[])/* using a reference variable*/
CALL myProc1(intVar1, intVar2, myReferenceVariable.RetVal[], myRef2.B[])
Zugehörige Konzepte
Übersicht zu ESQL
Zugehörige Tasks
ESQL erstellen
Gespeicherte Prozeduren aufrufen
Zugehörige Verweise
Syntaxdiagramme: verfügbare Typen
ESQL-Anweisungen
Die Anweisung CALL
Tabelle für die Zuordnung von ESQL- zu Java-Datentypen
Bemerkungen | Marken | Downloads | Bibliothek | Unterstützung | Rückmeldung
Copyright IBM Corporation 1999, 2005 Letzte Aktualisierung: Nov 17, 2005
ak04970_