diff --git a/ChangeLog b/ChangeLog index b74ea99..4db9bff 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,23 @@ +2019-05-23 James Bell + + * NAMESPACE: export new function defaultAuthentication() + + * vignettes/rblpapi-intro.Rmd: document blpAutoAuthenticate + clarify host (blpConnect) vs hostname (blpAuthenticate) vs ip.address + clarify UUID, Application-Name, blpConnnect() and blpAuthenicate() + + * R/defaultAuthentication.R: New file + Add default identity object + * R/blpAuthenticate.R: add default identity object + documentation clarification host vs ip + * R/init.R: check for auto-auth, call as needed + + * R/bdh.R: support default identity object + * R/bdp.R: Idem + * R/bds.R: Idem + * R/portfolio.R.R: Idem + * R/subscribe.R: Idem + 2019-04-02 Dirk Eddelbuettel * DESCRIPTION (Version, Date): New release 0.3.10 diff --git a/NAMESPACE b/NAMESPACE index 39ed8bd..97c538f 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -5,6 +5,7 @@ importFrom("utils", "object.size", "packageVersion") export("blpConnect", "blpDisconnect", "defaultConnection", + "defaultAuthentication", "blpAuthenticate", "bdp", "bdh", diff --git a/R/bdh.R b/R/bdh.R index 0c4d9b1..3f21fd9 100644 --- a/R/bdh.R +++ b/R/bdh.R @@ -38,7 +38,9 @@ ##' being set) as well as a value. ##' @param verbose A boolean indicating whether verbose operation is ##' desired, defaults to \sQuote{FALSE} -##' @param identity An optional identity object. +##' @param identity An optional identity object as created by a +##' \code{blpAuthenticate} call, and retrived via the internal function +##' \code{defaultAuthentication}. ##' @param con A connection object as created by a \code{blpConnect} ##' call, and retrieved via the internal function ##' \code{defaultConnection}. @@ -82,7 +84,7 @@ ##' } bdh <- function(securities, fields, start.date, end.date=NULL, include.non.trading.days=FALSE, options=NULL, overrides=NULL, - verbose=FALSE, identity=NULL, con=defaultConnection(), + verbose=FALSE, identity=defaultAuthentication(), con=defaultConnection(), int.as.double=getOption("blpIntAsDouble", FALSE)) { if (class(start.date) == "Date") { start.date <- format(start.date, format="%Y%m%d") diff --git a/R/bdp.R b/R/bdp.R index 9b527a6..b5d5ea2 100644 --- a/R/bdp.R +++ b/R/bdp.R @@ -33,7 +33,9 @@ ##' being set) as well as a value. ##' @param verbose A boolean indicating whether verbose operation is ##' desired, defaults to \sQuote{FALSE} -##' @param identity An optional identity object. +##' @param identity An optional identity object as created by a +##' \code{blpAuthenticate} call, and retrived via the internal function +##' \code{defaultAuthentication}. ##' @param con A connection object as created by a \code{blpConnect} ##' call, and retrieved via the internal function ##' \code{defaultConnection}. @@ -52,7 +54,7 @@ ##' bdp("SPX Index", "INTERVAL_AVG", overrides=ovrd) ##' } bdp <- function(securities, fields, options=NULL, overrides=NULL, - verbose=FALSE, identity=NULL, con=defaultConnection()) { + verbose=FALSE, identity=defaultAuthentication(), con=defaultConnection()) { if (any(duplicated(securities))) stop("Duplicated securities submitted.", call.=FALSE) bdp_Impl(con, securities, fields, options, overrides, verbose, identity) } diff --git a/R/bds.R b/R/bds.R index 991019e..4e3d573 100644 --- a/R/bds.R +++ b/R/bds.R @@ -33,7 +33,9 @@ ##' being set) as well as a value. ##' @param verbose A boolean indicating whether verbose operation is ##' desired, defaults to \sQuote{FALSE} -##' @param identity An optional identity object. +##' @param identity An optional identity object as created by a +##' \code{blpAuthenticate} call, and retrived via the internal function +##' \code{defaultAuthentication}. ##' @param con A connection object as created by a \code{blpConnect} ##' call, and retrieved via the internal function ##' \code{defaultConnection}. @@ -53,7 +55,7 @@ ##' } bds <- function(security, field, options=NULL, overrides=NULL, verbose=FALSE, - identity=NULL, con=defaultConnection()) { + identity=defaultAuthentication(), con=defaultConnection()) { if (length(security) != 1L) stop("more than one security submitted.", call.=FALSE) if (length(field) != 1L) diff --git a/R/blpAuthenticate.R b/R/blpAuthenticate.R index b4fd7a4..6468834 100644 --- a/R/blpAuthenticate.R +++ b/R/blpAuthenticate.R @@ -21,37 +21,70 @@ ##' This function authenticates against the the Bloomberg API ##' ##' @title Authenticate Bloomberg API access -##' @param uuid A character variable with a unique user id token. If this -##' is missing the function will attempt to connect to bpipe using the connection. It -##' is assumed that an app_name was set. See blpConnect() for app_name information -##' @param host A character variable with a hostname, defaults to 'localhost' +##' @param uuid An optional character variable with a unique user id +##' token. If this is missing the function will attempt to connect +##' to B-PIPE or SAPI using the connection. It is assumed that an +##' app_name was set. See \code{blpConnect()} for app_name +##' information. Defaults to \code{getOption("blpUUID")} or NULL +##' @param host An optional character variable with a hostname. This is +##' the hostname of the machine where the user last authenticated. +##' Either host or ip.address should be provided for user/uuid +##' authentication. Note this is likely not the same 'host' used in +##' \code{blpConnect()}. Defaults to +##' \code{getOption("blpLoginHostname")} or "localhost" ##' @param ip.address An optional character variable with an IP address +##' for authentication. Usually the IP address where the uuid/user +##' last logged into the Bloomberg Terminal appication. Defaults to +##' \code{getOption("blpLoginIP")} or NULL, which will then lookup +##' the IP of the "host" option. ##' @param con A connection object as created by a \code{blpConnect} ##' call, and retrieved via the internal function. This is the only required -##' argument to authenticate a bpipe connection with a appName. -##' \code{defaultConnection}. -##' @return The returned object should be passed to subsequent data -##' calls via bdp(), bds(), etc. +##' argument to authenticate a B-PIPE connection with a appName. +##' Defaults to \code{defaultConnection}. +##' @param default A logical indicating whether this authentication should +##' be saved as the default, as opposed to returned to the +##' user. Default to \code{TRUE}. +##' @return In the \code{default=TRUE} case nothing is returned, and +##' this authentication is automatically used for all future calls which +##' omit the \code{identity} argument. Otherwise an authentication object is +##' returned which is required by all the accessor functions in the +##' package. (e.g. \code{bdp()} \code{bds()} \code{getPortfolio()} ##' @author Whit Armstrong and Dirk Eddelbuettel ##' @examples ##' \dontrun{ ##' blpConnect(host=blpHost, port=blpPort) +##' blpAuthenticate(uuid=blpUUID, ip=blpIP_address) +##' bdp("IBM US Equity", "NAME") +##' ##' blpid <- blpAuthenticate(uuid=blpUUID, ip=blpIP_address) ##' bdp("IBM US Equity", "NAME", identity=blpid) ##' } -blpAuthenticate <- function(uuid, host="localhost", ip.address, con=defaultConnection()) { - if(missing(uuid)) { - ## no UUID, assume BPIPE - authenticate_Impl(con, NULL, NULL) +blpAuthenticate <- function(uuid=getOption("blpUUID", NULL), + host=getOption("blpLoginHostname", "localhost"), + ip.address=getOption("blpLoginIP", NULL), + con=defaultConnection(), + default=TRUE) { + if(is.null(uuid)) { + ## no UUID, assume B-PIPE or SAPI with application ID + blpAuth <- authenticate_Impl(con, NULL, NULL) } else { + if ( (!is.null(ip.address)) && (!identical(host,"localhost")) ) { + warning("Both ip.address and host are set. Using ip.address.") } + ## have UUID, assume SAPI - if (missing(ip.address)) { + if (is.null(ip.address)) { ## Linux only ? cmd.res <- system(paste("host",host), intern=TRUE, ignore.stdout=FALSE, ignore.stderr=FALSE,wait=TRUE) ip.address <- strsplit(cmd.res,"address ")[[1]][2] } - authenticate_Impl(con, as.character(uuid), ip.address) + blpAuth <- authenticate_Impl(con, as.character(uuid), ip.address) } + ## if we're setting the silent/hidden default object, return nothing + ## else, return the object (keeps old behavior) + if (default) + .pkgenv$blpAuth <- blpAuth + else + return(blpAuth) } diff --git a/R/defaultConnection.R b/R/defaultConnection.R deleted file mode 100644 index fa4612a..0000000 --- a/R/defaultConnection.R +++ /dev/null @@ -1,49 +0,0 @@ - -## -## Copyright (C) 2015 Whit Armstrong and Dirk Eddelbuettel and John Laing -## -## This file is part of Rblpapi -## -## Rblpapi is free software: you can redistribute it and/or modify -## it under the terms of the GNU General Public License as published by -## the Free Software Foundation, either version 2 of the License, or -## (at your option) any later version. -## -## Rblpapi is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. -## -## You should have received a copy of the GNU General Public License -## along with Rblpapi. If not, see . - - -##' This function return the default connection object from the -##' package environment. If no default connection has been -##' established yet, an error message is shown, -##' -##' @title Return the default connection object -##' -##' @details For the connection object, the required arguments -##' \code{host} and \code{port} argument can be set via -##' \code{\link{options}}. In addition, if an additional option -##' \code{blpAutoConnect} is set to \sQuote{TRUE}, a connection is -##' established in the \code{.onAttach()} function and stored in the -##' package environment. This effectively frees users from having to -##' explicitly create such an object. Of course, the user can also -##' call \code{blpConnect} explicitly and store the connection object. -##' This helper function looks up the stored connection object and -##' returns it. In case no connection has been established, and error -##' message is shown. -##' @author Whit Armstrong and Dirk Eddelbuettel -##' @examples -##' \dontrun{ -##' con <- defaultConnection() -##' } -defaultConnection <- function() { - con <- .pkgenv$con - if (is.null(con)) - stop("No connection object has been created. Use 'blpConnect()' first.", - call.=FALSE) - con -} diff --git a/R/defaults.R b/R/defaults.R new file mode 100644 index 0000000..99d4a87 --- /dev/null +++ b/R/defaults.R @@ -0,0 +1,62 @@ + +## +## Copyright (C) 2019 Whit Armstrong and Dirk Eddelbuettel and John Laing +## +## This file is part of Rblpapi +## +## Rblpapi is free software: you can redistribute it and/or modify +## it under the terms of the GNU General Public License as published by +## the Free Software Foundation, either version 2 of the License, or +## (at your option) any later version. +## +## Rblpapi is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +## GNU General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with Rblpapi. If not, see . + + +##' These functions return the default connection/authentication objects +##' from the package environment. If no default connection/authentication +##' has been established yet, will return NULL. +##' In the case of authentication, if using a desktop/workstation +##' session, NULL will work fine. If using SAPI/Bpipe, you may need +##' to use blpAuthenticate() to create an authentication object. +##' +##' @title Return the default connection/authentication objects +##' +##' @details Required arguments can be set via \code{\link{options}}. See +##' \code{\link{blpConnect}} and \code{\link{blpAuthenticate}} for details. +##' In addition, if options \code{blpAutoConnect} and/or +##' \code{blpAutoAuthenticate} are set to \sQuote{TRUE}, a connection and/or +##' authentication is established in the \code{.onAttach()} function and +##' stored in the package environment. This effectively frees users from +##' having to explicitly create such objects. Of course, the user can also +##' call \code{blpConnect} and/or \code{blpAuthenticate} explicitly and +##' store the connection/authentication objects. These helper functions +##' look up the stored connection/authentications object and return them. +##' In case no connection has been established, an error message is shown. +##' In case no authentication has been established, NULL is returned. +##' (NULL is sufficent for Desktop API connections.) +##' +##' @author Whit Armstrong and Dirk Eddelbuettel +##' @examples +##' \dontrun{ +##' con <- defaultConnection() +##' blpid <- defaultAuthentication() +##' } +##' @rdname defaults +defaultConnection <- function() { + con <- .pkgenv$con + if (is.null(con)) + stop("No connection object has been created. Use 'blpConnect()' first.", + call.=FALSE) + con +} +##' @rdname defaults +defaultAuthentication <- function() { + blpAuth <- .pkgenv$blpAuth + blpAuth +} diff --git a/R/init.R b/R/init.R index c40ef66..6d99b65 100644 --- a/R/init.R +++ b/R/init.R @@ -26,7 +26,7 @@ " and run-time ", getRuntimeVersion(), ".")) packageStartupMessage(paste0("Please respect the Bloomberg licensing agreement ", "and terms of service.")) - + if (getOption("blpAutoConnect", FALSE)) { con <- blpConnect() if (getOption("blpVerbose", FALSE)) { @@ -35,5 +35,14 @@ } else { con <- NULL } + if (getOption("blpAutoAuthenticate", FALSE)) { + blpAuth <- blpAuthenticate() + if (getOption("blpVerbose", FALSE)) { + packageStartupMessage("Created and stored default authentication object.") + } + } else { + blpAuth <- NULL + } assign("con", con, envir=.pkgenv) + assign("blpAuth", blpAuth, envir=.pkgenv) } diff --git a/R/portfolio.R b/R/portfolio.R index 2b06fc6..bab7166 100644 --- a/R/portfolio.R +++ b/R/portfolio.R @@ -32,7 +32,9 @@ ##' being set) as well as a value. ##' @param verbose A boolean indicating whether verbose operation is ##' desired, defaults to \sQuote{FALSE} -##' @param identity An optional identity object. +##' @param identity An optional identity object as created by a +##' \code{blpAuthenticate} call, and retrived via the internal function +##' \code{defaultAuthentication}. ##' @param con A connection object as created by a \code{blpConnect} ##' call, and retrieved via the internal function ##' \code{defaultConnection}. @@ -45,7 +47,7 @@ ## TODO: examples. Do global portfolios exist so that examples will ## work for everyone? Otherwise I don't know how to do this. getPortfolio <- function(security, field, options=NULL, overrides=NULL, - verbose=FALSE, identity=NULL, + verbose=FALSE, identity=defaultAuthentication(), con=defaultConnection()) { if (length(security) != 1L) stop("more than one security submitted.", call.=FALSE) diff --git a/R/subscribe.R b/R/subscribe.R index 2ebf57a..e10a2bd 100644 --- a/R/subscribe.R +++ b/R/subscribe.R @@ -36,7 +36,9 @@ ##' @param options An optional named character vector with option ##' values. Each field must have both a name (designating the option ##' being set) as well as a value. -##' @param identity An optional identity object. +##' @param identity An optional identity object as created by a +##' \code{blpAuthenticate} call, and retrived via the internal function +##' \code{defaultAuthentication}. ##' @param con A connection object as created by a \code{blpConnect} ##' call, and retrieved via the internal function ##' \code{defaultConnection}. @@ -49,7 +51,7 @@ ##' fields=c("LAST_PRICE","BID","ASK"), ##' fun=function(x) print(str(x$data))) ##' } -subscribe <- function(securities, fields, fun, options=NULL, identity=NULL, con=defaultConnection()) { +subscribe <- function(securities, fields, fun, options=NULL, identity=defaultAuthentication(), con=defaultConnection()) { if (any(duplicated(securities))) stop("Duplicated securities submitted.", call.=FALSE) subscribe_Impl(con, securities, fields, fun, options, identity) } diff --git a/man/bdh.Rd b/man/bdh.Rd index 8222a11..88ccbd5 100644 --- a/man/bdh.Rd +++ b/man/bdh.Rd @@ -6,8 +6,9 @@ \usage{ bdh(securities, fields, start.date, end.date = NULL, include.non.trading.days = FALSE, options = NULL, overrides = NULL, - verbose = FALSE, identity = NULL, con = defaultConnection(), - int.as.double = getOption("blpIntAsDouble", FALSE)) + verbose = FALSE, identity = defaultAuthentication(), + con = defaultConnection(), int.as.double = getOption("blpIntAsDouble", + FALSE)) } \arguments{ \item{securities}{A character vector with security symbols in @@ -34,7 +35,9 @@ being set) as well as a value.} \item{verbose}{A boolean indicating whether verbose operation is desired, defaults to \sQuote{FALSE}} -\item{identity}{An optional identity object.} +\item{identity}{An optional identity object as created by a +\code{blpAuthenticate} call, and retrived via the internal function +\code{defaultAuthentication}.} \item{con}{A connection object as created by a \code{blpConnect} call, and retrieved via the internal function diff --git a/man/bdp.Rd b/man/bdp.Rd index 51b0c44..17a2047 100644 --- a/man/bdp.Rd +++ b/man/bdp.Rd @@ -5,7 +5,7 @@ \title{Run 'Bloomberg Data Point' Queries} \usage{ bdp(securities, fields, options = NULL, overrides = NULL, verbose = FALSE, - identity = NULL, con = defaultConnection()) + identity = defaultAuthentication(), con = defaultConnection()) } \arguments{ \item{securities}{A character vector with security symbols in @@ -24,7 +24,9 @@ being set) as well as a value.} \item{verbose}{A boolean indicating whether verbose operation is desired, defaults to \sQuote{FALSE}} -\item{identity}{An optional identity object.} +\item{identity}{An optional identity object as created by a +\code{blpAuthenticate} call, and retrived via the internal function +\code{defaultAuthentication}.} \item{con}{A connection object as created by a \code{blpConnect} call, and retrieved via the internal function diff --git a/man/bds.Rd b/man/bds.Rd index 113ad36..06a3905 100644 --- a/man/bds.Rd +++ b/man/bds.Rd @@ -5,7 +5,7 @@ \title{Run 'Bloomberg Data Set' Queries} \usage{ bds(security, field, options = NULL, overrides = NULL, verbose = FALSE, - identity = NULL, con = defaultConnection()) + identity = defaultAuthentication(), con = defaultConnection()) } \arguments{ \item{security}{A character value with a single security symbol in @@ -24,7 +24,9 @@ being set) as well as a value.} \item{verbose}{A boolean indicating whether verbose operation is desired, defaults to \sQuote{FALSE}} -\item{identity}{An optional identity object.} +\item{identity}{An optional identity object as created by a +\code{blpAuthenticate} call, and retrived via the internal function +\code{defaultAuthentication}.} \item{con}{A connection object as created by a \code{blpConnect} call, and retrieved via the internal function diff --git a/man/blpAuthenticate.Rd b/man/blpAuthenticate.Rd index 009110d..ed3022c 100644 --- a/man/blpAuthenticate.Rd +++ b/man/blpAuthenticate.Rd @@ -4,26 +4,46 @@ \alias{blpAuthenticate} \title{Authenticate Bloomberg API access} \usage{ -blpAuthenticate(uuid, host = "localhost", ip.address, - con = defaultConnection()) +blpAuthenticate(uuid = getOption("blpUUID", NULL), + host = getOption("blpLoginHostname", "localhost"), + ip.address = getOption("blpLoginIP", NULL), con = defaultConnection(), + default = TRUE) } \arguments{ -\item{uuid}{A character variable with a unique user id token. If this -is missing the function will attempt to connect to bpipe using the connection. It -is assumed that an app_name was set. See blpConnect() for app_name information} +\item{uuid}{An optional character variable with a unique user id +token. If this is missing the function will attempt to connect +to B-PIPE or SAPI using the connection. It is assumed that an +app_name was set. See \code{blpConnect()} for app_name +information. Defaults to \code{getOption("blpUUID")} or NULL} -\item{host}{A character variable with a hostname, defaults to 'localhost'} +\item{host}{An optional character variable with a hostname. This is +the hostname of the machine where the user last authenticated. +Either host or ip.address should be provided for user/uuid +authentication. Note this is likely not the same 'host' used in +\code{blpConnect()}. Defaults to +\code{getOption("blpLoginHostname")} or "localhost"} -\item{ip.address}{An optional character variable with an IP address} +\item{ip.address}{An optional character variable with an IP address +for authentication. Usually the IP address where the uuid/user +last logged into the Bloomberg Terminal appication. Defaults to +\code{getOption("blpLoginIP")} or NULL, which will then lookup +the IP of the "host" option.} \item{con}{A connection object as created by a \code{blpConnect} call, and retrieved via the internal function. This is the only required -argument to authenticate a bpipe connection with a appName. -\code{defaultConnection}.} +argument to authenticate a B-PIPE connection with a appName. +Defaults to \code{defaultConnection}.} + +\item{default}{A logical indicating whether this authentication should +be saved as the default, as opposed to returned to the +user. Default to \code{TRUE}.} } \value{ -The returned object should be passed to subsequent data -calls via bdp(), bds(), etc. +In the \code{default=TRUE} case nothing is returned, and +this authentication is automatically used for all future calls which +omit the \code{identity} argument. Otherwise an authentication object is +returned which is required by all the accessor functions in the +package. (e.g. \code{bdp()} \code{bds()} \code{getPortfolio()} } \description{ This function authenticates against the the Bloomberg API @@ -31,6 +51,9 @@ This function authenticates against the the Bloomberg API \examples{ \dontrun{ blpConnect(host=blpHost, port=blpPort) +blpAuthenticate(uuid=blpUUID, ip=blpIP_address) +bdp("IBM US Equity", "NAME") + blpid <- blpAuthenticate(uuid=blpUUID, ip=blpIP_address) bdp("IBM US Equity", "NAME", identity=blpid) } diff --git a/man/defaultConnection.Rd b/man/defaultConnection.Rd deleted file mode 100644 index c85647c..0000000 --- a/man/defaultConnection.Rd +++ /dev/null @@ -1,34 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/defaultConnection.R -\name{defaultConnection} -\alias{defaultConnection} -\title{Return the default connection object} -\usage{ -defaultConnection() -} -\description{ -This function return the default connection object from the -package environment. If no default connection has been -established yet, an error message is shown, -} -\details{ -For the connection object, the required arguments -\code{host} and \code{port} argument can be set via -\code{\link{options}}. In addition, if an additional option -\code{blpAutoConnect} is set to \sQuote{TRUE}, a connection is -established in the \code{.onAttach()} function and stored in the -package environment. This effectively frees users from having to -explicitly create such an object. Of course, the user can also -call \code{blpConnect} explicitly and store the connection object. -This helper function looks up the stored connection object and -returns it. In case no connection has been established, and error -message is shown. -} -\examples{ -\dontrun{ - con <- defaultConnection() -} -} -\author{ -Whit Armstrong and Dirk Eddelbuettel -} diff --git a/man/defaults.Rd b/man/defaults.Rd new file mode 100644 index 0000000..5bc7211 --- /dev/null +++ b/man/defaults.Rd @@ -0,0 +1,43 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/defaults.R +\name{defaultConnection} +\alias{defaultConnection} +\alias{defaultAuthentication} +\title{Return the default connection/authentication objects} +\usage{ +defaultConnection() + +defaultAuthentication() +} +\description{ +These functions return the default connection/authentication objects +from the package environment. If no default connection/authentication +has been established yet, will return NULL. +In the case of authentication, if using a desktop/workstation +session, NULL will work fine. If using SAPI/Bpipe, you may need +to use blpAuthenticate() to create an authentication object. +} +\details{ +Required arguments can be set via \code{\link{options}}. See +\code{\link{blpConnect}} and \code{\link{blpAuthenticate}} for details. +In addition, if options \code{blpAutoConnect} and/or +\code{blpAutoAuthenticate} are set to \sQuote{TRUE}, a connection and/or +authentication is established in the \code{.onAttach()} function and +stored in the package environment. This effectively frees users from +having to explicitly create such objects. Of course, the user can also +call \code{blpConnect} and/or \code{blpAuthenticate} explicitly and +store the connection/authentication objects. These helper functions +look up the stored connection/authentications object and return them. +In case no connection has been established, an error message is shown. +In case no authentication has been established, NULL is returned. +(NULL is sufficent for Desktop API connections.) +} +\examples{ +\dontrun{ + con <- defaultConnection() + blpid <- defaultAuthentication() +} +} +\author{ +Whit Armstrong and Dirk Eddelbuettel +} diff --git a/man/getPortfolio.Rd b/man/getPortfolio.Rd index 69acbb0..9c8a6bc 100644 --- a/man/getPortfolio.Rd +++ b/man/getPortfolio.Rd @@ -5,7 +5,8 @@ \title{Run 'Portfolio Data' Queries} \usage{ getPortfolio(security, field, options = NULL, overrides = NULL, - verbose = FALSE, identity = NULL, con = defaultConnection()) + verbose = FALSE, identity = defaultAuthentication(), + con = defaultConnection()) } \arguments{ \item{security}{A character value with a single security symbol in @@ -24,7 +25,9 @@ being set) as well as a value.} \item{verbose}{A boolean indicating whether verbose operation is desired, defaults to \sQuote{FALSE}} -\item{identity}{An optional identity object.} +\item{identity}{An optional identity object as created by a +\code{blpAuthenticate} call, and retrived via the internal function +\code{defaultAuthentication}.} \item{con}{A connection object as created by a \code{blpConnect} call, and retrieved via the internal function diff --git a/man/subscribe.Rd b/man/subscribe.Rd index efafc93..0b3c8da 100644 --- a/man/subscribe.Rd +++ b/man/subscribe.Rd @@ -4,8 +4,8 @@ \alias{subscribe} \title{Subscribe to streaming market data} \usage{ -subscribe(securities, fields, fun, options = NULL, identity = NULL, - con = defaultConnection()) +subscribe(securities, fields, fun, options = NULL, + identity = defaultAuthentication(), con = defaultConnection()) } \arguments{ \item{securities}{A character vector with security symbols in @@ -19,7 +19,9 @@ Bloomberg notation.} values. Each field must have both a name (designating the option being set) as well as a value.} -\item{identity}{An optional identity object.} +\item{identity}{An optional identity object as created by a +\code{blpAuthenticate} call, and retrived via the internal function +\code{defaultAuthentication}.} \item{con}{A connection object as created by a \code{blpConnect} call, and retrieved via the internal function diff --git a/vignettes/rblpapi-intro.Rmd b/vignettes/rblpapi-intro.Rmd index 7a28efc..24d5548 100644 --- a/vignettes/rblpapi-intro.Rmd +++ b/vignettes/rblpapi-intro.Rmd @@ -48,17 +48,85 @@ blpConnect() ``` which will connect to the Bloomberg backend. Default values for the IP -address (127.0.0.1) and port (8194) are used and can be overridden both as -function arguments and via global options `blpHost` and `blpPort`. Moreover, -if option `blpAutoConnect` is set to `TRUE`, this connection is done at -package load. +address (127.0.0.1) and port (8194) are used and can be overridden both +as function arguments and via global options `blpHost` and `blpPort`. +Moreover, if option `blpAutoConnect` is set to `TRUE`, this connection +is done at package load. -The resulting connection object is stored in a per-package environment providing -a default value. If needed it can be overridden in each accessor function. +The `appName` argument is optional and is for Application-Name +authentication (via B-PIPE or SAPI, see `blpAuthenticate()`). + +The resulting connection object is stored in a per-package environment +providing a default value. If needed it can be overridden in each +accessor function. As the connection object is being held onto, the `blpDisconnect()` -function is implemented as an empty function without side-effects. The internal -function `defaultConnection()` returns the current connection object. +function is implemented as an empty function without side-effects. The +internal function `defaultConnection()` returns the default connection +object. + +Default arguments and auto-connect can be set via `options()` + +```{R, eval=FALSE} +options("blpAutoConnect" = TRUE) +options("blpHost" = "x.x.x.x") +options("blpPort" = 8194) +options("blpAppName" = "yyy") +``` + +Optionally use +```{R, eval=FALSE} +blpAuthenticate() +``` + +`blpAuthenticate()` is usually needed for SAPI & B-PIPE sessions. DAPI +(Desktop) sessions do not usually require calling `blpAuthenticate()`, +and will function with a default NULL `identity` object. + +`blpAuthenticate()` connects to SAPI/B-PIPE server, and authenticates +via UUID/login-location or Application-Name. It can set a default +identity object for future calls (`bdp()`, `bds()`, etc). Or it can +return an identity object to explicitly pass to future calls. + +Additionally, if `blpAutoAuthenticate` is true, `blpAuthenticate()` will +be called at package load, storing a default identity object. The +internal function `defaultAuthentication()` returns the default identity +object. + +If needed, the default identity object can be overridden in each +accessor function. + +Default arguments and auto-authentication can be set via `options()` + +```{R, eval=FALSE} +options("blpAutoAuthenticate" = TRUE) +options("blpUUID" = "xxx") +options("blpLoginHostname" = "yyy") +options("blpLoginIP" = "z.z.z.z") + +``` + +For application-id authentication, first use `blpConnect()` with an +`appName` argument. Then call `blpAuthenticate()` with no arguments. + + +```{R, eval=FALSE} +blpConnect( ... , appName = "appName") +blpAuthenticate() +``` + +For UUID authentication, connect with `blpConnect()`, then +`blpAuthenticate()` with the UUID and last hostname/IP the UUID logged +in from. Usually this is the IP of your Bloomberg Terminal. For your +UUID, `IAM ` in Bloomberg Terminal. Note, if you supply both IP and +host arguments, the IP will be used, and the host ignored. + + +```{R, eval=FALSE} +blpConnect( ... ) +blpAuthenticate( uuid="UUID", ip.address="x.x.x.x") +``` + ### bdp: Bloomberg Data Point