User Tools

  • Vistasource Document Library

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
rtw_4.5:rtshare_operation [2013/03/27 17:17]
Philip Wittamore
rtw_4.5:rtshare_operation [2018/08/04 20:09] (current)
Line 6: Line 6:
 The user interface of RTSHARE Client is accessible from the Excel ribbon. The user interface of RTSHARE Client is accessible from the Excel ribbon.
  
-{{ :​rtw_4.5:​excelvs_ribbon_rev.png?​nolink&​690 |Vistasource Ribbon Menu}}+{{ :​rtw_4.5:​excelvs_ribbon_rev.png?​nolink&​680 |Vistasource Ribbon Menu}}
 This section covers the following topics: ​ This section covers the following topics: ​
  
Line 20: Line 20:
 ====Requests==== ====Requests====
  
-For requesting ​data from records in another Excel workbook, two options are listed under Requests in the Vistasource ​portion of the Excel ribbon menu. You can either quickly enter a request or create a table with records in the spreadsheet. For more information see:+To request ​data from records in another Excel workbook, two options are available on the Vistasource ribbon menu. You can either quickly enter a request or create a table with records in the spreadsheet. For more information see:
  
   * [[#Quick Request]] ​   * [[#Quick Request]] ​
Line 31: Line 31:
 This option provides an easy way to automatically insert a request for a single record. ​ This option provides an easy way to automatically insert a request for a single record. ​
  
-Select **Vistasource -> RTSHARE -> Requests ->Quick Request** to create a subscribe request. ​+Select **Vistasource -> RTSHARE -> Requests -> Quick Request** to create a subscribe request. ​
  
 The RTSHARE Quick Request dialog box contains the following options: The RTSHARE Quick Request dialog box contains the following options:
Line 37: Line 37:
 |**Output Cell** | Enter a cell for the request’s output. To select a cell directly in the worksheet without having to type its reference, click on the icon next to the entry field.| |**Output Cell** | Enter a cell for the request’s output. To select a cell directly in the worksheet without having to type its reference, click on the icon next to the entry field.|
 |**Server** | Select the RTSHARE server by using one of the following methods: \\ - If a default server is set in [[#​rtshare_interface_preferences|Interface Preferences]],​ the server hostname will automatically fill in. \\ - Enter the server hostname in the server name box. \\ - Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list. \\ - Click **Query Network**, which updates the drop-down list of servers with a list of hosts on the network, and then selelct the server from the drop-down list. | |**Server** | Select the RTSHARE server by using one of the following methods: \\ - If a default server is set in [[#​rtshare_interface_preferences|Interface Preferences]],​ the server hostname will automatically fill in. \\ - Enter the server hostname in the server name box. \\ - Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list. \\ - Click **Query Network**, which updates the drop-down list of servers with a list of hosts on the network, and then selelct the server from the drop-down list. |
-|**Record Name** | Enter the record name. Clicking on the control on the right displays a list of available records. This list comes from the Update Record List and is based on which server is selected. Click **Update Record List** to refresh the list if you change the server.| +|**Record Name** | Enter the record name. Clicking on the control on the right displays a list of available records. This list comes from the Update Record List and is based on which server is selected. Click **Update Record List** to refresh the list if you change the server. Alternately,​ enter a new record name to create a new record.| 
-|**Add to Favorites** | To add frequently used records ​to a list of favorites, ​select ​a record and click **Add to Favorites**. To check which records have been added in previous and current sessions, click **View Favorites** to access the RTSHARE Records - Favorites List.|+|**Add to Favorites** | To add frequently used server/​record combinations ​to a list of favorites, ​supply ​server name and record ​name and click **Add to Favorites**. Favorites are saved in the following format: server, record or <​blank>,​record. To check which records have been added in previous and current sessions, click **View Favorites** to access the RTSHARE Records - Favorites List.|
    
 Click **OK** to insert the request in your workbook. ​ Click **OK** to insert the request in your workbook. ​
Line 51: Line 51:
  
 |**Cell Range** | Either highlight the table before accessing the dialogbox or enter a cell range for the formula’s output. To select a cell range directly in the worksheet without having to type its reference, click on the icon next to the entry field. The range has to contain your row or column of record names and a extra row or column accordingly. For instance: If records names are in row a1...a10, you need to specify a1....b10 for your range.| |**Cell Range** | Either highlight the table before accessing the dialogbox or enter a cell range for the formula’s output. To select a cell range directly in the worksheet without having to type its reference, click on the icon next to the entry field. The range has to contain your row or column of record names and a extra row or column accordingly. For instance: If records names are in row a1...a10, you need to specify a1....b10 for your range.|
-|**Server** | Select the RTSHARE server by using one of the following methods: \\ - If a default server is set in [[#​rtshare_interface_preferences|Interface Preferences]],​ the server hostname will automatically fill in. \\ - Enter the server hostname in the server name box. \\ - Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list. \\ - Click **Query Network**, which updates the drop-down list of servers with a list of hosts on the network, and then selelct ​the server from the drop-down list. |+|**Server** | Select the RTSHARE server by using one of the following methods: \\ - If a default server is set in [[#​rtshare_interface_preferences|Interface Preferences]],​ the server hostname will automatically fill in. \\ - Enter the server hostname in the server name box. \\ - Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list. \\ - Click **Query Network**, which updates the drop-down list of servers with a list of hosts on the network, and then select ​the server from the drop-down list. |
 |**Record Names in Column**| Choose the orientation of the data in columns. See example in Orientation panel.| |**Record Names in Column**| Choose the orientation of the data in columns. See example in Orientation panel.|
 |**Record Names in Row**| Choose the orientation of the data in rows. See example in Orientation panel| |**Record Names in Row**| Choose the orientation of the data in rows. See example in Orientation panel|
Line 64: Line 64:
 This option provides an easy way to automatically insert data to a record for sharing with other RTSHARE users. ​ This option provides an easy way to automatically insert data to a record for sharing with other RTSHARE users. ​
  
-Select **Vistasource -> RTSHARE -> Insert** to share a record. ​+Select **Vistasource -> RTSHARE -> Insert** to share data for a record. ​
  
 The RTSHARE Insert dialog box contains the following options: The RTSHARE Insert dialog box contains the following options:
Line 70: Line 70:
 |**Output Cell** | This is the location of the insert formula. To select a cell directly in the worksheet without having to type its reference, click on the icon next to the entry field.| |**Output Cell** | This is the location of the insert formula. To select a cell directly in the worksheet without having to type its reference, click on the icon next to the entry field.|
 |**Data Cell** | This is the location of the data you want to insert. To select a cell directly in the worksheet without having to type its reference, click on the icon next to the entry field| |**Data Cell** | This is the location of the data you want to insert. To select a cell directly in the worksheet without having to type its reference, click on the icon next to the entry field|
-|**Server** |Enter the name of the server or click **Query Network** ​to see a list of available ​servers. Clicking on the control on the right displays a history ​list with your previous choices. The list is stored in a file called rtshare_history.txt. **Note:** In Windows 7, this history file is located in ''​%USERPROFILE%\AppData\Roaming\Vistasource\RTW''​. In Windows XP, the file is located in ''​%USERPROFILE%\Application Data\Vistasource\RTW''​. If the AppData or Application directory does not exist, the file is located in ''​C:​\''​.| +|**Server** | Select the RTSHARE server by using one of the following methods: \\ - If a default server is set in [[#​rtshare_interface_preferences|Interface Preferences]],​ the server hostname will automatically fill in. \\ - Enter the server hostname in the server ​name box. \\ - Click the arrow on the right of the field to display ​a list of servers ​previously used, and select a server from the list. \\ - Click **Query Network**, which updates ​the drop-down list of servers with a list of hosts on the networkand then select ​the server from the drop-down list. | 
-|**Record Name** | Enter the record name. Clicking on the control on the right displays a list of available records. This list comes from the Update Record List and is based on which server is selected. Click **Update Record List** to refresh the list if you change the server.| +|**Record Name** | Enter the record name. Clicking on the control on the right displays a list of available records. This list comes from the Update Record List and is based on which server is selected. Click **Update Record List** to refresh the list if you change the server. Alternately,​ enter a new record name to create a new record.| 
-|**Add to Favorites** | To add frequently used server/​record combinations to a list of favorites, ​select ​a record and click the option button. Favorites are saved in the following format: server, record or <​blank>,​record. To check which records have been added in previous and current sessions, click **View Favorites** to access the RTSHARE Records - Favorites List.|+|**Add to Favorites** | To add frequently used server/​record combinations to a list of favorites, ​supply ​server name and record ​name and click **Add to Favorites**. Favorites are saved in the following format: server, record or <​blank>,​record. To check which records have been added in previous and current sessions, click **View Favorites** to access the RTSHARE Records - Favorites List.|
    
 Click **OK** to insert the shared data in your workbook. ​ Click **OK** to insert the shared data in your workbook. ​
Line 82: Line 82:
  
  
-To add frequently used records ​to a list of favorites, select a record and click **Add to Favorites** in the RTSHARE Quick Request or RTSHARE Insert dialog boxes.  ​+To add frequently used server/​record combinations ​to a list of favorites, select a server name and record ​name and click **Add to Favorites** in the RTSHARE Quick Request or RTSHARE Insert dialog boxes.  ​
  
-To check which records have been added in previous and current sessions, click **View Favorites** to access the RTSHARE Favorites List.+To check which server/records ​combinations ​have been added in previous and current sessions, click **View Favorites** to access the RTSHARE Favorites List.
    
-To modify the content of the RTSHARE Favorites List, click **Manage** to display the RTSHARE Manage Favorites List dialog box. To learn more about adding, deleting and modifying the RTSHARE Favorites list see [[#Manage Favorites]].+To modify the content of the RTSHARE Favorites List, click **Manage** ​while in the View Favorites dialog box to display the RTSHARE Manage Favorites List dialog box. To learn more about adding, deleting and modifying the RTSHARE Favorites list see [[#Manage Favorites]].
  
  
 ==== Manage Favorites ==== ==== Manage Favorites ====
  
-The RTSHARE Manage Favorites List dialog box allows you to add, delete, and modify your list of favorite records. To access this dialog, click **View Favorites** in the Quick Request or Insert dialog boxes, or select the dialog box launcher in the **Vistasource -> RTSHARE** group and then click on **Manage**+The RTSHARE Manage Favorites List dialog box allows you to add, delete, and modify your list of favorite records. To access this dialog, click **View Favorites** in the Quick Request or Insert dialog boxes, or select the dialog box launcher in the **Vistasource -> RTSHARE** group. ​
  
 The RTSHARE Manage Favorites List dialog box contains the following fields: The RTSHARE Manage Favorites List dialog box contains the following fields:
  
-|**Favorites List** | Displays all the server/​record combinations you have previously added. A record without a server preceeding ​has the local host. Add or delete ​records ​in this list or modify them by changing the associated fields: \\ <​html><​br/><​ul><​li>​To add a server/​record combination,​ enter the name of the server or click <​b>​Query Network</​b>​ to see a list of available servers and select the server. Next, click <b>Get Records</b>. All records on the server display. Select the record and click <​b>​Add</​b>​. </​li><​li>​To delete a server/​record combination,​ select the record in the  <​b>​Favorites List</​b>​ and click <​b>​Delete</​b>​.</​li><​li>​To modify a server/​record combination,​ select the record in the <​b>​Favorites List</​b>​. All relevant entry fields will automatically fill in. Make your modifications and click <​b>​Modify</​b>​.</​li></​ul></​html>​| +|**Favorites List** | Displays all the server/​record combinations you have previously added. A record without a server preceeding ​signifies ​local host. Add or delete ​record items in this list or modify them by changing the associated fields: \\ <​html><​br/><​ul><​li>​To add a server/​record combination,​ enter the name of the server or click <​b>​Query Network</​b>​ to see a list of available servers and select the server. Next, click <b>Update Record List</b>. All records on the server display. Select the record and click <​b>​Add</​b>​. </​li><​li>​To delete a server/​record combination,​ select the record in the  <​b>​Favorites List</​b>​ and click <​b>​Delete</​b>​.</​li><​li>​To modify a server/​record combination,​ select the record ​item in the <​b>​Favorites List</​b>​. All relevant entry fields will automatically fill in. Make your modifications and click <​b>​Modify</​b>​.</​li></​ul></​html>​| 
-|**Server** | Enter the server name for the records you want to add or choose from the list of favorites to modify. If left blank, ​the local host will be used.|+|**Server** | Enter the server name for the records you want to add or choose from the list of favorites to modify. If left blank, ​'local host' ​will be used.|
 |**Record** | Enter a name for the record you want to add or choose from the list of favorites to modify.| |**Record** | Enter a name for the record you want to add or choose from the list of favorites to modify.|
    
Line 105: Line 105:
  
  
-In RTSHARE, the Microsoft (r) Excel RTD function is used for requesting and inserting data. For more information about the syntax of the RTD when used in RTSHARE, see [[#​Requesting Data with the RTD Function]] and [[#​Inserting Data with the RTD Function]].+In RTSHARE, the Microsoft (r) Excel RTD function is used for requesting and inserting data. For more information about the syntax of the RTD function ​when used in RTSHARE, see [[#​Requesting Data with the RTD Function]] and [[#​Inserting Data with the RTD Function]].
  
 Vistasource recommends using the supplied [[#wrapper functions]] RTS_SHARE and RTINSERT_SHARE to simplify the use of the RTD function. ​ Vistasource recommends using the supplied [[#wrapper functions]] RTS_SHARE and RTINSERT_SHARE to simplify the use of the RTD function. ​
Line 114: Line 114:
 ====Wrapper functions==== ====Wrapper functions====
  
-The following wrapper functions are available for inserting and requesting data. Wrapper functions call the RTD function with the required default arguments, plus the given arguments. In this way, redundant arguments are hidden, exposing only the data that is important to you. +The following wrapper functions are available for inserting and requesting data with RTSHARE. Wrapper functions call the RTD function with the required default arguments, plus the given arguments. In this way, redundant arguments are hidden, exposing only the data that is important to you. 
  
 ===Requesting Data=== ===Requesting Data===
Line 121: Line 121:
  
 |**FUNCTION**|RTS_SHARE| |**FUNCTION**|RTS_SHARE|
-|**ARGUMENTS** | HostKey+|**ARGUMENTS** | HostnameRecordname
-|**EXAMPLE** | <​code>​=RTS_SHARE("​MYHOST", "MYKEY"​)</​code>​| +|**EXAMPLE** | <​code>​=RTS_SHARE("​MyHost", "MyRec"​)</​code>​| 
-|**DESCRIPTION** | Receives value of MYKEY using the specified RTSHARE server| +|**DESCRIPTION** | Receives value of MyRec using the specified RTSHARE server.
-|**NOTES** | MYKEY is obligatory. If no host is provided, then connection to the local machine is attempted.|+|**NOTES** | Recordname ​is obligatory. If no hostname ​is provided, then connection to the local machine is attempted.|
  
  
 ===Inserting Data=== ===Inserting Data===
  
-The wrapper ​functions ​RTINSERT_SHARE is used to insert data.+The wrapper ​function ​RTINSERT_SHARE is used to insert data.
  
 |**FUNCTION**|RTINSERT_SHARE| |**FUNCTION**|RTINSERT_SHARE|
-|**ARGUMENTS**|Valuehost. key+|**ARGUMENTS**|ContribCellHostname, Recordname
-|**EXAMPLE**|<​code>​=RTINSERT_RTSHARE("a1", "host", "MYKEY"​)</​code>​| +|**EXAMPLE**|<​code>​=RTINSERT_SHARE(a1, "MyHost", "MyRec"​)</​code>​| 
-|**DESCRIPTION**|Shares value of MYKEY in a1 using the specified RTSHARE server.| +|**DESCRIPTION**|Shares ​the cell value of the specified cell for recordname ​ MyRec using the specified RTSHARE server.| 
-|**NOTES**|Cell location ​and MYKEY are obligatory. If no host is provided, then connection to the local machine is attempted.| +|**NOTES**|ContribCell ​and Recordname ​are obligatory. If no Hostname ​is provided, then connection to the local machine is attempted.|
- +
  
  
 +<​note>​When inserting values with RTINSERT_SHARE,​ the output cell may show an initial #N/A, This is intrinsic to how an RTD server works, data is not dropped. As soon as the actual value is available, OK is displayed, indicating that the insert was successful. For more information see: [[http://​msdn.microsoft.com/​en-us/​library/​aa140060(v=office.10).aspx#​odc_xlrtdfaq_whyalwaysna|msdn.microsoft.com]]</​note> ​
 ===Requesting Data with the RTD Function=== ===Requesting Data with the RTD Function===
  
-The RTD function ​uses the following arguments when requesting data:+The generic syntax for the Microsoft Excel(r) ​RTD function ​is as follows:
    
-=RTD(ProgId, ​servercommandhost, recordname])+<​code>​=RTD(ProgId, ​ServerTopic1[Topic2], ...) </​code>​ 
 + 
 +When using RTSHARE to request data, the RTD function takes the following arguments:​ 
 + 
 +<​code>​=RTD(ProgId,​ Server, Command, Service, Hostname, Recordname</​code>​
    
 The arguments have the following meaning: The arguments have the following meaning:
Line 152: Line 155:
 |Server |Remains null.| ​ |Server |Remains null.| ​
 |Command|“rt”,​ to indicate the subscribe command.| ​ |Command|“rt”,​ to indicate the subscribe command.| ​
-|Host|The RTSHARE server facilitating the request. If left blank, local host will be used, i.e. the machine name where the RTSHARE server is running|+|Service|The name of the service, rtshare.| 
 +|Hostname|The RTSHARE server facilitating the request, i.e. the machine name where the RTSHARE server is running.  If left blank, localhost will be used. |
 |Recordname|The name of the record that is requested.| ​ |Recordname|The name of the record that is requested.| ​
    
-The following formula ​request ​the value of MyKey on server MyHost:+The following formula ​requests ​the value of MyRec on server MyHost:
  
-''​=rtd ("vistasource.rtdserver",,"​rt","​rtshare","​MyHost","​MyKey")\\ +<​code>​=RTD("Vistasource.RtdServer",,"​rt","​rtshare","​MyHost","​MyRec")</​code> ​\\
-''​+
  
  
  ​===Inserting Data with the RTD Function===  ​===Inserting Data with the RTD Function===
  
-The RTD function ​uses the following argument when inserting data: +The generic syntax for the Microsoft Excel RTD function ​is as follows:
-  +
-=RTD(ProgId,​ server, command, host, recordname])+
    
 +<​code>​=RTD(ProgId,​ Server, Topic1, [Topic2], ...) </​code>​
 +
 +When using RTSHARE to insert data, the RTD function takes the following arguments:
 +
 +<​code>​=RTD(ProgId,​ Server, Command, ContribCell,​ Service, Hostname, Recordname) </​code>​
 +
 +
 The arguments have the following meaning: The arguments have the following meaning:
  
Line 173: Line 181:
 |Server |Remains null.| ​ |Server |Remains null.| ​
 |Command|“rtinsert”,​ to indicate the insert command.| ​ |Command|“rtinsert”,​ to indicate the insert command.| ​
-|Data range|The cell location for the data being inserted.| +|ContribCell|The cell location for the data being inserted.| 
-|Host|The RTSHARE server facilitating the request. If left blank, local host will be used, i.e. the machine name where the RTSHARE server is running.| +|Service|The name of the service, rtshare.| 
-|Recordname|The name of the record ​that is requested.| +|Hostname|The RTSHARE server facilitating the request, i.e. the machine name where the RTSHARE server is running. If left blank, localhost will be used.| 
 +|Recordname|The name of the record ​of which to insert data.| 
    
-The following formula inserts the value of MyKey on server MyHost ​in cell a1:\\ +The following formula inserts the value of A1 using the recordname MyRec on server MyHost:\\
- +
-'' ​ =rtd ("​vistasource.rtdserver",,"​rtinsert",​ a1,"​rtshare","​MyHost","​MyKey"​) +
-''​+
  
 +<​code>​=RTD("​Vistasource.RtdServer",,"​rtinsert",​ a1,"​rtshare","​MyHost","​MyRec"​)</​code>​\\
  
 ==== Status Window for the RTSHARE Client==== ==== Status Window for the RTSHARE Client====