Teradata Package for R Function Reference | 17.00 - td_create_context - Teradata Package for R - Look here for syntax, methods and examples for the functions included in the Teradata Package for R.

Create a Context to run analytic functions on Teradata Vantage

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 non-persistent 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.
When logmech argument (other than TD2 which is the current default logon mechanism) is used, you should setup the client with relevant security mechanisms.
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 "temp.database" are provided	Internal temporary objects are created in "temp.database", and database table/view lookup is done from "database".
2.	"database" is provided but "temp.database" is not	Database table/view lookup and internal temporary objects are created in "database".
3.	"temp.database" is provided but "database" is not	Internal temporary objects are created in "temp.database", database table/view lookup from the users default database.
4.	Neither "database" nor "temp.database" are provided	Database table/view lookup and internal temporary objects are created in users default database.

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,
  log = 0,
  ...
)

Arguments

`dsn`	*(Deprecated)* 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 user Id 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 the function. More details on Stored Password Protection and how to generate key and encrypted password file can be found at Stored Password Protection.
`tdWalletString`	*(Deprecated)* 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. If not supplied and "dType" is 'ODBC', then the database name present in the DSN is used. "dType" is 'NATIVE', then database name associated with the user specified in the argument "uid" is used. 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 *(Deprecated)*, NATIVE Default Value: ODBC Types: character
`logmech`	Optional argument. Specifies the logon authentication method. If the value is NULL, it takes default value used by the Teradata SQL Driver for R. Note: Only applicable when "dType" is 'NATIVE'. Ignored when used with 'ODBC'. 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. Note: Only applicable when "dType" is 'NATIVE'. Ignored when used with 'ODBC'. 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
`log`	Optional argument. Specifies the controls for debug logging. The 1-bit governs function and method tracing, the 2-bit governs debug logging, the 4-bit governs transmit and receive message hex dumps, and the 8-bit governs timing. Default Value: 0 Types: integer Examples: If the user wants only debug logging, 2 (in bit representation: 0010) should be used as argument value. If the user wants timing and debug logging, 10 (in bit representation: 1010) should be used as argument value.
`...`	Specifies the additional connection parameters that are passed to Teradata SQL Driver for R. Please refer to Connection Parameters of the driver. Note: When the type of a connection parameter is integer or boolean (eg: lob_support etc,.), pass integer or boolean value, instead of quoted integer or quoted boolean as suggested in the documentation.

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.

# Example 1: 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 2: 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 3: 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 4: 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")

# Example 5: Create context using 'ansi' mode with log value set to 8 and lob_support disabled.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "NATIVE",
                  tmode = 'ansi', log = 8, lob_support = FALSE)

# Example 6: Create context with 'database' parameter.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "NATIVE",
                  database = '<schema_name>')

Teradata Package for R Function Reference | 17.00 - td_create_context - Teradata Package for R - Look here for syntax, methods and examples for the functions included in the Teradata Package for R.