Natural for Db2 unterstützt das Schreiben und Ausführen von Natural Stored Procedures und Natural User-Defined Functions (Natural UDFs).
Natural Stored Procedures sind vom Benutzer geschriebene Programme, die durch das
SQL-Statement CALL aufgerufen und von Db2 im SPAS (Stored Procedure Address
Space) ausgeführt werden. SPAS ist ein separater Adressraum, der für Stored Procedures
reserviert ist.
Eine Function ist eine Operation, die durch einen Funktionsnamen, gefolgt von null oder mehr Operanden, die in Klammern eingeschlossen sind, bezeichnet wird. Eine Function stellt eine Beziehung zwischen einer Menge von Eingabewerten und einer Menge von Ergebniswerten dar. Wenn eine Function durch ein vom Benutzer geschriebenes Programm implementiert wurde, wird sie in Db2 als User-Defined Function (UDF) bezeichnet.
Die folgenden Themen werden in diesem Kapitel behandelt:
Es gibt zwei Typen von Natural Used Defined Functions (UDF):
Die skalare UDF akzeptiert mehrere Eingangsargumente und gibt einen Ausgangswert zurück. Sie kann durch ein beliebiges SQL-Statement so wie eine eingebaute Db2-Funktion (Db2 Built-in Function) aufgerufen werden.
Die Tabellen-UDF akzeptiert mehrere Eingabeargumente und gibt bei jedem Aufruf eine Menge von Ausgabewerten zurück, die eine Tabellenzeile umfassen.
Sie können eine Tabellen-UDF mit einem Natural-SQL-SELECT-Statement aufrufen, indem
Sie den Namen der Tabellenfunktion in der FROM-Klausel angeben. Eine Tabellen-UDF verhält
sich wie eine Db2-Tabelle und wird bei jeder FETCH-Operation für die in
dem SELECT-Statement angegebene Tabellenfunktion aufgerufen.
Mit PARAMETER STYLE wird die Linkage-Konvention identifiziert, die zur
Übergabe von Parametern an eine Db2 Stored Procedure oder eine Db2 User Defined Function
(UDFs) verwendet wird.
Dieser Abschnitt beschreibt die PARAMETER STYLEs und die STCB, die Natural
for Db2 für die Verarbeitung von Natural for Db2 Stored Procedures oder Natural UDFs
verwendet.
AnmerkungPARAMETER STYLE GENERAL (oder GENERAL WITH NULL) und
STCB Layout gelten
nur für Natural Stored Procedures.
Anmerkung
Gilt nur für Natural Stored Procedures.
Eine Natural Stored Procedure, die mit PARAMETER STYLE GENERAL definiert
ist, erhält nur die angegebenen Benutzerparameter.
Eine Natural Stored Procedure, die mit PARAMETER STYLE GENERAL WITH NULL
definiert ist, erhält die angegebenen Benutzerparameter und zusätzlich ein
NULL-Indikator-Array, das einen NULL-Indikator für jeden
Benutzerparameter enthält.
Natural Stored Procedures, die mit PARAMETER STYLE GENERAL/PARAMETER
STYLE GENERAL WITH NULL definiert sind, erfordern, dass die Definition der
Stored Procedure im Db2-Katalog einen zusätzlichen Parameter vom Typ
VARCHAR vor den Benutzerparametern der Stored Procedure
enthält.
Dieser Parameter vor den Parametern ist der Stored Procedure Control Block (STCB), siehe auch STCB Layout weiter unten.
Nachfolgend finden Sie Informationen über:
Der Stored Procedure Control Block (STCB) enthält Informationen, die der Stub des Natural for Db2-Servers zur Ausführung von Natural Stored Procedures verwendet, z. B. die Library und das aufzurufende Subprogramm. Er enthält auch die Formatbeschreibungen der Parameter, die an die Stored Procedure übergeben werden.
Die STCB ist für die aufgerufene Natural Stored Procedure unsichtbar. Die STCB wird vom Natural for Db2 Server Stub ausgewertet und aus der Parameterliste entfernt, die an die Natural Stored Procedure übergeben wird.
Wenn der Aufrufer einer Natural Stored Procedure, die mit PARAMETER STYLE
GENERAL/PARAMETER STYLE GENERAL WITH NULL definiert ist, ein
Natural-Programm ist, muss das Programm ein Natural-SQL-Statement CALLDBPROC mit dem
Schlüsselwort CALLMODE=NATURAL verwenden.
Wenn der Aufrufer der Natural Stored Procedure kein Natural-Programm ist, muss der
Aufrufer die STCB für das Db2 CALL-Statement einrichten und die STCB als
ersten Parameter übergeben.
Wenn bei der Ausführung einer Natural Stored Procedure, die mit PARAMETER STYLE
GENERAL/PARAMETER STYLE GENERAL WITH NULL definiert ist, ein
Fehler auftritt, wird der Text der Fehlermeldung an die STCB zurückgegeben.
Wenn der Aufrufer ein Natural-Programm ist, das CALLDBPROC und CALLMODE=NATURAL verwendet, dann fügt die Natural for
Db2-Laufzeit den Fehlertext in die Fehlermeldung NAT3286 ein.
Definieren Sie in der Natural Stored Procedure die Parameter wie im folgenden Beispielprogramm gezeigt:
DEFINE DATA PARAMETER 01 P1 ... 01 P2 ... ... ... 01 Pn ... LOCAL ... ... END-DEFINE
Definieren Sie in der Natural Stored Procedure die Parameter wie im folgenden Beispielprogramm gezeigt:
DEFINE DATA PARAMETER 01 P1 ... 01 P2 ... ... ... 01 Pn ... 01 NULL-INDICATOR-ARRAY (I2/1:n) LOCAL ... ... END-DEFINE
Anmerkung
Gilt nur für Natural Stored Procedures.
Die folgende Tabelle beschreibt den ersten Parameter, der zwischen dem Aufrufer und der
Natural Stored Procedure übergeben wird, wenn CALLMODE=NATURAL in einem Natural SQL CALLDBPROC-Statement angegeben
ist.
| Name | Format | Verarbeitungsmodus-Server |
|---|---|---|
STCBL |
I2 | Eingabe (Größe der folgenden Informationen) |
|
Prozedur-Informationen
|
||
STCBLENG |
A4 | Eingabe (druckbare STCBL) |
STCBID |
A4 | Eingabe (STCB) |
STCBVERS |
A4 | Eingabe (Version von STCB 310) |
STCBUSER |
A8 | Eingabe (Benutzerkennung) |
STCBLIB |
A8 | Eingabe (Library) |
STCBPROG |
A8 | Eingabe (aufrufendes Programm) |
STCBPSW |
A8 | Ungenutzt (Passwort) |
STCBSTNR |
A4 | Eingabe (CALLDBPROC-Statement-Nummer)
|
STCBSTPC |
A8 | Eingabe (aufgerufene Prozedur) |
STCBPANR |
A4 | Eingabe (Anzahl der Parameter) |
|
Fehlerinformationen
|
||
STCBERNR |
A5 | Ausgabe (Natural-Fehlernummer) |
STCBSTAT |
A1 | Ungenutzt (Natural-Fehlerstatus) |
STCBLIB |
A8 | Ungenutzt (Natural-Fehler-Library) |
STCBPRG |
A8 | Ungenutzt (Natural-Fehlerprogramm) |
STCBLVL |
A1 | Ungenutzt (Natural-Fehlerebene) |
STCBOTP |
A1 | Ungenutzt (Fehlerobjekttyp) |
STCBEDYL |
A2 | Ausgabe (Fehlertextlänge) |
STCBEDYT |
A88 | Ausgabe (Fehlertext) |
| A100 | Reserviert für zukünftige Verwendung | |
|
Parameter Informationen
|
||
STCBPADE |
A variable | Eingabe. Siehe auch PARAMETER DESCRIPTION (STCBPADE) weiter unten. |
PARAMETER DESCRIPTION enthält eine Beschreibung zu jedem an die Natural
Stored Procedure übergebenen Parameter, bestehend aus Parametertyp, Formatangabe und
Länge. Der Parametertyp ist das Attribut AD des Natural-CALLNAT-Statements, wie in der
Natural-Statements-Dokumentation beschrieben.
Jeder Parameter hat das folgende Formatbeschreibungselement in der STCBPADE-Zeichenkette
atl,p[,d1]....
Bedeutung:
a ist eine Attributmarkierung, die den
Parametertyp angibt:
| Markierung | Typ |
Äquivalentes |
Äquivalente |
|---|---|---|---|
M |
änderbar | AD=M |
INOUT |
O |
nicht änderbar | AD=O |
IN |
A |
nur Eingabe | AD=A |
OUT |
t ist eines der folgenden
Natural-Format-Token:
l ist eine Ganzzahl, die die
Länge/Skalierung des Feldes angibt.
Bei numerischen und gepackten numerischen Feldern gibt
l die Gesamtzahl der Ziffern des
Feldes an, d. h. die Summe der Ziffern links und rechts vom Dezimalpunkt. Das
Natural-Format N7.3 wird z. B. durch N10.3 dargestellt. Siehe auch die obige
Tabelle.
p ist eine Ganzzahl, die die Genauigkeit
des Feldes angibt. Normalerweise ist sie 0, außer bei numerischen und
gepackten Feldern, wo sie die Anzahl der Stellen rechts vom Dezimalpunkt angibt.
Siehe auch die obige Tabelle.
d1 ist ebenfalls eine Ganzzahl, die die
Anzahl der Ausprägungen im alphanumerischen Feld angibt (nur alphanumerisch).
Siehe auch die obige Tabelle.
Dieser Beschreibungs-/Kontrollparameter ist für das aufrufende Natural-Programm und
die aufgerufene Natural-Stored-Procedure unsichtbar, muss aber in der
Parameterdefinition der Stored-Procedure-Zeile mit dem CREATE
PROCEDURE-Statement und dem Db2 PARAMETER STYLE
GENERAL/PARAMETER STYLE GENERAL WITH NULL definiert werden.
Die folgende Tabelle zeigt die Anzahl der Parameter, die mit dem CREATE
PROCEDURE-Statement für eine mit PARAMETER STYLE GENERAL
definierte Natural Stored Procedure definiert werden müssen, abhängig von der Anzahl
der Benutzerparameter und davon, ob der Client (d.h. der Aufrufer einer Stored
Procedure für Db2) und der Server (d.h. die Stored Procedure für Db2) in Natural oder
in einer anderen Standardprogrammier-Hostsprache geschrieben ist.
n bezeichnet die Anzahl der
Benutzerparameter.
| Client\Server | Natural | Nicht Natural |
|---|---|---|
| Natural |
n + 1
|
n (CALLMODE=NONE)
|
| non-Natural |
n + 1
|
n
|
AnmerkungPARAMETER DB2SQL gilt für Natural Stored Procedures und Natural
UDFs.
Eine Natural Stored Procedure oder Natural User Defined Function (UDF) mit
PARAMETER STYLE DB2SQL empfängt zuerst die angegebenen Benutzerparameter
und dann die unten unter Zusätzlich übergebene Parameter aufgeführten
Parameter. Bei einer Natural UDF werden die Eingabeparameter vor den Ausgabeparametern
übergeben.
Ein NULL-Indikator für jeden Benutzerparameter des
CALL-Statement,
der SQLSTATE, der an Db2 zurückgegeben wird,
der qualifizierte Name der Natural Stored Procedure oder UDF,
der spezifische Name der Natural Stored Procedure oder UDF,
das Feld SQL DIAGNOSE mit einer an Db2 zurückzugebenden
Diagnosezeichenfolge.
Der SQLSTATE, der qualifizierte Name, der spezifische Name und das
DIAGNOSE-Feld sind im Natural-Parameterdatenbereich (PDA)
DB2SQL_P definiert, der in der Natural System Library SYSDB2
bereitgestellt wird.
Wenn im CREATE FUNCTION-Statement für die Natural UDF zusätzlich das
optionale Merkmal SCRATCHPAD nnn angegeben ist,
wird der Speicherparameter SCRATCHPAD an die Natural UDF übergeben.
Verwenden Sie die folgenden Definitionen:
01 SCRATCHPAD A(4+nnn) 01 REDEFINE SCRATCHPAD 02 SCRATCHPAD_LENGTH(I4) 02 ...
Definieren Sie das SCRATCHPAD in der Natural UDF entsprechend Ihren
Anforderungen um.
Die ersten vier Bytes des SCRATCHPAD-Bereichs enthalten ein Integer-Längenfeld. Vor dem
ersten Aufruf der Natural UDF mit einem SQL-Statement setzt Db2 den SCRATCHPAD-Bereich
auf x'00' zurück und setzt die für den SCRATCHPAD-Bereich angegebene Größe
nnn in die ersten vier Bytes als
Integer-Wert.
Danach initialisiert Db2 den SCRATCHPAD-Bereich zwischen den Aufrufen der Natural UDF für das aufrufende SQL-Statement nicht neu. Stattdessen wird der Scratchpad-Inhalt nach der Rückkehr von der Natural UDF beibehalten und beim nächsten Aufruf der Natural UDF wiederhergestellt.
Nachfolgend finden Sie Informationen über:
Anmerkung
Dieser Parameter ist optional und gilt nur für Natural UDFs.
Der Parameter CALL TYPE wird übergeben, wenn die Option FINAL
CALL für eine skalare Natural UDF angegeben ist oder wenn die Natural UDF
eine Tabellen-UDF ist. Der Parameter CALL TYPE ist eine Ganzzahl, die den
Typ des Aufrufs angibt, den Db2 für die Natural UDF durchführt.
Einzelheiten zu den im Parameter CALL_TYPE angegebenen Parameterwerten
finden Sie im Db2 SQL GUIDE.
Dieser Parameter ist optional.
Wenn die Option DBINFO verwendet wird, wird die
DBINFO-Struktur an die Natural-Stored-Procedure oder UDF übergeben. Die
DBINFO-Struktur ist in der Natural-PDA DBINFO_P
beschrieben, die in der Natural-System-Library SYSDB2 enthalten ist.
Der Server-Stub von Natural for Db2 ermittelt das Subprogramm und die Library aus dem qualifizierten und spezifischen Namen der Natural Stored Procedure oder UDF. Der SCHEMA-Name wird als Library-Name und der Prozedur- oder Funktionsname als Subprogramm-Name verwendet.
Das Subprogramm ROUTINEN wird in der Natural Library SYSDB2
bereitgestellt. Mit diesem Subprogramm wird auf den Db2-Katalog zugegriffen, um die
Formate der für die Natural Stored Procedure oder UDF definierten Benutzerparameter zu
ermitteln. Nachdem die Formate ermittelt wurden, werden sie im Natural-Buffer Pool
gespeichert. Bei nachfolgenden Aufrufen der Natural Stored Procedure werden die
Formate dann aus dem Natural Buffer Pool abgerufen. Dies erfordert, dass für Natural
Stored Procedures oder UDFs mit PARAMETER STYLE DB2SQL mindestens
READS SQL DATA angegeben ist.
Das Subprogramm ROUTINEN wird statisch generiert. Das DBRM von
ROUTINEN ist als Package in der COLLECTION
SAGNDBROUTINENPACK gebunden. Bevor der Zugriff auf den Db2-Katalog beginnt,
speichert das Subprogramm das CURRENT PACKAGESET und setzt
SAGNDBROUTINENPACK auf CURRENT PACKAGESET. Nach der
Verarbeitung stellt das Subprogramm ROUTINEN das gespeicherte
CURRENT PACKAGESET wieder her.
Wenn der Aufrufer der Natural Stored Procedure mit PARAMETER STYLE
DB2SQL ein Natural-Programm ist, muss der Aufrufer das Natural-SQL-Statement
CALLDBPROC mit der
Angabe CALLMODE=NATURAL verwenden, was der Standard ist.
Wenn während der Ausführung einer Natural Stored Procedure oder UDF mit
PARAMETER STYLE DB2SQL ein Natural-Laufzeitfehler auftritt, wird der
SQLSTATE auf 38N99 gesetzt und der Diagnose-String enthält den Text der
Natural-Fehlermeldung.
Wenn während der Ausführung einer Natural Stored Procedure oder UDF mit
PARAMETER STYLE DB2SQL ein Fehler im Natural for Db2 Server Stub
auftritt, wird der SQLSTATE auf 38S99 gesetzt und der
Diagnosestring enthält den Text der Fehlermeldung.
Wenn die Anwendung eine Fehlerbedingung während der Ausführung einer Natural Stored
Procedure oder UDF auslösen will, muss der Parameter SQLSTATE auf einen
anderen Wert als '00000' gesetzt werden. Im entsprechenden Db2
SQL Guide finden Sie Angaben zu Benutzerfehlern im
SQLSTATE-Parameter.
Zusätzlich kann ein Text, der die Fehler beschreibt, in den
DIAGNOSE-Parameter eingegeben werden.
Wenn eine Natural-Tabellen-UDF Db2 signalisieren will, dass sie keine Zeile gefunden
hat, die sie zurückgeben kann, muss im SQLSTATE-Parameter
'02000' zurückgegeben werden.
Bei einer Natural-UDF, die die Attribute DISALLOW PARALLEL und
FINAL CALL enthält, behält der Natural for Db2 Server Stub die zuvor
zugeordnete Natural-Sitzung bei. Diese Natural-Sitzung wird dann von allen
nachfolgenden UDF-Aufrufen wiederverwendet, bis Natural auf den letzten Aufruf
trifft.
Definieren Sie in einer Natural Stored Procedure die Parameter wie im folgenden Beispielprogramm gezeigt:
DEFINE DATA PARAMETER 01 P1 ... 01 P2 ... ... ... 01 PN ... 01 N1 (I2) 01 N2 (I2) ... ... 01 N n (I2) PARAMETER USING DB2SQL_P [ PARAMETER USING DBINFO_P ] /* only if DBINFO is defined LOCAL ... ... END-DEFINE
Definieren Sie in einer Natural-UDF die Parameter wie im folgenden Beispielprogramm gezeigt:
DEFINE DATA PARAMETER 01 PI1 ... /* first input parameter 01 PI2 ... ... ... 01 PIn ... /* last input parameter 01 RS1... /* first result parameter ... ... 01 RSn ... /* last result parameter 01 N_PI1 (I2) /* first NULL indicator 01 N_PI2 (I2) ... ... 01 N_Pin (I2) 01 N_RS1 (I2) ... ... 01 N_RSn (I2) /* last NULL indicator PARAMETER USING DB2SQL_P /* function, specific, sqlstate, diagnose PARAMETER 01 SCRATCHPAD A(4+nnn) /* only if SCRATCHPAD nnn is specified 01 REDEFINES SCRATCHPAD 02 SCRATCHPAD_LENGTH (I4) 02 ... 01 CALL_TYPE (I4) /* --- only if FINAL CALL is specified or table UDF PARAMETER USING DBINFO_P /* ---- only if DBINFO is specified LOCAL ... ... END-DEFINE
Dieser Abschnitt enthält einen allgemeinen Leitfaden, wie eine Natural Stored Procedure geschrieben wird und was dabei zu beachten ist.
Um eine Natural Stored Procedure zu schreiben:
Bestimmen Sie das Format und die Attribute der Parameter, die zwischen dem Aufrufer und der Stored Procedure übergeben werden. Erwägen Sie die Erstellung eines Natural-Parameterdatenbereichs (PDA). Stored Procedures unterstützen keine Datengruppen und Neudefinitionen innerhalb ihrer Parameter.
Bestimmen Sie den PARAMETER STYLE der Stored Procedure:
GENERAL, GENERAL WITH NULL oder DB2SQL.
Wenn Sie GENERAL WITH NULL verwenden, hängen Sie die Parameter an
die Natural Stored Procedure an, indem Sie ein NULL-Indikator-Array
definieren, das einen NULL-Indikator (I2) für jeden anderen
Parameter enthält.
Wenn Sie DB2SQL verwenden, fügen Sie die Parameter der Natural
Stored Procedure an, indem Sie NULL-Indikatoren (einen für jeden
Parameter) definieren und den PDA DB2SQL_P und den PDA
DBINFO_P (nur bei Angabe von DBINFO) einschließen,
falls gewünscht. Siehe auch die entsprechende Db2-Literatur von IBM.
Entscheiden Sie, welche und wie viele Ergebnismengen (Result Sets) die Stored Procedure an den Aufrufer zurückgeben soll.
Codieren Sie Ihre Stored Procedure als Natural-Subprogramm.
Rückgabe von Ergebnismengen
Um Ergebnismengen (Result Sets) zurückzugeben, codieren Sie ein Natural SQL
SELECT-Statement
mit der Option WITH RETURN.
Um die gesamte Ergebnismenge zurückzugeben, codieren Sie ein ESCAPE
BOTTOM-Statement unmittelbar nach dem
SELECT-Statement.
Um einen Teil der Ergebnismenge zurückzugeben, codieren Sie ein IF
*COUNTER = 1 ESCAPE TOP END-IF unmittelbar nach dem
SELECT-Statement. Dadurch wird sichergestellt, dass Sie die erste
leere Zeile, die von dem SELECT WITH RETURN-Statement zurückgegeben
wird, nicht verarbeiten. Um die Zeilenverarbeitung zu stoppen, führen Sie ein
ESCAPE BOTTOM-Statement aus.
Wenn Sie die durch SELECT WITH RETURN eingeleitete
Verarbeitungsschleife nicht über ESCAPE BOTTOM verlassen, wird die
erzeugte Ergebnismenge geschlossen und nichts an den Aufrufer zurückgegeben.
Achtung beim Zugriff auf andere Datenbanken!
Sie können innerhalb einer Natural Stored Procedure auf andere Datenbanken (z.
B. Adabas) zugreifen. Beachten Sie jedoch, dass Ihr Zugriff auf andere
Datenbanken weder mit den Aktualisierungen durch den Aufrufer der Stored
Procedure noch mit den Aktualisierungen gegen Db2 innerhalb der Stored Procedure
synchronisiert wird.
Natural for Db2-Behandlung von COMMIT- und
ROLLBACK-Statemenst
Db2 lässt nicht zu, dass eine Stored Procedure Natural SQL COMMIT- oder ROLLBACK-Statements
ausgibt (die Ausführung dieser Statements versetzt den Aufrufer in einen
Must-Rollback-Status). Daher behandelt die Natural for Db2-Laufzeit diese
Statements wie folgt, wenn sie von einer Stored Procedure ausgegeben werden:
ROLLBACK gegen Db2 wird übersprungen, wenn es von Natural selbst
erzeugt wird.
ROLLBACK gegen Db2 wird ausgeführt, wenn es vom Benutzer
programmiert wurde. So erhält der Aufrufer nach einem Natural-Fehler die
Natural-Fehlerinformation und nicht den unqualifizierten Must-Rollback-Status.
Außerdem stellt diese Funktion sicher, dass jede Datenbanktransaktion der Stored
Procedure zurückgenommen wird, wenn das Benutzerprogramm die Transaktion
zurücknimmt.
Für Db2 UDB: Geben Sie ein CREATE
PROCEDURE Statement aus, das Ihre Stored Procedure definiert, z.B:
CREATE PROCEDURE <PROCEDURE> (INOUT STCB VARCHAR(274+13*N), INOUT <PARM1> <FORMAT>, INOUT <PARM2> <FORMAT>, INOUT <PARM3> <FORMAT> . ) DYNAMIC RESULT SET <RESULT_SETS> EXTERNAL NAME <LOADMOD> LANGUAGE ASSEMBLE PROGRAM TYPE <PGM_TYPE> PARAMETER STYLE GENERAL <WITH NULLS depending on LINKAGE>;
Die in spitzen Klammern (< >) angegebenen Daten entsprechen den
in der obigen Tabelle aufgeführten Daten, PARM1 - PARM3
und FORMAT hängen von der Aufrufparameterliste der Stored Procedure ab.
Siehe auch Beispiel Stored
Procedure NDBPURGN.
Codieren Sie Ihr Natural-Programm, das die Stored Procedure über das
Natural-SQL-Statement CALLDBPROC aufruft.
Kodieren Sie die Parameter in dem CALLDBPROC-Statement in der gleichen
Reihenfolge, wie sie in der Stored Procedure angegeben sind. Definieren Sie die
Parameter im aufrufenden Programm in einem Format, das mit dem in der Stored
Procedure definierten Format kompatibel ist.
Wenn Sie Ergebnismengen (Result Sets) verwenden, geben Sie eine RESULT
SETS-Klausel in dem CALLDBPROC-Statement an, gefolgt von einer Anzahl von
Ergebnismengen-Locator-Variablen in FORMAT (I4). Die Anzahl der
Ergebnismengen-Locator-Variablen sollte mit der Anzahl der von der Stored Procedure
erstellten Ergebnismengen übereinstimmen. Wenn Sie weniger angeben als erstellt
werden, gehen einige Ergebnismengen verloren. Wenn Sie mehr angeben, als erstellt
werden, gehen die restlichen Ergebnismengen-Locator-Variablen verloren. Die
Reihenfolge der Locator-Variablen entspricht der Reihenfolge, in der die
Ergebnismengen von der Stored Procedure erstellt werden.
Beachten Sie, dass die Felder, in die die Zeilen der Ergebnismenge gelesen werden,
den Feldern entsprechen müssen, die in dem SELECT WITH RETURN-Statement
verwendet werden, das die Ergebnismenge erzeugt hat.
Dieser Abschnitt enthält einen allgemeinen Leitfaden zum Schreiben einer benutzerdefinierten Funktion (Natural UDF) und zu den dabei zu beachtenden Aspekten.
Siehe auch den Abschnitt Schreiben einer Natural Stored Procedure.
Um eine Natural UDF zu schreiben:
Bestimmen Sie das Format und die Attribute der Parameter, die zwischen dem Aufrufer und der Stored Procedure übergeben werden.
Erstellen Sie einen Natural-Parameterdatenbereich (PDA).
Fügen Sie die Parameterdefinitionen der Natural UDF an, indem Sie
NULL-Indikatoren (einen für jeden Parameter) definieren und den PDA
DB2SQL_P inkludieren.
Kodieren Sie, falls erforderlich, einen SCRATCHPAD-Bereich in der
Parameterliste.
Kodieren Sie, falls erforderlich, einen Call-Type-Parameter. Wenn Sie
DBINFO angegeben haben, inkludieren Sie den PDA
DBINFO_P. Siehe auch die entsprechende Db2-Literatur von IBM.
Kodieren Sie Ihre UDF als Natural-Subprogramm und beachten Sie Folgendes:
Achtung beim Zugriff auf andere Datenbanken!
Sie können innerhalb einer Natural UDF auf andere Datenbanken (z. B. Adabas)
zugreifen. Beachten Sie jedoch, dass Ihr Zugriff auf andere Datenbanken weder
mit den Aktualisierungen durch den Aufrufer der Stored Procedure noch mit den
Aktualisierungen gegen Db2 innerhalb der Stored Procedure synchronisiert
wird.
Behandlung von COMMIT- und ROLLBACK-Statements
durch Natural für Db2
Db2 lässt nicht zu, dass eine Stored Procedure COMMIT- oder
ROLLBACK-Statements ausgibt. Die Ausführung dieser Statements
führt zu einem Must-Rollback-Status. Wenn eine Natural-Stored-Procedure ein
COMMIT oder ROLLBACK ausgibt, verarbeitet die
Natural for Db2-Laufzeitumgebung diese Statements wie folgt:
COMMIT gegen Db2 wird übersprungen. Dadurch kann die Stored
Procedure Adabas-Updates festschreiben (Commit), ohne in einen
Must-Rollback-Status von Db2 einzutreten.
ROLLBACK gegen Db2 wird übersprungen, wenn es implizit von der
Natural-Laufzeit ausgegeben wird.
ROLLBACK gegen Db2 wird ausgeführt, wenn es vom Benutzer programmiert wurde. So erhält der Aufrufer nach einem Natural-Fehler einen entsprechenden Natural-Fehlermeldungstext, gerät aber nicht in einen unqualifizierten Must-Rollback-Zustand. Außerdem stellt diese Reaktion sicher, dass jede Datenbanktransaktion, die die Stored Procedure ausführt, zurückgenommen wird, wenn das Benutzerprogramm die Transaktion zurücknimmt (Backout).
Geben Sie eine CREATE FUNCTION-Statement aus, das z.B. Ihre UDF
definiert:
CREATE FUNCTION <FUNCTION> ([PARM1] <FORMAT>, [PARM2] <FORMAT>, [PARM3] <FORMAT> ) RETURNS <FORMAT> EXTERNAL NAME <LOADMOD> LANGUAGE ASSEMBLE PROGRAM TYPE <PGM TYPE> PARAMETER STYLE DB2SQL . . .;
Im obigen Beispiel sind die variablen Daten in spitze Klammern (<
>) eingeschlossen und beziehen sich auf die Schlüsselwörter, die den
Klammern vorausgehen. Geben Sie einen gültigen Wert an, zum Beispiel:
LOADMOD bezeichnet das Natural for Db2 Server Stub-Modul, z. B.
NDBvrSRV, wobei
vr für die Natural-Versionsnummer
steht.
PARM1 - PARM3 und FORMAT beziehen sich auf
die Aufrufparameterliste der UDF. Siehe auch Beispiel für Natural User Defined
Function.
Codieren Sie ein Natural-Programm mit SQL-Statements, die die UDF aufrufen.
Geben Sie die Parameter des Natural-UDF-Aufrufs in der gleichen Reihenfolge an, wie sie in der Natural-UDF-Definition angegeben sind. Das Format der Parameter im aufrufenden Programm muss mit dem in der Natural UDF definierten Format kompatibel sein.
In diesem Abschnitt wird die Beispiel-Stored-Procedure NDBPURGN beschrieben,
ein Natural-Subprogramm, das Natural-Objekte aus dem vom Natural Stored-Procedures-Server
verwendeten Buffer Pool löscht.
Die folgenden Themen werden in diesem Abschnitt behandelt:
Die Beispiel-Stored-Procedure NDBPURGN besteht aus den folgenden
Textobjekten (Members), die in der Natural System Library SYSDB2 gespeichert sind:
| Objekt | Erläuterung |
|---|---|
CR6PURGN |
Eingabe-Member (Textobjekt) für SYSDB2 ISQL.
Enthält SQL-Statements,
die zur Deklaration von |
NDBPURGP |
Das Client-(Natural-)Programm, das
Stellen Sie sicher, dass das spezielle Db2-Register |
NDBPURGN |
Die Stored Procedure, die Objekte aus dem Buffer Pool löscht.
Deshalb muss |
Um die Beispiel-Stored-Procedure NDBPURGN zu definieren:
Definieren Sie die Stored Procedure im Db2-Katalog mit Hilfe der SQL-Statements,
die als Textobjekte CR5PURGN (für Db2 Version 5) und
CR6PURGN (für Db2 Version 6) bereitgestellt werden.
Geben Sie den Namen des Natural Stored Procedure Stub (hier:
NDBvrSRV, wobei
vr für die Natural-Versionsnummer
steht) als LOADMOD (V5) oder EXTERNAL NAME (V6) an. Der
Natural Stored Procedure Stub wird während der Installation durch Assemblieren des
Makros NDBSTUB erzeugt.
Übergeben Sie als ersten Parameter den internen Natural-Parameter
STCB an die Stored Procedure. Der
STCB-Parameter ist ein VARCHAR-Feld, das
Informationen enthält, die zum Aufrufen der Stored Procedure in Natural
erforderlich sind:
Der Programmname der Stored Procedure und die Library, in der sie sich befindet,
die Beschreibung der an die Stored Procedure übergebenen Parameter und
die von Natural erzeugte Fehlermeldung, wenn die Stored Procedure während der Ausführung fehlschlägt.
Der STCB-Parameter wird automatisch durch die CALLMODE=NATURAL-Klausel des Natural-SQL-Statement
CALLDBPROC
generiert und wird aus den Parametern entfernt, die der Server-Stub an die Natural
Stored Procedure übergibt. Somit ist STCB für den Aufrufer
und die Stored Procedure unsichtbar. Wenn jedoch ein Nicht-Natural-Client eine
Natural Stored Procedure aufrufen will, muss der Client den
STCB-Parameter explizit übergeben. Siehe auch
Stored Procedure Control Block weiter unten.
Nachfolgend sehen Sie den durch die CALLMODE=NATURAL-Klausel erzeugten Stored Procedure Control
Block (STBC), wie er von der Stored Procedure NDBPURGN
vor und nach der Ausführung erzeugt wurde. Geänderte Werte sind durch
Fettdruck hervorgehoben:
004C82 0132F0F3 F0F6E2E3 C3C2F3F1 F040C8C7 *..0306STCB310 HG* 11097D42 004C92 D2404040 4040C8C7 D2404040 4040D5C4 *K SAG ND* 11097D52 004CA2 C2D7E4D9 C7D74040 40404040 4040F0F5 *BPURGP 05* 11097D62 004CB2 F7F0D5C4 C2D7E4D9 C7D5F0F0 F0F6F0F9 *70NDBPURGN000609* 11097D72 004CC2 F9F9F940 40404040 40404040 40404040 *999 * 11097D82 004CD2 40404040 40404040 40404040 40404040 * * 11097D92 004CE2 40404040 40404040 40404040 40404040 * * 11097DA2 004CF2 40404040 40404040 40404040 40404040 * * 11097DB2 004D02 40404040 40404040 40404040 40404040 * * 11097DC2 004D12 40404040 40404040 40404040 40404040 * * 11097DD2 004D22 40404040 40404040 40404040 40404040 * * 11097DE2 004D32 40404040 40404040 40404040 40404040 * * 11097DF2 004D42 40404040 40404040 40404040 40404040 * * 11097E02 004D52 40404040 40404040 40404040 40404040 * * 11097E12 004D62 40404040 40404040 40404040 40404040 * * 11097E22 004D72 40404040 40404040 40404040 40404040 * * 11097E32 004D82 40404040 40404040 40404040 40404040 * * 11097E42 004D92 40404040 D4C1F86B F0D4C1F4 F06BF0D4 * MA8,0MA40,0M* 11097E52 004DA2 C2F26BF0 D4C2F26B F0D4C9F2 6BF0D4C9 *I2,0MI2,0MI2,0MI* 11097E62 004DB2 F26BF04B *2,0. * 11097E72
004C82 0132F0F3 F0F6E2E3 C3C2F3F1 F040C8C7 *..0306STCB310 HG* 11097D42 004C92 D2404040 4040C8C7 D2404040 4040D5C4 *K SAG ND* 11097D52 004CA2 C2D7E4D9 C7D74040 40404040 4040F0F5 *BPURGP 05* 11097D62 004CB2 F7F0D5C4 C2D7E4D9 C7D5F0F0 F0F6F0F0 *70NDBPURGN000600* 11097D72 004CC2 F0F0F040 40404040 40404040 40404040 *000 * 11097D82 004CD2 40404040 40404040 40404040 40404040 * * 11097D92 004CE2 40404040 40404040 40404040 40404040 * * 11097DA2 004CF2 40404040 40404040 40404040 40404040 * * 11097DB2 004D02 40404040 40404040 40404040 40404040 * * 11097DC2 004D12 40404040 40404040 40404040 40404040 * * 11097DD2 004D22 40404040 40404040 40404040 40404040 * * 11097DE2 004D32 40404040 40404040 40404040 40404040 * * 11097DF2 004D42 40404040 40404040 40404040 40404040 * * 11097E02 004D52 40404040 40404040 40404040 40404040 * * 11097E12 004D62 40404040 40404040 40404040 40404040 * * 11097E22 004D72 40404040 40404040 40404040 40404040 * * 11097E32 004D82 40404040 40404040 40404040 40404040 * * 11097E42 004D92 40404040 D4C1F86B F0D4C1F4 F06BF0D4 * MA8,0MA40,0M* 11097E52 004DA2 C2F26BF0 D4C2F26B F0D4C9F2 6BF0D4C9 *I2,0MI2,0MI2,0MI* 11097E62 004DB2 F26BF04B *2,0. * 11097E72
Dieser Abschnitt beschreibt die User Defined Function (UDF) NAT.DEM2UDFN,
ein Natural-Subprogramm zur Berechnung des Produkts zweier Zahlen.
Die Beispiel-UDF NAT.DEM2UDF besteht aus den folgenden Objekten, die in der
Natural-System-Library SYSDB2 ausgeliefert werden:
| Objekt | Erläuterung |
|---|---|
DEM2CUDF |
Enthält SQL-Statements, die zur Erstellung von DEM2UDFN
verwendet werden (siehe unten).
|
DEM2UDFP |
Das Client-(Natural-)Programm, das
|
DEM2UDFN |
Die UDF, die das Produkt von zwei Zahlen bildet. DEM2UDFN muss
in die Natural Library NAT in der Natural Systemdatei FUSER in der
Ausführungsumgebung kopiert werden.
|
