Teradata R Package Function Reference - 16.20 - td_create_context - Teradata R Package

Teradata® R Package Function Reference

prodname
Teradata R Package
vrm_release
16.20
created_date
February 2020
category
Programming Reference
featnum
B700-4007-098K

Description

Use the td_create_context function to establish a connection to Teradata Vantage. The established connection will be set as the current context for all subsequent analytic functions. If a context already exists, this overwrites the previous context and removes all nonpersistent work tables created by the analytic functions.

Usage

td_create_context(
  dsn = NULL,
  host = NULL,
  uid = NULL,
  pwd = NULL,
  tdWalletString = NULL,
  database = NULL,
  temp.database = NULL,
  dType = "odbc",
  logmech = NULL,
  ...
)

Arguments

dsn

Specifies the Data Source Name (DSN) for the ODBC connection. If not supplied, relevant optional arguments are used to form the connection string. Only applicable when dType is "odbc".
Default: NULL
Types: character

host

Specifies the fully qualified domain name or IP address of the Teradata Vantage System. This is a required argument when dType is "native".
Default: NULL
Types: character

uid

Specifies the userId for connection. If not supplied, the userId present in DSN is used.
Default: NULL
Types: character

pwd

Specifies the password. If not supplied, the password present in DSN is used.
Default: NULL
Types: character

tdWalletString

Specifies the tdwallet reference string for the password required for the connection. If this is specified, the pwd is ignored. Only applicable when dType is "odbc".
Default: NULL
Types: character

database

Specifies the database name to which connection is needed. If not supplied, the database name present in the DSN is used. Only applicable when dType is "odbc".
Default: NULL
Types: character

temp.database

Some of the functions need to create temporary database objects(table / view) for processing data. Such objects are garbage collected at the end of the session. If a user wants to specifically use a known database for temporary objects, the database name can be specified using this argument.
Make sure the user has privilege to create objects in this database, otherwise the functions that create temporary objects will fail.
If this argument is not supplied, default database of the connection is used for temporary objects. To get the temporary database name, use function td_get_context().
Default: NULL
Types: character

dType

Specifies the driver type.
Permitted Values: odbc for ODBC driver, native for Teradata SQL driver (teradatasql R package)
Default: odbc
Types: character

logmech

Specifies the logon authentication method. Only applicable when dType is "native". Ignored when used with odbc. Multiple values are not allowed. If the value is NULL, it takes default value used by the Teradata SQL driver.
Permitted Values: TD2, LDAP, TDNEGO, KRB5 for Kerberos
Default: NULL
Types: character

...

Optional arguments as applicable to the corresponding driver.

Details

You should make sure that Teradata driver is properly installed and configured on the system where this function is being invoked.
When logmech argument (other than TD2 which is the current default logon mechanism) is used, you should setup the client with relevant security mechanisms.

Value

Invisibly returns an object of class: DBIConnection.

See Also

td_remove_context, td_set_context, td_get_context

Examples

# Note: The default database in the connection is used as the temporary 
# database. For retrieving and removing context, check td_get_context
# and td_remove_context respectively. 

# Create a context (ODBC connection) specifying a dsn name.
con <- td_create_context(dsn = "TeradataDSN")

# Example 1: Create a context (ODBC connection) with a different temporary database.
td_create_context(dsn = "TeradataDSN", temp.database = "database_for_transient_objects")

# Example 2: Create a context (ODBC connection) using TdWallet.
td_create_context(dsn = "TeradataDSN", tdWalletString = "password_tduser")

# Example 3: Create a context using the Teradata SQL Driver. Note that the argument 'logmech' is
# not specified. Connection is established with default logon mechanism.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "native")

# Example 4: Create a context using the Teradata SQL Driver with various logon mechanisms.

# Connection using TD2: The Teradata 2(TD2) mechanism provides authentication using a Vantage 
# database username and password.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "native", 
                  logmech = "TD2")

# Connection using TDNEGO: TDNEGO is a security mechanism that automatically determines the 
# actual mechanism required, based on policy, without user's involvement. The actual mechanism 
# is determined by the TDGSS server configuration and the security policy's mechanism 
# restrictions.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "native", 
                  logmech = "TDNEGO")

# Connection using LDAP: LDAP is a directory-based mechanism. User logs on to a Vantage database 
# with a directory username and password and is authenticated by the directory.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "native", 
                  logmech = "LDAP")
                  
# Connection using KRB5: KRB5 is a directory-based mechanism. User logs on to a Vantage database 
# with a domain username and password and is authenticated by Kerberos (KRB5 or SPNEGO mechanism).
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "native", 
                  logmech = "KRB5")