DBFCON
DBFCON is the Connect function of DBCHCL.
DBFCON is used to:
CLIv2 allows users to append user-specific information to the LogonSource column of the DBC.EventLog table for each connected session. CLIv2 accesses this information through the LSINFO environment variable. The method for setting an environment variable does vary among platform implementations; consult the appropriate documentation for your specific platform environment.
Be aware that the LogonSource column is a string defined as VARCHAR(128). Therefore, the maximum allowable length of the LogonSource column is 127 bytes (with the last byte a null terminator). If the LogonSource column exceeds 127 bytes, it will be truncated and LSINFO will not be appended. If the sum of the lengths of the Logon Source column and LSINFO (plus a blank separator character) exceeds 127 bytes, LSINFO will not be appended.
What It Does
DBFCON performs the following functions:
If the application has requested option updates, perform option set/validation logic
Sending a Connect Request
The sequence of operations to send a connect request is:
1 Call DBCHCL for DBFCON
2 Check that return code is zero
Successful Connect Operation
The sequence of operations required for a successful connect operation is:
1 Call DBCHCL for DBFCON
2 Check that return code is zero
3 Call DBCHCL for DBFFET
4 Check that return code is zero
5 Check that parcel is not Error or Failure parcel
6 Call DBCHCL for DBFERQ
7 Check that return code is zero
Interface
The DBFCON interface is as follows:
Function: |
DBFCON - Connect |
Purpose: |
Logon and Run. (Analogous to SQL ‘CONNECT‘) |
Parms: |
struct DBCAREA *dbcptr pointer to a DBCAREA |
DBCAREA Parameters
The following fields in the DBCAREA may be read, or written to, by DBFCON, depending on the application program’s environment.
Input Arguments
Input arguments are listed below:
Output Arguments
Output arguments are listed below:
Asynchronous Connects
Asynchronous logons are available on all clients. For example, DBCHCL can be called more than once for DBFCON before calling DBCHCL for DBFFET.
As before, if Wait For Response is to be set to N for the fetch associated with the connect, the setting must take place at connect initiation time. Wait For Response is not read in at fetch time.
After a connect has been initiated, the application may do one of the following:
If the call to DBCHCL for DBFCON results in a non-zero return code, the connect has failed for the reason indicated by the value of the return code. However, the internal data structures are not de-allocated. The application program must de-allocate the CLI internal structures for the non-existing session by calling DBCHCL for DBFDSC. The Output Session Id from DBFCON is the appropriate value to place in Input Session Id for DBFDSC.
The database computer to be used is specified with the logon string. The set of services to be used is specified with the run string.
When DBCHCL returns control to the application program after initiating a connect operation, the initial status of the connect operation is reflected in the DBCAREA, including Output Session Id, Output Request Id. When DBCHCL returns control to the application program after the first fetch associated with the connect operation, the final status of the connect operation is reflected in the DBCAREA, including Output DBCpath, Output Host Id, and Output DBC Session Id.
Single Sign-On
Single Sign-On (SSO) is available only in the Windows environment. This feature has two modes of operations:
Direct Sign-On
Direct sign‑on permits a user to logon to a Teradata Database without providing a user name and password; an account string may or may not be necessary. The Windows user identity must match the Teradata username and the username must have previously been granted the logon with null password privilege.
Third-Party Sign-On
Third-party sign-on is designed for use by application servers that log on to a Teradata Database on behalf of a user through an API. Third-party sign-on requires that a user supply a username, password, and, possibly, a domain name to the application server. As with direct sign-on, the username must have previously been granted the logon with null password privilege.
A Logon parcel that does not contain a userid and a password will be interpreted as an SSO logon.
Note: For direct sign-on SSO to work correctly, the GUILOGON environment variable must be set to NO. Otherwise, CLI will display the GUILOGON dialog box.
For more information, see “Creating A User for Single Sign-On” and “LOGON Statement” in the SQL Fundamentals (B035‑1141) and “Single Sign-On” in the Utilities manual.
Encrypted Logon
If encryption support is switched on at the server (gateway), then CLI will send the logon string in encrypted form. The process of logon encryption is abstracted from and cannot be controlled by the applications.
Default Connection
A default connection will allow a CLI-based External Stored Procedure to function on behalf of the session under which it was initiated through the SQL CALL statement.
In order to create a default connection, the create_default_connection parameter to DBCHCL DBCHCON must be set to 'Y'. For more detail, see SQL External Routine Programming (B035‑1147).