Overview - Call-Level Interface Version 2
Teradata Call-Level Interface Version 2 Reference for Workstation-Attached Systems
Product
Call-Level Interface Version 2
Release Number
16.10
Published
May 2017
Language
English (United States)
Last Update
2018-05-01
dita:mapPath
ggf1488824663364.ditamap
dita:ditavalPath
Audience_PDF_include.ditaval
dita:id
B035-2418
lifecycle
previous
Product Category
Teradata Tools and Utilities
Preface
Purpose
Audience
Prerequisites
Revision History
Supported Releases
Additional Information
Product Safety Information
Introduction to CLI
Overview
What is CLIv2?
CLI Design Goals
Supported Operating Systems
Interface Overview
Logical Structure
Calling CLI Directly
CLI Data Structures
DBCAREA
DBCAREA Extensions
System Parameter Block
Session Control Block
Request Control Block
MTDP Control Block
Communicating with the Teradata Database
Sessions
Teradata Partitions
Requests and Responses
Parcels
Large Objects
Executing Programs in the Teradata Database
All-Or-Nothing Property
Statements and Transactions
Teradata Transaction Semantics
ANSI Transaction Semantics
Parallel Teradata Database Operations
Multi-Statement Management
Multi-Thread Management
Multi-Session Management
Using Fetch
Considering Alternative Approaches
Common Routines Supporting CLI
DBCHINI
DBCHCL
DBCHCLN
Using the DBCAREA
One DBCAREA
Multiple DBCAREAs
Setting Alarms and Signals
Handling Password Expiration
Submitting a New Password
Session Operations
Overview
Preparing to Use CLI
DBCHINI
How Many DBCAREAs to Use?
Setting/Using the DBCAREA Options
Change Options
Establishing a Session
Executing a Startup Request
Submitting a Request
Fetching the Response
No Rewinding, Single Buffering
Rewinding, Single Buffering
No Rewinding, Double Buffering
Rewinding, Double Buffering
Repositioning, Single Buffering
Repositioning, Single/Double Buffered LOB Data
Continuing a Teradata SQL Request
Ending a Request
Aborting a Transaction
Aborting a Request
Aborting a LOB Request: Example
Aborting a Request: Example
Terminating a Session
Cleaning Up CLI
Single Session Example
Multiple Session Example
Options Processing
Setting Change Options to Y
Setting Change Options to N
CLI Files and Setup
Finding CLI Files on the System
Required Files for UNIX Platforms
Required Files for Windows Platforms
Required Files for the Apple OS X Platform
Required Files for All Platforms
CLI Environment Variables
CLI2EXITLVL
COPLIB
COPANOMLOG, NETRACE, THREADLOGGING, and THREADONOFF
TDMSTPORT
System Parameter Block (SPB) Processing
Using the COPLIB Variable
Internal SPB
System Parameter Block (SPB) File
Accessible SPB
Accessing clispb.dat
If clispb.dat is Missing
Caveats
The clispb.dat Listing
Overriding Values
Reformatted File: Example
Valid Item Specifiers
Values Used by CLI: Summary
Initial Values
Final Values
DBCAREA
DBCAREA Fields
Allocating the DBCAREA
DBCAREA Security Mechanism Fields
Network CLIv2 User Exits
Supported Mechanisms
Single Sign-On Legacy Considerations
Integrity and Compatibility
Other Mechanisms
Determining Session Username
Default Mechanism Handling
Unicode Credential Processing
DBCAREA: Field Descriptions
Individual Field Descriptions: Alphabetical Listing
Automatic-redrive
Changing the Value for Automatic-redrive
Change Options
Character Set Pointer
Character Set Type
Changing the Value for Character Set Type
Column Title and Format Information
Changing the Value for Column-info
Connect Wait
Consider APH Responses
Continuation Code
Changing the Value for Continuation Code
Current Request Buffer Length
Current Response Buffer Length
Data Encryption
Changing the Value for Data Encryption
Date Form
Changing the Value for Date Form
DBC Level
Dynamic Result Sets Allowed
Extended-Load-Usage
Extension Pointer
Exempt Session from DBCHWAT
Eyecatcher
Fetch Data Pointer
Fetch Data Pointer, Move Mode
Fetch Data Pointer, Locate Mode
Fetch Error Indicator
Fetch Maximum Data Length
Fetch Parcel Flavor
Fetch Returned Data Length
Function
Input DBCpath
Input Request Id
Input Session Id
Keep Response
Changing the Value for Keep Response
Language Conformance
Language Id
Changing the Value for Language Id
Large Row
Changing the Value for Large Row
Locate Mode
Changing the Value for Locate Mode
Logon Length
Logon Pointer
Logon Mechanism Data Length
Logon Mechanism Data Pointer
Logon Mechanism Name
Logon Timeout
Maximum Decimal Precision
Maximum Number Of Sessions for a Single Process
Maximum Parcel
Changing the Value for Maximium Parcel
Determining Maximum Parcel Request Size
Maximum Single LOB
Maximum Size of Total LOBs Per Row
Message Area Length
Message Area Pointer
Message Charset Used
Message Length
Message Length Returned
Message Return Code
Message Text
MTDP Received
MTDP Sent
Multi-Statement-Errors
Output DBC Session Id
Output DBCpath
Output Host Id
Output Request Id
Output Session Id
Parcel Mode Fetch
Changing the Value for Parcel Mode Fetch
Period-as-Struct
Positioning-action
Positioning-statement-number
Positioning-value
Request Buffer Length
Request Length
Request Mode
Changing the Value for Request Mode
Request Pointer
Example
Request Processing Option
Changing the Value for Request Processing Option
Response Buffer Length
Using CLICON
Response Mode
Return Code
Return Identity Data
Return Object
Changing the Value for Return Object
Return Statement Info
Return Time
Changing the Value for Return Time
Run Length
Run Pointer
Segment Data
Changing the Value for Segment Data
Statement-status
Stored Procedure Return Result
TASM FastFail Request
Tell About Delay
Changing the Value for Tell About Delay
APRC and Tell About Delay
Used with Wait Across Delay
Time1
Time5
Timing Precision
Time1 Status
Time5 Status
Token
Total Length
Transaction Semantics
Changing the Value for Transaction Semantics
Transforms-off
Trusted-request
Two Response Buffers
Changing the Value for Two Response Buffers
Use Presence Bits
Changing the Value for Use Presence Bits
using-data-count
Using Data Length
Using Data Length Array
Using Data Pointer
Using Data Pointer Array
Utility Workload
Variable Length Fetch
Changing the Value for Variable Length Fetch
Variable Length Request
Changing the Value for Variable Length Request
Wait Across Delay
Changing the Value for Wait Across Delay
APRC and Wait Across Delay
Used with Tell About Delay
Wait For Response
Changing the Value for Wait For Response
Wait Timeout
Workload Length
Workload Pointer
XML Response Format
DBCAREA Fields Not Used by Network-Attached Systems
DBCAREA Extensions
Overview
Initiate-request Extensions
Usage Notes
Header
Elements
Initiate-request Extensions Fields
Data Address
Data Length
Data Size
Element Length
Element Type
EyeCatcher
Level
Next Pointer
Parcel Flavor
Total Length
Total Size
Connect extension (DBCACNX)
DBCACNX Fields
Common Routines
Overview
Introduction
Use
Parameters
DBCHINI
DBCHCL
DBCHCL Functions
DBFCON
DBCAREA Parameters
Asynchronous Connects
Single Sign-On
Default Connection
DBFCRQ
DBFRSUP
DBCAREA Parameters
DBFIRQ
DBCAREA Parameters
DBFABT
DBCAREA Parameters
DBFFET
DBCAREA Parameters
DBFREW
DBCAREA Parameters
DBFERQ
DBCAREA Parameters
DBFDSC
DBCAREA Parameters
DBCHCLN
Other CLI Routines
Overview
Use
Parameters of CLI Routines: Tabular Summary
DBCHERR
DBCHFER
DBCHFERL
DBCHPEC
DBCHQE
DBCHREL
DBCHSAD
DBCHUE
DBCHUEC
DBCHWAT
DBCHWL
Parcels
Overview
Structure
Parcel Structure
Flavor Field
Length Field
Parcel Body
Parcel Types
Request Parcels: Overview
Response Parcels: Overview
Common Parcel Fields
Data Type
Activity Type
Parcel Descriptions
Abort
Abrt2PC
Assign
AssignRsp
Cancel
Cmmt2PC
Connect
CursorDBC
CursorHost
Data
DataInfo
DataInfoX
ElicitData
ElicitDataReceived
ElicitFile
EndMultipartData
EndMultipartIndicData
EndMultipartRecord
EndRequest
EndStatement
EndWith
Error
ErrorInformation
ExtendedKeepRespond
ExtendedRespond
Failure
Field
Flagger
FMReq
FMRunStartup
FormatEnd
FormatStart
IndicData
IndicReq
IVRunStartup
KeepResp
KeepRespond
Logoff
Logon
MultipartData
MultipartIndicData
MultipartRecord
MultipartRequest
Multi-TSR
NOP
NullField
OffsetPosition
OK
Options
PosEnd
Position
PosStart
PrepInfo
PrepInfoX
RecEnd
Record
Record (In Indicator Mode)
Record (In Record Mode)
RecStart
Req
Resp
Respond
ResultSet
ResultSet Cursor
ResultSummary
Rewind
RowPosition
Run
RunResponse
RunStartup
SessionOptions
Setposition
Size
SizeEnd
SizeStart
SP Options
StatementError
StatementInformation
Parcel Data
StatementInformationEnd
StatementStatus
Parcel Data
Success
TitleEnd
TitleStart
UserNameRequest
UserNameResponse
VoteRequest
VoteTerm
With
Response Sequences
Overview
The Request Buffer
Allocating the Request Buffer
Values
Maximum Length
The Response Buffer
Making It Available
Replenishing the Response Buffer
Holding Error or Failure Parcels
Sending “Buffer-fulls”
Setting Save Response Buffer
Double Buffering
One Request at a Time
The Move Area
Typical Response Sequences
Sending the Response
Screening the Response
Consuming the Response
Parcels That Indicate Problems
What Error Parcels Indicate
What Failure Parcels Indicate
Failures During Multi-Statement Requests
Parcels in Normal Sequence
Response Sequences: Field Mode
Response Sequences: Indicator Mode
Response Sequences: Multipart Indicator Mode
Response Sequences: Record Mode
Parcel Sequences
Session Control: Logon
Issuing Requests: Field Mode
Issuing Requests: Indicator Mode
Issuing Requests: Multipart Indicator Mode
Examples
Issuing Requests: Record Mode
Return, Error, and Failure Codes
Overview
Code Sources
Return Code Values and Code Types
What Code Values Mean
Information Messages
Problem Messages
Coding Messages
Return Codes That Do Not Reach the Application
Timing of Return Codes
Examples
Error and Failure Codes
Saving the Request
Responding to Error and Failure Parcels
Checking Both Code Sources
Crash and Recovery
Overview
Handling Crashes
If the Workstation-Attached System Crashes
If An Internal Error is Detected
What the Teradata Database Does
What MTDP Does
Recovery Flags
AP Reset Containment (APRC)
Value of APRC
Crash Option Aliases
What APRC Does
Enabling/Disabling APRC
What the Application May Do
Case 1: Tell and Wait
Case 2: Just Wait
Case 3: Just Tell
Stored Procedures
Introduction
Description
Send Procedure to Server
Response Processing
Abort, Cancel, and Restart Processing
Effects on Other Options
Alternate Parcel Header
Introduction
Alternate Parcel Header Structure
Client Interface Changes
Applications Using Parcel Mode
APH Parcels Sent to CLI Using the Extension Area in Parcel Mode
Using the New Element Structure
Inline:
Pointed to:
Members of New Structure Elements
Possible Combination of Element Structures
For Applications using Buffer Mode
New CLI Errors with APH Implementation
Handling Variable Length Requests
Others
Extended Message Response Size
Overview
Existing Scenario
Applications using Parcel mode (request_mode='P')
Applications using Parcel mode (request_mode='B')
Limitation in Extending the Existing Scenario
CLI - Client Interface Changes
Applications using Parcel mode (request_mode='P')
Applications using Parcel mode (request_mode='B')
CLI Exit Functions
Overview
Use
Parameters of CLI Exit Routines
CliUsrLgnExt
Internal Variable
Interface
Return Value
Error Handling
CLI Pre- and Post-Process SQL User Exits
Internal Variable
CliPreSQLExt
CliPostSQLExt
User Exits for Security
Level 2 Login and Pre & Post Exits
CliLgnExit2
CliSQLExit2
CLI2EXITLVL Environment Variable
Large Objects (LOB) Support
Introduction
Determining LOB Support
Inline Method
Server to Client Transfer
Client to Server Transfer
Deferred Method
Server to Client Transfer
Client to Server Transfer
Summary
Error Messages and Codes
Performance Measurement
Overview
Example
Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
Using 64-bit Implementation-Defined Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
Example of Setting up "using_data_ptr_array" in DBCAREA
Using Multiple Using Data Records
Glossary
ABORT
administrator
ANSI
API
ASCII
binary large object (BLOB)
Basic Teradata Query (BTEQ)
Call-Level Interface Version 2 (CLIv2)
character set
client
character large object (CLOB)
column
data definition language (DDL)
DB2
DEFINE statement
delimiter
Dynamic-link library (DLL)
domain name
EBCDIC
exit routine
failure
field
function
gateway
I/O
in-doubt
internet protocol (IP)
Japanese Industrial Standards (JIS)
LAN
large object (LOB)
log
macro
methods
Micro Operating System Interface (MOSI)
Micro Teradata Director Program (MTDP)
multi-threading
network
network-attached
null
object
parameter
privilege
procedure
protocol
records
request
result
results table/file
row
rowId join
script
server
session
source database
Single Sign-On (SSO)
statement
statistics
stored procedure
table
target database
target table
TCP/IP
Teradata Director Program (TDP)
Teradata Director Program Identifier (TPDID)
Teradata Generic Security Services (GSS)
Teradata SQL
title
transaction
trigger
type
User-defined function (UDF)
Unicode
user
UTF-16
varbyte
varchar
vargraphic
view
workstation
This chapter describes:
The buffers used to hold parcels to be sent to and from the Teradata Database, that is, the:
Request buffer
Response buffer
Move area
Teradata SQL response sequences
The parcels used in typical exchanges, including parcels generated by an application when it makes a request and the parcels generated by the system when responding to a request