FORMAT_UNITS 函数

FORMAT_UNITS 函数可解释指定内存或大量存储的单位的数目和缩写名称的字符串。

此内建的函数可接受一个、两个或三个由引号括起的字符串参数。您可调用通过内存或大量存储的字节或更大的单位（比如，kilobyte、megabyte、gigabyte 等等）的标准缩写来表示处理大小规范的 SQL 语句中的 FORMAT_UNITS。

还可通过 SQL 管理 API ADMIN 和 TASK 函数来在 sysadmin 数据库中内部调用 FORMAT_UNITS 函数，在 GBase 8s 管理员参考中有对其的描述。

FORMAT_UNITS 函数

元素	描述	限制	语法
number	求值为存储或内存 units 的数目的表达式	必须为文字数值或指定可转换为 FLOAT 的数目的由引号括起的字符串	表达式
precision	要从 number 返回的有效数值的整数数目	必须为文字数值或指定整数的用引号括起的字符串	表达式
units	存储或内存的单位的缩写；缺省值为 'B'（表示字节）	必须以 'B'、'K'、'M'、'G'、'T'、'P' 或 'PB'（或这些字母的小写形式）开头。忽略任何收尾字符。	用引号括起的字符串

此内建的函数可接受一个、两个或三个参数。返回的值是展示指定的 number 和展示存储单位的适当的格式标签的字符串。如果您指定 precision 作为最后的参数，则以那个精度返回 number。否则，在缺省情况下，将 number 格式化为精度 3（%3.3lf）。

同样的表示法也适用于所有 SQL 管理 API ADMIN 和 TASK 命令的参数（效仿 Enterprise Replication cdr 实用程序的命令除外），这些参数指定内存、存盘存储或地址偏移量的大小：

表示法: 对应的单位
'B' 或 'b': 字节（= 以 2 为底，指数为 0）
'K' 或 'k': 千字节（= 以 2 为底，指数为 10）
'M' 或 'm': Megabyte（= 以 2 为底，指数为 20）
'G' 或 'g': Gigabyte（= 以 2 为底，指数为 30）
'T' 或 't': Terabyte（= 以 2 为底，指数为 40）
'PB': Petabyte（= 以 2 为底，指数为 50）
'P': 页（= 2 千字节或 4 千字节，依赖于系统的基础页大小）

unit 规范中的首字母（'B'、'K'、'M'、'G' 或 'T'）确定计量的单位，并忽略任何收尾的字符。然而，有一个例外，那就是在字符串中首字母 'P'（或 'p'）紧跟着 'B' 或 'b'，因为在此情况下，将该字符解释为 petabyte。将任何其他以 "P"（比如 "PA"、"pc"、"PhD"、"papyrus"，等等）起始的字符串解释为指定 pages，而不是指定 petabytes。

如果一个参数同时提供 number 和 units 规范，则 GBase 8s 忽略将 number 规范从 FORMAT_UNITS 或 SQL 管理 API ADMIN 或 TASK 函数的同一参数之内的 units 规范分隔开的任何空格。例如，将规范 '128M' 与 '128 m' 都解释为 128 megabyte。

下列示例以单个参数调用 FORMAT_UNITS 函数：

EXECUTE FUNCTION FORMAT_UNITS('1024 M');

返回下列字符串值。

(expression)
`1.00 GB`

        SELECT FORMAT_UNITS('1024 k') FROM systables WHERE tabid=1;

返回下列字符串值。

(expression)
`1.00 MB`

        SELECT FORMAT_UNITS(tabid || 'M') FROM systables WHERE tabid=100;

返回下列字符串值。

(expression)
`100 MB`

下列示例展示以两个参数调用 FORMAT_UNITS 函数：

EXECUTE FUNCTION FORMAT_UNITS(1024, 'k');

返回下列字符串值。

(expression)
`1.00 MB`

        SELECT FORMAT_UNITS( SUM(chksize), 'P') SIZE, 
        FORMAT_UNITS( SUM(nfree), 'p') FREE FROM syschunks;
        
        size  117 MB
        free  8.05 MB

此查询返回字符串值 size 117 MB 和 free 8.05 MB。

下列示例以三个参数调用 FORMAT_UNITS 函数：

EXECUTE FUNCTION FORMAT_UNITS(1024, 'k', 4);

返回下列字符串值。

(expression)
`1.000 MB`

        SELECT FORMAT_UNITS( SUM(chksize), 'P', 4), SIZE, 
        FORMAT_UNITS( SUM(nfree), 'p', 4) FREE FROM syschunks;
        
        size  117.2 MB
        free  8.049 MB

此查询返回字符串值 size 117.2 MB 和 free 8.047 MB。这些结果与前面仅以它们的非缺省的精度进行查询的示例不同，由 FORMAT_UNITS 的最后一个参数指定精度。