# 天软平台服务函数

文档类型：函数事实页
是否可直接用于生成代码：是；本页函数条目均包含参数表
遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md)

这一页描述天软平台服务、用户数据维护、自定义板块、平台执行信息和授权用户共享函数入口。生成函数调用时，只按函数条目中的参数表传参。

## 模块范围

- 说明：天软平台服务函数；包含用户数据、板块维护、平台执行信息和授权用户共享函数入口
- 函数事实数：17

## 自有数据维护函数

运行边界：这些函数依赖平台用户数据维护能力；目标环境没有用户数据服务时，不要生成这些调用。

### `saveTable(table_name, data, stream_mode)`

用途：把用户数据保存为平台用户数据表。

参数个数：2 或 3
返回值：整数；源文档示例中成功返回 `-1`

| 参数位置 | 参数名        | 必填 | 接收类型           | 说明                                                             |
| -------- | ------------- | ---- | ------------------ | ---------------------------------------------------------------- |
| 1        | `table_name`  | 是   | 字符串             | 用户数据名称；可用 `目录\\表名` 保存到指定目录                   |
| 2        | `data`        | 是   | 任意值，通常为数组 | 要保存的用户数据                                                 |
| 3        | `stream_mode` | 否   | 整数               | 流格式；`0` 表示原始流格式，`1` 表示新流格式；省略时使用默认格式 |

### `loadTable(table_name)`

用途：读取已保存的平台用户数据表。

参数个数：1
返回值：已保存的数据值

| 参数位置 | 参数名       | 必填 | 接收类型 | 说明                                            |
| -------- | ------------ | ---- | -------- | ----------------------------------------------- |
| 1        | `table_name` | 是   | 字符串   | 用户数据名称；读取目录下数据时使用 `目录\\表名` |

### `loadTableEx(table_name)`

用途：读取已保存的平台用户数据表。

参数个数：1
返回值：已保存的数据值

| 参数位置 | 参数名       | 必填 | 接收类型 | 说明                                            |
| -------- | ------------ | ---- | -------- | ----------------------------------------------- |
| 1        | `table_name` | 是   | 字符串   | 用户数据名称；读取目录下数据时使用 `目录\\表名` |

生成规则：默认使用 `loadTable`；只有用户明确要求 `loadTableEx`，或项目已有代码使用 `loadTableEx` 时，才生成 `loadTableEx`。

### `testTable(table_name)`

用途：检查指定平台用户数据表是否存在。

参数个数：1
返回值：整数；存在返回 `1`，不存在返回 `0`

| 参数位置 | 参数名       | 必填 | 接收类型 | 说明                                                    |
| -------- | ------------ | ---- | -------- | ------------------------------------------------------- |
| 1        | `table_name` | 是   | 字符串   | 要检查的用户数据名称；检查目录下数据时使用 `目录\\表名` |

### `listTable()`

用途：取得当前用户可见的平台用户数据表列表。

参数个数：0
返回值：数组

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | ------ | ---- | -------- | ---- |

### `deleteTable(table_name)`

用途：删除已保存的平台用户数据表。

参数个数：1
返回值：整数；源文档示例中成功返回 `-1`

| 参数位置 | 参数名       | 必填 | 接收类型 | 说明                                                    |
| -------- | ------------ | ---- | -------- | ------------------------------------------------------- |
| 1        | `table_name` | 是   | 字符串   | 要删除的用户数据名称；删除目录下数据时使用 `目录\\表名` |

## 自定义板块维护函数

运行边界：这些函数会写入或删除当前用户的自定义板块。只有用户明确要求维护板块时才生成调用。

### `saveBk(sector_name, category_path, stocks)`

用途：保存自定义板块。

参数个数：3
返回值：整数；成功返回 `-1`

| 参数位置 | 参数名          | 必填 | 接收类型 | 说明                                                       |
| -------- | --------------- | ---- | -------- | ---------------------------------------------------------- |
| 1        | `sector_name`   | 是   | 字符串   | 板块名称                                                   |
| 2        | `category_path` | 是   | 字符串   | 板块分类路径；多级分类用 `\\` 分隔                         |
| 3        | `stocks`        | 是   | 数组     | 板块成分证券代码数组，例如 `array("SZ000001", "SZ000002")` |

### `deleteBk(sector_name)`

用途：删除自定义板块。

参数个数：1
返回值：整数；成功返回 `-1`

| 参数位置 | 参数名        | 必填 | 接收类型 | 说明             |
| -------- | ------------- | ---- | -------- | ---------------- |
| 1        | `sector_name` | 是   | 字符串   | 要删除的板块名称 |

## 用户数据辅助函数

### `hexToString(value)`

用途：把用户数据文件名中的十六进制名称转换为可读字符串。

参数个数：1
返回值：字符串

| 参数位置 | 参数名  | 必填 | 接收类型 | 说明                                                                    |
| -------- | ------- | ---- | -------- | ----------------------------------------------------------------------- |
| 1        | `value` | 是   | 字符串   | 用户数据文件名或十六进制名称字符串，例如 `hex_74657374646174613031.stm` |

## 平台执行信息

### `tsAppServer()`

用途：取得当前平台执行服务器信息。

参数个数：0
返回值：字符串

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | ------ | ---- | -------- | ---- |

### `tsAppServerName()`

用途：取得当前平台执行程序信息。

参数个数：0
返回值：字符串

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | ------ | ---- | -------- | ---- |

### `ts_ModuleInfo()`

用途：平台执行信息相关函数。

参数个数：0
返回值：处理后的结果值

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | ------ | ---- | -------- | ---- |

## 用户和函数相关函数

### `userName()`

用途：获取当前用户名。

参数个数：0
返回值：字符串

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | ------ | ---- | -------- | ---- |

### `user(name)`

用途：取得指定授权用户的共享函数调用入口，并通过链式成员调用执行该用户共享的函数。

参数个数：1
返回值：用户共享函数调用代理；链式调用后的返回值由目标共享函数决定

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明               |
| -------- | ------ | ---- | -------- | ------------------ |
| 1        | `name` | 是   | 字符串   | 已授权用户的用户名 |

生成规则：

- 只在用户明确要求调用其它用户共享函数，且已经说明授权关系和目标函数名时生成。
- 生成形态是 `user("user1").sample(...)`，不要只生成裸 `user("user1")` 当成最终业务结果。
- 目标用户必须已经授权当前用户调用对应共享函数；目标函数名和参数按该共享函数事实或项目代码确定。
- 示例形态：`user("jrtzsupport").Show_DSXG_211(begt, endt, 0)`。

### `functionType()`

用途：取得当前运行函数的类型。

参数个数：0
返回值：整数；`1` 表示用户函数，`2` 表示公用函数

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | ------ | ---- | -------- | ---- |

生成规则：

- 只在需要判断当前函数来源类型时生成。
- 该函数读取当前运行函数上下文；不要把顶层空返回泛化成函数不存在。
- 相关函数：`functionName()`、`functionVer()`。

### `functionName()`

用途：取得当前运行函数的名称。

参数个数：0
返回值：字符串；当前运行函数的名称

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | ------ | ---- | -------- | ---- |

生成规则：

- 只在需要读取当前运行函数名称时生成。
- 该函数读取当前运行函数上下文；不要把顶层空返回泛化成函数不存在。
- 相关函数：`functionType()`、`functionVer()`。

### `functionVer(function_type, name)`

用途：返回指定函数的版本号；函数版本号是函数保存在 SERVER 的版本标识，可用于判断函数是否被修改过。

参数个数：2
返回值：整数；函数版本号

| 参数位置 | 参数名          | 必填 | 接收类型 | 说明     |
| -------- | --------------- | ---- | -------- | -------- |
| 1        | `function_type` | 是   | 整数     | 函数类型 |
| 2        | `name`          | 是   | 字符串   | 函数名称 |

生成规则：

- 只在需要比较或记录函数版本号时生成。
- 可与 `saveTable(...)`、`loadTable(...)` 配合保存和读取版本标识。
- 相关函数：`functionType()`、`functionName()`。