VARCHAR_FORMAT Skalarfunktion

Die Funktion VARCHAR_FORMAT gibt eine Zeichendarstellung eines Eingabeausdrucks zurück.

Zeichenfolge in VARCHAR

DATE oder TIMESTAMP in VARCHAR

Numerisch mit Vorzeichen in VARCHAR

Das Schema ist SYSIBM.

Wenn ein Argument der Funktion VARCHAR_FORMAT null sein kann, kann das Ergebnis null sein. Wenn ein Argument null ist, ist das Ergebnis der Nullwert.

Zeichenfolge in VARCHAR

zeichenausdruck: Ein Ausdruck, der einen Wert zurückgibt, der ein integrierter Datentyp CHAR oder VARCHAR sein muss. Wenn es sich bei einem angegebenen Argument um einen Datentyp GRAPHIC oder VARGRAPHIC handelt, wird es in einer Unicode-Datenbank zunächst in VARCHAR konvertiert, bevor die Funktion ausgewertet wird.

Das Ergebnis ist ein VARCHAR mit einem Längenattribut, das dem Längenattribut des Arguments entspricht. Der Wert des Ergebnisses ist mit dem Wert von zeichenausdruckidentisch.

Die Codepage des Ergebnisses ist die Codepage des Abschnitts.

DATE oder TIMESTAMP in VARCHAR

Datums-oder Zeitmarkenausdruck

Ein Ausdruck, der einen Wert zurückgibt, der ein DATE-oder TIMESTAMP sein muss, oder eine gültige Zeichenfolgedarstellung eines Datums oder einer Zeitmarke, die kein CLOB oder DBCLOB ist. Wenn der Ausdruck in einer Unicode-Datenbank eine grafische Zeichenfolgedarstellung eines Datums oder einer Zeitmarke zurückgibt, wird der zurückgegebene Wert zuerst in eine Zeichenfolge konvertiert, bevor die Funktion ausgewertet wird.

Wenn der Eingabeausdruck Folgendes zurückgibt:

Eine Zeichenfolge; das Argument formatzeichenfolge muss ebenfalls angegeben werden.
Ein DATE oder eine Zeichenfolgedarstellung eines Datums. Der zurückgegebene Wert wird zuerst in einen TIMESTAMP (0) -Wert mit einer Zeitkomponente von genau Mitternacht (00.00.00) konvertiert.
Eine Zeichenfolgedarstellung einer Zeitmarke, die zuerst in einen TIMESTAMP (12) -Wert konvertiert wird.

Eine Liste der gültigen Formate für Zeichenfolgedarstellungen von Werten für Datum und Uhrzeit finden Sie unter Zeichenfolgedarstellungen von Werten für Datum und Uhrzeit.

format-string1

Ein Ausdruck, der einen Wert mit einem der folgenden integrierten Datentypen zurückgibt:

Char oder Varchar
numerisch mit Vorzeichen
Datum/Zeit
GRAPHIC oder VARGRAPHIC (nur Unicode-Datenbanken)

Wenn der Datentyp nicht CHAR oder VARCHAR ist, wird er implizit in VARCHAR umgesetzt, bevor die Funktion ausgewertet wird. Die tatsächliche Länge darf nicht größer als 255 Byte sein (SQLSTATE 22007). Der Wert ist eine Vorlage für die Formatierung von zeitmarkenausdruck .

Die Standardformatzeichenfolge basiert auf dem Wert des Sonderregisters CURRENT LOCALE LC_TIME.

Eine gültige Formatierzeichenfolge muss eine Kombination der in Tabelle 1 aufgelisteten Formatelemente enthalten (SQLSTATE 22007). Zwei Formatelemente können optional durch eines oder mehrere der folgenden Trennzeichen getrennt werden:

Minuszeichen (-)
Punkt (.)
Schrägstrich (/)
Komma (,)
Hochkomma (')
Semikolon (;)
Doppelpunkt (:)
leer ()

Trennzeichen können auch am Anfang oder am Ende von formatzeichenfolgeangegeben werden.

Tabelle 1. Formatelemente für DATE oder TIMESTAMP in VARCHAR
Formatelement	Beschreibung
AM oder PM	Meridiananzeiger (morgens oder abends) ohne Punkte. Dieses Formatelement ist abhängig von `ländereinstellungsname`, falls angegeben; andernfalls hängt es vom Wert des Sonderregisters CURRENT LOCALE LC_TIME ab.
a.m. oder p.m. (vor- oder nachmittags)	Meridiananzeiger (morgens oder abends) mit Zeiträumen Dieses Formatelement verwendet die exakten Zeichenfolgen 'A.M. ' oder 'P.M. ' und ist unabhängig vom gültigen Ländereinstellungsnamen.
UT	Jahrhundert (01-99). Wenn die letzten beiden Ziffern des vierstelligen Jahres null sind, ist das Ergebnis die ersten beiden Ziffern des Jahres; andernfalls ist das Ergebnis die ersten beiden Ziffern des Jahres plus eins.
DAY, Day oder Day	Name des Tages in Großbuchstaben, Titleasen oder Kleinbuchstaben. Die verwendete Sprache hängt von `ländereinstellungsname`ab, falls angegeben. Andernfalls hängt sie vom Wert des Sonderregisters CURRENT LOCALE LC_TIME ab.
DY, Dy oder dy	Abgekürzter Name des Tages in Großbuchstaben, Titlecase oder Kleinbuchstaben. Die verwendete Sprache hängt von `ländereinstellungsname`ab, falls angegeben. Andernfalls hängt sie vom Wert des Sonderregisters CURRENT LOCALE LC_TIME ab.
D	Wochentag (1-7). Der erste Tag der Woche hängt von `ländereinstellungsname`ab, sofern angegeben; andernfalls hängt er vom Wert des Sonderregisters CURRENT LOCALE LC_TIME ab.
DD	Tag des Monats (01-31)
DDD	Tag des Jahres (001-366).
FF oder FFn	Sekundenbruchteile (0-999999999999), wobei n die Skala des zurückgegebenen Werts angibt. Gültige Werte für n sind 1-12 ohne führende Nullen. Die Angabe von FF entspricht der Angabe von FF6. Wenn die Skala der Eingabezeitmarke kleiner als nist, wird das Ergebnis mit abschließenden Nullen aufgefüllt.
HH	HH verhält sich wie HH12.
HH12	Stunde des Tages (01-12) im 12-Stunden-Format.
HH24	Stunde des Tages (00-24) im 24-Stunden-Format.
I	ISO-Jahr (0-9). Die letzte Ziffer des Jahres basierend auf der ISO-Woche, die zurückgegeben wird.
ID	ISO-Wochentag (1-7). 1 ist Montag und 7 ist Sonntag.
IW	ISO-Woche des Jahres (01-53). Die Woche beginnt am Montag und umfasst sieben Tage. Woche 1 ist die erste Woche des Jahres, die einen Donnerstag enthält, was der ersten Woche des Jahres entspricht, die den 4. Januar enthalten soll.
IY	ISO-Jahr (00-99). Die letzten beiden Ziffern des Jahres, basierend auf der ISO-Woche, die zurückgegeben wird
IYY	ISO-Jahr (000-999). Die letzten drei Ziffern des Jahres basierend auf der ISO-Woche, die zurückgegeben wird.
IYYY	ISO-Jahr (0000-9999). Das vierstellige Jahr basierend auf der ISO-Woche, die zurückgegeben wird.
J	Julianischer Tag (Anzahl der Tage seit 1. Januar 4713 v. Chr.).
MIN	Minute (00-59).
Mittel	Monat (01-12).
MONTH, Month oder month	Name des Monats in Großbuchstaben, Titleasen oder Kleinbuchstaben. Die verwendete Sprache hängt von `ländereinstellungsname`ab, falls angegeben. Andernfalls hängt sie vom Wert des Sonderregisters CURRENT LOCALE LC_TIME ab.
MON, Mon oder mon	Abgekürzter Name des Monats in Großbuchstaben, Titleasen oder Kleinbuchstaben. Die verwendete Sprache hängt von `ländereinstellungsname`ab, falls angegeben. Andernfalls hängt sie vom Wert des Sonderregisters CURRENT LOCALE LC_TIME ab.
NNNNNN	Mikrosekunden (000000-999999). Entspricht FF6.
Q	Quartal (1-4), wobei die Monate Januar bis März 1.
RR	RR verhält sich wie YY.
RRRR	RRRR verhält sich wie JJJJ.
SS	Sekunden (00-59).
SSSSS	Sekunden seit vorheriger Mitternacht (00000-86400).
W	Woche des Monats (1-5), wobei Woche 1 am ersten Tag des Monats beginnt und am siebten Tag endet.
WW	Woche des Jahres (01-53), wobei Woche 1 am 1. Januar beginnt und am 7. Januar endet.
Y	Letzte Ziffer des Jahres (0-9).
JJ	Die letzten beiden Ziffern des Jahres (00-99)
YYY	Die letzten drei Ziffern des Jahres (000-999)
YYYY	4-stelliges Jahr (0000-9999)

Bei den Formatelementen in Tabelle 1 muss die Groß-/Kleinschreibung nicht beachtet werden, mit den folgenden Ausnahmen:

Vormittags, nachmittags
A.M., P.M.
TAG, Tag, Tag
DY, Dy, dy
D
MONAT, Monat, Monat
Mo, Mo, Mo

In Fällen, in denen Formatelemente mehrdeutig sind, werden die von der Groß-/Kleinschreibung unabhängigen Formatelemente zuerst berücksichtigt. Beispiel: 'TTJJJJ' würde als "TT gefolgt von JJJJ" interpretiert, nicht als "D gefolgt von DY gefolgt von JJJ".

ländereinstellungsname

Eine Zeichenkonstante, die die Ländereinstellung angibt, die für die folgenden Formatelemente verwendet wird:

Vormittags, nachmittags
TAG, Tag, Tag
DY, Dy, dy
D
MONAT, Monat, Monat
Mo, Mo, Mo

Bei dem angegebenen Ländereinstellungsnamen muss die Groß-/Kleinschreibung nicht beachtet werden und er muss eine gültige Ländereinstellung sein (SQLSTATE-Wert 42815). Informationen zu gültigen Ländereinstellungen und deren Benennung finden Sie unter Ländereinstellungsnamen für SQL und XQuery. Der Standardwert ist der Wert des Sonderregisters CURRENT LOCALE LC_TIME.

Das Ergebnis ist eine Darstellung des Eingabezeitmarkenausdrucks in dem durch die Formatierzeichenfolge angegebenen Format. Die Formatierzeichenfolge wird als eine Reihe von Formatelementen interpretiert, die durch ein oder mehrere Trennzeichen voneinander getrennt werden können. Eine Zeichenfolge in der Formatzeichenfolge wird als das längste übereinstimmende Formatelement in Tabelle 1interpretiert. Wenn zwei Formatelemente, die dieselben Zeichen enthalten, nicht durch ein Trennzeichen begrenzt werden, wird die Spezifikation ausgehend von links als das längste übereinstimmende Formatelement in der Tabelle interpretiert und fortgesetzt, bis Übereinstimmungen für den Rest der Formatierzeichenfolge gefunden werden. Beispiel: 'JJJJJJTT' wird als Formatelement 'JJJJ', 'JJ' und 'TT ' interpretiert.

Das Ergebnis ist eine Zeichenfolge variabler Länge. Das Längenattribut ist 255. Wenn die Zeichenfolgeeinheiten der Umgebung oder formatzeichenfolge CODEUNITS32ist, lautet die Zeichenfolgeeinheit des Ergebnisses CODEUNITS32. Andernfalls lautet die Zeichenfolgeeinheit des Ergebnisses OCTETS. Die formatzeichenfolge bestimmt die tatsächliche Länge des Ergebnisses. Wenn die Ergebniszeichenfolge das Längenattribut des Ergebnisses überschreitet, wird das Ergebnis abgeschnitten.

Die Codepage des Ergebnisses ist die Codepage des Abschnitts.

Numerisch mit Vorzeichen in VARCHAR

numerischer_Ausdruck

Ein Ausdruck, der einen Wert eines beliebigen integrierten numerischen Datentyps mit Vorzeichen zurückgibt. Wenn der Datentyp des Werts nicht DECFLOAT ist, wird er zur Verarbeitung in DECFLOAT (34) konvertiert.

format-string2

Ein Ausdruck, der einen Wert mit einem der folgenden integrierten Datentypen zurückgibt:

Char oder Varchar
numerisch mit Vorzeichen
Datum/Zeit
GRAPHIC oder VARGRAPHIC (nur Unicode-Datenbanken)

Wenn der Datentyp nicht CHAR oder VARCHAR ist, wird er implizit in VARCHAR umgesetzt, bevor die Funktion ausgewertet wird. Die tatsächliche Länge darf 255 Byte nicht überschreiten (SQLSTATE 22018). Der Wert wird als Schablone zum Formatieren des dezimalen Gleitkommaausdrucks verwendet. Als Präfix angegebene Formatelemente können nur am Anfang der Schablone verwendet werden. Als Suffix angegebene Formatelemente können nur am Ende der Schablone verwendet werden. Die Vorlage darf nicht mehr als eines der Formatelemente MI, S oder PR enthalten (SQLSTATE 22018).

Wenn keine Formatzeichenfolge angegeben wird, wird der eingegebene dezimale Gleitkommaausdruck in Form einer SQL-dezimalen Gleitkommakonstante formatiert. Wenn der eingegebene dezimale Gleitkommaausdruck negativ ist, ist das erste Zeichen des Ergebnisses ein Minuszeichen; andernfalls ist das erste Zeichen eine Ziffer. Wenn der eingegebene dezimale Gleitkommaausdruck null ist, ist das Ergebnis 0.

Tabelle 2. Formatelemente für dezimale Gleitkommazahlen zu varchar
Formatelement	Beschreibung
0	Jede 0 steht für eine signifikante Ziffer. Führende Nullen in einer Zahl werden als Nullen angezeigt.
9	Jede 9 stellt eine signifikante Ziffer dar. Führende Nullen in einer Zahl werden als Leerzeichen angezeigt.
,	An der angegebenen Position wird ein Komma hinzugefügt, beispielsweise als Gruppentrennzeichen.
.	Ein Punkt wird an der angegebenen Position hinzugefügt, z. B. als Dezimalzeichen.
S	Präfix: Wenn der eingegebene dezimale Gleitkommaausdruck Folgendes zurückgibt: Eine negative Zahl, ein führendes Minuszeichen (-) wird zum Ergebnis hinzugefügt Eine positive Zahl, ein führendes Pluszeichen (+) wird zum Ergebnis hinzugefügt
$	Präfix: Dem Ergebnis wird ein führendes Dollarzeichen ($) hinzugefügt.
MIN	Suffix: Wenn der eingegebene dezimale Gleitkommaausdruck Folgendes zurückgibt: Eine negative Zahl, ein abschließendes Minuszeichen (-) wird zum Ergebnis hinzugefügt Eine positive Zahl, ein abschließendes Leerzeichen wird zum Ergebnis hinzugefügt
Bedarfsanforderung	Suffix: Wenn der eingegebene dezimale Gleitkommaausdruck Folgendes zurückgibt: Eine negative Zahl, ein führendes Kleiner-als-Zeichen (<) Dem Ergebnis wird ein nachfolgendes Größer-als-Zeichen (>) hinzugefügt. Eine positive Zahl, ein führendes Leerzeichen und ein nachfolgendes Leerzeichen werden zum Ergebnis hinzugefügt.

Bei den Formatelementen muss die Groß-/Kleinschreibung beachtet werden.

Das Ergebnis ist eine Zeichenfolgedarstellung variabler Länge des eingegebenen dezimalen Gleitkommaausdrucks. Das Längenattribut ist 255. Wenn die Zeichenfolgeeinheiten der Umgebung oder die Formatzeichenfolge CODEUNITS32ist, sind die Zeichenfolgeeinheiten des Ergebnisses CODEUNITS32; andernfalls sind die Zeichenfolgeeinheiten des Ergebnisses OCTETS. Die tatsächliche Länge des Ergebnisses wird durch die Formatzeichenfolge bestimmt, falls angegeben. Andernfalls ist die tatsächliche Länge des Ergebnisses die kleinste Anzahl von Zeichen, die den Wert des eingegebenen dezimalen Gleitkommaausdrucks darstellen können. Wenn die Ergebniszeichenfolge das Längenattribut des Ergebnisses überschreitet, wird das Ergebnis abgeschnitten.

Wenn der Wert des eingegebenen dezimalen Gleitkommaausdrucks der Sonderwert ist:

Infinity, die Zeichenfolge "INFINITY" wird zurückgegeben
sNaN, die Zeichenfolge "SNAN" wird zurückgegeben
NaNwird die Zeichenfolge "NAN" zurückgegeben.

Wenn der Sonderwert negativ ist, ist das erste Zeichen des Ergebnisses ein Minuszeichen (-). Der dezimale Gleitkomma-Sonderwert sNaN führt nicht zu einer Ausnahmebedingung, wenn er in eine Zeichenfolge konvertiert wird.

Wenn die Formatzeichenfolge keines der Formatelemente MI, S oder PR enthält und der Wert des Eingabeausdrucks negativ ist, wird ein Minuszeichen (-) in das Ergebnis eingeschlossen; andernfalls wird ein Leerzeichen in das Ergebnis eingeschlossen.

Wenn die Anzahl Ziffern links vom Dezimalzeichen im Eingabeausdruck größer ist als die Anzahl Ziffern links vom Dezimalzeichen in der Formatierzeichenfolge, ist das Ergebnis eine Zeichenfolge mit einem oder mehreren Nummernzeichen (#). Wenn die Anzahl der Stellen rechts vom Dezimalzeichen im Eingabeausdruck größer ist als die Anzahl der Stellen rechts vom Dezimalzeichen in der Formatierzeichenfolge, wird das Ergebnis auf die Anzahl der Stellen rechts vom Dezimalzeichen in der Formatierzeichenfolge gerundet. Der Rundungsmodus DECFLOAT wird nicht verwendet. Das Rundungsverhalten von VARCHAR_FORMAT entspricht einem Wert von ROUND_HALF_UP.

Die Codepage des Ergebnisses ist die Codepage des Abschnitts.

Hinweise

Julianischer Kalender und gregorianischer Kalender: Für "Timestamp to varchar" wird der Übergang vom Julianischen Kalender zum gregorianischen Kalender am 15. Oktober 1582 von dieser Funktion berücksichtigt.
Determinismus VARCHAR_FORMAT ist eine deterministische Funktion. Die folgenden Aufrufe der Funktion hängen jedoch vom Wert des Sonderregisters CURRENT LOCALE LC_TIME ab.
- Zeitmarke für varchar, wenn formatzeichenfolge nicht explizit angegeben wird oder wenn ländereinstellungsname nicht explizit angegeben wird und eine der folgenden Aussagen zutrifft:
  - formatzeichenfolge ist keine Konstante
  - formatzeichenfolge ist eine Konstante und enthält Formatelemente, die von der Ländereinstellung abhängig sind.
  Diese Aufrufe, die vom Wert eines Sonderregisters abhängen, können nicht verwendet werden, wenn keine Sonderregister verwendet werden können (SQLSTATE 42621, 428ECoder 429BX).
Syntaxalternativen: TO_CHAR ist ein Synonym für VARCHAR_FORMAT.

Beispiele

Beispiel 1: Anzeigen der Namen und Erstellungszeitmarken für alle Systemtabellen, deren Namen mit SYSUbeginnen.

   SELECT VARCHAR(TABNAME, 20) AS TABLE_NAME,
     VARCHAR_FORMAT(CREATE_TIME, 'YYYY-MM-DD HH24:MI:SS')
       AS CREATION_TIME
     FROM SYSCAT.TABLES
     WHERE TABNAME LIKE 'SYSU%'

Dieses Beispiel gibt die folgende Ausgabe zurück:

   TABLE_NAME           CREATION_TIME
   -------------------- -------------------
   SYSUSERAUTH          2000-05-19 08:18:56
   SYSUSEROPTIONS       2000-05-19 08:18:56

Beispiel 2: Die Variable TMSTMP ist als TIMESTAMP definiert und hat den Wert 2007-03-09-14.07.38.123456. Die folgenden Beispiele zeigen Aufrufe der Funktion VARCHAR_FORMAT und die resultierenden Zeichenfolgewerte. Der Datentyp jedes Ergebnisses ist VARCHAR (255).

Function invocation                          Result
-------------------                          ------
VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHHMISSFF3')   20070309020738123
VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHH24MISS')    20070309140738
VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHHMI')        200703090207

VARCHAR_FORMAT(TMSTMP,'DD/MM/YY')            09/03/07
VARCHAR_FORMAT(TMSTMP,'MM-DD-YYYY')          03-09-2007
VARCHAR_FORMAT(TMSTMP,'J')                   2454169
VARCHAR_FORMAT(TMSTMP,'Q')                   1
VARCHAR_FORMAT(TMSTMP,'W')                   2
VARCHAR_FORMAT(TMSTMP,'IW')                  10
VARCHAR_FORMAT(TMSTMP,'WW')                  10
VARCHAR_FORMAT(TMSTMP,'Month','en_US')       March 
VARCHAR_FORMAT(TMSTMP,'MONTH','en_US')       MARCH 
VARCHAR_FORMAT(TMSTMP,'MON','en_US')         MAR 
VARCHAR_FORMAT(TMSTMP,'Day','en_US')         Friday 
VARCHAR_FORMAT(TMSTMP,'DAY','en_US')         FRIDAY 
VARCHAR_FORMAT(TMSTMP,'Dy','en_US')          Fri 
VARCHAR_FORMAT(TMSTMP,'Month','de_DE')       März 
VARCHAR_FORMAT(TMSTMP,'MONTH','de_DE')       MÄRZ 
VARCHAR_FORMAT(TMSTMP,'MON','de_DE')         MÄR 
VARCHAR_FORMAT(TMSTMP,'Day','de_DE')         Freitag 
VARCHAR_FORMAT(TMSTMP,'DAY','de_DE')         FREITAG 
VARCHAR_FORMAT(TMSTMP,'Dy','de_DE')          Fr.

Beispiel 3: Die Variable DTE ist als DATE definiert und hat den folgenden Wert: 2007-03-09. Die folgenden Beispiele zeigen mehrere Aufrufe der Funktion und die resultierenden Zeichenfolgewerte. Der Datentyp jedes Ergebnisses ist VARCHAR (255).

Function invocation                          Result
-------------------                          ------
VARCHAR_FORMAT(DTE,'YYYYMMDD')               20070309
VARCHAR_FORMAT(DTE,'YYYYMMDDHH24MISS')       20070309000000

Beispiel 4: Die Variablen POSNUM und NEGNUM sind beide als DECFLOAT (34) definiert und der Wert von POSNUM ist 1234.56 und der Wert von NEGNUM ist -1234.56. Die folgenden Beispiele zeigen mehrere Aufrufe von VARCHAR_FORMAT und den resultierenden Zeichenfolgewerten. Der Datentyp jedes Ergebnisses ist VARCHAR (255).

Function invocation                           Result
-------------------                           ------
VARCHAR_FORMAT(POSNUM)                        '1234.56'
VARCHAR_FORMAT(NEGNUM)                        '-1234.56'
VARCHAR_FORMAT(POSNUM,'9999.99')              ' 1234.56'
VARCHAR_FORMAT(NEGNUM,'9999.99')              '-1234.56'
VARCHAR_FORMAT(POSNUM,'99999.99')             '  1234.56'
VARCHAR_FORMAT(NEGNUM,'99999.99')             ' -1234.56'
VARCHAR_FORMAT(POSNUM,'00000.00')             ' 01234.56'
VARCHAR_FORMAT(NEGNUM,'00000.00')             '-01234.56'
VARCHAR_FORMAT(POSNUM,'9999.99MI')            '1234.56 '
VARCHAR_FORMAT(NEGNUM,'9999.99MI')            '1234.56-'
VARCHAR_FORMAT(POSNUM,'S9999.99')             '+1234.56'
VARCHAR_FORMAT(NEGNUM,'S9999.99')             '-1234.56'
VARCHAR_FORMAT(POSNUM,'9999.99PR')            ' 1234.56 '
VARCHAR_FORMAT(NEGNUM,'9999.99PR')            '<1234.56>'
VARCHAR_FORMAT(POSNUM,'S$9,999.99')           '+$1,234.56'
VARCHAR_FORMAT(NEGNUM,'S$9,999.99')           '-$1,234.56'