ds.ls.Rdcreates a list of the names of all of the objects in a specified serverside environment.
ds.ls(
search.filter = NULL,
env.to.search = 1L,
search.GlobalEnv = TRUE,
datasources = NULL
)character string (potentially including * symbol) specifying the filter
for the object name that you want to find in the enviroment. For more information see Details.
an integer (e.g. in 2 or 2L format) specifying the position
in the search path of the environment to be explored. 1L is the current active analytic
environment on the server-side and is the default value of env.to.search.
For more information see Details.
Logical. If TRUE, ds.ls will list all objects
in the .GlobalEnv R environment on the server-side. If FALSE and if env.to.search is also
set as a valid integer, ds.ls will list all objects in the server-side R environment
identified by env.to.search in the search path.
For more information see Details.
a list of DSConnection-class
objects obtained after login. If the datasources argument is not specified
the default set of connections will be used: see datashield.connections_default.
ds.ls returns to the client-side a list containing:
(1) the name/details of the server-side R environment which ds.ls has searched;
(2) a vector of character strings giving the names of
all objects meeting the naming criteria specified by the argument search.filter in this
specified R server-side environment;
(3) the nature of the search filter string as it was applied.
When running analyses one may want to know the objects already generated. This request is not disclosive as it only returns the names of the objects and not their contents.
By default, objects in DataSHIELD's Active Serverside Analytic Environment (.GlobalEnv)
will be listed. This is the environment that contains all of the objects that server-side DataSHIELD
is using for the main analysis or has written out to the server-side during the process
of managing or undertaking the analysis (variables, scalars, matrices, data frames, etc).
The environment to explore is specified by the argument env.to.search (i.e. environment
to search) to an integer value. The default environment
which R names as .GlobalEnv is set by specifying env.to.search = 1 or 1L
(1L is just an explicit way of writing the integer 1).
If the search.GlobalEnv argument is set to TRUE the env.to.search parameter
is set to 1L regardless of what value it is set in the call
or if it is set to NULL.
So, if search.GlobalEnv is set to TRUE, ds.ls will automatically
search the .GlobalEnv R environment on the server-side which contains all of the
variables, data frames and other objects read in at the start of the analysis,
as well as any new objects of any sort created using DataSHIELD assign functions.
Other server-side environments contain other
objects. For example, environment 2L contains the functions loaded via the native R
stats package and 6L contains the standard list of datasets built into R. By default
ds.ls will return a list of ALL of the objects in the environment specified by the
env.to.search argument but you can specify search filters including * wildcards
using the search.filter argument.
In search.filter you can use the symbol * to find all the object that contains
the specified characters. For example, search.filter = "Sd2*"
will list the names of all objects in the specified
environment with names beginning capital S, lower case d and number 2.
Similarly, search.filter="*.ID" will return all objects with names ending with .ID,
for example Study.ID.
If a value is not specified for the search.filter argument or it is set as NULL, the names of
all objects in the specified environment will be returned.
Server function called: lsDS.
if (FALSE) { # \dontrun{
## Version 6, for version 5 see the Wiki
# connecting to the Opal servers
require('DSI')
require('DSOpal')
require('dsBaseClient')
builder <- DSI::newDSLoginBuilder()
builder$append(server = "study1",
url = "http://192.168.56.100:8080/",
user = "administrator", password = "datashield_test&",
table = "CNSIM.CNSIM1", driver = "OpalDriver")
builder$append(server = "study2",
url = "http://192.168.56.100:8080/",
user = "administrator", password = "datashield_test&",
table = "CNSIM.CNSIM2", driver = "OpalDriver")
builder$append(server = "study3",
url = "http://192.168.56.100:8080/",
user = "administrator", password = "datashield_test&",
table = "CNSIM.CNSIM3", driver = "OpalDriver")
logindata <- builder$build()
connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D")
#Example 1: Obtain the list of all objects on a server-side environment
ds.ls(datasources = connections)
#Example 2: Obtain the list of all objects that contain "var" character in the name
#Create in the server-side variables with "var" character in the name
ds.assign(toAssign = "D$LAB_TSC",
newobj = "var.LAB_TSC",
datasources = connections)
ds.assign(toAssign = "D$LAB_TRIG",
newobj = "var.LAB_TRIG",
datasources = connections)
ds.assign(toAssign = "D$LAB_HDL",
newobj = "var.LAB_HDL",
datasources = connections)
ds.ls(search.filter = "var*",
env.to.search = 1L,
search.GlobalEnv = TRUE,
datasources = connections)
# clear the Datashield R sessions and logout
datashield.logout(connections)
} # }