Teradata R Package Function Reference | 17.00 - 17.00 - td_create_context

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.
Note: If a context already exists, this overwrites the previous context and removes all nonpersistent work tables created by the analytic functions, even though the connection parameters host, uid and database (i.e. default schema) are same for both the new connection object and the connection object from the previous context.

Usage

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

Arguments

`dsn`	Optional argument. Specifies the Data Source Name (DSN) for the ODBC connection. If this argument is not specified, relevant optional arguments are used to form the connection string. Note : Only applicable when the argument "dType" is 'ODBC' Default Value: NULL Types: character
`host`	Optional argument. Required when "dType" is 'NATIVE'. Specifies the fully qualified domain name or IP address of the Teradata Vantage System. Default Value: NULL Types: character
`uid`	Optional argument. Specifies the userId for connection. If not supplied, the userId present in DSN is used. Default Value: NULL Types: character
`pwd`	Optional argument. Specifies the password. If not supplied, the password present in DSN is used. Default Value: NULL Types: character Note: Encrypted passwords can also be passed to this argument, using Stored Password Protection feature. Examples section below demonstrates passing encrypted password to "td_create_context". More details on Stored Password Protection and how to generate key and encrypted password file can be found at StoredPasswordProtection
`tdWalletString`	Optional argument. Specifies the tdwallet reference string for the password required for the connection. If this is specified, the argument 'pwd' is ignored. Note : Only applicable when the argument "dType" is 'ODBC' Default Value: NULL Types: character
`database`	Optional argument. Specifies the database name to which connection is needed. If not supplied, the database name present in the DSN is used. Note : Only applicable when the argument "dType" is 'ODBC' Default Value: NULL Types: character
`temp.database`	Optional argument. 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 Value: NULL Types: character
`dType`	Required argument. Specifies the driver type. Permitted Values: ODBC, NATIVE Default Value: ODBC Types: character
`logmech`	Optional argument. Specifies the logon authentication method. Only applicable when "dType" is 'NATIVE'. Ignored when used with 'ODBC'. If the value is NULL, it takes default value used by the Teradata SQL driver. Permitted Values: TD2, LDAP, TDNEGO, KRB5 (for Kerberos) and JWT Default Value: NULL Types: character
`logdata`	Optional argument. Specifies additional data for the chosen logon authentication method. Only applicable when 'dType' is "NATIVE". Ignored when used with "ODBC". Note: If "logmech" is "JWT", then JWT token should be provided with the key 'jwt.token' in the named list of this argument. Default Value: NULL Types: Named list of characters
`...`	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.

Note:

tdplyr requires that the user has certain permissions on the user's default database or the initial default database specified using the "database" argument, or the temporary database when specified using "temp.database".
These permissions allow the user to:
1. Create tables to save results of Vantage analytic functions.
2. Create views in the background for objects of class "tbl_teradata" based on query.
It is expected that the user has the required permissions to create these objects in the database that will be used.
For views based on Vantage Analytic Functions, additional permissions may be required, which can be granted using:
GRANT EXECUTE FUNCTION ON SYSLIB ... WITH GRANT OPTION.
The access to the views created may also require issuing additional permissions depending on which database is used and which object the view being created is based on, which can be granted using:
GRANT SELECT ... WITH GRANT OPTION.

The "temp.database" and "database" parameters help determine which database is used by default to lookup for tables/views while creating objects of class "tbl_teradata" and which database is used to create all internal temporary objects, as shown in the table below.

	Scenario	tdplyr behaviour
1.	Both "database" and	Internal temporary objects are created in
	"temp.database" are provided	"temp.database", and database table/view lookup
		is done from "database".
2.	"database" is provided	Database table/view lookup and internal
	but "temp.database" is not	temporary objects are created in "database".
3.	"temp.database" is provided	Internal temporary objects are created in
	but "database" is not	"temp.database", database table/view lookup
		from the users default database.
4.	Neither "database" nor	Database table/view lookup and internal
	"temp.database" are provided	temporary objects are created in users
		default database.

Value

Invisibly returns an object of class: DBIConnection.

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>", dType = "NATIVE", logmech = "KRB5")

# Connection using JWT: Using JWT token to connect to Vantage.
td_create_context(host = "<dbcname>", dType = "NATIVE", logmech = "JWT",
                  logdata = list(jwt.token="<token_value>"))

# Example 5: Create context using encrypted password and key passed to "pwd" parameter.
# The password should be specified in the format mentioned below:
# ENCRYPTED_PASSWORD(file:<PasswordEncryptionKeyFileName>, file:<EncryptedPasswordFileName>)
# The PasswordEncryptionKeyFileName specifies the name of a file that contains the password
# encryption key and associated information.
# The EncryptedPasswordFileName specifies the name of a file that contains the encrypted password
# and associated information.
# Each filename must be preceded by the 'file:' prefix. The PasswordEncryptionKeyFileName must be
# separated from the EncryptedPasswordFileName by a single comma.
td_create_context(host = "<dbcname>", uid = "<tduser>",
                  pwd = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)",
                  dType = "NATIVE")

# Example 6: Create context using encrypted password in LDAP logon mechanism.
td_create_context(host = "<dbcname>", uid = "<tduser>",
                  pwd = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)",
                  dType = "NATIVE", logmech = "LDAP")

Teradata R Package Function Reference | 17.00 - 17.00 - td_create_context - Teradata R Package