VARCHAR_FORMAT 标量函数

VARCHAR_FORMAT 函数返回输入表达式的字符表示。

字符串到 VARCHAR

DATE 或 TIMESTAMP 到 VARCHAR

带符号数字到 VARCHAR

该模式是 SYSIBM。

如果 VARCHAR_FORMAT 函数的任何参数可以为空，那么结果可以为空；如果任何参数为空，那么结果为空值。

字符串到 VARCHAR

character-expression

用于返回必须为内置 CHAR 或 VARCHAR 数据类型的值的表达式。在 Unicode 数据库中，如果提供的参数是 GRAPHIC 或 VARGRAPHIC 数据类型，那么在对该函数进行求值之前，需先将其转换为 VARCHAR。

结果是其长度属性与参数的长度属性相匹配的 VARCHAR。结果的值与 character-expression 的值相同。

结果的代码页是该节的代码页。

DATE 或 TIMESTAMP 到 VARCHAR

date-or-timestamp-expression

用于返回 DATE 或 TIMESTAMP 值的表达式，或者非 CLOB 或 DBCLOB 的日期或时间戳记的有效字符串表示。在 Unicode 数据库中，如果表达式返回日期或时间戳记的图形字符串表示，那么在对该函数进行求值之前，需先将返回的值转换为字符串。

如果输入表达式返回：

同时还必须指定 format-string 参数（一个字符串）。
DATE 或日期的字符串表示，返回的值首先转换为 TIMESTAMP (0) 值，时间部分正好为午夜 (00.00.00)。
时间戳记的字符串表示，它首先会转换为 TIMESTAMP(12) 值

有关日期时间值的字符串表示的有效格式列表，请参阅日期时间值的字符串表示。

format-string1

用于返回以下某种内置数据类型值的表达式：

CHAR 或 VARCHAR
带符号的数字
Datetime
GRAPHIC 或 VARGRAPHIC（仅限 Unicode 数据库）

如果数据类型不是 CHAR 或 VARCHAR，那么在对该函数进行求值之前，需先将其隐式转换为 VARCHAR。实际长度不得大于 255 个字节 (SQLSTATE 22007)。该值是规定如何格式化 timestamp-expression 的模板。

缺省格式字符串基于专用寄存器 CURRENT LOCALE LC_TIME 的值。

有效格式字符串必须包含表 1 中列出的格式元素的组合 (SQLSTATE 22007)。可以选择使用以下一个或多个分隔符来分隔两个格式元素：

减号 (-)
句点 (.)
斜杠 (/)
逗号 (,)
撇号 (')
分号 (;)
冒号 (:)
空白 ( )

也可以在 format-string 的开头或结尾指定分隔符。

表 1. DATE 或 TIMESTAMP 到 VARCHAR 的格式元素
格式元素	描述
AM 或 PM	不含周期的子午线指示器（早上或晚上）。此格式元素取决于 `locale-name`（如果已指定）；否则，它取决于专用寄存器 CURRENT LOCALE LC_TIME 的值。
A.M. 或 P.M.	含周期的子午线指示器（早上或晚上）。此格式元素使用精确字符串A.M. ' 或 'P.M. ' 并且独立于有效的语言环境名称。
CC	世纪 (01-99)。如果四位数年份的后两位为零，那么结果为年份的前两位；否则，结果为年份的前两位数加一。
DAY、Day 或 day	以大写、首字母大写或小写格式的日期名称。使用的语言依赖于 `locale-name`（如果已指定）；否则，它依赖于专用寄存器 CURRENT LOCALE LC_TIME 的值。
DY、Dy 或 dy	以大写、首字母大写或小写格式的缩写日期名称。使用的语言依赖于 `locale-name`（如果已指定）；否则，它依赖于专用寄存器 CURRENT LOCALE LC_TIME 的值。
D	星期几 (1-7)。一周的第一天依赖于 `locale-name`（如果已指定）；否则，它依赖于专用寄存器 CURRENT LOCALE LC_TIME 的值。
DD	月日期 (01-31)。
DDD	年日期 (001-366)。
FF 或 FFn	小数秒数 (0-99999999999999) ，其中 n 指定返回值的小数位。 n 的有效值为 1 - 12（不带前导零）。指定 FF 相当于指定 FF6。如果输入时间戳记的小数位数小于 n，那么将使用尾部零填充结果。
HH	HH 的行为与 HH12 相同。
HH12	12 小时格式的小时值 (01-12)。
HH24	24 小时格式的小时值 (00-24)。
I	ISO 年份 (0-9)。基于返回的 ISO 周的年份的最后一位数字。
标识	ISO 星期几 (1-7)。 1 是星期一， 7 是星期日。
IW	ISO 周 (01-53)。一周从星期一开始，包括 7 天。第 1 周是一年中包含星期四的第一周，相当于一年中包含 1 月 4 日的第一周。
IY	ISO 年份 (00-99)。基于返回的 ISO 周的年份的最后两位数字。
IYY	ISO 年份 (000-999)。基于返回的 ISO 周的年份的最后三位数字。
IYYY	ISO 年份 (0000-9999)。基于返回的 ISO 周的 4 位数年份。
J	儒略日（自公元前 4713 年 1 月 1 日以来的天数）。
MI	分钟 (00-59)。
MM	月份 (01-12)。
MONTH、Month 或 month	以大写、首字母大写或小写格式的月份名称。使用的语言依赖于 `locale-name`（如果已指定）；否则，它依赖于专用寄存器 CURRENT LOCALE LC_TIME 的值。
MON、Mon 或 mon	以大写、首字母大写或小写格式的缩写月份名称。使用的语言依赖于 `locale-name`（如果已指定）；否则，它依赖于专用寄存器 CURRENT LOCALE LC_TIME 的值。
MS	毫秒 (000-999)。与 FF3 相同。
NNNNNN	微秒 (000000-999999)。与 FF6 相同。
Q	季度 (1-4)，其中 1 月到 3 月返回 1。
RR	RR 的行为与 YY 相同。
RRRR	RRRR 的行为与 YYYY 相同。
SS	秒 (00-59)。
SSSSS	自上一个午夜以来的秒数 (00000-86400)。
US	微秒 (000000-999999)。与 FF6 相同。
W	一月中的第几周 (1-5)，其中第 1 周从每月的第一天开始，到第七天结束。
全球	一年中的第几周 (01-53)，其中第 1 周从 1 月 1 日开始，到 1 月 7 日结束。
Y	年份的最后一位数字 (0-9)。
YY	年份的最后两位数字 (00-99)。
YYY	年份的最后三位数字 (000-999)。
YYYY	4 位数年份 (0000-9999)。

表 1 中的格式元素不区分大小写，但存在以下例外情况:

AM 或 PM
A.M., P.M.
DAY、Day 或 day
DY、Dy 或 dy
D
MONTH、Month 或 month
MON、Mon 或 mon

在格式元素不明确的情况下，将首先考虑不区分大小写的格式元素。例如，“DDYYYY”将解释为“DD 后跟 YYYY”，而不是“D 后跟 DY 后跟 YYY”。

locale-name

用于指定以下格式元素所用的语言环境的字符常量：

AM 或 PM
DAY、Day 或 day
DY、Dy 或 dy
D
MONTH、Month 或 month
MON、Mon 或 mon

指定的语言环境名称不区分大小写，并且必须是有效的语言环境 (SQLSTATE 42815)。有关有效语言环境及其命名的信息，请参阅 SQL 和 XQuery 的语言环境名称。缺省值是 CURRENT LOCALE LC_TIME 专用寄存器的值。

结果是格式字符串所指定格式的输入时间戳记表达式的表示。格式字符串将解释为可由一个或多个分隔符分隔的一系列格式元素。格式字符串中的字符串被解释为表 1中最长的匹配格式元素。如果包含相同字符的两个格式元素没有由分隔符分隔，那么指定的内容从左侧开始解释为表中最长的匹配格式元素，并继续解释下去直至找到格式字符串其余部分的匹配项。例如，“YYYYYYDD”将解释为格式元素“YYYY”、“YY”和“DD”。

结果是可变长度字符串。长度属性为 255。如果环境或 format-string 的字符串单元是 CODEUNITS32，那么结果的字符串单元是 CODEUNITS32。否则，结果的字符串单位为 OCTETS。 format-string 将确定结果的实际长度。如果生成的字符串超过结果的长度属性，那么结果将被截断。

结果的代码页是该节的代码页。

带符号数字到 VARCHAR

numeric-expression

返回任何内置带符号数字数据类型的值的表达式。如果该值的数据类型不是 DECFLOAT，那么会将其转换为 DECFLOAT(34) 以便进行处理。

format-string2

用于返回以下某种内置数据类型值的表达式：

CHAR 或 VARCHAR
带符号的数字
Datetime
GRAPHIC 或 VARGRAPHIC（仅限 Unicode 数据库）

如果数据类型不是 CHAR 或 VARCHAR，那么在对该函数进行求值之前，需先将其隐式转换为 VARCHAR。实际长度不能大于 255 个字节 (SQLSTATE 22018)。该值将用作可格式化输入十进制浮点表达式的模板。指定为前缀的格式元素只能在模板的开头使用。指定为后缀的格式元素只能在模板的末尾使用。模板不能包含多个 MI、S 或 PR 格式元素 (SQLSTATE 22018)。

如果未指定格式字符串，则该函数等同于 VARCHAR(DECFLOAT(numeric-expression))。

表 2. 十进制浮点到 varchar 的格式元素
格式元素	描述
0	每个 0 代表一个有效数字。数字中的前导零显示为零。
9	每个 9 代表一个有效数字。数字中的前导零显示为空白。
损益	如果输入十进制浮点表达式返回一个正数，那么会在指定的位置添加一个加号 (+)。
G	将在指定的位置添加由语言环境指定的组分隔符。
D	将在指定的位置添加由语言环境指定的小数定界符。
,	将在指定的位置添加逗号（例如作为组分隔符）。
.	将在指定的位置添加句点（例如作为小数点）。
S	前缀：如果输入十进制浮点表达式返回：负数，那么会将一个前导减号 (-) 添加到结果上正数，那么会将一个前导加号 (+) 添加到结果上
$	前缀：将一个前导美元符号 ($) 添加到结果上。
MI	后缀：如果输入十进制浮点表达式返回：负数，那么会将一个尾部减号 (-) 添加到结果上正数，那么会将一个尾部空格添加到结果上
PR(D)	后缀：如果输入十进制浮点表达式返回：负数，那么会将一个前导小于字符 (<) 和一个尾部大于字符 (>) 添加到结果上正数，那么会将一个前导空格和一个尾部空格添加到结果上

格式元素不区分大小写。

locale-name

可指定用于确定组分隔符和小数定界符的语言环境的字符常量。

结果是输入十进制浮点表达式的变长字符串表示。如果指定了单个参数，那么长度属性为 42。否则，长度属性为 254。如果环境或格式字符串的字符串单位为 CODEUNITS32，那么结果的字符串单位为 CODEUNITS32；否则，结果的字符串单位为 OCTETS。结果的实际长度由格式字符串（如果已指定）确定；否则，结果的实际长度是可表示输入十进制浮点表达式值的最小字符数。如果生成的字符串超过结果的长度属性，那么结果将被截断。

如果输入十进制浮点表达式的值为特殊值：

无穷大，那么将返回字符串“INFINITY”
sNaN，那么将返回字符串“SNAN”
NaN，那么将返回字符串“NAN”

如果特殊值是负数，那么结果的第一个字符是减号 (-)。十进制浮点特殊值 sNaN 转换为字符串时不会导致异常。

如果格式字符串不包含任何格式元素 MI、S 或 PR，并且输入表达式的值为负数，那么结果中会包含一个减号 (-)；否则，结果中会包含一个空格。

如果输入表达式中小数点左侧的位数大于格式字符串中小数点左侧的位数，那么结果是包含一个或多个井号 (#) 字符的字符串。如果输入表达式中小数点右侧的位数大于格式字符串中小数点右侧的位数，那么会将结果四舍五入到格式字符串中小数点右侧的位数。将不使用 DECFLOAT 取整方式。 VARCHAR_FORMAT 的取整行为对应于 ROUND_HALF_UP 的值。

结果的代码页是该节的代码页。

注意

儒略历和公历：对于时间戳记到 varchar，此函数考虑了 1582 年 10 月 15 日从儒略历到公历的转换。
确定性： VARCHAR_FORMAT 是一个确定性函数。但是，函数的以下调用取决于专用寄存器 CURRENT LOCALE LC_TIME 的值。
- 时间戳记到 varchar，当未显式指定 format-string 时，或当未显式指定 locale-name 并且以下某个语句为 true 时：
  - format-string 不是常量
  - format-string 是一个常量，并且包含语言环境敏感的格式元素
  不能在不能使用专用寄存器的任何位置使用依赖于专用寄存器值的这些调用 (SQLSTATE 42621 ， 428EC或 429BX)。
替代语法：TO_CHAR 是 VARCHAR_FORMAT 的同义词。

示例

示例 1：显示其名称以 SYSU 开头的所有系统表的名称和创建时间戳记。

   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%'

此示例将返回以下输出：

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

示例 2：变量 TMSTMP 定义为 TIMESTAMP 且具有值 2007-03-09-14.07.38.123456。以下示例显示了 VARCHAR_FORMAT 函数的调用和生成的字符串值。每个结果的数据类型为 VARCHAR (255)。

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


VARCHAR_FORMAT(TMSTMP,'HH12:MI:SS.MS AM')    02:07:38.123 PM
VARCHAR_FORMAT(TMSTMP,'HH24:MI:SS.US')       14:07:38.123456

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ÄRZ 
VARCHAR_FORMAT(TMSTMP,'Day','de_DE')         Freitag 
VARCHAR_FORMAT(TMSTMP,'DAY','de_DE')         FREITAG 
VARCHAR_FORMAT(TMSTMP,'Dy','de_DE')          Fr.

示例 3：变量 DTE 定义为 DATE 且具有以下值：2007-03-09。以下示例显示了函数的多次调用和生成的字符串值。每个结果的数据类型为 VARCHAR (255)。

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

示例 4：变量 POSNUM 和 NEGNUM 都定义为 DECFLOAT(34)，POSNUM 的值为 1234.56，NEGNUM 的值为 -1234.56。以下示例显示了 VARCHAR_FORMAT 的多次调用以及生成的字符串值。前两个结果的数据类型为VARCHAR(42)，其余结果的数据类型为VARCHAR(254)。

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'


VARCHAR_FORMAT(POSNUM,'99,99,99')             '    12,35'
VARCHAR_FORMAT(NEGNUM,'99,99,99')             '   -12,35'
VARCHAR_FORMAT(POSNUM,'PL9999.99')            '+1234.56'
VARCHAR_FORMAT(NEGNUM,'PL9999.99')            ' 1234.56'
VARCHAR_FORMAT(POSNUM,'9999PL')               ' 1234+'
VARCHAR_FORMAT(NEGNUM,'9999PL')               '-1234 '
VARCHAR_FORMAT(POSNUM,'9999.9')               ' 1234.6'
VARCHAR_FORMAT(NEGNUM,'9999.9')               '-1234.6'
VARCHAR_FORMAT(POSNUM,'9999')                 ' 1235'
VARCHAR_FORMAT(NEGNUM,'9999')                 '-1235'
VARCHAR_FORMAT(POSNUM,'99.99')                '######'
VARCHAR_FORMAT(NEGNUM,'99.99')                '######'
VARCHAR_FORMAT(POSNUM,'9999D99', 'en_US')     ' 1234.56'
VARCHAR_FORMAT(POSNUM,'9999D99', 'fr_FR')     ' 1234,56'
VARCHAR_FORMAT(POSNUM,'9G999D99', 'en_US')    ' 1,234.56'
VARCHAR_FORMAT(POSNUM,'9G999D99', 'de_DE')    ' 1.234,56'