REDCapR (version 0.9.8)

retrieve_token: Read a token from a (non-REDCap) database.

Description

This function will soon be deprecated; please transition to retrieve_token_mssql(). These functions are not essential to calling the REDCap API, but instead are functions that help manage tokens securely.

Usage

retrieve_token_mssql(project_name, dsn = NULL, channel = NULL)

Arguments

project_name

The friendly/shortened name given to the REDCap project in the MSSQL table. Notice this isn't necessarily the same name used by REDCap. Required

dsn

A DSN on the local machine that points to the desired MSSQL database. Required.

channel

An optional connection handle as returned by RODBC::odbcConnect(). See Details below. Optional.

Value

The token, which is a 32 character string.

Details

If no channel is passed, one will be created at the beginning of the function, and destroyed at the end. However if a channel is created, it's the caller's responsibility to destroy this resource. If you're making successive calls to the database, it might be quicker to create a single channel object and batch the calls together. Otherwise, the performance should be equivalent.

If you create the channel object yourself, consider wrapping calls in a base::tryCatch block, and closing the channel in its finally expression; this helps ensure the expensive database resource isn't held open unnecessarily. See the internals of retrieve_token_mssql() for an example of closing the channel in a tryCatch block.

If the database elements are created with the script provided in package's 'Security Database' vignette, the default values will work.

Examples

# NOT RUN {
library(REDCapR) #Load the package into the current R session.
# }
# NOT RUN {
# ---- SQL Server Example ----------------------------
# Rely on `retrieve_token()` to create & destory the channel.
dsn      <- "TokenSecurity"
project  <- "DiabetesSurveyProject"
token    <- retrieve_token(dsn=dsn, project_name=project)

# Create & close the channel yourself, to optimize repeated calls.
dsn      <- "TokenSecurity"
project1 <- "DiabetesSurveyProject1"
project2 <- "DiabetesSurveyProject2"
project3 <- "DiabetesSurveyProject3"

channel  <- RODBC::odbcConnect(dsn=dsn)
token1   <- retrieve_token(dsn=dsn, project_name=project1)
token2   <- retrieve_token(dsn=dsn, project_name=project2)
token3   <- retrieve_token(dsn=dsn, project_name=project3)
RODBC::odbcClose(channel)
# }