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.
Anmerkung:PARAMETER 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
|
Anmerkung:PARAMETER 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 Anweisungen 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 Bibliothek, 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.
|