Sie können große Objekte, wie beispielsweise Abbilder, Audioclips und Videoclips, auf verschiedene Weisen zwischen der Anwendung und einer DB2-Datenbank übertragen. Die verwendete Methode hängt davon ab, ob das Objekt aus einer/einem bzw. in eine Datei oder in einen Speicherpuffer übertragen wird. Die verwendete Methode hängt außerdem davon ab, ob die Datei sich auf der Client-Maschine oder dem Datenbank-Server befindet.
Wenn Sie ein Objekt zwischen einer Datenbanktabelle und einer Server-Datei übertragen, müssen Sie den Dateipfad in der entsprechenden Anforderung für die benutzerdefinierte Extender-Funktion angeben. Da sich die benutzerdefinierte Extender-Funktion und die Datei auf dem Server befinden, kann der Extender die Datei finden. In der folgenden SQL-Anweisung wird beispielsweise ein Abbild, dessen Inhalt sich in einer Server-Datei befindet, in einer Datenbanktabelle gespeichert:
EXEC SQL BEGIN DECLARE SECTION; long hvStorageType; EXEC SQL END DECLARE SECTION; hvStorageType=MMDB_STORAGE_TYPE_INTERNAL; EXEC SQL INSERT INTO EMPLOYEE VALUES( '128557', 'Anita Jones', DB2Image( CURRENT SERVER, '/employee/images/ajones.bmp', 'ASIS', :hvStorageType, 'Anita''s picture') );
Die Extender können nicht direkt auf einen Speicherpuffer zugreifen. Wenn Sie ein Objekt in einen oder aus einem Puffer auf Ihrer Client-Maschine übertragen wollen, müssen Sie eine Methode verwenden, bei der kein Speicherstandort angegeben wird. Eine Möglichkeit für die Übertragung ist die Verwendung einer Host-Variablen. Mit dieser Methode werden im allgemeinen Objekte zwischen einer Anwendung und einer DB2-Datenbank übertragen.
Host-Variablen für große Objekte werden auf die gleiche Weise definiert und verwendet wie für herkömmliche Zeichenobjekte und numerische Objekte. Sie deklarieren die Host-Variablen in einem DECLARE-Abschnitt, ordnen ihnen Werte für die Übertragung zu oder greifen auf die Werte zu, die an sie übertragen wurden.
Geben Sie den Datentyp BLOB an, wenn Sie eine Host-Variable für Abbild-, Audio- oder Videodaten deklarieren. Wenn Sie eine benutzerdefinierte Funktion (UDF) verwenden, um ein Objekt zu speichern, abzurufen oder zu ändern, wird die entsprechende Host-Variable als Argument in der UDF-Anforderung angegeben. Verwenden Sie das gleiche Format wie für andere Host-Variablen, die in einer SQL-Anweisung angegeben werden.
Im folgenden Beispiel wird durch die SQL-Anweisungen eine Host-Variable mit dem Namen hvaudio deklariert und verwendet, um einen Audioclip an die Datenbank zu übertragen:
EXEC SQL BEGIN DECLARE SECTION; SQL TYPE IS BLOB (2M) hvaudio; EXEC SQL END DECLARE SECTION; EXEC SQL INSERT INTO EMPLOYEE VALUES( '128557', 'Anita Jones', DB2Audio( CURRENT SERVER, :hvaudio, 'WAVE', CAST(NULL as LONG VARCHAR), 'Anita''s voice') );
Objekte, wie beispielsweise Audio- und Videoclips, können sehr groß sein, so daß die Verwendung von Host-Variablen möglicherweise nicht die effizienteste Methode ist, sie zu bearbeiten. Ein LOB-Zeiger kann eine günstigere Methode sein, LOBs (Large Objects) in Ihren Anwendungen zu bearbeiten.
Ein LOB-Zeiger ist ein kleiner (4 Byte großer) Wert, der in einer Host-Variablen gespeichert ist, und den das Programm verwenden kann, um auf ein wesentlich größeres LOB zu verweisen. Mit Hilfe eines LOB-Zeigers kann das Programm das LOB bearbeiten, als sei das LOB in einer normalen Host-Variablen gespeichert. Der Unterschied liegt darin, daß das LOB nicht zwischen dem Datenbank-Server und der Anwendung auf der Client-Maschine übertragen werden muß. Wenn Sie beispielsweise ein LOB in einer Datenbanktabelle auswählen, verbleibt der LOB auf dem Server und der LOB-Zeiger wird an den Client übertragen.
Ein LOB-Zeiger wird in einem DECLARE-Abschnitt deklariert und auf die gleiche Weise verwendet wie eine Host-Variable. Geben Sie den Datentyp BLOB_LOCATOR an, wenn Sie einen LOB-Zeiger für Abbild-, Audio- oder Videodaten deklarieren. Im folgenden Beispiel wird durch die SQL-Anweisungen ein LOB-Zeiger mit dem Namen video_loc deklariert, um ein ein Videoclip aus einer Datenbanktabelle abzurufen:
EXEC SQL BEGIN DECLARE SECTION; SQL TYPE IS BLOB_LOCATOR video_loc; EXEC SQL END DECLARE SECTION; EXEC SQL SELECT CONTENT(VIDEO) INTO :video_loc FROM EMPLOYEE WHERE NAME='Anita Jones';
UDFs verwenden LOB-Zeiger: DB2 Extender-UDFs, die Abbild-, Audio- und Videoobjekte speichern, abrufen und aktualisieren, verwenden LOB-Zeiger. Unter DB2 Extender V1 verwendeten diese UDFs keine LOB-Zeiger und konnten aus diesem Grund keine Objekte verarbeiten, die größer als 2 MB waren. Aufgrund dieser Einschränkung waren Benutzer gezwungen, Objekte, die größer als 2 MB waren, in Segmenten zu übertragen. Da diese UDFs jetzt LOB-Zeiger verwenden, entfällt die Einschränkung auf 2 MB.
Eine Dateireferenzvariable wird verwendet, um Objekte in eine oder aus einer Datei auf einem Client zu übertragen. Durch die Verwendung einer Dateireferenzvariablen ist es nicht mehr notwendig, für ein großes Objekt in Ihrem Anwendungsprogramm Pufferbereich zuzuordnen. Wenn Sie eine Dateireferenzvariable mit einer benutzerdefinierten Funktion (UDF) verwenden, findet die Übergabe des BLOB-Inhalts direkt zwischen Datei und UDF statt.
Eine Dateireferenzvariable wird in einem DECLARE-Abschnitt deklariert und auf die gleiche Weise verwendet wie eine Host-Variable. Geben Sie den Datentyp BLOB_FILE an, wenn Sie eine Dateireferenzvariable für Abbild-, Audio- oder Videodaten deklarieren. Im Gegensatz zu einer Host-Variablen, die den Inhalt eines Objekts enthält, enthält eine Dateireferenzvariable den Namen der Datei. Die Datei kann nicht größer sein, als die für die UDF definierte Größe des BLOB.
Für die Verwendung einer Dateireferenzvariablen für die Ein- und Ausgabe bestehen verschiedene Optionen. Wählen Sie die gewünschte Option aus, indem Sie das Feld FILE_OPTIONS in der Struktur der Dateireferenzvariablen im Programm definieren. Folgende Optionen stehen zur Verfügung:
Option für die Eingabe:
SQL_FILE_READ. Diese Datei kann geöffnet, gelesen und geschlossen werden. Die Länge der Daten in der Datei (in Byte) wird beim Öffnen der Datei festgelegt. Das Feld data_length in der Struktur der Dateireferenzvariablen enthält die Länge der Datei (in Byte).
Optionen für die Ausgabe:
Die Anweisungen im folgenden Beispiel deklarieren eine Dateireferenzvariable mit dem Namen Img_file und verwenden sie, um ein Abbild, dessen Inhalt sich in einer Client-Datei befindet, in einer Datenbanktabelle zu speichern. Beachten Sie die Zuordnung SQL_FILE_READ im Feld FILE_OPTIONS:
EXEC SQL BEGIN DECLARE SECTION; SQL TYPE IS BLOB_FILE Img_file; EXEC SQL END DECLARE SECTION; strcpy (Img_file.name,"/employee/images/ajones.bmp"); Img_file.name_length=strlen(Img_file.name); Img_file.file_options=SQL_FILE_READ; EXEC SQL INSERT INTO EMPLOYEE VALUES( '128557', 'Anita Jones', DB2Image( CURRENT SERVER, :Img_file, 'ASIS', CAST(NULL as LONG VARCHAR), 'Anita''s picture') );
Die DB2 Extender geben Ihnen verschiedene Möglichkeiten, wie Sie Dateinamen beim Speichern, Abrufen und Aktualisieren von Objekten angeben können.
Sie können einen vollständig qualifizierten Dateinamen (d. h. einen vollständigen Pfad, gefolgt vom Dateinamen) für Speicher-, Abruf- und Aktualisierungsoperationen angeben; die Angabe eines relativen Pfadnamens ist jedoch vorteilhafter. Unter AIX, HP-UX und Solaris ist ein relativer Dateiname jeder Dateiname, der nicht mit einem Schrägstrich beginnt. Unter OS/2 und Windows ist ein relativer Dateiname jeder Dateiname, der nicht mit einem Laufwerkbuchstaben, gefolgt von einem Doppelpunkt und einem umgekehrte Schrägstrich, beginnt.
Wenn Sie einen relativen Dateinamen angeben, verwenden die Extender die Verzeichnisangaben in den verschiedenen Client- und Server-Umgebungsvariablen als Suchpfad, um den Dateinamen aufzulösen. Ein vollständiger Pfadname besteht aus einem führenden Teil, der sich normalerweise auf Mount-Punkte bezieht, und einem abschließenden Pfadnamen, der die benötigte Datei eindeutig identifiziert. Der abschließende Pfadname ist in UDFs angegeben. Umgebungsvariablen liefern eine Liste von führenden Pfadnamen, die durchsucht werden soll, wenn versucht wird, relative Dateinamen aufzulösen. Weitere Informationen zu den Umgebungsvariablen, die von den DB2 Extendern verwendet werden, um Dateinamen aufzulösen, befinden sich in Anhang A, Umgebungsvariablen für DB2 Extender einstellen.
Außerdem setzen die Extender, falls erforderlich, die Formate der Dateinamen um. Wird ein Dateiname an den Server übergeben, wird er in das Dateiformat für das Betriebssystem des Servers umgesetzt. So wird z. B. ein OS/2-Dateiname, wie etwa :\dir1\abc.bmp in das Format /dir1/abc.bmp umgesetzt, wenn er an einen AIX-Server übergeben wird.
Alle eingebetteten SQL-Anweisungen oder DB2 CLI-Aufrufe in Ihrem Programm, einschließlich derer, die DB2 Extender UDFs anfordern, generieren Codes, die angeben, ob die eingebettete SQL-Anweisung oder der DB2 CLI-Aufruf erfolgreich ausgeführt wurde. Andere DB2 Extender-APIs, wie z. B. Verwaltungs-APIs, geben auch Code zurück, der angibt, ob die API erfolgreich oder nicht erfolgreich ausgeführt wurde. Ihr Programm sollte die Codes, die von eingebetteten SQL-Anweisungen, CLI-Aufrufen und APIs zurückgegeben werden, überprüfen und entsprechend auf sie reagieren.
Informationen zur Verwendung dieser Rückkehrcodes befinden sich in Kapitel 19, Diagnoseinformationen.
In Situationen, in denen eine Extender-API ihre Arbeitseinheiten nicht erfolgreich abschließen kann, wird eine ROLLBACK-Operation ausgeführt. Die API gibt außerdem einen Fehlercode zurück. Die ROLLBACK-Operation wird ausgeführt, damit die Datenbank zum vorherigen konsistenten Stand zurückkehren kann. Nähere Einzelheiten finden Sie in Kapitel 16, Anwendungsprogrammierschnittstellen.