# 服务器交互函数

## `checkConnected()`

声明：function

检查是否和服务器已连接。已连接返回 `true`，否则返回 `false`

<!-- tags: 服务器交互函数 判断 检查 -->

返回：boolean

### 示例

范例01：确认断开连接后的状态

先主动断开连接，使结果不依赖脚本启动前的连接状态。

```tsl
disconnectServer();
return checkConnected();
// 输出：false
```

## `checkLogined()`

声明：function

检查是否已经登录上服务器。已登录返回 `true`，否则返回 `false`

<!-- tags: 服务器交互函数 判断 检查 -->

返回：boolean

### 示例

范例01：确认断开连接后的登录状态

先主动断开连接，使结果不依赖脚本启动前的登录状态。

```tsl
disconnectServer();
return checkLogined();
// 输出：false
```

## `connectServer(address, port[, proxy_info])`

声明：function

连接服务器。成功返回 `0`，否则返回错误代码

<!-- tags: 服务器交互函数 连接 登录 -->

| 参数         | 类型    | 说明                                                             |
| ------------ | ------- | ---------------------------------------------------------------- |
| `address`    | string  | 服务器地址。                                                     |
| `port`       | integer | 服务器端口。                                                     |
| `proxy_info` | array   | 可选。省略时不使用代理服务器；代理服务器信息使用字符串下标数组。 |

`proxy_info` 支持以下字符串下标：

| 下标       | 类型    | 说明                                   |
| ---------- | ------- | -------------------------------------- |
| `Address`  | string  | 代理服务器地址。                       |
| `Port`     | integer | 代理服务器端口。                       |
| `User`     | string  | 代理服务器用户名。                     |
| `Password` | string  | 代理服务器密码。                       |
| `AuthMode` | integer | 代理模式：`0` 为 HTTP，`5` 为 SOCKS5。 |

返回：integer

### 示例

范例01：直接连接服务器

以下示例要求目标服务器可连接；连接成功时返回 `0`。

```tsl
connect_result := connectServer("tsl.tinysoft.com.cn", 443);
if connect_result = 0 then
    disconnectServer();
return connect_result;
// 输出：0
```

范例02：通过 HTTP 代理连接

将代理地址和端口替换为可用配置；连接成功时返回 `0`。

```tsl
connect_result := connectServer("tsl.tinysoft.com.cn", 443,
    array("Address": "192.168.0.250", "Port": 808, "AuthMode": 0));
if connect_result = 0 then
    disconnectServer();
return connect_result;
// 输出：0
```

## `defaultConnectAndLogin(alias[, err_msg])`

声明：function

连接并登录服务器。成功返回 `0`，否则返回错误代码

<!-- tags: 服务器交互函数 连接 登录 -->

| 参数      | 类型   | 说明                                                             |
| --------- | ------ | ---------------------------------------------------------------- |
| `alias`   | string | 服务器别名，其相应的配置在INI中。配置可参考：INI文件配置登陆信息 |
| `err_msg` | string | 可选。登录失败时接收错误信息。                                   |

返回：integer

### 示例

范例01：使用 INI 别名连接并登录

以下示例要求在 `tslclient.ini` 中配置可用的 `test` 别名。

```tsl
login_result := defaultConnectAndLogin("test", err_msg);
if login_result = 0 then
    disconnectServer();
return login_result;
// 输出：0
```

## `disconnectServer()`

声明：function

断开服务器。成功断开返回 `0`

<!-- tags: 服务器交互函数 -->

返回：integer

### 示例

范例01：断开当前连接

```tsl
return disconnectServer();
// 输出：0
```

## `endExecute(exec_handle)`

声明：function

终止异步执行或者订阅。有效异步句柄成功终止返回 `0`；无效句柄返回 `0`

<!-- tags: 服务器交互函数 -->

| 参数          | 类型    | 说明                          |
| ------------- | ------- | ----------------------------- |
| `exec_handle` | integer | 由SendExecute返回的执行句柄。 |

返回：integer

### 示例

范例01：终止异步执行

以下示例要求脚本已登录服务器，以便取得有效的异步执行句柄。

```tsl
remote_exec := "program ServerExample; begin end.";
callback_code := "echo 'server_example_done';";
exec_handle := sendExecute(remote_exec, getSysParams(), callback_code, true);
stop_result := -1;
if exec_handle <> 0 then
    stop_result := endExecute(exec_handle);
return stop_result;
// 输出：0
```

## `getComputebitsOption()`

声明：function

获取使用的计算的位选项。`0` 表示自动选择，`1` 表示 32 位服务器，`2` 表示 64 位服务器

<!-- tags: 服务器交互函数 获取 查询 -->

返回：byte

### 示例

范例01：读取计算位选项

```tsl
old_option := getComputebitsOption();
setComputebitsOption(1);
current_option := getComputebitsOption();
setComputebitsOption(old_option);
return current_option;
// 输出：1
```

## `getComputeService()`

声明：function

获取计算的服务群选择。空字符串表示默认服务，`'auto'` 表示自动选择，否则为指定的服务群名

<!-- tags: 服务器交互函数 获取 查询 -->

返回：string

### 示例

范例01：读取计算服务群

```tsl
old_service := getComputeService();
setComputeService("auto");
current_service := getComputeService();
setComputeService(old_service);
return current_service;
// 输出："auto"
```

## `loginedUser()`

声明：function

获取登录的用户名。未登录时返回空字符串

<!-- tags: 服务器交互函数 获取 查询 -->

返回：string

### 示例

范例01：读取断开连接后的登录用户名

先主动断开连接，使返回值固定为空字符串。

```tsl
disconnectServer();
return loginedUser();
// 输出：""
```

## `loginServer(user_name, password[, var err_msg])`

声明：function

登录服务器。成功返回 `0`，否则返回错误代码

<!-- tags: 服务器交互函数 连接 登录 -->

| 参数        | 类型   | 说明                           |
| ----------- | ------ | ------------------------------ |
| `user_name` | string | 字符串类型，登录用户名。       |
| `password`  | string | 字符串类型，登录密码。         |
| `err_msg`   | string | 可选。登录失败时接收错误信息。 |

返回：integer

### 示例

范例01：使用脚本参数登录

以下示例要求将有效的用户名和密码作为前两个脚本参数传入。

```tsl
login_result := -2;
if sysParamcount() >= 2 then
begin
    connect_result := connectServer("tsl.tinysoft.com.cn", 443);
    if connect_result = 0 then
    begin
        login_result := loginServer(sysParamStr(1), sysParamStr(2), err_msg);
        disconnectServer();
    end
    else
        login_result := connect_result;
end
return login_result;
// 输出：0
```

## `remoteAddress()`

声明：function

第三方交互中得到远程登录的地址。未连接时返回空字符串

<!-- tags: 服务器交互函数 -->

返回：string

### 示例

范例01：在 TSL 中读取断开连接后的服务器地址

先主动断开连接，使返回值固定为空字符串。

```tsl
disconnectServer();
return remoteAddress();
// 输出：""
```

范例02：Python 交互

```python
import sys

sys.path.append('D:\\tinysoft\\Analyse.NET\\')
import TSLPy3 as ts

login_result = ts.DefaultConnectAndLogin("test")
print(ts.Logined())
print("远程登录地址", ts.RemoteAddress())
print("服务器设置:", ts.GetService())
ts.SetComputeBitsOption(64)  # 设置计算单位
print("计算位数设置:", ts.GetComputeBitsOption())
ts.Disconnect()  # 断开连接
```

打印内容取决于 `test` 别名配置和服务器状态。

## `remotePort()`

声明：function

获取远程端口

<!-- tags: 服务器交互函数 获取 查询 -->

返回：integer

### 示例

范例01：读取断开连接后的服务器端口

先主动断开连接，使返回值固定为 `0`。

```tsl
disconnectServer();
return remotePort();
// 输出：0
```

## `sendExecute(remote_exec, sys_param, call_back[, online = true])`

声明：function

递交请求给服务器异步执行；成功返回和服务器通讯的句柄，`0` 表示错误

<!-- tags: 服务器交互函数 发送 提交 -->

| 参数          | 类型    | 说明                                                                                                        |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `remote_exec` | string  | 递交远程的执行串，Program 开始 end结束。                                                                    |
| `sys_param`   | array   | 缺省的服务器系统环境参数。                                                                                  |
| `call_back`   | string  | 当执行结束或者出错等等回调的TSL语言代码。                                                                   |
| `online`      | boolean | 可选。默认 `true`，在线执行；为 `false` 时委托执行，结果存入 `sys_param` 中 `resultname` 指定的用户数据表。 |

返回：integer

实时行情订阅调用形式为 `sendExecute("", order_param, call_back, false)`。

| 参数          | 类型   | 说明                                                                  |
| ------------- | ------ | --------------------------------------------------------------------- |
| `order_param` | array  | 订阅请求参数，使用下表所列的字符串下标。                              |
| `call_back`   | string | 实时数据到达、订阅结束或出错时执行的 TSL 回调代码；信息位于系统参数。 |

`order_param` 的下标：

| 下标   | 类型    | 说明                                       |
| ------ | ------- | ------------------------------------------ |
| `Type` | integer | 必需。订阅类型，`1` 表示行情订阅。         |
| `IDs`  | array   | 必需。订阅 ID 数组；行情订阅时为股票列表。 |
| `SUBs` | array   | 行情订阅必需。指定订阅字段。               |

普通行情支持的 `SUBs` 字段：`StockID`、`StockName`、`date`、`price`、`open`、`close`、`high`、`low`、`vol`、`amount`、`cjbs`、`yclose`、`syl1`、`syl2`、`lb`、`buy1` 至 `buy5`、`sale1` 至 `sale5`、`bc1` 至 `bc5`、`sc1` 至 `sc5`。

Level2 行情还支持：`buy6` 至 `buy10`、`sale6` 至 `sale10`、`bc6` 至 `bc10`、`sc6` 至 `sc10`。

### 示例

范例01：异步提交远程脚本

以下示例要求脚本已登录服务器；成功取得句柄时返回 `true`。

```tsl
remote_exec := "program ServerExample; begin end.";
callback_code := "echo 'server_example_done';";
exec_handle := sendExecute(remote_exec, getSysParams(), callback_code, true);
submitted := exec_handle > 0;
if submitted then
    endExecute(exec_handle);
return submitted;
// 输出：true
```

范例02：订阅实时行情后立即结束

以下示例要求脚本已登录服务器并具备行情权限；成功取得句柄时返回 `true`。

```tsl
order_param := array(
    "Type": 1,
    "IDs": array("SH000001"),
    "SUBs": array("StockID", "price"));
callback_code := "echo 'server_quote_update';";
exec_handle := sendExecute("", order_param, callback_code, false);
subscribed := exec_handle > 0;
if subscribed then
    endExecute(exec_handle);
return subscribed;
// 输出：true
```

## `sendExecuteAndWait(remote_exec, sys_param, var exec_result, var env_or_err[, online = true])`

声明：function

递交请求给服务器执行。成功返回 `0`，否则返回错误代码

<!-- tags: 服务器交互函数 发送 提交 -->

| 参数          | 类型    | 说明                                                                                                        |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `remote_exec` | string  | 递交远程的执行串，以 `Program` 开始、`end.` 结束。                                                          |
| `sys_param`   | array   | 服务器系统环境参数。                                                                                        |
| `exec_result` | any     | 接收远程执行结果。                                                                                          |
| `env_or_err`  | any     | 执行成功时接收辅助结果；执行失败时接收错误信息。辅助结果由模型通过 `env_return` 系统参数设置。              |
| `online`      | boolean | 可选。默认 `true`，在线执行；为 `false` 时委托执行，结果存入 `sys_param` 中 `resultname` 指定的用户数据表。 |

返回：integer

### 示例

范例01：同步执行远程脚本

以下示例要求脚本已登录服务器。

```tsl
remote_exec := "program ServerExample; begin return 7; end.";
status := sendExecuteAndWait(
    remote_exec, getSysParams(), exec_result, env_or_err, true);
if status = 0 then
    example_result := exec_result;
else
    example_result := env_or_err;
echo example_result;
// 输出：7
```

## `setComputebitsOption(v)`

声明：function

设置使用的计算的位选项。返回修改前的设置选项

<!-- tags: 服务器交互函数 设置 修改 -->

| 参数 | 类型 | 说明                                                         |
| ---- | ---- | ------------------------------------------------------------ |
| `v`  | byte | 整数。0表示自动选择，1表示32位服务器计算 2表示64位服务器计算 |

返回：byte

### 示例

范例01：设置计算位数并恢复原值

```tsl
old_option := getComputebitsOption();
setComputebitsOption(1);
current_option := getComputebitsOption();
setComputebitsOption(old_option);
return current_option;
// 输出：1
```

## `setComputeService(service)`

声明：function

设置使用的计算的服务群。设置成功返回 `0`

<!-- tags: 服务器交互函数 设置 修改 -->

| 参数      | 类型   | 说明                                                                          |
| --------- | ------ | ----------------------------------------------------------------------------- |
| `service` | string | 服务群名。空字符串表示默认服务，`'auto'` 表示自动选择，否则为指定的服务群名。 |

返回：integer

### 示例

范例01：设置自动选择并恢复原值

```tsl
old_service := getComputeService();
setComputeService("auto");
current_service := getComputeService();
setComputeService(old_service);
return current_service;
// 输出："auto"
```

## `tsTaskAdmin(command, var cmd_return, broad_cast_msg, err_msg[, wait_ms, data_recved_wait_ms])`

声明：function

向天软平台发送管理命令。本地函数调用时需要加上 RDO2。成功返回 `0`，结果通过 `cmd_return` 和 `broad_cast_msg` 输出

<!-- tags: 服务器交互函数 RDO2 -->

| 参数                  | 类型    | 说明                                                            |
| --------------------- | ------- | --------------------------------------------------------------- |
| `command`             | string  | 字符串类型，送入的命令串。更多任务管理命令查看：Q：任务管理说明 |
| `cmd_return`          | string  | 输出参数，接收命令执行结果。                                    |
| `broad_cast_msg`      | string  | 输出参数，接收命令期间收到的广播消息。                          |
| `err_msg`             | string  | 输出参数，发生错误时接收错误信息。                              |
| `wait_ms`             | integer | 可选。等待信息的毫秒数。                                        |
| `data_recved_wait_ms` | integer | 可选。收到数据后继续等待多少毫秒再结束。                        |

返回：integer

### 示例

范例01：发送任务管理命令

以下示例要求脚本已登录服务器。`oa` 命令无管理结果时，`cmd_return` 为 `0`。

```tsl
rdo2 tsTaskAdmin("oa", cmd_return, broad_cast_msg, err_msg, 3000, 1000);
return cmd_return;
// 输出：0
```