Docking with Hang Seng express ― dolphin DB NSQ plug-in tutorial

For docking with Hang Seng NSQ Speed market service software ,DolphinDB Developed NSQ plug-in unit . Through this plug-in, you can get the market prices of Shanghai and Shenzhen . Mainly get the following three kinds of market ：

1. main - The spot depth market mainly pushes the callback
2. main - Spot transaction by transaction market is mainly driven by callback
3. main - The spot consignment market mainly pushes the callback

Issued by Hang Seng Electronics NSQ Speed market service software SDK, The name is HSNsqApi. Its corresponding linux Under the libHSNsqApi.so or windows Under the HSNsqApi.dll. When compiling, you need to copy the corresponding dynamic library to the lib/[linux.x/win][32/64]（ Such as lib/linux.x64) Folder . At runtime, you need to ensure that the corresponding link library can be found .

This paper mainly includes Linux/Windows In the environment DolphinDB NSQ Construction of plug-ins 、 Load and API Detailed instructions for use , And code examples and error messages .

---

Support NSQ Of server edition

at present , Only the following versions server Support NSQ plug-in unit ：

DolphinDB_Linux64_V2.00.6

DolphinDB_Linux64_V1.30.18

DolphinDB_Win64_V1.30.18_JIT

DolphinDB_Win64_V2.00.6_JIT

among , If you use Linux System , In the use of NSQ Before plug-in , You need to specify environment variables ：

Log in and copy

      
      

       
       export LD_LIBRARY_PATH=/your_plugin_path:$LD_LIBRARY_PATH 
      
      
      
      

       
       
1.
      
      

structure

Linux

Use cmake Compiling and constructing

First , stay nsq Create a plug-in folder build Folder , As a compilation workspace . Because you need links when compiling plug-ins libDolphinDB.so （libDolphinDB.so Is to run dolphindb The library on which we depend , Non plug-in specific ）. Before compilation , Need to put dolphindb server Under the same level or superior directory libDolphinDB.so Copy to build Folder .

Be careful ： stay  ​​nsq/lib​​  Next , There are for different operating systems NSQ SDK library , Stored in different folders , You need to copy one of the dynamic libraries to lib Catalog （ The default is linux64）. You also need to load this when the plug-in is running so library , Therefore, you also need to copy it to identify the so File path ( for example ：dolphindb server Lower and libDolphinDB.so Peer directory ).

Log in and copy

      
      

       
       mkdir build
       
       
cd build
       
       
cmake ..
       
       
make
      
      
      
      

       
       
1.
       
       
2.
       
       
3.
       
       
4.
      
      

windows

windows Under the system , Need to put nsq/lib/win32 perhaps nsq/lib/win64 Medium HSNsqApi.dll Copy to nsq/lib/ Catalog .

Compilation preparation

stay Windows Need to be used in the environment cmake and MinGW Compile , Download through the following link ：

• Download and install ​ ​MinGW​​. Ensure that bin Directories adding to system environment variables Path in .
• Download and install ​ ​cmake​​.

Use cmake structure

First , stay nsq Create a plug-in folder build Folder , As a compilation workspace . Because you need links when compiling plug-ins libDolphinDB.so （libDolphinDB.so Is to run dolphindb The library on which we depend , Non plug-in specific ）. Before compilation , Need to put dolphindb server Under the same level or superior directory libDolphinDB.dll Copy to build Folder .

Build plug-in content ：

Log in and copy

      
      

       
       cd <PluginDir>\nsq
       
       
mkdir build                                             #  newly build  build  Catalog 
       
       
COPY <ServerDir>/libDolphinDB.dll build                 #  Copy  libDolphinDB.dll  To  build  Under the table of contents 
       
       
cd build
       
       
cmake  ../ -G "MinGW Makefiles"
       
       
mingw32-make -j
      
      
      
      

       
       
1.
       
       
2.
       
       
3.
       
       
4.
       
       
5.
       
       
6.
      
      

Plug-in loading

The configuration file is PluginNsq.txt, Located in and libPluginNsq.so and libPluginNsq.dll Of the same rank build Catalog .

Compile the generated libPluginNsq.so after , Load the plug-in through the following script ：

Log in and copy

      
      

       
       loadPlugin("/path/to/PluginNsq.txt");
      
      
      
      

       
       
1.
      
      

API

nsq::connect(configFilePath)

Parameters

​​configFilePath​​  A string , Express  ​​sdk_config.ini​​  The absolute path of ; If copy  ​​sdk_config.ini​​  to dolphindb server, It can be relative to dolphindb server A relative path of .

Function details

This function will be based on NSQ The configuration file  ​​sdk_config.ini​​  Configuration of , Connect with the quotation server . After the connection is successful, the log file dolphindb.log Will print “OnFrontConnected”.

Please note that , Re execution connect Before reconnecting , It has to be executed first nsq::close() disconnect , Otherwise, an exception will be thrown .

nsq::subscribe(type, location, streamTable)

Parameters

​​type​​  A string , Indicates the type of quotation , Include the following values ：

• "snapshot"： Represents a callback function OnRtnSecuDepthMarketData（ main - Spot depth market ） Obtained market data .
• "trade"： Represents a callback function OnRtnSecuTransactionTradeData（ main - Spot transaction by transaction quotation main ） Obtained market data .
• "ticks"： Represents a callback function OnRtnSecuTransactionEntrustData（ main - Spot consignment market ） Obtained market data .

​​location​​: A string , Means Shanghai Stock Exchange or Shenzhen Stock Exchange . For Shanghai Stock Exchange  ​​sh​​  Express , Shenzhen Stock Exchange  ​​sz​​  Express .

​​streamTable​​: A table object that represents a shared flow table . Before subscribing, you need to create a flow table , And the flow table schema It needs to be consistent with the obtained market data structure . Please note that , It is recommended to set it as a persistent stream table object （ See  ​ ​enableTableShareAndPersistence​​  or  ​ ​enableTablePersistence​​）. otherwise , It could happen OOM.

Function details

It means subscribing to some market data published by Shanghai Stock Exchange or Shenzhen Stock Exchange , And save the result to the parameter  ​​streamTable​​  In the specified flow table .

After successful subscription , In the Journal （dolphindb.log) The following information will be printed in ( If it appears successfully, Indicates the subscription is successful )：

Log in and copy

      
      

       
       OnRspSecuTransactionSubscribe: nRequestID[0], ErrorID[0], ErrorMsg[subscribe all transaction trans type[1] of exchange_id [1] successfully]---------------------
      
      
      
      

       
       
1.
      
      

Please note that , If you need to subscribe to the same (​​type​​, ​​location​​) Market data output to another  ​​streamTable​​, Need to pass through  ​​unscribeTable​​  Command unsubscribe , Otherwise, an exception will be thrown .

streamTable（ Flow meter ） Is a special memory table , Used to store and publish stream data . For more usage methods of flow table, please refer to the document ：​ ​DolphinDB Stream computing tutorial ​​

nsq::unsubscribe(type, location)

Parameters

unsubscribe Two arguments to the command  ​​type​​  and  ​​location​​  The description of is the same as subscribe The consistency of .

Function details

It means to cancel the subscription to some market data published by Shanghai Stock Exchange or Shenzhen Stock Exchange , for example ：unsubscribe(`snapshot, `sz) It means to cancel the snapshot Subscription of market data .

After unsubscribing successfully , In the Journal （dolphindb.log) The following information will be printed in ( If it appears successfully, Indicates that unsubscribe succeeded )：

Log in and copy

      
      

       
       OnRspSecuTransactionCancel: nRequestID[0], ErrorID[0], ErrorMsg[unsubscribe all transaction trans type [2] of exchange_id [2] successfully]---------------------
      
      
      
      

       
       
1.
      
      

nsq::close()

Parameters

nothing

Function details

Indicates to disconnect the current connection . If the configuration file is modified , You need to execute close after , Re execution connect, So as to establish a new connection .

nsq::getSubscriptionStatus()

Parameters

nothing

Function details

​​getSubscriptionStatus​​  It is an operation and maintenance order , Used to get the current connection status , And the status of each subscription .

This function will return a table , adopt select Statement to view the obtained status , Usage is as follows ：

Log in and copy

      
      

       
       status = nsq::getSubscriptionStatus(); 
       
       
select * from status;
      
      
      
      

       
       
1.
       
       
2.
      
      

For example, the current status may be as follows :

Log in and copy

      
      

       
       topicType     isConnected isSubscribed processedMsgCount lastErrMsg failedMsgCount lastFailedTimestamp
       
       
-------------- ----------- ------------ ----------------- ---------- -------------- -------------------
       
       
(snapshot, sh) 1           1            0                            0
       
       
(snapshot, sz) 1           1            0                            0
       
       
(trade, sh)    1           1            0                            0
       
       
(trade, sz)    1           1            0                            0
       
       
(ticks, sh)    1           1            0                            0
       
       
(ticks, sz)    1           1            0                            0
      
      
      
      

       
       
1.
       
       
2.
       
       
3.
       
       
4.
       
       
5.
       
       
6.
       
       
7.
       
       
8.
      
      

Example

In the plug-in root directory  ​​nsq_script.txt​​  The document shows the application nsq A complete example of the plug-in . Here are some scripts （ Omit the specific schema part ）：

Log in and copy

      
      

       
       //  Sign in 
       
       
login("admin", "123456")
       
       
//  Add plug-ins 
       
       
loadPlugin("Your_plugin_path/PluginNsq.txt");
       
       
t = streamTable(
       
       
  xxx // schema
       
       
)
       
       
t1 = streamTable(
       
       
  xxx
       
       
);
       
       
go
       
       
//  Stream table persistence 
       
       
enableTableShareAndPersistence(table=t, tableName=`snapshot_sh, cacheSize=100000)
       
       
enableTableShareAndPersistence(table=t1, tableName=`trade_sh, cacheSize=100000)
       
       
nsq::connect(your_config_path);
       
       
//  Subscribe to the in-depth market of Shanghai Stock Exchange 
       
       
nsq::subscribe(`snapshot, `sh, snapshot_sh);
       
       
//  Unsubscribe 
       
       
nsq::unsubscribe(`snapshot, `sh)
       
       
//  Subscribe to the transaction by transaction quotation of Shanghai Stock Exchange 
       
       
nsq::subscribe(`trade`, `sh`, trade_sh);
       
       
//  Use this table object to operate 
       
       
select * from snapshot_sh limit 100;
       
       
//  Unsubscribe 
       
       
nsq::unsubscribe(`trade`, `sh`)
       
       

       
       
//  Get the status of each subscription 
       
       
status = nsq::getSubscriptionStatus();
       
       
select * from status;
       
       

       
       
//  Close the connection 
       
       
nsq::close();
      
      
      
      

       
       
1.
       
       
2.
       
       
3.
       
       
4.
       
       
5.
       
       
6.
       
       
7.
       
       
8.
       
       
9.
       
       
10.
       
       
11.
       
       
12.
       
       
13.
       
       
14.
       
       
15.
       
       
16.
       
       
17.
       
       
18.
       
       
19.
       
       
20.
       
       
21.
       
       
22.
       
       
23.
       
       
24.
       
       
25.
       
       
26.
       
       
27.
       
       
28.
       
       
29.
       
       
30.
       
       
31.
       
       
32.
      
      

Be careful ：schema The field type and order in need of and sdk The field types and order in the document are strictly consistent .

Error message

The information about the normal operation of the plug-in will be printed in the log file （dolphindb.log）, If an error occurs during operation , An exception will be thrown . Specific abnormal information and solutions are as follows ：

1. Repeated connection exception . If currently connected , You need to pass close Close the connection , Again connect Reconnection .

You are already connected. To reconnect, please execute close() and try again.

2. API Initialization error , Need to confirm connect Whether the incoming configuration file path and configuration information are correct .

Initialization failed. Please check the config file path and the configuration.

3. API Failed to connect to server , Need to confirm connect Whether the incoming configuration file path and configuration information are correct .

Failed to connect to server. Please check the config file path and the configuration.

4. Login error , user name , Wrong password .

login failed: iRet [iRet], error: [errorMsg]

5. API Uninitialized error , Need to check if connect() success

API is not initialized. Please check whether the connection is set up via connect().

6. subscribe Of  ​​streamTable​​  Parameter error , Need is a shared streamTable（ Shared flow table ）

The third parameter "streamTable" must be a shared stream table.

7. subscribe Of  ​​location​​  Parameter error , Need to be  ​​sh​​  or  ​​sz​​

The second parameter "location" must be ​​sh​​ or ​​sz​​.

8. subscribe Of  ​​type​​  Parameter error , Should be  ​​snapshot​​ or ​​trade​​ or ​​ticks​​

The first parameter "type" must be ​​snapshot​​, ​​trade​​ or ​​ticks​​.

9. subscribe ​​streamTable​​  Parametric schema error ,schema To be and SDK Agreement

Subscription failed. Please check if the schema of “streamTable” is correct.

10. Repeated subscription error , Want to change the same kind of subscription ( Such as  ​​snapshot​​, ​​sh​​  The two fields uniquely identify a type of subscription ) Subscribed flow table , It has to be executed first unsubscribe, Then update the subscription

Subscription already exists. To update subscription, call unsubscribe() and try again.

11. unsubscribe when API Uninitialized error

API is not initialized. Please check whether the connection is set up via connect().

12. close() error , Not initialized at （ Not invoked connect） Of API On the close

Failed to close(). There is no connection to close.