Logon Elements

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

de how to request multiple sessions.

The last two actions are about taking measures to use the most efficient set of
commands when logging on
whether interactively entering the necessary input or u
sing a pre-written script.
SESSIONS Command
The SET SESSIONS command, also known as the SESSIONS setting, is used to assign
an integer value for the number of sessions that all subsequent LOGON commands u
sed should end up attempting to connect. It can not be used while already logged
on. Note that the exact number of sessions being requested may not be available
to get connected. As long as one session successfully gets established, BTEQ wi
ll treat the logon as successful.
Syntax:
SESSION command syntax diagram
The maximum number (n) is 200. BTEQ assumes 1 if the number argument is omitted.
The key for determining when to use multiple sessions lies in understanding that
their existence may enable the Teradata Database to process requests in paralle
l. This might mean they could be useful for loading a large number of rows into
a database when insert order is not important or when some of the associated SQL
requests will be long running.
The SHOW CONTROLS command can be used to see what the current value is for the S
ESSIONS setting. For example, let s assume Jane has invoked Windows BTEQ in order
to interactively explore logon-related commands. She first uses the SET SESSIONS
command to establish a persistent setting for having up to 5 sessions per logon
and then follows that with a SESSIONS-specific SHOW CONTROLS command to verify
she used the command correctly. The following snippet shows what output she woul
d be seeing in the console window:
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.set sessions 5
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.show controls sessions
[SET] SESSIONS = 5
Note: To have cleaner examples, BTEQ s ECHOREQ setting was set to OFF to produce m
ost of the interactive output snippets in this article.
TDP Command
The SET TDP command, also known as the TDP setting, is used to override the defa
ult TdpId value to be used for all subsequent LOGON commands where a TdpId value
is not supplied. Note that whenever a TdpId value is supplied as part of a LOGO
N command that the TDP setting is automatically updated with that value as the n
ew default.
Syntax:
TDP command syntax diagram
Will Jane need to use this command? Well, her DBA told her that the Network-atta
ched and Channel-attached CLIs that BTEQ will use have been configured to tell B
TEQ to use tdprod and TDPS as the default TdpId values respectively. So she unde
rstands that in order to use tdtest that she is, at times, going to have to spec
ify a TdpId value. It could be the case she develops habits using SET TDP that m

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.

This can be accomplished by setting the environment variable GUILOGON to NO.

LOGMECH Command
The Workstation-BTEQ-only LOGMECH command, also known as the LOGMECH setting, is
used to supply the name of the needed authentication mechanism. Its use is only
required when the default mechanism needs to be overridden.
Syntax:
LOGMECH command syntax diagram
Jane s DBA told her that LDAP has been established at her site as the default mech
anism for tdprod. When she wants to use the same BTEQ process to switch between
logging on to tdprod and tdtest she will need to use this setting.
LOGDATA Command
The Workstation-BTEQ-only LOGDATA command, also known as the LOGDATA setting, is
used to supply user credentials and qualifier parameters needed by the external
authentication mechanism. BTEQ will accept a character string of up to 32000 by
tes for the value.
Syntax:
LOGDATA command syntax diagram
For batch mode, the value is entered as an argument to the LOGDATA command on th
e same line of input with the string immediately following the LOGDATA keyword.
However, since the LOGDATA value can contain sensitive information (such as a pa
ssword), when the value is entered in interactive mode, the user must wait for B
TEQ to switch to protected data-entry mode and give a prompt for the value to be
entered. This protected mode entry exchange is also what BTEQ uses when prompti
ng for a LOGON command s Password value. Furthermore, the SHOW CONTROLS command ca
n not be used to see what the current value is for the setting.
If you are entering a LOGDATA value interactively and forget to wait for BTEQ to
prompt you for its protected mode entry, BTEQ will generate an error message. I
t took a few attempts for Jane to get into the correct habit. Using Windows BTEQ
interactively, here s what Jane saw when she messed up :
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.logdata JaneDoe@@bulbs2flowers user=jd1
*** Error: Value entered as argument, rather than as response to
prompt.
And here s what it looked like when she entered it correctly:
Teradata BTEQ 13.10.00.00 for WIN32. Enter your logon or BTEQ command:
.logdata
LOGDATA:
LOGON Command
The LOGON command, as mentioned previously, is what triggers the process of logg
ing on. Its arguments are comprised of positional values for TdpId, UserId, Pass
word, and AcctId elements or no argument string at all. In interactive mode, BTE
Q will then prompt for any required missing values. What is considered to be miss
ing will depend on the LOGONPROMPT, LOGMECH, and LOGDATA settings.

Syntax for Interactive Mode:

Interactive LOGON command syntax diagram
Syntax for Batch Mode:
Batch LOGON command syntax diagram
If the LOGMECH and LOGDATA commands were previously used for defining an externa
l authentication mechanism and credentials, then the UserId and Password element
s do not need to be included in the LOGON command.
So what happens when all values have been supplied without having to supply an a
rgument string for the LOGON command **and** all logon prompts have been disable
d? Well BTEQ will proceed with doing a tacit logon for the user when it encounter
s a subsequent SQL request.
LOGON Examples
Jane is ready to logon and test out all of her Teradata UserIds for the first ti
me. Her DBA helped her understand how to create scripts that can be executed usi
ng BTEQ s RUN command. So for the moment she s using batch mode logons, so as not to
have to retype all the commands while figuring things out. Here s the Windows BTE
Q script that she initially comes up with:
/*-------------------------------------------------------*/
/* Logon 1 tdtest session using Doe, Jane .
*/
/*-------------------------------------------------------*/
.SET TDP tdtest
.LOGMECH TD2
.SET SESSIONS 1
.LOGON tdtest/ Doe, Jane ,sqlgood, pitstop ;
SELECT USER;
.LOGOFF;
/*-------------------------------------------------------*/
/* Logon 1 tdprod session using jd1 for pitstop queries. */
/*-------------------------------------------------------*/
.SET TDP tdprod
.LOGMECH LDAP
.LOGDATA JaneDoe@@bulbs2flowers user=jd1
.SET SESSIONS 1
.LOGON tdprod/,, pitstop ;
SELECT USER;
.LOGOFF;
/*-------------------------------------------------------*/
/* Logon 5 tdprod sessions using jd2 for adhoc queries. */
/*-------------------------------------------------------*/
.SET TDP tdprod
.LOGMECH LDAP
.LOGDATA JaneDoe@@bulbs2flowers user=jd2
.SET SESSIONS 5
.LOGON tdprod/,, adhoc ;
SELECT USER;
.LOGOFF;
Everything worked fine. However, she didn t need to explicitly specify all values
for every setting used for each LOGON. It could be greatly condensed for these r
easons:
Using the SET TDP command upfront means she doesn t need to supply a TdpId value f
or the LOGON commands.

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

(including double quotes), she was then prompted to enter

Password:
She went ahead and entered her

sqlgood

password and noticed she was not subsequent

ly prompted to enter an AcctId default but the logon succeeded and BTEQ generate
d success messages that looked similar to this
***
***
***
***
***

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'.

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

sweet success. We can now say bon voyage to Jane. smiley

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