Merge pull request #5 from exxeleron/develop

qXL tutorial added

doc/Building-qXL.md

@@ -31,7 +31,7 @@ To fully rebuild the solution and create the installer, execute:
 msbuild qXL.sln /t:Rebuild /p:Configuration=Release
 ```
 
-The installer is being built to the `ExcelAddInDeploy\bin\Release` folder.
+The installer is then built to the `ExcelAddInDeploy\bin\Release` folder.
 
 > Note:
 > 
@@ -47,7 +47,7 @@ The version number in AssemblyInfo and installer is generated upon build based o
 
 Version number follows the pattern `VERSION_MAJOR.VERSION_MINOR.VERSION_REVISION.VERSION_BUILD`, where each version element is represented as 16 bit integer. 
 
-In addition the `qXL` name can be post-fixed if the `VERSION_TYPE`. This can be used to create `BETA`, `RC` flavours of build.
+In addition the `qXL` name can be post-fixed if the `VERSION_TYPE`. This can be used to create `BETA` and `RC` flavours of build.
 
 
 ## Troubleshooting

doc/Installation.md

@@ -38,7 +38,7 @@ Most recent `qXL` plugin for Excel can be downloaded from [here](../../../releas
 
   ![step_4](../doc/img/Inst_step_4.png)
 
-1. Select which `qXL` features (XLL AddIn, examples) shall be installed:
+1. Select which `qXL` features (XLL AddIn, examples) should be installed:
 
   ![step_5](../doc/img/Inst_step_5.png)
 

doc/RTD-API-Functions.md

@@ -30,29 +30,29 @@ same Workbook object)
 - `password` [`String`] - password used to connect to q process
 
 Returns either:
-- alias bound with currently opened connection - in case opened successfully
+- alias associated with currently opened connection - in case opened successfully
 - description of error - in case connection could not be established
 
 The connection is opened only once. When using the same alias for all subsequent function calls, the same existing 
 connection will be used.
 
 > Note: 
 
->To force re-opening of the connection use `qUnsubscribe` and `qSubscribe` again or use different alias.
+>To force re-opening of the connection use different alias.
 
 [**Examples**](RTD-Examples.md#opening-and-closing-connection)
 
 <!--------------------------------------------------------------------------------------------------------------------->
 ### qRtdClose
 
-Function used to correctly close the connection bound with given alias:
+Function used to correctly close the connection associated with given alias:
 
 ```
 String qRtdClose ( alias )
 ```
 
 where:
-- `alias` [`String`] - closes the connection bound with given alias
+- `alias` [`String`] - closes the connection associated with given alias
 
 Returns string `Closed` if connection closed successfully or error description in case of failure.
 
@@ -61,7 +61,7 @@ Returns string `Closed` if connection closed successfully or error description i
 <!--------------------------------------------------------------------------------------------------------------------->
 ### qRtdConfigure
 
-Function used to configure various aspects of RTD server behavior:
+Function used to configure various aspects of RTD server behaviour:
 
 ```
 Object qRtdConfigure ( paramName, paramValue )
@@ -95,8 +95,8 @@ otherwise will return `old` value of the parameter.
 
 ### RTD
 
-Function used to subscribe to certain value from within cell in workbook so that it gets automatically populated with 
-new values as soon as they’re available:
+Function used to subscribe to certain value from within a cell in workbook so that it automatically gets populated with 
+new values as soon as they are available:
 
 ```
 Object RTD ( progID, server, topic1, topic2, topic3, topic4, topic5, topic6)
@@ -115,12 +115,12 @@ where:
 
 > Note:
 
-> Since `Topic6` can be used only for back tick subscription, system cannot determinate where to put data for 
+> Since `Topic6` can be used only for back tick subscription, system cannot determine where to put data for 
 particular symbols. That is why `Topic6` has been introduced – it is used to map incoming symbols to numbers. 
 First symbol which is delivered from database is mapped with first empty number of `Topic6` and it stays mapped 
 until all `RTD` formulas with given value of `Topic6` are present in the sheet.
 
-Updates the content of cell to which this function call is bound with the value matching subscription criteria.
+Updates the content of cell to which this function call is linked with the value matching subscription criteria.
 
 
 [**Examples**](RTD-Examples.md#subscribe-single-symbol)

doc/RTD-Examples.md

@@ -19,7 +19,8 @@
 
 #### Q process
 
-Before running examples it is assumed that system built based on [Lesson04](../../../../enterprise-components/edit/master/tutorial/Lesson04) is running on the local server. 
+Before running examples it is assumed that `Exxeleron` system from [Lesson04](../../../../enterprise-components/edit/master/tutorial/Lesson04) 
+ is installed [Lesson04](../../../../enterprise-components/edit/master/tutorial/Lesson04) on the local server. 
 
 
 #### Excel list separators
@@ -44,15 +45,15 @@ for more details.
 <!--------------------------------------------------------------------------------------------------------------------->
 ## Opening and closing connection
 
-To open a RTD connection to q process, necessary parameters need to be given to `qRtdOpen` function:
+To open a RTD connection to q process, necessary parameters need to be passed to `qRtdOpen` function:
 
 ```
 =qRtdOpen("testRTDConnection","localhost",17010)
 ```
 
 > Note:
 
-> Typically on production environment one would need to also pass username and password as parameters:
+> Typically, on production environment one would need to also pass username and password as parameters:
 > ```
 > =qRtdOpen("testRTDConnection","localhost",17010,"username","password")
 > ```
@@ -63,7 +64,7 @@ Otherwise, error message will appear:
 ![qOpen](../doc/img/qRTDOpen.png)
 
 
-Closing connection can be done by using the same alias as given in the `qRtdOpen` function:
+To close the connection again, use the same alias as given in the `qRtdOpen` function:
 
 ```
 =qRtdClose("testRTDConnection")
@@ -73,7 +74,7 @@ If connection is terminated, the `Disconnected from 'testRTDConnection'` message
 
 ![qClose](../doc/img/qRTDClose.png)
 
-Summary below shows all function calls which can be used to open and close connection between `qXL` and kdb+ server:
+Summary below shows all function calls, which can be used to open and close connections between `qXL` and kdb+ server:
 
 ![OpenCloseSummary](../doc/img/qRTDOpen_qRTDClose_summary.png)
 
@@ -85,11 +86,11 @@ Various aspects of RTD server configuration can be defined using `qRtdConfigure`
 =qRtdConfigure(paramName, paramValue)
 ```
 
-This function does not require `alias` as an argument since it is valid for all open subscriptions. It returns value of the parameter in question. If the parameter (given in the `paramName`) has been set correctly, its value will equal to `ParamValue`, otherwise `old` value of the parameter will be returned.
+This function does not require `alias` as an argument since it is valid for all open subscriptions. It returns the value of the parameter in question. If the parameter (given in the `paramName`) has been set correctly, its value will equal `ParamValue`, otherwise the `old` value of the parameter will be returned.
 
 The list of all possible parameters and their values is available in [RTD API documentation](../doc/RTD-API-Functions.md#qrtdconfigure)
 
-The most common example is setting history length, .i.e. the number of available published values starting from the latest one. 
+The most common example is setting history length, i.e. the number of available published values starting from the latest one. 
 
 ```
 =qRtdConfigure("data.history.length",60)
@@ -128,7 +129,7 @@ Please compare these two calls subscribing single and all instruments:
 =RTD("qxlrtd",,"testRTDConnection","quote","`",     "bid","", 1)    / all instruments
 ```
 
-As per [RTD](RTD-API-Functions.md#rtd) documentation, the last two parameters in second call are:
+According to [RTD](RTD-API-Functions.md#rtd) documentation, the last two parameters in second call are:
 
 > - `topic5` [`String`] - history index; optional - only needed when `Topic3` equals back tick symbol (\`); when filling 
 `Topic6` we have to have `Topic5` (can be empty)
@@ -148,22 +149,22 @@ Then for the screenshot below:
 
 ![RTD Wildcard](../doc/img/wildcard.png)
 
-following processing will take place:
+the following processing will take place:
 
-1. Initially none of the mapping identifiers defined in column A are used 
+1. Initially, none of the mapping identifiers defined in column A are used 
 2. First published symbol `GOOG` will be associated with first mapping identifier specified in cell `A2`, symbol and bid price will be displayed in cells `B2` and `C2` respectively
 3. Next published symbol from kdb+ is `MSFT` - since the first mapping identifier is already used for `GOOG`, the next available identifier will be used instead (defined in cell `A3`), symbol and bid price will be displayed in cells `B3` and `C3` respectively
 4. Another update will be also for `MSFT`, since this symbol is associated with mapping identifier `2`, only the bid price will be updated in cell `C3`
 5. Next published symbol - `YHOO` - will not be shown in Excel since only two mappings were created and both are already used
 6. Last update for `MSFT` will cause changes in cell `C3` for bid price
 
-To sum it up:
+Summary:
 - In Excel, if one would like to use all subscribed symbols, the mapping identifier has to be specified for each available symbol
 - List of subscribed instruments in Excel can be extended at any time by providing additional mapping identifiers, these mappings will be associated with published instruments without current identifiers
 - Symbols initially associated to mapping identifiers are based on the order of incoming updates
 - If published symbol is already associated with mapping identifier, existing values are updated
 - If published symbol is not associated with mapping identifier, either:
-  - new mapping identifier is allocated to this symbol if mapping identifiers are still available
+  - new mapping identifier is allocated to this symbol if mapping identifiers are still available or
   - update is disregarded if no further mapping identifiers are defined in Excel
 
 ## Opening and closing the workbook

doc/Troubleshooting.md

@@ -0,0 +1,65 @@
+###                                           **Troubleshooting**
+
+<!--------------------------------------------------------------------------------------------------------------------->
+`Troubleshooting` document describes known problems and solutions encountered during usage of `qXL` COM add-in. 
+
+> Note:
+  
+> Please use our [google group](https://groups.google.com/d/forum/exxeleron) 
+or open a [ticket](https://github.com/exxeleron/enterprise-components/issues) 
+in case you enocounter any installation/startup problem which is not covered in this document.
+
+
+### Issue 1 - memory leak while using charts based on RTD data
+
+##### Problem
+It was observed that memory usage is constanly growing for Excel Workbooks which contain charts built dynamically based on the data from `RTD` formula. The increase in memory usage depends on the charts types and amount of data they require. 
+The issue is caused by the memory leak for Excel charts with external data source. 
+
+##### Solution
+Using charts with `RTD` data is generally not recommended. Open again the Workbook to free the memory.
+
+### Issue 2 - no data updates after calling `qRTDClose` and `qRTDOpen`. 
+
+##### Problem
+In case of calling `qRTDClose` function the subscription is properly closed and the `RTD` formuls stops updating. However, calling `qRTDOpen` with the same alias again does not result in subsribing for new values. 
+
+##### Solution
+Calling `qRTDOpen` with different alias refreshes the connection and results in subscribing for new values. 
+
+### Issue 3 - stop of the display in the Excel after publishing process is stopped
+
+##### Problem
+In case of stopping the publishing `q` process to which Excel is subscribed the `RTD` formula values stop updating. Even after restrting the process the subscription is not automatically re-opened, values are not updating. 
+
+##### Solution
+Calling `qRTDOpen` with different alias refreshes the connection and results in subscribing for new values. 
+
+### Issue 4 - different display of `qQueryRange` and `qQuery` nested results. 
+
+#####Problem
+Nested results (with more than two dimensions) are displayed differently in Excel in `qQuery` and `qQueryResult` formulas.
+Whenever we try to display something different than `q` atom in single cell `qQuery` prints `#VALUE` error and `qQueryRange`
+leaves the cell blank. 
+
+Please see the example below: 
+
+We query nested list which have atoms on all position except for the first element of the second row where there is another list. 
+
+`qQuery` displays nested result as `#VALUE` error in Excel as can be seen below:
+
+![qQueryNested](../doc/img/qQueryNested.png)
+
+
+`qQueryRange` displays nested result as empty cell as can be seen below:
+
+
+![qQueryRangeNested](../doc/img/qQueryRangeNested.png)
+
+
+##### Solution
+
+To have the same display `qQuery` can be wrappred with `IFERROR` formula as can be seen below: 
+
+![qQueryNestedAligned](../doc/img/qQueryNestedAligned.png)
+

doc/Tutorial/Lesson01/README.md

@@ -0,0 +1,111 @@
+
+[:arrow_forward:](../Lesson02/README.md)
+
+#                                         **Lesson 1 - Opening a connection and running a query**
+
+<!--------------------------------------------------------------------------------------------------------------------->
+
+
+This tutorial only covers a subset of the available interface functions contained in qXL add-in.  Please refer 
+to `qXL` [documentation](../../Worksheet-Examples.md) for for  a full description of all functions.
+
+## Goal of the lesson
+
+The goal of the lesson is to present basic functionalities of `qXL`
+
+- opening a connection
+- running a query from Worksheet
+
+You can download the Excel [Workbook](../Lesson01/Lesson01.xlsx) with the content of the lesson.  
+
+<!--------------------------------------------------------------------------------------------------------------------->
+## Prerequisites
+
+Although this whole tutorial is built based on the assumption that `Exxeleron` 
+[system](https://github.com/exxeleron/enterprise-components) is installed locally, it is possible to use with other 
+systems. All parts of code which need amending will be explicitly mentioned.
+
+
+<!--------------------------------------------------------------------------------------------------------------------->
+## Opening connection
+
+To open a connection the `qOpen` formula needs to be called. It is described in details
+ [here](../../doc/Worksheet-VBA-API-Functions.md#qOpen).
+
+We suggest to have a seperate Sheet in each Workbook which handles all connections (especially if there are multiple
+ connections opened). It is more convenient to use Named Ranges for referring to connection details in `qOpen` '
+ function, as can be seen on the screen below. 
+
+![qOpen](../Lesson01/img/qOpen.png)
+
+```
+=qOpen(nrRdbAlas,nrRdbHost,nrRdbPort,nrRdbUser,nrRdbPassword)
+```
+
+As we see on the screen we have two connections opened:
+- first allows to process process on port 17011, which corresponds to `core.rdb` component on `Exxeleron` system installed locally
+- second allows to process process on port 17050, which corresponds to `access.ap` component on `Exxeleron` system installed locally
+
+> Note 
+> 
+The configuration needs to be changed in case of a system different than `Exxeleron`.  
+
+We also added  check cell, which shows whether the connection is open (cell "G2"). The formula inside is simply 
+`=A2=B2`, as properly opened connection returns the alias name.  
+
+<!--------------------------------------------------------------------------------------------------------------------->
+
+##Querying from Excel 
+
+The basic query function is `qQuery`. It is decribed in more detail 
+[here](../../doc/Worksheet-VBA-API-Functions.md#qQuery). 
+
+It takes the connection alias as the first argument and any `q` stament returning `q` object as the second. We use the already opened connection to `core.rdb` so we can query the process without using handles. In this example we use `q-sql` statement as the second argument. 
+
+> Note
+> In case of the production system it is recommended not to query `core.rdb` directly, but to use the access point component. 
+
+![queryResult](../Lesson01/img/qQueryResult.png) 
+
+```
+{=qQuery('kdb+ connection'!nrRdbConnection,A1)}
+```
+
+As we can see in the Excel Formula Bar the result is returned as an Array Formula. All non scalar results of `qQuery` are 
+returned this way. We can now run other queries by changing the content of the cell A1 only. The output range will be 
+automatically rescaled to match new query result. 
+
+<!--------------------------------------------------------------------------------------------------------------------->
+
+##Queries with paramaters
+
+Now we will present an example of calling a `qQuery` with multiple argument function being the secon `qQuery paramater. 
+The [.example.ohlcVwap2](https://github.com/exxeleron/enterprise-components/tree/master/tutorial/Lesson04) function
+returns OHLC table based on following parameters:
+
+- sym - list of securities symbols
+- d - list of dates
+- sTime - start time
+- eTime - end time
+- binSize - number of seconds
+
+The function is defined on the `access.ap` component, so we use this alias as the first `qQuery` argument.  
+We insert example values to Excel cells, as can be seen on the screen below using Named Ranges. 
+
+![qOhlcResult](../Lesson01/img/qOHLCResult.png)
+
+```
+{=qQuery('kdb+ connection'!nrApConnection,".example.ohlcVwap2",qList(nrSymbol,"s"),qList(nrDate,"d"),qAtom(nrStartTime,"t"),qAtom(nrEndTime,"t"),qAtom(nrTimeInterval,"i"))}
+```
+
+For getting results, we again use `qQuery` function. This time we need to provide the list of arguments converted to 
+proper `q` types. We use `qAtom` for converting scalars and `qList` for converting the list. Documentation of all
+convertion functions is available [here](../../Worksheet-VBA-API-Functions.md).
+
+`nrSymbol` Named Range formula is defined in the special way. It results in automatic expanding of the Named Range `nrSymbol` any time we add new symbol on the right side of the current range. We do the same for date. 
+
+![qRangeFormula](../Lesson01/img/qRangeFormula.png)
+
+
+
+