Connecting a Client Application | VantageCloud Lake - Connecting a Client Application to Vantage - Teradata VantageCloud Lake

Lake - Working with SQL
Deployment
VantageCloud
Edition
Lake
Product
Teradata VantageCloud Lake
Release Number
Published
February 2025
ft:locale
en-US
ft:lastEdition
2025-11-21
dita:mapPath
jbe1714339405530.ditamap
dita:ditavalPath
pny1626732985837.ditaval
dita:id
jbe1714339405530

The Teradata-embedded SQL preprocessor, which runs on a client system, must make a connection to Vantage. Connections are required both during precompilation and at runtime.

The preprocessor connection to Vantage made at precompile time and the connection made by an application at run time are separate events.

LOGON and CONNECT statements embedded within the SQL of a host application program have no effect on the preprocessor connection.

Preprocessor Connection

You can run the preprocessor against an application without connecting to Vantage:

SQLCHECK or -sc Option Preprocessor Requires Connection
NOSYNTAX No
  • FULL (default)
  • SQLFLAGGER(ENTRY)
 Yes

You can establish a preprocessor connection by using the tdpid or -t and userid or -u preprocessor options.

If you do not provide a user ID and the preprocessor is operating in the IBM mainframe environment, then an implicit connection is tried.

For the mainframe-attached system only, Preprocessor2 does not operate without at least one started TDP on the mainframe, even if no data access is required (that is, NOSYNTAX). If a precompile step is done on the mainframe with no started TDP, Preprocessor2 outputs this message:
SPP9980 Fatal Error:
        Unexpected CLI return 280 on DBCHINI call

Runtime Execution Connection

Runtime connection to Vantage is made either explicitly or implicitly.

The TRANSACT or -tr preprocessor transaction mode setting for a session is established when the connection (either explicit or implicit) is made.

The transaction mode is based on the TRANSACT or -tr preprocessor option setting for the application that established the session.

Completion Conditions

A successful runtime connection returns the following completion codes:
  • SQLCODE = 0
  • SQLSTATE = ‘00000’
  • SQLCA fields SQLWARN0 and SQLWARN2 = W (Teradata mode only)

Explicit Connections

An application can specify its connection explicitly using the CONNECT or the LOGON statement.

Explicit connection permits precise control over which TDP and user ID to connect with, while implicit connection uses system defaults for the TDP and user ID. For this reason, any time you need to connect to a non-default TDP or user ID, you must make an explicit connection.

Explicit connections provide precise control, even when default TDPs and user IDs are sufficient to make a connection.

If an explicit connection request is made and the application is already connected, the previous connection is dropped before the new connection is tried.

If an explicit connection request is made and a transaction is active, the connection request is rejected with an SQLCODE of -752. The application must terminate the current transaction explicitly using one of the following before trying to issue a new explicit connection request:
  • COMMIT
  • ROLLBACK (or ABORT)
  • LOGOFF
Any explicit connection to Vantage requires the following:
  • TDP ID
  • User ID
  • Password

TDP ID and user ID preprocessor options do not affect the application logon at execution time.

Default TDP ID

If you do not specify a tdpid, then the connection is made using the system default tdpid.

Platform Default TDP
IBM mainframe-attached system From the HSHSPB data area module.
Workstation-attached system TDPID from the user-defined clispb.dat file or the CLI2SPB data area.

Implicit Connection

If an embedded SQL application running in an IBM mainframe environment submits an SQL request without specifying an explicit connection, an implicit connection is tried based on the job or session under which the application is running.

LAN-attached platforms do not permit implicit connections.

Related Information

  • Preprocessor invocation options, see Teradata® Preprocessor2 for Embedded SQL Programmer Guide, B035-2446.
  • User ID security, TDP IDs, and user IDs, see Teradata® Director Program Reference, B035-2416.
  • Default TDP ID from the HSHSPB data area module, see Teradata® Call-Level Interface Version 2 Reference for Mainframe-Attached Systems, B035-2417.
  • Implicit connection mechanism, see Teradata® Call-Level Interface Version 2 Reference for Workstation-Attached Systems, B035-2418.