# Builtin - 数据库

## `execSql([flags,] [params,] database_name, sql, var result[, user_name, password][, data_keep_null])`

声明：function

执行 SQL 语句。flags、params、user_name、password 和 data_keep_null 均为可选参数；不需要时可按参数顺序省略。

| 参数             | 类型                   | 说明                               |
| ---------------- | ---------------------- | ---------------------------------- |
| `flags`          | integer                | 可选执行标志。                     |
| `params`         | array                  | 可选存储过程参数。                 |
| `database_name`  | string                 | 数据库别名。                       |
| `sql`            | string                 | 要执行的 SQL 语句。                |
| `result`         | array\|string\|integer | 写回查询结果、影响行数或错误信息。 |
| `user_name`      | string                 | 用户名。                           |
| `password`       | string                 | 密码。                             |
| `data_keep_null` | boolean                | 是否在结果集中保留空值。           |

返回：integer

### 示例

范例01：基本用法

```tsl
// demo_db 为已配置的数据库别名。
result_count := execSql("demo_db", "select 1 as value", result);
echo result_count > 0, "\n";
// 输出：1
```

## `sqlBeginTrans(database_alias)`

声明：function

开始数据库事务。返回 -1 表示连接失败，-2 表示异常，其它值表示事务层级。

| 参数             | 类型   | 说明         |
| ---------------- | ------ | ------------ |
| `database_alias` | string | 数据库别名。 |

返回：integer

### 示例

范例01：基本用法

```tsl
// demo_db 为已配置的数据库别名。
level := sqlBeginTrans("demo_db");
echo level >= -2, "\n";
// 输出：1
```

## `sqlCloseConn([database_alias])`

声明：function

关闭指定数据库别名的连接；省略 database_alias 时关闭全部数据库连接。

| 参数             | 类型   | 说明         |
| ---------------- | ------ | ------------ |
| `database_alias` | string | 数据库别名。 |

返回：integer

### 示例

范例01：基本用法

```tsl
closed := sqlCloseConn();
echo closed >= 0, "\n";
// 输出：1
```

## `sqlCommit(database_alias)`

声明：function

提交数据库事务。返回 -1 表示无事务或连接失败，-2 表示异常，0 表示提交后无事务，1 表示仍在事务中。

| 参数             | 类型   | 说明         |
| ---------------- | ------ | ------------ |
| `database_alias` | string | 数据库别名。 |

返回：integer

### 示例

范例01：基本用法

```tsl
// demo_db 为已配置且已开始事务的数据库别名。
result := sqlCommit("demo_db");
echo result >= -2 and result <= 1, "\n";
// 输出：1
```

## `sqlErrorMsg()`

声明：function

取得最近一次 SQL 执行错误信息。

返回：string

### 示例

范例01：基本用法

```tsl
echo length(sqlErrorMsg()) >= 0, "\n";
// 输出：1
```

## `sqlInTrans(database_alias)`

声明：function

检查数据库连接是否处于事务中。返回 -1 表示连接失败，-2 表示异常，0 表示无事务，1 表示有事务。

| 参数             | 类型   | 说明         |
| ---------------- | ------ | ------------ |
| `database_alias` | string | 数据库别名。 |

返回：integer

### 示例

范例01：基本用法

```tsl
// demo_db 为已配置的数据库别名。
result := sqlInTrans("demo_db");
echo result >= -2 and result <= 1, "\n";
// 输出：1
```

## `sqlRollback(database_alias)`

声明：function

回滚数据库事务。返回 -1 表示无事务或连接失败，-2 表示异常，0 表示回滚后无事务，1 表示仍在事务中。

| 参数             | 类型   | 说明         |
| ---------------- | ------ | ------------ |
| `database_alias` | string | 数据库别名。 |

返回：integer

### 示例

范例01：基本用法

```tsl
// demo_db 为已配置且已开始事务的数据库别名。
result := sqlRollback("demo_db");
echo result >= -2 and result <= 1, "\n";
// 输出：1
```

## `sysDbfRead(alias, file_name, var value[, is_col_info])`

声明：function

读取 DBF 文件内容或字段结构。is_col_info 可省略，缺省为假；为真时读取字段结构。

| 参数          | 类型          | 说明                                 |
| ------------- | ------------- | ------------------------------------ |
| `alias`       | string        | 目录别名；空字符串表示当前目录。     |
| `file_name`   | string        | 文件名称。                           |
| `value`       | array\|string | 成功时写回数据，失败时写回错误信息。 |
| `is_col_info` | boolean       | 可选；为真时读取字段结构，缺省为假。 |

返回：boolean

### 示例

范例01：基本用法

```tsl
data := `array("A": (1, 2, 3), "B": ("a", "b", "c"));
sysDbfWrite("", "example.dbf", data);
ok := sysDbfRead("", "example.dbf", restored);
echo ok and ifArray(restored), "\n";
// 输出：1
```

## `sysDbfWrite(alias, file_name, value[, col_info])`

声明：function

将带字符串列名的数组写入 DBF 文件。col_info 可省略，缺省时自动判断字段类型。

| 参数        | 类型   | 说明                             |
| ----------- | ------ | -------------------------------- |
| `alias`     | string | 目录别名；空字符串表示当前目录。 |
| `file_name` | string | 文件名称。                       |
| `value`     | array  | 带字符串列名的待写入数据。       |
| `col_info`  | array  | 可选 DBF 字段结构定义。          |

返回：boolean

### 示例

范例01：基本用法

```tsl
data := `array("A": (1, 2, 3), "B": ("a", "b", "c"));
echo sysDbfWrite("", "example.dbf", data), "\n";
// 输出：1
```