Verarbeitung von Natural Stored Procedures und UDFs

#### Search Results

Search

# 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

- PARAMETER STYLE

- Schreiben einer Natural Stored Procedure

- Schreiben einer Natural UDF

- Beispiel einer Stored Procedure

- Beispiel einer Natural User Defined Function

## 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 STYLE`s 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

- STCB Layout

- DB2SQL

### 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
- Beispiel für PARAMETER STYLE GENERAL
- Beispiel für GENERAL WITH NULL

#### 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
- Parameter DBINFO
- Ermitteln von Library, Subprogramm und Parameterformaten
- Aufrufen einer Natural Stored Procedure
- Fehlerbehandlung
- Lebensdauer der Natural-Sitzung
- Beispiel für DB2SQL - Natural Stored Procedure
- Beispiel für DB2SQL - Natural UDF

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

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.

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

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

- Definieren der Stored Procedure NDBPURGN

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

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

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

### On this page

- Natural-UDF-Typen
- PARAMETER STYLE
- Schreiben einer Natural Stored Procedure
- Schreiben einer Natural UDF
- Beispiel einer Stored Procedure
- Beispiel einer Natural User Defined Function