sdcConnect
Import Data from a Spotfire Data Connection

### Description

Imports data from a Spotfire Data Connection.

### Usage

    sdcConnect(url, user="", password="")
    sdcGetInfo(conn, path)
    sdcGetData(conn, path, ..., parameters=NULL,
               view=NULL, maxRows=NULL, file=NULL)

### Arguments

url | a character string specifying the URL of a Spotfire Web Player to access. This is normally a full URL; for example, "http://srvtest04/SpotfireWeb".
user | a character string specifying the user name to log in to the Spotfire Web Player.
password | a character string specifying the user password to log in to the Spotfire Web Player.
conn | an object returned by sdcConnect that specifies the Spotfire Web Player to access.
path | a character string specifying the path to a data connection on the server.
... | Any number of named parameters specified to access the data connection.
parameters | If this argument is given, it is used to specify the parameter names and values, rather than the contents of the ... arguments. This argument allows using parameters with the same names as the arguments to sdcGetData.
view | a character string specifying the view name of the data connection. This must be specified only if the data connection has more than one view.
maxRows | an integer giving the maximum number of rows to retrieve. If it is NULL or less than one, all of the data rows are retrieved. This value can be ignored for some types of Spotfire data connections.
file | if this argument is given, it must be a file name where the retrieved data is stored in the SBDF file format. If it is not given, the retrieved data is returned as a data.frame.

### Details

These functions support importing data from a Spotfire Data Connection or an Information Link by accessing a Spotfire Web Player server.

- sdcConnect connects to a Spotfire Web Player when given the URL to the server and an optional user name and password. It returns an object that identifies the server. If it cannot find the server or log in to it, an error is generated. After logging in to a Spotfire Web Player, the login becomes invalid after some period of time; therefore, the functions to read data from a Spotfire Web Player automatically re-establish the connection if necessary, using the same user name and password.

- sdcGetInfo queries the Web Player for information about a given data connection. The data connection is specified by path, giving the folder, the subfolders, and the file name of a data connection in the Spotfire Web Player library. For example, the path to a top-level file might be "/OneFile", and the path to a file in the folder MyFolder might be "/MyFolder/MyFile".

  sdcGetInfo returns a SpotfireDataConnectionInfo object, which has a print method that displays information about the given data connection necessary to access its data. This information includes one or more named "views" included for the data connection, as well as "parameters" that must be specified for each view. See the Example section for a demonstration of how this information is printed.

  If a data connection has more than one view, you must specify the view to use (by giving its view name) when retrieving its data. If a data connection has only one view, the view name does not need to be specified.

  A data connection view has zero or more named parameters that you can specify when retrieving its data. When you print the object returned by sdcGetInfo, note that the parameters are printed as a data.frame with the following columns:

  Name | The parameter name.
  DataType | The type of data expected for the parameter.
  Required | If TRUE, then this parameter must be specified.
  AllowMultipleValues | If TRUE, then this parameter can have more than one value specified.
  IsRangeValues | If TRUE, then specify this parameter as two numeric values: a lower range and an upper range value.

  A SpotfireDataConnectionInfo object is implemented as a list with the following elements:

  server | The URL to the server.
  path | The specified path to the data.
  LibraryId | An ID used to specify the dataset to the server.
  Views | A list of SpotfireDataConnectionView objects describing each of the views.

  A SpotfireDataConnectionView object is implemented as a list with the following elements:

  ViewName | The name of the view.
  RequireDatabaseCredentials | A logical value that is true if the view requires specifying database credentials.
  Parameters | A data.frame describing the parameters, with the columns described above, as well as an additional Id column used to specify the parameter to the server.

- sdcGetData retrieves the data from a given data connection path.
  - The path argument specifies the path on the server.
  - The view argument specifies the view name. (This is need only if there is more than one view).
  - The ... arguments are named arguments, giving the values of the parameters. Parameters with multiple values are specified by giving a vector containing the values.
  - The file argument to sdcGetData can be used to store the retrieved data as an SBDF file. The data in the file can be read by calling importDataFromSBDF, which has arguments for specifying which data columns and rows to import.

Value

sdcConnect | returns a SpotfireDataConnection object that identifies a particular Spotfire Web Player.
sdcGetInfo | returns a SpotfireDataConnectionInfo object containing information about the views and parameters of a specified data connection.
sdcGetData | returns a data.frame with the retrieved data (unless file is specified, in which case it returns NULL).

See Also
importDataFromSBDF.
Examples

    ## Not run:
    # Connect to a Web Player
    conn <- sdcConnect("http://myServer/SpotfireWeb", "myname", "mypassword")
    # Retrieve and print info about a data connection
    print(sdcGetInfo(conn, "/MyFolder/SalesWithParameters"))
    ## Spotfire data connection info
    ##   server: http://myServer/SpotfireWeb
    ##   path: /MyFolder/SalesWithParameters
    ##   1 view
    ##
    ## Spotfire data connection view: "SalesWithParameters"
    ##   Parameters:
    ##           Name   DataType Required AllowMultipleValues IsRangeValues
    ## 1       Region     String     TRUE                TRUE         FALSE
    ## 2  Sales Total SingleReal     TRUE                TRUE          TRUE
    ## 3 ShipContains     String     TRUE               FALSE         FALSE
    # Retrieve data with specified parameters,
    # where parameter "Sales Total" specifies the range 100 to 300,
    # and the other parameters are strings.
    salesData <- sdcGetData(conn, "/MyFolder/SalesWithParameters",
         Region="WEST", "Sales Total"=c(100,300), ShipContains="SMALL")

    ## End(Not run)

Package SpotfireData version 6.1.5-18
Package Index