Funktionsgruppe: Tabellenfunktion
Mit der Tabellenfunktion CSV() können Sie den Inhalt einer BS2000-Datei als „read-only“ Tabelle in beliebigen SQL-Anweisungen verwenden.
Für die Darstellung von SQL-Tabellen in Dateien wird dabei das CSV-Format verwendet (CSV: Comma Separated Values). Das ist ein standardisiertes Format für den plattform-unabhängigen Austausch von tabellarischen Daten, siehe „Format von CSV-Dateien". Die Datei enthält die Folge von Zeilen der Tabelle, wobei jede Zeile der Reihe nach ihre Spaltenwerte als Zeichenketten enthält. Solche Dateien können mit vielen Softwareprodukten (z.B. mit Microsoft EXCEL) erzeugt werden.
CSV ([FILE] datei DELIMITER delimiter [QUOTE quote ] [ESCAPE escape ], datentyp ,...)
FILE datei
Name der Eingabedatei. datei muss als alphanumerisches Literal angegeben werden.
Die Eingabedatei muss eine SAM-Datei sein.
Liegt die Eingabedatei nicht in der Kennung des DBH, so muss die DBH-Kennung eine Leseberechtigung für diese Datei haben. Andernfalls kann der DBH nicht auf die Eingabedatei zugreifen.
Wenn ein Lesekennwort für die Datei benötigt wird, so muss dieses in der Form ?PASSWORD=< kennwort > an den BS2000-Dateinamen angefügt werden,
z.B. ':8OSH:$ABC.MYFILE?PASSWORD=C''ABCD'''.
Für die Angabe von kennwort gibt es folgende Möglichkeiten:
C
''zeichenkette''
zeichenkette enthält vier abdruckbare Zeichen.X
''hex-zeichenkette''
hex-zeichenkette enthält acht sedezimale Zeichen.n
n bezeichnet eine ganze Zahl von - 2147483648 bis + 2147483647
DELIMITER delimiter
Trennzeichen (DELIMITER-Zeichen) zwischen den Spaltenwerten der CSV-Datei. Ein DELIMITER-Zeichen kann auch Bestandteil eines Wertes sein, siehe die nachfolgenden Beschreibungen zu quote und escape.
delimiter muss als alphanumerisches Literal der Länge 1 angegeben werden.
QUOTE quote
Anführungszeichen (QUOTE-Zeichen), in das die Spaltenwerte in der CSV-Datei eingeschlossen sein können. Diese QUOTE-Zeichen gehören nicht zum Spaltenwert. Ein QUOTE-Zeichen im Spaltenwert muss in der CSV-Datei verdoppelt werden. Wenn ein Wert in QUOTE-Zeichen eingeschlossen ist, dann kann er auch NEWLINE-Zeichen (die nicht als Zeilenwechsel interpretiert werden) oder DELIMITER-Zeichen enthalten. Ein Wert, der lediglich aus einem öffnenden und schließenden QUOTE-Zeichen besteht, wird als Wert der Länge 0 interpretiert.
quote muss als alphanumerisches Literal der Länge 1 angegeben werden.Wenn QUOTE nicht angegeben ist, dann können die Spaltenwerte in der CSV-Datei nicht in QUOTE-Zeichen eingeschlossen werden.
ESCAPE escape
Entwertungszeichen (ESCAPE-Zeichen), mit dem ESCAPE-Folgen, bestehend aus zwei Zeichen, in der Eingabedatei beginnen.
Mit ESCAPE-Folgen können DELIMITER-Zeichen, QUOTE-Zeichen und ESCAPE-Zeichen als Teil eines Spaltenwerts geschrieben und NEWLINE-Zeichen als Trenner zwischen zwei Eingabezeilen ignoriert werden.
escape muss als alphanumerisches Literal der Länge 1 angegeben werden.Wenn ESCAPE nicht angegeben ist, dann können in der CSV-Datei keine ESACPE-Folgen verwendet werden.
delimiter, quote und escape müssen unterschiedliche Zeichen sein.
datentyp,...
Datentypen der einzelnen Spalten der Tabelle, die aus der CSV-Datei gelesen wird.Jeder datentyp muss ein Datentyp CHARACTER(n) (mit 1 <= n <= 256) oder CHARACTER VARYING(n) (mit 1 <= n <= 32000 ) sein.
Ergebnis
Eine Tabelle mit ebensovielen Spalten, wie Datentypen angegeben sind, jeweils mit dem angegebenen Datentyp.
Beispiel
Es wird eine neue Basistabelle LEIST_ENCR aufgebaut. Ihr Inhalt wird einer CSV-Datei entnommen.
 | INSERT INTO leist_encr (letext, lesatz_encr)
SELECT a,b
FROM TABLE(CSV(FILE 'out.leistung.070' DELIMITER ':',
CHAR(25),VARCHAR(16)))
AS t(a,b)
|
Format von CSV-Dateien
Das CSV-Format (CSV: Comma Separated Values) ist ein standardisiertes Format für den plattform-unabhängigen Austausch von tabellarischen Daten. Solche Dateien können mit vielen Softwareprodukten (z.B. mit Microsoft EXCEL) erzeugt und bearbeitet werden.
Tabellen werden in CSV-Dateien als Folge von Zeilen dargestellt, wobei die Zeilen in der Datei durch (ein oder mehrere) NEWLINE-Zeichen (Zeilenwechsel) getrennt werden. Auch der Übergang zum nächsten Satz in einer SAM-Datei ist ein solcher Zeilenwechsel, obwohl er kein EBCDIC-Zeichen ist. In einem Satz einer SAM-Datei können mehrere Zeilen, getrennt durch ein NEWLINE-Zeichen, stehen. Auch vor der ersten und nach der letzten Zeile dürfen Zeilenwechsel vorkommen.
In einer Zeile werden die einzelnen Spaltenwerte durch ein einzelnes DELIMITER-Zeichen getrennt. Auch nach dem letzten Spaltenwert einer Zeile darf ein DELIMITER-Zeichen stehen.
Für die Darstellung der einzelnen Spaltenwerte in jeder Zeile gibt es zwei Formen: die einzelnen Zeichen der Spalte können in QUOTE-Zeichen eingeschlossen werden oder nicht. Im ersten Fall können die Spaltenwerte auch NEWLINE- und das DELIMITER-Zeichen enthalten. Allerdings muss ein QUOTE-Zeichen im Spaltenwert verdoppelt werden (sonst beendet es den Spaltenwert). Spaltenwerte in QUOTE-Zeichen können nur dann verwendet werden, wenn in der CSV-Funktion der Operand QUOTE angegeben ist.Beginnt ein Spaltenwert nicht mit dem QUOTE-Zeichen (oder ist der Operand QUOTE nicht in der CSV-Funktion angegeben), dann endet der Spaltenwert vor dem nächsten DELIMITER- oder NEWLINE-Zeichen.
In SESAM/SQL können Sie auch ein ESCAPE-Zeichen definieren. Mit dem ESCAPE-Zeichen können Sie innerhalb des Spaltenwerts ESCAPE-Folgen verwenden, die wie folgt interpretiert werden:
Escape-Folge | wird interpretiert als |
escape newline | „kein Zeichen“ |
escape delimiter | ein DELIMITER-Zeichen |
escape quote | ein QUOTE-Zeichen |
escape escape | ein ESCAPE-Zeichen |
ESCAPE-Folgen sind auch in Spaltenwerten erlaubt, die in QUOTE-Zeichen eingeschlossen sind. Insbesondere ESCAPE NEWLINE ist nützlich, denn wenn am Ende eines SAM-Satzes ein ESCAPE-Zeichen steht, dann gilt damit die Zeile als noch nicht beendet und wird mit dem folgenden SAM-Satz fortgesetzt. Die Zeilen in einer CSV-Datei können damit länger sein als ein Satz in einer SAM-Datei von BS2000.
Wenn beim Lesen der CSV-Datei Fehler auftreten oder ein Verstoss gegen das CSV-Format festgestellt wird (z.B. bei Dateiende in einem Spaltenwert, der mit dem QUOTE-Zeichen beginnt, aber nicht damit endet), so wird dies mit Fehlercode angezeigt.
Anmerkung zu NEWLINE-Zeichen
Im CSV-Format werden vier EBCDIC Control Characters als NEWLINE-Zeichen interpretiert::
X'04' X'0D' | ist das Zeichen NEXT LINE ist das Zeichen CARRIAGE RETURN. Sein ASCII-Äquivalent wird in einigen |
X'15' | ist das Zeichen LINE FEED. Sein ASCII-Äquivalent wird in POSIX- und LINUX-Systemen |
X'25' | ist das Zeichen PRIVATE USE TWO. Es wird aber in EBCDIC-Systemen von IBM |
Das CSV-Format akzeptiert alle diese Control Characters (ebenso wie den Übergang zum nächsten Satz einer SAM-Datei) als Zeilenwechsel.
Syntax einer CSV-Datei
Eine syntaktische Darstellung des Formats einer CSV-Datei finden Sie in "Syntaxübersicht CSV-Datei".
Interpretation von CSV-Dateien als SQL-Tabelle
In der CSV-Funktion werden die Anzahl der zu lesenden Spalten und ihre Datentypen angegeben. Diese Spalten entsprechen den Spaltenwerten in der CSV-Datei in derselben Reihenfolge. Wenn eine Zeile der CSV-Datei weniger Spaltenwerte enthält, dann werden NULL-Werte ergänzt. Wenn eine Zeile der CSV-Datei mehr Spaltenwerte enthält, dann werden die überschüssigen Spaltenwerte ignoriert.
Eine Zeile in einer CSV-Datei muss wenigstens ein Zeichen enthalten. Mehrere aufeinanderfolgende Zeilenwechsel werden wie ein Zeilenwechsel behandelt.
Ein leerer Spaltenwert (z.B. zwischen zwei aufeinanderfolgenden DELIMITER-Zeichen) wird als NULL-Wert interpretiert.
Ein Spaltenwert, der länger ist als die (maximale) Länge des Datentyps der Spalte, wird gekürzt. Es wird eine Warnung ausgegeben.
Wenn der Datentyp der Spalte CHARACTER(n), aber der Spaltenwert kürzer als n ist, dann wird wird der Spaltenwert am Ende mit Leerzeichen (X'40') ergänzt.
Ein Spaltenwert der Länge 0 lässt sich mit QUOTE-Zeichen schreiben, z.B. als "";wenn in der CSV-Funktion DELIMITER ';' QUOTE '"' angegeben wird.
Einschränkungen bei der Verwendung von CSV-Dateien
Die BS2000-Datei wird exklusiv geöffnet. Sie kann deshalb nicht gleichzeitig von derselben oder einer anderen SQL-Transaktion in einer weiteren CSV-Funktion verwendet werden. Eine Abhilfe bietet die CACHE-Annotation, bei der die CSV-Datei temporär zwischengespeichert wird, siehe das Handbuch „ Performance“.
Wenn die Datei nicht geöffnet werden kann, dannn wird eine Fehlermeldung ausgegeben und die Bearbeitung abgebrochen.
Die Datei wird erst geschlossen, wenn die sie enthaltende Abfrage vollständig ausgewertet wurde, wenn die Abfrage nicht mehr benötigt wird (z.B. weil der Cursor, der die Datei verwendet hat, geschlossen wird) oder wenn die CSV-Datei zwischengespeichert ist.
Darüber hinaus gibt es eine Maximalzahl von CSV-Dateien (derzeit: 4), die gleichzeitig geöffnet sein dürfen. Wenn diese Maximalzahl überschritten ist, dann wird eine entsprechende Fehlermeldung ausgegeben.
Wenn für die verwendete Datenbank und für die CSV-Datei jeweils ein codierter Zeichensatz (CODE_TABLE ungleich _NONE_ bzw. CODED-CHARACTER-SET ungleich *NONE) definiert ist, dann müssen die beiden angegebenen Namen gleich sein.