Interface-Subprogramme

#### Search Results

Search

# Interface-Subprogramme

Es stehen mehrere Natural- und Nicht-Natural-Subprogramme zur Verfügung, die Ihnen interne Informationen aus Natural for Db2 liefern oder spezifische Funktionen bereitstellen, für die es kein entsprechendes Natural-Statement gibt.

In diesem Kapitel werden die folgenden Themen behandelt:

- Natural-Subprogramme

- Subprogramm NDBCONV

- Subprogramm NDBDBRM

- Subprogramm NDBDBR2

- Subprogramm NDBDBR3

- Subprogramm NDBERR

- Subprogramm NDBISQL

- Subprogramm NDBISQLD

- Subprogramm NDBNOERR

- Subprogramm NDBNROW

- Subprogramm NDBSTMP

- DB2SERV-Schnittstelle

## Natural-Subprogramme

Die folgenden Natural-Subprogramme sind verfügbar:

Subprogramm | Funktion
--- | ---
`NDBCONV` | Setzt den Conversational Mode 2 und setzt ihn zurück.
`NDBDBRM` | Prüft, ob ein Natural-Programm SQL-Zugriffe enthält und ob es für die statische Ausführung modifiziert wurde.
`NDBDBR2` | Prüft, ob ein Natural-Programm SQL-Zugriffe enthält und ob es für die statische Ausführung modifiziert wurde.
`NDBDBR3` | Prüft, ob ein Natural-Programm SQL-Zugriffe enthält, ob es für die statische Ausführung modifiziert wurde und ob es als statisch generiert werden kann.
`NDBERR` | Liefert Diagnoseinformationen über den zuletzt ausgeführten SQL-Aufruf.
`NDBISQL` | Führt SQL-Statements im dynamischen Modus aus.
`NDBISQLD` | Führt SQL-Statements im dynamischen Modus unter Verwendung dynamischer Variablen aus.
`NDBNOERR` | Unterdrückt die normale Natural-Fehlerbehandlung.
`NDBNROW` | Ermittelt die Anzahl der Zeilen, die von einem Natural SQL-Statement betroffen sind.
`NDBSTMP` | Stellt eine Db2-`TIMESTAMP`-Spalte als alphanumerisches Feld zur Verfügung und umgekehrt.

Die oben genannten Subprogramme sind alle in der Natural Library SYSDB2 und in der Natural Library SYSTEM in der Systemdatei FNAT enthalten.

Darüber hinaus enthält die Natural Library SYSTEM in der Systemdatei FNAT das Subprogramm `DBTLIB2N` und die Subroutine `DBDL219S`. Sie werden von `NDBDBRM` und `NDBDBR2` verwendet. Die entsprechenden Parameter müssen in einem `DEFINE DATA`-Statement definiert werden.

Die Natural-Subprogramme `NDBDBRM`, `NDBDBR2` und `NDBDBR3` gestatten die optionale Angabe der Datenbankkennung, der Dateinummer, des Passworts und des Chiffriercodes der Library-Datei, die das zu untersuchende Programm enthält.

Werden diese Parameter nicht angegeben, wird entweder die aktuelle FNAT-Datei oder die FUSER-Datei verwendet, um das zu untersuchende Programm zu finden, je nachdem, ob der Library-Name mit "SYS" beginnt oder nicht.

Programme, die `NDBDBRM`, `NDBDBR2` oder `NDBDBR3` ohne diese Parameter aufrufen, funktionieren ebenfalls wie vor dieser Änderung, da die hinzugefügten Parameter als optional deklariert sind.

Ausführliche Informationen zu diesen Subprogrammen finden Sie unter den in der obigen Tabelle enthaltenen Links und in der Beschreibung des Aufrufformats und der Parameter in dem mit dem Subprogramm gelieferten Textobjekt (`subprogram-nameT`).

#### Aufrufen von Subprogrammen aus einem Natural-Programm heraus

- Natural-Subprogramme werden mit dem Natural-Statement `CALLNAT` aufgerufen.

- Nicht-Natural-Subprogramme werden mit dem Natural-Statement `CALL` aufgerufen.

## Subprogramm NDBCONV

Das Natural-Subprogramm `NDBCONV` wird verwendet, um den Conversational Mode 2 in CICS-Umgebungen entweder zu setzen oder zurückzusetzen. Der Conversational Mode 2 bedeutet, dass Aktualisierungstransaktionen über Terminal-E/A erzeugt werden, bis entweder ein `COMMIT` oder `ROLLBACK` ausgegeben wurde (Achtung: Db2- und CICS-Ressourcen werden über Terminal-E/A gehalten!). Das bedeutet, dass der Conversational Mode 2 die gleiche Wirkung hat wie der Natural-Profilparameter `PSEUDO=OFF`, mit dem Unterschied, dass der Conversational Mode nach einem Db2-Aktualisierungs-Statement (`UPDATE`, `DELETE`, `INSERT`) aufgenommen und nach einem `COMMIT` oder `ROLLBACK` wieder verlassen wird, während `PSEUDO=OFF` den Conversational Mode für die gesamte Natural-Sitzung bewirkt.

Ein Beispielprogramm namens `CALLCONV` wird in der Library SYSDB2 zur Verfügung gestellt. Es demonstriert, wie man `NDBCONV` aufruft. Eine Beschreibung des Aufrufformats und der Parameter finden Sie in dem Textobjekt `NDBCONVT`.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBCONV' #CONVERS #RESPONSE

Die verschiedenen Parameter sind in der folgenden Tabelle beschrieben:

Parameter | Format/Länge | Erläuterung
--- | --- | ---
`#CONVERS` | I1 | Enthält den gewünschten Conversational Mode (Eingabe)
`#RESPONSE` | I4 | Enthält die Rückmeldung von `NDBCONV` (Ausgabe)

Der Parameter `#CONVERS` kann die folgenden Werte enthalten:

Code | Erläuterung
--- | ---
`0` | Der Conversational Mode 2 muss zurückgesetzt werden.
`1` | Der Conversational Mode 2 muss gesetzt werden.

Der Parameter `#RESPONSE` kann die folgenden Werte enthalten:

Code | Erläuterung
--- | ---
`0` | Der Conversational Mode 2 wurde erfolgreich gesetzt oder zurückgesetzt.
`-1` | Der angegebene Wert von `#CONVERS` ist ungültig, der Conversational Mode wurde nicht geändert.
`-2` | `NDBCONV` wird in einer Umgebung aufgerufen, die keine CICS-Umgebung ist und in der der Conversational Mode 2 nicht unterstützt wird.

## Subprogramm NDBDBRM

Das Natural-Subprogramm `NDBDBRM` wird verwendet, um zu prüfen, ob ein Natural-Programm SQL-Zugriffe enthält und ob es für die statische Ausführung modifiziert wurde. Es wird außerdem verwendet, um den entsprechenden DBRM-Namen (Datenbankanforderungsmodul) aus dem Header eines als statisch generierten Natural-Programms zu ermitteln (siehe auch Programme für die statische Ausführung vorbereiten vorbereiten).

Das Installationsmedium enthält ein Beispielprogramm namens `CALLDBRM`, das den Aufruf von `NDBDBRM` demonstriert. Eine Beschreibung des Aufrufformats und der Parameter finden Sie in dem Textobjekt `NDBDBRMT`.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBDBRM' #LIB #MEM #DBRM #RESP #DBID #FILENR #PASSWORD #CIPHER

Die verschiedenen Parameter sind in der folgenden Tabelle beschrieben:

Parameter | Format/Länge | Erläuterung
--- | --- | ---
`#LIB` | A8 | Enthält den Namen der Library des zu prüfenden Programms.
`#MEM` | A8 | Enthält den Namen des zu prüfenden Programms (Member).
`#DBRM` | A8 | Gibt den DBRM-Namen zurück.
`#RESP` | I2 | Gibt einen Rückmeldecode zurück. Die möglichen Codes sind unten aufgeführt.
`#DBID` | N5 | Optional. Datenbankkennung der Library-Datei.
`#FILENR` | N5 | Optional. Dateinummer der Library-Datei.
`#PASSWORD` | A8 | Optional. Passwort der Library-Datei.
`#CIPHER` | N8 | Optional. Chiffrierschlüssel der Library-Datei.

Der Parameter `#RESP` kann die folgenden Werte enthalten:

Code | Erläuterung
--- | ---
`0` | Das Member `#MEM` in der Library `#LIB` hat SQL-Zugriff; es ist statisch, wenn `#DBRM` einen Wert enthält.
`-1` | Das Member `#MEM` in der Library `#LIB` hat keinen SQL-Zugriff.
`-2` | Das Member `#MEM` in der Library `#LIB` existiert nicht.
`-3` | Es wurde kein Library-Name angegeben.
`-4` | wurde kein Member-Name angegeben.
`-5` | Der Library-Name muss mit einem Buchstaben beginnen.
`>-5` | Weitere negative Rückmeldecodes entsprechen den Fehlernummern der Natural-Fehlermeldungen.
`>0` | Positive Rückmeldecodes entsprechen Fehlernummern von Natural Security-Meldungen.

## Subprogramm NDBDBR2

Das Natural-Subprogramm `NDBDBR2` dient dazu, zu prüfen, ob ein Natural-Programm SQL-Zugriffe enthält und ob es für die statische Ausführung modifiziert wurde. Außerdem ermittelt es aus dem Header eines statisch generierten Natural-Programms den entsprechenden DBRM-Namen (Datenbankanforderungsmodul) (siehe auch Programme für die statische Ausführung vorbereiten) und den vom Precompiler generierten Zeitstempel.

Das Installationsmedium enthält ein Beispielprogramm namens `CALLDBR2`, das den Aufruf von `NDBDBR2` demonstriert. Eine Beschreibung des Aufrufformats und der Parameter finden Sie im Textobjekt `NDBDBR2T`.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBDBR2' #LIB #MEM #DBRM #TIMESTAMP #PCUSER #PCRELLEV #ISOLLEVL #DATEFORM #TIMEFORM #RESP #DBID #FILENR #PASSWORD #CIPHER

Die verschiedenen Parameter sind in der folgenden Tabelle beschrieben:

Parameter | Format/Länge | Erläuterung
--- | --- | ---
`#LIB` | A8 | Enthält den Namen der Library des zu prüfenden Programms.
`#MEM` | A8 | Enthält den Namen des zu prüfenden Programms (Member).
`#DBRM` | A8 | Gibt den DBRM-Namen zurück.
`#TIMESTAMP` | B8 | Vom Precompiler erzeugtes Konsistenz-Token.
`#PCUSER` | A8 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#PCRELLEV` | A1 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#ISOLLEVL` | A1 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#DATEFORM` | A1 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#TIMEFORM` | A1 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#RESP` | I2 | Gibt einen Rückmeldecode zurück. Die möglichen Codes sind unten aufgeführt.
`#DBID` | N5 | Optional. Datenbankkennung der Library-Datei.
`#FILENR` | N5 | Optional. Dateinummer der Library-Datei.
`#PASSWORD` | A8 | Optional. Passwort der Library-Datei.
`#CIPHER` | N8 | Optional. Chiffriercode der Library-Datei.

Der Parameter `#RESP` kann die folgenden Werte enthalten:

Code | Erläuterung
--- | ---
`0` | Das Member `#MEM` in der Library `#LIB` hat SQL-Zugriff. Es ist statisch, wenn `#DBRM` einen Wert enthält.
`-1` | Das Member `#MEM` in der Library `#LIB` hat keinen SQL-Zugriff.
`-2` | Das Member `#MEM` in der Library `#LIB` existiert nicht.
`-3` | Es wurde kein Library-Name angegeben.
`-4` | Es wurde kein Member-Name angegeben.
`-5` | Der Library-Name muss mit einem Buchstaben beginnen.
`>-5` | Weitere negative Rückmeldeecodes entsprechen den Fehlernummern der Natural-Fehlermeldungen.
`>0` | Positive Rückmeldeecodes entsprechen Fehlernummern von Natural Security-Meldungen.

## Subprogramm NDBDBR3

Mit dem Natural-Subprogramm `NDBDBR3` kann geprüft werden, ob ein Natural-Programm SQL-Zugriffe enthält (`#RESP 0`), ob das Natural-Programm ausschließlich SQL-Anweisungen enthält, die dynamisch ausführbar sind (`#RESP 0`, `#DBRM '*DYNAMIC'`) und ob es für die statische Ausführung modifiziert wurde (`#RESP 0`, `#DBRM dbrmname`). Es wird außerdem verwendet, um den entsprechenden DBRM-Namen (Datenbankanforderungsmodul) aus dem Header eines als statisch generierten Natural-Programms (siehe auch Vorbereitung von Programmen für die statische Ausführung) und den vom Precompiler generierten Zeitstempel zu erhalten.

Auf dem Installationsmedium befindet sich ein Beispielprogramm namens `CALLDBR3`, das den Aufruf von `NDBDBR3` demonstriert. Eine Beschreibung des Aufrufformats und der Parameter finden Sie im Textobjekt `NDBDBR3T`.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBDBR3' #LIB #MEM #DBRM #TIMESTAMP #PCUSER #PCRELLEV #ISOLLEVL #DATEFORM #TIMEFORM #RESP #DBID #FILENR #PASSWORD #CIPHER

Die verschiedenen Parameter sind in der folgenden Tabelle beschrieben:

Parameter | Format/Länge | Erläuterung
--- | --- | ---
`#LIB` | A8 | Enthält den Namen der Library des zu prüfenden Programms.
`#MEM` | A8 | Enthält den Namen des zu prüfenden Programms (Member).
`#DBRM` | A8 | Gibt den DBRM-Namen zurück. Leerschritt (Space), wenn das Programm SQL-Zugriff hat, `*DYNAMIC`, wenn das Programm nur dynamisch ausführbares SQL enthält, DBRM-Name, wenn das Programm statisch generiert wurde.
`#TIMESTAMP` | B8 | Vom Precompiler erzeugtes Konsistenz-Token.
`#PCUSER` | A8 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#PCRELLEV` | A1 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#ISOLLEVL` | A1 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#DATEFORM` | A1 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#TIMEFORM` | A1 | Nicht unterstützter Parameter. Wird nur aus Kompatibilitätsgründen beibehalten.
`#RESP` | I2 | Gibt einen Rückgabecode zurück. Die möglichen Codes sind unten aufgeführt.
`#DBID` | N5 | Optional. Datenbankkennung der Library-Datei.
`#FILENR` | N5 | Optional. Dateinummer der Library-Datei.
`#PASSWORD` | A8 | Optional. Passwort der Library-Datei.
`#CIPHER` | N8 | Optional. Chiffrierschlüssel der Library-Datei.

Der Parameter `#RESP` kann die folgenden Werte enthalten:

Code | Erläuterung
--- | ---
`0` | Das Member `#MEM` in der Library `#LIB` hat SQL-Zugriff. Es ist statisch, wenn `#DBRM` einen anderen Wert als Leerschritt (Space) und `*DYNAMIC` enthält.
`-1` | Das Member `#MEM` in der Library `#LIB` hat keinen SQL-Zugriff.
`-2` | Das Member `#MEM` in der Library `#LIB` existiert nicht.
`-3` | Es wurde kein Library-Name angegeben.
`-4` | Es wurde kein Member-Name angegeben.
`-5` | Der Library-Name muss mit einem Buchstaben beginnen.
`>-5` | Weitere negative Rückmeldecodes entsprechen den Fehlernummern der Natural-Fehlermeldungen.
`>0` | Positive Rückmeldecodes entsprechen Fehlernummern von Natural Security-Meldungen.

## Subprogramm NDBERR

Das Natural-Subprogramm `NDBERR` ersetzt die Funktion `E` der `DB2SERV`-Schnittstelle, die zwar noch vorhanden, aber nicht mehr dokumentiert ist. Es liefert Diagnoseinformationen über den letzten SQL-Aufruf. Es gibt auch den Datenbanktyp zurück, bei dem der Fehler aufgetreten ist. `NDBERR` wird typischerweise aufgerufen, wenn ein Datenbankaufruf einen SQLCODE ungleich Null zurückgibt (was einen Fehler NAT3700 bedeutet).

Ein Beispielprogramm namens `CALLERR` wird auf dem Installationsmedium mitgeliefert. Es demonstriert, wie `NDBERR` aufgerufen werden kann. Eine Beschreibung des Aufrufformats und der Parameter finden Sie im Textobjekt `NDBERRT`.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBERR' #SQLCODE #SQLSTATE #SQLCA #DBTYPE

Die verschiedenen Parameter sind in der folgenden Tabelle beschrieben:

Parameter | Format/Länge | Erläuterung
--- | --- | ---
`#SQLCODE` | I4 | Gibt den SQL-Rückgabecode zurück.
`#SQLSTATE` | A5 | Gibt einen Rückgabecode für die Ausgabe des zuletzt ausgeführten SQL-Statements zurück.
`#SQLCA` | A136 | Gibt den SQL-Kommunikationsbereich des letzten Db2-Zugriffs zurück.
`#DBTYPE` | B1 | Gibt die Kennung (im Hexadezimalformat) für die aktuell verwendete Datenbank zurück (wobei `X'02'` für Db2 steht).

## Subprogramm NDBISQL

Das Natural-Subprogramm `NDBISQL` dient dazu, SQL-Statements im dynamischen Modus auszuführen. Das `SELECT`-Statement und alle SQL-Statements, die dynamisch vorbereitet werden können (gemäß der Db2-Literatur von IBM), können an `NDBISQL` übergeben werden.

Auf dem Installationsmedium befindet sich ein Beispielprogramm namens CALLISQL, das den Aufruf von `NDBISQL` demonstriert. Eine Beschreibung des Aufrufformats und der Parameter ist im Textobjekt `NDBISQLT` enthalten.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBISQL'#FUNCTION #TEXT-LEN #TEXT (*) #SQLCA #RESPONSE #WORK-LEN #WORK (*)

Die verschiedenen Parameter sind in der folgenden Tabelle beschrieben:

Parameter | Format/Länge | Erläuterung
--- | --- | ---
`#FUNCTION` | A8 | Gültige Funktionen, siehe unten.
`#TEXT-LEN` | I2 | Länge des SQL-Statements oder des Puffers für den Rückgabebereich.
`#TEXT` | A1(1:V) | Enthält das SQL-Statement (`EXECUTE`) oder empfängt eine Datenzeile (`FETCH`).
`#SQLCA` | A136 | Enthält die SQLCA.
`#RESPONSE` | I4 | Gibt einen Rückmeldecode zurück.
`#WORK-LEN` | I2 | Länge des durch `#WORK` angegebenen Arbeitsbereiches (optional).
`#WORK` | A1(1:V) | Arbeitsbereich zur Aufnahme von SQLDA/SQLVAR und Hilfsfeldern bei Aufrufen (optional).
`#DBTYPE` | I2 | Datenbanktyp (optional).
`0` | Voreinstellung
`2` | DB2
`4` | CNX

Gültige Funktionen für den Parameter `#FUNCTION` sind:

Function | Parameter | Erläuterung
--- | --- | ---
`CLOSE` |  | Schließt den Cursor für das `SELECT`-Statement.
`EXECUTE` | #TEXT-LEN #TEXT (*) | Führt das SQL-Statement aus. Enthält die Länge des Statements. Enthält das SQL-Statement. Die ersten beiden Zeichen müssen leer sein.
`FETCH` | #TEXT-LEN #TEXT (*) | Gibt einen Datensatz aus dem `SELECT`-Statement zurück. Größe von `#TEXT` (in Bytes). Puffer für die Kopfzeile.
`TITLE` | `#TEXT-LEN` `#TEXT (*)` | Gibt die Kopfzeile für das `SELECT`-Statement zurück. Größe von `#TEXT` (in Bytes), erhält die Länge der Kopfzeile (= Länge des Datensatzes). Puffer für die Kopfzeile.

Der Parameter `#RESPONSE` kann die folgenden Rückmeldecodes enthalten:

Code | Funktion | Erläuterung
--- | --- | ---
`5` | `EXECUTE` | Das Statement ist ein `SELECT`-Statement.
`6` | `TITLE`, `FETCH` | Die Daten werden abgeschnitten; nur beim ersten Aufruf von `TITLE` oder `FETCH` gesetzt.
`100` | `FETCH` | Kein Datensatz / Ende der Daten.
`-2` |  | Nicht unterstützter Datentyp (z.B. `GRAPHIC`).
`-3` | `TITLE`, `FETCH` | Kein Cursor geöffnet; wahrscheinlich ungültige Aufrufsequenz oder anderes Statement als `SELECT`.
`-4` |  | Zu viele Spalten in der Ergebnistabelle.
`-5` |  | SQLCODE vom Aufruf.
`-6` |  | Keine Versionsübereinstimmung.
`-7` |  | Ungültige Funktion.
`-8` |  | Fehler beim SQL-Aufruf.
`-9` |  | Arbeitsbereich ungültig (möglicherweise Relokation).
`-10` |  | Schnittstelle nicht verfügbar.
`-11` | `EXECUTE` | Die ersten beiden Bytes des Statements sind nicht leer.

#### Aufruf-Reihenfolge

Der erste Aufruf muss ein `EXECUTE`-Aufruf sein. `NDBISQL` hat einen festen SQLDA AREA, der Platz für 50 Spalten bietet. Wenn dieser Bereich für ein bestimmtes `SELECT` zu klein ist, ist es möglich, einen optionalen Arbeitsbereich bei den Aufrufen von `NDBISQL` durch Angabe von `#WORK-LEN` (I2) und `#WORK(A1/1:V)` bereitzustellen.

Dieser Arbeitsbereich wird verwendet, um die SQLDA und temporäre Arbeitsfelder wie Null-Indikatoren und Hilfsfelder für numerische Spalten aufzunehmen. Kalkulieren Sie 16 Bytes für den SQLDA-Kopf und 44 Bytes für jede Ergebnisspalte sowie 2 Bytes Null-Indikator für jede Spalte und Platz für jede numerische Spalte, wenn Sie `#WORK-LEN` und `#WORK(*)` bei `NDBISQL`-Aufrufen angeben. Wenn diese optionalen Parameter bei einem `EXECUTE`-Aufruf angegeben werden, müssen sie auch bei jedem folgenden Aufruf angegeben werden.

Handelt es sich bei der Anweisung um ein `SELECT`-Statement (d.h. es wird der Rückmeldecode 5 zurückgegeben), kann eine beliebige Folge von `TITLE-` und `FETCH-`Aufrufen verwendet werden, um die Daten abzurufen. Ein Rückmeldecode von `100` zeigt das Ende der Daten an.

Der Cursor muss mit einem `CLOSE`-Aufruf geschlossen werden.

Der Funktionscode `EXECUTE` schließt implizit einen Cursor, der durch einen vorherigen `EXECUTE`-Aufruf für ein `SELECT`-Statement geöffnet wurde.

In TP-Umgebungen kann zwischen einem `EXECUTE`-Aufruf und einem `TITLE`-, `FETCH`- oder `CLOSE`-Aufruf, der sich auf dasselbe Statement bezieht, keine Terminal-E/A durchgeführt werden.

## Subprogramm NDBISQLD

Das Natural-Subprogramm `NDBISQLD` dient dazu, SQL-Statements im dynamischen Modus auszuführen. Das `SELECT`-Statement und alle SQL-Statements, die dynamisch vorbereitet werden können (gemäß der Db2-Literatur von IBM), können an `NDBISQLD` übergeben werden.

Ein Beispielprogramm namens `CALISQLD` ist im Lieferumfang des Installationsmediums enthalten. Es demonstriert, wie man `NDBISQLD` aufruft. Eine Beschreibung des Aufrufformats und der Parameter ist im Textobjekt `ISQLDT` enthalten.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBISQLD'#FUNCTION #TEXT #SQLCA #RESPONSE #WORK #DBTYPE

Die verschiedenen Parameter sind in der folgenden Tabelle beschrieben:

Parameter | Format/Länge | Erläuterung
--- | --- | ---
`#FUNCTION` | A8 | Gültige Funktionen, siehe unten.
`#TEXT` | A DYNAMIC | Enthält das SQL-Statement (`EXECUTE`) oder empfängt die Datenzeile (`FETCH`).
`#SQLCA` | A136 | Enthält die SQLCA.
`#RESPONSE` | I4 | Gibt einen Rückmeldecode zurück.
`#WORK` | A DYNAMIC | Arbeitsbereich, um SQLDA/SQLVAR und Hilfsfelder über Aufrufe hinweg zu halten (optional). Wenn angegeben, muss `#WORK` groß genug sein, um alle Hilfsfelder (SQLDA) für die SQL-Anfrage zu speichern.
`#DBTYPE` | I2 | Datenbanktyp (optional).
`0` | Voreinstellung
`2` | DB2
`4` | CNX

Gültige Funktionen für den Parameter `#FUNCTION` sind:

Funktion | Parameter | Erläuterung
--- | --- | ---
`CLOSE` | - | Schließt den Cursor für das `SELECT`-Statement.
`EXECUTE` | `#TEXT` | Schließt den Cursor für das SELECT-Statement. Enthält das SQL-Statement. Die ersten vier Zeichen müssen leer sein.
`FETCH` | `#TEXT` | Gibt eine Zeile aus dem `SELECT`-Statement zurück. `#TEXT` muss groß genug sein, um die Zeile der durch das `SELECT`-Statement erzeugten Ergebnismenge (Result Set) aufzunehmen. After `FETCH`, the `*LENGTH(#TEXT)` is reduced to the exact size of the row. Nach `FETCH` wird die `*LENGTH(#TEXT)` auf die genaue Größe der Zeile reduziert.
`TITLE` | `#TEXT` | Gibt die Header-Literale für das `SELECT`-Statement zurück. `#TEXT` muss groß genug sein, um die Zeile der durch das SELECT-Statement erzeugten Ergebnismenge (result set) aufzunehmen.

Der Parameter #RESPONSE kann die folgenden Rückmeldecodes enthalten:

Code | Funktion | Erläuterung
--- | --- | ---
`5` | `EXECUTE` | Das Statement ist ein `SELECT`-Statement.
`6` | `TITLE`, `FETCH` | Die Daten werden abgeschnitten; nur beim ersten Aufruf von `TITLE` oder `FETCH` gesetzt.
`100` | `FETCH` | Kein Datensatz/Ende der Daten.
`-2` | - | Nicht unterstützter Datentyp (z.B. `GRAPHIC`).
`-3` | `TITLE`, `FETCH` | Kein Cursor geöffnet. Wahrscheinlich ungültige Aufrufsequenz oder anderes Statement als `SELECT`.
`-4` | - | Zu viele Spalten in der Ergebnistabelle.
`-5` | - | SQLCODE aus Aufruf.
`-6` | - | Keine Versionsübereinstimmung.
`-7` | - | Ungültige Funktion.
`-8` | - | Fehler vom SQL-Aufruf.
`-9` | - | Arbeitsbereich ungültig (möglicherweise Relokation).
`-10` | - | Schnittstelle nicht verfügbar.
`-11` | `EXECUTE` | Die ersten beiden Bytes des Statements sind nicht leer.

#### Aufruf-Reihenfolge

Der erste Aufruf muss ein `EXECUTE`-Aufruf sein. `NDBISQLD` hat eine feste SQLDA AREA, die Platz für 50 Spalten bietet. Wenn dieser Bereich für ein bestimmtes `SELECT` zu klein ist, ist es möglich, bei den Aufrufen von `NDBISQLD` mit `#WORK(A)DYNAMIC` einen optionalen Arbeitsbereich anzugeben.

Dieser Arbeitsbereich wird verwendet, um die SQLDA und temporäre Arbeitsfelder wie Null-Indikatoren und Hilfsfelder für numerische Spalten aufzunehmen. Kalkulieren Sie 16 Bytes für den SQLDA-Header und 44 Bytes für jede Ergebnisspalte sowie 2 Bytes Null-Indikator für jede Spalte und Platz für jede numerische Spalte, wenn Sie `#WORK(A)DYNAMIC` bei `NDBISQLD`-Aufrufen angeben. Wenn diese optionalen Parameter bei einem `EXECUTE`-Aufruf angegeben werden, müssen sie auch bei jedem folgenden Aufruf angegeben werden.

Handelt es sich bei dem Statement um ein SELECT-Statement (d.h. es wird der Rückmeldecode 5 zurückgegeben), kann eine beliebige Folge von `TITLE`- und `FETCH`-Aufrufen verwendet werden, um die Daten abzurufen. Ein Rückmeldecode von 100 zeigt das Ende der Daten an.

Der Cursor muss mit einem `CLOSE`-Aufruf geschlossen werden.

Der Funktionscode `EXECUTE` schließt implizit einen Cursor, der durch einen vorherigen `EXECUTE`-Aufruf für ein `SELECT`-Statement geöffnet wurde.

In TP-Umgebungen kann zwischen einem `EXECUTE`-Aufruf und einem `TITLE`-, `FETCH`- oder `CLOSE`-Aufruf, der sich auf dasselbe Statement bezieht, keine Terminal-E/A durchgeführt werden.

## Subprogramm NDBNOERR

Das Natural-Subprogramm `NDBNOERR` dient zur Unterdrückung von Natural-NAT3700-Fehlern, die durch den nächsten SQL-Aufruf verursacht werden. Dies ermöglicht eine kontrollierte Fortsetzung des Programms, wenn ein SQL-Statement einen SQLCODE ungleich Null erzeugt. Nachdem der SQL-Aufruf ausgeführt wurde, wird `NDBERR` zur Untersuchung des SQLCODE verwendet.

Ein Beispielprogramm namens `CALLNOER` wird auf dem Installationsmedium mitgeliefert; es demonstriert, wie `NDBNOERR` aufgerufen werden kann. Eine Beschreibung des Aufrufformats und der Parameter finden Sie im Textobjekt `NDBNOERT`.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBNOERR'

Für dieses Subprogramm sind keine Parameter vorgesehen.

Anmerkung
Es werden nur NAT3700-Fehler (d.h. SQL-Rückmeldecodes ungleich Null) unterdrückt, und außerdem nur Fehler, die durch den nächstfolgenden SQL-Aufruf verursacht werden.

#### Einschränkungen bei Datenbankschleifen

- Wenn `NDBNOERR` vor einem Statement aufgerufen wird, das eine Datenbankschleife einleitet, und ein Initialisierungsfehler auftritt, wird keine Verarbeitungsschleife eingeleitet, es sei denn, es wurde eine `IF NO RECORDS FOUND`-Klausel angegeben.

- Wenn `NDBNOERR` innerhalb einer Datenbankschleife aufgerufen wird, gilt dies nicht für die Verarbeitungsschleife selbst, sondern nur für das SQL-Statement, das anschließend innerhalb dieser Schleife ausgeführt wird.

## Subprogramm NDBNROW

Das Natural-Subprogramm `NDBNROW` wird verwendet, um die Anzahl der von den Natural-SQL-Statements Searched `UPDATE`, Searched `DELETE` und `INSERT` betroffenen Zeilen zu ermitteln.

Die Anzahl der betroffenen Zeilen wird aus dem SQL-Kommunikationsbereich (SQLCA) gelesen. Ein positiver Wert steht für die Anzahl der betroffenen Zeilen, während ein Wert von minus eins (`-1`) anzeigt, dass alle Zeilen einer Tabelle in einem segmentierten Tablespace gelöscht wurden, siehe auch die Natural-Systemvariable `*NUMBER` in der Natural-Systemvariablen-Dokumentation.

Auf dem Installationsmedium befindet sich ein Beispielprogramm namens `CALLNROW`, das den Aufruf von `NDBNROW` demonstriert. Eine Beschreibung des Aufrufformats und der Parameter finden Sie in dem Textobjekt `NDBNROWT`.

Das aufrufende Natural-Programm muss die folgende Syntax verwenden:

    CALLNAT 'NDBNROW' #NUMBER

Der Parameter `#NUMBER` (I4) enthält die Anzahl der betroffenen Zeilen.

## Subprogramm NDBSTMP

Für Db2 bietet Natural eine `TIMESTAMP`-Spalte als alphanumerisches Feld (A26) im Format `YYYY-MM-DD-HH.MM.SS.MMMMMM`.

Da Natural noch keine Berechnungen mit solchen Feldern unterstützt, wird das Natural-Subprogramm `NDBSTMP` bereitgestellt, um diese Art von Funktionalität zu ermöglichen. Es konvertiert Natural-Zeitvariablen in Db2-Zeitstempel und umgekehrt und führt arithmetische Berechnungen mit Db2-Zeitstempeln durch.

Ein Beispielprogramm namens `CALLSTMP` wird auf dem Installationsmedium mitgeliefert; es demonstriert, wie `NDBSTMP` aufgerufen werden kann. Eine Beschreibung des Aufrufformats und der Parameter ist im Textobjekt `NDBSTMPT` enthalten.

Die verfügbaren Funktionen sind:

Code | Erläuterung
--- | ---
`ADD` | Addiert Zeiteinheiten (Labeled Durations, s. Anmerkung weiter unten) zu einem gegebenen Db2-Zeitstempel und gibt eine Natural-Zeitvariable und einen neuen Db2-Zeitstempel zurück.
`CNT2` | Konvertiert eine Natural-Zeitvariable (Format T) in einen Db2-Zeitstempel (Spaltentyp `TIMESTAMP`) und Labeled Durations.
`C2TN` | Konvertiert einen Db2-Zeitstempel (Spaltentyp `TIMESTAMP`) in eine Natural-Zeitvariable (Format T) und Labeled Durations.
`DIFF` | Ermittelt die Differenz zwischen zwei gegebenen Db2-Zeitstempeln und gibt Labeled Durations zurück.
`GEN` | Generiert einen Db2-Zeitstempel aus den aktuellen Datums- und Zeitwerten der Natural-Systemvariablen `*TIMX` und gibt einen neuen Db2-Zeitstempel zurück.
`SUB` | Subtrahiert Labeled Durations von einem gegebenen Db2-Zeitstempel und gibt eine Natural-Zeitvariable und einen neuen Db2-Zeitstempel zurück.
`TEST` | Prüft einen gegebenen Db2-Zeitstempel auf gültiges Format und gibt `TRUE` oder `FALSE` zurück.

Anmerkung
Labeled Durations sind Einheiten von Jahr, Monat, Tag, Stunde, Minute, Sekunde und Mikrosekunde.

## DB2SERV-Schnittstelle

`DB2SERV` ist ein Assembler-Programm-Einstiegspunkt, der aus einem Natural-Programm heraus aufgerufen werden kann.

`DB2SERV` führt eine der folgenden Funktionen aus:

- Funktion D, die das SQL-Statement `EXECUTE IMMEDIATE` ausführt.

- Funktion P, die ein Assembler-Modul namens `NDBPLAN` aufruft.

Die Parameter- oder Variablenwerte, die von jeder dieser Funktionen zurückgegeben werden, werden auf ihr Format, ihre Länge und ihre Anzahl überprüft.

### Funktion D

Die Funktion `D` führt das SQL-Statement `EXECUTE IMMEDIATE` aus. Damit können SQL-Statements innerhalb eines Natural-Programms ausgegeben werden.

Der SQL-Statement-String, der auf das `EXECUTE IMMEDIATE`-Statement folgt, muss der Natural-Programmvariablen `STMT` zugewiesen werden. Er muss gültige SQL-Statements enthalten, die mit dem `EXECUTE IMMEDIATE`-Statement zulässig sind, wie in der entsprechenden IBM-Literatur beschrieben. Beispiele finden Sie unten und in den Demonstrationsprogrammen `DEM2*` in der Natural System Library SYSDB2.

Anmerkung
Die Bedingungen, die für die Ausgabe der Natural-Statements `END TRANSACTION` oder `BACKOUT TRANSACTION` gelten, gelten auch für die Ausgabe der SQL-Statements `COMMIT` oder `ROLLBACK`.

#### Kommandosyntax

    CALL 'DB2SERV' 'D' STMT STMTL SQLCA RETCODE

Die in diesem Kommando verwendeten Variablen sind in der folgenden Tabelle beschrieben:

Variable | Format/Länge | Erläuterung
--- | --- | ---
`STMT` | `Annn` | Enthält einen Kommando-String, der aus der oben beschriebenen SQL-Syntax besteht.
`STMTL` | I2 | Enthält die Länge des in `STMT` definierten Strings.
`SQLCA` | A136 | Gibt den aktuellen Inhalt des SQL-Kommunikationsbereichs zurück.
`RETCODE` | I2 | Gibt einen Schnittstellen-Rückgabecode zurück. Die folgenden Codes sind möglich:
0 | Keine Warnung bzw. kein Fehler aufgetreten.
4 | SQL-Statement verursachte eine SQL-Warnung.
8 | SQL-Statement führte zu einem SQL-Fehler.
12 | Interner Fehler aufgetreten; die entsprechende Natural-Fehlernummer kann mit dem Kommando `SQLERR` angezeigt werden.

Der aktuelle Inhalt des SQLCA und ein Schnittstellen-Rückgabecode (`RETCODE`) werden zurückgegeben. Der SQLCA ist eine Sammlung von Variablen, die von Db2 verwendet werden, um einem Anwendungsprogramm Informationen über die Ausführung seiner SQL-Statements zu liefern.

Die folgenden Beispiele zeigen, wie Sie `DB2SERV` mit der Funktion `D` verwenden können.

#### Beispiel für Funktion D - DEM2CREA:

      **************************************************************************
      *  DEM2CREA - CREATE TABLE NAT.DEMO                                      *
      **************************************************************************
      *
      DEFINE DATA
      LOCAL USING DEMSQLCA
      LOCAL
      *                                   Parameters for DB2SERV
      1 STMT         (A250)
      1 STMTL        (I2)     CONST <250>
      1 RETCODE      (I2)
      *
      END-DEFINE
      *
      COMPRESS  'CREATE TABLE NAT.DEMO'
        '(NAME        CHAR(20)     NOT NULL,'
        ' ADDRESS     VARCHAR(100) NOT NULL,'
        ' DATEOFBIRTH DATE         NOT NULL,'
        ' SALARY      DECIMAL(6,2),'
        ' REMARKS     VARCHAR(500))'
        INTO STMT
      CALL 'DB2SERV' 'D' STMT STMTL SQLCA RETCODE
      *
      END TRANSACTION
      *
      IF RETCODE = 0
        WRITE 'Table NAT.DEMO created'
      ELSE
        FETCH 'SQLERR'
      END-IF
      END
      **************************************************************************

Anmerkung
Die Funktionalität der `DB2SERV`-Funktion `D` wird auch mit dem `PROCESS SQL`-Statement bereitgestellt.

#### Beispiel für Funktion D - DEM2SET:

      **************************************************************************
      *  DEM2SET - Set Current SQLID                                           *
      **************************************************************************
      *
      DEFINE DATA
      LOCAL USING DEMSQLCA
      LOCAL
      *                                   Parameter for DB2SERV
      1 STMT         (A250)
      1 STMTL        (I2)     CONST <250>
      1 RETCODE      (I2)
      1 OLDSQLID     (A8)
      1 NEWSQLID     (A8)
      *
      END-DEFINE
      *
      SELECT DISTINCT CURRENT SQLID
        INTO OLDSQLID
        FROM SYSIBM.SYSTABLES
      ESCAPE BOTTOM
      END-SELECT
      *
      MOVE  'SET CURRENT SQLID="PROD"';
        TO   STMT
      CALL 'DB2SERV' 'D' STMT STMTL SQLCA RETCODE
      *
      IF RETCODE > 0
        FETCH 'SQLERR'
      ELSE
        SELECT DISTINCT CURRENT SQLID
          INTO NEWSQLID
          FROM SYSIBM.SYSTABLES
        ESCAPE BOTTOM
        END-SELECT
      *
        WRITE ' Old SQLID was :' OLDSQLID
        WRITE ' New SQLID is  :' NEWSQLID
      END-IF
      *
      END
      **************************************************************************

Bei Verwendung von `SET CURRENT SQLID` kann der Ersteller-Name (Creator Name) einer Tabelle durch die aktuelle SQLID ersetzt werden. Damit ist es möglich, auf identische Tabellen mit demselben Tabellennamen, aber mit unterschiedlichen Ersteller-Namen zuzugreifen. Tabellennamen dürfen also nicht durch einen Ersteller-Namen qualifiziert werden, wenn dieser durch die SQLID ersetzt werden soll.

In allen unterstützten TP-Monitor-Umgebungen kann die `SQLID` dann über Terminal-Ein-/Ausgaben hinweg beibehalten werden, bis entweder die Sitzung beendet oder sie über `DB2SERV` zurückgesetzt wird.

### Funktion P

Die Funktion `P` ruft ein Assembler-Modul namens `NDBPLAN` auf, das zum Aufbau und/oder Abbau der Db2-Verbindung unter TSO und im Batch-Modus verwendet wird. Damit kann eine Natural-Anwendung eine Planumschaltung unter TSO und im Batch-Modus durchführen.

Das Programm `DEM2PLAN` ist ein Anwendungsbeispiel für den Einsatz von `DB2SERV` mit der Funktion `P`.

Der Name des aktuellen Db2-Subsystems (`#SSM`) und der Name des neuen Anwendungsplans (`#PLAN`) müssen angegeben werden. Außerdem werden ein Schnittstellen-Rückgabecode (`#RETCODE`) und der Db2-Ursachencode (`#REASON`) zurückgegeben.

#### Kommando-Syntax

    CALL 'DB2SERV' 'P' #SSM #PLAN #RETCODE #REASON

Variable | Format/Länge | Erläuterung
--- | --- | ---
`#SSM` | A4 | Enthält den Namen des aktuellen Db2-Subsystems.
`#PLAN` | A8 | Enthält den Namen des neuen Plans.
`#RETCODE` |  | Gibt einen Schnittstellen-Rückgabecode zurück. Die folgenden Codes sind möglich:
0 | Keine Warnung bzw. kein Fehler aufgetreten.
12 | Der angegebene neue Anwendungsplan ist nicht eingeplant.
99 | Die aktuelle Umgebung ist keine Call Attachment Facility-Umgebung (CAF).
`nnn` | Rückgabecode aus der CAF-Schnittstelle (siehe auch die entsprechende Db2-Literatur von IBM).
`#REASON` | I4 | Gibt den Ursachencode der CAF-Schnittstelle zurück (siehe auch die entsprechende Db2-Literatur von IBM).

#### Beispiel für Funktion P - DEM2PLAN:

      **************************************************************************
      *  DEM2PLAN - Switch application plan under TSO/Batch with CAF interface *
      **************************************************************************
      *
      DEFINE DATA
      LOCAL
      *                                   Parameter for DB2SERV
      01 #SSM         (A4))    CONST <'DB2'>
      01 #PLAN        (A8
      01 #RETCODE     (I2)
      01 #REASON      (I4)
      *
      END-DEFINE
      *
      INPUT 'PLEASE ENTER NEW PLAN NAME' #PLAN (AD='_'I)
      *
      END TRANSACTION
      *
      CALL 'DB2SERV' 'P' #SSM #PLAN #RETCODE #REASON
      *
      DECIDE FOR FIRST VALUE OF #RETCODE
      *
        VALUE  0
          IGNORE
        VALUE  99
          INPUT 12/23 'This is not a CAF environment !!'
        VALUE  8,12
          INPUT 12/18 'New plan not scheduled, reason code'
                       #REASON (AD=OI EM=H(4))
        NONE
          INPUT 12/15 'CAF interface error'
                       #RETCODE (AD=OI EM=Z(3))
                      'with reason code'
                       #REASON (AD=OI EM=H(4))
      *
      END-DECIDE
      *
      END
      **************************************************************************

Wichtig
Die Planumschaltung unter TSO und im Batch-Modus ist nur mit der CAF-Schnittstelle möglich; siehe auch den Abschnitt Planumschaltung unter TSO und im Batch-Modus.

### On this page

- Natural-Subprogramme
- Subprogramm NDBCONV
- Subprogramm NDBDBRM
- Subprogramm NDBDBR2
- Subprogramm NDBDBR3
- Subprogramm NDBERR
- Subprogramm NDBISQL
- Subprogramm NDBISQLD
- Subprogramm NDBNOERR
- Subprogramm NDBNROW
- Subprogramm NDBSTMP
- DB2SERV-Schnittstelle