XTPPro

DolphinDB Server 2.00.19 和 3.00.6 及更高版本。支持 Linux x64。支持 Linux_ABI 特性。

使用前应准备以下信息：

• 可登录的 XTP-Pro 行情账户、服务器 IP 和端口，以及相应的行情权限。

• DolphinDB 进程可写的日志目录。

• 使用 UDP 时，准备 XTP-Pro SDK 要求的配置文件、对应的本地网卡和行情网络。配置文件需位于 DolphinDB 服务器上。

1. 在 DolphinDB 客户端中使用 listRemotePlugins 命令查看插件仓库中的插件信息。

   注意：仅展示当前操作系统和 server 版本支持的插件。若无预期插件，可自行编译（请选择对应分支下的插件）或在 DolphinDB 用户社区进行反馈。

   login("yourUser", "yourPassword")
   listRemotePlugins()

2. 使用 installPlugin 命令完成插件安装。

   installPlugin("XTPPro")

3. 使用 loadPlugin 命令加载插件。

   loadPlugin("XTPPro")

语法

XTPPro::setGlobalConfig(clientId, saveFilePath, [logLevel=3], [udpSeqOutput=false])

详情

设置一些全局配置项。在创建句柄前必须调用至少一次。无返回值。

在调用该接口时不能有已创建的句柄。第一次登录尝试后，修改日志路径、日志级别或 UDP 序列日志开关需要重启 DolphinDB 进程才能生效。

参数

clientId INT 类型标量，1-99 之间取值，表示客户端 ID。如果需要在多个 DolphinDB 进程中使用同一个账户去连接，则需要使用不同的 clientId。

saveFilePath STRING 类型标量，表示存储日志文件的目录，要求必须存在且有可写权限。

logLevel INT 类型标量，表示 xtp 记录日志的级别，0-5 之间取值，分别对应 FATAL ERROR WARNING INFO DEBUG TRACE 级别，默认是 3。

udpSeqOutput BOOL 类型标量，设定 UDP 方式接收行情时，是否输出序列相关异步日志，默认为 false。

语法

XTPPro::createXTPConnection(name, [config])

详情

返回一个连接句柄，可用于登录，订阅数据。

参数

name STRING 类型标量，连接句柄的唯一标识符，不能为空，也不能重复。

config 一个 key 类型为 STRING 的字典，包含如下所示的配置项：

语法

XTPPro::login(conn, config)

详情

连接 XTP-Pro 服务器并登录。无返回值。

注意事项（摘自 XTP 官方文档）：

• 测试环境使用 TCP 的方式推送行情。由于带宽的限制，建议客户只订阅少量股票，否则会出现推送延时、断线等问题。

• XTP 提供的 API 的默认日志级别是 DEBUG，需要调整到 INFO（或 ERROR），否则可能会导致丢包。本插件已将默认级别调整到 INFO，在调试时可以设置为 DEBUG。

参数

conn 由 createXTPConnection 接口返回的句柄。

config 一个 key 类型为 STRING 的字典，包含一些配置项：

语法

XTPPro::subscribe(conn, quoteType, marketType, codeList, tableDict)

详情

订阅行情数据，收到数据后存储到目标表中。无返回值。

注意事项：

• 订阅同一个行情类型时，在多次订阅上证、深证市场时，要求传入的 tableDict 相同，如果不同，则以第一次订阅传入的 tableDict 为准。

• 订阅同一个行情类型时，在多次订阅新三板市场时，要求传入的 tableDict 相同，如果不同，则以第一次订阅传入的 tableDict 为准。

• 订阅同一个行情类型时，市场类型如果已订阅了 5（上证+深证）则不能再次订阅 1（上证）或 2（深证）。

• 订阅同一个行情类型时，市场类型如果已订阅了 1（上证）或 2（深证）则不能再次订阅 5（上证+深证）。

• 如果 marketType 填为 5，则不能填非空的 codeList。

• 各目标表的 schema 可以通过 getSchema 接口获取。

• 目标表要求是共享表。

• 公网测试环境仅供客户调试 API 接口，没有订单簿 OB 行情。

参数

conn 由 createXTPConnection 接口返回的句柄。

quoteType INT 类型标量，表示行情类型。1：快照，2：逐笔，3：订单簿。

marketType INT 类型标量，表示市场类型。1：上证， 2：深证，3：新三板，5：上证+深证。

marketType=3 对应北交所及全国股转系统，仅支持通过 UDP 接收快照。

codeList STRING 类型向量或空值，表示合约 ID 数组。如果填 NULL 或空向量，则订阅全市场数据。

tableDict 一个字典，key 类型是 STRING，除 TickByTickTable 可使用通道字典外，value 必须是共享表，用来指定输出表。根据行情类型的不同，输出表的数量也不同。首次订阅时，如果空缺其中若干表，则相对应的行情会被丢弃，详情如下表所示：

注意：TickByTickTable 即逐笔合并表，其包含收到的三种逐笔数据（委托、成交、状态），在订阅逐笔数据时，tableDict 如果指定了 “TickByTickTable”，就会忽略其它的表。当 key 为 “TickByTickTable” 时，value 分成两种情况：

• value 为一个表，即包含收到的所有数据。

• value 为一个字典，该字典的键为整型，表示 channelNo，值是共享表，会将收到数据按照 channelNo 进行分类，放到不同的表中。

语法

XTPPro::unsubscribe(conn, quoteType)

详情

取消订阅某个类型的行情数据。无返回值。

参数

conn 由 createXTPConnection 接口返回的句柄。

quoteType INT 类型标量，表示行情类型。1：快照；2：逐笔；3：订单簿。

语法

XTPPro::getStatus([conn])

详情

获取订阅的状态信息。返回一个表，表结构如下所示：

参数

conn 由 createXTPConnection 接口返回的句柄，可选参数。如果不填，则返回当前所有连接的状态信息。

语法

XTPPro::getHandle(name)

详情

返回由 name 指定的连接句柄。

参数

name STRING 类型标量，表示连接句柄的唯一标识符。

语法

XTPPro::closeXTPConnection(conn)

详情

断开连接，销毁句柄。

参数

conn 由 createXTPConnection 接口返回的句柄。

语法

XTPPro::getSchema(type, [outputRecvTime=false], [outputElapsed=false])

详情

返回可存储相应行情类型数据的表的结构。

参数

type STRING 类型标量，表示类型。可选的 type 如下表所示：

outputRecvTime BOOL 类型标量，可选参数，默认为 false，表示是否需要包含 receiveTime 列。如果在 createXTPConnection 时指定了 receiveTime=1 配置，那么该参数须设置为 true。

outputElapsed BOOL 类型标量，可选参数，表示返回的 schema 是否包含 elapsedTime 列。默认为 false，表示不包含。如果在 createXTPConnection 时指定了 OutputElapsed=1 配置，那么该参数须设置为 true。

当 outputRecvTime 和 outputElapsed 均为 true 时，最后两列依次为 receiveTime、elapsedTime。

返回值

一个表结构。返回表每行描述一个输出字段，按输出列的实际顺序排列，包含以下列：

各行情输出表的完整字段说明见“数据表结构”。

语法

XTPPro::getAllNQTickersFullInfo(conn)

详情

查询北交所及全国股转系统证券的全量基础信息，返回包含 37 列的表，字段说明见“证券基础信息表”。

参数

conn 由 createXTPConnection 或 getHandle 返回的连接句柄，须已成功登录。

先设置 XTP_CLIENT_ID、XTP_LOG_PATH、XTP_IP、XTP_PORT、XTP_USER 和 XTP_PASSWORD 环境变量。以下示例采用 TCP，订阅上交所两个证券，并启用接收时间和处理耗时字段。

// 1. 设置全局配置。此时不能已有 XTPPro 连接句柄。
XTPPro::setGlobalConfig(
    clientId=int(getEnv("XTP_CLIENT_ID")),
    saveFilePath=getEnv("XTP_LOG_PATH"),
    logLevel=3,
    udpSeqOutput=false)

// 2. 创建句柄。如需多个连接，应在首次登录前全部创建。
connConfig = dict(keyType=STRING, valueType=ANY)
connConfig["receiveTime"] = 1
connConfig["OutputElapsed"] = 1
conn = XTPPro::createXTPConnection(name="xtpProFeed", config=connConfig)

// 3. 按对应 schema 创建并共享输出表。
quoteSchema = XTPPro::getSchema(
    type="actualMarketData", outputRecvTime=true, outputElapsed=true)
quoteTable = streamTable(10000:0, quoteSchema.name, quoteSchema.typeString)
share(table=quoteTable, sharedName="xtpProActual")
outputTables = dict(keyType=STRING, valueType=ANY)
outputTables["actualTable"] = quoteTable

// 4. 登录 TCP 行情服务器。
loginConfig = dict(keyType=STRING, valueType=ANY)
loginConfig["ip"] = getEnv("XTP_IP")
loginConfig["port"] = int(getEnv("XTP_PORT"))
loginConfig["user"] = getEnv("XTP_USER")
loginConfig["password"] = getEnv("XTP_PASSWORD")
loginConfig["protocolType"] = 1
XTPPro::login(conn=conn, config=loginConfig)

// 5. 订阅现货快照；其他未配置输出表的快照不会写入。
XTPPro::subscribe(conn=conn, quoteType=1, marketType=1,
    codeList=["600000", "600519"], tableDict=outputTables)

接收行情后，可在同一节点查询状态和输出表。

XTPPro::getStatus(conn=conn)
select top 10 * from xtpProActual

停止接收时，取消订阅并关闭连接。共享表保留，可继续查询已收到的数据。

XTPPro::unsubscribe(conn=conn, quoteType=1)
XTPPro::closeXTPConnection(conn=conn)

以下为快照示例中第 3 步、第 5 步的替换模板；先按相同流程配置、创建句柄并成功登录。

tickSchema = XTPPro::getSchema(
    type="TickByTickTable", outputRecvTime=true, outputElapsed=true)
tickTable = streamTable(10000:0, tickSchema.name, tickSchema.typeString)
share(table=tickTable, sharedName="xtpProTicks")
tickTables = dict(keyType=STRING, valueType=ANY)
tickTables["TickByTickTable"] = tickTable
XTPPro::subscribe(conn=conn, quoteType=2, marketType=1,
    codeList=["600000", "600519"], tableDict=tickTables)

如需按通道分表，将 TickByTickTable 的值改为通道字典。下例通道号仅作示意，应替换为行情源实际使用的通道号。此配置应在首次订阅逐笔数据时使用；已订阅时需先取消该类型的全部订阅。

channelOneTable = streamTable(10000:0, tickSchema.name, tickSchema.typeString)
channelTwoTable = streamTable(10000:0, tickSchema.name, tickSchema.typeString)
share(table=channelOneTable, sharedName="xtpProChannelOne")
share(table=channelTwoTable, sharedName="xtpProChannelTwo")
channelTables = dict(keyType=INT, valueType=ANY)
channelTables[1] = channelOneTable
channelTables[2] = channelTwoTable
tickTables = dict(keyType=STRING, valueType=ANY)
tickTables["TickByTickTable"] = channelTables
XTPPro::subscribe(conn=conn, quoteType=2, marketType=1,
    codeList=["600000", "600519"], tableDict=tickTables)

以下为快照示例的替换模板。不要在已有 TCP 登录的句柄上直接重复登录。

// 替换原登录步骤。XTP_CONFIG_FILE 为服务器上可读配置文件的绝对路径。
loginConfig["protocolType"] = 2
loginConfig["configFilePath"] = getEnv("XTP_CONFIG_FILE")
loginConfig["localIP"] = getEnv("XTP_LOCAL_IP")
XTPPro::login(conn=conn, config=loginConfig)

bseSchema = XTPPro::getSchema(
    type="BSEMarketData", outputRecvTime=true, outputElapsed=true)
bseTable = streamTable(10000:0, bseSchema.name, bseSchema.typeString)
share(table=bseTable, sharedName="xtpProBse")
bseTables = dict(keyType=STRING, valueType=ANY)
bseTables["BSEMarketData"] = bseTable
XTPPro::subscribe(conn=conn, quoteType=1, marketType=3,
    codeList=NULL, tableDict=bseTables)

// 一次性查询证券基础信息。
nqInfo = XTPPro::getAllNQTickersFullInfo(conn=conn)