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 ：

export LD_LIBRARY_PATH=/your_plugin_path:$LD_LIBRARY_PATH 

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 ).

mkdir buildcd buildcmake ..make

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 ：

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

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 ：

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

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 )：

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

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 )：

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

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 ：

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

For example, the current status may be as follows :

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

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 ）：

//  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();

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.