|
1 | 1 | #' |
2 | | -#' @title Gets the names of a server-side list |
3 | | -#' @description Function to get the names of an object that is stored on the server-side. |
4 | | -#' @details This function is similar to the R function \code{names}. |
5 | | -#' In DataSHIELD the use of this function is restricted to objects of type list. |
6 | | -#' |
7 | | -#' Server function called: \code{namesDS} |
8 | | -#' @param x a character string specifying the name of the list. |
9 | | -#' @param datasources a list of \code{\link{DSConnection-class}} |
10 | | -#' objects obtained after login. If the \code{datasources} argument is not specified |
11 | | -#' the default set of connections will be used: see \code{\link{datashield.connections_default}}. |
| 2 | +#' @title Return the names of a list object |
| 3 | +#' @description Returns the names of a designated server-side list |
| 4 | +#' @details ds.names calls aggregate function namesDS. This function is similar to |
| 5 | +#' the native R function \code{names} but it does not subsume all functionality, |
| 6 | +#' for example, it only works to extract names that already exist, |
| 7 | +#' not to create new names for objects. The function is restricted to objects of |
| 8 | +#' type list, but this includes objects that have a primary class other than list but which |
| 9 | +#' return TRUE to the native R function {is.list}. As an example this includes |
| 10 | +#' the multi-component object created by fitting a generalized linear model |
| 11 | +#' using ds.glmSLMA. The resultant object saved on each server separately |
| 12 | +#' is formally of class "glm" and "ls" but responds TRUE to is.list(), |
| 13 | +#' @param xname a character string specifying the name of the list. |
| 14 | +#' @param datasources a list of \code{\link{DSConnection-class}} |
| 15 | +#' objects obtained after login that represent the particular data sources |
| 16 | +#' (studies) to be addressed by the function call. If the \code{datasources} |
| 17 | +#' argument is not specified the default set of connections will be used: |
| 18 | +#' see \code{\link{datashield.connections_default}}. |
12 | 19 | #' @return \code{ds.names} returns to the client-side the names |
13 | | -#' of a list stored on the server-side. |
14 | | -#' @author DataSHIELD Development Team |
| 20 | +#' of a list object stored on the server-side. |
| 21 | +#' @author Amadou Gaye, updated by Paul Burton for DataSHIELD development |
| 22 | +#' team 25/06/2020 |
15 | 23 | #' @export |
16 | 24 | #' @examples |
17 | 25 | #' \dontrun{ |
18 | | -#' |
| 26 | +#' |
19 | 27 | #' ## Version 6, for version 5 see the Wiki |
20 | | -#' |
| 28 | +#' |
21 | 29 | #' # connecting to the Opal servers |
22 | | -#' |
| 30 | +#' |
23 | 31 | #' require('DSI') |
24 | 32 | #' require('DSOpal') |
25 | 33 | #' require('dsBaseClient') |
26 | 34 | #' |
27 | 35 | #' builder <- DSI::newDSLoginBuilder() |
28 | | -#' builder$append(server = "study1", |
29 | | -#' url = "http://192.168.56.100:8080/", |
30 | | -#' user = "administrator", password = "datashield_test&", |
| 36 | +#' builder$append(server = "study1", |
| 37 | +#' url = "http://192.168.56.100:8080/", |
| 38 | +#' user = "administrator", password = "datashield_test&", |
31 | 39 | #' table = "CNSIM.CNSIM1", driver = "OpalDriver") |
32 | | -#' builder$append(server = "study2", |
33 | | -#' url = "http://192.168.56.100:8080/", |
34 | | -#' user = "administrator", password = "datashield_test&", |
| 40 | +#' builder$append(server = "study2", |
| 41 | +#' url = "http://192.168.56.100:8080/", |
| 42 | +#' user = "administrator", password = "datashield_test&", |
35 | 43 | #' table = "CNSIM.CNSIM2", driver = "OpalDriver") |
36 | 44 | #' builder$append(server = "study3", |
37 | | -#' url = "http://192.168.56.100:8080/", |
38 | | -#' user = "administrator", password = "datashield_test&", |
| 45 | +#' url = "http://192.168.56.100:8080/", |
| 46 | +#' user = "administrator", password = "datashield_test&", |
39 | 47 | #' table = "CNSIM.CNSIM3", driver = "OpalDriver") |
40 | 48 | #' logindata <- builder$build() |
41 | | -#' |
42 | | -#' connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") |
43 | | -#' |
44 | | -#' #Create a list in the server-side |
45 | | -#' |
| 49 | +#' |
| 50 | +#' connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") |
| 51 | +#' |
| 52 | +#' #Create a list in the server-side |
| 53 | +#' |
46 | 54 | #' ds.asList(x.name = "D", |
47 | 55 | #' newobj = "D.list", |
48 | 56 | #' datasources = connections) |
49 | | -#' |
| 57 | +#' |
50 | 58 | #' #Get the names of the list |
51 | | -#' |
52 | | -#' ds.names(x = "D.list", |
| 59 | +#' |
| 60 | +#' ds.names(xname = "D.list", |
53 | 61 | #' datasources = connections) |
54 | 62 | #' |
55 | | -#' |
| 63 | +#' |
56 | 64 | #' # clear the Datashield R sessions and logout |
57 | 65 | #' datashield.logout(connections) |
58 | 66 | #' |
59 | 67 | #' } |
60 | 68 | #' |
61 | | -ds.names <- function(x=NULL, datasources=NULL){ |
| 69 | +ds.names <- function(xname=NULL, datasources=NULL){ |
62 | 70 |
|
63 | 71 | # look for DS connections |
64 | 72 | if(is.null(datasources)){ |
65 | 73 | datasources <- datashield.connections_find() |
66 | 74 | } |
67 | 75 |
|
68 | | - if(is.null(x)){ |
| 76 | + if(is.null(xname)){ |
69 | 77 | stop("Please provide the name of the input list!", call.=FALSE) |
70 | | - }else{ |
71 | | - defined <- isDefined(datasources, x) |
72 | | - } |
73 | | - |
74 | | - # call the internal function that checks the input object is of the same class in all studies. |
75 | | - typ <- checkClass(datasources, x) |
76 | | - |
77 | | - # the input object must be a list |
78 | | - if(!('list' %in% typ)){ |
79 | | - stop("The input object must be a list.", call.=FALSE) |
80 | 78 | } |
81 | 79 |
|
82 | | - # call the server side function that does the job. |
83 | | - cally <- paste0('namesDS(', x, ')') |
84 | | - output <- DSI::datashield.aggregate(datasources, as.symbol(cally)) |
| 80 | + calltext<-call("namesDS", xname) |
| 81 | + output<-datashield.aggregate(datasources,calltext) |
85 | 82 | return(output) |
86 | | - |
87 | 83 | } |
| 84 | + |
| 85 | +#ds.names |
0 commit comments