17.10 - 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
17.10
Release Date
October 2021
Content Type
Programming Reference
Publication ID
B035-2418-061K
Language
English (United States)

DBFCON is the Connect function of DBCHCL.

DBFCON is used to perform the following tasks:
  • 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 as follows:
  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 as follows:
  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