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

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.