User Tools

  • Vistasource Document Library

RTSHARE Administration

RTSHARE allows a flexible setup of server and client machines. The RTSHARE client requests or inserts data to and from an RTSHARE server. The initial setup of RTSHARE occurs during installation, where you can choose to install either the RTSHARE Server or Client, or both. To use RTSHARE, you will need a minimum of one server and one client. Multiple servers and clients can be networked together. For more details, see:

For information regarding the functionality of RTSHARE, see:

RTSHARE Server Administration

For system administrators who need to manually start the RTSHARE Server process or stop/start the process, delete records or troubleshoot RTSHARE, see:

Other administrative steps for the RTSHARE Server process take place in the RTSHARE Admin window. The Admin window can be accessed from both the RTSHARE Server and the RTSHARE Client machines; however, its contents will differ slightly depending on whether you access it from a RTSHARE Server or Client machine.

The following tasks are available on the tabs of the RTSHARE Admin window:

For information about administrative tasks specific to RTSHARE Client, see Administration of the RTSHARE Client.

We strongly recommend that only system administrators or experienced users make changes to the configuration options.

Server Startup

During the installation of the RTSHARE server:

  • If you keep the default selections, license the product and restart your machine, the executables rtshare and rts_share will start automatically when Windows starts. In this case, you do not need to manually start the RTSHARE Server process.
  • If you uncheck the default option to automatically start the RTSHARE Server process when Windows starts and then start Windows, a Vistasource RTSHARE license gets checked out and the Vistasource RTSHARE icon appears on the task bar together with a brief window about the licensing status. However, the RTSHARE server process must be manually started.
To Manually Start the RTSHARE Server Process

Click Vistasource → RTSHARE in the Windows Start menu. This starts both rts_share and rtshare, which will automatically start the RTSHARE service and check out a VSRTSHARE license. The RTSHARE icon appears in the taskbar together with a brief window about the licensing status. By right-clicking on the icon you can access the RTSHARE Admin window, view logs, server_stop/start, access the online help and view the RTSHARE About dialog box.

The RTSHARE Server process has to be manually started this way, otherwise it will fail.

Server Stop/Start

On the RTSHARE Server machine, you can start or stop the rtshare service:

  1. Right-click on the RTSHARE icon in the taskbar.
  2. Select Stop rtshare if the rtshare service is running and should be stopped for any reason.
  3. Alternately, select Restart rtshare, if the service has stopped and should be restarted.
Stopping and restarting rtshare permanently deletes records which have been deleted in the spreadsheet from the record list by refreshing the cache. However, permission settings for the records remain in the registry.

When the RTSHARE server stops or goes down for any reason, the RTSHARE client users will receive a message asking whether they want to reconnect to the server. If the RTSHARE server has started up again and the reconnect is successful, the last successfully inserted value before the connection went down is re-published.

Deleting Records

Records are created by Inserts and Requests. These records are added to the record list. If a user deletes a formula that contains a particular record, this record is still available in the record list. To prevent accidental deletion of records, the only way to permanently delete records from the record list is by refreshing the record cache.

To learn more about refreshing the record cache, see Server Stop/Start.

RTSHARE Admin Window

The RTSHARE Admin window contains options for administrating the RTSHARE Server process, including viewing records, modifying permissisons, settings ports, as well as setting and viewing trace and error files.

To access the RTSHARE Admin Window:

  • On the RTSHARE server machine, right-click on the RTSHARE icon in the taskbar and select Admin. The RTSHARE Admin (Server) window displays.

  • On the RTSHARE client machine, in Excel, click Vistasource→RTSHARE→Admin. The RTSHARE Admin (Client) window displays.

RTSHARE Admin Window Tabs

The RTSHARE Admin window contains the tabs View and Settings, plus a Logs tab on the server machine:

The View tab facilitates:

The Settings tab facilitates:

The Logs tab in the RTSHARE Admin window on the server machine facilitates:

Viewing Records

The View tab in the RTSHARE Admin Window lists the available records on a server together with information about the record owner and the permission status.

From the Server Admin Window

  1. Right-click on the RTSHARE icon in the taskbar and select Admin.
  2. Select the View tab. The records are fetched and displayed.
  3. Click on Update Records to show the most current status.

From the Client Admin Window

  1. In Excel, click Vistasource→RTSHARE→Admin.
  2. Select the RTSHARE server using one of the following methods:
    1. If a default server is set in Interface Preferences, the server hostname will automatically fill in.
    2. Enter the server hostname in the server name box.
    3. Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list.
    4. 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.
  3. Click the View tab in the Admin dialog box.
  4. If no records are displayed, click Get Available Records. The records for the server are fetched and displayed.
  5. If records are already displayed, clicking Get Available Records updates the list. Any additionally available records are appended.

Record Permissions

RTSHARE allows you to deny or allow user access to individual records. See Modifying Record Permissions

By default, all records are open to all users.

Modifying Record Permissions

Permissions can be modified in the RTSHARE Admin Window.

From the Server Admin Window

  1. Right-click on the RTSHARE icon in the taskbar and select Admin.
  2. Select the View tab. The records are fetched and displayed. Clicking Update Record List will show the most record list.
  3. Select the record. The button Modify Permissions becomes available.
  4. Click Modify Permissions. The RTSHARE Modify Permissions for [record] on [server] dialog opens.
  5. In the Permission Context panel, select whether you want to set request or insert permissions to the record name.
  6. In the Permission Type panel, select to allow users or deny users access to the record depending on your selection of Request or Insert Permission. For more detail, see Allow Access to a Record or Deny Access to a Record.

From the Client Admin Window

  1. In Excel, click Vistasource→RTSHARE→Admin.
  2. Select the RTSHARE server using one of the following methods:
    1. If a default server is set in Interface Preferences, the server hostname will automatically fill in.
    2. Enter the server hostname in the server name box.
    3. Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list.
    4. 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.
  3. Click the View tab in the Admin window.
  4. Click Get Available Records. The records for the server are fetched and displayed. If records were already displayed, the list will be updated and any additionally available records are appended to the list.
  5. Select a record. The button Modify Permissions becomes available.
  6. Click Modify Permissions. The RTSHARE Modify Permissions for [record] on [server] dialog opens.
  7. In the Permission Context panel, select whether you want to set request or insert permissions to the record name.
  8. In the Permission Type panel, select to allow users or deny users access to the record depending on your selection of Request or Insert Permissions. For more detail, see Allow Access to a Record or Deny Access to a Record.

Allow Access to a Record

  1. In the Permission Type panel, select Allow Users to define which users should have access to the record. All other users will have access denied. Whether the permissions affect requesting or inserting the record depends on your selection in the Permission Context panel above.
  2. Enter the user name or user/host combination in the Name field and then click Add User or Add Host depending on your entry. To add more users, repeat this step. Only these users/hosts will have access to the record. The following options are available when selecting users:
    • user@host = specific user on specific host
    • user = specific user on any host
    • @host = any user on a specific host
  3. To remove a user for the allowed user list, select the name, and click Remove User or Remove Host depending on your selection.
  4. Click OK to return to the View tab.

Deny Access to a Record

  1. In the Permission Type panel, select Deny Users to define which users should have no have access to the record. All other users will have access. Whether the permissions affect requesting or inserting a record depends on your selection in the Permission Context panel above.
  2. Enter the user name or user/host combination in the Name field and then click Add User or Add Host depending on your entry. To add more users, repeat this step. Only these users/hosts will have no access to the record. The following options are available when selecting users:
    • user@host = specific user on specific host
    • user = specific user on any host
    • @host = any user on a specific host
  3. To remove a user for the denied user list, select the name, and click Remove User or Remove Host depending on your selection.
  4. Click OK to return to the View tab.

Managing Ports

For RTSHARE to properly communicate between server and client, the port settings on both client and server must match. The default server port is 5494. While it is not necessary to set both server and client to the default port, both settings must be identical.

The RTSHARE client and server ports can be modified in the RTSHARE Admin Window. The RTSHARE Client Admin window allows you to specify the RTSHARE Server port. If you change the server port, you must restart the server for the change to take effect. The RTSHARE Client Admin window allows you to see the server port and modify the client port if the ports do not match.

Make sure the port used is not blocked by your firewall

Managing the Server Port

To verify or change the port settings on the RTSHARE Server machine:

  1. Right-click on the RTSHARE icon in the taskbar and select Admin. The RTSHARE Server Admin window displays.
  2. Select the Settings tab. The default port is 5494. If you change this setting, click Apply. You will be prompted to restart the server for the change to take effect. Note: If you change the port number, the port settings on the client machines must be changed as well.
  3. Click Close.
If two or more RTSHARE servers are used, all ports must be identical.

Managing the Client Port

For RTSHARE Client users on Windows 7: This option is only available, if Excel is running in elevated mode. If the option appears greyed out, please contact your system administrator about running in elevated mode.

To verify or change port settings on the RTSHARE Client machine:

  1. In Excel, click Vistasource→RTSHARE→Admin. THe RTSHARE Admin Client window displays.
  2. Select the RTSHARE server using one of the following methods:
    1. If a default server is set in Interface Preferences, the server hostname will automatically fill in.
    2. Enter the server hostname in the server name box.
    3. Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list.
    4. 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.
  3. Click the Settings tab in the Admin dialog box,
  4. Click Get current settings. The bottom of the Settings tab displays the port on the server you queried and the current port setting for the client mahcine. If the server port differs from the client port, the following message appears: No response from server. In this case, change the client port and click OK.
If two or more servers are used, all ports must be identical.

Tracing

Tracing collects a detailed log of service initialization, all transactions between server and client as well as general information. It is typically used to debug network or connection problems. Tracing options for the server can be modified using both the client and server RTSHARE Admin Window.

To obtain tracing information, turn on the Trace option. The option is turned off by default.

From the RTSHARE Server Admin Window

To turn on Tracing:

  1. Right-click on the RTSHARE icon in the taskbar and select Admin.
  2. Click on Settings tab.
  3. Toggle on Tracing option.
  4. Specify a path and filename in the Trace File option. The path is empty by default. To enter the path, click Browse to choose the directory and file name for the trace file, e.g.
    C:\Users\[username]\AppData\Roaming\Vistasource\RTW\rtshare_log.
  5. Click Apply.

To view the Trace file:

  1. Right-click on the RTSHARE icon in the taskbar and select Admin.
  2. Click on Views tab. Here you can toggle between the active Trace and Error files.

Alternatively, right-click on the RTSHARE icon in the taskbar and select View Logs in the menu or navigate to the file in the specified directory on the server machine and open it in a text editor like notepad or wordpad.

From the Client Admin Window

  1. In Excel, click Vistasource→RTSHARE→Admin.
  2. Select the RTSHARE server using one of the following methods:
    1. If a default server is set in Interface Preferences, the server hostname will automatically fill in.
    2. Enter the server hostname in the server name box.
    3. Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list.
    4. 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.
  3. Click on Settings tab.
  4. Click Get Current Settings, because the tracing option and the trace file may already be set. In this case, the option and path will autofill. Skip the next steps and click Apply and then Close. If you wish to change these setttings, toggle the tarce file on/off and specify a different path accordingly.
  5. If nothing has been set, check the Tracing option. The path for the trace file will be empty by default.
  6. Enter the path for the trace file on the server machine, e.g. C:\Users\[username]\AppData\Roaming\Vistasource\RTW\rtshare_log. Note: Please consult with your system administrator before changing location as you change it for all users on the server.
  7. Click Apply and then Close.
You can only view the Trace file on the RTSHARE Server machine. Alternately, if the Trace file is saved on a shared directory accessible from the client machine, you can open it in a text editor like notepad or wordpad.

Error Logging

To log errors that might occur during the operation of RTSHARE server on the server machine, turn on error logging. The option is turned off by default. You can administer error logging for the server via both the RTSHARE server and RTSHARE client machines. For information about error messages, see Troubleshooting.

For information about error messages on a RTSHARE Client machine, see Status Window for RTSHARE Client.
From the Server Admin Window

To log errors:

  1. Right-click on the RTSHARE icon in the taskbar and select Admin.
  2. Click on Settings tab.
  3. Toggel on the Log Errors option
  4. Specify a path and file name in the Error File optin. The Path is empty by default. Ener the path or click Browse to choose the directory and file name for the error file , e.g. C:\Users\[username]\AppData\Roaming\Vistasource\RTW\rtshare_err.
  5. Click Apply.

To view the Error file:

  1. Right-click on the RTSHARE icon in the taskbar and select Admin.
  2. Click on Views tab. Here you can toggle between the active Trace and Error files.

Alternatively, right-click on the RTSHARE icon in the taskbar and select View Logs in the menu or navigate to the file in the specified directory on the server machine and open it in a text editor like notepad or wordpad.

From the Client Admin Window

To set the Error file:

  1. In Excel, click Vistasource→RTSHARE→Admin.
    1. If a default server is set in Interface Preferences, the server hostname will automatically fill in.
    2. Enter the server hostname in the server name box.
    3. Click the arrow on the right of the field to display a list of servers previously used, and select a server from the list.
    4. 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.
  2. Click on Settings tab.
  3. Click Get Current Settings, because the error option and error log file may already be set. In this case, the option and path will autofill. Skip the next steps and click Apply and then Close. If you wish to change these setttings, toggle the error log file on/off and specify a different path accordingly.
  4. If nothing has been set, check the Error Logging option. The path for the error file will be empty by default.
  5. Enter the path for the error file on the server machine, e.g. C:\Users\[username]\AppData\Roaming\Vistasource\RTW\rtshare_log. Note: Please consult with your system administrator before changing location as you change it for all users on the server.
  6. Click Apply and then Close.
You can only view the Error Log file on the RTSHARE Server machine. Alternately, if the Error Log file id saved in a shared directory accessible from the client machine, you can open it in a text editor like notepad or wordpad.

RTSHARE Client Administration

The administration of the RTSHARE Client includes the following options:

RTSHARE Interface Preferences

On the RTSHARE tab of the Interface Preferences dialog box, you can set the default server for RTSHARE to provide ease of use when working in the dialog boxes. If specified, the default server will be automatically entered in the Server field in the RTSHARE Insert, Request and Client Admin dialog boxes:

  1. Select Vistasource → Settings → Interface Preferences to display the RTW Interface Preferences dialog box. This dialog box contains a Generic Tab as well as tabs representing the installed and licensed RTW Engines and/or RTSHARE.
  2. Select the RTSHARE tab.
  3. Enter a server name in the field Default Server or click Query Network for a list of available servers on the network.
  4. Select the server you want to use.
  5. Click OK to confirm your selection.

For more information about the Generic Tab, go to Generic Tab. If your installation also includes one or more of the RTW engines, tabs for all installed and licensed RTW engines are displayed. See Interface Preferences for information regarding the installed engines.

The interface preferences are stored in a file which RTW will read when it starts. In Windows 7, the file is located in %USERPROFILE%\AppData\Roaming\Vistasource\RTW\preferences. In Windows XP, this file located in %USERPROFILE%\Application Data\Vistasource\RTW\preferences. In both operating systems, this file can be read in any text editor, such as Notepad or Wordpad.

Rtconfig Editor - RTSHARE Settings

RTW and RTSHARE have configuration options which define the behavior of RTW, RTSHARE, and the RTW engines. These options are saved in a file called rtconfig, which is located:

In Windows 7, in %USERPROFILE%\AppData\Roaming\Vistasource\RTW\
In Windows XP, in %USERPROFILE%\Application Data\Vistasource\RTW\

To edit these options using the Rtconfig Editor, select Vistasource → Settings → Rtconfig Editor. For an RTSHARE installation, this dialog box only contains the generic tab. A subset of the options on this tab are applicable to RTSHARE.

We strongly recommend that you consult a system administrator before editing any options.

Status Window Options

The behavior of the Status Window depends on your settings in the rtconfig file. For information regarding the content of this window, click Status Window.

Vistasource recommends using the Rtconfig editor - Generic Tab to modify these settings:

  1. Click Vistasource→Settings→Rtconfig Editor. The Rtconfig Editor dialog displays.
  2. Click on the Generic Tab, which will be the only tab available, unless you have an RTW Engine installed. The Status Window options are located in the right panel. These options correspond to those found in the rtconfig file. To edit the options directly in the rtconfig file, see Manually Editing the rtconfig File:
  3. Set your options (see details below).
  4. Click Save to file which saves your selections to the rtconfig file.
  5. Click Close.
Changes to the generic RTW options require a restart of Excel.

The following options apply to the rtconfig file settings “rtexcel:SWOption” and “rtexcel:SWDir”.

Full Debug Mode

Logs service start, warnings, errors, other status information and debugging information, and generates two files: xll.log and rts.log. By default, these files are created in the default installation directory. You can browse to change the log directory.

Information Mode

Logs service start, warnings and errors. The log file rts.log will only be created if a log directory is specified.

Errors Only Mode

Logs errors only. The log file rts.log will only be created if a log directory is specified.

Hidden Mode

Status Window is never displayed. If selected, the menu option Vistasource → Info → Show/Hide Status Window is disabled. However, the log file rts.log will still be created if a log directory is defined.

Log Directory

If Full Debug Mode is turned on, two log files are created; xll.log and rts.log. If no log directory is specified, the files are created in the RTW installation directory. To use a different log directory, specify one here.

If Information Mode, Errors Only Mode or Hidden mode is selected, and a log directory is specified, then the log file rts.log will be created.

To specify a directory, enter a directory in the Log Directory field or browse to a directory of your choice.

Status Window Promote Options

The following options refer to the “suppress_rt_status” and “rtexcel:SWpromote” rtconfig settings, which define when the status window is displayed. The default is Show Always.

Show Always

The status windows displays the first time a real-time request is made.

Suppress Always

The status window is not displayed, except when Vistasource → Info → Show/Hide Status Window is selected.

Show on Error Only

The status window only displays when an error occurs.

Promote on Error

The status window is promoted to the foreground when an error is encountered.

Option 'No Excel Event'

In addition to the Status Window options, the RTW option 'No Excel Event' can be modified according to your work environment on the RTSHARE clientside.

This option refers to the rtconfig file option

no_excel_events

which specifies whether RTW listens to certain Excel events. If you add RTW to an installation that also includes other add-ins listening to Excel events, these add-ins may not receive the events that they are waiting for if they are loaded after the RTW add-in is loaded.

If checked, RTW is no longer listening to Microsoft Excel events, thereby allowing other add-ins to properly trap the events. By default, this option is turned off.

If this option is selected, the RTW menu items will not always be enabled or disabled as appropriate, for example when there is no workbook in Microsoft Excel.

In addition, the following functionalities are affected if this option is selected:

RTW Wrapper Functions

With the No Excel Events option selected, the RTW wrapper functions no longer automatically calculate when the file is opened, but require a manual calculation to start them. See RTW Functions for more information regarding the wrapper functions.

WorkbookBeforeClose

The WorkbookBeforeClose event is used to prevent the RTW Add-ins from being unloaded when the user exits a work book, but then chooses to cancel the operation. With the No Excel Events option selected, this functionality is no longer available.

WorkbookBeforeSave

The WorkbookBeforeSave event is used to maintain any RTW settings that are saved with a workbook. With the No Excel Events option selected, this functionality is no longer available.