Verarbeitung von Natural Stored Procedures und UDFs

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:


Natural-UDF-Typen

Es gibt zwei Typen von Natural Used Defined Functions (UDF):

  • Skalare 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.

  • Tabellen-UTF

    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.

PARAMETER STYLE

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.

GENERAL und GENERAL WITH NULL

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:

Stored Procedure Control Block

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.

Beispiel für PARAMETER STYLE GENERAL

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

Beispiel für GENERAL WITH NULL

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

STCB Layout

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 (STCBPADE)

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
    AD-Attribut

    Äquivalente
    DB2-Klausel

    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:

    t Beschreibung l p dl Beispiel
    A Alphanumerisch 1-253 0

    1-32767
    oder
    -

    A30,0
    oder
    A30,0,10

    N Numerisch, nicht gepackt 1-29 0-7 - N10,3
    P Numerisch, gepackt 1-29 0-7 - P13,4
    I Ganzzahl 2 oder 4 0 - I2,0
    F Floating point   0 - I4,0
    B Binär   0 - B23,0
    D Datum 6 0 - D6
    T Uhrzeit 12 0 - T12
    L Logisch (wird nicht unterstützt)        
  • 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

DB2SQL

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.

Zusätzlich übergebene Parameter

  • 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:

Parameter CALL TYPE

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.

Parameter DBINFO

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.

Ermitteln von Library, Subprogramm und Parameterformaten

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.

Aufrufen einer Natural Stored Procedure

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.

Fehlerbehandlung

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.

Lebensdauer der Natural-Sitzung

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.

Beispiel für DB2SQL - Natural Stored Procedure

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

Beispiel für DB2SQL - Natural UDF

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

Schreiben einer Natural Stored Procedure

Dieser Abschnitt enthält einen allgemeinen Leitfaden, wie eine Natural Stored Procedure geschrieben wird und was dabei zu beachten ist.

Beginn der Anweisungsliste Um eine Natural Stored Procedure zu schreiben:

  1. 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.

  2. 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.

  3. Entscheiden Sie, welche und wie viele Ergebnismengen (Result Sets) die Stored Procedure an den Aufrufer zurückgeben soll.

  4. 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.

  5. 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.

  6. 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.

Schreiben einer Natural UDF

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.

Beginn der Anweisungsliste Um eine Natural UDF zu schreiben:

  1. Bestimmen Sie das Format und die Attribute der Parameter, die zwischen dem Aufrufer und der Stored Procedure übergeben werden.

  2. Erstellen Sie einen Natural-Parameterdatenbereich (PDA).

  3. 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.

  4. Kodieren Sie, falls erforderlich, einen SCRATCHPAD-Bereich in der Parameterliste.

  5. 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.

  6. 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).

  7. 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.

  8. 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.

Beispiel einer Stored Procedure

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:

Objekte von NDBPURGN

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 NDBPURGN in Db2 verwendet werden.

NDBPURGP Das Client-(Natural-)Programm, das
  • den Namen des zu löschenden Programms und die Library, in der es sich befindet, abfragt,

  • die Stored Procedure NDBPURGN aufruft

  • und das Ergebnis der Anfrage meldet.

Stellen Sie sicher, dass das spezielle Db2-Register PATH den Schema-Namen der von CR6PURGN erstellten Stored Procedure NDBPURGN enthält. Dies kann mit dem SQL-Statement SET PATH schema-name erreicht werden. Fehlt der Schema-Name, kann der SQLCODE-440 zurückgegeben werden.

NDBPURGN Die Stored Procedure, die Objekte aus dem Buffer Pool löscht.

NDBPURGN ruft die Anwendungsprogrammierschnittstelle USR0340N auf, die in der Natural System Library SYSEXT bereitgestellt wird..

Deshalb muss USR0340N in der Library verfügbar sein, die als Steplib für die Ausführungsumgebung definiert ist.

Definieren der Stored Procedure NDBPURGN

Beginn der AnweisungslisteUm die Beispiel-Stored-Procedure NDBPURGN zu definieren:

  1. 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.

  2. 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.

  3. Ü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.

Stored Procedure Control Block (STCB)

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:

STCB vor der Ausführung:

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

STCB nach der Ausführung:

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

Beispiel einer Natural User Defined Function

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

  • Zeilen aus der UDF-Tabelle NAT.DEMO holt,

  • die NAT.DEM2UDFN (siehe unten) in der WHERE-Klausel aufruft und

  • die abgerufenen Zeilen anzeigt.

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.