DBFCON - Call-Level Interface Version 2

Teradata Call-Level Interface Version 2 Reference for Workstation-Attached Systems

Product
Call-Level Interface Version 2
Release Number
15.10
Language
English (United States)
Last Update
2018-10-07
dita:id
B035-2418
lifecycle
previous
Product Category
Teradata Tools and Utilities

DBFCON

DBFCON is the Connect function of DBCHCL.

DBFCON is used to:

  • Log on to the specified database computer.
  • Arrange to have the specified set of services used for all requests on that session.
  • Allocate internal control structures that CLI uses to store session context.
  • 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:

  • Obtains and initializes context block
  • Validates DBCAREA arguments, as necessary
  • If the application has requested option updates, perform option set/validation logic

  • Obtains/initializes buffers, the length of which is either the user requested size or the default size
  • Sets actual length of request/fetch buffers
  • If the application program has requested the User Exit option, sends a special logon string to the CLI User Exit Function
  • Sends the logon (connect) request and connect request parcels in the request buffer to the MTDP and awaits completion
  • If the Run String Buffer Length field indicates the buffer is a run string and not a connect structure, builds a connect structure for the session
  • If successful, sets the actual session number output argument and the return code and returns control to caller
  • If the Connect fails, returns an error; run string, if omitted, defaults to Teradata SQL
  • 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:

     

    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:

  • Change Options
  • Character Set Pointer
  • Character Set Type
  • Connect Type
  • Create Default Connection
  • Data Encryption
  • Date Form
  • Dynamic Result Sets Allowed
  • Extended Load Usage
  • Function
  • Input DBCpath
  • Keep Response
  • Language Conformance
  • Locate Mode
  • Logon Length
  • Logon Pointer
  • Maximum Decimal Precision
  • Maximum Number of Sessions for a single process
  • Maximum Parcel
  • Multi-Statement-Errors
  • Parcel Mode
  • Request Buffer Length
  • Request Mode
  • Request Processing Option
  • Response Buffer Length
  • Response Mode
  • Return Time
  • Run Length
  • Run Pointer
  • Save Response Buffer
  • Stored Procedure Return Result
  • TASM FastFail Request
  • Tell About Crash
  • Token
  • Transaction Semantics
  • Two Response Buffers
  • Use Presence Bits
  • Utility Workload
  • Variable Length Fetch
  • Variable Length Request
  • Wait Across Crash
  • Wait For Response
  • Output Arguments

    Output arguments are listed below:

  • Current Request Buffer Length
  • Current Response Buffer Length
  • Maximum Decimal Precision
  • Message Length
  • Message Text
  • MTDP Received
  • MTDP Sent
  • Output DBC Session Id (after first associated fetch)
  • Output DBCpath (after first associated fetch)
  • Output Host Id (after first associated fetch)
  • Output Request Id
  • Output Session Id
  • Return Code
  • 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:

  • Call DBCHCL for DBFFET with Wait For Response set to Y, causing the DBCHCL to wait for the completion of an explicit session connect request.
  • Call DBCHWAT, which will return session identifiers for connect requests as they complete, and then call DBCHCL for DBFFET for the completed session.
  • Call DBCHCL for DBFFET repeatedly, with Wait For Response set to N, until the connect request has completed.
  • 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
  • Third‑party sign‑on
  • 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).