Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
The process of logging on via BTEQ is, at its simplest, triggered by issuing a LOG
ON command. This causes a request to get sent to the indicated Teradata Database
for one or more sessions to get established in order that the specified user en
tity will then be able to submit SQL statements. For purposes of this article, t
he information needed for uniquely identifying the user as well as the database
will be collectively referred to as the Basic Logon Elements. These are the attr
ibutes that, on their own, are generally sufficient for employing the simpler de
fault authentication mechanism TD2, which most typically relies solely on provis
ion of a LOGON command.
The four basic attributes are:
TDP Identifier
User Identifier
Password Value
Account Identifier
The more advanced forms of logging on , though, also require identification of a sp
ecific authentication mechanism such as LDAP or SSO. External authentication all
ows network attached users to be authenticated by an external agent rather than
by a Teradata Database. You must properly configure the Teradata Database to sup
port external authentication and must select a mechanism that supports it. Chann
el attached users cannot use external authentication.
The information needed for specifying which mechanism to use, as well as any arg
ument data it might need, will be collectively referred to as the Advanced Logon
Elements. Specifying information about which non-default mechanism to use requi
res use of BTEQ s LOGMECH and LOGDATA commands.
The two advanced attributes are:
Mechanism Name
Mechanism Data
To handle a user s LOGON request, BTEQ takes all of the basic and advanced element
s and passes their information along to CLI. CLI will work with TeraGSS as neede
d to authenticate the user based on the user-specified or default security mecha
nism and then handles requesting the required connections. When the logon is suc
cessful, the Teradata Database will have assigned unique numbers to all the sess
ions associated with the logged on user. The following is a graphical representa
tion of how the logon string and logon mechanism information gets routed for the
purpose of authenticating a user. The logon elements are shown using their comm
only used nicknames.
Flow of LOGON request
Basic Attributes
TDP Identifier
The TDP Identifier element, also known as TdpId value, identifies the target Ter
adata Database system which the user wants to log on to. The value can be compri
sed of any combination of letters and numbers. For Workstation BTEQ, up to 258 c
haracters may be used in quoted or non-quoted form. For Mainframe BTEQ, only an
assigned name string of up to 8 characters can be used. The term TdpId comes fro
m the historical timeframe when BTEQ was first released and was only being built
for execution via mainframe systems. Use of this term was carried over for all
BTEQ build flavors, but is also referred to as host name or database name .
So for Mainframe BTEQ, the TdpId value actually identifies the assigned
the Teradata Director Program or TDP client-side subsystem which will
unication with the target database. A TDP establishes sessions with the
Database and routes user requests between the client and the database.
name of
provide comm
Teradata
But for
Workstation BTEQs, the TdpId is actually a value that must resolve down to an IP
address corresponding to a server-side Teradata Gateway. The value given may re
present a host name or an actual address -- using full internet IPv4 or IPv6 (as
of TTU 13.10) formats.
These are the valid IPv4/IPv6 address formats supported by BTEQ:
<IPv4 address>
<IPv4 address>:<port number>
[<IPv6 address>]
[<IPv6 address>]:<port number>
And here are some examples of validly formatted Workstation BTEQ TdpId values ex
pressed as addresses:
Internet format
-- mytdpid.td.teradata.com
IPv4 format with port -- 111.122.133.144:1025
IPv6 format
-- [2002:9941:abcd::cebf]
What does this all mean for Jane? Well, what her DBA explained to her is that th
eir company s production Teradata Database system is called tdprod and their test sy
stem is called tdtest . The names were coined from the TdpId values used to logon s
essions via network-attached BTEQ (meaning using Windows BTEQ or one of the supp
orted UNIX or Linux BTEQs). She was told she shouldn t need to quote the names or
alternatively use any direct addressing formats since their DNS setup will enabl
e CLI to lookup their necessary addresses by name. If she wants to use channel-a
ttached BTEQ (aka z/OS BTEQ), however, she s been told to use TDPS as the TdpId for
tdprod and TDTS as the TdpId for tdtest.
User Identifier
The User Identifier value, also known as UserId, identifies the name of an exist
ing user object to establish sessions for. Although BTEQ will accept (as of TTU
13.10) up to 2000 multi-byte characters for this value, the maximum allowed size
is determined by the version of the Teradata Database system that was used to c
reate the object name. The database also imposes rules about which characters ca
n be used in the UserId value. The only rule imposed by BTEQ is that double quot
es must surround a UserId value containing whitespace or comma characters.
So what is Jane s UserId? Well, her DBA created three new user objects for her. On
e on tdtest called Doe, Jane and two on tdprod called jd1 and jd2 . The two tdprod use
s were created with different roles. The jd1 user would allow her to add new sal
es data and jd2 would allow her to access historical sales data. She was also to
ld she would need to get into the habit of always quoting her UserId value for a
logon to tdtest since it contains the comma and space characters.
Password Value
The Password value is a character string that must match the password string ass
igned to the associated UserId. The same object name format rules that apply to
UserId values also apply to Password values. Double quotes may need to be used t
o enable BTEQ to correctly parse values supplied via LOGON command arguments.
So what are Jane s Passwords? Well, her DBA created a default value of sqlgood for h
er tdtest UserId but told her she would instead be using her network password fo
r authentication when logging on to tdprod.
Account Identifier
The Account Identifier value, also known as AcctId, is an optional quoted charac
ter string that associates the established sessions with an accounting group to
enable their resource utilization to be monitored and/or prioritized. Like UserI
d and Password, AcctId values are subject to the database s rules for object names
. If not specified, a default account value associated with the user object will
be used.
So what is Jane s AcctId? Well, her DBA told her she can omit it entirely when log
ging on to tdtest. The default value of pitstop will be assumed. However, when she
is going to be executing long-running queries on tdprod she should explicitly s
upply a value of adhoc .
Advanced Attributes
Mechanism Name
The Mechanism Name, also known as the LogMech value, identifies the name of the
security mechanism which will need to define the security context under which th
e established sessions will operate. If not specified, the logon will proceed us
ing the designated default mechanism. NTLM , KRB5 and LDAP are all examples of valid L
gMech values. The names are not case-sensitive and can be up to 8 characters in
length.
When any value other than TD2 is supplied, the definition of the basic elements
UserId and Password must be broadened as their values may then represent mapped
user credentials managed not by a Teradata Database but rather by an external au
thentication mechanism.
The values are still being used to determine which underlying Teradata Database
user object to establish sessions for. But the user names may actually be differ
ent.
Jane s DBA has informed her that she must use TD2 authentication (the out-of-box d
efault) when accessing tdtest and must use LDAP (the site default) when accessin
g either of her tdprod UserIds.
Mechanism Data
Mechanism Data, also known as LogData, is a character string that is used to sup
ply the non-Teradata-managed user credentials that are needed by the external au
thentication mechanisms being used.
This is where things become a bit more complex for Jane. Her DBA explained that
since she has a choice of two UserIds on tdprod -- and has to use LDAP authentic
ation to logon sessions using them -- that she would need to supply her network
user credentials as well as qualify which tdprod UserId she wants to use via Log
Data when she logs on. The specific format she would need to use for the string
would be as follows:
<NetworkUserId>@@<NetworkPassword> user=<TeradataUserId>
Jane s network user name is JaneDoe and her associated current password is bulbs2flow
ers reflecting her current penchant for gardening. So the string she would need t
o enter to logon to her tdprod jd1 UserId would need to be as follows:
JaneDoe@@bulbs2flowers user=jd1
Commands & Settings
BTEQ provides several other logon-related commands besides LOGMECH, LOGDATA, and
LOGON. These additional commands, which must be used prior to actually using th
e LOGON command (directly or tacitly), provide the ability to:
Establish multiple Teradata Database sessions
Make BTEQ s interactive mode smarter
Make BTEQ s LOGON command syntax shorter
New BTEQ users need to form the habit of always considering whether there will b
e a Teradata Database performance advantage to using multiple sessions with ever
y logon they make. So although the scope for this article does not include how t
o request all the various types of sessions, it was decided that it should inclu
akes switching back and forth between tdprod and tdtest easier within the same B
TEQ process. But, more likely, she will find that she prefers to use SET TDP whe
n running RUN files or batch-driven scripts that contain pre-written LOGON state
ments and SQL requests which she does not want to have to alter as much to test
them out on tdtest before running them on tdprod. Using Windows BTEQ interactive
ly, here s what Jane would see based on trying out the command and then using SHOW
CONTROLS to verify the result:
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.show controls tdp
[SET] TDP = tdprod
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.set tdp tdtest
New TDP id: tdtest
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.show controls tdp
[SET] TDP = tdtest
LOGONPROMPT Command
The Workstation-BTEQ-only SET LOGONPROMPT command, also known as the LOGONPROMPT
setting, can be set to OFF or ON (its default). Setting it to OFF serves two pu
rposes with regard to using external authentication mechanisms as follows:
For logon scenarios where UserId and Password values do not actually need to be
supplied, it is used to instruct BTEQ to purposefully suppress prompts and warni
ngs that would normally occur for a user who incompletely supplies LOGON command
arguments when using standard TD2 authentication when using BTEQ in interactive
mode.
For interactive as well as batch modes, it allows use of the LOGON command to be
treated as an optional action (rather than a required action) prior to submitti
ng SQL. When OFF, BTEQ submits a tacit logon request to CLI when it encounters a
n SQL request being submitted to its input stream without any sessions having be
en first logged on.
Syntax:
LOGONPROMPT command syntax diagram
When would Jane need to use this command? Well, since she is going to use extern
al authentication for her logons to tdprod, where she will be switching between
using her jd1 and her jd2 UserIds, and she is going to be working in interactive
mode sometimes, it s quite likely that she will find she will want to tell BTEQ t
o suppress prompts associated with the LOGON command. Using Windows BTEQ interac
tively, here s what Jane would see based on trying out the command and then using
SHOW CONTROLS to verify the result:
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.set logonprompt off
*** Logon prompts disabled. Type .LOGONPROMPT ON; to re-enable.
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.show controls logonprompt
[SET] LOGONPROMPT = OFF
Note that setting LOGONPROMPT to OFF is sometimes not going to be sufficient for
suppressing all unnecessary prompts when using Windows BTEQ. You may also need
to instruct CLI to suppress its generation of what is known as its GUILOGON dial
og box.
Once TDP is set to tdprod it doesn t need to be reset for the logon to her jd2 Use
rId.
Once LOGMECH is set, its value will persist so it doesn t need to be reset for the
second LDAP logon.
The initial default SESSIONS setting is 1. So it doesn t need to be changed until
5 sessions are to be requested.
Since pitstop is her default AcctId, she does not need to specify it at all.
There would be no need to use a LOGON command for the second logon since she cou
ld let her AcctId value default and has supplied all other values through persis
tent settings. However, she would have had to issue a LOGONPROMPT OFF command to
be able to do that which doesn t make sense for the batch mode context. So using
the LOGON command actually makes her script easier to understand.
So here s all she really needed in her script:
/*-------------------------------------------------------*/
/* Logon 1 tdtest session using Doe, Jane .
*/
/*-------------------------------------------------------*/
.SET TDP tdtest
.LOGMECH TD2
.LOGON Doe, Jane ,sqlgood;
SELECT USER;
.LOGOFF;
/*-------------------------------------------------------*/
/* Logon 1 tdprod session using jd1 for pitstop queries. */
/*-------------------------------------------------------*/
.SET TDP tdprod
.LOGMECH LDAP
.LOGDATA JaneDoe@@bulbs2flowers user=jd1
.LOGON
SELECT USER;
.LOGOFF;
/*-------------------------------------------------------*/
/* Logon 5 tdprod sessions using jd2 for adhoc queries. */
/*-------------------------------------------------------*/
.LOGDATA JaneDoe@@bulbs2flowers user=jd2
.SET SESSIONS 5
.LOGON tdprod/,, adhoc ;
SELECT USER;
.LOGOFF;
As a final exercise, Jane decided to explore completely interactive logons using
Windows BTEQ. First she wanted to logon to tdtest and then tdprod. Remembering
that she needed to override the default TdpId value of tdprod supplied by CLI, she
entered the LOGON command including the TdpId value followed by a slash charact
er. She was immediately prompted for her UserId value
Teradata BTEQ 13.10.00.00 for WIN32.
Copyright 1984-2010, Teradata Corporation. ALL RIGHTS RESERVED.
Enter your logon or BTEQ command:
.logon tdtest/
.logon
UserId:
After entering Doe, Jane
a Password value
Password:
She went ahead and entered her
sqlgood
ly prompted to enter an AcctId default but the logon succeeded and BTEQ generate
d success messages that looked similar to this
***
***
***
***
***
She decided to move on to logging on interactively using her jd2 tdprod user. Th
is time she wanted to specify her AcctId as adhoc . So how would BTEQ prompt her fo
r the AcctId value? Well, what was not so obvious before was that she would have
needed to enter both her Password as well as her quoted AcctId, separated by a
comma, at the Password prompt for her tdtest logon. To make matters more confusi
ng, this time, since she would be using LOGDATA to authenticate to tdprod, she d
idn t need to enter her Teradata UserId/Password values for the LOGON command and
in fact would be first setting LOGONPROMPT to OFF to suppress prompts. After rev
iewing her batch mode logon script, she figured out she would just need to inclu
de it on the LOGON command rather than be prompted for it. The sequence of comma
nds she used was LOGONPROMPT, LOGMECH, LOGDATA (for which she had to blindly ente
r in her credentials), and then LOGON. Here s what her console window output looke
d like
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.logonprompt off
*** Logon prompts disabled. Type .LOGONPROMPT ON; to re-enable.
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.logmech ldap
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.logdata
LOGDATA:
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.logon tdprod/,,'adhoc';
.logon tdprod/,
*** Logon successfully completed.
*** Teradata Database Release is 13.10.00.00
*** Teradata Database Version is 13.10.00.00
*** Transaction Semantics are BTET.
*** Session Character Set Name is 'ASCII'.
Ah
Concluding Remarks
Hopefully reading through this article has given you a better understanding of t
he basics of how to use BTEQ to logon Teradata Database sessions. The goal was t
o cover all associated commands and settings and to provide some simplistic exam
ples of the more complex scenarios in order to give an idea of the BTEQ-specific
issues that might be encountered. As such, the scope of this article was very n
arrow and confined to BTEQ itself. There is much more to know about when it come
s to connecting to the Teradata Database and many related topics that might be o
f further interest to you. Just to name a few, you may want to find out :
What special characters the database allows for logon object names.
Which command to use to set environment variables recognized by CLI.
How to configure a specific authentication mechanism.
How to create a user that has a STARTUP string.
How to establish the same query band across multiple sessions.
How to use UTF8 or UTF16 as a session character set.
Obviously, the list could go on and on. To learn more about BTEQ itself, go thro
ugh the Basic Teradata Query Reference Manual (Publication B035-2414). If you ar
e further interested to know about the logon mechanisms, go through the Teradata
Database Security Administration manual (Publication B035-1100). And to know mo
re about CLI SPB defaults, such as TDP Id and session character set, go through
the Teradata Call-Level Interface Version 2 reference manuals (Publications B035
-2417 and B035-2418).
DISCUSSION