INPUT 语句 [Interactive SQL]

此语句用于将数据从外部文件或键盘导入到数据库表，或从通用 ODBC 数据源导入数据。

语法 1 - 从外部文件或键盘导入

INPUT INTO [ owner.]table-name input-options

input-options :
[ ( column-name, ... ) ]
[ BY { ORDER | NAME ]
[ BYTE ORDER MARK { ON | OFF } ]
[ COLUMN WIDTHS ( integer, ...) ]
[ DELIMITED BY string ]
[ ENCODING encoding ]
[ ESCAPE CHARACTER character ]
[ ESCAPES { ON | OFF }
[ FORMAT input-format ]
[ FROM filename | PROMPT ]
[ NOSTRIP ]

input-format :
TEXT 
| FIXED

encoding : identifier or string

语法 2 - 从 ODBC 数据源导入

INPUT  
USING connection-string
FROM source-table-name 
INTO destination-table-name
[ CREATE TABLE { ON | OFF } ]

connection-string :  
{ DRIVER=odbc_driver_name 
| DSN=odbc_data_source } [ ; { connection_parameter = value } ]

参数

BY 子句 BY 子句允许用户指定输入文件中的列是基于它们在列表中的顺序位置（ORDER，缺省值）还是按它们的名称 (NAME) 与表列进行匹配。并非所有输入格式在文件中都有列名信息。只有那些具有列名信息的格式才可以按 NAME 匹配。
BYTE ORDER MARK 子句 此子句用于指定是否处理数据中的字节顺序标记 (BOM)。
仅当从 TEXT 格式的文件中读取时，BYTE ORDER MARK 子句才有意义。如果试图将 BYTE ORDER MARK 子句与 FORMAT（而不是 TEXT）子句一起使用，会返回错误。

仅当读取或写入以 UTF-8 或 UTF-16（及它们的变体）编码的文件时才使用 BYTE ORDER MARK 子句。如果试图将 BYTE ORDER MARK 子句与任何其它编码一起使用，会返回错误。

如果指定了 ENCODING 子句：
- 如果 BYTE ORDER MARK 选项为 ON，并且指定了具有某一种字节序（如 UTF-16BE 或 UTF-16LE）的 UTF-16 编码，则 Interactive SQL 会在数据的开始位置搜索 BOM。如果 BOM 存在，会将它用于验证数据的字节排序方式。如果指定了错误的字节序，则返回错误。
- 如果 BYTE ORDER MARK 选项为 ON，但指定的是没有显式字节序的 UTF-16 编码，则 Interactive SQL 将在数据的开始位置搜索 BOM。如果 BOM 存在，会将它用于确定数据的字节排序方式。否则，会将其假定为操作系统的字节排序方式。
- 如果 BYTE ORDER MARK 选项为 ON，并指定了 UTF-8 编码，则 Interactive SQL 会在数据的开始位置搜索 BOM。如果 BOM 存在，则会被忽略。
如果未指定 ENCODING 子句：
- 如果未指定 ENCODING 子句而 BYTE ORDER MARK 选项为 ON，则 Interactive SQL 会在输入数据的开始位置搜索 BOM。如果找到 BOM，则会根据 BOM 的编码（UTF-16BE、UTF-16LE 或 UTF-8）自动选择源编码，同时不将 BOM 视作要装载的数据的一部分。
- 如果未指定 ENCODING 子句且 BYTE ORDER MARK 选项为 OFF，或在输入数据的开始位置未找到 BOM，则使用数据库 CHAR 编码。
COLUMN WIDTHS 子句 只能为 FIXED 格式指定 COLUMN WIDTHS。它在输入文件中指定列的宽度。如果没有指定 COLUMN WIDTHS，则宽度由数据库的列类型决定。
CREATE TABLE 子句 CREATE TABLE 子句用于指定在目标表不存在时是否创建表。缺省值为 ON。
DELIMITED BY 子句 DELIMITED BY 子句允许指定用作 TEXT 输入格式中的分隔符的字符串。缺省分隔符是逗号。
ENCODING 子句 encoding 参数允许您指定用于读取文件的编码。ENCODING 子句只能与 TEXT 格式配合使用。
有关如何获得 SQL Anywhere 支持的编码列表的详细信息，请参见支持的字符集。

对于 Interactive SQL，如果未指定 encoding 子句，则按以下顺序确定用于读取文件的编码：
- 用 default_isql_encoding 选项指定的编码（如果设置此选项）
- 运行 Interactive SQL 的计算机上操作系统字符集的缺省编码
如果使用 OUTPUT 语句创建输入文件并指定了编码，那么在 INPUT 语句中应指定相同的 ENCODING 子句。

有关 Interactive SQL 和编码的详细信息，请参见default_isql_encoding 选项 [Interactive SQL]。

指定 BYTE ORDER 子句，使数据中包含字节顺序标记。
ESCAPE CHARACTER 子句 十六进制代码和符号的缺省转义字符是反斜线 (\)。例如，\x0A 是换行符。
换行符可以指定为 \n。其它字符可以使用十六进制 ASCII 代码（如使用 \x09 表示制表符）指定。两个连续的反斜线字符 ( \\ ) 被解释为单个反斜线。后跟除 n、x、X 或 \ 外的任何字符的反斜线解释为两个单独的字符。例如，\q 被解释为反斜线和字母 q。

使用 ESCAPE CHARACTER 子句可更改转义字符。例如，要将感叹号用作转义字符，可按如下方式指定：
... ESCAPE CHARACTER '!'
ESCAPES 子句 ESCAPES 设置为 ON（缺省值）时，数据库服务器会将转义字符后面的字符解释为特殊字符。当 ESCAPES 设置为 OFF 时，会完全按照字符在源代码中的出现方式读取字符。
FORMAT 子句 FORMAT 子句允许指定输出的文件格式。
如果未指定 FORMAT 子句，那么各组值都必须采用 Interactive SQL 的 SET OPTION input_format 语句所设置的格式。

从命令文件输入的内容由包含 END 的行终止。从文件输入的内容在文件末尾终止。

允许的输入格式为：
- TEXT 将输入行假定为字符，每个输入行占一行，列值以逗号分隔。字母字符串可以用撇号（单引号）或引号（双引号）括起来。包含分隔符的字符串必须用单引号或双引号括起来。如果字符串本身包含单引号或双引号，则字符串内使用的引号字符需要两个。可以使用 DELIMITED BY 子句指定缺省值（逗号）之外的其它分隔符字符串。
  另外，还识别其它三个特殊序列。两个字符 \n 代表换行符，\\ 代表单个 \；而序列 \xDD 代表具有十六进制代码 DD 的字符。
  
  如果文件中有一些条目指示某个值可能为空，则它会被视为 NULL。如果该位置的值不能为 NULL，则在数字列中插入零，并在字符列中插入空字符串。
- FIXED 输入行采用固定格式。使用 COLUMN WIDTHS 子句可指定列的宽度。如果未指定列宽，则文件中的列宽必须与相应数据库列类型的任何值所要求的最大字符数相同。
  FIXED 格式不能与包含嵌入式换行符和文件结尾字符序列的二进制列一起使用。
如果要使用其它格式，如 DBASEII、DBASE III、FoxPro、Lotus 123 或 Excel 97，则需要使用 INPUT USING 语句。

FROM filename 子句 filename 可以带引号也可以不带引号。如果字符串带引号，则其遵循的格式要求与其它 SQL 字符串一样。

要指示目录路径，反斜线字符 (\) 必须用两个反斜线来表示。将数据从文件 c:\temp\input.dat 装载到 Employees 表的语句为：

INPUT INTO Employees
FROM 'c:\\temp\\input.dat';

相关 filename 的位置按以下方式确定：

如果直接在 Interactive SQL 中执行 INPUT 语句，则相对于正在运行 Interactive SQL 的目录解析 filename 的路径。例如，假设您从 c:\work 目录打开 Interactive SQL，并执行以下语句：

INPUT INTO Employees
 FROM 'inputs\\inputfile.dat';

Interactive SQL 将查找 c:\work\inputs\inputfile.dat。

如果 INPUT 语句在 .sql 文件中，则 Interactive SQL 会首先尝试相对于外部文件所在位置来解析 filename 的路径。如果未成功，则 Interactive SQL 会在相对于正运行 Interactive SQL 的目录的路径中查找 filename。

例如，假设存在文件 c:\homework\inputs.sql，它包含以下语句：

INPUT INTO Employees
 FROM 'inputs\\inputfile.dat';

Interactive SQL 会首先在 c:\homework\inputs 中查找 inputfile.dat。如果 Interactive SQL 在该位置没有找到 inputfile.dat，则它会在运行 Interactive SQL 的目录中继续查找。

FROM source-table-name 子句 source-table-name 参数是一个带引号的字符串，它包含源数据库中的表名。表名的形式可以为 database-name.owner.table-name、owner.table-name 或仅为 table-name。在表名中使用句点分隔各个部分，即使它不是源数据库中的本地分隔符。如果源数据库需要数据库名，但不需要所有者名，则 source-table-name 的格式必须为 database..table（在本例中所有者名为空）。不要给参数中的任何名称加引号（例如，不要使用 'dba."my-table"'，而是使用 'dba.my-table'。）
INTO 子句 要输入数据的表的名称。
PROMPT 子句 用户可使用 PROMPT 子句为一行中的各列逐一输入值。在窗口模式下运行时，会显示一个窗口，允许用户为新行输入值。如果在命令行上运行 Interactive SQL，Interactive SQL 会在命令行提示您为每一列键入值。
NOSTRIP 子句 通常，对于 TEXT 输入格式，在插入值之前，将去除无引号字符串中的尾随空白。NOSTRIP 可用于取消去除尾随空白。不管是否使用此选项，带引号字符串中的尾随空白都不会去除。无论 NOSTRIP 选项的设置如何，无引号字符串中的前导空白都会去除。
USING 子句 USING 子句从 ODBC 数据源输入数据。可以使用 DSN 选项指定 ODBC 数据源名，或用 DRIVER 选项指定 ODBC 驱动程序名和连接参数。Connection-parameter 是数据库特定的连接参数的可选列表。
odbc-data-source 是用户名称或 ODBC 数据源名称。例如，SQL Anywhere demo 数据库的 odbc-data-source 为 SQL Anywhere 11 Demo。

Odbc-driver-name 是 ODBC 驱动程序名。对于 SQL Anywhere 11 数据库，odbc-driver-name 是 SQL Anywhere 11；而对于 UltraLite 数据库，odbc-driver-name 为 UltraLite 11。

注释

INPUT 语句允许向指定的数据库表中进行高效的大量插入。通过输入窗口从用户处读取（如果指定了 PROMPT）或从文件中读取（如果指定了 FROM filename）输入行。如果两者均未指定，则从包含 INPUT 语句的命令文件中读取输入—在 Interactive SQL 中，甚至可以直接从 [SQL 语句] 窗格中读取。

当直接从 [SQL 语句] 窗格读取输入时，必须在要插入到 INPUT 语句结尾处的记录值前指定分号。例如：

INPUT INTO Owner.TableName;
value1, value2, value3
value1, value2, value3
value1, value2, value3
value1, value2, value3
END;

END 语句为不指定文件也不包括 PROMPT 关键字的 INPUT 语句终止数据。

如果指定了列的列表，则数据将插入到指定表的指定列中。缺省情况下，INPUT 语句假定输入文件中的列值显示顺序与它们在数据库表定义中显示的顺序相同。如果输入文件的列顺序不同，则必须在 INPUT 语句末尾列出输入文件的实际列顺序。

例如，如果使用以下语句创建一个表：

CREATE TABLE inventory (
Quantity INTEGER,
item VARCHAR(60)
);

并想从依次包含名称值和数量值的输入文件 stock.txt 中导入 TEXT 数据，

'Shirts', 100
'Shorts', 60

则必须在 INPUT 语句末尾列出输入文件的实际列顺序，才能正确地插入数据：

INPUT INTO inventory
FROM stock.txt
FORMAT TEXT
(item, Quantity);

缺省情况下，当 INPUT 语句试图插入导致错误的行时会停止。通过设置 on_error 和 conversion_error 选项，可以通过不同的方式来处理错误（请参见 SET OPTION）。如果在 INPUT 上截断任何字符串值，则 Interactive SQL 会在 [消息] 选项卡上输出警告。NOT NULL 列中缺少的值被设置为零（对于数值类型）和空字符串（对于非数值类型）。如果 INPUT 试图插入 NULL 行，则输入文件包含空行。

由于 INPUT 语句是 Interactive SQL 命令，它不能用在任何复合语句（例如 IF）或存储过程中。

请参见过程、触发器、事件和批处理中允许使用的语句。

权限

必须有表或视图的 INSERT 权限。

副作用

无。

另请参见

标准和兼容性

SQL/2003 服务商扩充。

示例

以下是一个 TEXT 文件中的 INPUT 语句的示例。

INPUT INTO Employees
FROM new_emp.inp
FORMAT TEXT;

以下虚构示例将表 ulTest 复制到名为 saTest 的表中。ulTest 是位于文件 C:\test\myULDatabase.udb 中的 UltraLite 数据库中的表，saTest 是在 demo.db 中创建的表：

INPUT USING 'driver=Ultralite 11;dbf=C:\\test\\myULDatabase.udb'
            FROM "ulTest" INTO "saTest";