Teradata Call-Level Interface
Version 2
Reference for Network-Attached Systems
Release 13.10
B035-2418-020A
February 2010
The product or products described in this book are licensed products of Teradata Corporation or its affiliates.
Teradata, BYNET, DBC/1012, DecisionCast, DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce,
SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts, WebAnalyst, and You’ve Never Seen Your Business Like
This Before are trademarks or registered trademarks of Teradata Corporation or its affiliates.
Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.
AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.
BakBone and NetVault are trademarks or registered trademarks of BakBone Software, Inc.
EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.
GoldenGate is a trademark of GoldenGate Software, Inc.
Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company.
Intel, Pentium, and XEON are registered trademarks of Intel Corporation.
IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation.
Linux is a registered trademark of Linus Torvalds.
LSI and Engenio are registered trademarks of LSI Corporation.
Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United
States and other countries.
Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.
QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation.
SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc.
SPARC is a registered trademark of SPARC International, Inc.
Sun Microsystems, Solaris, Sun, and Sun Java are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other
countries.
Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States
and other countries.
Unicode is a collective membership mark and a service mark of Unicode, Inc.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other product and company names mentioned herein may be the trademarks of their respective owners.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN “AS-IS” BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION
MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
The information contained in this document may contain references or cross-references to features, functions, products, or services that are
not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features,
functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions,
products, or services available in your country.
Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated
without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any
time without notice.
To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this
document. Please e-mail: [email protected]
Any comments or materials (collectively referred to as “Feedback”) sent to Teradata Corporation will be deemed non-confidential. Teradata
Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform,
create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata
Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including
developing, manufacturing, or marketing products or services incorporating Feedback.
Copyright © 1998-2010 by Teradata Corporation. All Rights Reserved.
Preface
Purpose
This book provides information about Teradata Call-Level Interface Version 2 for NetworkAttached Systems (CLIv2), which is a Teradata® Tools and Utilities product. Teradata Tools
and Utilities is a group of products designed to work with Teradata Database.
CLIv2 is a library of routines that enable an application to access data on Teradata Database.
Audience
This book is intended for use by:
•
System and application programmers responsible for writing programs to access data on a
Teradata Database
•
System administrators
•
Database administrators
•
Relational database developers
Supported Releases
This book supports the following:
•
Teradata Database 13.10
•
Teradata Tools and Utilities 13.10
•
Teradata Call-Level Interface Version 2 for Network-Attached Systems 13.10
Note: See “The qepItem Field” on page 224 for the query that verifies the version number.
To locate detailed supported release information:
1
Go to http://www.info.teradata.com
2
Click General Search under Online Publications.
3
Type 3119 in the Publication Product ID box.
4
Under Sort By, select Date.
5
Click Search.
6
Open the version of the Teradata Tools and Utilities ##.# Supported Platforms and Product
Versions spreadsheet associated with this release.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
3
Preface
Prerequisites
The spreadsheet includes supported Teradata Database versions, platforms, and product
release numbers.
Prerequisites
The following prerequisite knowledge is required for this product:
•
Basic computer technology
•
Database management systems
•
Utilities that load and retrieve data
Changes to This Book
The following changes were made to this book in support of the current release. Changes are
marked with change bars. For a complete list of changes to the product, see the Teradata Tools
and Utilities Release Definition associated with this release.
Date and Release
Description
February 2010
13.10
Added clispb.dat items to tables 3, 4, and 5, in Chapter 4.
Added or changed the following queries to in the table labeled “The
qepItem Field” on page 224:
• QEPIUD (23)
• QEPIDAP (49)
• QEPITSS (50)
• QEPILNS (51)
• QEPITOU (52)
• QEPITRS(53)
Added support for “username” and “client application name” in logon
source string. See “DBFCON” on page 193.
Added support for ColumnInfo. See “Column Title and Format
Information” on page 93.
Added support for Trusted Sessions. See “Trusted-request” on page 159 and
“The qepItem Field” on page 224.
Added support for UDT TransformsOff. See “Period-as-Struct” on
page 132, “Transforms-off ” on page 158, and “The qepItem Field” on
page 224.
Documented “tx_semantics” and other entries for clispb.dat. See “The
clispb.dat Listing” on page 66.
Changed erroneous references from EBCDIC to ACSII.
Made changes to tables for DBCAREA. See “DBCAREA: Field
Descriptions” on page 82.
4
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Preface
Changes to This Book
Date and Release
Description
Made changes to “Maximum Number of Sessions” to be “Maximum
Number of Sessions for a Single Process.”
Added information on SPNEGO. See “SPNEGO” on page 77.
Added a caveat to QEPIDR about functionality. See QEPIDDBR under
qepItem in “DBCHQE” on page 220.
Samples and Windows makefiles support Visual Studio 7.1 and height.
Support TASM Utility Management. See “Utility Workload” on page 166.
Remove references to MVS. Sytem obsolete.
Added dbcarea.consider_APH_resps. See “Consider APH Responses” on
page 94.
TDQM is obsolete.
April 2009
13.00
Corrected Table, “Sequential Order of the DBCAREA.”
August 2008
13.00
Added a description of how to set maximum file size of copanomlog. See
“COPANOMLOG, NETRACE, THREADLOGGING, and
THREADONOFF” on page 61.
Expanded the syntax of LDAP authentication for logons. See “LDAP” on
page 78.
Added a new field in DBCAREA that indicates the character set used to
construct error messages. See “Message Charset Used” on page 123.
Modified the behavior of user exit routines, so CLI now works with or
without user exit routines. See “Overview” on page 385 and “CLI2EXITLVL
Environment Variable” on page 391.
Added the following queries to in the table labeled “The qepItem Field” on
page 224:
•
•
•
•
•
•
QEPISCS (46)
QEPICCS (47)
QEPIUS (48)
QEPIDAP (49)
QEPITSS (50)
QEPILNS (51)
Added support for periodic data types. See “Common Parcel Fields” on
page 255.
Clarified the impact of user-defined functions (UDFs), which use the
ElictData, ElicitFile, and ElicitName parcels. See “Communicating with
Teradata Database” on page 29 and “Continuing a Teradata SQL Request”
on page 50.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
5
Preface
Additional Information
Additional Information
Additional information that supports this product and Teradata Tools and Utilities is available
at the web sites listed in the table that follows. In the table, mmyx represents the publication
date of a manual, where mm is the month, y is the last digit of the year, and x is an internal
publication code. Match the mmy of a related publication to the date on the cover of this book.
This ensures that the publication selected supports the same release.
Type of Information
Description
Access to Information
Release overview
Use the Release Definition for the following
information:
1 Go to http://www.info.teradata.com.
• Overview of all of the products in the
release
• Information received too late to be
included in the manuals
• Operating systems and Teradata
Database versions that are certified to
work with each product
• Version numbers of each product and
the documentation for each product
• Information about available training
and the support center
3 In the Publication Product ID box, type 2029.
Use the Teradata Information Products web
site to view or download specific manuals
that supply related or additional
information to this manual.
1 Go to http://www.info.teradata.com.
Late information
Additional product
information
2 Click General Search under Online Publications.
4 Click Search.
5 Select the appropriate Release Definition from
the search results.
2 Click Data Warehousing under Online
Publications, Browse by Category.
3 Do one of the following:
• For a list of Teradata Tools and Utilities
documents, click Teradata Tools and Utilities,
and then select an item under Releases or
Products.
• Select a link to any of the data warehousing
publications categories listed.
Specific books related to Teradata Call-Level
Interface Version 2 for Network-Attached Systems
are as follows:
• Teradata Tools and Utilities Installation Guide for
Microsoft Windows
B035-2407-mmyx
• Messages
B035-1096-mmyx
• Teradata Tools and Utilities Command Summary
B035-2401-mmyx
6
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Preface
Additional Information
Type of Information
Description
Access to Information
CD-ROM images
Access a link to a downloadable CD-ROM
image of all customer documentation for
this release. Customers are authorized to
create CD-ROMs for their use from this
image.
1 Go to http://www.info.teradata.com.
Use the Teradata Information Products web
site to order printed versions of manuals.
1 Go to http://www.info.teradata.com.
Ordering
information for
manuals
2 Click Data Warehousing under Online
Publications, Browse by Category.
3 Click CD-ROM List and Images.
2 Click How to Order under Print & CD
Publications
3 Follow the ordering instructions.
General information
about Teradata
The Teradata home page provides links to
numerous sources of information about
Teradata. Links include:
1 Go to Teradata.com.
2 Select a link.
• Executive reports, case studies of
customer experiences with Teradata,
and thought leadership
• Technical information, solutions, and
expert advice
• Press releases, mentions, and media
resources
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
7
Preface
Additional Information
8
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Supported Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Changes to This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Chapter 1:
Introduction to CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
What is CLIv2? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Interface Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
CLI Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Communicating with Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Programs Executed within the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Parallel Teradata Database Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-Statement Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
32
32
33
Common Routines Supporting CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Using the DBCAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Setting Alarms and Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Handling Password Expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Chapter 2:
Session Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Preparing to Use CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Setting/Using the DBCAREA Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
9
Table of Contents
Establishing a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Executing Startup Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Submitting a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Fetching the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Continuing a Teradata SQL Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Ending a Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Aborting a Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Aborting a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Aborting a LOB Request: Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Aborting a Request: Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Terminating a Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Cleaning Up CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Single Session Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Multiple Session Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Options Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Chapter 3:
CLI Files and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Finding CLI Files on the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
CLI Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Chapter 4:
System Parameter Block (SPB) Processing . . . . . . . . . . . . . . . . . . . . . .65
Using the COPLIB Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
System Parameter Block (SPB) File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
The clispb.dat Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Overriding Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Values Used by CLI: Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Chapter 5:
DBCAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
DBCAREA Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Allocating the DBCAREA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
10
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Table of Contents
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
74
75
76
80
80
80
80
81
81
DBCAREA: Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Individual Field Descriptions: Alphabetical Listing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Change Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Character Set Pointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Character Set Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Column Title and Format Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Connect Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Consider APH Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Continuation Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Current Request Buffer Length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Current Response Buffer Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Data Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Date Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
DBC Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Dynamic Result Sets Allowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Extension Pointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Exempt Session from DBCHWAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Eyecatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Fetch Data Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Fetch Data Pointer, Move Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Fetch Data Pointer, Locate Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Fetch Error Indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Fetch Maximum Data Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Fetch Parcel Flavor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Fetch Returned Data Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Input DBCpath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Input Request Id. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Input Session Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Keep Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Language Conformance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Language Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Locate Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Logon Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
11
Table of Contents
Logon Pointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Logon Mechanism Data Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Logon Mechanism Data Pointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Logon Mechanism Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Maximum Decimal Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Maximum Number Of Sessions for a Single Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Maximum Parcel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Message Area Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Message Area Pointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Message Charset Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Message Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Message Length Returned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Message Return Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Message Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
MTDP Received . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
MTDP Sent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Output DBC Session Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
Output DBCpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Output Host Id. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Output Request Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Output Session Id. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Parcel Mode Fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Period-as-Struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Positioning-action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Positioning-statement-number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Positioning-value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Request Buffer Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Request Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
Request Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Request Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Request Processing Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Response Buffer Length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Response Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
Return Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Return Identity Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Return Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Return Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Run Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Run Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Segment Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Statement-status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Stored Procedure Return Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Tell About Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
12
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Table of Contents
Time1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Time5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Timing Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Time1 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Time5 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Total Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Semantics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transforms-off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trusted-request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Two Response Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Variable Length Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Wait Across Crash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Wait Across Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Wait For Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Workload Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Workload Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
152
152
153
154
155
155
156
157
158
159
159
160
161
162
163
164
165
166
167
168
169
170
170
172
172
DBCAREA Fields Not Used by Network-Attached Systems. . . . . . . . . . . . . . . . . . . . . . . . . . 173
Chapter 6:
DBCAREA Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Initiate-request Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Initiate-request Extensions Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Connect extension (DBCACNX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Chapter 7:
Common Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
13
Table of Contents
DBCHINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
DBCHCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
DBCHCL Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192
DBFCON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
DBFCRQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
DBFRSUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
DBFIRQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
DBFABT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
DBFFET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
DBFREW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208
DBFERQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
DBFDSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
DBCHCLN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
Chapter 8:
Other CLI Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Parameters of CLI Routines: Tabular Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
DBCHFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
DBCHFERL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
DBCHPEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
DBCHQE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
DBCHREL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
DBCHSAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
DBCHUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238
DBCHUEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
DBCHWAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240
DBCHWL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
Chapter 9:
Parcels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
Parcel Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
Request Parcels: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
Response Parcels: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
Common Parcel Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
Activity Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257
14
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Table of Contents
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
259
259
260
260
261
262
262
263
264
264
265
266
267
268
268
269
270
270
270
271
271
271
272
273
274
274
275
276
277
277
278
278
279
279
281
281
282
282
283
284
285
286
287
15
Table of Contents
MultipartRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
Multi-TSR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
NOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
NullField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
OffsetPosition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
OK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
PosEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295
Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
PosStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
PrepInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
PrepInfoX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
RecEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Record (In Indicator Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304
Record (In Record Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306
RecStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .308
Req. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Resp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Respond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
ResultSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311
ResultSet Cursor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311
ResultSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Rewind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
RowPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
RunResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315
RunStartup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
SessionOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
Setposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .318
Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .318
SizeEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
SizeStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
SP Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
StatementInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
StatementInformationEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .326
Success. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327
TitleEnd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
TitleStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
UserNameRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
UserNameResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
VoteRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
VoteTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
16
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Table of Contents
With. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Chapter 10:
Response Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
The Request Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
The Response Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
The Move Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Typical Response Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Response Sequences: Field Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Response Sequences: Indicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Response Sequences: Multipart Indicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Response Sequences: Record Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Parcel Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Session Control: Logon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Issuing Requests: Field Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Issuing Requests: Indicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Issuing Requests: Multipart Indicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Issuing Requests: Record Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Chapter 11:
Return, Error, and Failure Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Code Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Return Code Values and Code Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Error and Failure Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Responding to Error and Failure Parcels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Checking Both Code Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Chapter 12:
Crash and Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Handling Crashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
What the Teradata Database Does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
What MTDP Does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
AP Reset Containment (APRC). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
17
Table of Contents
What the Application May Do. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365
Case 1: Tell and Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .366
Case 2: Just Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .366
Case 3: Just Tell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367
Chapter 13:
Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
Send Procedure to Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
Response Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
Abort, Cancel, and Restart Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
Effects on Other Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
Chapter 14:
Alternate Parcel Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
Alternate Parcel Header Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .374
Client Interface Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .374
Using the New Element Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
Members of New Structure Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
Chapter 15:
Extended Message Response Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
Existing Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
Limitation in extending the existing Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
CLI - Client Interface changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
Chapter 16:
CLI Exit Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
Parameters of CLI Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
18
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Table of Contents
CliUsrLgnExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
CLI Pre- and Post-Process SQL User Exits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
CliPreSQLExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
CliPostSQLExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
User Exits for Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Level 2 Login and Pre & Post Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CliLgnExit2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CliSQLExit2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
390
390
390
390
CLI2EXITLVL Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Chapter 17:
Large Objects (LOB) Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Determining LOB Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Inline Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Deferred Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Error Messages and Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Chapter 18:
Performance Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Appendix A:
Examples of Using
DBCAREA Extension Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Sending TDSP Options Parcel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Using 64-bit Implementation-Defined Extension Elements . . . . . . . . . . . . . . . . . . . . . . 401
Sending TDSP Options Parcel Using APH Defined Extension Elements . . . . . . . . . . . . . . . 411
Sending a Parameterized SQL Using APH Defined Extension Elements . . . . . . . . . . . . . . . 419
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
19
Table of Contents
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .429
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .437
20
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
List of Figures
Figure 1: CLI Interface: Logical Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Figure 2: CLI Routine Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Figure 3: Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Figure 4: SPH Parcel Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Figure 5: APH Parcel Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
21
List of Figures
22
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
List of Tables
Table 1: Single Session Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Table 2: Multiple Session Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Table 3: clispb.dat File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Table 4: clispb.dat File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Table 5: Mnemonic Names of Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Table 6: Sequential Order of the DBCAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Table 7: Processing Options for Network-Attached Systems . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Table 8: Uses of Routines and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Table 9: Parameters for CLI Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Table 10: Function Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Table 11: Use of Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Table 12: Parameters for CLI Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Table 13: Parcel Flavors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Table 14: Request Parcels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Table 15: Response Parcels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Table 16: Data Type Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Table 17: Activity Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Table 18: PrepInfoX Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Table 19: Teradata Database Internal Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Table 20: ResultSummary Parcel Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Table 21: Full-layout Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Table 22: PBTIFDT Additional Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Table 23: Limited-layout Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Table 24: Statistic-layout Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Table 25: Update Table1 Set Field1 = 999999; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Table 26: Select Field1 From Table1;. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Table 27: Select Field1 From Table1 With Sum (FIELD1);. . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Table 28: Select Field1 From Table1; Select Field2 From Table2; . . . . . . . . . . . . . . . . . . . . . 347
Table 29: Echo ‘Select Field1 From Table1’; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Table 30: Update Table1 Set Field1 = 999999; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Table 31: Select Field1 From Table1;. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Table 32: Select Field1 From Table1 With Sum (Field1); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
23
List of Tables
Table 33: Select Field1 From Table1; Select Field2 From Table2; . . . . . . . . . . . . . . . . . . . . . .350
Table 34: Echo ‘Select Field1 From Table1’;. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Table 35: Update Table1 Set Field1=999999; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Table 36: Select Field1 From Table1;. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Table 37: Select Field1 from Table1 With Sum (Field1); . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Table 38: Select Field1 From Table1; Select Field2 From Table2; . . . . . . . . . . . . . . . . . . . . . .356
Table 39: Echo ‘Select Field1 From Table1’;. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
Table 40: Error and Failure Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .359
Table 41: Parcel Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
Table 42: Use of Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
Table 43: CLI Routine Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
24
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 1
Introduction to CLI
This chapter describes the:
•
CLIv2 interface, including its logical structure and the data structures supporting it
•
Information flow between the application program and the Teradata Database using
CLIv2
•
Common routines supporting CLIv2
•
Parallel processing capabilities of the Teradata Database, including multi-statement,
multi-request, and multi-session management
•
Setting of alarms and signals within a user’s CLIv2 program and how password expiration
is handled
What is CLIv2?
Teradata Call-Level Interface Version 2 for Network-Attached Systems (CLIv2, hereafter
referred to as CLI unless otherwise noted), is a collection of callable service routines that
provide the interface between applications and the Teradata Gateway. Gateway is the interface
between CLI and the Teradata Database.
CLI sends requests to the Teradata Database and provides the application with a response
returned from the system.
CLI provides support for:
•
Managing multiple serially-executed requests on a session
•
Managing multiple simultaneous sessions to the same, or different, Teradata Databases
•
Using cooperative processing so that the application can perform operations on the client
and the Teradata Database simultaneously
•
Generally insulating the application from details in communicating with a Teradata
Database
CLI Design Goals
The design of CLI was guided by the following goals:
•
It must be simple to use.
•
It must have enough power and flexibility to enable Teradata SQL (Structured Query
Language) applications to exploit fully the power of the Teradata Database.
•
It must be efficient. Workstation CPU and virtual storage utilization must be minimized.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
25
Chapter 1: Introduction to CLI
Supported Operating Systems
•
The above goals must be met both for preprocessor applications and for applications that
do not use a preprocessor, that is, for applications that make direct calls to CLI.
•
It must support SQL/DS- and DB2- compatible preprocessors, if they become available.
•
Installation and maintenance must be simple.
Supported Operating Systems
See Teradata Tools and Utilities xx.xx.xx Supported and Certified Versions B035-3119 at
www.info.teradata.com.
For information about where CLI files are installed on different platforms, see “Finding CLI
Files on the System” on page 59.
Interface Overview
Applications manipulating data on the Teradata Database communicate indirectly with the
Teradata Database by means of CLI.
Logical Structure
CLI is the interface between an application and the Micro Teradata Director Program
(MTDP). CLI does the following:
•
Builds parcels that MTDP packages for sending to the Teradata Database using the Micro
Operating System Interface (MOSI), and
•
Provides the application with a pointer to each of the parcels returned from the Teradata
Database.
MTDP is the interface between CLI and MOSI. MOSI is the interface to the Teradata
Database.
Calling CLI Directly
Applications coded in languages for which the Teradata Database does not provide a
preprocessor, or applications requiring features not provided by the preprocessor, call CLI
directly. But many applications use one of the Teradata SQL preprocessors and thus are
shielded from the details of CLI.
26
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 1: Introduction to CLI
CLI Data Structures
Figure 1: CLI Interface: Logical Structure
Application
Response
Request
CLI
MTDP
MOSI
Teradata
Database
2418B004
CLI Data Structures
CLI consists of the following data structures:
Note: None of the following control blocks are available outside of CLI.
• DBCAREA and its extensions
-
Data Structure
• CLI2SPB
-
CLIv2 System Parameter Block
• CLI2ACB
-
CLIv2 Application Control Block
• CLI2SCB
-
CLIv2 Session Control Block
• CLI2RCB
-
CLIv2 Request Control Block
• MTDPCB
-
MTDP Control Block
DBCAREA
The DBCAREA is the communication structure between an application and CLI. Applications
use it to forward control and data information. CLI uses it to return control and data
information.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
27
Chapter 1: Introduction to CLI
CLI Data Structures
An application may use a single DBCAREA or multiple DBCAREAs. CLI retains no
knowledge of a particular DBCAREA across multiple CLI calls. CLI is concerned only with the
values for DBCAREA that are meaningful to the routine called.
DBCAREA Extensions
A DBCAREA extension is addressed by a DBCAREA and allows specialized applications to
provide additional information to CLI. The extensions may be chained together, allowing
more than one extension for a single request.
System Parameter Block
The CLI System Parameter Block (CLI2SPB), the internal SPB, is a data structure that is
examined during initialization. During initialization, any DBCAREA values not set in the
clispb.dat file by the user will default to the values contained in CLI2SPB.
On the release media, the accessible SPB file is named clispb.dat and contains the required
system-specific defaults when a DBCAREA is initialized. The values are specified with
mnemonic field specifiers to permit flexible organization of data in the SPB file.
Application Control Block
The CLI Application Control Block (CLI2ACB) is an internal application-transparent area
used to maintain the list of session control blocks (SCBs). As each SCB is created, it is inserted
into the list of open SCBs pointed to by the ACB.
Session Control Block
The CLI Session Control Block (CLI2SCB) is an internal application-transparent area used to
maintain the context of a session. When a logon is performed, an SCB is created to contain the
session identifiers and the list of requests posted to the session, as well as the session state and
associated information.
Request Control Block
The CLI Request Control Block (CLI2RCB) is an internal control block used to maintain the
context of a request. When a request is posted to a session, an RCB is created to contain the
request identifiers, the request state, and pointers to the request and response buffers
associated with the request. The RCB is inserted in a queue of RCBs attached to a session’s
SCB.
MTDP Control Block
The MTDP Control Block (MTDPCB) is an internal data structure used by CLI to
communicate with MTDP. Requested functions within MTDP, and information necessary to
execute those functions, are communicated by the MTDP control block.
28
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 1: Introduction to CLI
Communicating with Teradata Database
Communicating with Teradata Database
Information flow between an application and Teradata Database is as follows:
•
The application sends requests containing Teradata SQL statements and data to Teradata
Database.
•
Teradata Database performs the activities requested by the application, such as selecting,
updating, inserting, and deleting data, and returns response information to the
application.
Sessions
A session is an authenticated, logical connection between an application and Teradata
Database. Sessions are explicitly connected and disconnected, and while connected provide
the vehicle for all communication between the application and Teradata Database.
Teradata Partitions
Teradata Database supports several different types of request processors, which are known as
partitions. A partition is specified when a session is established by the CLIv2 Run String
addressed in the DBCAREA. CLI operates identically for all partitions. Although the structure
of requests and responses is the same for all partitions, the contents vary by partition. The
following partitions are supported by the system for general use:
Partition
Action Taken
DBC/SQL
processes SQL requests
EXPORT
used by FastExport utility
HUTCTL and HUTPARSE
used by ARC utility
FASTLOAD
used by FastLoad utility
MLOAD
used by MultiLoad utility
MONITOR
processes performance monitor requests
The remaining chapters of this manual assume use of the DBC/SQL partition.
Requests and Responses
Requests are sent by an application to a Teradata Database to initiate an action. Responses are
sent by a Teradata Database to the application to reflect the results of that action. Both
requests and responses are associated with an established session. One or more Teradata SQL
statements that are submitted to the Teradata Database at the same time are called a Teradata
SQL request.
Having several statements carried in the same request saves message transfer time. This is
important to CPU- and I/O-bound programs or sites because a two-statement multiTeradata Call-Level Interface Version 2 Reference for Network-Attached Systems
29
Chapter 1: Introduction to CLI
Communicating with Teradata Database
statement request uses half the local (not the Teradata Database) CPU time of two single
statement requests.
Most requests contain all of the data needed for their completion, but a few require additional
data. For example, requests that either insert a large database field, such as a picture, or define
a program to run within the database, first prompt CLI to supply the data or program. The
application then continues the request by providing the data or program.
Parcels
Parcels are the basic unit of information for requests and responses. Although CLI allows
applications to manipulate request parcels directly, most applications let CLI handle them
internally. However, applications must process responses parcel by parcel. Each type of parcel
is uniquely identified by its flavor. The flavor and format of parcels, and the processing of
response parcels of interest to applications, are described in the following chapters.
Three response parcels (ElicitData, ElicitFile, and ElicitName) prompt CLI to provide
additional information needed to complete requests. CLI continues the request by providing
the additional information.
Large Objects
Normal fields in a database table are limited to 64000 bytes. To allow for significantly larger
fields, such as audio or video data, large object (LOB) fields are supported. Since their data
may exceed the maximum statement size, instead of including the entire LOB in the initial
request it may be deferred using the AS DEFERRED phrase in the USING row descriptor for
the request string: for example, (USING BLOB AS DEFERRED) or (USING BLOB AS
DEFERRED BY NAME). Teradata Database then includes an ElicitData or ElicitName parcel
in the response to prompt the CLIv2 application to provide the LOB. For more information,
see Chapter 17: “Large Objects (LOB) Support.”
Programs Executed within the Database
Certain aspects of SQL statements can result in a user-defined program being executed within
Teradata Database. Such a program must first be defined using SQL, such as CREATE
FUNCTION, CREATE METHOD, or CREATE PROCEDURE statements, which result in an
ElicitFile parcel in the response to prompt CLI to provide the program's source.
All-Or-Nothing Property
Teradata SQL INSERT statements can be used to add rows of data to a table. They are similar
to the write statements used to add records to a file. Teradata SQL SELECT statements can be
used to read rows of data from a table. Occasionally, an application requires that a set of
Teradata SQL statements must all be complete or all be backed out.
Example
If money is being transferred from one account to another, the UPDATE statement that
subtracts the amount from the first account and the UPDATE statement that adds the amount
to the second account must both take place or neither take place.
30
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 1: Introduction to CLI
Parallel Teradata Database Operations
Statements and Transactions
The application can enforce the all-or-nothing property described above, but it is much
simpler to have the Teradata Database enforce it. The system will enforce the all-or-nothing
property if it has the information that one or more statements constitutes a transaction. If one
of the statements in a transaction fails, the system aborts the transaction and returns any
database that was affected to the state it would have been in if the transaction had not been
submitted.
Teradata Transaction Semantics
Two modes of transactions are available:
•
Teradata
•
ANSI
If you are using Teradata transaction semantics, there are two types of transactions that differ
in the way the application identifies which statements are to share the all-or-none property.
•
Explicit
•
Implicit
All three methods result in all the statements being backed out if any statement fails.
In this transaction type is...
The application...
Explicit (user-generated)
precedes the statements by a Teradata SQL BEGIN TRANSACTION
statement and follows them with a Teradata SQL END
TRANSACTION statement.
Implicit
submits the statements as a single request
ANSI Transaction Semantics
If you are using ANSI transaction semantics, the first request begins a transaction implicitly.
All subsequent requests are part of the transaction until one of the following events occurs:
•
SQL COMMIT statement
•
SQL ROLLBACK statement
•
LOGOFF statement
•
Failure response
A failure response rolls back only the statement causing the error unless that error threatens
the integrity of the database, in which case the entire transaction is rolled back.
Parallel Teradata Database Operations
The Teradata Database automatically manages processors to optimize the processing of an
application-initiated Teradata SQL request. No special programming is necessary to take
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
31
Chapter 1: Introduction to CLI
Parallel Teradata Database Operations
advantage of these parallel processing capabilities. Performance improvements can be
achieved by programming an application to overlap the processing of more than one Teradata
SQL request at a time.
The following sections discuss three programming techniques that enable an application to
overlap the processing of several Teradata SQL requests:
•
Multi-statement management
•
Multi-thread management
•
Multi-session management
Multi-Statement Management
A single Teradata SQL request consists of one or more Teradata SQL statements. The system
executes these statements in parallel.
Multi-Thread Management
Note: A thread, in the context of CLI, is an open request on a Teradata Database session.
How It Works
Multi-threading involves having two or more requests open on a single session. The
application program can intersperse calls to DBCHCL for the Initiate Request function and
calls to DBCHCL for the Fetch function. In this way it can submit new requests while
examining responses from older requests.
The application opens the request by calling DBCHCL for the Initiate Request function. The
request is considered open until the application calls DBCHCL for the End Request function.
Two rules apply to multi-threading operations:
•
No more than one Teradata SQL request can be active at one time per session, with the
following exception: an abort request and a disconnect request are accepted on a session
that has some other request active.
•
No more than sixteen Teradata SQL requests on the Teradata Database can be open at one
time (per session).
Multi-thread management supports techniques functionally similar to multi-session
techniques, but on a single session.
Identifying a Request
The application program may identify a request by its session number and request number, or
by assigning it a token which is used with DBCHWAT and a request number. The request
number is the input argument for subsequent Fetch, Rewind, and EndRequest operations
against the request.
DBCHCL maintains response buffer context such as current position and amount of data in
the buffer. Thus, the application can fetch the response data from any open request and/or
initiate other requests, as desired.
32
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 1: Introduction to CLI
Parallel Teradata Database Operations
Example
An application might initiate a request that contains a SELECT statement to return several
response rows. The application might fetch a response row, and initiate a request that contains
an UPDATE for that row.
Another response row could then be fetched, and another UPDATE sent. The results of the
UPDATE could be checked when desired. The application need only keep track of the request
number.
Multi-Session Management
An application can achieve true parallel request processing by using more than one Teradata
Database session. The application can then dispatch several requests simultaneously, one on
each session.
How It Works
Each concurrent request can be identified to CLI by using the id of the session with which it is
associated (that is, the value in Output Session Id from a call to DBCHCL for the Connect
function) and its own id (that is, the value in Output Request Id from a call to DBCHCL for
the Connect, Initiate Request, or Run Startup function).
Using Tokens
The application may also supply a token for each request when it is initiated. That token is
returned by the DBCHWAT routine when a request’s response arrives.
An application may have requests pending on several sessions simultaneously. One way for the
application program to wait is to call an asynchronous wait using DBCHWAT. The wait ends
when any outstanding request completes.
Using Fetch
An alternate way for the application to wait is to call a synchronous wait using DBCHCL for
the Fetch function, using the session id of an active session. The wait ends when the specified
session completes.
Usage Notes
On the one hand, the problem with this method is that the application cannot know which of
the active sessions will complete first. On the other hand, an asynchronous wait (calling
DBCHWAT) maximizes throughput by reducing session idle time. The application can handle
the response and dispatch another request as soon as the session completes.
The application calls DBCHWAT, which determines which requests are active and waits for
any of them to complete. When a request completes, DBCHWAT returns to the caller the
session identifier and optional user-specified token associated with the completed request.
The application can then handle the response, dispatch another request, and again call
DBCHWAT.
Windows presently supports a maximum of 320 sessions (for a single process). Linux has a
maximum session limit of 1024 (for a single process). All other UNIX-based operating
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
33
Chapter 1: Introduction to CLI
Common Routines Supporting CLI
systems set the session limit based upon the maximum number of file descriptors returned
from the ulimit UNIX command.
Considering Alternative Approaches
Prior to considering a multi-session approach, the application programmer should determine
whether multi-statement requests on a single session satisfy throughput and response time
requirements.
A multi-session application is much more complicated to implement, debug, and maintain.
But CLI provides facilities to assist implementation of multi-session applications.
Common Routines Supporting CLI
There are three common routines that support CLI. They enable the user to initialize the
DBCAREA and CLI, send requests, fetch responses, disconnect and terminate a session. See
Figure 1 on page 27.
DBCHINI
DBCHINI is the routine that initializes the DBCAREA that is shared by your application
program and most CLI routines. DBCHINI also does the internal initialization of CLI.
DBCHCL
DBCHCL is the routine used for each interaction with the Teradata Database. It is used to
connect and log on to the database computer to send SQL statements, to receive responses (for
example, rows from a table) and to disconnect and log off.
DBCHCLN
DBCHCLN is the routine used for cleanup after your application program is finished using
the Teradata Database.
When your application calls DBCHCLN and the return code is zero, data structures allocated
internally during the calls to CLI routines are de-allocated. At this point, if space is at a
premium, de-allocate the DBCAREA.
34
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 1: Introduction to CLI
Using the DBCAREA
Figure 2: CLI Routine Sequence
Begin Program
Initialize
Call DBCHINI
Connect
Call DBCHCL
Initiate Request
Call DBCHCL
Fetch Response
Call DBCHCL
End Request
Call DBCHCL
Disconnect
Call DBCHCL
Terminate
Call DBCHCLN
End Program
2418A005
Using the DBCAREA
An application can handle the DBCAREA in two ways. The application can use:
•
One DBCAREA for all the requests or a separate DBCAREA for each request, or
•
Any combination in between.
This choice is available for either multi-sessions or multi-threads.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
35
Chapter 1: Introduction to CLI
Setting Alarms and Signals
One DBCAREA
If the application program is facing space limitations, then one DBCAREA can be reused (at
the expense of added cpu time). This entails copying the Output Request Ids, saving them,
and replacing them when doing a Fetch, Rewind, or Cancel against that same Teradata SQL
request. If other fields, such as the processing options or buffer addresses or sizes, change from
one request to another, they too must be saved and replaced. Because much less information
than the whole DBCAREA is saved, the application program can show a significant saving of
space at the small cost of unloading and reloading those fields between calls.
Multiple DBCAREAs
If the application program is able to spare the space for multiple DBCAREAs, the application
program can allocate one DBCAREA per concurrent request. This saves time, at the cost of the
space for the extra DBCAREAs.
Setting Alarms and Signals
It is not possible to set alarms or other signals within the user’s CLI program. Doing so will
result in the following error message:
MTDP: EM_BREAK(218): Break was hit
Handling Password Expiration
When the application sends out the logon request with an expired password, a conditional
session is established with the Teradata Database. The only Teradata SQL action that the
application can take is to submit a MODIFY USER statement that assigns a new password to
the user.
If a logon is attempted for a user with an expired password, and if there is already a session
logged on for that user, the logon attempt receives a failure notification and the session is not
established.
Submitting a New Password
To submit a new password for the user using a CLI application, all previously established
sessions with the user need to be terminated.
Submit an application as follows:
36
•
Log on to the Teradata Database with the old username and password
•
Submit a MODIFY USER statement which assigns a new password to the user.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 2
Session Operations
This chapter describes how an application and the Teradata server interact through CLI:
•
Preparing to Use CLI
•
Setting/Using the DBCAREA Options
•
Establishing a Session
•
Executing Startup Requests
•
Submitting a Request
•
Fetching the Response
•
Continuing a Teradata SQL Request
•
Ending a Request
•
Aborting a Request
•
Terminating a Session
•
Cleaning Up CLI
•
Single Session Example
•
Multiple Session Example
•
Options Processing
Preparing to Use CLI
The application must first establish a storage area referred to as the DBCAREA. The
DBCAREA is the communication structure between the application and CLI.
DBCHINI
The DBCAREA is initialized by clearing all fields and then copying the options fields from the
clispb.dat file to the options fields of the DBCAREA. Any options not found in the clispb.dat
file are copied from the internal CLI System Parameter Block. Control is returned to the
application program and the interface is now ready to establish a session. If the return code in
the DBCAREA is not normal, a major system error has occurred and the application will not
be able to proceed.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
37
Chapter 2: Session Operations
Setting/Using the DBCAREA Options
How Many DBCAREAs to Use?
An application can use one DBCAREA for all the requests or a separate DBCAREA for each
request, or use any combination. This choice is available for either multi-sessions or multirequests.
If the application is...
Then you can...
Facing space limitations
Reuse the one DBCAREA. This involves copying the Output
Request Ids, saving them, and replacing them when doing a Fetch,
Rewind, or Cancel against the same Teradata SQL request.
In other fields, like the processing options or buffer addresses or
sizes, to change from one request to another, the previous
information must be saved and replaced. Because much less
information than the whole DBCAREA is saved, the application
can show a significant saving of space at the small cost of
unloading and reloading those fields between calls.
Able to spare the space for
multiple DBCAREAs
Allocate one DBCAREA per concurrent request. The application
can show some saving of time at the cost of the space for the extra
DBCAREAs.
Multi-threaded
Allocate one DBCAREA per thread. This is generally a
requirement while using multiple threads, because the sharing of
DBCAREAs by multiple threads would cause simultaneous
updates to the DBCAREA, mixing session results.
Setting/Using the DBCAREA Options
The DBCAREA contains option values used by the CLI routines. These options are initially set
by DBCHINI based on the values provided in the clispb.dat file. The path of this file can be
exported to CLI by using the COPLIB environment variable. During the installation of CLI, a
sample clispb.dat file is installed. If a value for a particular option is not mentioned, a default
value is taken from the CLISPB control structure.
The application may alter any of the DBCAREA options as necessary for the particular
processing required. Not all options (and in some cases, none) are used by all calls to CLI.
Before calling any CLI common routines (except DBCHINI), applications can indicate to CLI
a change in option values by setting the Change Options field to “Y”. All options will be copied
by CLI from the DBCAREA fields. CLI will verify the settings for the options as necessary.
Change Options
The CONNECT function always validates and saves the DBCAREA options. The options
remain in effect until another CONNECT function is requested or until the values are
changed by an Initiate Request or a RunStartUp function call.
38
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Establishing a Session
Miscellaneous Functions
The Disconnect, Fetch, Rewind, Abort, and End Request functions reference the options set by
the last Connect, Initiate Request, or RunStartUp function executed.
Maximum Parcel Option
Newer databases are being defined with fields or rows greater than 32767 bytes. As a result,
applications need to support larger parcel sizes. We recommend that the Maximum Parcel
option be set to “H” for all future applications, indicating that the application can support
parcel sizes greater than 32767 bytes. CLI now supports a parcel size of 1048500.
When using Move Mode, you may need to increase the Fetch Maximum Data Length to
accommodate the larger parcels.
Language ID Option
Applications can receive messages in either English or Japanese by setting the dbcniLid field.
Language
ID
English
EN
Japanese
JA
Additional information about supported languages can be found in “Language Id” on
page 112.
Establishing a Session
Before logging a session, check for entries of COPs in the following files:
•
/etc/hosts on UNIX systems
•
%windir%\system32\drivers\etc\hosts on Windows systems
If Distributed Name Service (DNS) is enabled, these files will be resident on the appropriate
DNS servers.
If a Teradata Database has four COPs that can be connected to, the COP entries in the hosts file
should look as follows:
[IP address of NODE1]
NODENAMEcop1
[IP address of NODE2]
NODENAMEcop2
[IP address of NODE3]
NODENAMEcop3
[IP address of NODE4]
NODENAMEcop4
Note: NODENAME should be the same for all the nodes.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
39
Chapter 2: Session Operations
Establishing a Session
CLI assumes that the COP entries are serial, cop1, cop2, cop3..., cop100. If the environment
variable is set, CLI will keep connecting the COPs until the value specified in the environment
variable is reached.
Example:
[IP address of NODE1]
NODENAMEcop1
[IP address of NODE2]
NODENAMEcop2
[IP address of NODE5]
NODENAMEcop5
[IP address of NODE6]
NODENAMEcop6
In the above example, CLI will ignore NODE5 and NODE6 and connect all requested sessions
to NODE1 and NODE2.The performance of the logon process can be improved by setting an
environment variable with the name equal to the machine (NODENAME) name, and by
specifying the number of COPs available for it. In the previous example, if an environment
variable NODENAME with a value of 3 exists before initiating the first CONNECT request,
CLI will try to connect to the first three nodes only. In the previous example, if an
environment variable NODENAME with a value of 3 exists before initiating the first
CONNECT request, CLI will try to connect to the first three nodes only. However, if an
environment variable NODENAME with a value of 7 exists, CLI will try to connect all
available notes, NODE1, NODE2, NODE5, and NODE6, in this case.
Before establishing a session, check for Teradata service entries in the following files:
•
/etc/services on UNIX systems
This file should contain the following entries:
tdmst - 1025/udp
If the gateway service on a NODE is configured to listen on a port other than 1025, these
entries should be modified to reflect the port on which the gateway is listening. Another way
of changing the default tdmst port (1025) is to set the environment variable TDMSTPORT to
the appropriate port. CLI and the gateway must use the same port for communication.
In the DBCAREA, the application program provides a pointer to the logon string, its length,
and, optionally, a pointer to the run string (partition name) and its length. The application
program provides the maximum length of the Request Buffer and Response Buffer in the
DBCAREA. Optionally, it modifies the processing options in the DBCAREA. It then sets the
function code in the DBCAREA to DBFCON and calls DBCHCL.
DBCHCL
DBCHCL obtains and initializes the CLI2SCB. If the application has specified that options
values in the DBCAREA are to be used, the options are copied from the DBCAREA to the
System Control Block (SCB); otherwise, options are copied from the System Parameter Block
(SPB). A Request Control Block (RCB) is then allocated and initialized for the logon sequence.
The application may provide token identifiers for its own use when starting a request or a
session; the value of this DBCAREA field will be copied to the logon RCB and will be returned
whenever the logon request is referenced.
40
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Executing Startup Requests
DBCHCL obtains and initializes request and response buffers. DBCHCL prepares a Logon
parcel and a Run (or Connect) parcel in the Request Buffer. The request is sent to MTDP.
MTDP
MTDP obtains from the Teradata Database the address of the COP to which the session is
assigned, connects to that COP, logs on to the database computer, and connects to the
partition requested. MTDP then returns control to DBCHCL.
DBCHCL
If the connection in MTDP is successful, and the wait for data options flag has been set to Y,
MTDP is called again to wait until the logon response is received. In any event, an error or
success message is generated in the message field of the DBCAREA and DBCHCL returns
control to the application program.
Application
If the return code in the DBCAREA is not normal, the application makes the appropriate
changes and re-submits the DBCAREA to DBCHCL. If the application program plans to run
multiple sessions concurrently, it saves the session id from the DBCAREA.
The interface is now ready to accept the execution of the startup request or the submission of
regular Teradata SQL requests.
Executing Startup Requests
An option, usually taken by interactive programs, allows the application program to execute
the user’s startup request, which is a Teradata SQL request that was stored earlier with the data
base. In the DBCAREA, the application:
•
Supplies the session id, if the DBCAREA has been used for any other session since last used
for this session
•
Supplies the length of and a pointer to the input data, if the STARTUP string contains a
Teradata SQL statement with a USING modifier
•
Changes the setting of the processing options
•
Supplies the length of and a pointer to the Move area, if the Move Mode processing option
was chosen
•
Supplies the function code to the Run Startup Request (DBFRSUP)
The application then calls DBCHCL.
DBCHCL
DBCHCL prepares either a RunStartup, IVRunStartup or FMRunStartup parcel in the
message body of the Request Buffer depending on the value of the Record Mode options flag,
and then prepares a Resp or KeepResp parcel depending on the value of the Keep Mode flag,
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
41
Chapter 2: Session Operations
Submitting a Request
and a Data or Indic data parcel if the Teradata SQL request contained a Teradata SQL
statement with a USING modifier in the Request Buffer.
In the MTDP Control Block, DBCHCL provides a pointer to the Request Buffer and the
length including the LAN header structure, of the data in the buffer, provides the length of and
a pointer to the Response Buffer, sets the selfrecov option (if needed), and sets the function
code to MTDPSTA. DBCHCL then calls MTDP.
MTDP
MTDP prepares and sends a Start Request message to the Teradata Database. It then returns
control to DBCHCL.
DBCHCL
If the return code in the MTDP Control Block is normal and the wait data option for the run
startup request is set to Y, DBCHCL sets the wait data option in the MTDP control block to
TRUE, sets the function code to MTDPRET, and calls MTDP.
MTDP
MTDP checks to see if the Start Response message has been received from the Teradata
Database. With the wait data option set to “on,” MTDP will wait for the arrival of the Start
Response message and then return control to DBCHCL.
DBCHCL
Based on the return code in the MTDP Control Block, DBCHCL generates an error or success
message string in the message field of the DBCAREA and DBCHCL returns control to the
application program.
Application
If the return code in the DBCAREA is not normal, the application program makes the
appropriate changes and re-submits the DBCAREA to DBCHCL, as above. Otherwise, the
application program saves the request id if the application program plans to use the
DBCAREA for any other request concurrently. The application consumes the Teradata SQL
response as it would any other, see below. The interface is then ready to process regular
Teradata SQL requests.
Submitting a Request
In the DBCAREA, the application program:
42
•
Supplies the session id if the DBCAREA has been used for another session since last used
for this session
•
Supplies the maximum Request Buffer and Response Buffer lengths if the DBCAREA has
been used with other lengths since they were last set
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Submitting a Request
•
Supplies the length of, and a pointer to, the Teradata SQL request. The combined request
and data with a USING modifier should not exceed 32500 bytes for a 32K buffer, 65000
bytes for a 64K buffer, or 1048500 for a 1M buffer.
•
Supplies a pointer to and the data for the USING modifier if the Teradata SQL request
contained a Teradata SQL statement with a USING modifier
•
May change the settings of the processing options
•
Sets the function code to DBFIRQ
•
Calls DBCHCL
DBCHCL
If a request is currently active on the session specified by the session identifier fields of the
DBCAREA:
•
Function field of the MTDP control block is set to MTDPRET
•
Session and request identifier fields of the MTDPCB are set to the active session and
request identifiers
•
Waitdata option is set according to the value of the DBCAREA waitdata option flag
•
MTDP is called to wait for completion of the active request
MTDP
MTDP checks if the specified request has completed, and, if the waitdata options flag is true,
waits until the response message for the prior request arrives or an error occurs, and then
returns control to DBCHCL.
DBCHCL
If an active request was completed, the state flag of its RCB is posted as pending, making the
request available for fetches.
Using the information in the DBCAREA, DBCHCL:
•
Creates an RCB for the new request
•
Inserts it at the head of the request lists on the associated SCB
•
Fills in its options fields from either the SCB of the associated session or the DBCAREA if
the set options flag is set to Y. allocates request and response buffers based on the lengths
specified in the DBCAREA or, if none are given, the default lengths specified in the
CLI2SPB
•
Loads the Request Buffer with parcels:
•
A Req, FMReq or IndicReq parcel depending on the Record Mode option flag,
containing the Teradata SQL request
•
One Data or IndicData parcel if the Teradata SQL request contained a Teradata SQL
statement with a USING modifier
•
A Resp or KeepResp parcel containing the length of the Response Buffer
In the MTDP Control Block, DBCHCL:
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
43
Chapter 2: Session Operations
Fetching the Response
•
Provides the length of and a pointer to the Request Buffer
•
Provides the length of and a pointer to the Response Buffer
•
Modifies the selfrecov option (if needed).
•
Sets MTDPSTA in the function code of the MTDP Control Block
•
Assigns a request id
•
Calls MTDP
MTDP
MTDP submits a Start Request message to the Teradata Database, and returns control to
DBCHCL.
DBCHCL
Based on the value returned from MTDP:
•
An error or success message is generated and returned to the application in the message
field of the DBCAREA
•
The logical request identifier is returned in the request substructure of the DBCAREA
•
DBCHCL returns to the application
Application
If the return code in the DBCAREA is not normal, the application makes the appropriate
changes and re-submits the DBCAREA to DBCHCL, as above. Otherwise, the application
saves the request id if the application program plans to use the DBCAREA for any other
concurrent request. The interface is ready for the application to consume the Teradata SQL
response.
Fetching the Response
The response can be single or double buffered. The response can also be used as returned,
rewound, or repositioned. The response can be rewound only if DBCAREA option keep_resp
is set to 'P' or 'Y' while initiating a request. The response can be repositioned only if the
DBCAREA keep_resp is set to 'P' and cursor repositioning is supported at the Teradata
Database.
No Rewinding, Single Buffering
The following information applies if the application chose single-buffering when initiating the
request, and is choosing now to see the response without rewinding it.
Application
In the DBCAREA, the application supplies the session id and request id of the request from
which data is to be fetched and sets the function code to DBFFET.
44
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Fetching the Response
If the request was submitted with the Move Mode processing option, the application program
must also supply the length of and a pointer to the response area in the DBCAREA. DBCHCL
is then called to perform the fetch.
DBCHCL
DBCHCL first determines whether options flags are to be taken from the RCB of the specified
request or from the set options flag of the DBCAREA. If set options flag is Y, options are taken
from the DBCAREA, otherwise the options in the RCB are used.
If the next unit of response is not in the Response Buffer, DBCHCL:
•
Supplies the session and request identifiers for the specified request in the MTDPCB
•
Constructs a continue request in the request buffer for the request by creating a Resp or
KeepResp Parcel
•
Sets the function code of the MTDPCB to MTDPCONT
•
Calls MTDP
MTDP
MTDP sends a Continue Request message to the Teradata Database. It then returns control to
DBCHCL.
DBCHCL
If the specified request is active, DBCHCL:
•
Supplies the session id and request id of the active request in the MTDPCB
•
Sets the waitdata option flag according to the input options waitdata value
•
Sets the function code to MTDPRET
•
Calls MTDP
MTDP
MTDP checks if the request has completed, and, if waitdata is TRUE, waits until the response
message for the prior request arrives or an error occurs, and then returns control to DBCHCL.
DBCHCL
If all prior calls to MTDP have returned successfully, DBCHCL checks for a buffer overflow; if
one is found, the buffer is grown to accommodate the larger response, and the request is
continued. DBCHCL makes the next unit of response available to the application program by
locating the next parcel and returning it to the application either through a pointer into the
response buffer, or, if Move Mode has been specified, by copying the parcel into the buffer
provided by the application and pointed to be the data field of the DBCAREA.
Application
If the return code or error flag in the DBCAREA are not normal, the application makes the
appropriate changes, and re-submits the MTDP Control Block to DBCHCL, as above.
Otherwise, it consumes the unit of response. Typically, the application loops back for another
unit of response until the EndRequest parcel is obtained.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
45
Chapter 2: Session Operations
Fetching the Response
Rewinding, Single Buffering
The following information applies if the application chose single-buffering when initiating the
request and sets keep-response to 'Y', and is now choosing to rewind the response and review
it.
Application
In the DBCAREA, the application:
•
Supplies the session id and request id of the response required
•
Supplies the length of and a pointer to the response area, if the request was submitted with
the Move Mode processing option
•
Sets the function code to Rewind and Fetch (DBFREW)
•
Calls DBCHCL
DBCHCL
If the specified session is active:
•
The RCB for the active request is located
•
The waitdata options flag for the request is passed to MTDP in the MTDPCB along with
the session and request identifiers
•
MTDP is called to check for or wait for completion of the request
If the request did not complete successfully an error message is returned to the application.
If the current response buffer is the first buffer for the request, the buffer pointer is reset to the
top of the buffer and DBCHCL returns successfully to the application. If KeepResp had not
been specified for the request and the response buffer contains an EndRequest parcel,
DBCHCL returns with a message indicating it cannot rewind the response. Otherwise,
DBCHCL places a Rewind parcel and either a KeepResp or Resp parcel (depending on the
KeepResp processing option value) in the request buffer for the request, supplies the session id
and request id of the specified request in the MTDPCB, sets the MTDPCB function code to
MTDPCONT, and calls MTDP.
MTDP
MTDP sends a Continue Request message to the Teradata Database. It then returns control to
DBCHCL.
DBCHCL
A success or error message is generated in the message field of the DBCAREA and DBCHCL
returns to the application.
Application
If the return code or error flag in the DBCAREA are not normal, the application makes the
appropriate changes, and re-submits the DBCAREA to DBCHCL, as above. Otherwise, it
performs a fetch as for the no-rewind case and consumes the unit of response. Typically, the
application loops back for another unit of response until the EndRequest parcel is obtained.
46
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Fetching the Response
No Rewinding, Double Buffering
The following information applies if the application has chosen double buffering when
initiating the request, and is now choosing to see the response without rewinding.
Application
In the DBCAREA, the application:
•
supplies the session id and request id of the response required
•
sets the function code to DBFFET
•
supplies the length of and a pointer to a response area, if the request was submitted with
the Move Mode processing option
•
calls DBCHCL
DBCHCL
DBCHCL first determines whether to use the DBCAREA or the RCB for the specified request
when testing options by testing the set options flag of the DBCAREA. If it is Y, the DBCAREA
options are used; otherwise, the RCB options are used. If the current response buffer has been
consumed and the EndRequest parcel has not been received, MTDP is called with the request
and session identifiers, the MTDPRET function, and the waitdata options set according to the
waitdata options flag value of the selected options area.
MTDP
MTDP checks if the specified request has completed, and, if it has not completed and the
waitdata option is set, waits until the response message for the prior request arrives or an error
occurs, then returns control to DBCHCL.
DBCHCL
If MTDP fails either because of a fault or because the wait data option was not set, DBCHCL
returns an error message to the application. Otherwise, the active response buffer becomes the
current buffer, and, if the current buffer does not contain an EndRequest parcel, the
previously current buffer becomes the active buffer and MTDP is called with the session and
request identifier fields of the MTDPCB set as before and the function field set to
MTDPCONT.
MTDP
MTDP sends a Continue Request message to the Teradata Database and returns to DBCHCL.
DBCHCL
If MTDP returns unsuccessfully, an error message is returned to the application. DBCHCL
makes the next unit of response available to the application program using the method chosen
by the application when the request was initiated, and returns control to the application
program.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
47
Chapter 2: Session Operations
Fetching the Response
Application
If the return code in the DBCAREA is not normal, the application makes the appropriate
changes, and re-submits the MTDP Control Block to DBCHCL, as above. Otherwise, it
consumes the unit of response. Typically, the application loops back for another unit of
response until the EndRequest parcel is obtained.
Rewinding, Double Buffering
The procedure for rewinding the double buffered request is identical to that for the single
buffered request, except that both buffers must be scanned for an EndRequest parcel to check
if a rewind can be performed for a no KeepResp request.
Repositioning, Single Buffering
The following information applies if an application chooses single-buffering and a request is a
single statement request. CLI will fetch the response in single buffering mode only; even if
double buffering is set and reposition of response is requested.
Application
In the DBCAREA, the application:
•
Supplies the session id and request id of the response required.
•
Supplies the length of and a pointer to the response area, if the request was submitted with
the Move Mode processing option.
•
Sets the DBCAREA fields positioning_action, positioning_value, and
positioning_stmt_number, as required.
•
Sets the function code to FETCH(DBFFET).
•
Calls DBCHCL.
DBCHCL
If the specified session is active and the Teradata Database to which the session is connected
supports Cursor Repositioning:
•
The RCB for the active request is located.
•
The waitdata options flag and other cursor repositioning flags are passed to MTDP with
session and request identifiers.
•
MTDP is called to check for or wait for completion of the request.
An error is returned to the application in the following scenarios:
•
If keep_resp is not set to 'P' while initiating the request.
•
The request did not complete successfully.
•
The requested reposition is invalid.
Otherwise, DBCHCL places a PclROWPOSITION/PclOFFSETPOSITION parcel in the
request buffer for the request, supplies the session id and request id of the specified request in
the MTDPCB, sets the MTDPCB function code to MTDPCONT, and calls MTDP.
48
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Fetching the Response
MTDP
MTDP sends a Continue Request message to the Teradata Database. It then returns control to
DBCHCL.
DBCHCL
A success or error message is generated in the message field of the DBCAREA and DBCHCL
returns to the application.
Application
If the return code or the error flag in the DBCAREA is not normal, the application makes the
appropriate changes, and re-submits the DBCAREA to DBCHCL, as above. Otherwise, it
performs a fetch as for the non-reposition case and consumes the unit of response. Typically,
the application loops back for another unit of response until the EndRequest parcel is
obtained.
Repositioning, Single/Double Buffered LOB Data
The following information applies if an application chooses to fetch LOB data in deferred
mode, using locators and choosing to reposition the response.
If double buffering is set and LOB data is fetched in deferred mode, CLI will fetch the response
in single buffering mode when initiating the request, and will fetch LOB data in deferred
mode.
Application
•
Supplies the session id and request id of the response required.
•
Supplies the length of and a pointer to the response area, if the request was submitted with
the Move Mode processing option.
•
At the time of initiating the request, application has to set the DBCAREA fields resp_mode
to 'M' and return_object to 'S' or 'T', depending on whether Static (spool locators) or
transaction locators are to be returned.
•
Sets the function code to FETCH(DBFFET).
•
Calls DBCHCL.
DBCHCL
If the specified request is active, DBCHCL:
•
Supplies the session id and request id of the active request in the MTDPCB.
•
Sets the waitdata option flag, according to the input options waitdata value.
•
Checks if keep_resp is set to 'Y'. If not, an error message is returned to the application.
•
Sets the function code to MTDPRET.
•
Calls MTDP.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
49
Chapter 2: Session Operations
Continuing a Teradata SQL Request
MTDP
MTDP checks if the request has completed, and, if waitdata is TRUE, waits until the response
message for the prior request arrives or an error occurs, and then returns control to DBCHCL.
DBCHCL
A success or error message is generated in the message field of DBCAREA and DBCHCL
returns to the application.
Application
If an application is ready to receive binary large object (BLOB) data at this point:
•
It issues the SQL SELECT request, using the BLOB locator returned in a previous response
(e.g., USING (A BLOB AS LOCATOR) SELECT :A;).
Note: This select must be issued on the same session by the application.
•
CLI and the application handle the fetch request for this select the same way as in a normal
No Rewinding, Single Buffering fetch. See “No Rewinding, Single Buffering” on page 44.
Continuing a Teradata SQL Request
When an ElicitData, ElicitFile, or ElicitName response parcel is fetched, Teradata Database
requires additional information to complete the request. To provide that information, CLI
performs the following steps:
1
Modifies the DBCAREA.
a
Set the Function to 15 (ContinueRequest).
b
Set the Input CLI Session Id to the Output CLI Request Id returned when the session
was established.
c
Set the Input CLI Request Id to the Output CLI Request Id returned when the request
was initiated.
d
Set the Request Pointer field.
e
Set the Request Length field.
f
Optionally set the following fields:
g
2
50
•
Fetch Buffer Length field
•
Message Area Pointer field
•
Message Area Length field
Optionally set the Change Options option to 'Y', and set the following:
•
C2S Conversion option
•
Locate Mode option
•
Maximum Parcel option
Calls DBCHCL to perform the ContinueRequest function.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Ending a Request
3
4
Checks the return code from DBCHCL.
Return Code.
Result
0
Calls DBCHCL to perform a Fetch function to get the final status of the
rewind and the first part of the response. For more information, see “Fetching
the Response” on page 44.
anything else
Processes the return code and DBCAREA message.
Calls DBCHCL to perform the End Request function. For more information, see “Ending
a Request” on page 51.
Ending a Request
If the Teradata Database is processing a request submitted under the Resp processing option
and sends a Response Message that contains the last parcel of the Teradata SQL response, the
Teradata Database discards the Teradata SQL response and closes the Teradata SQL request.
If the Teradata Database is processing a request submitted under the KeepResp processing
option and sends a Response Message that contains the last parcel of the Teradata SQL
response, the Teradata Database keeps the Teradata SQL response and does not close the
Teradata SQL request.
If a Teradata SQL response is being held by the Teradata Database (because the last parcel has
not been sent or because the KeepResp option is in effect) and the application program no
longer needs the Teradata SQL response, the application program can have the Teradata SQL
response discarded and Teradata SQL request closed out. The next sections describe this
process.
Application
In the DBCAREA, the application supplies the session id and request id, if they have changed
since the DBCAREA was last used, and sets the function code to DBFERQ. It then calls
DBCHCL.
DBCHCL
DBCHCL first determines whether to use the DBCAREA or the RCB for the specified request
when testing options by testing the set options flag of the DBCAREA. If it is “Y,” the
DBCAREA options are used; otherwise, the RCB options are used. If the specified session is
active, MTDP is called with the session and request identifiers of the active request, the
function code set to MTDPRET, and the waitdata flag set according to the value of the selected
options area’s waitdata flag.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
51
Chapter 2: Session Operations
Aborting a Transaction
MTDP
MTDP checks if the specified request has completed, and, if it has not completed and the
waitdata option is set, waits until the response message for the prior request arrives, or an
error occurs, and then returns control to DBCHCL.
DBCHCL
If MTDP fails (either because of a fault or because the waitdata option was not set), DBCHCL
returns an error message to the application. DBCHCL builds a Cancel parcel in the message
body part of the Request Buffer, sets the function code in the MTDP Control Block to
MTDPCONT, and calls MTDP.
MTDP
MTDP sends a Continue Request message containing a Cancel parcel to the Teradata
Database, and returns control to DBCHCL.
DBCHCL
If the return code in the MTDP Control Block is not normal, DBCHCL returns an error
message to the application. Otherwise, in the MTDP Control Block DBCHCL sets the
waitdata option to “on” and sets the function code to MTDPRET. DBCHCL then calls MTDP.
MTDP
MTDP waits for the arrival of the Continue Response Message and then returns control to
DBCHCL.
DBCHCL
DBCHCL returns an error message to the application if the MTDP indicated a failure.
Otherwise, the buffers allocated for the requests are returned to the free memory pool, the
RCB is removed from the request list of its SCB and returned to free memory, and a success
message is returned to the application.
Application
If the return code in the DBCAREA is not normal, the application makes the appropriate
changes and re-submits the DBCAREA to DBCHCL, as above. Otherwise, the application
consumes the response.
Aborting a Transaction
Under some circumstances, such as the detection of a break key at a keyboard, the application
may want to stop and abort a transaction on a session.
52
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Aborting a Request
If a transaction is “between requests” that is, does not have an active Teradata SQL request, the
application program can abort the transaction by sending in a Teradata SQL request
containing a single Teradata SQL ABORT or ROLLBACK statement.
The request is submitted the same way as any other Teradata SQL request, described above.
When the transaction is aborted, the Teradata Database discards the Teradata SQL response
being held for any Teradata SQL request in the transaction, closes out all Teradata SQL
requests in the transaction, and backs out from the Teradata Database any effects of the
Teradata SQL requests in the transaction.
Aborting a Request
If a request is active or a transaction has an active request, the application program can
attempt to abort the request and transaction, if any. Such an abort is called an asynchronous
abort.
•
If the abort reaches the Teradata Database before the Start Response message is returned,
the Teradata SQL response in preparation is discarded, the active Teradata SQL request is
closed out, and any effect of the active Teradata SQL request and any other Teradata SQL
request in the transaction (if any) are backed out of the Teradata Database.
•
If the abort reaches the Teradata Database after the Start Response message is returned, the
abort does not take effect.
Aborting a LOB Request: Example
Applications can abort a deferred client to server transfer of LOB data or create a UDF request.
For example, assume a session has been created and a request transfer of LOB data in deferred
mode is initiated. If the application wants to abort the request, the DBCAREA field
continuation_code to 'C'. Then set the DBCAREA function code to DBFCRQ and call
DBCHCL
DBCHCL
DBCHCL allocates a request buffer and places a PclUCABORT parcel in the message body
part of the Request Buffer. DBCHCL places the session and Request Ids in the MTDPCB, sets
the function code to MTDPABOT, and calls MTDP.
MTDP
MTDP prepares and sends an Abort Request message to the Teradata Database, and waits for
the Abort Response message. MTDP then returns control to DBCHCL.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
53
Chapter 2: Session Operations
Aborting a Request: Example
DBCHCL
If the return code in the MTDP Control Block is not normal, DBCHCL returns the error
message pointed to by the DBCAREA to the application. Otherwise, the buffers allocated to
the request are returned to free memory and the RCB is removed from its RCB list and
returned to free memory.
If the return code or error flag in the DBCAREA is not normal, the application makes the
appropriate changes and then re-submits the DBCAREA to DBCHCL.
Aborting a Request: Example
Assume a session has been created and a request started as in the single buffering, no rewind
example given above. If the application wants to abort the request, the following must be
performed.
The application sets the function code to abort (DBFABT) in the DBCAREA and calls
DBCHCL.
Note: This implies that if the end-user may need to abort a request, the application must
submit the prior-pending request with the Wait For Response option set to no, so that the
application can get control before the start response is returned from the Teradata Database.
DBCHCL
DBCHCL allocates a request buffer and places an Abort parcel in the message body part of the
Request Buffer. DBCHCL places the session and Request Ids in the MTDPCB, sets the
function code to MTDPABOT, and calls MTDP.
MTDP
MTDP prepares and sends an Abort Request message to the Teradata Database, and waits for
the Abort Response message. MTDP then returns control to DBCHCL.
DBCHCL
If the return code in the MTDP Control Block is not normal, DBCHCL returns the error
message pointed to by the DBCAREA to the application. Otherwise, the buffers allocated to
the request are returned to free memory and the RCB is removed from its RCB list and
returned to free memory.
If the return code or error flag in the DBCAREA is not normal, the application program
makes the appropriate changes and then re-submits the DBCAREA to DBCHCL.
Terminating a Session
After all processing is complete for a session, the application should terminate the session.
54
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Cleaning Up CLI
Note: If a transaction is in progress at the time of the disconnect (that is, no ET has been
issued), the Teradata server will roll back any work done for the transaction.
Application
In the DBCAREA, the application supplies the session id of the session to be terminated and
sets the function code to disconnect (DBFDSC). Then it calls DBCHCL.
DBCHCL
DBCHCL generates a dummy request (including RCB and buffers). DBCHCL builds a Logoff
parcel in the message body part of the Request Buffer for the dummy request. DBCHCL then
sets the function code in the MTDP Control Block to MTDPLOFF and calls MTDP.
MTDP
MTDP terminates the session and then returns control to DBCHCL.
DBCHCL
All the requests attached to the disconnected session are removed by deallocating their buffers
and RCBs, and then the associated SCB are removed from the session queue and returns it to
the free memory pool. DBCHCL then returns a success code to the application program. If the
return code in the MTDP Control Block is abnormal, DBCHCL returns an error message to
the application.
Application
If the return code in the DBCAREA is not normal the application makes the appropriate
changes and re-submits the DBCAREA to DBCHCL, as described above. Otherwise, the
session is terminated.
Cleaning Up CLI
DBCHCLN is the CLI routine used to clean up all CLI memory. The following processes take
place when the application program no longer needs to use the Teradata Database.
Application
The application calls DBCHCLN. Calling DBCHCLN should be the last CLI call that the
process makes. See “DBCHCLN” on page 213 for more information.
DBCHCLN
A dummy DBCAREA is allocated and the DBFDSC function is invoked repeatedly for each
session opened by the application until all the sessions are logged off or an error occurs. An
error or success message is then returned to the application.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
55
Chapter 2: Session Operations
Single Session Example
Application
If the return code is not normal, the application makes the appropriate changes and resubmits to DBCHCLN. Otherwise, the application’s ties to the Teradata Database are gone.
Single Session Example
Each horizontal item in Table 1 represents a call to DBCHCL, with function code set as in the
left column.
Table 1: Single Session Sequence
Function
Description
Connect
Obtain CLI2SCB, CLI2RCB, buffers; send logon; and, if options so specify, await
completion; send run and return. Application must have set address and length of
logon string. All other arguments (buffer sizes, run string, and various other
arguments) are optional and will default if they are left unset.
Fetch
Fetch response data, either a Success or a Failure parcel.
Initiate Request
Send Teradata SQL request to the Teradata Database. Application must set address
and length of Teradata SQL request and optional using data. DBCHCL builds
request buffer (adds Response parcel) and sends request.
Fetch
Fetch response data. DBCHCL will return address and length of first parcel (or
buffer, if in Buffer Mode). If dual buffering was specified and the current buffer is
not the last response buffer, DBCHCL will immediately dispatch a continue request
to retrieve the next “buffer full of data”. Thus, the continue request process is
overlapped with consumption of the first buffer. If dual buffering is not in effect,
DBCHCL will dispatch the continue request when the current buffer is exhausted.
End Request
Clean up request-related context. Disconnect. Log off the Teradata Database and
free the session-related control blocks.
Multiple Session Example
Each horizontal item in Table 2 represents a call to DBCHCL with the function code set as in
the left column.
Table 2: Multiple Session Sequence
Function
Description
Connect/Fetch
Same as for a single session.
Note: A Connect and Fetch must be done for each session.
56
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 2: Session Operations
Options Processing
Table 2: Multiple Session Sequence (continued)
Function
Description
Initiate Request
(Session 1)
Send Teradata SQL request to the Teradata Database. Application must set address
and length of Teradata SQL request and optional using data. DBCHCL adds
response parcel and sends request. Application must save the output request and
output session identifiers.
Initiate Request
Same as for session 1, probably with different data.
(Session 2)
Fetch
Same as for a single session:
(Session 1 and 2) • Set DBCAREA. header. logsessid to id of session to be used.
• Set DBCAREA input session id of session to be used.
• Set DBCAREA input request id of request to be accessed.
End Request
Clean up request-related context. (Stream 1 and 2)
Disconnect
Log off the Teradata Database and free the session-related control blocks.
(for each session)
Options Processing
The application calls DBCHINI to initialize the DBCAREA. Before initializing it, DBCHINI
first parses the clispb.dat file, if it is being used. An error message is returned if any clispb.dat
options are illegal.
After regaining control from DBCHINI, the application’s DBCAREA is initialized with values
from clispb.dat, if it is being used, and from the CLI defaults for any values not supplied from
clispb.dat.
Setting Change Options to Y
If the value of Change Options in
the input DBCAREA is Y and...
Then...
Connect
then, in the SCB that is generated, all of the option values in the
input DBCAREA are copied to the SCB and in the RCB (internal
CLI Request Control Block) that is generated, all of the option
values in the SCB are copied to the RCB. Connect uses options
values from the RCB.
Run Startup or Initiate Request
none of the option values in the input DBCAREA are copied to
the SCB.
Rewind, Fetch, End Request, or
Abort
none of the option values in the input DBCAREA are copied to
the SCB or the RCB.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
57
Chapter 2: Session Operations
Options Processing
If the value of Change Options in
the input DBCAREA is Y and...
Disconnect
Then...
none of the option values in the input DBCAREA are copied to
the SCB or the RCB. Disconnect uses the value of Message
Security from the RCB. Values of the Wait Across Crash and Tell
About Crash are taken from the SCB.
Setting Change Options to N
If Change Option in the input
DBCAREA is N and the function
is...
Connect
Then...
then, in the SCB that is generated, all option values in the
internal defaults are copied to the SCB and none of the option
values in the input DBCAREA are copied to the SCB.
The internal defaults are either the initial values as provided by
the Teradata Database or, if available, the values read from the
clispb.dat file.
In the RCB that is generated, all of the option values in the SCB
are copied to the RCB and none of the option values in the input
DBCAREA are copied to the RCB. Connect uses option values
from the RCB.
Run Startup or Initiate Request
none of the option values in the input DBCAREA are copied to
the SCB.
In the RCB that is generated, all of the option values in the SCB
are copied to the RCB; none of the option values in the input
DBCAREA are copied to the RCB. Initiate Request and Run
Startup use option values from the RCB.
58
Rewind, Fetch, End Request, or
Abort
none of the option values in the input DBCAREA are copied to
the SCB. None of the option values in the input DBCAREA are
copied to the RCB. All option values are read from the RCB.
Disconnect
none of the option values in the input DBCAREA are copied to
the SCB or the RCB. Disconnect uses the value of Message
Security from the RCB. Values of the Wait Across Crash and Tell
About Crash are taken from the SCB.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 3
CLI Files and Setup
This chapter describes:
•
Finding CLI Files on the System
•
CLI Environment Variables
Finding CLI Files on the System
CLI is supported on Windows and UNIX operating systems. The files and libraries/DLLs
required for using CLI are installed at different locations on different platforms. Those files
that are essential for using CLI are described in this chapter. For complete information, refer
to the specific platform installation guide.
Files listed in this section are essential for CLI to work with any application.
Required Files for UNIX Platforms
Default Installation Directories
On all UNIX platforms, the default installation directory for:
•
32-bit files is /opt/teradata/client/<release_number>/lib
•
64-bit files is /opt/teradata/client/<release_number>/lib64
The installation path is added to LD_LIBRARY_PATH/LIBPATH/SHLIBPATH environment
variables.
errmsg.cat
This catalogue file contains the CLI error messages in localized form. This file is used by CLI
for populating the appropriate DBCAREA fields with CLI messages after each call to any of
the CLI common routines used by the applications.
libcliv2
This CLI library contains the CLI calls that are used by the applications to interface with the
server. On HP-UX, this library is named libcliv2.sl; on all other UNIX platforms, it is named
libcliv2.so.
libtdusr
This CLI library contains the user exit routines. For more information about exit routines, see
Chapter 16: “CLI Exit Functions.”
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
59
Chapter 3: CLI Files and Setup
CLI Environment Variables
Required Files for Windows Platforms
Default Installation Directories
•
On 32-bit Windows, the default installation directory for the files listed in this section is:
%ProgramFiles%\Teradata\ Client\<release_number>\cliv2
•
On 64-bit Windows, the default installation directory for 32-bit files is:
%ProgramFilesx86%\Teradata\ Client\<release_number>\cliv2
•
On 64-bit Windows, the default installation directory for 64-bit files is:
%ProgramFiles%\Teradata\ Client\<release_number>\cliv2
Note: 32-bit Windows CLI libraries are not supported on IA64 processors.
Localisation.dll
This file is used to generate the CLI messages. It is the equivalent to the UNIX file errmsg.cat.
tdusr32.dll
This is the equivalent to the UNIX library libtdusr.
terasso.dll
Supports session logins utilizing Single Sign-On.
wincli32.dll
This is the equivalent to the UNIX library libcliv2. Both 32-bit and 64-bit versions of this dll
exist.
Required Files for All Platforms
clispb.dat
This file is used to change SPB options and is installed during CLI installation.
Header files
CLIv2 header files are required for developing CLI-based applications. The files are provided
with the installation of 32-bit or architecture-independent packages on UNIX platforms and
32- and 64-bit packages on Windows.
CLI Environment Variables
The following variables are created during CLI installation.
CLI2EXITLVL
See Chapter 16: “CLI Exit Functions.”
60
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 3: CLI Files and Setup
CLI Environment Variables
COPERR
This CLI environment variable is used by CLI to determine the location of the errmsg.cat file.
This is used by CLI on UNIX platforms only. If this variable is not set to the location where the
errmsg.cat file exists and the file does not exist in /usr/lib, CLI prints the following message on
STDOUT and then exits:
CLI:Message catalog open failed!: No such file or directory
The file “errmsg.cat” cannot be opened.
There may be problems with your installation.
Exiting...
On UNIX platforms, CLI installation places an entry in /etc/profile and sets the value of this
environment variable to the installation directory.
COPLIB
This CLI environment variable is used to determine the path of clispb.dat. CLI installation
adds this variable to /etc/profile on UNIX platforms, and to system environment variables on
Windows platforms. If you modify the sample clispb.dat file provided during installation and
place it in a different location, you must change this variable to reflect the new file location.
Note: If the symbolic names of SPB fields in the clispb.dat file are invalid, CLI prints a warning
message, in English, on STDOUT that reads:
CLI ignored bad clispb.dat entry “entryname”
If the value provided for the SPB fields in clispb.dat is invalid, CLI exits printing a CLI-310
error. The message returned in the respective DBCAREA message field will always be in
English, no matter what value is set in the Language Id field.
The following variables are not created during installation.
COPANOMLOG, NETRACE, THREADLOGGING, and THREADONOFF
CLI uses these environment variables to decide whether to collect any CLI trace.
CLI provides three levels of tracing:
•
Minimal tracing without parcel dumps
•
Tracing with parcel dumps
•
Tracing on a thread basis (Windows platforms only)
COPANOMLOG
COPANOMLOG should be set to the file name in which the user intends to collect the trace.
On Windows platforms, the trace file name provided in the COPANOMLOG is appended with
a .txt extension.
The default maximum file size of a copanomlog is 250 MB. When this limit is reached, the
active log file is closed and a new file is opened with a four-digit number embedded in the file
name that grows by one each time a new file is opened. For example, if the COPANOMLOG
variable is set to "my_copalog" and a 787 MB log needs to be recorded, the following happens,
depending on the operating system:
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
61
Chapter 3: CLI Files and Setup
CLI Environment Variables
•
Unix
my_copalog, my_copalog_0001, my_copalog_0002, my_copalog_0003
•
Windows
my_copalog.txt, my_copalog.txt_0001, my_copalog.txt_0002, my_copalog.txt_0003
The COPANOMLOG_SIZE environment variable can change the maximum size of
copanomlog. Most operating systems support files up to 2 GB.
NETRACE
If the NETRACE variable is set, options become available in the level of logging details. These
options are available on a bit level, within the NETRACE variable. The NETRACE variable is a
16-bit value. The lowest order bit enables the incoming/outgoing parcel dumps. Each higher
order bit turns off the options. The only options available presently are:
NETRACE = 0: (or environment variable not set) incoming/outgoing parcel dumps are
disabled, only minimal tracing enabled.
NETRACE = 1: incoming/outgoing parcel dumps are enabled. This is the most detailed
logging option.
NETRACE = 3: incoming/outgoing parcel dumps are enabled, timestamps are disabled.
NETRACE = 5, 9, 17, etc. reserved for future options.
Note: Any enabling of additional logging features must have the lowest order bit set in
NETRACE. For example, all options must be odd, to enable the lowest order bit.
THREADLOGGING
If the THREADLOGGING variable is set, CLI trace is collected on a thread basis. For example,
if COPANOMLOG is set to c:\temp\coplog, three threads would create the following three files:
•
c:\temp\coplog0.txt
•
c:\temp\coplog1.txt
•
c:\temp\coplog2.txt
If logon encryption is enabled at the gateway, then connect messages collected in trace will be
encrypted.
If data encryption is enabled by applications for a request, then request and response messages
printed for that particular request in the trace will be encrypted.
On all other UNIX/Linux platforms, COPANOMLOG outputs can be recorded in different
files when thread logging. The only difference between the UNIX/Linux and the Windows
implementation of thread logging is that on UNIX/Linux platforms the output file names
contain a POSTFIX thread ID.
THREADONOFF Variable
The environment variable THREADONOFF turns multithreaded support on or off on UNIX
and Linux platforms. Setting the variable to 1 turns on multithreaded support; 0 turns it off.
62
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 3: CLI Files and Setup
CLI Environment Variables
Values other than 1 or 0 have no effect. The default value on UNIX and Linux is 0, that is,
multithreaded support is turned off.
TDMSTPORT
If the gateway to the Teradata server to which the application is trying to connect is listening
on a port other than the default of 1025, applications can set this variable to the appropriate
port. This can be done instead of changing the entry in the services file.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
63
Chapter 3: CLI Files and Setup
CLI Environment Variables
64
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 4
System Parameter Block (SPB)
Processing
This chapter contains information about:
•
Using the COPLIB Variable
•
System Parameter Block (SPB) File
•
The clispb.dat Listing
•
Overriding Values
•
Values Used by CLI: Summary
Using the COPLIB Variable
The SPB file is located by CLI with the environment variable COPLIB, which specifies the
directory path that contains the SPB file.
If the SPB file is not found, predetermined defaults provided by the internal SPB will be used.
Internal SPB
The application program does not directly access the internal SPB values stored in CLI. The
settings in the DBCAREA, after DBCHINI is called, are copies of the values contained in the
internal SPB and can be modified by the program.
The application program does not fail if the accessible clispb.dat file is missing. DBCHINI uses
the defaults in the internal SPB instead.
System Parameter Block (SPB) File
Accessible SPB
The accessible SPB file, clispb.dat, is provided on the release media. That file contains the
system specific defaults to be used when a DBCAREA is initialized. The values are specified
with mnemonic field specifiers to permit flexible organization of data in the SPB file.
Accessing clispb.dat
When the workstation portion of the COP Interface software is installed, the clispb.dat file is
modified and placed in a directory to which all applications have read access.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
65
Chapter 4: System Parameter Block (SPB) Processing
The clispb.dat Listing
Values from clispb.dat are copied to the internal SPB and override the default values when the
application program calls DBCHINI.
If clispb.dat is Missing
If the clispb.dat file, or any of its values, are missing, the default values from the internal SPB
are used. (The internal SPB is copied to the DBCAREA when the application calls DBCHINI.)
Caveats
As provided on the release media, the clispb.dat file contains defaults recommended for typical
installations running under the given operating system. Managers responsible for overall
operations at the site may change the defaults to reflect conditions appropriate for the site.
In general, application programmers can override the defaults via the DBCAREA in order to
reflect conditions appropriate for the application.
The clispb.dat Listing
Table 3 gives the contents of the clispb.dat file. The defaults are recommended for typical
network-attached systems. See the corresponding field name for more information.
Table 3: clispb.dat File
Name
Default
DBCAREA Field Name
change_opts
Y
Change Options
charset_id*
ASCII
Character Set Pointer
Note: This field contains either the character set code or
the character set name. In the DBCAREA charset_id is
named Character Set Pointer.
66
connect_type
N
Connect Type
charset_type
N
Character Set Type
columnInfo
0
Varying-length column title and format information
connect_wait
10
Connect Wait
consider_aph_resps
N
APH/1 MB Responses
data_encryption
N
Data Encryption
date_form
D
Date Form
dbriseg
N
Segmented data transfer for (TDSP)
dynamic_result_sets_allowed
N
Dynamic Result Sets Allowed
i_dbcpath
dbc
Input DBCpath
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 4: System Parameter Block (SPB) Processing
The clispb.dat Listing
Table 3: clispb.dat File (continued)
Name
Default
DBCAREA Field Name
keep_resp
N
Keep Response
lang_conformance
N
Language Conformance
lang_id
EN
Language to be used for generating CLI messages
loc_mode
N
Locate Mode
max_decimal_returned
0
Maximum Decimal Precision
max_num_sess for a single
process
300
Maximum Number of Sessions
maximum_parcel
O
Maximum Parcel
msg_security
N
Message Security
parcel_mode
Y
Parcel Mode Fetch
req_buf_len
1024
Request Buffer Length
req_proc_opt
E
Request Processing Option
request_mode
P
Request Mode
resp_ buf_len
8192
Response Buffer Length
resp_mode
R
Response Mode
ret_time
N
Return Time
return_object
D
Type of LOB to be returned
send_delegated_credentials
Y
send delegated credentials
save_resp_buf
N
Save Response Buffer (not used)
SP_return_result
0
Stored Procedure return result
tell_about_crash
Y
Tell About Crash (Tell About Delay)
timing_precision
20
Timing-Precision
two_resp_bufs
N
Two Response Buffer
tx_semanticss
D
Transaction Semantics
use_presence_bits
N
Use Presence Bits
var_len_fetch
N
Variable Length Fetch
var_len_req
N
Variable Length Request
wait_across_crash
N
Wait Across Crash (Wait Across Delay)
wait_for_resp
N
Wait For Response
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
67
Chapter 4: System Parameter Block (SPB) Processing
Overriding Values
If you have write access to clispb.dat, you may edit clispb.dat and replace the current names
with the old (alternate) ones. Table 4 gives the corresponding names:
Table 4: clispb.dat File Names
Current
Old
change_opts
seto
data_encryption
secure
i_dbcpath
dbcname
keep_resp
krsp
loc_mode
floc
max_num_sess
maxsess
parcel mode
btpm
req_buf_len
reqlen
req_proc_opt
funt
resp_buf_len
rsplen
resp_mode
rmod
ret_time
rts
save_resp_buf
fsvb
tell_about_crash
crtl
two_resp_bufs
twob
use_presence_bits
idta
var_len_fetch
fvar
var_len_req
rvar
wait_across_crash
crsw
wait_for_resp
bsyw
long_conformance
conf
CLI does not recognize the old symbol names.
Overriding Values
To override default values contained in the internal SPB, the user specifies the new values in
the clispb.dat.
68
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 4: System Parameter Block (SPB) Processing
Overriding Values
File values are specified by using a mnemonic term, such as an option field name, followed by
an equal sign (=) and the appropriate value. For example, resp_mode=R.
The clispb.dat file is distributed with one item per line, and that item is set exactly the same as
it is in the internal SPB.
When you modify the file, you may either keep the same format or vary the format, if you stay
within the following guidelines:
•
As many items may be placed on a line as will fit in 80 characters;
•
Items may not span lines and must be separated by commas;
•
Any number of spaces may separate items and the fields in an item specification;
•
Option values must be in uppercase;
•
The dbcname may be in upper or lowercase.
Reformatted File: Example
The following lines are an example of a reformatted file that contains valid syntax:
req_buf_len=1024,
resp_buf_len=8192,
resp_mode=F,
max_num_sess=300
wait_for_resp=N,
ret_time=Y,
i_dbcname=mysite,
loc_mode=Y
The application program may specify values in the DBCAREA for the various option
arguments before calling DBCHCL. The program indicates to CLI that changes to the options
are to be honored by setting the value of Change Options to Y in the DBCAREA. Depending
on the function code set in the DBCAREA, different options are looked at by DBCHCL.
Table 5 lists the fields by their mnemonic names and specifies the default value and the set of
possible values.
Table 5: Mnemonic Names of Fields
Opt=Dflt
Type Values
Description
change_opts=Y
C
Y/N
options-changed flag
charset_type=N
char
C/N
c:char set code N:name R:run logon
columnInfo=0
C
E/O
varying length column allowed
connect_type=c
char
C/R
C:connect logon (used on host)
connect_wait=10
char
10
Connect wait
consider_aph_resps=N
char
Y/N
APH/1 MB Responsest
data_encryption=N,
C
Y/N
data encryption
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
69
Chapter 4: System Parameter Block (SPB) Processing
Overriding Values
Table 5: Mnemonic Names of Fields (continued)
Opt=Dflt
Type Values
Description
data_form=0
char
T/A/D
T - Teradata Format
A - ANSI format
D - Default
dbriseg=N
char
N/F/I/L/C
N - Default
F - First segment
I - Last segment
L - Last segment
C-Cancel Requset
dynamic_result_sets_allowed C
=N
Y/N
dynamic result sets allowed
i_dbcpath=dbc
C
1-8ch
name of default database computer
keep_resp=N,
C
Y/N/P
Y:keepresp, N:resp, P:positioning information
lang_conformance=N
char
N/2/3
N - None
2 - FIPS127-2
3 - FIPS127-3
loc_mode=N,
C
Y/N
fetch use locate mode
max_decimal_returned=0
Int
0-255
maximum decimal precision value
max_num_sess=300
Int
1-999
max. concurrent sessions
maximum_parcel=0
char
O/H
O - 32k
H - 64k
mag_security=N
char
Y/N
Y: To encrypt the message
N: Not to encrypt the message
parcel mode=Y,
C
Y/N
parcel mode (buffer mode if no)
req_buf_len=1024,
Int
1K-64K
request buffer size
req_proc_opt=E
C
E/P/B/S
perform/execute SQL request/
perform&execute /analyze parameterized SQL
requst_mode=P
char
P/B/D
Options for request handling:
P: parcelmode
B: buffermode
D: descriptor list
70
resp_buf_len=8192,
Int
1K-64K
response buffer size
resp_mode=R,
C
R/F/I/M
R:record mode, F:field mode, I:indicator mode
M:MultiPart Indicator mode
ret_time=N,
C
N/Y
return time stamps
return_object=D
char
D/T/S
D - Data
T - Tx-related locators
S: Spool-related locator
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 4: System Parameter Block (SPB) Processing
Overriding Values
Table 5: Mnemonic Names of Fields (continued)
Opt=Dflt
Type Values
Description
save_resp_buf=N,
C
Y/N
save buff for re-use at erq
send_delegated_credentials= char
Y
Y/N
Send delegated credentials
SP_return_result=0
Int
0-5
Stored Procedure return result
tell_about_crash=N,
C
Y/N
inform application of crash
two_resp_bufs=N,
C
Y/N
‘double buffering’
tx_semantics
char
D/T/A
D - server default
T - Teradata Database
A - ANSI
use_presence_bits=N,
C
Y/N
Y:indicdata mode
var_len_fetch=N,
C
Y/N
return fetch data var string
var_len_req=N,
C
Y/N
request data is var string
wait_across_crash=N,
C
Y/N
wait for resp if dbc crash
wait_for_resp=N,
C
Y/N
allow CLI to block on reads
To be specific, the range on the response buffer size and request buffer size is 1024 bytes to
32768 bytes, if Maximum Parcel is set to O or 65536/1048500, if Maximum Parcel is set to H,
of which 16 bytes are reserved for internal use. The maximum number of concurrent sessions
for a single process may be less than 999, depending on your system and the local system
configuration.
Note: The value of 1048500 is only when support for APH and extended response exists at the
server to which the session is logged on.
Valid Item Specifiers
Valid item specifiers are:
•
req_buf_len<number> : specifies the default request buffer length
•
rsp_buf_len<number> : specifies the default response buffer length
•
i_dbcname<dbcname string> : specifies the default database computer name string
•
max_num_sess<number> : specifies the maximum number of sessions allowed to
belogged on at any time for a given single process.
•
<option field><option value> : specifies the default value for the specified option.
The option field string is the declared option name, as given below.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
71
Chapter 4: System Parameter Block (SPB) Processing
Values Used by CLI: Summary
Values Used by CLI: Summary
Initial Values
The initial values in the:
•
internal SPB are shown as Dflt in the Opt=Dflt column above.
•
DBCAREA are those in the internal SPB as overridden by those in clispb.dat.
Final Values
Three structures control the final values used by CLI programs.
72
•
The value actually used is the one set in the DBCAREA.
•
If no value is set in the DBCAREA, use the value set in the clispb.dat file.
•
If no value is set in clispb.dat, use the value set in the internal SPB.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 5
DBCAREA
This chapter describes:
•
DBCAREA Fields
•
Allocating the DBCAREA
•
DBCAREA Security Mechanism Fields
•
DBCAREA: Field Descriptions
•
Individual Field Descriptions: Alphabetical Listing
•
DBCAREA Fields Not Used by Network-Attached Systems
DBCAREA Fields
The DBCAREA is a data structure shared by the application program and CLI (Figure 3).
•
The application program sets values in it to transfer information to CLI.
•
CLI sets values in it to transfer information back to the application program.
The DBCAREA data structure defines the interface between CLI and the application.
Figure 3: Data Flow
Application
DBCAREA
CLIv2 Routines
Teradata Database via MTDP
2418B003
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
73
Chapter 5: DBCAREA
Allocating the DBCAREA
Allocating the DBCAREA
The DBCAREA is originally allocated by the application program and then passed to
DBCHINI, where it is cleared and some fields are initialized to their default values. DBCHINI
initializes the area for an application.
After initialization, the application program sets appropriate input values in the DBCAREA
before each call to the DBCHCL.
When the application program regains control from DBCHCL, it can obtain the appropriate
output values from the DBCAREA.
DBCAREA Security Mechanism Fields
The DBCAREA structure has added the following fields:
logmech_name
logmech_data_ptr
logmech_data_len
The logmech_name is an 8-byte field supplied by the application and derived from the
.logmech command or statement, or the mechanism name list box of the logon dialog box. It
is located in the eight bytes after the existing using-data-count field. If a default session
character set is in use, the application must ensure that only a valid mechanism name is passed
(single-byte LATIN1, left-justified, case-insensitive, and padded with blanks), performing
conversion, if necessary. The mechanism name will be converted internally to the OID
corresponding to the indicated mechanism; the application does not need to know anything
about OIDs.
The logmech_data_ptr is a 32- or 64-bit pointer to a variable-length field (maximum of 65535
bytes) supplied by the application and derived from the .logdata command or statement, or
the mechanism data text box of the logon dialog box. The logmech_data_ptr immediately
follows the logmech_name. In 32-bit implementations, a 4-byte unused field will precede the
32-bit logmech_data_ptr; in 64-bit implementations, logmech_data_ptr will occupy the full 8
bytes following logmech_name.
The logmech_data_len is a 32-bit unsigned integer supplied by the application and specifies
the length of the mechanism data in bytes. It is located immediately following
logmech_data_ptr. The maximum allowable value for logmech_data_len is 64 KB.
These fields are only examined at connect time (that is, when the DBFCON function of
DBCHCL is requested) or if connection is lost and CLI is set up to reconnect automatically.
The associated data will be passed as-is to the indicated mechanism. It is the responsibility of
the user to ensure that the mechanism can handle a specific character set.
74
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
DBCAREA Security Mechanism Fields
Network CLIv2 User Exits
The existing network CLIv2 user exits continue to be supported in addition to a new set of
user exits that allow for the inspection and possible modification of .logmech and .logdata
information. These new exits offer additional flexibility as well other improvements over the
extant implementation. For more information, see Chapter 16: “CLI Exit Functions.”
Changes to dbchqep.h
#define QEPIALM 32
When this item is selected for a DBCHQE invocation, CLIv2 will return a list of supported
mechanism names. It will operate similarly to the QEPIACS query. That is, no new QEP fields
will be added, QEPTOKEN will be honored, and the returned information will consist of a 4byte token, a 2-byte count of the number of logon mechanism names not yet returned, a 2byte count of the number of logon mechanism names returned by this query, a 2-byte length
of each name, and zero or more names and associated flags themselves (16 bytes per
mechanism). The order of returned mechanisms is irrelevant and may even vary between
invocations.
If a valid TDPid (machine name) is passed to DBCHQE, then intersection of the list of clientand server-supported mechanisms will be returned. If the TDPid pointer contains 0, only a list
of client-supported mechanisms will be returned.
If no mechanism(s) can be returned for whatever reason, a list consisting of 0 (that is, null)
elements will be returned.
In addition to the 8-byte mechanism name, one flag will be returned. It will be set to ‘D’ if the
associated mechanism is the default mechanism; otherwise, the flag will contain a blank.
Only one mechanism will be identified as the default mechanism.
typedef struct QEPLMINFO_ {
UInt32 qeralmTk; /* Token, !should not modified by application*/
UInt16 qeralmNR; /* Number of mechanisms not returned */
UInt16 qeralmNP; /* Number of mechanisms returned */
UInt16 qeralmLn; /* Length of each mechanism name plus flags */
/* Variable part follows in QEPAREA */
}QEPLMINFO;
typedef struct QEPLMITEM_ {
char mech_name[8];
char default_flag; /* ‘D’ if default, blank otherwise */
char future_use[7]; /* reserved for future use */
} QEPLMITEM;
If no mechanism(s) can be returned for whatever reason, a list consisting of 0 (that is, null)
elements will be returned (that is, both qeralmNR and qeralmNP will be zero upon return
from the first invocation of DBCHQE (QEPIALM)).
This query item can be used by GUI applications that want to display a list of available
mechanisms (for example, a drop down box) for a user to select. Also, applications can use
this query item to determine whether CLIv2 can accommodate .logmech and/or .logdata
items.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
75
Chapter 5: DBCAREA
DBCAREA Security Mechanism Fields
For QEPIALM, the minimum value for qepRALen is 26 (sizeof(QEPLMINFO) +
sizeof(QEPLMITEM).
CLI355 (QEPITEM) error will be returned from the DBCHQE(QEPIALM) call if CLIv2 does
not support the QEPIALM query.
For TTU 8.0 and above, client applications that want to determine whether data encryption
can be employed should use both the QEPIALM and QEPIENC DBCHQE query items.
Neither of these, by themselves, is necessary and sufficient for determining the availability of
data encryption.
Data encryption is generally available if QEPIENC returns ‘Y’ and QEPIALM returns a list of
one or more mechanisms. It is not incumbent upon the client application to verify data
encryption availability; CLIv2 will return an error (CLI500 NOENCRYPTION) if an attempt
is made to initiate a request with data encryption when data encryption is not available.
Supported Mechanisms
In general, mechanisms which perform authentication and/or validation do not require that a
Teradata Database username and password be included as part of the logon string. If these
items are supplied in conjunction with such a mechanism, they will effectively be ignored.
The following mechanisms are supported:
Kerberos
In all environments that support Kerberos, the user may supply a userid, password, domain
(or a realm), and password. The domain or realm must be supplied separately as mechanism
data. After the user’s identity has been verified by Kerberos, an implicit logon will proceed
using the tendered userid as the Teradata username.
.logmech KRB5
.logdata joe@domain1@@mypassword
.logon mydbs/
For single-domain environments, the gateway can be configured so that the domain or realm
need not be indicated (this is discussed in the relevant gateway documentation).
.logmech KRB5
.logdata joe@@mypassword
.logon mydbs/
Alternatively, a Kerberos-mediated SSO-style logon can be used by omitting the userid,
password, and domain or realm, and password. In this case, Kerberos uses the security
credentials associated with the current client session.
.logmech KRB5
.logon mydbs/
If required, the user may include Teradata accounting information as part of .logon command
as follows:
.logmech KRB5
.logdata joe@domain1@@mypassword
.logon mydbs/,,2345889909
or
76
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
DBCAREA Security Mechanism Fields
.logmech KRB5
.logdata joe@@mypassword
.logon mydbs/,,2345889909
or
.logmech KRB5
.logon mydbs/,,2345889909
In all of the above cases, there must exist a Teradata username defined in the target database
that matches the actual or derived userid and, further, that username must have previously
been granted the logon with null password privilege. The special “dbc” username cannot be
used with this mechanism because “dbc” cannot be granted the logon with null password
privilege (the DBS will return error 3790 in this case).
KRB5C
This mechanism is maintained for compatibility purposes only (TTU 8.0 and above
communicating with Teradata Database pre-V2R6 that supports SSO and/or logon
encryption) and should not generally be specified directly by the user. The teraSSO library will
automatically determine the appropriate mechanism when interfacing to such a DBS, using
the same logic as employed in TTU 7.1. Windows clients will use NTLMC or KRB5C for SSO
(direct or third-party), TD1 otherwise; non-Windows clients will use TD1. In the event a user
manually selects an incompatible mechanism, TERASSO_SECPKGMATCH_FAIL will be
returned.
SPNEGO
Teradata Database employs the Simple and Protected GSSAPI Negotiation Mechanism
(SPNEGO) to provide confidentiality and integrity while supporting non-LDAP external
authentication for users logging on to Teradata Database through Windows .NET
applications. The SPNEGO mechanism functions almost identically to the KRB5 mechanism,
except that KRB5 cannot be used in a Windows .Net environment. See “Kerberos” on page 76.
NTLM
Windows to Windows environments only. The user may supply a userid, password, and
domain. After the user’s identity has been verified by NTLM, an implicit logon will proceed
using the tendered userid as the Teradata username.
.logmech NTLM
.logdata joe@domain1@@mypasswordjoe
.logon mydbs/
For single-domain environments, the gateway can be configured so that the domain or realm
need not be indicated (this is discussed in the relevant gateway documentation).
.logmech NTLM
.logdata joe@@mypasswordjoe
.logon mydbs/
Alternatively, an NTLM-mediated SSO-style logon can be used by omitting the userid,
domain, and password.omitting the userid, password, and domain or realm. In this case,
NTLM uses the security credentials associated with the current client session.
logmech NTLM
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
77
Chapter 5: DBCAREA
DBCAREA Security Mechanism Fields
logon mydbs/
If required, the user may include Teradata accounting information as part of .logon command
as follows:
.logmech NTLM
.logdata joe@domain1@@mypassword
.logon mydbs/,,2345889909
or
.logmech NTLM
.logdata joe@@mypassword
.logon mydbs/,,2345889909
or
.logmech NTLM
.logon mydbs/,,2345889909
In all of the above cases, there must exist a Teradata username defined in the target DBS that
matches the actual or derived userid and, further, that username must have previously been
granted the logon with null password privilege. The special “dbc” username cannot be used
with this mechanism because “dbc” cannot be granted the logon with null password privilege
(the DBS will return error 3790 in this case).
For compatibility purposes, this is equivalent to the existing SSO feature. The existing thirdparty sign-on variant of SSO (NTLM only) will be supported for compatibility purposes.
However, it is recommended that new applications use the logmech_name,
logmech_data_ptr, and logmech_data_len fields in DBCAREA instead.
NTLMC
This mechanism is maintained for compatibility purposes only (TTU 8.0 and above
communicating with Teradata Database pre-V2R6 that supports SSO and/or logon
encryption) and should not generally be specified directly by the user. The teraSSO library will
automatically determine the appropriate mechanism when interfacing to such a DBS, using
the same logic as employed in TTU 7.1. Windows clients will use NTLMC or KRB5C for SSO
(direct or third-party), TD1 otherwise; non-Windows clients will use TD1. In the event a user
manually selects an incompatible mechanism, TERASSO_SECPKGMATCH_FAIL will be
returned.
LDAP
The LDAP mechanism allows a user to be authenticated via LDAP and, optionally, to assume a
role or user identity other than his or her own, as allowed by the appropriate directory
settings.
The user may supply a userid, password, and domain or realm. The exact contents of the
LDAP .logdata information necessarily depends largely upon how the site is using LDAP, how
LDAP has been configured, etc. The samples below are only generic examples. After the user’s
identity has been verified by LDAP, an implicit logon will proceed using the userid as the
Teradata username. Brackets denote optional fields and commands.
.logmech LDAP
.logdata authcid=joe password=password [realm=myrealm]
78
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
DBCAREA Security Mechanism Fields
.logon mydbs/
.logmech LDAP
.logdata joe[@myrealm]@@password
.logon mydbs/
.logmech LDAP
[.logdata realm=myrealm]
.logon mydbs/joe,password
If required, the user may include Teradata accounting information as part of .logon command
as follows:
.logmech LDAP
.logdata authcid=joe password=password realm=myrealm
.logon mydbs/,,2345889909
If the directory maps the userid to a specific Teradata username, that username must be
defined in the target DBS and must have previously been granted the logon with null
password privilege. After the user’s identity has been verified by LDAP, an implicit logon will
proceed using the tendered userid as the Teradata username. The special “dbc” username
cannot be used with this mechanism because “dbc” cannot be granted the logon with null
password privilege (the DBS will return error 3790 in this case).
If the directory does not map the userid to a specific Teradata username, a generic username
will be used and a role assigned. The role will be derived from information contained in the
directory. Logon will be by extended logon.
TD1 and TD2
TD1 and TD2 represent the Teradata mechanisms. They do not perform any authentication.
Rather, they facilitate encryption/decryption for sessions connected absent the mediation of
extended security. Therefore, a valid Teradata username and password are always required.
Only TD1 is used by TTU 7.1. TD2 is used by TTU 8.0 and above for Teradata Database V2R6;
TD1 is used by TTU 8.0 and above for Teradata Database V2R5.1. The difference between the
two mechanisms is that the encryption key for TD2 is longer (and, therefore, offers a higher
degree of security) than that of TD1. For TD2, there should be no .logdata parameter; if one is
passed to CLIv2, it will be ignored.
TD2 is shipped as the default mechanism for the server-based XML config file.
.logmech TD2
.logon mydbs/joe,password
TD1
TD1 is a deprecated mechanism used by TTU 7.1. It will also be used by TTU 8.0 and above
when communicating with Teradata Database V2R5.x.
This mechanism is maintained for compatibility purposes only (TTU 8.0 and above
communicating with Teradata Database V2R5.x) and should not generally be specified
directly by the user. The teraSSO library will automatically determine the appropriate
mechanism when interfacing to Teradata Database V2R5.x, using the same logic as used in
TTU 7.1. Windows clients will use NTLMC or KRB5C for SSO (direct or third-party), TD1
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
79
Chapter 5: DBCAREA
DBCAREA Security Mechanism Fields
otherwise. In the event a user manually selects an incompatible mechanism,
TERASSO_SECPKGMATCH_FAIL will be returned.
Single Sign-On Legacy Considerations
To provide backward compatibility with pre-TTU 8.0 applications that use SSO, the following
items apply:
•
Direct sign-on: If a user does not supply a username and password as part of the Teradata
logon string AND no mechanism name is specified via .logmech, the client interface will
not use the default mechanism. Rather, it will first determine if the Kerberos mechanism is
available and, if so, use it. If not, it will next determine if the NTLM mechanism is available
and, if so, use it. If neither NTLM nor Kerberos is available, the logon attempt will fail.
If .logmech is specified and it turns out to be different from the one automatically
determined by the client interface, an error will be returned.
•
Third-party sign-on: If an application uses the programmatic third-party sign-on
capability via the DBCAREA extension AND no mechanism name is specified via
logmech_name, the client interface will not use the default mechanism. Rather, it will first
determine if the Kerberos mechanism is available and, if so, use it. If not, it will next
determine if the NTLM mechanism is available and, if so, use it. If neither NTLM nor
Kerberos is available, the logon attempt will be failed.
If .logmech is specified and it turns out to be different from the one automatically
determined by the client interface, an error will be returned.
Integrity and Compatibility
TTU 8.0 and above applications paired with pre-TTU 8.0 client interfaces should reject logon
attempts in which a mechanism name has been explicitly proffered. Not doing so may give the
user a false sense of security because pre-TTU 8.0 client interfaces do not support mechanism
selection by the user.
CLIv2 applications may use the DBCHQE QEPIALM query item to determine whether the
mechanism name should be accepted or not. If DBCHQE returns CLI355, the application
should reject the logon attempt. The application is under no obligation to verify the proffered
mechanism name against the list of available mechanisms (obtainable via DBCHQE
QEPIALM); the teraSSO library performs that task.
Other Mechanisms
The above list is by no means exclusive or complete. Extended security supports any method
that conforms to the GSS protocol. It is anticipated that customer-written mechanisms will be
supported in a future release.
Determining Session Username
Some mechanisms (e.g., LDAP) may result in sessions being connected under a username
different from the one indicated in the logon character sequence. If an application needs to
80
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
DBCAREA Security Mechanism Fields
determine the actual logged on username for a given session, it should use the extant QEPISU
item of the DBCHQE service. This item was originally added for SSO in TTU 6.1.
Default Mechanism Handling
To relieve users of the necessity of supplying a mechanism name for every connect request, a
default mechanism can be used instead. This mechanism name may be supplied at either the
client or the server. The specified mechanism must appear in both the client and server lists of
supported mechanisms. If there is no match, the default mechanism is not be eligible for use.
A client-supplied default mechanism will take precedence over a server-supplied default
mechanism. The default attribute is specified in the XML-based mechanism list that resides
on both client and server platforms.
A server default mechanism must always be supplied. The presence of a default mechanism
does not prevent users from using an alternative mechanism (provided the mechanism occurs
in both the client and server lists of supported mechanisms).
An application-supplied mechanism name (if supplied) is preferred to the client default
mechanism (if one exists), which is preferred to the server default mechanism. In all cases the
chosen mechanism must exist on the client and the server for a successful connection,
otherwise an error (CLI507) will be returned.
CLIv2 will place the name of actual mechanism used into the logmech_name field of the
DCBAREA. It will be available to the application after control has been returned from
DBCHCL (DBFCON).
If a mechanism has been tagged as disabled in either the client- or server-based XML
configuration file, it will be ignored (default or otherwise). The server side config file must
contain one and only one default mechanism. The client side config file may or may not
contain a default mechanism; if it does, there can only be one default mechanism.
Unicode Credential Processing
CLIv2 provides a DBCAREA field called mechdata_Unicode_set. Acceptable binary values are:
0 - raw data (default)
1 - reserved
2 - reserved
3 - UTF8
4 - UTF16
5 - UTF32
This field should only be used by applications or interfaces that know that mechanism data
will be passed as other than raw data to a mechanism capable of recognizing such data. If
mechdata_Unicode_set is set or defaulted to 0 and the session character set is UTF8, UTF16,
or UTF32, then CLIv2 will internally set mechdata_Unicode_set to 3, 4, or 5, respectively. If a
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
81
Chapter 5: DBCAREA
DBCAREA: Field Descriptions
mechdata_Unicode_set is specified either externally or internally, but the target mechanism
does not accept that particular character set, CLIv2 returns EM_GSSINITFAIL (235) to the
caller.
Note: This field is ignored when the mechanism is TD1 or TD2.
DBCAREA: Field Descriptions
The DBCAREA contains seven logical sections:
•
Header
•
General Input
•
General Output
•
Function Specific
•
Time Stamp
•
Option
•
Message
Individual fields in these logical sections are illustrated, in sequential order, in the figures that
follow.
Table 6: Sequential Order of the DBCAREA
Byte
Number
000
Description
Eyecatcher, 8 bytes
004
82
008
Total Length, 4 bytes
012
Function, 4 bytes
016
Input Session ID, 4 bytes
020
Input Request ID, 4 bytes
024
Request Buffer Length, 4 bytes
028
Response Buffer Length, 4 bytes
032
Maximum Number of Sessions for a Single Process, 4 bytes
036
Token, 4 bytes
040
Return Code, 4 bytes
044
Output Session ID, 4 bytes
048
Output Request ID, 4 bytes
052
Output DBC Path, 8 bytes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
DBCAREA: Field Descriptions
Table 6: Sequential Order of the DBCAREA (continued)
Byte
Number
Description
056
060
064
Output DBC Session ID, 4 bytes
Output Host ID,
2 bytes
Session Status,
1 byte
068
TDP Request Number, 4 bytes (not used)
072
Current Request Buffer Length, 4 bytes
076
Current Response Buffer Length, 4 bytes
080
Unused,
1 byte
Input DBC Path, 8 bytes
084
088
Logon Pointer, 4 bytes
092
Logon Length, 4 bytes
096
Run Pointer, 4 bytes
100
Run Length, 4 bytes
104
Request Pointer, 4 bytes
108
Request Length, 4 bytes
112
Using Data Pointer, 4 bytes
116
Using Data Length, 4 bytes
120
Msg Class, 2 bytes
124
Msg Kind, 2 bytes
Mailbox, 6 bytes
128
Unused, 2 bytes
132
Open Request, 4 bytes
136
Fetch Maximum Data Length, 4 bytes
140
Fetch Data Pointer, 4 bytes
144
Fetch Returned Data Length, 4 bytes
148
Fetch Parcel Flavor, 4 bytes
152
156
Fetch Error Indicator,
1 byte
Unused,
3 bytes
TDP-receipt-timestamp, 8 bytes (not used)
160
164
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Time1, 4 bytes
83
Chapter 5: DBCAREA
DBCAREA: Field Descriptions
Table 6: Sequential Order of the DBCAREA (continued)
Byte
Number
Description
168
Time2, 4 bytes
172
Time3, 4 bytes
176
Time4, 4 bytes
180
Time5, 4 bytes
184
Character Set Pointer, 4 bytes
188
MTDP sent, 4 bytes
192
MTDP received, 4 bytes
196
|.....|
Unused, 16 bytes
208
212
Extension Pointer, 4 bytes
216
Change Options,
1 byte
Response Mode,
1 byte
Use Presence Bits,
1 byte
Keep Response,
1 byte
220
Wait Across Crash,
1 byte
Tell About Crash,
1 byte
Connect Wait,
1 byte
Locate Mode,
1 byte
224
Variable Length
Request, 1 byte
Variable Length
Fetch, 1 byte
Save Response,
Buffers, 1 byte
Two Response,
Buffers, 1 byte
228
Return Time,
1 byte
Parcel Mode Fetch,
1 byte
Wait for Response,
1 byte
Request Processing
Option, 1 byte
232
Message Security,
1 byte
Set Character,Set,
1 byte
Connect Type,
1 byte
Request Mode,
1 byte
236
2PC,
1 byte
Protocol-Function
1 byte
Transaction
Semantics, 1 byte
Conformance
1 byte
240
Unused, 2 bytes
Message Length, 2 bytes
244
|.....|
Message Text, 76 bytes
312
320
Route Description Codes, 4 bytes
324
|.....|
Unused, 16 bytes
336
84
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
DBCAREA: Field Descriptions
Table 6: Sequential Order of the DBCAREA (continued)
Byte
Number
Description
340
Unused,
2 bytes
344
LanguageId, 2 bytes
Date Form,
1 byte
Maximum
Parcel, 1 byte
Unused, 2 bytes
348
Segment Data,
1 byte
Return-objects-as,
1 byte
Continuation Code,
1 byte
Data Encryption,
1 byte
352
Unused,
1 byte
Statement Status,
1 byte
Continued
Characters State,
1 byte
Consider APH
Responses,
1 byte
356
Return statement
info, 1 byte
Return Identity
Data, 1 byte
360
Positioning-statement-number,
2 bytes
Positioning-value, 8 bytes
364
368
Positioning-action, 2 bytes
Timing-precision, 2 bytes
Unused,
1 byte
372
DBC Level,
1 byte
376
Message Length Returned, 2 bytes
Message Return Code,
2 bytes
Message Area Length, 2 bytes
380
Message Area Pointer, 4 bytes
384
req_buf_len_4, 8 bytes
388
392
resp_buf_len_4, 8 bytes
396
400
curr_req_buf_len_4, 8 bytes
404
408
cur_resp_buf_len_4, 8 bytes
412
416
Logon Pointer, 8 bytes
420
424
Run Pointer, 8 bytes
428
432
Request Length, 8 bytes
436
440
Request Pointer, 8 bytes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
85
Chapter 5: DBCAREA
DBCAREA: Field Descriptions
Table 6: Sequential Order of the DBCAREA (continued)
Byte
Number
Description
444
448
Unused, 8 bytes
452
456
using_data_pointer, 8 bytes
460
464
Unused, 8 bytes
468
472
fet_max_data_length, 8 bytes
476
Unused, 8 bytes
480
484
488
Fetch Data Pointer, 8 bytes
492
Fetch Return Data Length, 8 bytes
496
500
504
Character Set Pointer, 8 bytes
508
512
Extension Pointer, 8 bytes
516
520
Message Area Pointer, 8 bytes
524
528
Unused, 4 bytes
532
Unused,
1 byte
Time1-status,
1 byte
Time2-status,
1 byte
Time3-status,
1 byte
536
Time4-status,
1 byte
Time5-status,
1 byte
exempt_sess_from_
DBCHWAT,
1byte
create_default_
connection,
1 byte
540
Using Data Count, 4 bytes
544
logmech_name, 8 bytes
548
552
86
logmech_data_ptr_reserved, 4 bytes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Table 6: Sequential Order of the DBCAREA (continued)
Byte
Number
Description
556
logmech_data_ptr, 4 bytes
560
logmech_data_len, 4 bytes
564
mechdata_Unicode
_set,
1 byte
dynamic_result_sets
_allowed,
1 byte
SP_return_result,
1 byte
568
using_data_ptr_array_reserved, 4 bytes
572
using_data_ptr_array, 4 bytes
576
using_data_len_array_reserved, 4 bytes
580
using_data_len_array, 4 bytes
584
max_decimal_returned,
2 bytes
transformsoff, 1
byte
588
workload_len, 4 bytes
592
workload_ptr, 4 bytes
596
workload_ptr_reserved, 4 bytes
600
Reserved, 12 bytes
Send_deligated
_credentials,
1 byte
periodasstruct,
1 byte
|....|
608
612
616
trustedrequest,
1 byte
columninfo,
1 byte
utilityworkload,
1 byte
Unused,
1bytes
Unused, 24 bytes
|....|
640
Individual Field Descriptions: Alphabetical
Listing
Each of the fields described in the following section contain a table that lists the language used
and the corresponding variable name.
The variable names for C:DBCAREA.H are found in the dbcarea.h file.
The definition of the DBCAREA in COBOL is found on the release tape or disk as
DBCAREAC. Cobol is supported only on the VAX through the preprocessor.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
87
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Input fields are used by applications to indicate an action to be taken, to set processing
options, and to pass data to CLI. Some of the fields are used to construct parcels for the
Teradata Database.
The output fields are used by CLI to provide the return code from the action requested and to
pass back information from CLI, for example, a pointer to a parcel in the response. Include
files that define this area are provided for the supported language, which is C.
Change Options
Usage Notes
The Change Options field specifies whether any options have been changed since the last time
they were scanned by CLI.
Language
Variable Name
COBOL:
DBCAREA-CHANGE-OPTS
C: DBCAREA.H:
change_opts
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP; IRQ; FET; REW; ERQ; ABT)
Used by
Action Taken
application program
writes
Change Options is initialized by DBCHINI to the default value provided for Change Options
in the site’s SPB.
If the value provided is not appropriate for the application, the application program may
change the value. Options processing is expensive, so use it only when necessary. It may be
necessary immediately after the call to DBCHINI to establish application-specific defaults.
After that, it is only necessary if some processing option is changed.
Set Change Options to N after CLI picks up the new option settings. If Change Options is set
to Y, DBCHCL uses the option flags that are appropriate for the value specified in function.
Table 7 summarizes the option flags scanned for each function if Change Options is set to Y.
88
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Table 7: Processing Options for Network-Attached Systems
Options Scanned
Function
Connect
Run Startup*
Initiate Request
Fetch
Rewind
End Request
Abort
Disconnect
Continue Request
columnInfo
No
Yes
Yes
No
No
No
No
No
No
Connect Type
Yes
No
No
No
No
No
No
No
No
Connect Wait
No
No
No
No
No
No
No
No
No
Continuation Code
No
No
No
No
No
No
No
No
Yes
Data Encryption
Yes
Yes
Yes
No
No
No
No
No
No
Date Form
Yes
No
No
No
No
No
No
No
No
Dynamic Result Sets Allowed
No
Yes
Yes
No
No
No
No
No
No
Keep Response
Yes
Yes
Yes
No
No
No
No
No
No
Language Conformance
Yes
No
No
No
No
No
No
No
No
Locate Mode
Yes
Yes
Yes
No
No
No
No
No
Yes
Maximum Integer Precision
No
Yes
Yes
No
No
No
No
No
No
Maximum Parcel
Yes
Yes
Yes
No
No
No
No
No
Yes
Options Scanned
Yes
No
No
No
No
No
No
No
No
Parcel Mode Fetch
Yes
Yes
Yes
No
No
No
No
No
Yes
Period-as-Struct
No
Yes
Yes
No
No
No
No
No
No
Positioning-action
No
No
No
Yes
No
No
No
No
No
Positioning-statement-number
No
No
No
Yes
No
No
No
No
No
Positioning-value
No
No
No
Yes
No
No
No
No
No
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
89
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Table 7: Processing Options for Network-Attached Systems (continued)
Options Scanned
Function
Connect
Run Startup*
Initiate Request
Fetch
Rewind
End Request
Abort
Disconnect
Continue Request
Request Mode
No
No
Yes
No
No
No
No
No
Yes
Request Processing Option
Yes
Yes
Yes
No
No
No
No
No
No
Response Mode
Yes
Yes
Yes
No
No
No
No
No
No
Return Identity Data
No
Yes
Yes
No
No
No
No
No
No
Return Time
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Return Object
No
Yes
Yes
No
No
No
No
No
No
Save Response Buffer
Yes
Yes
Yes
No
No
No
No
No
Yes
Segment Data
No
Yes
No
No
No
No
No
No
No
Set Character Set
Yes
Yes
Yes
No
No
No
No
No
No
Statement-status
Yes
No
Yes*
Yes*
No
No
No
No
No
Stored Procedure Return Result
No
Yes
Yes
No
No
No
No
No
No
Tell About Crash
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Transaction Semantics
Yes
No
No
No
No
No
No
No
No
Transforms-Off
No
Yes
Yes
No
No
No
No
No
No
Trusted-request
No
Yes
Yes
No
No
No
No
No
No
Two Response Buffer
Yes
Yes
Yes
No
No
No
No
No
No
Use Presence Bits
Yes
Yes
Yes
No
No
No
No
No
No
Variable Length Fetch
Yes
Yes
Yes
No
No
No
No
No
Yes
90
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Table 7: Processing Options for Network-Attached Systems (continued)
Options Scanned
Function
Connect
Run Startup*
Initiate Request
Fetch
Rewind
End Request
Abort
Disconnect
Continue Request
Variable Length Request
Yes
Yes
Yes
No
No
No
No
No
Yes
Wait Across Delay
Yes
Yes
Yes
-
Yes
Yes
Yes
No
Yes
Wait For Response
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Note: Use uppercase Y or N when setting options.
Character Set Pointer
Usage Notes
The Character Set Pointer field specifies the address of a one-byte character set code or a
thirty-byte character set name. It also specifies the character set to be used on this and
subsequent requests and responses.
The following character sets that are supplied by the server are known to CLIv2:
EBCDIC
EBCDIC037_0E
KANJIEBCDIC5026_0I
KANJIEBCDIC5035_0I
KATAKANAEBCDIC
ASCII
LATIN1_0A
LATIN9_0A
UTF16
UTF8
KANJIEUC_0U
KANJISJIS_0S
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
91
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Note: In the clispb.dat file, Character Set Pointer is called charset_id. The field contains either
the character set code or the character set name.
Language
Variable Name
COBOL:
DBCAREA-CSC-PTR
C: DBCAREA.H:
inter_ptr
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads
Used by
Action Taken
application program
writes
This field is used in conjunction with the Set Character Set field in the options fields.
Character Set Type
Usage Notes
The Character Set field is initialized to the default value provided for Character Set Type in the
site’s SPB.
92
Language
Variable Name
COBOL:
DBCAREA-SET-CHAR-SET
C: DBCAREA.H:
charset_type
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (COM; RSUP:IRQ)
Used by
Action Taken
application program
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
If the value provided is not appropriate for the application, the application program may,
before calling DBCHCL for any function, set:
•
Change Options to Y, and
•
Character Set Type to:
•
C, if Character Set Pointer points to a one-byte character set code.
•
N, if Character Set Pointer points to a thirty-byte character set name.
Column Title and Format Information
Usage Notes
Column-info is a one byte ASCII field that indicates whether varying-length column name,
title, and format information in existing response parcels (Field (flavor 18), PrepInfo[X]
(flavors 86 and 126), StmtInfo (flavor 169)) can be longer than the existing maximum.
Language
Variable Name
COBOL:
COLUMNINFO
C:
columnInfo
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (RSUP; IRQ)
Used by
Action Taken
application program
writes
Possible value can be set in this DBCAREA field in ‘E’ and ‘O’.
•
'E' - the value of 'E' indicates that than 30 characters or 60 bytes may be returned.
•
'O' - the value of 'O' indicates that names longer than 30 characters or 60 bytes may not be
returned.
Connect Wait
Usage Notes
The Connect Wait field allows the user to set the amount of time in seconds for the initial
connect of the virtual circuit to a COP/AP before the connection times out. This option can
also be changed via the clispb.dat file.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
93
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBCAREA-CONNECT-WAIT
C: DBCAREA.H:
connect_wait
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads
Used by
Action Taken
application program
writes
Connect Wait is initialized to the default value provided for Connect Wait in the site’s SPB.
Consider APH Responses
Usage Notes
To receive Alternate Parcel Header (APH) responses, consider_APH_resps must be set to ‘Y’.
Continuation Code
Usage Notes
The Continuation Code field specifies the processing to be performed when the Continue
Request (CLICRQ) function, which is defined for deferred mode LOB processing, is invoked.
The value indicates whether the request is for the first, intermediate, or last continuation, or
whether processing is to be cancelled.
Note: DBCHINI does not initialize this value.
If this function is needed by the application, the following procedure must be performed prior
to calling DBCHCL.
94
1
Set the Change-options to “Y”
2
Set the value as follows:
•
First segment : F
•
Intermediate segment : I
•
Last segment : L
•
cancel Continued Request : C
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBNICNT
C: DBCAREA.H:
dbniCnt/continuation_code
Routine
Action Taken
DBCHCL:
reads
Used by
Action Taken
application program
writes
Current Request Buffer Length
Usage Notes
The Current Request Buffer Length field is the actual length of the request buffer at the time
the request is made.
Language
Variable Name
COBOL:
DBCAREA-CUR-REQ-BUF-LEN
C: DBCAREA.H:
cur_req_buf_len
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (CON; IRQ)
Used by
Action Taken
application program
reads
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
95
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Current Response Buffer Length
Usage Notes
The Current Response Buffer Length field is the actual length of the response buffer at the
time the request is made. Current Response Buffer Length indicates any problems with
memory allocation.
Language
Variable Name
COBOL:
DBCAREA-CUR-RESP-BUF-LEN
C: DBCAREA.H:
cur_resp_buf_len
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (CON; RSUP; IRQ; FET; REW; ABT)
Used by
Action Taken
application program
reads
After regaining control from a call to DBCHCL with function code set to any function except
Disconnect, the application program may obtain the value of the actual response buffer length
in Current Response Buffer Length.
Data Encryption
Usage Notes
The Data Encryption field specifies whether or not the messages to and from the Teradata
Database for the given request on the given session are to be encrypted. The session
encryption process, which could be more accurately described as “Network Traffic
Encryption,” provides for user-enabled full session encryption, including SQL and Data
requests and responses.
96
Language
Variable Name
COBOL:
DBCAREA-MSG-SECURITY
C: DBCAREA.H:
data_encryption
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Data Encryption is initialized by DBCHINI to the default value provided for Data Encryption
in the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request function, the application program may set:
•
Change Options to Y, and
•
Data Encryption to:
•
Y, if messages to and from the Teradata Database are to be encoded, starting with this
message.
•
N, if messages to and from the Teradata Database are not to be encoded, starting with
this message.
Users have no control over encryption of the connect (logon) messages. If the GSS or the SSO
flags are turned on at the database/Gateway, connect messages will automatically be
encrypted. Encryption of all other messages is controlled via the Data Encryption field. For
more information on database/Gateway flags, refer to the Gateway Control Utility
documentation.
If Data Encryption is Y, messages to the database computer are encrypted before they are
placed on the network and decrypted when they reach the database computer, and messages
from the database computer are encrypted before they are placed on the network and
decrypted when they reach the network-attached system.
Encryption and decryption take time. It is the application programmer’s responsibility to
determine whether any particular request requires encryption. Some applications and sites
may not require anything to be encrypted, some may require everything to be encrypted, and
some may require selective encryption, for instance, encryption when text contains a
password.
Date Form
Usage Notes
Date Form specifies whether dates are stored in Teradata or ANSI format.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
97
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DATE-FORM
C: DBCAREA.H:
date_form
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
Date Form is initialized to the default value provided for Date Form in the site’s CLISPB. If the
value is not appropriate for the application, the application, before calling DBCHCL for
Connect, may set Change Options to Y and Date Form to one of the following values:
•
D, if dates are stored in default format
•
T, if dates are stored in Teradata format
•
A, if dates are stored in ANSI format.
Note: T may always be specified, but A will be rejected if the server does not support ANSI
date format.
It is recommended that mnemonics be used for the codes. Mnemonics are provided in the
language definition file for the DBCAREA.
DBC Level
Usage Notes
Level indicates the format of the DBCAREA. Note this is returned by CLIv2, it is not set by the
application.
98
Language
Variable Name
COBOL:
DBCLEVEL
PL/I:
DBCLEVEL
Assembler:
DBCLEVEL
C:
dbcLevel (case is significant)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI
writes
Application
reads (CON)
Level Value
Meaning
Binary 0
Initial DBCAREA consists of 384 bytes.
Binary 1
Initial DBCAREA consists of 640 bytes.
Dynamic Result Sets Allowed
Usage Notes
Even if the procedure requests that the results of its SQL be reflected to the CALLer or the
application through the use of either the SQL PROCEDURE's WITH RETURN clause or the
DBCAREA Return-result-to option, a CLIv2 routine so targeted must allow these results using
the DBCAREA Result-sets-OK option. If this option was not specified, the results will not be
returned there.
When results are propagated, they appear in the response with an incremented statement
number after the statement that contained the SQL CALL. The statement number is contained
in both the first parcel for the implicit statement, either Success, OK, ResultSummary; and the
last parcel for the implicit statement: EndStatement. Such a Success, OK, or ResultSummary
parcel will also contain an ActivityType of 176. The next parcel will be ResultSet, which
identifies the procedure and provides the row number to which the procedure positioned the
results. Any response parcels follow the ResultSet.
The options for the request making the CALL and the request issued by the stored procedure
could differ: the response provided to the procedure, the caller, or the application would
reflect the request options that each established. So a response honors that request's
DBCAREA Return-objects-as, Continued-characters-state, APH-response-OK, Returnstatement-info, Max-decimal-returned, Return-identity-data options. If the procedure
specified the DBCAREA MultipartIndicator Response-mode and selects a Large Object (LOB)
but the CALLer or application specified a Response-mode that does not support LOBs, the
procedure will receive an error and no response will be propagated.
Similarly, the response provided to the procedure, the caller, or the application honors the
character set that each established. However, their collation is not. Instead, the collation used
for all responses is the collation that was used when the stored procedure was compiled.
The procedure may use the DBCAREA Keep-response option to provide CLIv2 the same
information that would be provided by SCROLL or NO SCROLL on the SQL DECLARE
CURSOR statement for an SQL Stored Procedure. Specifically, a setting of 'Y' corresponds to
NO SCROLL, indicating the propagated results are positioned to the next unfetched row, with
fetched rows not propagated; a setting of 'P' corresponds to SCROLL, indicating the
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
99
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
propagated results are positioned to the last row fetched, with earlier fetched rows propagated
and available by explicit positioning using either the CLIv2 Fetch function specifying the
DBCAREA Positioning-action, or the CLIv2 Rewind function. The Success, OK, or
ResultSummary parcel ActivityCount field will indicate all available rows available, without
regard to initial positioning.
Unlike positioning of the returned row, the procedure cannot position the offset of a Large
Object (LOB) selected by locator. Any positioning by the procedure within the LOB is not
reflected.
Language
Variable Name
COBOL:
DYNAMIC-RESULT-SETS-ALLOWED
C:
dynamic_result_sets_allowed
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
read(RSUP;IRQ)
Used by
Action Taken
application program
writes
Possible value can be set in this DBCAREA field is 'Y' and 'N'.
Extension Pointer
Usage Notes
The Extension Pointer field specifies the address of the first or only DBCAREA extension,
DBCAREAX.
100
Language
Variable Name
COBOL:
DBCAREA-EXT-PTR
C: DBCAREA.H:
extension_pointer
Routine
Action Taken
DBCHINI:
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHCL:
reads
Used by
Action Taken
application program
writes
Exempt Session from DBCHWAT
The exempt_sess_from_DBCHWAT field is located at hex offset +21A in the DBCAREA and
is read by CLIv2 only when a session is connected.
The exempt_sess_from_DBCHWAT settings are:
•
'Y' - indicates that the session should be ignored for the purposes of DBCHWAT.
•
'N' - (default setting) indicates that the session should participate in DBCHWAT
processing.
Language
Variable Name
COBOL
DBRIXWAT
C/C++
dbriXWat
Routine
Action Taken
DBCHINI
writes
DBCHCL
writes
Used by
Action Taken
application program
reads
Eyecatcher
Usage Notes
The Eyecatcher field is used for self-documentation and debugging.
Language
Variable Name
COBOL:
DBCAREA-EYECATCHER
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
101
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
C: DBCAREA.H:
eyecatcher
Routine
Action Taken
DBCHINI:
none
Used by
Action Taken
application program
none
The application program may set Eyecatcher to DBCAREA prior to calling DBCHINI.
Fetch Data Pointer
Usage Notes
The meaning of the Fetch Data Pointer field depends upon whether it is used in the Move
Mode or in the Locate Mode. These modes are described in the two sections that follow.
The variable name is the same in either mode.
Language
Variable Name
COBOL:
DBCAREA-FET-DATA-PTR
C: DBCAREA.H:
fet_data_ptr
Fetch Data Pointer, Move Mode
Usage Notes
In Move Mode, that is, when Locate Mode is set to N and Parcel Mode Fetch is set to Y or N,
Fetch Data Pointer is the field where the application program specifies the address of its Move
area before calling DBCHCL for the Connect, Run Startup, or Initiate Request functions.
If Fetch Maximum data length is less than the actual data to be returned by CLI, CLI will
return a BUFOVFLOW error.
Variable length fetch should not be set to 'Y' when parcel mode is set to 'N'.
If Parcel Mode is used with Move Mode, that is, Parcel Mode is set to Y and Locate Mode is set
to N, when DBCHCL is called for the Connect, Run Startup, or Initiate Request function, and
if Variable Length Fetch is set to:
•
102
Y, CLI copies the two-byte length field that precedes the Parcel body into the address
specified in Fetch Data Pointer.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
•
N, CLI copies the parcel body into the address specified in Fetch Data Pointer.
If Buffer mode is used with Move mode, that is, if Locate mode is set to N and Parcel Mode
Fetch is set to N:
•
Variable Length Fetch must be set to N, and
•
CLI copies one buffer full of response into the address specified in Fetch Data Pointer.
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (FET)
Used by
Action Taken
application program
writes (FET)
Fetch Data Pointer, Locate Mode
Usage Notes
In Locate Mode, when Locate Mode is set to Y and Parcel Mode Fetch is set to N or Y, Fetch
Data Pointer is the field where the application program can obtain the address of the returned
data after calling DBCHCL for the Fetch function.
If Locate Mode is used, when DBCHCL is called for the Connect, Run Startup or Initiate
Request function, and
•
•
If Parcel Mode is used, that is, if Parcel Mode Fetch was set to Y, and if Variable Length
Fetch was set to:
•
Y, the address in Fetch Data Pointer points to the two-byte length field that precedes
the returned data.
•
N, the address in Fetch Data Pointer points to the first byte of the parcel body.
If Buffer Mode is used, that is, if Locate Mode is set to Y and Parcel Mode Fetch is set to N,
•
Variable Length Fetch must be set to N, and
•
The address in Fetch Data Pointer points to the first byte of the buffer, which is the first
byte of the parcel header of the first parcel.
In Locate Mode, DBCHCL places Fetch Data Pointer in the DBCAREA when the Fetch
function completes. Thus, Fetch Data Pointer is available when the application program
regains control with a return code of zero from a call to DBCHCL for the Fetch function.
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (FET)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
103
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
reads (FET)
Fetch Error Indicator
Usage Notes
The Fetch Error Indicator field specifies the status of the move in Move Mode.
Language
Variable Name
COBOL:
DBCAREA-FET-ERROR-IND
C: DBCAREA.H:
fet_error_ind
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (FET)
Used by
Action Taken
application program
reads
After a call to DBCHCL for the Fetch function and the request was issued with Move Mode in
effect, the application program can obtain an indicator of the success of the move. If the Move
area is too small to hold the parcel, Fetch Error Indicator is set to 0xFF; otherwise, Fetch Error
Indicator is set to 0x00.
If Fetch Error Indicator is set to 0xFF after a call to DBCHCL for the Fetch function in Move
Mode, the application program may re-allocate the Move area so that it is at least as long as the
value in Fetch Returned Data Length. It may then re-issue the call to DBCHCL for the Fetch
function.
DBCHCL places Fetch Error Indicator in the DBCAREA when the Fetch function completes.
Thus, Fetch Error Indicator is available when the application program regains control with a
return code of zero from a call to DBCHCL for the Fetch function. The application should
check this field, in case CLI returns with BUFOVFLOW to confirm that it needs to re-allocate
its Move area as notified by CLI in Fetch Returned Data Length.
104
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Fetch Maximum Data Length
Usage Notes
The Fetch Maximum Data Length field specifies the length in bytes of the Move area, if any,
allocated by the application program.
If the application program is using Move Mode for processing the parcels in the response, that
is, if Locate Mode is set to N and Parcel Mode Fetch is set to Y or N in the DBCAREA, then the
application program must allocate the Move area and place its length in Fetch Maximum Data
Length before calling DBCHCL for the Connect, Run Startup, or Initiate Request functions.
Language
Variable Name
COBOL:
DBCAREA-FET-MAX-DATA-LEN
C: DBCAREA.H:
fet_max_data_len
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (FET)
Used by
Action Taken
application program
writes
Fetch Parcel Flavor
Usage Notes
The Fetch Parcel Flavor field is the flavor of the parcel containing the returned data.
Language
Variable Name
COBOL:
DBCAREA-FET-PARCEL-FLAVOR
C: DBCAREA.H:
fet_parcel_flavor
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (FET)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
105
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
reads
After a call to DBCHCL for the Fetch function, the application program can obtain the flavor
or type of parcel returned if Parcel Mode Fetch was set to Y when DBCHCL was called for the
Connect, Run Startup, or Initiate Request function.
DBCHCL puts Fetch Parcel Flavor in the DBCAREA when the Fetch function completes. Thus
Fetch Parcel Flavor is available when the application program regains control with return code
of zero from a call to DBCHCL for the Fetch function.
Fetch Returned Data Length
Usage Notes
The Fetch Returned Data Length field specifies the length in bytes of the returned data.
Language
Variable Name
COBOL:
DBCAREA-FET-RET-DATA-LEN
C: DBCAREA.H:
fet_ret_data_len
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (FET)
Used by
Action Taken
application program
reads
After a call to DBCHCL for the Fetch function, the application program can obtain the length
of the returned data.
Where the length is provided and what the length refers to depends on the settings in effect
when DBCHCL is called for the Connect, Run Startup, or Initiate Request function:
•
If Locate Mode was set to N and Parcel Mode Fetch was set to Y and
•
If Variable Length Fetch was set to N,
then, the length is in Fetch Returned Data Length; length is the length of the parcel
body
•
106
If Variable Length Fetch was set to Y,
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
then, the length is in first two bytes at address given in Fetch Data Pointer; length is the
length of the parcel body
•
•
If Locate Mode was set to N and Parcel Mode Fetch was set to N and
•
if Variable Length Fetch was set to N, then the length is in Fetch Returned Data Length;
length is the length of the buffer copied into fet_data_ptr by CLI.
•
if Variable Length Fetch was set to Y, then there is an error
(this last option is not allowed).
If Locate Mode was set to Y and Parcel Mode Fetch was set to Y and
•
If Variable Length Fetch was set to N,
then, the length is in Fetch Returned Data Length; length is the length of the parcel
body
•
If Variable Length Fetch was set to Y,
then, the length is in first two bytes at address given in Fetch Data Pointer; length is the
length of the parcel body
•
If Locate Mode was set to Y and Parcel Mode Fetch was set to N and
•
If Variable Length Fetch was set to N,
then, the length is in Fetch Returned Data Length; length refers to the grand total of all
parcels (headers and bodies) in the response buffer
•
If Variable Length Fetch was set to Y,
then, there is an error (this last option is not allowed).
In Move Mode only the length number of bytes are affected in the Move area. The bytes
beyond are left “as is.”
DBCHCL places Fetch Returned Data Length, if used, in the DBCAREA when the Fetch
function completes. Thus Fetch Data Pointer is available when the application program
regains control with return code of zero from a call to DBCHCL for the Fetch function.
Function
Usage Notes
The Function field specifies the operation to be carried out by DBCHCL.
Language
Variable Name
COBOL:
DBCAREA-FUNC
C: DBCAREA.H:
func
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
107
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
writes
The application program must set the Function field to the appropriate non-zero value before
calling DBCHCL. It is recommended that mnemonics be used for the codes.
Each of the following codes represents a different operation:
Code
Operation
Mnemonic
1
Connect
DBFCON
2
Disconnect
DBFDSC
3
Run Startup
DBFRSUP
4
Initiate Request
DBFIRQ
5
Fetch
DBFFET
6
Rewind
DBFREW
7
Abort
DBFABT
8
End Request
DBFERQ
15
Continue Request
DBFCRQ
Input DBCpath
Usage Notes
The Input DBCpath field is not used. Instead, the default value in the SPB is used. The value of
Input DBCpath in the DBCAREA is ignored.
108
Language
Variable Name
COBOL:
DBCAREA-I-DBCPATH
C: DBCAREA.H:
i_dbcpath
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
none
Input Request Id
Usage Notes
The Input Request Id field specifies the request to be acted on by DBCHCL.
Language
Variable Name
COBOL:
DBCAREA-I-REQ-ID
C: DBCAREA.H:
i_req_id
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (FET; REW; ERQ; ABT)
Used by
Action Taken
application program
writes
The application program copies the value that was placed by the Connect, Run Startup, or
Initiate Request function in Output Request Id into Input Request Id.
If the application program uses the same DBCAREA for more than one concurrent request or
more than one session, it should save the Output Request Id from each request’s submission.
The application program must store the appropriate value of Output Request Id in Input
Request Id whenever it intends the next DBCHCL call to affect a different request.
Input Session Id
Usage Notes
The Input Session Id field specifies the session to be acted on by DBCHCL.
Language
Variable Name
COBOL:
DBCAREA-I-SESS-ID
C: DBCAREA.H:
i_sess_id
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
109
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (RSUP; IRQ; FET; REW; ERQ; ABT; DSC)
Used by
Action Taken
application program
writes
The application program copies the value from Output Session Id into Input Session Id.
If the application program uses the same DBCAREA to run sessions concurrently, it should
save Output Session Id from each session’s logon. The application program must store the
appropriate value of Output Session Id in Input Session Id whenever it intends the next
DBCHCL call to affect a different session.
Connects only take place by calls to DBCHCL for the Connect function.
Keep Response
Usage Notes
The Keep Response field specifies whether or not the Teradata Database is to keep the spool
file and repositioning information after it sends the last parcel of the Teradata SQL response to
the client.
Language
Variable Name
COBOL:
DBCAREA-KEEP-RESP
C: DBCAREA.H:
keep_resp
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Keep Response is initialized by DBCHINI to the default value provided for Keep Response in
the site’s SPB.
110
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request function, the application program may set:
•
Change Options to Y, and
•
Keep Response to:
•
Y, if the spool file is to be retained by the Teradata Database even after the last parcel of
the Teradata SQL response has been sent to the client.
•
N, if the spool file is to be discarded by the Teradata Database after the last parcel of the
Teradata SQL response has been sent.
•
P, if the applications are to use cursor repositioning while fetching the response.
A call to DBCHCL for the Rewind function will not fail if Keep Response is set to N as long as
all the parcels in the Teradata SQL response can fit in one response buffer.
Note: Always set keep_resp to 'N' while initiating a connect request.
Language Conformance
Usage Notes
The Language Conformance field specifies whether or not SQL requests are to be checked for
conformance with a particular standard.
The option is rejected unless you also specify Connect Type C.
Language
Variable Name
COBOL:
DBCAREA-CONFORMANCE
C: DBCAREA.H:
lang_conformance
Routine
Action Taken
DBCHINI
writes
DBCHCL
reads (CON)
Used by
Action Taken
application program
writes
The values for the Language Conformance field are:
•
N (none)
•
2 (FIPS127-2)
•
3 (FIPS127-3)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
111
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language Id
Usage Notes
Language Id is a 2-byte field that specifies the language to be used for all CLI error messages
returned in the Message Text DBCAREA field, associated with the current session. The value
specifies a two-character Language Id. The entire value is in ASCII and must be in upper case.
Language
Variable Name
COBOL:
DBCNILID
C: DBCAREA.H:
dbniLid (case-sensitive)
Routine
Action Taken
DBCHINI
writes
DBCHCL
reads (CON)
Used by
Action Taken
application program
writes
DBCHINI initializes the Language Id to the default value provided in the clispb.dat file being
used. Otherwise, it picks up the default language, English, from CLISPB.
If the default value for Language Id is not appropriate for the application, perform the
following before calling DBCHCL for the connect function:
1
Set Change Options to “Y”.
2
Change the value as appropriate:
•
ENGLISH = EN
•
JAPANESE = JA
These are the only two languages supported in this release. If any other value is entered, the
default language (English) is used.
Locate Mode
Usage Notes
The Locate Mode field specifies where the data returned is to be made available.
112
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBCAREA-LOC-MODE
C: DBCAREA.H:
loc_mode
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Locate Mode is initialized by DBCHINI to the default value provided for Locate Mode in the
site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request function, the application program may set:
•
Change Options to Y, and
•
Locate Mode to:
•
Y, if the data returned is to be made available in the response buffer.
•
N, if the data returned is to be made available in the Move area.
A Locate Mode of Y is known as Locate Node. A Locate Mode of N, with Parcel Mode Fetch of
Y, is known as Move Mode. (Locate Mode operates in conjunction with Parcel Mode Fetch.)
The setting of Locate Mode affects the use of Fetch Maximum Data Length, Fetch Data
Pointer, Fetch Returned Data Length, Fetch Parcel Flavor, and Fetch Error Indicator.
Do not set both Variable Length Fetch and Locate Mode to Y.
Logon Length
Usage Nodes
The Logon Length field is the length in bytes of the logon string.
Language
Variable Name
COBOL:
DBCAREA-LOGON-LEN
C: DBCAREA.H:
logon_len
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
113
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
Before a call to DBCHCL for the Connect function, the application program sets Logon
Length to the length of the string whose address is provided in Logon Pointer.
Logon Pointer
Usage Notes
The Logon Pointer field specifies the address of the logon string for the session.
114
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBCAREA-LOGON-PTR
C: DBCAREA.H:
logon_ptr
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
Before calling DBCHCL for the Connect function, the application program must build a
logon string and provide its address in Logon Pointer. A logon string has the following format:
[tdpid[.domain][:port]/][userid,password][,'acctid']
where
The variable...
Is...
tdpid
one of the dbcnames in the network-attached client’s host file on the
network. Both ip address and ip port format in tdpid are supported.
Examples are listed as follows:
"ipaddress/username,passwd..."
"ipaddress:port/username,passwd..."
"dbcname:port/username,passwd..."
Simple machine names that are used as TDPids should be unique across
multiple domains (that is, the high-level qualifier in the fully-qualified
domain name should be unique).
For example, bteqdev.sandiegoca.teradata.com and
bteqdev.northpole.hellokitty.com should not be used in the same job.
When a simple machine name is supplied and there is no corresponding
entry in the local hosts file, gethostbyname() appends the default domain
name as found in /etc/resolv.conf (for UNIX) or in Advanced TCP/IP
Settings (for Windows). This is done to obtain a valid IP address from
DNS.
If tdpid is omitted, CLI uses the default for dbcname in the SPB
(see Chapter 4: “System Parameter Block (SPB) Processing”).
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
115
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
The variable...
Is...
userid
the user’s id on the corresponding database computer. Maximum length
of userid is 30 bytes (alpha characters are not case specific; dollar sign ($),
pound sign (#), and underscore (_) are allowed anywhere in userid;
numbers are allowed but the first character may not be numeric).
password
the password on the corresponding database computer. Maximum length
of password is 30 bytes (alpha characters are not case specific; dollar sign
($), pound sign (#) and underscore (_) are allowed anywhere in userid;
numbers are allowed but the first character may not be numeric).
acctid
the account to be charged on network-attached clients. Maximum length
of acctid is 30 bytes.
Note: Do not end the logon string with a semicolon.
Logon Pointer always points to the beginning of the logon string.
Kanji Support
Kanji characters used in userid, password and acctid are limited to a maximum of 30 bytes.
Because Kanji characters may be double or triple bytes, the maximum length when counted in
Kanji characters should be less than 30. For example, if the userid contains only double byte
Kanji characters, the maximum length for userid should be 15 Kanji characters.
Kanji characters are only allowed in userid, password and acctid. Blanks, commas and slashes
must be single byte characters.
Logon Mechanism Data Length
Usage Notes
If additional data is required by the specified logmech_name, logmech_data_len specifies the
length, in bytes, of the area addressed by logmech_data_ptr.
116
Language
Variable Name
COBOL
DBCNIMDL
C
logmech_data_len
Routine
Action Taken
DBCHINI
writes
DBCHCL
reads (CON)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used By
Action Taken
application program
writes
The value must be positive with a maximum value of:
•
32763 if the Maximum-parcel option is set to 'O', or
•
64 K if the Maximum-parcel option is set to 'H'.
Logon Mechanism Data Pointer
Usage Notes
If additional data is required by the specified logmech_name, logmech_data_ptr addresses
that data, specified in the session character set.
If a logmech_name is not specified, the value will be ignored.
Currently, the maximum length is 65535 bytes.
Language
Variable Name
COBOL
DBCNIMDP
C
logmech_data_ptr
Routine
Action Taken
DBCHINI
writes
DBCHCL
reads (CON)
Used by
Action Taken
application program
writes
Currently, the maximum meaningful length is 256 characters.
Multibyte Character Support
When the session character set is KANJIEBCDIC5026_0I, KANJIEBCDIC5035_0I, or
KATAKANAEBCDIC, double-byte characters may be included by preceding each contiguous
group of them with the Shift-out control byte, X’0E’, and following this group with the
Shift-in control byte, X’0F’.
When the session character set is UTF8, each character requires between one and three bytes.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
117
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
When the session character set is KANJIEUC_0U, each character requires one or two bytes,
each possibly preceded by a Single-shift-2, X'8E', or Single-shift-3, X'8F', control byte. So each
character requires a total of between one and three bytes.
When the session character set is KANJISJIS_0S, each character requires one or two bytes.
Logon Mechanism Name
Usage Notes
The logmech_name field specifies the name of the logon mechanism to be used to
authenticate the connection. A name is ignored if it consists solely of spaces or binary zeroes.
If required, additional data for the mechanism may be supplied using the logmech_data_ptr
and logmech_data_len. If the specified mechanism is not supported, the request will be
rejected.
Language
Variable Name
COBOL
DBCNIMNM
C
logmech_name
Routine
Action Taken
DBCHINI
writes
DBCHCL
reads (CON)
Used by
Action Taken
application program
writes
Upon return from the Connect function, logmech_name will contain the mechanism name
used, monocased as necessary.
Maximum Decimal Precision
Usage Notes
The Maximum Decimal Precision field indicates the precision of decimal data types in
responses. The supported values are:
•
a positive value up to a maximum obtained using the DBCHQE SQL-limits query.
•
binary zero (the default) if the client default (18) is used.
Valid values are 0 through 255.
118
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
MAX-DECIMAL-RETURNED
C:
max_decimal_returned
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (RSUP; IRQ)
Used by
Action Taken
application program
writes
Maximum Number Of Sessions for a Single Process
Usage Notes
The Maximum Number Of Sessions field specifies the maximum number of sessions that the
application program is allowed to have running concurrently on database computers.
Language
Variable Name
COBOL:
DBCAREA-MAX-NUM-SESS
C: DBCAREA.H:
max_num_sess
Routine
Action Taken
DBCHINI:
reads
DBCHCL:
ignores
Used by
Action Taken
application program
none
The value of zero indicates that DBCHCL is to use the default value from the SPB for the
Maximum Number Of Sessions. The maximum possible value for this field is systemdependent, that is, limited to the number of open file descriptors a process is allowed.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
119
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
The application program generates sessions on more than one database computer, the
application still cannot have more than Maximum Number Of Sessions, in total, running
concurrently.
The application program generates sessions on more than one database computer, the
application still cannot have more than Maximum Number Of Sessions, in total, running
concurrently.The application program calls DBCHCL for the Connect function when it
already has Maximum Number Of Sessions logged on, the return code from DBCHCL will be
non-zero.
The default value of Maximum Number of Session, which is 300, can only be changed by an
application by setting the max_num_sess field in the clispb.dat file. If this DBCAREA field is
set, CLI ignores this field.
Maximum Parcel
Usage Notes
Maximum Parcel specifies whether the maximum parcel length is 32 KB, 64 KB, or 1 MB
bytes. The exact size depends upon numerous factors related to the nature and structure of a
specific request.
120
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
MAXIMUM-PARCEL
C: DBCAREA.H:
maximum_parcel
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RESUP; IRQ)
Used by
Action Taken
application program
writes
Maximum Parcel is initialized to the default value provided for Maximum Parcel in the site’s
CLISPB. If the value is not appropriate for the application, the application, before calling
DBCHCL for Connect, Run Startup and Initiate Request, may set Change Options to Y and
Maximum Parcel to one of the following values:
•
O, if the original limit of 32 KB is the maximum size of one parcel.
•
H, if the limit of 64 KB or 1 MB (APH-requests/extended response support exists at the
server) is the maximum size of one parcel.
When the actual row size to be returned is:
•
Less than 32 KB and the response buffer is not large enough to hold a parcel, the Teradata
server returns a 3116 error. In response, CLI will retry with a larger buffer size.
•
Greater than 32 KB and the response buffer is not large enough to hold a parcel, the
Teradata server returns a 3115 error. CLI will retry with a larger buffer size only if
Maximum Parcel is set to H. If Maximum Parcel is set to O, CLI will not retry the 3115
error with a larger buffer size, but will return the 3115 error to the user. This prevents retry
looping.
•
Greater than 64 KB and the response buffer is not large enough to hold a parcel, the
Teradata server returns a 3177 error followed by an ErrorInfo parcel with an InfoType of 1
(PCLBUFFERSIZE). CLI will retry with a larger buffer size only if Maximum Parcel is set
to H. If Maximum Parcel is set to O, CLI will not retry the 3177 error with a larger buffer
size, but will return the 3177 error to the user. This prevents retry looping.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
121
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Determining Maximum Parcel Request Size
Maximum parcel size is determined by which of the two parcel header formats is used. The
maximum lengths are as shown below:
•
When maximum_parcel is 'O':
- buffer size limit: ~32KB
•
When maximum_parcel is 'H:'
- buffer size limit: ~64KB (APH-requests is 0)
•
When maximum_parcel is 'H:'
- buffer size limit: ~1MB (APH-requests is non-zero)
Message Area Length
Usage Notes
Message Area Length is a 2-byte field that is the length of the area pointed to by the Message
Area Pointer field.
The value is equivalent to the maximum length of a message that can be returned in that area.
CLI does not alter this value, so after it is set, it remains unless changed by the application.
Language
Variable Name
COBOL:
DBCIMSGM
C: DBCAREA.H:
dbciMsgM (case-sensitive)
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads
Used by
Action Taken
application program
writes
If the Message Area Pointer is not specified, this value is ignored.
Message Area Pointer
Usage Notes
The Message Area Pointer field specifies the address of an area into which any error message
will be placed.
122
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
The Message Area Length field specifies the length of the addressed area. CLI does not alter
this value, so after it is set, it remains unless changed by the application.
Language
Variable Name
COBOL:
DBCIMSGP
C: DBCAREA.H:
dbciMsgP (case-sensitive)
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads
Used by
Action Taken
application program
writes
An error message is returned when a CLI routine that uses the DBCAREA returns a non-zero
return code. The message will be contained either in the Message Text field within the
DBCAREA or in the area addressed by Message Area Pointer. A message is never returned in
both places. If a Message Area Pointer in not specified, the Message Text field will contain the
message and Message Length will return the length of the message. If a Message Area Pointer is
specified, the area addressed will contain the message and Message Length will return the
length of the message.
If an error occurs while building the message, the Message Return Code field will contain a
CLI return code. When this code is non- zero, the text of the message may be usable,
depending on the nature of the error.
Messages are returned in this area depending on the Language Id specified by the application.
If an error occurs before the Language Id is determined, CLI will return the message in
English.
Message Charset Used
Message Charset Used is a 1-byte field that indicates the character set used to construct the
message. The value in this field is returned by CLIv2 rather than by the application.
Language
Variable Name
COBOL:
DBCOMSGMC
C: DBCAREA.H:
dbcoMsgC (case-sensitive)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
123
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes
Used by
Action Taken
application program
reads
Message Charset Used is a 1-byte character field that indicates the character set used to
construct the message. The value of this field is set by CLIv2 rather than by the application.
•
'S' indicates that the session character set is used.
•
'D' indicates that the default CLIv2 character set (ASCII) is used.
The session character set is always used if known, but if an error occurs before the character
set is known, the default CLIv2 character set is used.
Message Length
Usage Notes
The Message Length field is the length of the message in Message Text.
Language
Variable Name
COBOL:
DBCAREA-MSG-LEN
C: DBCAREA.H:
msg_len
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes
Used by
Action Taken
application program
reads
Message Length is available after every call to DBCHCL, even those with return code of zero.
If the Message Area Pointer is specified, this value is not returned.
124
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Message Length Returned
Usage Notes
The Message Length Returned field is a 2-byte field that is the length of the message returned
by CLI. The message is returned to the area pointed to by the Message Area Pointer field.
The value is equal or less than the maximum length of a message that can be returned in that
area.
Language
Variable Name
COBOL:
DBCOMSGL
C: DBCAREA.H:
dbcoMsgL (case-sensitive)
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes
Used by
Action Taken
application program
reads
Information in this field is valid only if a Message Area Pointer is specified.
Message Return Code
Usage Notes
The Message Return Code is a 2-byte field that is the CLI return code for any error that
occurred while constructing the message. If no error occurred, binary zeroes are returned.
Language
Variable Name
COBOL:
DBCOMSGMR
C: DBCAREA.H:
dbcoMsgR (case-sensitive)
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
125
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
reads
CLI returns the following error codes:
•
0 - Message returned successfully
•
1 - Truncated error message
Message Text
Usage Notes
The Message Text field is the text of the message indicated by Return Code. Message Text is
available in the DBCAREA after every call to DBCHCL even those with return code of zero.
Language
Variable Name
COBOL:
DBCAREA-MSG-TEXT
C: DBCAREA.H:
msg_text
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes
Used by
Action Taken
application program
reads
Only Message Length bytes are guaranteed to be affected in Message Text.
An error message is returned when a CLI routine that uses the DBCAREA ends with a nonzero/Zero return code. The message will be contained in Message Text field within the
DBCAREA only if the area addressed by Message Area Pointer is NULL. Message Length will
return the length of the message.
Language used to return the message in this field is driven by the Language Id field in
DBCAREA. If an error occurs before the Language Id is determined, CLI will return the error
message in English.
126
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
MTDP Received
Usage Notes
The MTDP Received field specifies the actual time in seconds that MTDP received the
response from the database computer.
Language
Variable Name
COBOL:
(FILLER)
C: DBCAREA.H:
mtdp_received
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (CON; FET)
Used by
Action Taken
application program
reads
After a call to DBCHCL for the Connect or Fetch function and if Return Time is set to Y, the
application program can obtain the value of MTDP Received.
Use of this field is deprecated. For more information, see Chapter 18: “Performance
Measurement.”
MTDP Sent
Usage Notes
The MTDP Sent field specifies the actual time in seconds at which MTDP sent the request to
the database computer.
Language
Variable Name
COBOL:
(FILLER)
C: DBCAREA.H:
mtdp_sent
Routine
Action Taken
DBCHINI:
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
127
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHCL:
writes (CON: IRQ; FET; REW; ABT)
Used by
Action Taken
application program
reads
After a call to DBCHCL for the Connect, Initiate Request, Fetch, Rewind, or Abort function
and if Return Time is set to Y, the application program can obtain the value of MTDP Sent.
Use of this field is deprecated. For more information, see Chapter 18: “Performance
Measurement.”
Output DBC Session Id
Usage Notes
The Output DBC Session Id field is the actual, not logical, identifier assigned to the session by
the Teradata Database. It is provided for diagnostic purposes, audit logs, and so on.
Language
Variable Name
COBOL:
DBCAREA-O-DBC-SESS-ID
C: DBCAREA.H
o_dbc_sess_id
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (FET associated with connect operation)
Used by
Action Taken
application program
reads
Output DBC Session Id is available in the DBCAREA when the application program regains
control (with return code zero) from calling DBCHCL for the first Fetch function that is
associated with the connect operation.
Compare with Output Session Id.
128
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Output DBCpath
Usage Notes
The Output DBCpath field specifies the route used to send to and from the database computer
for the session. It is provided for diagnostic purposes and for logs, such as audit logs.
Language
Variable Name
COBOL:
DBCAREA-O-DBCPATH
C: DBCAREA.H:
o_dbcpath
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (FET associated with connect operation)
Used by
Action Taken
application program
reads
After regaining control from a call to DBCHCL for the Connect function, the application
program can obtain the route used from Output DBCpath. The Output DBCpath contains the
name of the set of co-COPs used for the session.
Output DBCpath is available in the DBCAREA when the application program regains control,
with return code zero, from calling DBCHCL for the first Fetch function that is associated
with the connect operation.
Output Host Id
Usage Notes
The Output Host Id field specifies the host id for the set of IFPs or COPs. In effect, it identifies
the logical LAN. It is provided for diagnostic purposes, audit logs, and so on.
Language
Variable Name
COBOL:
DBCAREA-O-HOST-ID
C: DBCAREA.H:
o_host_id
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
129
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (FET associated with connect operation)
Used by
Action Taken
application program
reads
Output Host Id is available in the DBCAREA when the application program regains control
(with return code zero) from calling DBCHCL for the first Fetch function that is associated
with the connect operation.
Output Host Id is a two-byte (16 bit) field. The ten least significant bits are the host number
which is in unsigned binary.
Output Request Id
Usage Notes
The Output Request Id field is CLI’s logical identifier of a given request on the database
computer.
Language
Variable Name
COBOL:
DBCAREA-O-REQ-ID
C: DBCAREA.H:
o_req_id
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (CON; RSUP; IRQ)
Used by
Action Taken
application program
reads
When the application program regains control from a call to DBCHCL for the Connect, Run
Startup, or Initiate Request function, the logical request id is available in the DBCAREA in
Output Request Id.
130
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Before using the DBCAREA again to call DBCHCL for an operation related to that request,
the application program must copy the value to Input Request Id.
DBCHCL places Output Request Id in the DBCAREA as soon as DBCHCL is called for a
request-generating function. Output Request Id is available after the application program
regains control from DBCHCL, even in a connect operation.
Compare with TDP Request Number, below. The Teradata Database and CLI have a number
for each request and the numbers are not identical.
Output Session Id
Usage Notes
The Output Session Id field is CLI’s logical identifier of a given session on the database
computer.
Language
Variable Name
COBOL:
DBCAREA-O-SESS-ID
C: DBCAREA.H:
o_sess_id
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes (CON)
Used by
Action Taken
application program
reads
After the application program regains control from a call to DBCHCL for the Connect
function, the logical session id is available in the DBCAREA in Output Session Id. Before
using the DBCAREA again to call DBCHCL for the session, the application program must
copy the value to Input Session Id.
DBCHCL places Output Session Id in the DBCAREA as soon as DBCHCL is called for a
session-generating function. Thus Output Session Id is available after the application program
regains control from DBCHCL, even in a connect operation.
Compare with Output DBC Session Id. Note that both the database computer and CLI have a
number for each session and that the two numbers are not identical.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
131
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Parcel Mode Fetch
Usage Notes
The Parcel Mode Fetch field specifies whether fetches are to provide the next parcel or the next
buffer-full of returned data.
Language
Variable Name
COBOL:
DBCAREA-PARCEL-MODE
C: DBCAREA.H:
parcel_mode
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Parcel Mode Fetch is initialized by DBCHINI to the default value provided for Parcel Mode in
the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request function, the application program may set:
•
Change Options to Y, and
•
Parcel Mode Fetch to:
•
Y, if each fetch is to provide the next parcel (Parcel Mode Fetch set to Y is known as
Parcel Mode).
•
N, if each fetch is provide the next buffer-full of parcels (Parcel Mode Fetch set to N is
known as Buffer Mode).
If Buffer Mode is in effect, each fetch results in a new buffer-full of parcels. It is assumed that
the application program has “consumed” the previous buffer-full of parcels.
Period-as-Struct
Usage Notes
Period-as-Struct is a one byte ASCII field that indicates whether to treat Period data types as
Structured UDTs in honoring the Transforms-off option and return information about the
constituent attributes.
132
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
PERIODASSTRUCT
C:
periodAsStruct
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (RSUP; IRQ)
Used by
Action Taken
application program
writes
Possible value that can be set in this DBCAREA field is 'Y' and 'N'.
•
'N' - the value of 'N' indicates that Period data types are treated as simple data types.
•
'Y' - the value of 'Y' indicates that Period data types are treated as Structured UDTs in
honoring the Transforms-off option. Setting "periodAsStruct" to 'Y' requires setting the
"transformsOff " to 'Y' at the same time. If not, DBS will return an error since the support
of Period as Struct is an extension of the support of Structured UDTs.
Positioning-action
Usage Notes
Positioning-action specifies the position in the response from which the Fetch is to be
performed.
Language
Variable Name
C: DBCAREA.H:
positioning_action or dbfiPAct
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (FET)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
133
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
writes
One of the following values may be set before calling the Fetch function:
Set Value
To...
0
fetch the next parcel. This is the default.
1
fetch the first parcel in the row number, specified by Positioning-value for the
statement and Positioning-statement-number.
2
fetch bytes in the Binary Large Object (BLOB), beginning at the byte offset.
Specified by Positioning-value for the statement and Positioning-statementnumber. This may be done only if a single BLOB was selected using a locator.
3
fetch characters in the Character Large Object (CLOB), beginning at the character
offset. Specified by Positioning-value for the statement and Positioningstatement-number. This may be done only if a single CLOB was selected using a
locator.
Use of this option requires that Keep-response=P be specified when initiating the request.
Use of this setting does not require use of Change-option. That is, Positioning-action
overrides Change-option setting.
Positioning-statement-number
Usage Notes
Positioning-statement-number specifies the statement number for the Fetch that is to be
performed when Positioning-action indicates other than Next-parcel.
134
Language
Variable Name
C: DBCAREA.H:
positioning_stmt_number
or dbfiPSNm
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (FET)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
writes
Use of this setting does not require use of Change-option. That is, honoring Positioningstatement-number depends only upon the setting of Positioning-action, not Change-option.
Positioning-value
Usage Notes
Positioning-value specifies either the row number, the byte offset into a BLOB, or the
character offset into a CLOB, from which the Fetch is to be performed when Positioningaction indicates other than Next-parcel.
When specifying a row number, by convention, a value of zero represents parcels that precede
the first row (such as, Success or OK). When specifying a byte or character offset, by
convention, a value of zero corresponds to the first byte or character. A value of zero also
returns Success, Data-information-extended, and No-operation parcels before the
Multipart-record parcel for the start of the data.
Language
Variable Name
C: DBCAREA.H:
positioning_value
or dbfiPVal
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (FET)
Used by
Action Taken
application program
writes
Use of this setting does not require use of Change-option. That is, honoring Positioning-value
depends only upon the setting of Positioning-action, not Change-option.
Request Buffer Length
Usage Notes
The Request Buffer Length field specifies the desired length of the buffer in which requests are
placed for sending to the Teradata Database.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
135
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBCAREA-REQ-BUF-LEN
C: DBCAREA.H:
req_buf_len
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP; IRQ; REW; ABT)
Used by
Action Taken
application program
writes
A value of zero indicates that DBCHCL is to use the default value from the SPB for the
Request Buffer Length. The application program may change the value in Request Buffer
Length. The minimum value is 256 and the maximum value is:
•
32768, if Maximum Parcel is set to O
•
65536, if Maximum Parcel is set to H
•
1048500, if Maximum Parcel is set to H and the Teradata server supports
ExtendedRespond, as indicated by the DBCHQE QEPIXRS item.
The size of the request buffer is increased by CLI if a larger buffer is required.
Note: If applications are using Parcel mode, the applications have to spare a buffer size of 24
bytes for CLI to place the parcels built by CLI in the request buffer.
Request Length
Usage Notes
Request Length field is the length in bytes of the request string.
136
Language
Variable Name
COBOL:
DBCAREA-REQ-LEN
C: DBCAREA.H:
req_len
Routine
Action Taken
DBCHINI:
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHCL:
reads (IRQ)
Used by
Action Taken
application program
writes
Before calling DBCHCL for the Initiate Request function and if Variable Length Request is set
to:
•
N, the application program must set the value of Request Length to the length of the
request string.
•
Y, the application program ignores Request Length and sets the value in the two-byte
length field that precedes the request text.
Request Mode
Usage Notes
The Request Mode field specifies the form that a request and optional data are passed from the
application program to CLI.
Language
Variable Name
COBOL:
DBCAREA-REQUEST-MODE
C: DBCAREA.H:
request_mode
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (COM; RSUP:IRQ)
Used by
Action Taken
application program
writes
Request Mode is initialized to the default value provided for Connect Type in the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL for the
Initiate Request option the application program may set:
•
Change Options to Y, and
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
137
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
•
Request Mode to:
•
P, if the application program is passing to CLI the Request parcel body and, optionally,
the Using Data parcel body and, optionally, parcel elements in the DBCAREA
extension, DBCAREAX.
•
B, if the application program is passing to CLI a pre-built buffer containing parcels.
An application that uses Buffer Mode is responsible for setting the Keep Response option and
Response Buffer Size options consistent with the Response parcel provided in the pre-built
request buffer.
Note: The parcels included are just copied into the message and sent to the Teradata Database.
The application is responsible for building the parcel as demanded by the protocol being used.
This option is used by some defined protocols of the Teradata Database such as FastLoad, Hut,
and MultiLoad. It is not recommended for use in Teradata SQL sessions.
Request Mode is read by the call to DBCHCL for the Connect and Run Startup options and
stored in the appropriate control blocks, but it is not used during either function.
Request Pointer
Usage Notes
The Request Pointer field specifies the address of the request string.
Language
Variable Name
COBOL:
DBCAREA-REQ-PTR
C: DBCAREA.H:
req_ptr
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (IRQ)
Used by
Action Taken
application program
writes
Before calling DBCHCL for the Initiate Request function, the application program must build
a request string, such as a Teradata SQL request.
If Variable Length Request is set to:
•
138
N, Request Pointer must contain the address of the beginning of the request string.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
•
Y, Request Pointer must contain the address of the two-byte length field immediately
preceding the request string. See “Variable Length Request” on page 168.
The request string should not be enclosed in apostrophes. If there is more than one statement
in the request, a semicolon must separate the statements. A semicolon after the last statement
in the request is optional.
Note: If a USING modifier is included in the Teradata SQL request, the USING modifier must
be the very first clause in the request. The USING modifier names and describes each field of
the data pointed to by Using Data Pointer, in positional sequence. Each field name may be
referred to any number of times in any number of statements in that request, including the
case of no references to that name.
Example
Note: The following is an example of a valid request:
USING x1 (INTEGER), x2 (CHAR (2) )
SELECT * FROM t1 WHERE c1 = :x2;
SELECT * FROM t2 WHERE c2 = :x2;
Request Processing Option
Usage Notes
The Request Processing Option field specifies whether the Teradata Database is to return:
•
The data described in the request string, or
•
Information about the data described in the request string, or
•
BOTH.
Language
Variable Name
COBOL:
DBCAREA-REQ-PROC-OPT
C: DBCAREA.H:
req_proc_opt
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Request Processing Option is initialized by DBCHINI to the default value provided for
Request Processing Option in the site’s SPB.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
139
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request options, the application program may set:
•
Change Options to Y, and
•
Request Processing Option to:
•
E, if the Teradata Database is to execute the request in the request string and send back
the returned data,
•
P, if the Teradata Database is to analyze the request in the request string, and if:
•
•
•
Request is valid, send back a time estimate and format information about the data
that it would return if the request were executed (the time estimate is the same as
EXPLAIN returns)
•
Request is invalid, send back an Error or Failure parcel (the same as if Request
Processing Option is set to E).
S, analyze each statement in the request.
•
The statements may contain parameterized SQL. If the request is valid, the
Teradata server will return a time estimate and format information about the data
that would be returned if the request were executed.
•
The time estimate is the same as EXPLAIN returns.
•
The difference between the P and S mode is that P mode cannot contain a
parameterized SQL request.
B, analyze each statement in the request, then execute the request. The statements may
contain parameterized SQL. If the request is valid, the Teradata server will return not
only a time estimate and format information about the data that would be returned if
the request were executed, but also the data resulting from the executed request. The
time estimate is the same as EXPLAIN returns.
B option is supported both in buffer and parcel modes.
Note: Segmented requests(TDSP) are not supported in S, B, and P modes. If these
requests are submitted in either the S, B or P modes, the Teradata Database would
return a failure parcel with the error code set to 3749.
Request Processing Option is read by the call to DBCHCL for the Connect function and stored
in the appropriate control blocks, but is not used during the connect.
Response Buffer Length
Usage Notes
The Response Buffer Length field specifies the desired length of the buffer in which responses
received from the Teradata Database are made available to the application program.
140
Language
Variable Name
COBOL:
DBCAREA-RESP-BUF-LEN
C: DBCAREA.H:
resp_buf_len
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP; IRQ; REW; ABT)
Used by
Action Taken
application program
writes
The value of zero indicates that DBCHCL is to use the default value from the SPB bytes for the
Response Buffer Length. The application program may change the value in Response Buffer
Length as shown in the following sections.
Using CLICON
When connecting one or more sessions using CLICON, regardless of whether extended
response is supported by the server, the maximum response buffer size limit is:
•
~32K (for maximum_parcel='O')
•
~64K (for maximum_parcel='H')
After a session has been successfully connected, the maximum response buffer size limit is:
•
~32K (for maximum_parcel='O')
•
~64K (for maximum_parcel='H' when extended response support is not supported by the
server)
•
~1M (for maximum_parcel='H' when extended response is supported by the server)
Response Mode
Usage Notes
The types of parcels returned in a response that selects database fields are determined when
the request is made. Applications can drive the type of response needed from the Teradata
server by specifying any of the four values mentioned below in the Response Mode field of
DBCAREA while initiating a request.The four response modes are:
•
F - Field mode (returns database fields, except large objects, formatted as character data)
•
R - Record mode (returns non-null fields, except large objects, as unformatted data)
•
I - Indicator mode (returns all fields, except large objects, as unformatted data)
•
M - MultipartIndicator mode (returns all fields, including large objects, as unformatted
data with additional character set detail.)
For information on how and when to use this mode, see Chapter 17: “Large Objects (LOB)
Support.”
Field, Record, and Indicator modes will return an error if large objects are involved.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
141
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBCAREA-RESP-MODE
C: DBCAREA.H:
resp_mode
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP; IRQ)
Used by
Action Taken
application program
writes
Return Code
Usage Notes
The Return Code field specifies the state of the call as known by DBCHCL and MTDP.
Language
Variable Name
COBOL:
DBCAREA-RETURN-CD
C: DBCAREA.H:
return_cd
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
writes
Used by
Action Taken
application program
reads
After regaining control from DBCHCL, the application program uses Return Code as the first
indicator (initial status) of the success of the call.
142
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
A return code of zero indicates the call is successful as far as CLI and MTDP know. It does not
imply the call is successful on the database computer. The application program determines
that by examining the first parcel in the response.
The return code from a call to DBCHCL is output as the value in Return Code in the
DBCAREA, the value in Return Code in the parameter list of DBCHCL, and the returned
value of the DBCHCL function. The return code is identical in all three places.
Return Identity Data
Usage Notes
Return-identity-data specifies whether data is returned in response to an SQL INSERT
operation when Identity columns are involved. An Identity column is a table column created
using GENERATED AS IDENTITY SQL syntax.
This field is a one-byte switch located at hex offset +165.
Language
Variable Name
COBOL:
RETURN-IDENTITY-DATA
C:
return_identity_data
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (RSUP; IRQ)
Used by
Action Taken
application program
writes
Value
Description
N
This is the default. If N is set, there is no auto-generated key retrieval.
C
This value specifies column-oriented retrieval.
R
This value specifies row-oriented retrieval.
The passed values must be in ASCII.
Do not specify Return-identity-data in clispb.dat or HSHSPB; you can only use Returnidentity-data with the DBFIRQ function.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
143
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Return Object
Usage Notes
Return Object specifies how large objects (LOBs) are to be returned to the application. The
value indicates whether the actual data, or locators to the actual data, are returned.
This field is initialized to the default value provided in the clispb.dat file. If the default is not
appropriate for the application, the following must be performed before calling DBCHCL for
the Initiate or Initiate With function.
1
Set Change options to “Y”.
2
Set the value to one of the following:
•
D - Data (default)
•
T - Transaction-related locator
•
S - Spool-related locator
Note: These values are case sensitive.
Language
Variable Name
COBOL:
DBRIROB
C: DBCAREA.H:
dbriROb/return_object
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads
Used by
Action Taken
application program
writes
Return Time
Usage Notes
The Return Time field specifies whether or not time stamps are to be generated for the
application program.
144
Language
Variable Name
COBOL:
DBCAREA-RET-TIME
C: DBCAREA.H:
ret_time
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ; FET; REW; ERQ; ABT)
Used by
Action Taken
application program
writes
Return Time is initialized by DBCHINI to the default value provided for Return Time in the
site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL, the
application program may set:
•
Change Options to Y, and
•
Return Time to:
•
Y, if time stamps are to be provided.
•
N, if time stamps are not to be provided.
When time stamps are specified for the Fetch function, the time stamps provided are only
valid on the first call to DBCHCL for the Fetch function. The time stamps may be changed
later, for instance, if DBCHCL exchanges information with the Teradata Database to keep the
response buffer stocked.
It is recommended that only diagnostic applications use the time stamp capability.
The Fetch, Rewind, End Request, and Abort functions read and use the value of Return Code,
but do not store it.
Run Length
Usage Notes
For existing applications that set the Connect Type to R, if Run Pointer field is not zero, the
application program, before calling DBCHCL for the Connect function, must set the value of
Run Length to the length of the run string whose address is in Run Pointer.
Language
Variable Name
COBOL:
DBCAREA-RUN-LEN
C: DBCAREA.H:
run_len
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
145
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
If the connect-type is set to C, a logon parcel will be built based on the value set in Run
Length.
•
If the value is 16 or less, the LSN and Function fields in the connect parcel are set to zero
and run string in the connect parcel is left justified (in 16 bytes) and spaced-filled to the
right.
•
If the value is 17 to 24, what the Run Pointer points to is moved into a connect parcel, left
justified and zero-filled to the right.
Run Pointer
Usage Notes
The Run Pointer field specifies a particular set of services to be used by the Teradata Database
session.
Language
Variable Name
COBOL:
DBCAREA-RUN-PTR
C: DBCAREA.H:
run_ptr
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
If Run Pointer is zero, DBCHCL will use Teradata SQL as the default value.
146
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
The application program may specify the value of Run Pointer. To do so, the program must
build a run string or a Connect parcel body and set Run Pointer to the address of the run
string for the Run parcel or the address of the connect parcel body before calling DBCHCL for
the Connect function. Teradata SQL is an allowed value. Run string is not case sensitive.
Run Pointer is the address of the beginning of the run string.
Segment Data
Usage Notes
Segment Data specifies the processing to be performed when statements of a stored procedure
are being segmented into multiple requests. The value indicates whether the request is for the
first, intermediate, or last segment, or if processing is cancelled.
Language
Variable Name
COBOL:
DBRISEG
PL/I
DBRISEG
Assembler
DBRISEG
C
dbriSeg
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads for (IRQ; IWPF)
Used by
Action Taken
application program
writes
DBCHINI initializes the value 'N'.
When segmenting data is appropriate for the application, you should perform the following
procedure before calling DBCHCL for the Initiate Request or Initiate With Protocol Function
functions (although with the latter the Initiate Protocol-function must be 'N'):
1
Set Change Options to Y.
2
Change the value for Segment Data as follows:
If desired segment action is to be...
Then change Segment Data to...
no segmenting
N
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
147
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
If desired segment action is to be...
Then change Segment Data to...
first segment
F
intermediate segment
I
last (or only) segment
L
cancel segmenting
C
If Segment Data is other than 'N', then the following options must be used:
•
Keep Response option must also be 'N'
•
Request Mode option must be 'P'
•
Request Processing option must be 'E'
•
Initiate Protocol-function option must be 'N' (if the Initiate with Protocol Function
function is used).
Statement-status
Usage
Statement-status specifies whether or not the server may return ResultSummary parcels rather
than Success or ResultSummary or OK parcels.
148
Language
Variable Name
COBOL
DBCNISS
PL/I
DBCNISS
C
dbcniSS
IBM Assembler
DBCNISS
Routine
Action Taken
DBCHINI
writes
DBCHCL
reads (RCON, IRQ, IWPF)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
writes
One of the following values may be set before
establishing a connection:
‘O’ indicates that Success or OK parcels are
returned
‘E’ indicates that ResultSummary parcels may be
returned.
Use mnemonics, which are provided in the language definition file for the DBCAREA, for the
codes.
Tell About Crash
Tell About Crash is functionally identical to Tell About Delay.
Usage Notes
The Tell About Crash field specifies whether or not the application program is to be informed
of a computer crash/restart while waiting for the restart to complete.
•
If a restart is detected during logoff processing, CLI reconnects the session and resubmits
the logoff request.
•
If a restart occurs during a logoff request, CLI automatically resubmits the request.
Note: FastLoad and BTEQ applications cannot use the CAP library because it overrides
FastLoad and BTEQ settings. Thus, the DBCAREA must be changed dynamically to effect
a change to Tell About Crash.
Language
Variable Name
COBOL:
DBCAREA-TELL-ABOUT-CRASH
C: DBCAREA.H:
tell_about_crash
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ; FET; REW; ERQ; ABT)
Used by
Action Taken
application program
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
149
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Tell About Crash is initialized by DBCHINI to the default value provided in the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL the
application program may:
•
Set Change Options to Y, and
•
Change the value in Tell About Crash to:
•
‘Y’ - if notification is to take place during the wait period
•
‘N’ - if notification is not to take place during the wait period.
Used with Wait Across Crash
The combination of Tell About Crash set to N and Wait Across Crash set to N is not allowed.
If Tell About Crash and Wait Across Crash are both set to Y, an intermediate return code of
220 is returned when communication is lost with the Teradata Database. If the request is still
pending, the response’s final status will be returned after communication is restored. That is,
if Wait Across Crash is set to Y, the notification it supplies is the one at the end of the waiting
period, and the notification that Tell About Crash does, or does not, supply is an additional
one during the waiting period.
The Fetch, Rewind, End Request, and Abort functions read and use the value of Tell About
Crash, but do not store it.
Stored Procedure Return Result
Usage Notes
The application sends the statements composing a procedure to the Database, where they are
compiled and saved for subsequent execution. The application that defines the procedure
must send an SQL statement to create (CREATE PROCEDURE) or replace (REPLACE
PROCEDURE) the procedure.
If the Database does not support External Stored Procedures the SQL will be rejected (there is
no capability provided to ensure that the SQL is supported).
If it is supported, an ElicitFile response parcel will be returned, whereupon the application
uses the CLIv2 ContinueRequest function to send the procedure's statements to the Database.
When all statements have been sent, the procedure is compiled and saved on the Database.
The character set used for compilation is the character set used when the procedure is created
or replaced.
Using the Procedure
To invoke a previously compiled and saved procedure, an SQL CALL statement is sent to the
Database. When called, the procedure that was defined with the SQL READS SQL DATA or
WRITES SQL DATA clause may itself invoke CLIv2 to establish a connection and send SQL
requests. Such a connection may either be a new connection (a DBCAREA Use-default-conn
value of 'N'), for which a standard Database logon string would be supplied, or the connection
could use the same session used to CALL the procedure (a DBCAREA Use-default-conn value
of 'Y').
150
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
The latter is known as the default connection, and has some limitations. Specifically, the
character set used when the procedure is executed is the character set established when the
procedure is created or replaced, not the character set being used when the CALL is sent. No
capability is provided for the procedure to ascertain this character set.
Also, the following options established by the application cannot be changed:
•
Date-form
•
Language-conformance
•
Statement-status
•
Transaction-semantics
•
2PC
No capability is provided for the procedure to ascertain the application's setting for these
options. Also, the default connection may not be disconnected.
The procedure may use the DBCAREA Return-result-to option to provide CLIv2 the same
information that would be provided by the WITH RETURN clause on the SQL PROCEDURE
statement for an SQL Stored Procedure. Specifically, whether the results for an SQL request
are returned to the requester, the caller of the procedure, or the application. If propagated to
the caller or application, the parcels are preceded by a ResultSet response parcel.
Language
Variable Name
COBOL:
SP-RETURN-RESULT
C:
SP_return_result
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
read(RSUP;IRQ)
Used by
Action Taken
application program
writes
Possible value can be set in this DBCAREA field is 0 through 5.
Tell About Delay
Tell About Delay is functionally identical to Tell About Crash.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
151
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
APRC and Tell About Delay
With AP Reset Containment (APRC), the change in nomenclature (from Crash to Delay) is a
more accurate designation of this variable. To prevent the need for users having to make
changes to their applications, the actual field name in the structure/record definition supplied
remains Tell About Crash.
Time1
Usage Notes
The Time1 field records the time when the request is sent from CLI to Teradata Database.
Language
Variable Name
COBOL
DBCAREA-TDPWAIT-TIME
C:dbcarea.h
tdpwait_time
Routine
Action Taken
DBCHINI
writes
DBCHCL
writes:
• CON
• RSUP
• IRQ
Used by
Action Taken
application program
reads
Time1 field is four bytes long and contains an unsigned binary timestamp. The precision for
Time1 is specified by the Timing-precision option. The validity of the Time1 field is indicated
by the Time1-status field.
Time5
Usage Notes
The Time5 field records the time when the first response is received in the CLI buffer.
152
Language
Variable Name
COBOL
DBCAREA-SRBSCHED-TIME
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
C:dbcarea.h
srbsched_time
Routine
Action Taken
DBCHINI
writes
DBCHCL
writes:
FET
Used by
Action Taken
application program
reads
The Time5 field is four bytes long and contains an unsigned binary timestamp. The difference
between Time5 and Time1 gives the time taken in request processing. The precision for
Time5, is specified by the Timing-precision option. The validity of the Time5 field is indicated
by the Time5-status field.
Timing Precision
Usage Notes
The Timing precision field is a signed two-byte value that specifies the precision of Time1
through Time5.
Language
Variable Name
COBOL
DBCITSP
C:dbcarea.h
dbciTSP
(case is significant)
Routine
Action Taken
DBCHINI
writes
DBCHCL
reads: (CON; RSUP; IRQ)
Used by
Action Taken
application program
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
153
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Timing precision specifies the power of two by which a timestamp in microseconds is raised.
The default is 20, in which case the Time values are in units of 2**20, or seconds. The
minimum value is 0 (microsecond) on all UNIX platforms and 10 (milliseconds) on all
Windows platforms. The maximum value is 20.
Time1 Status
Usage Notes
The Time1 status field is a single-byte ASCII character that indicates the status of Time1.
Time1 status exists only in extended DBCAREAs (that is, if the application provided an area
large enough so that Level is at least 1). The application should initialize Time1 status to a
space (0x20) before initiating a new request.
Language
Variable Name
COBOL
DBCOTSS1
C:dbcarea.h
dbcoTSS1
(case is significant)
Routine
Action Taken
DBCHINI
writes
DBCHCL
writes
Used by
Action Taken
application program
reads
writes
(before initiating a new request)
154
If Time5-status is a...
Then...
V
the timestamp is valid.
O
the timestamp overflowed. Could not be contained
in four-bytes.
Space
or
binary zero
the timestamp is not valid.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Time5 Status
Usage Notes
The Time5 status field is a single-byte ASCII character that indicates the status of Time5.
Time5 status exists only in extended DBCAREAs (that is, if the application provided an area
large enough so that Level is at least 1). The application should initialize Time5 status to a
space (0x20) before initiating a new request.
Language
Variable Name
COBOL
DBCOTSS5
C:dbcarea.h
dbcoTSS5
(case is significant)
Routine
Action Taken
DBCHINI
writes
DBCHCL
writes
Used by
Action Taken
application program
reads
writes
(before initiating a new request)
If Time5-status is a...
Then...
V
the timestamp is valid.
O
the timestamp overflowed. Could not be contained
in four-bytes.
Space
or
binary zero
the timestamp is not valid.
Token
Usage Notes
The Token field is used to specify a user-defined identifier for the request.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
155
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBCAREA-TOKEN
C: DBCAREA.H:
token
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP; IRQ)
DBCHWAT:
uses
Used by
Action Taken
application program
writes
Token is maintained for each request and is returned by DBCHWAT when a pending request
has completed its transfer.
At the application programmer’s discretion, it may be used in whatever way is useful. It is
primarily used by application programs running concurrent requests or sessions. It is most
often used to index into or point to some application-program-maintained request context, so
that an actual request id and session id can be retrieved for later calls to fetch, rewind, abort,
or end request.
Total Length
Usage Notes
The Total Length field specifies the length of the DBCAREA in bytes.
156
Language
Variable Name
COBOL:
DBCAREA-TOTAL-LEN
C: DBCAREA.H:
total_len
Routine
Action Taken
DBCHINI:
reads
DBCHCL:
reads
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
writes
Total Length must be initialized by the application program before calling DBCHINI. The
current length of the DBCAREA is 640 bytes, but it is preferable to use a symbolic value rather
than a constant.
Transaction Semantics
Usage Notes
The Transaction Semantics field specifies the semantics to be used for requests within a
transaction.
The option is rejected unless you also specify Connect Type C.
Language
Variable Name
COBOL
DBCAREA-SEMANTICS
C: DBCAREA.H:
tx_semantics
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
DBCHCL initializes Transaction Semantics to the default value provided for it in the site’s
SPB.
When the value for Transaction Semantics is not appropriate for the application, perform the
following procedure before calling DBCHCL for the Connect function.
1
Set Change Options to Y.
2
Change the value for Transaction Semantics as follows:
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
157
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
IF the transaction semantics to be used for the
application is...
THEN change the value for Transaction
Semantics to...
your server’s default.
D
This value is always acceptable.
ANSI
A
This value is rejected if the Teradata Database does
not support the selection of transaction semantics.
Teradata
T
This value is always acceptable.
Transforms-off
Usage Notes
Transforms-off is a one byte ASCII field that indicates whether SQL Structured User Defined
Types (UDTs) are transformed into their external data type or left as their constituent
attributes.
Language
Variable Name
COBOL:
TRANSFORMSOFF
C: DBCAREA.H:
transformsOff
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (RSUP: IRQ)
Used by
Action Taken
application program
writes
Possible value that can be set in this DBCAREA field is 'Y' and 'N'.
158
•
'N' - the value of 'N' indicates that the flag is off and Structured UDTs are transformed into
their external type.
•
'Y' - the value of 'Y' indicates that the flag is on and Structured UDTs are to be returned
from the server in the un-translated mode.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Trusted-request
Usage Notes
Trusted-request is a one byte ASCII field that indicates whether the request is trusted to use
the Teradata SQL SET QUERY_BAND='PROXYUSER=...' statement to change the session
userid. So unless the application accepts SQL requests from an outside source, this option has
no use.
Language
Variable Name
COBOL:
TRUSTEDREQUEST
C: DBCAREA.H:
trustedRequest
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (RSUP: IRQ)
Used by
Action Taken
application program
writes
Possible value that can be set in this DBCAREA field is 'Y' and 'N'.
•
'N' - the value of 'N' indicates that this is not a trusted request. If the trusted user possesses
the trust-only attribute, this setting will prevent "SET QUERY_BAND PROXYUSER..."
from being affected.
•
'Y' - the value of 'Y' indicates that this is a trusted request. If the trusted user possesses the
trust-only attribute, this setting will allow "SET QUERY_BAND PROXYUSER..." to be
affected.
Two Response Buffers
Usage Notes
The Two Response Buffers field specifies whether or not double-buffering is to be used for the
response.
Language
Variable Name
COBOL:
DBCAREA-TWO-RESP-BUFS
C: DBCAREA.H:
two_resp_bufs
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
159
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Two Response Buffers is initialized by DBCHINI to the default value provided for Two
Response Buffers in the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request function, the application program may set:
•
Change Options to Y, and
•
Two Response Buffers to:
•
Y, if the response is to be double-buffered.
•
N, if a single buffer is to be used for the response.
Double buffering is useful when large responses are expected from the Teradata Database and
large response buffers are used. Substantial improvements in response time can result by
transferring the next buffer-full of response data from the Teradata Database while the
previous buffer-full is being accessed by the application program.
The response buffer or buffers are re-stocked automatically by DBCHCL. The application
program may have to wait for data to arrive if the application program is consuming the data
faster than the Teradata Database can re-stock the buffer, but it does not have to arrange for
data to arrive.
Note: The connect request’s response is not double-buffered, even if Two Response Buffers is
set to Y when DBCHCL is called for the Connect function. However, any other request’s
responses on that session are double buffered, unless the setting of Two Response Buffers is
changed before the request is submitted.
Although the value of Two Response Buffers is read and stored by the Connect function, it is
not used for the connect operation itself.
Two Response buffers will be ignored if the fetch request is for LOB or cursor repositioning
responses.
Use Presence Bits
Usage Notes
The Use Presence Bits field specifies the mode in which data is to be packaged by the client for
sending to the Teradata Database.
160
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBCAREA-USE-PRESENCE-BITS
C: DBCAREA.H:
use_presence_bits
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Use Presence Bits is initialized by DBCHINI to the default value provided for Use Presence
Bits in the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request function, the application program may set:
•
Change Options to Y, and
•
Use Presence Bits to:
•
Y, if the data string has been prepared in Indicator (IndicData) Mode.
•
N, if the data string has been prepared in Record Mode.
To send null data to the Teradata Database, set Use Presence Bits to Y and provide a data string
as described for the IndicData parcel.
Note: Because DBCHCL does not parse the request string, it is the application program’s
responsibility to check whether the request string contains a USING clause and to set Use
Presence Bits, Using Data Pointer, and Using Data Length appropriately.
Note: Although Use Presence Bits is read during the call to DBCHCL for Connect and Run
Startup functions and stored in the appropriate session and request control blocks, it is not
used by the function. Neither function sends an input data string to the Teradata Database.
using-data-count
Usage Notes
using-data-count is a four byte field that indicates that using-data-ptr-array addresses a list of
pointers to areas containing data that is referred to by the USING clause in the
request string. The number of pointers in the list is the value of using-data-count.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
161
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Similarly, if Variable-length-request is not specified, using-data-length-vector either contains
the length of the using-data or addresses a list of four byte values containing the length of each
area of using-data. If Variable-length-request is specified, using-data-length-vector is unused.
using-data-pointer (along with the associated length) is functionally equivalent to
using-data-count of one (along with the associated data and lengths).
A using-data-count of one (along with the associated data and lengths) is functionally
equivalent to the existing using-data-pointer (along with the associated length). A
using-data-count greater than one will be rejected if the server does not support Array
Operations. The DBCHQE Array-operations may be used to ascertain whether the server
supports this feature.
Language
Variable Name
COBOL:
DBCAREA-USING-DATA-COUNT
C: DBCAREA.H:
using-data-count
Routine
Action Taken
DBCHINI
writes
DBCHCL
reads (RSUP; IWPF; IRQ)
Used by
Action Taken
application program
writes
Using Data Length
Usage Notes
The Using Data Length field has three meanings relating to:
162
•
Contents of the request string
•
Contents of the data string
•
Length in bytes of the data string
Language
Variable Name
COBOL:
DBCAREA-USING-DATA-LEN
C: DBCAREA.H:
using_data_len
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
•
•
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (IRQ)
Used by
Action Taken
application program
writes
If Using Data Length is zero:
•
No USING clause is to be in the request string.
•
No data string is to accompany the request (thus neither Using Data Pointer nor Use
Presence Bits contain meaningful information).
•
The length of the non-existent data string is zero.
If Using Data Length is non-zero:
•
A USING clause begins the request string.
•
A data string accompanies the request (thus Using Data Pointer and Use Presence Bits
contain meaningful information).
•
The length of the data string (including the bytes containing presence bits, if any) in
bytes is provided as the value of Using Data Length.
Before calling DBCHCL for the Initiate Request function and if the request contains a USING
modifier, the Teradata Database application program must build a data string. The data string
must contain the data described by the USING modifier.
The data string is placed in Using Data Length.
Because DBCHCL does not parse the request string, it is the application program’s
responsibility to check whether the request string contains a USING clause and to set Using
Data Length appropriately.
Using Data Length Array
Usage Notes
The Using Data Length array field points to an array of using_data_len elements.
using_data_len_array is similar to using_data_len except that instead of containing a single
length, it points to an array of lengths. Each length is associated with the corresponding
element referenced by using_data_ptr_array. If var_len_req is set to 'Y', using_data_ptr_array
must be zero; in this case, CLIv2 will extract the length from the first two bytes of each
using_data_ptr_array element (and the length of each element is necessarily limited to 64K 1).
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
163
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Language
Variable Name
COBOL:
DBCAREA-USING-DATA-LEN-ARRAY
C: DBCAREA.H:
using_data_len_array
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (IRQ)
Used by
Action Taken
application program
writes
Error code 502 will be returned under the following circumstances:
1
using_data_count and using_data_ptr are both non-zero
2
using_data_count is non-zero but using_data_ptr_array is zero
3
using_data_ptr_array is non-zero and using_data_len_array is zero but var_len_req is set
to 'N'
Error Code 502
CLI502 BADARRAYOPS: Invalid parameter combination for array- operations.
Using Data Pointer
Usage Notes
The Using Data Pointer field specifies the address of the data string that is referred to by the
USING clause in the request string. DBCHCL does not parse the request string. It is the
application program’s responsibility to be certain that a data string exists and that it is pointed
to by Using Data Pointer if a USING clause is in the request string.
164
Language
Variable Name
COBOL:
DBCAREA-USING-DATA-PRT
C: DBCAREA.H:
using_data_ptr
Routine
Action Taken
DBCHINI:
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHCL:
reads (IRQ)
Used by
Action Taken
application program
writes
Before calling DBCHCL for the Initiate Request function and if the request string contains a
USING clause, the Teradata Database application program must build a data string that
contains the data described by the USING clause.
•
If the data cannot contain null values, the application program sets Use Presence Bits to N
in the DBCAREA.
•
If the data can contain null values, the application program inserts bytes containing
indicator bits (one per column) at the front of the data string and sets Use Presence Bits to
Y. See “Use Presence Bits” on page 160.
The application program must place the address of the first byte of presence bits or the first
byte of the data string, if there are no presence bits, in Using Data Pointer.
If there is no USING clause in the request string, be certain that Using Data Length is set to
zero; otherwise, whatever value is in Using Data Pointer is used as if it were a real address and
may cause unpredictable errors.
Using Data Pointer Array
Usage Notes
The Using Data Pointer Array field points to an array of using_data_ptr elements.
using_data_ptr_array is similar to using_data_ptr except that instead of pointing to an
individual data item to be bound with the USING clause in the associated SQL request, it
points to an array of data items. When the Teradata Database receives the request it will iterate
the statement represented by the SQL request by the number of times specified in
using_data_count. Using this technique, an application that previously had to submit, 200
requests with the same SQL but different data items can accomplish the same thing with one
request and 200 data items; this reduces network traffic considerably.
Language
Variable Name
COBOL:
DBCAREA-USING-DATA-PRT-ARRAY
C: DBCAREA.H:
using_data_ptr_array
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
165
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (IRQ)
Used by
Action Taken
application program
writes
Error code 502 will be returned under the following circumstances:
1
using_data_count and using_data_ptr are both non-zero
2
using_data_count is non-zero but using_data_ptr_array is zero
3
using_data_ptr_array is non-zero and using_data_len_array is zero but var_len_req is set
to 'N'
Error Code 502
CLI502 BADARRAYOPS: Invalid parameter combination for array- operations.
Utility Workload
Usage Notes
Utility-workload is a one byte ASCII field that is used only by Teradata utilities to indicate
whether the proprietary CHECK WORKLOAD statement will be used. When Utilityworkload 'Y' is specified, Connect-type 'C' must also be specified.
166
Language
Variable Name
COBOL:
UTILITYWORKLOAD
C:
utilityWorkload
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Possible values which can be set in this DBCAREA field are: 'Y' and 'N'.
•
'N' - the value of 'N' indicates that the proprietary CHECK WORKLOAD statement will
not be used.
•
'Y' - the value of 'Y' indicates that the proprietary CHECK WORKLOAD statement will be
used.
Variable Length Fetch
Usage Notes
The Variable Length Fetch field specifies the location of the length information for the data
made available from the response.
Language
Variable Name
COBOL:
DBCAREA-VAR-LEN-FETCH
C: DBCAREA.H:
var_len_fetch
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Variable Length Fetch is initialized by DBCHINI to the default value provided for Variable
Length Fetch in the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request function, the application program may set:
•
Change Options to Y, and
•
Variable Length Fetch to:
•
Y, if the length information is to immediately precede the string to which it applies.
•
N, if the length information is to be supplied separately from the string to which it
applies.
For a parcel of data made available by DBCHCL from the response, DBCHCL supplies to the
application program both the length and the address of the data.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
167
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
If Variable Length Fetch is set to N the address in Fetch Data Pointer points to the beginning of
the parcel body and the length of the parcel body is supplied separately in Fetch Returned
Data Length.
If Variable Length Fetch is set to Y, the address in Fetch Data Pointer points to a two-byte
length (in binary) field which precedes the parcel body, and the length of the parcel body is
not supplied in Fetch Returned Data Length.
Only set Variable Length Fetch to Y if Parcel Mode Fetch is set to Y.
Do not set both Variable Length Fetch and Locate Mode to Y.
Variable Length Request
Usage Notes
The Variable Length Request field specifies the location of the length information for the
request.
Language
Variable Name
COBOL:
DBCAREA-VAR-LEN-REQ
C: DBCAREA.H:
var_len_req
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ)
Used by
Action Taken
application program
writes
Variable Length Request is initialized by DBCHINI to the default value provided for Variable
Length Request in the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL for the
Connect, Run Startup, or Initiate Request function, the application program may set:
168
•
Change Options to Y, and
•
Variable Length Request to:
•
Y, if the length information is to immediately precede the string to which it applies.
•
N, if the length information is to be supplied separately from the string to which it
applies.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
For example, to do a request, the application program must supply to DBCHCL both the
length and the address of the request.
•
If Variable Length Request is set to N, the address supplied in Request Pointer points to the
beginning of the text of the request, and the length of the request text is supplied in a
separate field of the DBCAREA, Request Length.
•
If Variable Length Request is set to Y, the address supplied in Request Pointer points to a
two-byte length (in binary) field which precedes the text of the request, and the length of
the request text is not supplied in Request Length. The length provided preceding the text
measures only the length of the request text, and does not include the two bytes of its own
length.
The Variable Length Request setting affects only the request string. The logon string, run
string, and input data string always have the length supplied separately from the string.
Note: The fragments of the string must be in the following order, if applicable:
two-byte length information
followed by n-byte indicator information
followed by bytes containing the
text or value information
In situations in which only two fragments apply, they must be in the order shown above. In all
cases, the pointer to the string must contain the address of the first fragment that is supplied.
Wait Across Crash
Wait Across Crash is functionally identical to Wait Across Delay.
Usage Notes
The Wait Across Crash field specifies how CLI should handle a request that it is unable to
initialize or complete because the database computer has crashed and is being restarted.
If a restart occurs during a logoff request, CLI automatically resubmits the request.
Language
Variable Name
COBOL:
DBCAREA-WAIT-ACROSS-CRASH
C: DBCAREA.H:
wait_across_crash
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ; FET; REW; ERQ; ABT)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
169
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
Used by
Action Taken
application program
writes
Wait Across Crash is initialized by DBCHINI to the default value in the site’s SPB.
If the value provided is not appropriate for the application, before calling DBCHCL, the
application program may set:
•
Change Options to Y, and
•
Wait Across Crash to:
•
Y, if CLI is to return control to the application program after the Teradata Database
restart completes.
•
N, if CLI is to return control to the application program as soon as the database
computer crash/restart is detected.
The Fetch, Rewind, End Request, and Abort functions read and use the value of Wait Across
Crash, but do not store it.
Used with Tell About Crash
The combination of Wait Across Crash set to N and Tell About Crash set to N is not allowed.
If Wait Across Crash and Tell About Crash are both set to Y, an intermediate return code of
220 is returned when communication is lost with the Teradata server. If the request is still
pending, the response’s final status will be returned after communication is restored.
Wait Across Delay
Wait Across Delay is functionally identical to Wait Across Crash.
APRC and Wait Across Delay
With AP Reset Containment (APRC), the change in nomenclature (from Crash to Delay) is a
more accurate designation of this variable. To prevent the need for users having to make
changes to their applications, the actual field name in the structure/record definition supplied
remains as Wait Across Crash.
Wait For Response
Usage Notes
The Wait For Response field specifies whether or not DBCHCL is to retain control or return
control to the application program in two situations:
170
1
When the application program has called DBCHCL for some function and DBCHCL
cannot send a request to the Teradata Database to carry out that function because another
request in the same session is active. DBCHCL is unable to initiate that function.
2
When the application program has called DBCHCL for the Fetch function and DBCHCL
cannot provide access to a parcel or buffer, depending on the setting of Parcel Mode Fetch,
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
because the re-stocking of the buffer is in progress. DBCHCL is unable to complete the
Fetch function.
Language
Variable Name
COBOL:
DBCAREA-WAIT-FOR-RESP
C: DBCAREA.H:
wait_for_resp
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON; RSUP: IRQ; FET; REW; ERQ; ABT)
Used by
Action Taken
application program
writes
Wait For Response is initialized by DBCHINI to the default value.
If the value provided is not appropriate for the application, before calling DBCHCL, the
application program may set:
•
Change Options to Y, and
•
Wait For Response to:
•
Y, if DBCHCL is not to return control until it is able to initiate or complete.
•
N, if DBCHCL is to return control as soon as the function’s request has been sent to the
Teradata Database, in which case the application program must use some other
method to detect when the function’s response arrives.
If Wait For Response is set to N and one of the two situations described above occurs, the
following return codes are given:
EM_NOTIDLE (208) or EM_NODATA (211),
The application program may try again.
•
The first way to decide when it is reasonable to try again is to call DBCHWAT. When
control is returned from DBCHWAT, try again. This method ties up less system resources
while waiting.
Several tries may be necessary. Occasionally CLI may finish one operation it is doing and
go on to another immediately. In that case, DBCHWAT will return control when one
operation is over, but the application program’s next call to DBCHCL “doesn’t go
through” because CLI has already started another operation. Allow for the possibility of
multiple tries.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
171
Chapter 5: DBCAREA
Individual Field Descriptions: Alphabetical Listing
•
The second way to decide when it is reasonable to try again is to try again immediately,
and keep trying until “the call gets through.”
Note: If one above situations occurs and Wait For Response is set to “N”, the original call to
DBCHCL did not “take” at all. CLI is reporting “I was not able to do that; try again later.”
Note: Neither the Abort function nor the Disconnect function is affected by the setting of
Wait For Response.
The Fetch, Rewind, End Request, and Abort functions read and use the value of Wait For
Response, but do not store it.
By using Wait for Response during CLI logoff processing, applications can prevent CLI from
waiting “forever” if the gateway does not respond to the logoff request.
Workload Length
Usage Notes
The workload length is the length in bytes of the workload pointer. This is an unsigned
integer. The length should be less or equal to 8 bytes. If zero is set, the workload pointer will
not be referenced.
Language
Variable Name
COBOL:
WORKLOAD_LEN
C:
workload_len
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
Possible value can be set in this DBCAREA field is an unsigned integer value.
Workload Pointer
Usage Notes
The workload pointer specifies the address of the program or process name string.
If the name is shorter than eight bytes, it will be padded with trailing blanks. If the name is
longer than eight bytes, it will be truncated to eight bytes.
172
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 5: DBCAREA
DBCAREA Fields Not Used by Network-Attached Systems
Language
Variable Name
COBOL:
WORKLOAD_PTR
C:
workload_ptr
Routine
Action Taken
DBCHINI:
writes
DBCHCL:
reads (CON)
Used by
Action Taken
application program
writes
Possible value can be set in this DBCAREA field is an ASCII character string of program or
process name.
DBCAREA Fields Not Used by Network-Attached
Systems
The following fields are listed in the DBCAREA files, but are not used by network-attached
systems. They are used by channel-attached systems.
•
HSISVC Time
•
Input DBCpath
•
Open Requests
•
Route Description Codes
•
Save Response Buffer
•
Session Status
•
SRBSCHED Time
•
TDP Request Number
•
TDPDBI Time
•
TDPDBO Time
•
TDPWAIT Time
•
TDPXMM Time
For information about these fields see Teradata Call-Level Interface Version 2 Reference for
Channel-Attached Systems.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
173
Chapter 5: DBCAREA
DBCAREA Fields Not Used by Network-Attached Systems
174
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 6
DBCAREA Extensions
The DBCAREA extensions allow the application to provide information to a CLIv2 function
that is not general enough to be defined within the DBCAREA.
Two types of DBCAREA extensions are available:
•
Initiate-request Extensions
•
Initiate-request Extensions Fields
Initiate-request Extensions
Usage Notes
Initiate-request extensions (IRX) are used for initiating requests. It is of variable length, is not
initialized by DBCHINI, and is allocated by the application. The DBCAREA Extension Pointer
field points to IRX. IRX does not exist if there is a zero in the DBCAREA Extension Pointer
field.
Note: The IRQ Ext provides support for parameterized SQL, which is used by the
Preprocessor2. It also provides support for TDSP, providing MultiTSR options.
IRX Fields
The IRX extension contains two logical sections:
•
Header
•
Element
Header
Two possible header formats are available for IRX.
0
Eyecatcher (DBCX), 4 bytes
4
Next Pointer, 4 bytes
8
Total Length, 2 bytes
Unused, 2 bytes
2418A010
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
175
Chapter 6: DBCAREA Extensions
Initiate-request Extensions
The above structure is defined as "DBCAREAX" in the dbcarea.h file, provided during
installation.
0
Eyecatcher (IRX8), 4 bytes (32 bit)
Unused, 4 bytes (64 Bit)
4
Next Pointer, 4 bytes
8
Total Size, 4 bytes
12
Level, 1 byte
Unused, 3 bytes
16
Next Pointer, 8 bytes (64 bit)
Unused, 8 bytes (32 bit)
20
2418A009
The above structure is defined as "D8CAIRX" in the dbcarea.h file, provided during
installation.
Elements
Immediately following the header are one or more elements. Each element will either:
•
Contain the actual data
•
Address the actual data
When the Eyecatcher field contains 'IRX8' and the Level field contains a value of '1', there is
one element format, which either contains the data or addresses the data. New development
should use only a Level of '1'; a value of 0 is deprecated. These elements are described by the
following figure.
176
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 6: DBCAREA Extensions
Initiate-request Extensions
offset
0
Element Length, 2 bytes
Element Type, 2 bytes
4
Parcel Flavor, 2 bytes
Unused, 2 bytes
Data Size, 4 bytes
8
12
Unused, 4 bytes
16
Data Address, 4 bytes (32 bit)
Imised. 4 bytes (64 bit)
20
Data Address, 8 bytes (64 bit)
Unused, 8 bytes (32 bit)
24
28
Unused, 8 bytes (32 bit)
36
Parcel Data (no mandatory length)
2418A014
The above format is implemented using two structures 'D8XIELEM' and 'D8XIEP' in the
dbcarea.h file, provided during installation. When either the Eyecatcher field contains 'IRX8'
and the Level field contains a value of '0', or the Eyecatcher field contains 'DBCX', there are
two element formats:
•
Inline format contains data.
•
Pointer format addresses the data.
Inline Method
The element type field in the Element header indicates whether the parcel body will follow the
header or a pointer element will follow the header. For information on setting Inline and
Pointer methods, see “Element Type” on page 180.
If Eyecatcher is set to (IRX8) and Level field is set to '0' in the extension header (D8CAIRX) or
if the Eyecatcher is set into (DBCX) in Extension header (DBCAREAX), the following is
format in which the parcel is sent in Inline method.
offset
0
4
Element Type, 2 bytes
Element Length, 2 bytes
Parcel Data (No Mandatory Length)
2417A017
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
177
Chapter 6: DBCAREA Extensions
Initiate-request Extensions
If 'IRX8' with level '0' is used, then the structure defined for this purpose is'D8XILMNT'.
If 'DBCX' eyecatcher is used, then the structure defined for this purpose is 'x_element'.
Pointer Method
If Eyecatcher is set to (IRX8) and Level field is set to '0' in the extension header (D8CAIRX8),
the following is the format in which the parcel is sent in the Pointer method.
0
Element Type, 2 bytes
4
Unused, 2 bytes
Data Address, 4 bytes (32 bit)
Unused, 4 bytes (64 bit)
Data Address (continued)
Unused, 4 bytes
12
Unused (continued)
Unused, 4 bytes
16
Unused (continued)
Unused, 4 bytes
20
Unused (continued)
Unused, 4 bytes
24
Unused (continued)
Data Size, 4 bytes
28
Data Size (continued)
Unused, 4 bytes
32
Unused (continued)
Unused, 8 bytes (32 bit)
Data Address, 8 bytes (64 bit)
36
Unused (continued) (32 bit)
Data Address (continued) (64 bit)
8
Element Length, 2 bytes
2418A012
The structure defined for this purpose is 'D8XILPTR' and is available in dbcarea.h.
If Eyecatcher is set to (DBCX) in the extension header (DBCAREAX), the following is the
format in which the parcel is sent in Pointer method.
offset
0
Element Type, 2 bytes
Element Length, 2 bytes
4
Data Length, 2 bytes
Data Address, 4 bytes
8
Data Address
(continued)
2417A018
The structure defined for this purpose is 'xp_element' and is available in dbcarea.h.
178
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 6: DBCAREA Extensions
Initiate-request Extensions Fields
Initiate-request Extensions Fields
This section describes each of the fields in Initiate-request extensions. The fields are listed in
alphabetical order.
Data Address
The data address field specifies the address of the parcel body. The symbolic name of the
member and its structure depends on the value set in the Eyecatcher and Level fields in the
extension header.
Element name: Structure defined in the dbcarea.h in which the member exists.
Extension Head
Eyecatcher
Level
Element Name
Member Name
DBCAREAX
DBCX
--
xp_element
x_pelm_addr
D8CAIRX
IRX8
0
D8XILPTR
d8xilpPt
D8CAIRX
IRX8
1
D8XIEP
d8xiepPt
Data Length
When the Eyecatcher is DBCX8, the Data Length field specifies the length of the parcel body
addressed by the Data Address field.
Extension Head
Eyecatcher
Level
Element Name
Member Name
DBCAREAX
DBCX
--
xp_element
x_pelm_len
Data Size
When Eyecatcher is 'IRX8', the Data Size field specifies the length of the parcel body addressed
by the Data Address field.
Extension Head
Eyecatcher
Level
Element Name
Member Name
D8CAIRX
IRX8
0
D8XILPTR
d8xilpLn
D8CAIRX
IRX8
1
D8XIEP
d8xiepLn
Element Length
Element Length contains the length of the individual element.
Extension Head
Eyecatcher
Level
Element Name
Member Name
DBCAREAX
DBCX
-
x_element
x_elm_length
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
179
Chapter 6: DBCAREA Extensions
Initiate-request Extensions Fields
Extension Head
Eyecatcher
Level
Element Name
Member Name
D8CAIRX
IRX8
0
D8XILMNT
d8xilLen
D8CAIRX
IRX8
1
D8XIELEM
d8xieLen
The value to which the length of the element needs to be set depends on the value to which
eyecatcher is set and the method used.
Inline Method
Extension Head
Eyecatcher
Level
Element Length
DBCAREAX
DBCX
-
sizeof(x_element)+
sizeof(parceldata)
D8CAIRX
IRX8
0
sizeof(D8XILMNT) +
sizeof(parcel data)
D8CAIRX
IRX8
1
sizeof(D8XIELEM) +
sizeof(D8XIEP) +
sizeof(parcel data)
Extension Head
Eyecatcher
Level
Element Length
DBCAREAX
DBCX
-
sizeof(x_element)
D8CAIRX
IRX8
0
sizeof(D8XILMNT) +
sizeof(D8XILPTR)
D8CAIRX
IRX8
1
sizeof(D8XIELEM) +
sizeof(D8XIEP)
Pointer Method
Element Type
When the Eyecatcher field contains 'IRX8' and the Level field contains '1', Element Type
indicates the type of method:
0 - Inline method
1 - Pointer method
When either the Eyecatcher field contains 'IRX8' and the Level field contains '0', the
Eyecatcher field contains 'DBCX'. The Element Type not only indicates whether the parcel
data is in the element (inline method) or simply addressed by the element (pointer method),
but also specifies the parcel flavor.
If the left most bit is zero, then the parcel body is contained in the element itself; if this bit is
one, then the parcel body is addressed by the element. The remainder of the field contains the
parcel flavor.
180
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 6: DBCAREA Extensions
Initiate-request Extensions Fields
The symbolic name depends upon both the Eyecatcher and Level fields:
Extension Head
Eyecatcher
Level
Element Name
Member Name
DBCAREAX
DBCX
-
x_element/
xp_element
x_elm_type
D8CAIRX
IRX8
0
D8XILMNT
d8xilTyp
D8CAIRX
IRX8
1
D8XIELEM
d8xieTyp
Any value in Element Type greater than 4095 gives a nonzero return code.
Any value in Element Type less than 4096 and not a valid parcel flavor will result in an error
being returned from the Teradata server.
If the high-order bit is off in Element Type, the element data contains a parcel body. However,
if the high-order bit is on in Element Type, the element data contains a pointer to the actual
parcel body and the length of the pointed to parcel body.
EyeCatcher
EyeCatcher field should be used by the applications to indicate to CLI which type of element
structures are used.
Extension Head
Eyecatcher
Level
Element Structures Used
DBCAREAX
DBCX
-
x_element, xp_element
D8CAIRX
IRX8
0
D8XILMNT, D8XILPTR
D8CAIRX
IRX8
1
D8XIELEM, D8XIEP
Level
When the Eyecatcher is IRX8, the Level field specifies the format of the extension. If it is set to
0, elements defined for 64-bit implementation are used. If it is set to 1, elements defined for
APH implementation are used.
Extension Head
Eyecatcher
Level
Element Structures Used
D8CAIRX
IRX8
0
D8XILMNT, D8XILPTR
D8CAIRX
IRX8
1
D8XIELEM, D8XIEP
Use of value '0' is deprecated. New implementations should use the elements defined for APH
implementation.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
181
Chapter 6: DBCAREA Extensions
Initiate-request Extensions Fields
Next Pointer
If nonzero, Next Pointer points to another DBCAIRX or DBCAREAX to form a linked list of
DBCAIRX or DBCAREAX extensions. The symbolic name depends upon the Eyecatcher field.
Extension Head
Eyecatcher
Member Name
DBCAREAX
DBCX
x_next_ptr
D8CAIRX
IRX8
d8xiNext
The sequence in which the DBCAREAX or DBCAIRX extensions are linked are the same
sequence in which the parcels contained in these extensions are built in the request buffer.
Parcel Flavor
The Parcel Flavor field specifies the flavor of the parcel. This should be used only when
Eyecatcher is set to 'IRX8' and Level field is set to '1'.
Extension Head
Eyecatcher
Level
Element Name
D8CAIRX
Len
IRX8
1
D8XIEP
Member Name
d8xiepF
Total Length
If DBCX was specified in Eyecatcher, Total Length specifies the length of one DBCAREAX
extension in bytes. This includes the size of extension header, size of each element used in the
extension, and size of parcel data (if inline method is used).
Extension Head
Eyecatcher
Member Name
DBCAREAX
DBCX
x_total_length
Total Size
Total size conveys the same information as Total Length. This field should be used if
Eyecatcher is set to 'IRX8'.
182
Extension Head
Eyecatcher
Member Name
D8CAIRX
IRX8
d8xiSize
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 6: DBCAREA Extensions
Initiate-request Extensions Fields
Connect extension (DBCACNX)
Usage Notes
The DBCACNX extension applies only to the Connect function and only when the Connecttype option specifies a combined logon and connect. Use of the Connection-extension will be
rejected if the Connect-type option specifies a separate logon and run. When used, it should
be pointed to by the Extension Pointer DBCAREA field before invoking Connect. The
Extension Pointer should be zeroed after the Connect function to prevent subsequent
functions from attempting to use it.
Note: The DBCACNX can be used only to provide information required by CLI for third
party Logon (SSO). Third party logon is supported only on Windows.
DBCACNX Fields
The DBCACNX consists of two logical sections:
•
Header
•
Element
One header always exists and is followed by one or more elements. If data is associated with an
element, it may either be included with the element or pointed to by the element. More than
one extension may be chained together.
Header
Level should be set to 2.
0
Eyecatcher (CNX), 4 bytes
4
Next Pointer, 4 bytes (32 bit)
Unused, 4 bytes (64 bit)
8
Total Size, 4 bytes
12
16
Level, 1 byte
Unused, 3 bytes
Next Pointer, 8 bytes (64 bit)
Unused, 8 bytes (32 bit)
20
2418A008
A structure DBCACNX is defined in the dbcacnx.h file with the above format.
DBCACNX Element Fields when Level is set to 2.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
183
Chapter 6: DBCAREA Extensions
Initiate-request Extensions Fields
0
4
8
12
16
20
Element Type, 2 bytes
Element Length, 2 bytes
Unused, 2 bytes
Data Type, 2 bytes
Data Length, 4 bytes
Data Pointer, 4 bytes (32 bit)
Unused, 4 bytes (64 bit)
Unused, 4 bytes
Data Pointer, 8 bytes (64 bit)
Unused, 8 bytes (32 bit)
24
16 or 28
Data (no fixed length)
2418A013
Structures 'D8XCELEM' and ‘D8XCED’ are defined in the dbcacnx.h file with the above
format.
The sections that follow describe each of the fields, in alphabetical order.
Data-length
Data-length is a four-byte unsigned integer field into which the length of the data is placed. If
no data is associated with this type, the field is zero.
Structure
Member Name
D8XCED
d8xcedLn
Data Pointer
Data-pointer is a four-byte field into which the pointer to the data is placed. If either there is
no data associated with this type or the data is included in the element, the field is zero or null.
Structure
Member Name
D8XCED
d8xcedPt
Data-type
Data-type is a two-byte unsigned integer field into which the type of data is placed.
184
Structure
Member Name
D8XCED
d8xcedTy
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 6: DBCAREA Extensions
Initiate-request Extensions Fields
The following types are supported:
•
1, for Client Userid (mnemonic DBXCEDTU)
•
2, for Client Password (mnemonic DBXCEDTP)
•
3, for Client Domain (mnemonic DBXCEDTD)
Element-length
Element-length is a two-byte unsigned integer field into which the length of the element is
placed.
Structure
Member Name
D8XCELEM
d8xceLen
Element-type
Element-type is a two-byte unsigned integer field into which the type of element is placed.
Currently, there is only one type of element, a data element with a type of 0.
Structure
Member Name
D8XCELEM
d8xceTyp
Eyecatcher
Eyecatcher is a four-byte field into which the ASCII characters 'CNX ' must be placed.
Structure
Member Name
D8CACNX
d8xcId
Length
Length is a four-byte unsigned integer field into which the total length of the extension is
placed. The length includes the header fields, the fields of all elements, and any in-line data for
the elements.
Structure
Member Name
D8CACNX
d8xcLen
Level
The Level field specifies the format of the extension.
The current level is 2. New development should use only the level 2 form. The level 1 form is
deprecated.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
185
Chapter 6: DBCAREA Extensions
Initiate-request Extensions Fields
Structure
Member Name
D8CACNX
d8xcLvl
Next-pointer
Next-pointer is a four-byte (32-bit) or an eight-byte (64-bit) field into which the pointer to
the next Connect-extension is placed. If another Connect-extension does not exist, the field is
zero or null.
186
Structure
Member Name
D8CACNX
d8xcNext
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 7
Common Routines
This chapter describes common CLI routines: DBCHINI, DBCHCL, and DBCNCLN. The
following subfunctions of DBCHCL are also covered:
DBCHINI
DBCHCL Functions
DBFCON
DBFCRQ
DBFRSUP
DBFIRQ
DBFABT
DBFFET
DBFREW
DBFERQ
DBFDSC
DBCHCLN
The other CLI routines are described in Chapter 8: “Other CLI Routines.”
Introduction
CLI routines are used by application programs when:
•
No preprocessor exists for the application language.
•
Facilities not supported by the preprocessors are required.
•
Standard OS linkage conventions are required by the CLI routines.
•
The application has severe performance or memory constraints.
CLI routines reside in the CLIv2 library.
Use
Table 8 on page 188 lists the common routines and describes how they are used.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
187
Chapter 7: Common Routines
Parameters
Table 8: Uses of Routines and Functions
Routine
Description
DBCHINI
What:
Initializes the application program allocated by DBCAREA and
allocates and initializes internal CLI memory areas.
Why:
To prepare for interaction with the Teradata Database
Where:
All clients
What:
Manages interaction with the Teradata Database. Each type of
interaction is called a function.
Why
To send Teradata SQL requests to, and receive Teradata SQL from,
the Teradata Database
Where
All clients
Function
Use
DBFCON
Logs a session on to the Teradata Database and specifies a set of
services.
DBFCRQ
Sends LOB data in deferred mode
DBFRSUP
Submits a request to execute the Startup Request stored in the
Teradata Database
DBFIRQ
Submits a Teradata SQL request from the application
DBFABT
Aborts a request asynchronously
DBFFET
Makes available the next parcel or buffer (which one depends on the
setting of Parcel Mode) of the Teradata SQL response
DBFREW
Repositions to start of Teradata SQL response (spool file)
DBFERQ
Closes a Teradata SQL request and has the Teradata Database discard
the response
DBFDSC
Logs off and deletes a session from the Teradata Database
What:
Releases the internal CLI memory areas that were allocated by
DBCHINI
Why:
To clean up after interacting with the database computer
Where:
All clients
DBCHCL
DBCHCLN
Parameters
Table 9 lists the parameters for the common CLI routines described in this chapter.
188
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
Parameters
Table 9: Parameters for CLI Routines
Routines
Parameters
DBCHINI
ReturnCode
ContextArea
DBCAREA
DBCHCL
ReturnCode
ContextArea
DBCAREA
DBCHCLN
ReturnCode
ContextArea
DBCHINI
DBCHINI sets up the CLI environment. Applications must allocate the DBCAREA and then
call DBCHINI to initialize it.
How It Works
Applications must first allocate storage for a DBCAREA and then call DBCHINI for the
following processing:
•
Initializing the Application Control Block (ACB)
•
Initializing the DBCAREA
•
Resetting the DBCAREA length field
•
Setting all options to either their default (in CLI2SPB) or application specified values (in
clispb.dat)
•
Initializing MTDP for the application
Note: DBCHINI does not initialize the DBCAREAX.
Parameters
The DBCHINI parameters are:
Int32
DBCHINI (ReturnCode, ContextArea, DBCAREA)
Int32
*ReturnCode;
char
*ContextArea;
struct
DBCAREA
where:
For the Return Code Address
Length:
4 bytes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
189
Chapter 7: Common Routines
Parameters
Input:
address of a four-byte integer return code variable
Output:
unchanged
After control returns from DBCHINI, the integer contains a code whose value represents
success or failure to initialize. Return code zero indicates the DBCAREA is initialized. A nonzero return code indicates failure, and the value specifies the reason for the failure.
For the Context Area Address
Length:
4 bytes
Input:
0
Output:
address of the internal CLI context area
Context Area is provided to maintain compatibility with calls on channel-attached systems.
For the DBCAREA Address
Length:
4 bytes
Input:
address of the DBCAREA structure
Output:
unchanged
Applications and CLI share the DBCAREA and use it for input of values to CLI and output of
values from CLI.
Usage Notes
Application must declare or allocate the DBCAREA and call DBCHINI to initialize the fields
prior to using CLI functions. Total Length must be filled in by the application before calling
DBCHINI.
DBCHINI obtains default values from the SPB currently available to the application.
Applications are able to use the same DBCAREA for all requests. If this is the case, one call to
DBCHINI is sufficient regardless of the number of sessions, requests, and so on, used by the
application program. If the DBCAREA is used this way, Input Session Id, Input Request Id,
and Token, if used, must be checked before each call, to ensure that they are appropriate for
that call.
But the application can allocate and then initialize a new DBCAREA for each session and even
for each request within each session. This is done by another call to DBCHINI with the new
location. Using multiple DBCAREAs requires additional space for the extra DBCAREAs and
additional time to allocate and initialize the extra DBCAREAs. However, this may result in
saving some CPU time after the application program is in progress.
In addition to initializing the DBCAREA, DBCHINI also allocates and initializes some
internal data structures.
190
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
Parameters
DBCHCL
DBCHCL calls the functions requested by the application program.
For an overview of the functions relative to DBCHCL (see Table 8 on page 188). Each function
is described in detail later in the sections that follow.
How It Works
Before each call to DBCHCL, the application program modifies the DBCAREA to specify the
action requested and to fill in the input fields relevant to that action.
DBCHCL carries out the function specified by the function code in the DBCAREA and then
passes back to the caller the DBCAREA, which contains, among other things, a return code.
The application program checks the return code in the DBCAREA, which is where CLI and
MTDP indicate any problem they find. If the call resulted in a delivery of parcels to the
response buffer, the program checks the first parcel, which is the Error and Failure parcel.
Parameters
The DBCHCL parameters are:
Int32
DBCHCL (ReturnCode, ContextArea, DBCAREA)
Int32
*ReturnCode;
char
*ContextArea;
struct
dbcarea_struct *dbcarea;
where:
The parameter . .buffer-full
Is the...
ReturnCode
four-byte address of an area allocated by the application program for
storage of a four-byte signed integer.
After control returns from DBCHCL, the integer contains a code
whose value represents success or failure of the function as seen by CLI
and MTDP.
A return code of zero indicates success. A non-zero return code
indicates failure, and the value specifies the reason.
Note: The return code covers only the work done on the client, it does
not cover any work that may have been done on the Teradata Database.
ContextArea
four-byte field that may contain any value because it is not used by CLI
or the application program.
It is provided to maintain compatibility with calls on channel-attached
systems.
DBCAREA
four-byte address of the area allocated by the application program for
use as DBCAREA.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
191
Chapter 7: Common Routines
Parameters
The parameter . .buffer-full
Is the...
The application program and CLI share the DBCAREA and use it for
input of values to CLI and output of values from CLI.
Usage Notes
Before DBCHCL is called:
•
The application program must call DBCHINI to initialize the DBCAREA to be used by
DBCHCL.
•
The application program must provide input in the DBCAREA whose address is provided
to DBCHCL. The function code must always be provided. The other input that must be
provided is determined by the function code chosen.
After DBCHCL returns control to the application program, the application program must
check the return code. The return code may be checked in either the parameter list, the
DBCAREA or in the DBCHCL function. All have the same value.
•
If the application program is running with Wait For Response set to Y, a return code of
busy (EM_NODATA 211) will not be encountered.
•
If the application program is running with Wait For Response set to N, a return code of
busy may be encountered.
What Busy Means
Busy means that the requested function could not be initiated or completed, because the
session was in pending state (that is, CLI was waiting for the Teradata Database to send it some
information it requested on that session). There are two ways to code for busy:
1
If the return code from DBCHCL is busy, call DBCHCL for the same function, repeat.
2
If the return code from DBCHCL is busy, call DBCHWAT, check for a DBCHWAT return
code of zero, call DBCHCL for the same function, repeat.
The second method is strongly preferred because it does not tie up the system during the wait
period.
Note: Do not code a fixed number of loops, because the number may change depending on
the circumstances.
DBCHCL Functions
Function Abbreviations
Table 10: Function Abbreviations
192
Abbreviations
Function
DBFCON
call to DBCHCL for the Connect function
DBFRSUP
call to DBCHCL for the Run Startup function
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
Parameters
Table 10: Function Abbreviations (continued)
Abbreviations
Function
DBFIRQ
call to DBCHCL for the Initiate Request function
DBFCRQ
call to DBCHCL for sending LOB data in deferred Mode
DBFFET
call to DBCHCL for the Fetch function
DBFREW
call to DBCHCL for the Rewind function
DBFERQ
call to DBCHCL for the End Request function
DBFABT
call to DBCHCL for the Abort function
DBFDSC
call to DBCHCL for the Disconnect function
For an overview of the use of these functions, see Table 8 on page 188.
For each function, there is a list of the required and optional input arguments and output
arguments, and a general description of how DBCHCL processes the function.
The interpretation of some of the arguments can depend on the setting of the DBCAREA set
options. For instance, input/output string pointers can be variable strings. For output strings,
DBCHCL will provide an address and length if Locate Mode is in effect; otherwise DBCHCL
expects that the application has set the address of the area to which DBCHCL is to move the
string. If DBCHCL detects an error while processing, various fields will be set to help the user
interpret and handle the error.
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 via 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.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
193
Chapter 7: Common Routines
Parameters
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:
194
Function:
DBFCON - Connect
Purpose:
Logon and Run. (Analogous to SQL ‘CONNECT‘)
Parms:
struct DBCAREA *dbcptr pointer to a DBCAREA
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
Parameters
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
•
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
•
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
•
Tell About Crash
•
Token
•
Transaction Semantics
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
195
Chapter 7: Common Routines
Parameters
•
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
196
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
Parameters
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 via 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 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.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
197
Chapter 7: Common Routines
Parameters
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 via 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.
DBFCRQ
DBFCRQ is the Continue LOB request function of DBCHCL.
DBFCRQ is used in conjunction with DBFIRQ, to send LOB data.
How It Works
After issuing a Multipart LOB request using DBFIRQ, the application initiates a DBFCRQ to
send Multipart LOB data to the server.
DBFCRQ performs the following functions:
•
If the session is active, awaits completion of the active request
•
Reads the continuation code given by the application in DBCAREA field
'continuation_code'
•
If other than 'F', 'I', 'L' or 'C' is used, CLI returns error
•
If 'C' is mentioned, then CLI will send abort parcel to the server
•
If Parcel request mode is used, CLI will build Multipart data parcel and End Multipart data
parcel to the server
•
The data sent to the server is supplied by the application through DBCAREA field 'req_ptr'
•
If buffer mode is used, CLI will send the request buffer build by the application to the
server
DBFRSUP
DBFRSUP is the Run Startup function of DBCHCL.
DBFRSUP sends a request to the Teradata Database to execute the Startup Request stored on
the Teradata Database.
How It Works
The startup request is a Teradata SQL request stored on the Teradata Database by means of a
CREATE USER or MODIFY USER statement that contains a STARTUP clause.
DBFRSUP performs the following functions:
•
If the session is active, awaits completion of the active request
•
If the previous request was a CON and it was not successful, receives an error indicating
“unable to initiate because session is not logged on”
Note: Upon receiving this return error, the application must invoke DBFDSC.
•
198
If the application has requested option updates, performs option set/validation logic
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
Submitting the Startup Request
•
Ensures that request buffer is large enough.
•
Builds request in request buffer, as follows:
•
Request parcel in either Record, Field, or Indicator Mode based on the setting of the
Response Mode
•
Input Data parcel in either Record or Indicator Mode based on setting of Using
Presence Bits, and
•
Resp or KeepResp parcel based on Keep Response setting
Then DBFRSUP sends a request to the MTDP:
•
If not successful, cleanups and returns to the application
•
Sets Open Request, and so on, and returns to caller
Submitting the Startup Request
The sequence of operations for submitting the startup request is:
1
Call DBCHCL for DBFRSUP
2
Check that return code is zero
A return code of zero does not imply that the Teradata SQL request was successful. It does
imply that the request has been sent to the Teradata Database, that is, the initial status is
successful. If the request is successful on the client, the Teradata Database processes it and
sends the first portion (buffer-full) of the Teradata SQL response to the client. To verify that
the request was successful, call DBCHCL for DBFFET and check that the first parcel in the
response stream is not an Error or Failure parcel.
Successful Run Startup Operation
The sequence of operations for a successful run startup operation is:
1
Call DBCHCL for DBFRSUP
2
Check that return code is zero
See “DBFFET” on page 206 for steps to take until response is “consumed” or no longer
required (if rewind is required, see “DBFREW” on page 208 and then “DBFFET” on
page 206)
3
Call DBCHCL for DBFERQ
4
Check that return code is zero
If the application program calls DBCHCL for the DBFRSUP without first calling DBCHCL
for DBFCON, DBCHCL returns with a return code “first do a connect” (NO SESSION 304).
If the call to DBCHCL for the DBFRSUP results in a non-zero return code, the run startup has
failed for the reason indicated by the value of the return code. CLI internal structures for the
non-existing request can (and should) be de-allocated by calling DBCHCL for DBFERQ. The
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
199
Chapter 7: Common Routines
Interface
Output Request Id from the DBFRSUP is the appropriate value to place in Input Request Id
for DBFERQ.
The startup request is not to contain a USING clause. Thus, the value of Use Presence Bits is
read and stored, but not used.
Interface
The DBFRSUP interface is as follows:
Function:
DBFRSUP - RunStartUp
Purpose:
Perform the DBFRSUP
Parms:
DBCAREA Parameters
The following fields in the DBCAREA may be read or written to by DBCHCL’s DBFRSUP,
depending on the application program’s environment.
Input Arguments
200
•
Change Options
•
Column Title and Format Information
•
Data Encryption
•
Dynamic Result Sets Allowed
•
Function
•
Input Session Id
•
Keep Response
•
Locate Mode
•
Maximum Parcel
•
Parcel Mode
•
Period-as-Struct
•
Request Buffer Length
•
Request Processing Option
•
Response Buffer Length
•
Response Mode
•
Return Time
•
Save Response Buffer
•
Stored Procedure Return Result
•
Tell About Crash
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
DBCAREA Parameters
•
Token
•
Transforms-off
•
Trusted-request
•
Two Response Buffers
•
Use Presence Bits
•
Variable Length Fetch
•
Variable Length Request
•
Wait Across Crash
•
Wait For Response
Output Arguments
•
Current Response Buffer Length
•
Message Length
•
Message Text
•
Output Request Id
•
Return Code
•
Return Identity Data
•
TDP Request Number
DBFIRQ
DBFIRQ is the Initiate Request function of DBCHCL; DBFIRQ sends a request to the Teradata
Database to be processed.
How It Works
DBFRIRQ performs the following functions:
•
If the session is active, awaits completion of the active request
•
If the active request was an IRQ, saves the ending status of the request internally
•
If the previous request was a CON and it was not successful, receives a return error
indicating “unable to initiate because session is not logged on”
•
Ensures that request buffer is large enough
•
Builds a request in request buffer, as follows:
•
•
The response should be in either Record, Field, Indicator or Multipart Mode, based on
the setting of the Response Mode field
•
Input data should be in either Record or Indicator Mode based on the setting of the
Use Presence Bits field, or neither based on setting of Using Data Length field
Appends a SETPOSITION position parcel and then a Resp or KeepResp parcel based on
Keep Response field setting. If keep_resp is set to 'P', then a SETPOSITION parcel is
appended with a KeepResp parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
201
Chapter 7: Common Routines
DBCAREA Parameters
•
If the session is not a Teradata SQL (that is, if the bypass flag is set to Y), disregards the
SQL buffer pointer and uses the using data buffer as is to generate the request buffer,
without any additional parcels added to the request buffer
•
Sends request to the MTDP
•
If not successful, cleanups and returns to the application
•
Sets Open Requests field, and so on, and returns to caller
Initiating a Request
The sequence of operations for initiating a request is:
1
Call DBCHCL for DBFIRQ
2
Check that return code is zero
A return code of zero does not imply that the Teradata SQL request was successful. It
implies that the Teradata SQL request has been sent in to the Teradata Database. That is,
that the initial status is successful. If the request is successful on the client, the Teradata
Database processes it and sends the first portion (buffer-full) of the Teradata SQL response
to the client.
Successful Request/Response Operation
The sequence of operations required for a successful request/response operation is:
1
Call DBCHCL for DBFIRQ
2
Check that return code is zero
Note: See “DBFFET” on page 206 for steps to take until response is “consumed” or no
longer required. If rewind is required, see “DBFREW” on page 208 and then “DBFFET” on
page 206.
3
Call DBCHCL for DBFERQ
4
Check that return code is zero
If DBCHCL is called for DBFIRQ without having first called DBCHCL for DBFCON,
DBCHCL returns with a return code, “first do a connect” (NOSESSION; 304).
It is the application program’s responsibility to provide Using Data Pointer and Using Data
Length if the Teradata SQL request contains a USING modifier. CLI does not parse the
Teradata SQL request, so it cannot coordinate the USING modifier and the using data.
Similarly, it is the application program’s responsibility to set Using Data Length to zero if the
Teradata SQL request does not contain a USING modifier.
If the call to DBCHCL for DBFIRQ results in a non-zero return code, the Initiate Request has
failed for the reason indicated by the value of the return code. CLI internal structures for the
non-existing request can (and should) be de-allocated by calling DBCHCL for the DBFERQ.
The Output Request Id from DBFIRQ is the appropriate value to place in Input Request Id for
the DBFERQ.
202
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
DBCAREA Parameters
Interface
Function:
DBFIRQ - Initiate ReQuest
Purpose:
Initiate a request
Parms:
DBCAREA Parameters
The following fields in the DBCAREA may be read or written to by DBCHCL’s DBFIRQ,
depending on the application program’s environment.
Input Arguments
•
Change Options
•
Character Set Pointer
•
Column Title and Format Information
•
Data Encryption
•
Extension Pointer
•
Keep Response
•
Input Session Id
•
Locate Mode
•
Maximum Parcel
•
Parcel Mode
•
Period-as-Struct
•
Request Buffer Length
•
Request Mode
•
Request Length
•
Request Pointer
•
Request Processing Option
•
Response Buffer Length
•
Response Mode
•
Return Identity Data
•
Return Time
•
Save Response Buffer
•
Set Character Set
•
Statement-status
•
Tell About Crash
•
Token
•
Transforms-off
•
Trusted-request
•
Two Response Buffers
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
203
Chapter 7: Common Routines
DBCAREA Parameters
•
Use Presence Bits
•
Using Data Length
•
Using Data Pointer
•
Variable Length Request
•
Variable Length Fetch
•
Wait Across Crash
•
Wait For Response
Output Arguments
•
Current Response Buffer Length
•
Current Request Buffer Length
•
Message Length
•
Message Text
•
MTDP Sent
•
Output Request Id
•
Return Code
DBFABT
DBFABT is the Abort Request function of DBCHCL.
DBFABT attempts to abort the current start request and the transaction in which it is
embedded. It is used asynchronously to abort a request in progress.
How It Works
DBFRABT performs the following functions:
•
If the application has requested option updates, performs option set/validation logic
•
If specified request is active on the Teradata Database, sends an Abort Request message
and returns to caller; otherwise, returns a error code
Sending an Abort
The sequence of operations to send an abort request is:
1
Call DBCHCL for DBFABT
2
Check that return code is zero
A return code of zero indicates that an abort has been sent. It does not guarantee that the
abort has been successful; the abort may “cross in the mail” with the response. The
application program must also look at the first parcel received in the response to
determine if the abort has been successful.
Successful Abort Operation
The sequence of operations for a successful abort operation is:
204
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
DBCAREA Parameters
1
Call DBCHCL for DBFABT
2
Check that return code is zero
3
Call DBCHCL for DBFFET
4
Check that return code is zero
5
Check that first parcel is Failure
6
Check that failure code is ‘user abort’ (3110)
7
Call DBCHCL for DBFERQ
8
Check that return code is zero
Asynchronous Aborts
If the asynchronous abort reaches the Teradata Database before it completes the response
(spool file), the Teradata Database aborts the original Teradata SQL request, rolls back the
transaction (explicit or implicit) in which it was embedded, if any, and sends a Failure parcel
as the response to the original request.
If a transaction is rolled back, any data base changed by the transaction is returned to the state
it would have been in if the transaction had not been submitted. However, the Teradata SQL
response files for any Teradata SQL requests that have already completed are not discarded.
They remain in the Teradata Database until the requests are closed by a call to DBCHCL for
the DBFERQ.
If the asynchronous abort reaches the Teradata Database after it completes the response, the
client receives the original response parcels for the original request. The abort does not take
place.
To abort one request, the application program specifies that request’s session id and request id
in the DBCAREA, sets the function code to abort, and calls DBCHCL. If multiple sessions are
being used and more than one request is to be aborted, the application repeats these steps for
each request.
The DBFABT is not itself affected by the setting of Wait For Response.
If the application program has a transaction in progress and is between requests, submit a
synchronous abort by calling DBCHCL for DBFIRQ with a request consisting of the Teradata
SQL ROLLBACK statement, not by calling DBCHCL for the DBFABT.
Values Read and Used, But Not Stored
The values of Wait Across Crash, Tell About Crash, Return Time, and Wait For Response are
read and used, but not saved.
Interface
The DBFABT interface is as follows:
Function:
DBFABT - Abort Request
Purpose:
Attempt to ‘abort’ a currently active request
Parms:
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
205
Chapter 7: Common Routines
DBCAREA Parameters
DBCAREA Parameters
The following fields in the DBCAREA may be read or written to by DBCHCL’s DBFABT,
depending on the application program’s environment.
Input Arguments
•
Change Options
•
Input Session Id
•
Input Request Id
•
Request Buffer Length
•
Response Buffer Length
•
Return Time
•
Tell About Crash
•
Token
•
Wait Across Crash
•
Wait For Response
Output Arguments
•
Current Response Buffer Length
•
Message Length
•
Message Text
•
MTDP Sent
•
Return Code
DBFFET
DBFFET is the Fetch function of DBCHCL.
DBFFET delivers a pointer to the next parcel of the response.
How It Works
DBFFET performs the following functions:
206
•
If request is still active, waits for completion
•
If the application has requested option updates, performs option set/validation logic
•
If this is the first FET call, examines first parcel
•
If double buffering is set and the current buffer is not the last, dispatches continue request
on the second buffer
•
Returns the next output data
•
If in Buffer Mode, which is necessarily Locate Mode, returns pointer to next buffer
•
If in Parcel Mode, returns next parcel
•
If buffer is exhausted, sets return code to indicate this
•
Delivers a pointer to the next unit (parcel or buffer) of the response
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
DBCAREA Parameters
•
If in Move Mode, moves the parcel from the Response buffer to a location specified by the
application program
Submitting a Fetch
The sequence of operations to submit a fetch is:
1
Call DBCHCL for DBFFET
2
Check that return code is zero
Successful Fetch Operation
The sequence of operations for a successful fetch operation is:
1
Call DBCHCL for DBFFET
2
Check that return code is zero
3
If in Move Mode, check that Fetch Error Indicator is zero
If in Parcel Mode, check that parcel is not Error or Failure parcel and “consume” the
information in the parcel
If in Buffer Mode, check that parcel is not Error or Failure parcel and “consume” the
information in the parcel
4
Repeat check and “consume” steps for each parcel in buffer
Combination of Modes
There are four combinations of modes for working with the parcels in the response:
•
Locate Mode with Parcel Mode
The application program can leave the parcels in the response buffer (Locate Mode) and
obtain the address of the next parcel (Parcel Mode) each time it calls DBCHCL for
DBFFET.
•
Locate Mode with Buffer Mode
The application program can leave the parcels in the response buffer (Locate Mode) and
obtain the address of the whole buffer (Buffer Mode) each time it calls DBCHCL for
DBFFET. It is then the application program’s responsibility to separate the parcels, if
required.
•
Move Mode with Parcel Mode
The application program can have the parcels copied (Move Mode) from the response
buffer into the Move area, one parcel (Parcel Mode) each time DBCHCL is called for
DBFFET. This method is very convenient for the application program, at the small cost of
the extra space for the Move area and the extra time for DBCHCL to copy the parcel.
•
Move Mode with Buffer Mode
The application program can have the complete response buffer copied (Move Mode) into
the Move area. DBCHCL is called for DBFFET. This method should only be used if the
application program must have the complete response buffer copied into its process space.
Expect performance to be taxed, because of the extra space for the Move area and the extra
time for DBCHCL to copy the parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
207
Chapter 7: Common Routines
DBCAREA Parameters
Interface
The DBFFET interface is as follows:
Function:
DBFFET - Fetch
Purpose:
Fetch next parcel (analogous to SQL ‘FETCH‘)
Parms:
DBCAREA Parameters
The following fields in the DBCAREA may be read or written to by DBCHCL’s DBFFET,
depending on the application program’s environment.
Input Arguments
•
Change Options
•
Fetch Data Pointer (if Move Mode)
•
Fetch Maximum Data Length
•
Function
•
Input Request Id
•
Input Session Id
•
Return Time
•
Tell About Crash
•
Wait Across Crash
•
Wait For Response
Output Arguments
•
Current Response Buffer Length
•
Fetch Data Pointer (if Locate Mode)
•
Fetch Error Indicator (if Move Mode)
•
Fetch Parcel Flavor (if Parcel Mode)
•
Fetch Returned Data Length
•
Message Length
•
Message Text
•
MTDP Received
•
MTDP Sent
•
Output DBC Session Id (after associated connect)
•
Output DBCpath (after associated connect)
•
Output Host Id (after associated connect)
•
Return Code
DBFREW
DBFREW is the rewind function of DBCHCL.
208
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
DBCAREA Parameters
DBFREW sends a reset- pointer request to the Teradata Database.
How It Works
DBFREW performs the following functions:
•
If the session is active, awaits completion
•
If Keep response is set to 'N' at the time of submitting the request whose response is to be
rewound, then CLI will return 310 error.
•
If a Failure or Error parcel is received in response to the request whose response is to be
rewound, then CLI will return 310 error.
•
If there is a first fetch buffer, positions to the beginning.
•
If Keep Response is set and there is no first Fetch buffer, sends a Continue Request message
containing a Rewind parcel and return to caller
Requesting a Rewind
The sequence of operations to request a rewind is:
•
If the reset request is successful on the client, the Teradata Database resets its parcel pointer
to the first parcel in the response and sends the first portion of the response to the client.
Note: Rewind does not include fetch (DBFFET). The application program must submit a
Fetch separately.
•
If rewinding may be required, sets Keep Response to Y when the request is submitted.
•
If Keep Response is set to N, the response may have been discarded by the time a rewind is
required. If rewinding is required, sets Keep Response to ‘Y’ or ‘P’ when the request is
submitted.
Values Read and Used, But Not Stored
The values of Wait Across Crash, Tell About Crash, Return Time, and Wait For Response are
read and used, but not stored.
Interface
Function:
DBFREW - Rewind
Purpose:
Reposition to beginning of response
Parms:
DBCAREA Parameter
The following fields in the DBCAREA may be read or written to by DBCHCL’s DBFREW,
depending on the application program’s environment.
Input Arguments
•
Change Options
•
Function
•
Input Request Id
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
209
Chapter 7: Common Routines
DBCAREA Parameters
•
Input Session Id
•
Request Buffer Length
•
Response Buffer Length
•
Return Time
•
Tell About Crash
•
Token
•
Wait Across Crash
•
Wait For Response
Output Arguments
•
Current Response Buffer Length
•
Message Length
•
Message Text
•
MTDP Sent
•
Return Code
DBFERQ
DBFERQ is the End Request function of DBCHCL.
DBFEEQ is used to explicitly close a request, discard its response, and de-allocate internal data
structures related to the request.
How It Works
DBFERQ performs the following functions:
•
If the application has requested option updates, performs option set/validation logic
•
If not Keep Response, and the EndRequest has been received, continues
•
If Keep Response, or if the EndRequest parcel has not been received, sends a Continue
Request message containing a Cancel parcel
•
If the session is active, awaits completion
•
Sends a Continue Request message containing a Cancel parcel and awaits completion
•
Destroys request context
Successful End Request Operation
The sequence of operations for a successful end request operation is:
1
Call DBCHCL for DBFERQ
2
Check for return code of zero
The DBFERQ applies to requests generated by calling DBCHCL for the DBFCON, DBFRSUP,
and DBFIRQs.
210
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
DBCAREA Parameters
The DBFERQ ensures that the Teradata SQL request’s response is discarded, thus freeing space
on the database computer, and de-allocates CLI internal buffers (thus freeing space on the
client).
These space-saving operations make it valuable to call DBCHCL for the DBFERQ as soon as
the response is no longer required by the application program. In fact, it is still valuable
(especially on IBM PC clients) to call DBCHCL for the DBFERQ even if the request was
submitted with Keep Response set to N and the response was consumed or discarded by the
Teradata Database.
DBCHCL always de-allocates the response buffer.
DBCHCL does not use the Open Requests field.
Values Read and Used, But Not Stored
The values for Wait Across Crash, Tell About Crash, Return Time, and Wait For Response are
read and used, but not stored.
Interface
Function:
DBFERQ - End Request
Purpose:
Terminate/cleanup specified request
Parms:
DBCAREA Parameters
The following fields in the DBCAREA may be read or written to by DBFERQ, depending on
the application program’s environment.
Input Arguments
•
Change Options
•
Function
•
Input Request Id
•
Input Session Id
•
Return Time
•
Tell About Crash
•
Wait Across Crash
•
Wait For Response
Output Arguments
•
Message Length
•
Message Text
•
Return Code
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
211
Chapter 7: Common Routines
DBCAREA Parameters
DBFDSC
DBFDSC is the Disconnect function of DBCHCL.
DBFDSC is used to log a session off the Teradata Database and de-allocate internal structures
allocated by DBFCON.
How It Works
DBFDSC performs the following function:
•
If session active, awaits completion
•
If the application has requested option updates, performs option set/validation logic
•
Performs logical ERQ on all open requests, except for spool file cancel processing
•
Sends logoff request to the Teradata Database
•
Frees all session-related control blocks
Successful Disconnect Operation
The sequence of operations for a successful disconnect operation is:
1
Call DBCHCL for DBFDSC
2
Check that the return code is zero
If the session being disconnected has a pending request, DBCHCL returns control to the
application program with a return code zero.
Both the return code of zero and the return code of “request may be aborted” allow the
application program to be certain that the session will be logged off. The application does not
have to do further checking. However, if the application program receives a return code of
“request may be aborted,” the application program cannot determine whether the request
aborted.
If a transaction is in progress, logging the session off causes the transaction to be rolled back.
Note: DBFDSC is not affected by the setting of Wait For Response.
For a connect that was unsuccessful, the internal structures that CLI allocated for the session
still exist.
Interface
Function:
DBFDSC - Disconnect
Purpose:
Logoff session and free associated control blocks
Parms:
DBCAREA Parameters
The following fields in the DBCAREA may be read or written to by DBCHCL’s DBFDSC,
depending on the application program’s environment.
212
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 7: Common Routines
DBCAREA Parameters
Input Arguments
•
Function
•
Input Session Id
Output Arguments
•
Message Length
•
Message Text
•
Return Code
DBCHCLN
DBCHCLN cleans up CLI ‘s memory.
How It Works
The application invokes the DBCHCLN routine when all processing that involves interfacing
with the Teradata Database is complete.
DBCHCLN logs off any idle sessions, awaits completion of any active sessions (internally
DBCHCLN invokes DBFDSC on any session that is still logged on) and then logs them off,
and frees all internal memory and context information allocated by CLI.
DBCHCLN de-allocates internal data structures that were allocated by DBCHINI.
DBCHCLN returns control to the application after all sessions have been logged off and all
internal context has been cleaned up.
The call to DBCHCLN does not de-allocate the DBCAREA. The application program may
itself de-allocate the DBCAREA if the programming language provides that ability.
DBCHCLN performs clean-up on a process-wide basis and, ideally, it should only be issued
once. If the application program consists of multiple threads using CLIv2, issuing DBCHCLN
while one or more threads is still using CLIv2 can result in failures. To avoid this situation, the
application program must ensure that DBCHCLN is issued only from a control or supervisory
thread after all other threads have concluded their use of CLIv2. Alternatively, the application
program can use the atexit() function of the C/C++ run-time library to invoke DBCHCLN at
process termination as follows:
if (atexit(clean_up))
{
perror("atexit failed");
exit(8);
}
...
void clean_up(void)
{
DBCHCLN(&result, cnta);
}
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
213
Chapter 7: Common Routines
DBCAREA Parameters
The process termination exit registered by atexit() is only called for normal termination. It
will not receive control if the program is terminated by abort(), an unhandled signal. Consult
system documentation or man pages for further information.
Returns 0 if succeeds, else returns error.
Parameters
Int32
DBCHCLN (ReturnCode, ContextArea)
Int32
*ReturnCode;
char
*ContextArea;
where:
The parameter...
Is the...
ReturnCode
four-byte address of an area allocated by the application program for storage
of a four-byte signed integer.
After control returns from DBCHCLN, the integer contains a code whose
value represents success or failure to clean up. A return code of zero indicates
success; a non-zero return code indicates failure, and the value specifies the
reason for the failure.
ContextArea
214
four-byte field which may contain any value because it is not used by CLI or
the application program. It is provided to maintain compatibility with calls
on mainframe clients.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 8
Other CLI Routines
This chapter describes these routines:
•
DBCHFER
•
DBCHPEC
•
DBCHQE
•
DBCHREL
•
DBCHSAD
•
DBCHUE
•
DBCHUEC
•
DBCHWAT
•
DBCHWL
See Chapter 16: “CLI Exit Functions” for descriptions of the CLI exit functions.
Use
Table 11 lists the remaining routines and describes how they are used.
Table 11: Use of Routines
Routine
Description
DBCHFER
What:
Fetches textual description and error codes for the last error detected
for a specific session, or the last error that occurred overall.
Why:
To provide adequate information about an error condition so that
applications and/or users can recover from, or correct the condition.
Where:
All clients.
What:
Sets the global CLI attention flag.
Why:
To return control to the application program when some event occurs
such as a signal like a control-C break.
Where:
All clients.
DBCHPEC
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
215
Chapter 8: Other CLI Routines
Use
Table 11: Use of Routines (continued)
Routine
Description
DBCHQE
What:
Queries the Teradata Database.
Why:
To see default information prior to logging on so that changes can be
made before starting a session.
Where:
All clients.
What:
Returns the release level and version numbers of the software running
on the database computer handling the specified session.
DBCHREL
Caution: For increased reliability, use the QEPIDBR field of the
DBCHQE routine instead of DBCHREL. See “The qepItem
Field” on page 224 for more information.
DBCHSAD
DBCHUE
DBCHUEC
DBCHWAT
DBCHWL
216
Why:
To generate an audit trail, to aid in debugging, and so on.
Where:
All clients.
What:
Stores specified value at specified address.
Why:
To return the address of a given parameter.
Where:
All clients.
What:
Associates platform-defined events with user defined contexts.
Why:
To associate an event with a user context in which DBCHWL waits for
completion. The only event supported is a timeout event, permitting
DBCHWL to return a timeout to the application in the case of no
completed requests from the session list.
Where:
All Windows ™ clients.
What:
Resets the global CLI attention flag.
Why:
To set up a way for the application program to regain control if some
event, such as a terminal attention, is detected.
Where:
All clients.
What:
Waits for event to occur (an “event” refers to the arrival of some
response from the Teradata Database; if DBCHUEC has been invoked,
“event” also refers to the occurrence of some application programdefined event).
Why:
To provide a mechanism for explicit waits for events and to simplify
the handling of concurrent Teradata Database sessions.
Where:
All clients.
What:
Wait for completion of any active requests from a supplied session list
or completion of an optionally supplied event.
Why:
To simplify multi-threaded applications by waiting on a specific set of
sessions and/or events.
Where:
All Windows clients.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Parameters of CLI Routines: Tabular Summary
Table 12 lists the parameters for the routines described in this chapter.
Table 12: Parameters for CLI Routines
Routines
Parameters
DBCHFER
LogSessId
ErrorStruct
MsgBuf
DBCHFERL
LogSessId
ErrPtr
msgbuf
ibuflen
obuflen
msgerr
DBCHPEC
ReturnCode
UserECB
DBCHQE
ReturnCode
ContextArea
DBCHQEP
DBCHREL
ReturnCode
ContextArea
Session
Release Version
DBCHSAD
ReturnCode
Target Address
Source Value
DBCHUE
ReturnCode
ContextArea
EventIDAddress
Function
DBCHUEC
ReturnCode
ContextArea
UserECB
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
217
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Table 12: Parameters for CLI Routines (continued)
Routines
Parameters
DBCHWAT
ReturnCode
ContextArea
Session, Token
DBCHWL
ReturnCode
ContextArea
sessions
sessid
reqtoken
DBCHFER
DBCHFER retrieves session specific error information.
The value returned by this routine is the value that was actually returned by the CLI service
routine that encountered the error being reported on.
Values
The values stored in the err_code structure identify what errors actually occurred at levels
“below” CLI, that is, MTDP and MOSI.
This structure contains three error values:
•
e_class
This class of error values defines the type of operation MTDP was performing when the
error occurred. For example, EC_NETWORK.
•
e_reason
This class of error values defines the actual error encountered by MOSI. For example,
ER_LINKDOWN.
•
e_syst
This class of error values is the value of errno (stored in e_syst by MOSI) if the error
resulted from a failed system call.
Parameters
DBCHFER (LogSessId, ErrPtr, MsgBuf)
where:
218
The parameter...
Is the...
LogSessId
integer logical session number assigned by CLI, if error information for
a specific session is desired.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
The parameter...
Is the...
If this value is zero, information on the last error that occurred overall
is provided. The size of this argument is the integer size on the target
machine.
ErrPtr
four-byte pointer to a structure to receive error codes. This structure is
defined in COPERR.H, and has the following format:
struct err_code
{ int
e_class;
int
e_reason;
long e_syst;
}
This argument is optional and should be NULL if no specific error
code information is desired.
MsgBuf
four-byte pointer to an 80 byte text area to receive error message text.
This argument is optional, and should be NULL if no text is desired.
DBCHFERL
DBCHFERL (Fetch Error Localized) is an extension of DBCHFER. This routine has an
additional capability of returning the session-specific error information in localized form.
Messages are returned by CLI, in the message buffer provided by the application, in the
specified language. The length of the message returned depends on the size of the buffer
allocated. The value returned by this routine is the value that was actually returned by the CLI
service routine that encountered the error being reported.
Parameters
Int32 DBCHFERL
(int LogSessId,
register errpt_t Err,
char*msgbuf,
unsigned short ibuflen,
unsigned short * obuflen,
short * msgerr)
LogSessId
Integer logical session number assigned by CLI,
if error information for a specific session is desired.
If this value is zero, information on the last error that occurred overall is
provided. The size of this argument is the integer size on the target machine.
ErrPtr
pointer to a structure to receive error codes. This structure is defined in
COPERR.H, and has the following format:
struct err_code{
int e_class;
int e_reason;
long e_syst;
}
This argument is optional and should be NULL if no specific error code
information is desired.
msgbuf
pointer to a buffer for placing error message. Allocated by the application.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
219
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
ibuflen
size of the message buffer allocated by the application
obuflen
length of the message returned by CLI, in application-provided buffer
msgerr
Indicating error, if one occurred while building the message.
-1 = Application failed to provide a valid buffer
1 = Error message is truncated
0 = Successfully build the message
DBCHPEC
DBCHPEC sets the global CLI attention flag to indicate that the application has responded to
a BREAK interrupt.
DBCHPEC also wakes the process from a wait state (for example, if it is in DBCHWAT or a
waiting DBCHCL function).
Note: Using a control-C break/abort and if a break handler is posted (for example, via a signal
C call), the application should not post the abort call within the signal handler routine; if
DBCHCL is called from the signal handler, erroneous results could occur. To properly handle
the break/abort, the application should wait for any pending DBCHCL operation to complete
by returning the EM_BREAK return code and then post the Abort function.
Parameters
DBCHPEC (ReturnCode, UserECB)
where:
The parameter...
Is the...
ReturnCode
four-byte address of an area allocated by the application program for storage
of a four-byte signed integer.
UserECB
four-byte address of the area allocated by the application program for use as
UserECB.
Usage Notes
After control returns from DBCHPEC, the integer contains a code whose value represents
success or failure. A return code of zero indicates success; a non-zero return code indicates
failure, and the value specifies the reason for the failure.
DBCHQE
DBCHQE is a query facility that enables you to request system default information from the
Teradata Database prior to logging on, thereby allowing you to make changes before starting a
session.
The Session Character Set, which is obtained on per session basis, can be obtained only after a
session has been logged on.
220
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Parameters
DBCHQE (ReturnCode, ContextArea,DBCHQEP)
Int32
*ReturnCode
Int32
*ContextArea
Int32
*DBCHQEP
where:
The parameter...
Is the...
ReturnCode
four-byte address of an area allocated by the application program for storage
of a four-byte signed integer.
ContextArea
four-byte address not used by CLI. It is provided to maintain compatibility
with the mainframe.
DBCHQEP
four-byte address of the DBCHQEP structure.
Some of this structure needs to be filled in by the application program to
request query information. The results of the query will then be sent back to
the application in this structure.
DBCHQEP Structure
Fields
Data Type
Description
qepLevel
unsigned char
Unassigned numeric format of the parameter list.
The values supported in this field are:
• 1 - The default character set is returned. The
application should specify dbcname in qepTDP
while using this option. Applications should use
this level for querying any other information.
• 2 - The character set specified for that particular
session is returned. The application should
specify the session number in qepConn.
• 129 - (QEPL10NLVL1) Same as level 1.
Additionally, uses new fields defined in
DBCHQEP structure to give localized CLI error
information.
• 130 - (QEPL10NLVL2) Same as level 2.
Additionally, uses new fields defined in
DBCHQEP structure to give localized CLI error
information.
qepItem
unsigned char
For valid item codes and their descriptions, see
“The qepItem Field” on page 224.
qepTLen
unsigned short
Must be set to the TDPID length and TDPID name
(dbcname) used for the query.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
221
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Data Type
Description
qepTDP
long
Must be set to the TDPID length and TDPID name
(dbcname) used for the query.
qepRsv1[4]
char
Reserved
qepRALen
unsigned short
Unsigned numeric length of the area in which the
result of the query is returned. Supplied by caller.
qepRDLen
unsigned short
Unsigned numeric length of the data returned. CLI
writes into this field the length of the data it
returned in qepRArea. (Sets to the length of the data
returned, up to the size of the area specified by the
qepRALen field.)
Set to the length of the data returned (up to the size
of the area as specified by the qepRALen field).
*qepRArea
void
Pointer to the area in which the result of the query is
returned.
The length of this area is set by the application in
qepRALen.
qepRsv2
unsigned short
Reserved
qepMLen
unsigned short
Reserved
qepMsg
char
Reserved
qepConn
long
Session number
qepMLid
char[2]
Specify the language to be used for any CLI error
message associated with the request.
• EN for English
• JA for Japanese
222
*qepMsgP
char
Pointer to an area into which any error message will
be placed. Area is allocated by the application.
qepMsgM
unsigned short
Unsigned numeric length, in bytes, of the area
pointed to by QepMsgP.
qepRC
unsigned short
Unsigned numeric CLI return code that occurred
while processing the DBCHQEP.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Data Type
Description
qepRMRC
unsigned short
Unsigned numeric CLI return code for any error
that occurred while constructing the message.
• 1 = overflow
• 4 = Langid used is not supported.
Message is returned in English
• 2 = CLI is not able to build the message because
qepMsgP is not provided by the application.
• 0 = Built the message successfully.
If two errors occur simultaneously then the result
returned is a bit-wise ‘or’ of the two return codes.
(for example, if langid used is default and overflow
occurred while returning the message, the output
will be:
QEPRC = 2 | 1 = 3
qepRMLen
unsigned short
Unsigned numeric length, in bytes, of the message
returned in the area addressed by QEPMSGP.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
223
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
The qepItem Field
qepItem must be set to a value indicating the type of request, as follows:
Fields
Value
Description
QEPIIID
1
Not supported
QEPISC
2
Returns the name of the default session character set. The return
area must be at least 30 bytes because DBCHQE will return a 30byte character string containing the default character set. All
other requests need only a one-byte response area.
Refers to the session whose CLIv2 session number is specified in
the qepConn field.
QEPIFTSM
3
Transaction Semantics
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for Teradata transaction semantics.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
QEPIFLCS
4
Language Conformance
Returns the following values to the area pointed to by qepRArea
to indicate what type of SQL is supported:
• 'Y' - Standard SQL and Teradata SQL are supported.
• 'N' - Only Teradata SQL is supported.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
QEPIFUCR
5
Updatable Cursor
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for updatable cursors.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
QEPIFRFI
6
Referential Integrity
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for referential integrity.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
QEPIDTSM
7
Returns the default transaction semantics, a one-byte character
(A or T), for the identified Teradata server to the area pointed to
by qepRArea.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
224
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEP64K
8
64K Parcels
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for 64K parcels.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
QEPICL2R
9
Release Identifier
Returns the release identifier for the CLI being used.
The release identifier is an eleven-character value consisting of
the two-character major release identifier, the two-character
minor release identifier, and the two-character maintenance
release identifier, each separated by periods. The last three
characters are often blank, but if they are not, they are a period
delimiter followed by the two-character E-tape identifier.
Note: The intent of the data is not to deduce CLI functionality,
but simply to provide the current CLI release identification.
QEPIDPF
10
Parallelism
Returns a dimensionless value that indicates the extent of parallel
processing used internally by the server as a four-byte unsigned
integer to the area pointed by qepRArea.
Note: The exact meaning of this factor should be considered an
implementation detail internal to the Teradata Database.
Itsutility to a normal application is limited to comparisons of the
parallelism of different servers.
QEPIDMSS
11
Maximum Parcel Size
Returns a four-byte value that indicates the maximum size
allowed for a segment supported by the server. Segments are used
to subdivide special purpose requests that exceed the maximum
parcel size.
QEPITDPR
12
Mainframe Compatibility
This query level is for mainframe compatibility only. On
network-attached clients, this query will result in CLI Error 354
(NOQINFO), "The requested query information is unavailable".
QEPIFSSO
13
Single Sign-On
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for single sign-on.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
225
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPISU
14
Authentication
Returns the actual Teradata Database username of a user logged
in using single sign-on or third-party authentication mechanism
(such as LDAP).
Refers to the numeric session id indicated by qepConn.
QEPIFUPS
15
Atomic UPSERT
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for Atomic UPSERT.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
QEPIAOP
16
Array Operations
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for ARRAY OPERATIONS. The length of qepRArea
should be at least 1 byte.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
QEPIFMRG
17
MERGE INTO
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for MERGE_INTO. The length of the qepRArea should
be at least 1 byte.
Refers to the Teradata server whose TDP identifier is addressed
by the qepTDP field and has length specified by the qepTLen
field.
QEPIFLOB
18
LOB
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for LOB support.
Refers to the server whose TDP identifier is addressed by the
qepTDP field and has length specified by the qepTLen field.
QEPITPR
19
Timing Precision
Returns the minimum and maximum values for timing-precision
supported by client platform, as two signed, 2-byte fields.
The QEPTDP is ignored. The length of the qepRArea should be
at least 4 bytes.
QEPIXRS
20
Extended Response
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for extended message response. The length of the
qepRArea should be at least 1 byte.
Refers to the server whose TDP identifier is addressed by the
qepTDP field and has length specified by the qepTLen field.
226
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPIEPU
21
APH Request
Returns one of the following to the area pointed to by qepRArea:
• 1 - supports APH
• 0 - does not support APH
The length of the qepRArea must be at least 2 bytes.
Refers to the server whose TDP identifier is addressed by the
qepTDP field and has length specified by the qepTLen field.
QEPIUD
23
Utility-data support
Refers to the server whose TDP identifier is addressed by the
qepTDP field. The length of the qepRArea should be at least 4
bytes.
The returned 4 byte value contains:
• first byte - 'Y' or 'N' for the existing Checkpoint-Interval
support of the identified Teradata server.
• second byte - unused
• third and forth byte - A two-byte unsigned integer 0 or 1 for
FastExport Without Spooling support of the identified
Teradata server.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
227
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPIASL
24
Aggregate Support List
Returns a list of values that indicate support for multiple features.
The list consists of 1-byte values equal to those returned by the
following query items, in order:
QEPIASL
(continued)
•
•
•
•
•
•
QEPIFTSM (Transaction Semantics)
QEPIFLCS (Language Conformance)
QEPIFUCR (Updatable Cursor)
QEPIFRFI (Referential Integrity)
QEP64K (64K parcels)
QEPIFSSO (Single Sign-On)
Note: When connecting to a Teradata Database older than
V2R6.0, this field will not contain the correct value unless a
session has been established.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
QEPIFUPS (Atomic UPSERT)
QEPIAOP (Array Operations)
QEPIFMRG (MERGE INTO)
QEPIFLOB (LOB)
QEPIXRS (Extended Response)
(reserved)
QEPIEPU (APH request)
QEPIRPO (Cursor Positioning)
QEPIUDT (UDT)
QEPIESS (Enhanced Statement Status)
QEPIAPH (APH response)
QEPIRCA (Relaxed Call Argument)
QEPISIS (Statement Info parcel)
QEPIIDE (Large Integer/Decimal)
QEPIRID (Insert returns data when identity columns are
involved)
• QEPIDRS (ResultSet)
• QEPIQBS (QUERY_BAND)
• QEPIMIU (MERGE INTO)
• QEPILEU (LOGGING ERRORS)
• QEPIPD (Default Connection)
• QEPITSS (Trusted Sessions)
• QEPILNS (LOB Name)
• QEPICCS (Column Correlation)
The length of the qepRArea should be at least 29 bytes. A length
of 64 bytes is recommended.
Refers to the server whose TDP identifier is addressed by the
qepTDP field and has length specified by the qepTLen field.
228
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPIRPO
25
Cursor Positioning
Returns 'N' or 'Y' to the area pointed to by qepRArea to indicate
support for cursor positioning. The length of the qepRArea
should be at least 1 byte.
Refers to the server whose TDP identifier is addressed by the
qepTDP field and has length specified by the qepTLen field.
QEPIENC
26
Data Encryption
Returns 'N' or 'Y' to indicate whether encryption is both
supported and enabled on the database server to which the
session is connected.
Refers to the session whose CLIv2 session number is specified in
the qepConn field.
QEPIRMR
27
CLI Information
Returns the CLIv2 release identifier and any customization
information for the message table used for the session whose
CLIv2 connection number is specified in the qepConn field and
the request whose CLIv2 request number is specified in the
QEPRQST field.
The length of the returned information is up to 48 ASCII
characters, consisting of one or two identifiers separated by a
comma.
QEPIACS
28
Character Sets
Returns the names of the character sets available on the server
specified by the TDP identifier addressed by the qepTidp field
and has length specified by the qepTlen field.
The length of the response is four fixed fields followed by a
variable number of character set names. Returns as many whole
character set names as will fit into the response area whose length
is indicated by qepRalen. If all names are not returned, one of the
following queries (that specify the returned token) can be issued
to indicate the processing of additional names:
• qeracsTk - A 4-byte token to be placed into qepToken to
retrieve any additional character set names. The content of the
token is undefined and must not be altered by the application.
• qeracsNR - A 2-byte unsigned integer that indicates the
number of character set names not returned.
• qeracsNP - A 2-byte unsigned integer that indicates the
number of character set names returned.
• qeracsLn - A 2-byte unsigned integer that indicates the length
of each character set name.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
229
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPIESS
29
Enhanced Statement Status
Returns 'Y' or 'N' to indicate support for enhanced statements.
The length of the qepRArea should be at least 1 byte.
Refers to the TDP identifier addressed by the qepTDP field and
has length specified by the qepTLen field.
QEPIUDT
30
UDT
Returns 'Y' or 'N' to indicate support for user-defined types.
QEPIAPH
31
APH Response
Returns to the area pointed to by qepRArea a numeric value or 0
to indicate support for APH responses.
Refers to the TDP identifier addressed by the qepTDP field and
has length specified by the qepTLen field.
QEPIALM
32
Mechanisms
Returns a list of supported mechanism names:
• qeralmTk - A 4-byte token to be placed into QEPTOKEN to
retrieve any additional mechanism names. The content of the
token is undefined and must not be altered by the application.
• qeralmNR - A 2-byte unsigned integer that indicates the
number of mechanism names not returned.
• qeralmNP - A 2-byte unsigned integer that indicates the
number of mechanism names returned.
• qeralmLn - A 2-byte unsigned integer that indicates the length
of each mechanism name and associated flags.
QEPIDCS
33
Default Character Set
Returns the default character set of the database as 30 single-byte
characters in the platform character set (ASCII), left-justified,
and padded with blanks.
The caller of DBCHQE must supply a return area with a length of
at least 30 bytes.
Note: This field is not returned as a string, so the caller will need
to insert a null terminator in the first blank location prior to
attempting to write the field to output via print.
230
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPIDBR
34
Teradata Database Information
Returns the Teradata Database release and version information in
two contiguous fields using slightly different formats:
• 30 single-byte characters in the platform character set
(ASCII), left-justified, and padded with blanks, for example,
V2R.06.01c.00.00.
• Immediately following, 32 single-byte characters in the
platform character set (ASCII), left-justified, and padded with
blanks, for example, 06.01c.00.00.
The caller of DBCHQE must supply a return area with a length of
at least 62 bytes.
Note: Neither field is returned as a string, so the caller will need
to insert a null terminator in the first blank location prior to
attempting to write the field to output via print.
Note: The intent of the data is not to deduce Teradata Database
functionality, but simply to provide the release and version
information for whatever diagnostic use they may be. The values
should not be parsed for any reason since their format is subject
to change.
QEPIC2L
35
CLI Limits
Returns limits for the Teradata Database affecting an
application's values for CLIv2 settings. The response consists of
four fields totalling 32 bytes.
The caller of DBCHQE (QEPIC2L) must supply a return area of
at least 32 bytes. A structure mapping (struct QEPCLLIMIT_) is
supplied in dbchqep.h for the convenience of users.
QEPISQL
36
SQL Limits
Returns limits for the Teradata Database affecting an
application's use of SQL statements. The response consists of 24
field totalling 104 bytes.
The caller of DBCHQE (QEPISQL) must supply a return area of
at least 104 bytes. A structure mapping (struct QEPDBLIMIT_)
is supplied in dbchqep.h for the convenience of users.
QEPIRCA
37
Relaxed Call Argument
Returns an indicator which can be used to determine whether the
target server supports the Relaxed Call Argument feature.
DBCHQE will return 'Y' if server supports this feature and 'N'
if it does not (using ASCII characters).
The caller of DBCHQE must supply a return area with a length of
at least one byte.
QEPISIS
38
StatementInformation Parcels
Returns 'Y' or 'N' to indicate support of StatementInformation
parcels.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
231
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPIIDE
39
Large Integer/Decimal
Returns 'Y' or 'N' to indicate support for the Large Integer/
Decimal feature.
A returned value of 'Y' indicates that the server supports this
feature. A returned value of 'N' or any non-zero return code
indicates that the server does not support this feature. Returned
values are in ASCII.
QEPIIDE requires a return area of at least one byte and a target
TDPid.
This query item is also included in the aggregate support list.
QEPIRID
40
Defines whether data may be returned in response to an SQL
Insert operation when Identity columns are involved.
A returned value of 'Y' indicates that the server supports this
feature. A returned value of 'N' or any non-zero return code
indicates that the server does not support this feature. Returned
values are in ASCII.
QEPIRID requires a return area of at least one byte and a target
TDPid.
This query item is also included in the aggregate support list.
QEPIDRS
41
ResultSet
Returns 'Y' or 'N' to indicate whether stored procedures may
return the results of their SQL statements to the application.
QEPIQBS
42
Query Band
Returns 'Y' or 'N' to indicate support for the SQL SET
QUERY_BAND statement.
QEPIMIU
43
MERGE INTO
Returns 'Y' or 'N' to indicate support for the SQL MERGE INTO
statement.
QEPILEU
44
Logging Errors
Returns 'Y' or 'N' to indicate support for the Teradata SQL
LOGGING ERRORS clause.
QEPIPD
45
Default Connection
Returns 'Y' or 'N' to indicate support for the Default Connection
feature.
The caller must supply a return area with a length of at least one
byte.
232
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPISCS
46
Session Character Set
Returns the name of the session character set. The return area
must be at least 30 bytes because DBCHQE returns a 30-byte
character string that contains the character set.
Refers to the session whose CLIv2 session number is specified in
the qepConn field.
QEPICCS
47
Column Correlation
Returns 'Y' or 'N' to indicate support for the Column Correlation
feature.
QEPIUS
48
Utility Session
Returns the following values:
• Any 2-byte integer - The unformatted Teradata Database
node-id associated with the session.
• 0 - The node-id is not available.
Refers to the session whose CLIv2 session is specified in the
qepConn field. Utility-session is used by proprietary Teradata
utilities, and is not intended for other applications.
QEPIDAP
49
Returns the database access path
A database access path is a variable-length string that contains the
fully qualified domain name and its associated IP address and
port number.
The following possibilities are equally valid as the prefix for a
logon string. Accordingly, the query result consists of one
variable-length value. The port number (server side) is always
returned following the machine name, FQDN, or IP address,
separated by the conventional colon:
• If a dbcname is used (for example, a machine name sans
domain), a dbcname is returned.
• If a fully-qualified domain name (FQDN) is used, an FQDN
returned.
• If an IP address was used, an IP address will be returned.
QEPITSS
50
Trusted Decisions
Returns 'Y' or 'N' to indicate support for the Trusted Decisions
feature.
QEPILNS
51
LOBs
Returns 'Y' or 'N' to indicate support for the LOBs feature.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
233
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Fields
Value
Description
QEPITOU
52
UDT-TransformsOff-support
The caller of DBCHQE (QEPITOU) must supply a return area of
at least two bytes and a target TDPid.
The returned value containing one of the following values:
• 0 - the value of 0 indicates that no UDTs can be transformed.
• 1 - the value of 1 indicates that UDTs can be transferred in the
untransformed mode.
• 2 - the value of 2 indicates that Period data type can be
transformed. DBS will accept from the client either PERIOD
Struct metadata and data values, or non-Struct PERIOD
metadata and data values.
QEPITRS
53
Trusted-request-support
Defines whether the database supports trusted sessions
enhancement for the trusted-request option.
A returned value of 'Y' indicates that the server supports this
feature. A returned value of 'N' or any non-zero return code
indicates that the server does not support this feature.
The caller of DBCHQE (QEPITRS) must supply a return area of
one byte and a target TDPid.
This query item is not included in the aggregate support list.
CLIv2-limits
An application can use CLIv2-limits to choose CLIv2 settings to optimize its execution for the
accessed Teradata Database, or to prevent errors caused by exceeding limits. Return limits for
the Teradata Database affect an application's values for CLIv2 settings. The response consists
of four fields totalling 32 bytes.
DBQERC2L (DbqerC2L for C)
Item
Code
Mnemonic
Fields
Value
35
QEPIC2L
MaxRequestBytes
An eight-byte unsigned integer.
MaxSegRequestBytes
An eight-byte unsigned integer.
MaxUsingDataBytes
An eight-byte unsigned integer.
MaxResponseBytes
An eight-byte unsigned integer.
Note: The caller of DBCHQE (QEPIC2L) must supply a return area of at least 32 bytes. A
structure mapping (struct QEPCLLIMIT_) is supplied in dbchqep.h for the convenience of
users.
234
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
SQL-limits
An application can use SQL-limits to construct SQL statements to optimize its execution for
the accessed Teradata Database, or to prevent errors caused by exceeding limits.
Return limits for the Teradata Database affect an application's use of SQL statements. The
response consists of 24 fields totalling 104 bytes.
DBQERSQL (DbqerSQL for C)
Item
Code
Mnemonic
Fields
Value
36
QEPISQL
MaxRowBytes
An eight-byte unsigned integer.
MaxLobBytes
An eight-byte unsigned integer.
MaxObjectNameChars
A four-byte unsigned integer.
MaxColinTbl
A four-byte unsigned integer.
MaxTblinSel
A four-byte unsigned integer.
MaxColinSel
A four-byte unsigned integer.
MaxColGrpBy
A four-byte unsigned integer.
MaxColOrdrBy
A four-byte unsigned integer.
MaxCharLiteralChars
A four-byte unsigned integer.
MaxBinLiteralChars
A four-byte unsigned integer.
MaxColBytes
A four-byte unsigned integer.
MaxCharChars
A four-byte unsigned integer.
MaxVarcharChars
A four-byte unsigned integer.
MaxGraphicChars
A four-byte unsigned integer.
MaxVargraphicChars
A four-byte unsigned integer.
MaxByteBytes
A four-byte unsigned integer.
MaxVarbyteBytes
A four-byte unsigned integer.
MaxDecimal
A four-byte unsigned integer.
MaxTimeScale
A four-byte unsigned integer.
MaxTimeStampScale
A four-byte unsigned integer.
MaxIntervalToSecondScale
A four-byte unsigned integer.
MaxFldsUsingRow
A four-byte unsigned integer.
MaxParamsInRequest
A four-byte unsigned integer.
MaxSPParams
A four-byte unsigned integer.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
235
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Note: The caller of DBCHQE (QEPISQL) must supply a return area of at least 104 bytes. A
structure mapping (struct QEPDBLIMIT_) is supplied in dbchqep.h for the convenience of
users.
DBCHREL
DBCHREL returns the software release level and version number strings for the session
specified by the input session identifier.
Caution:
For increased reliability, use the QEPIDBR field of the DBCHQE routine instead of
DBCHREL. See “The qepItem Field” on page 224 for more information.
The release level string is returned as a 6 byte string of the format XX.YY, where XX is the
major release number and YY is the minor release number. For example, 3.1 would be
returned for 3.1 level software.
The version string is a 15 byte string of the form XXXX.YYYY.ZZZZ, where XXXX is the
major version number, YYYY is the minor version number, and ZZZZ is the update version
number. For example, 0051.0000.0130 would be returned for version 51.0.130.
Note: Release level and version number are session-specific because it is possible to log
sessions onto different database computers from the same application program.
Returns 0 if succeeds, else returns error.
DBCHREL will return NOSESSION (304) if the session is not found.
Parameters
Int32 DBCHREL (ReturnCode, ContextArea, sessid, relstr, verstr)
Int32
*ReturnCode;
char
*ContextArea;
Int32
sessid;
char
*relstr;
char
*verstr;
where:
The parameter...
Is the...
ReturnCode
address of an area allocated by the application program for storage of a fourbyte signed integer.
After control returns from DBCHREL, the integer contains a code whose
value represents success or failure to obtain the information. A return code of
zero indicates success; a non-zero return code indicates failure, and the value
specifies the reason for the failure.
ContextArea
address of a one-byte area not used by CLI or the application program.
It is provided to maintain compatibility with calls on mainframe clients.
236
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
The parameter...
Is the...
sessid (session)
four-byte signed integer returned in the Output Session Id field of
DBCAREA from a previous call to DBCHCL for the DBFCON.
The integer contains the session id of the session for which the release
information is to be obtained.
relstr (release)
address of an area allocated by the application program for storage of a 6byte character string.
Upon return from DBCHREL, the string will contain the printable release
level of the software that is running on the database computer which is
handling the specified session.
verstr (version)
address of an area allocated by the application for storage of a 15-byte
character string.
Upon return from DBCHREL, the string will contain the printable version
number of the software that is running on the database computer which is
handling the specified session.
DBCHSAD
DBCHSAD returns the address of a given parameter.
It performs this function by storing the source argument at the target address. This allows the
DBCAREA pointer arguments to be set in languages that do not support pointer
manipulation.
CLI does not go through DBCHSAD’s internal initialization or attempt to find its internal
context.
Parameters
DBCHSAD (ReturnCode, TargetAddress, SourceValue)
Int32
*ReturnCode
void
**TargetAddress
void
*SourceValue
where:
The parameter...
Is the...
ReturnCode
After control returns from DBCHSAD, the integer contains a code whose
value represents success or failure to copy source value. A return code of zero
indicates success; a non-zero return code indicates failure, and the value
specifies the reason for the failure.
TargetAddress
address of the first byte of the area at which the source value is to be stored.
SourceValue
signed integer containing the value to be stored at the target address.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
237
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
DBCHUE
Restriction
Only supported on Microsoft Windows platforms.
Description
Associates platform-defined events with user defined contexts. Currently only supports one
event type - a timeout defined internally as CLI_WIN_TIMEOUT.
Parameters
The following structure, cli_win_event is used as the parameter EventIDAddress in this
function:
struct cli_win_event {
Int32 kind;
void *data;
}
/*event kind */
/*event data */
where kind must be a CLI_WIN_TIMEOUT and data must point to a timeval structure.
struct timeval {
Int32 tv_sec;
/* seconds */
Int32 tv_usec; /* microseconds */
}
The DBCHUE parameters are:
DBCHUE (ReturnCode, ContextArea, EventIDAddress, Function)
Int32 *ReturnCode
char **ContextArea
struct cli_win_event *EventIDAddress
Int32 Function
where:
The parameter...
Is the...
ReturnCode
Address of a four byte signed integer allocated by the application program.
After control returns from DBCHUE, the integer contains a code whose
value represents success or failure. A zero return value indicates success,
while a non-zero return code indicates the reason for failure.
Possible return codes include:
EM_OK - no errors
BADUECNTA - context area is invalid
BADUEKIND - bad kind value
BADUEDATA - data values NULL
238
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
The parameter...
Is the...
ALLOCFAIL - memory failure
BADUEFUNC - invalid function specified
ContextArea
Indirect pointer to a character pointer. During INSERT_EVENT functions,
this pointer is allocated memory and initialized by DBCHUE. During
DELETE_EVENT functions, this memory is freed by DBCHUE.
This ContextArea is used for waiting on user defined events in DBCHWL.
EventIDAddress
User defined event. Currently only event kinds of CLI_WIN_TIMEOUT are
supported.
Function
4 byte signed integer defining 2 supported event types - INSERT_EVENT
and DELETE_EVENT. INSERT_EVENT inserts the event and associates the
event with the ContextArea. DELETE_EVENT deletes the event and
disassociates the event with the ContextArea.
Usage Notes
DBCHUE presently only supports two event types - INSERT_EVENT and DELETE_EVENT.
Only CLI_WIN_TIMEOUT events are supported.
Only one event may be associated with a ContextArea.
DBCHUE supports multi-threaded CLI.
Example
This example defines a 5 second timeout event for use with DBCHWL.
cli_win_event time_event;
static struct timeval time_val;
Int32 result = 0;
Int32 retcode = 0;
char *cnta;
time_val.tv_sec = 5;
time_val.tv_usec = 0;
time_event.kind = CLI_WIN_TIMEOUT;
time_event.data = (void *)&time_val;
retcode = DBCHUE(&result, (char **) &cnta, &time_event,
INSERT_EVENT);
DBCHUEC
DBCHUEC (user-provided ECB subroutine) resets the global CLI attention flag.
Parameters
DBCHUEC (ReturnCode, ContextArea, UserECB)
Int32
*ReturnCode
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
239
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
char
ContextArea
char
UserECB
where:
The parameter...
Is the...
ReturnCode
four-byte address of an area allocated by the application program for storage
of a four-byte signed integer.
After control returns from DBCHUEC, the integer contains a code whose
value represents success or failure to establish the master ECB.
• A return code of zero indicates success.
• A non-zero return code indicates failure, and the value specifies the reason
for the failure.
ContextArea
four-byte field that may contain any value because it is not used by CLI or the
application program.
It is provided to maintain compatibility with calls on mainframe clients.
UserECB
four-byte field that may contain any value because it is not used by CLI or the
application program.
It is provided to maintain compatibility with calls on mainframe clients.
DBCHWAT
DBCHWAT waits for one or more requests to complete on the Teradata Database and the
response to arrive at the workstation, that is, it returns to the caller the session id and the
associated request Token (which was supplied by the application when the request was
initiated) of the first active request to complete.
DBCHWAT is intended primarily for the use of multi- session applications so that the
application can have several active requests on the Teradata Database simultaneously.
Note: Each session can only have one active request at a time on the Teradata Database.
DBCHWAT should not generally be used by multi-threaded applications. Nor should it be
used by single-threaded applications that employ more than one CLIv2-dependent
component within a given process. Because DBCHWAT causes the current unit of work to
block until *any* session within the process returns ready, it is possible for unpredictable
results to occur should a request initiated by one component signal completion while another
component is in control. To avoid this problem, such applications should instead use
DBCHWL exclusively.
What Event Means
DBCHWAT waits for an event to occur. Event refers to the arrival of some response from the
Teradata Database. If DBCHUEC has been invoked, event also refers to the occurrence of
some application-program-defined event.
240
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
Parameters
Int32 DBCHWAT (ReturnCode, ContextArea, sessid, token)
Int32
*ReturnCode;
char
*ContextArea;
Int32
*sessid;
Int32
*token;
where:
The parameter...
Is the...
ReturnCode
four-byte address of an area allocated by the application program for storage
of a four-byte signed integer.
After control returns from DBCHWAT, the integer contains a code whose
value represents success or failure.
• A return code of zero indicates success.
• A non-zero return code indicates failure, and the value specifies the reason
for the failure.
ContextArea
four-byte field which may contain any value, because it is not used by CLI or
the application program.
It is provided to maintain compatibility with calls on mainframe clients.
sessid (session)
four-byte address of an area allocated by the application for storage of a fourbyte signed integer.
After control returns from DBCHWAT, the integer contains the logical
session id of the first active request to complete.
token
four-byte address of an area allocated by the application for storage of a fourbyte signed integer.
After control returns from DBCHWAT, the integer contains the user-supplied
token, if there is one, that is associated with the first active request to
complete.
Usage Notes
If two requests post arrival of responses, the second notice does not overwrite the first. Each
call to DBCHWAT will obtain a notice of the arrival of a response until the list of postings is
empty.
Also, after the application is notified about the arrival of a response, DBCHWAT no longer
retains information about that posting. For example, if two requests complete and the
application calls DBCHWAT three times, on the third time DBCHWAT returns “nothing
pending”.
With the introduction of multi-threaded Windows CLI, DBCHWAT becomes limited in it's
applicability on Windows platforms for multi-threaded applications. A more applicable wait
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
241
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
function - DBCHWL will wait on a list of sessions for each thread, while DBCHWAT waits on
the next available request from ANY session.
Returns 0 if succeeds, else returns error.
DBCHWL
Description
Wait for completion of any active requests from the application or events associated with the
ContextArea.
A completed request will return the request token and the session id. A completed event will
return a value in ReturnCode indicating completion of the event.
Only those sessions defined in the supplied sessions list are considered eligible.
Parameters
Int32 DBCHWL (ReturnCode, ContextArea,sessions, sessid, reqtoken)
Int32 *ReturnCode;
char **ContextArea;
SESSIONS_PTR sessions
Int32 *sessid;
Int32 *reqtoken;
where:
The parameter...
Is the...
ReturnCode
Address of a four byte signed integer allocated by the application program.
After control returns from DBCHWL, the integer contains a code whose
value represents success or failure. A zero return value indicates success, while
a non-zero return code indicates the reason for failure.
If the sessions array is NULL, a NOSESSION error is returned. If the
ContextArea is not initialized correctly, a BADUECNTA error is returned. If
the user supplied event times out, an EM_TIMEEXCEEDED error is
returned.
ContextArea
Indirect pointer to a character pointer. DBCHUE initializes the ContextArea
and associates an event with this ContextArea.
If this parameter is non-null, DBCHWL will wait for completion of the
defined event or a completed request contained within the session list,
whichever completes first.
sessions
242
Array of SESSIONS_PTR, containing session ids in which the application is
interested on completion of requests. This user supplied array must contain a
NULL session array element terminating this array.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
The parameter...
Is the...
sessid (session)
Pointer to a four byte signed integer. After control returns successfully from
DBCHWL, sessid will contain the value of the session id of the completed
request.
reqtoken
Pointer to a four byte signed integer. After control returns successfully from
DBCHWL, reqtoken will contain the optionally supplied user token, that is
associated with the first active request to complete, from the user supplied
sessions list.
Usage Notes
DBCHWL must contain a NULL session in the terminating element of the SESSIONS_PTR
array.
DBCHWL waits for a request on a specified list of sessions or an event associated with a
ContextArea defined in DBCHUE.
Only CLI_WIN_TIMEOUT events are supported as event types in DBCHWL. The associated
return code from this event is EM_TIMEEXCEEDED.
This function supports multi-threaded CLI.
Example
Wait for requests from a single session for only 5 seconds.
/* supplied from a previous call to DBCHUE - char *cnta, which
contains a 5 second timeout event */
SESSIONS_PTR Sessions;
Int32 Active;
Int32 retcode = 0;
Int32 result = 0;
struct DBCAREA dbc;
/* allocate 2 session arrays and initialize arrays to 0's */
Sessions = (SESSIONS_PTR)calloc(2, sizeof(SESSIONS));
/* the dbcarea has been updated from the dbc.o_sess_id from
DBFCON CLI function */
/* first session is set, second session is NULL */
Sessions[0].session = dbc.i_sess_id;
retcode = DBCHWL(&result, (char **) &cnta, Sessions,
&Active,&dbc.token);
/* done with the event - delete the event and free memory */
retcode = DBCHUE(&result, (char **) &cnta, &time_event,
DELETE_EVENT);
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
243
Chapter 8: Other CLI Routines
Parameters of CLI Routines: Tabular Summary
244
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 9
Parcels
This chapter describes:
•
The structure of a parcel
See Chapter 14: “Alternate Parcel Header” for the redefined parcel structure by alternate
parcel headers.
•
The two parcel types: request and response
See Chapter 17: “Large Objects (LOB) Support” for LOB parcels.
•
Individual parcels in alphabetical order
Structure
A parcel is a discrete logical unit of information. It consists of two parts:
•
The parcel header
•
The parcel body
Parcel Structure
There are two parcel header formats:
•
Standard Parcel Header (SPH)
•
Alternate Parcel Header (APH)
The maximum length of an SPH parcel is 65,535 bytes; the maximum length of an APH parcel
is ~1 MB.
Note: A parcel using the APH will be 4-bytes larger than a parcel using the SPH.
The format of the SPH shown in Figure 4.
Figure 4: SPH Parcel Format
Flavor
0
Body
Length
1 2
3 4
65535
maximum
2418A006
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
245
Chapter 9: Parcels
Structure
Note: A maximum parcel body size of 65,104 bytes is only approached with the Archive/
Recovery utility. The maximum size of a regular SQL parcel body is 64,260 bytes, including
overhead such a presence bits and variable length columns.
The format of the APH is shown in Figure 5.
Figure 5: APH Parcel Format
Flavor
0
1 2
Body
Length
Unused
3 4
7 8
~1 MB
2418A007
The two types of parcel headers may be intermixed in the same request or response. Parcels
whose length is less than or equal to 65,535 may use either header format.
Note: A response will only contain a parcel using APH if the APH-response-permitted option
was specified and the Teradata Database supports the alternate header for that parcel.
Note: dbcarea.consider_APH_resps must be set to ‘Y’ to receive APH responses.
Flavor Field
The Flavor field indicates the parcel type and differentiates the format of the two parcel
headers. If the leftmost bit is zero, the SPH format will be used. If the leftmost bit is one, the
APH format is used.
The remaining fifteen bits identify the parcel flavor. Table 13 lists parcels by flavor number.
Table 13: Parcel Flavors
246
Flavor
Name
1
Req parcel
2
RunStartup parcel
3
Data parcel
4
Resp parcel
5
KeepResp parcel
6
Abort parcel
7
Cancel parcel
8
Success parcel
9
Failure parcel
10
Record parcel
11
EndStatement parcel
12
EndRequest parcel
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Structure
Table 13: Parcel Flavors (continued)
Flavor
Name
13
FMReq parcel
14
FMRunStartup parcel
17
Ok parcel
18
Field parcel
19
NullField parcel
20
TitleStart parcel
21
TitleEnd parcel
22
FormatStart parcel
23
FormatEnd parcel
24
SizeStart parcel
25
SizeEnd parcel
26
Size parcel
27
RecStart parcel
28
RecEnd parcel
31
Rewind parcel
32
NOP parcel
33
With parcel
34
Position parcel
35
EndWith parcel
36
Logon parcel
37
Logoff parcel
38
Run parcel
40
UCABORT
42
Config parcel
43
Config Rsp parcel
46
PosStart parcel
47
PosEnd parcel
49
Error parcel
68
IndicData parcel
69
IndicReq parcel
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
247
Chapter 9: Parcels
Structure
Table 13: Parcel Flavors (continued)
248
Flavor
Name
71
DataInfo parcel
72
IVRunStartup parcel
85
Options parcel
86
PrepInfo parcel
88
Connect parcel
100
Assign parcel
101
AssignRsp parcel
106
SesInfo parcel
107
SesInfoRsp parcel
114
Session Options parcel
120
CursorHost
121
CursorDBC
122
Flagger
123
XindicReq
125
PrepInfoX
128
Multi-TSR
129
SP Options
130
SSOAUTHREQ
131
SSOAUTHRESP
132
SSOREQ
133
SSODOMAIN
134
SSORESP
135
SSOAUTHINFO
136
USERNAMEREQ
137
USERNAMERESP
140
MultipartData
141
EndMultipartData
142
MultipartIndicData
143
EndMultipartIndicData
144
MultipartRecord
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Types
Table 13: Parcel Flavors (continued)
Flavor
Name
145
EndMultipartRecord
146
DataInfox
147
MultiPartRunStartup
148
MultiPartRequest
150
ElicitData
151
ElicitFile
152
ElicitDataReceived
153
BIGRESP
154
BIGKEEPRESP
157
SETPOSITION
158
ROWPOSITION
159
OFFSETPOSITION
164
ErrorInformation
169
StatementInformation
170
StatementInformationEnd
172
ResultSet
Length Field
The Length field contains the length in bytes of the entire parcel, which is the total length of
the Flavor, Length, and Body fields.
When CLIv2 constructs parcels, it builds an appropriate parcel header, based on the
DBCAREA Function and length of the relevant data. When CLIv2 returns the parcel body, it
adjusts the length returned for the removal of the parcel header.
Parcel Body
The parcel body consists of zero or more fields. The number of fields, their names, contents,
and lengths depends on the parcel flavor.
Parcel Types
There are two parcel types:
•
Request parcels
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
249
Chapter 9: Parcels
Parcel Types
Request parcels are sent from the client to the Teradata Database.
•
Response parcels
Response parcels are generated for responses and are sent from the Teradata Database to a
client.
Request Parcels: Overview
The application program arranges for request parcels to be generated but does not view them
directly if the Request Mode is Parcel Mode and a DBCAREAX is not being used. If a
DBCAREAX is being used, then the application builds parcels directly in the DBCAREAX.
If Request Mode is Buffer Mode, then parcels are built directly in the Request buffer.
Table 14 lists, in numerical order, the request parcels.
Table 14: Request Parcels
250
Parcel
Flavor
Parcel Name
Parcel Use
Parcel
Length
Fields in Parcel Body
1
Req
Initiates a request
5-12504
ReqText
2
RunStartup
Executes the user’s startup
request
4
None
3
Data
Contains data for a Teradata
SQL request
5-32004/
65104
Data
4
Resp
Request portion of Teradata SQL 6
response
MaxMsgSize
5
KeepResp
Requests a portion of Teradata
SQL response without
discarding response
6
MaxMsgSize
6
Abort
Attempts to abort a request
4
None
7
Cancel
Discards Teradata SQL response 4
and closes Teradata SQL request;
discards those segments of a
segmented data request that
have already been sent.
None
13
FMReq
Initiates a request
5-12504
ReqText
14
FMRunStartup
Executes the user’s startup
request
4
None
31
Rewind
Positions spool file pointer to
beginning of the spool file
4
None
36
Logon
Establishes a session
132
LogonString
37
Logoff
Terminates a session
4
None
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Types
Table 14: Request Parcels (continued)
Parcel
Flavor
Parcel Name
Parcel Use
Parcel
Length
Fields in Parcel Body
38
Run
Connects to specified server on
the COP for network-attached
clients or to the specified IFP
partition for channel- attached
systems
20
PartitionName
42
Config
68
IndicData
Contains data for a Teradata
SQL request
6-32004/
65104
NullIndic Data
69
IndicReq
Initiates a request
5-12504
ReqText
71
DataInfo
Sends description of whichever
data parcel follows it
6-32004/
65104
FieldCount Groups:
Length
Type
72
IVRunStartup
Executes the user’s startup
request
4
None
85
Options
Specified which PREPARE
options are used when a request
is sent to the Teradata Database
14
RequestMode
DBCFunction
RFU[0] - RFU[5]
88
Connect
Connects to specified server on
the COP for network-attached
systems
28
PartitionName
LogonSequenceNum
ber
Functions
100
Assign
Request a session COP
36
UserName
106
SesInfo
114
SessionOptions Session options
14
Semantics
Mode
Conformance
DateForm
120
CursorHost
18
Processor
Row
Request
123
Xindicreq
1 to 8196
Reqtxt
125
PrepInfoX
1 to
Maximum
parcel size
CostEstimate
SummaryCount
ColumnCount
DataType
DataLen
ColumnCharSetCode
ColumnExtInfo
ColumnName
ColumnFormat
ColumnTitle
Provides cursor information.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
251
Chapter 9: Parcels
Parcel Types
Table 14: Request Parcels (continued)
Parcel
Flavor
Parcel Name
Parcel Use
Parcel
Length
128
Multi-TSR
Segments special-purpose
requests into multiple parcels
7
Sequence number
IsLast
129
SP Options
Provides options for creation of
a Stored Procedure.
6
Print Option
SPL Option
140
Multipart
Record
2 to 32000
Data
141
End Multipart
Record
2
None
142
Multipart
IndicData
2 to 32000
Data
143
EndMultipart
Indicdata
2
None
146
DataInfoX
6 to 32004
FieldCount
Datatype, Length
pairs
148
MultiPart
Request
1 to
Maximum
parcel size
Request Text
Fields in Parcel Body
Response Parcels: Overview
These parcels are generated by the Teradata Database. The application program can see all of
them directly.
Table 15 lists, in numerical order, the response parcels.
Table 15: Response Parcels
Parcel
Flavor
Parcel Name
Parcel Use
8
Success
Indicates that the specified
Teradata SQL statement
completed successfully
Parcel
Length
Fields in Parcel
Body
18-273
StatementNo
ActivityCount
WarningCode
FieldCount
ActivityType
WarningLength
WarningMsg
252
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Types
Table 15: Response Parcels (continued)
Parcel
Flavor
Parcel Name
Parcel Use
9
Failure
Indicates that the specified
statement has a failed and the
entire transaction was rolled
back
Parcel
Length
Fields in Parcel
Body
13-267
StatementNo
Info
Code
Length
Msg
InsCount
InsTriad
10
Record
Returns one row of selected
results
5-32004/
65104
Data
11
EndStatement
Delimits the end of the results
from the specified Teradata SQL
statement
6
StatementNo
12
EndRequest
Delimits the end of a Teradata
SQL response to a DBC/SQL
request
4
None
17
Ok
Indicates that the specified
Teradata SQL statement
completed successfully
18-273
StatementNo
FieldCount
ActivityCount
ActivityType
WarningCode
WarningLength
WarningMsg
18
Field
Contains returned information
(data value, title, format, or
echo)
4-32004/
65104
Data
19
NullField
Returns a null data value for a
field
4
None
20
TitleStart
Delimits the start of a set of
format- containing Field parcels
4
None
21
TitleEnd
Delimits the end of a set of
format-containing Field parcels
4
None
22
FormatStart
Delimits the start of a set of
format- containing Field parcels
4
None
23
FormatEnd
Delimits the end of a set of
format- containing Field parcels
4
None
24
SizeStart
Delimits the start of a set of Size
parcels
4
None
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
253
Chapter 9: Parcels
Parcel Types
Table 15: Response Parcels (continued)
Parcel
Flavor
Parcel Name
Parcel Use
Parcel
Length
Fields in Parcel
Body
25
SizeEnd
Delimits the end of a set of Size
parcels
4
None
26
Size
Specified the width of a column
of selected results
4
MaxFldSize
27
RecStart
Delimits the start of a set of
data-value containing Field and
Null-Field parcels or a set of
echoed string- containing Field
parcels
4
None
28
RecEnd
Delimits the end of a set of data- 4
value containing Field and NullField parcels or a set of echoed
string- containing Field parcels
None
32
NOP
Sends test messages to make sure 4
the connection is still alive.
None
33
With
Delimits the start of a set of
parcels for the specified WITH
clause
6
WithId
34
Position
Specifies the column number
being summarized
6
ColumnNo
35
EndWith
Delimits the end of a set of
parcels for the specified WITH
clause
6
WithId
46
PosStart
Delimits the start of a set of
Position parcels
3
None
47
PosEnd
Delimits the end of a set Position 4
parcels
None
49
Error
13-267
Indicates that the specified
statement has an error not
serious enough to cause rollback
StatementNo
Info
Code
Length
Msg
InsCount
InsTriad
71
DataInfo
Returns a description of the
following Indicator Mode
Record parcels
6-32004/
65104
FieldCount Pairs:
Length
Type
254
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Common Parcel Fields
Table 15: Response Parcels (continued)
Parcel
Flavor
Parcel Name
Parcel Use
Parcel
Length
Fields in Parcel
Body
86
PrepInfo
Returns column information to
the Teradata Database when a
Teradata SQL statement has
been prepared using the Request
Processing Option.
16 to 32004/
65104
None
101
AssignRsp
Assigns a session COP by
returning the information
needed for the workstation to
connect to the Teradata
Database.
76
PublicKey
SesCOPAddr
PublicKeyN
RelArray
VerArray
HostId
121
CursorDBC
Returns cursor information.
14
Processor
Row
122
Flagger
Returns language
nonconformances.
164
ErrorInformation After an Error parcel (flavor 49),
provides additional information
about the error.
10 to 32004/
65104
Flags
1 to
maximum
parcel size
InformationID
Information
Length
Information
169
StatementInform
ation
6 to
Returns a description of the
maximum
data, when Returnstatement_info ‘Y’ was returned. parcel size
PBTILOUT
PBTIID
PBTILEN
170
StatementInform
ationEnd
Delimits related
StatementInformation parcels.
0
none
172
ResultSet
Introduce parcels returned from
a CALLed stored procedure.
12
PBRTRNUM
PBRTDB
PBRTPN
Common Parcel Fields
Two fields occur in multiple parcels and have a large number of possible values: Data Type and
Activity Type.
Data Type
The Data Type field specifies the type of data contained in a database column.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
255
Chapter 9: Parcels
Common Parcel Fields
Table 16: Data Type Values
Name
Type if
non-nullable
Type if
Nullable
Type if IN
parameter
Type if INOUT
parameter
Type if OUT
parameter
BLOB
400
401
900
901
902
BLOB AS DEFERRED
404
405
904
905
906
BLOB AS LOCATOR
408
409
908
909
910
CLOB
416
417
916
917
918
CLOB AS DEFERRED
420
421
920
921
922
CLOB AS LOCATOR
424
425
924
925
926
UDT
432
433
932
933
934
Distinct UDT
436
437
936
937
938
Structure UDT
440
441
940
941
942
VARCHAR
448
449
948
949
950
CHAR
452
453
952
953
954
LONGVARCHAR
456
457
956
957
958
VARGRAPHIC
464
465
964
965
966
GRAPHIC
468
469
968
969
970
LONGVARGRAPHIC
472
473
972
973
974
FLOAT
480
481
980
981
982
DECIMAL
484
485
984
985
986
INTEGER
496
497
996
997
998
SMALLINT
500
501
1000
1001
1002
BIGINT
600
601
1100
1101
1102
VARBYTE
688
689
1188
1189
1190
BYTE
692
693
1192
1193
1194
LONGVARBYTE
696
697
1196
1197
1198
DATE with DBCAREA
Date-format 'A'
748
749
1248
1249
1250
DATE with DBCAREA
Date-format 'T'
752
753
1252
1253
1254
BYTEINT
756
757
1256
1257
1258
The several values for each type are algorithmically related to the non-nullable value: the
nullable value is one greater; the IN parameter value is 500 greater; the INOUT parameter
256
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Common Parcel Fields
value is 501 greater; and the OUT parameter value is 502 greater. Note that the three
parameter values do not differentiate non-nullable from nullable.
Non-nullable refers to columns defined NOT NULLS.
IN, INOUT, and OUT refer to attributes for parameters on an SQL CALL statement.
The temporal data types are given for “StatementInformation” on page 320. When used
elsewhere, these types are all indicated as the CHAR data type.
Activity Type
The Activity Type field indicates the type of processing performed for the request.
Table 17: Activity Codes
Value
Statement
Value
Statement
Value
Statement
0
Not available
1
SQL SELECT
2
SQL INSERT
3
SQL UPDATE
4
UPDATE...
RETRIEVING
5
SQL DELETE
6
SQL CREATE
TABLE
7
SQL ALTER TABLE
8
SQL CREATE
VIEW
9
SQL CREATE
MACRO
10
SQL DROP TABLE
11
SQL DROP VIEW
12
SQL DROP
MACRO
13
SQL DROP INDEX
14
SQL RENAME
TABLE
15
SQL RENAME
VIEW
16
SQL RENAME
MACRO
17
SQL CREATE
INDEX
18
SQL CREATE
DATABASE
19
SQL CREATE USER
20
SQL GRANT
21
SQL REVOKE
22
Give
23
SQL DROP
DATABASE
24
SQL MODIFY
DATABASE
25
SQL DATABASE
26
SQL BEGIN
TRANSACTION
27
SQL END
TRANSACTION
28
SQL ABORT
29
Null
30
SQL EXECUTE
31
SQL COMMENT SET
32
SQL COMMENT
33
SQL ECHO
34
Replace View
35
Replace Macro
36
SQL
CHECKPOINT
37
Delete Journal
38
SQL ROLLBACK
39
Release Lock
40
HUT Config
41
VerifyCheckpoint
42
Dump Journal
43
Dump
44
Restore
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
257
Chapter 9: Parcels
Common Parcel Fields
Table 17: Activity Codes (continued)
258
Value
Statement
Value
Statement
Value
Statement
45
RollForward
46
SQL Delete Database
47
Internal use only
(for crash dumps)
48
Internal use only
(for crash dumps)
49
SQL Show
50
SQL Help
51
Begin Loading
52
Check Point Load
53
End Loading
54
Insert
56
Revoke Logon
57
Begin Access Log
58
End Access Log
59
Collect Statistics
60
Drop Statistics
61
Session Set
62
Begin Multiload
63
Multiload
64
Execute Multiload
65
End Multiload
66
Release Multiload
67
Multiload Delete
68
Multiload Insert
69
Multiload Update
70
Begin Delete
Multiload
71
Data Status
72
Reserved for B1
security
73
Reserved for B1
security
74
Begin Export
75
End Export
76
2PC Vote Request
77
2PC Vote and
Terminate Request
78
2PC Commit
79
2PC Abort
80
2PC Yes/Done
Response to Vote
Request
81
Obsolete
82
Obsolete
83
Set Session Rate
84
Monitor Session
85
Identify
86
Abort Session
87
Set Resource Rate
88
Obsolete
89
Revalidate RI
references
90
ANSI SQL COMMIT
WORK
91
Monitor Virtual
Config
92
Monitor Physical
Config
93
Monitor Virtual
Summary
94
Monitor Physical
Summary
95
Monitor Virtual
Resource
96
Monitor Physical
Resource
97
SQL CREATE
TRIGGER
98
SQL DROP
TRIGGER
99
SQL RENAME
TRIGGER
100
Replace Trigger
101
SQL ALTER
TRIGGER
103
Drop Procedure
104
Create Procedure
105
Call
106
SQL RENAME
PROCEDURE
107
Replace Procedure
109
Locking logger
110
Monitor Session
111
Monitor Version
112
Begin Database Query
Log
113
End Database Query
Log
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Table 17: Activity Codes (continued)
Value
Statement
Value
Statement
Value
Statement
114
SQL Create Role
115
SQL DROP ROLE
116
Grant Role
117
Revoke Role
118
SQL Create Profile
119
SQL Modify Profile
120
SQL Drop Profile
121
SQL SET ROLE
122
Create UDF
123
Replace UDF
124
Drop UDF
125
Alter UDF
126
Rename UDF
127
SQL MERGE INTO,
updates, no inserts
128
SQL MERGE INTO,
all inserts, no
updates
129
SQL MERGE INTO,
updates and inserts
130
SQL ALTER
PROCEDURE
131
PM/API request
TDWM ENABLE
132
PM/API request
TDWM
STATISTICS
133
TDWM Perf Groups
134
Create UDT
135
Drop UDT
136
Alter UDT
138
SQL CREATE
METHOD
139
Alter Method
140
Replace Method
141
Create Cast
142
Replace Cast
143
Drop Cast
144
SQL CREATE
ORDERING
145
Replace Ordering
146
Drop Ordering
147
SQL CREATE
TRANSFORM
148
Replace Transform
149
SQL DROP
TRANSFORM
Parcel Descriptions
The sections that follow describe, in alphabetical order, the parcels generated by client
applications and the Teradata Database.
Abort
Purpose
The Abort parcel terminates processing of a specific request. It is created by CLIv2 in response
to an abort request or to a logoff of a session in which a request is active.
Usage Note
The Abort parcel is sent in a simplex request asynchronously with the start request carrying
the Teradata SQL request to be aborted. If the Teradata Database is processing the specified
request, the request is aborted and the Failure parcel is returned. If the request had been
completed upon receipt of the abort, the abort is ignored.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
259
Chapter 9: Parcels
Parcel Descriptions
Parcel Data
The following table lists field information for the Abort parcel.
Flavor Field
Body Parcel
Length
Parcel Body Fields
6
0
none
Abrt2PC
Purpose
Aborts the current transaction for a 2PC session. CLIv2 creates this parcel at the direction of
the coordinator. The parcel can be submitted whenever there is an open transaction.
Usage Notes
Use of this parcel requires Teradata Database for UNIX version 2 release 2 (or later), or
Teradata DBS for TOS version 1 release 5 (or later).
The successful response is a Failure parcel.
If...
Then...
there is no open transaction
an Error parcel is returned.
the session is not in 2PC mode
a Failure parcel is returned.
Parcel Data
The following table lists field information for Abrt2PC Parcel.
Flavor
Parcel
Body
Length
Parcel Body Fields
118
0
none
Assign
Purpose
The Assign parcel requests a session COP be assigned for a workstation user attempting to log
onto the Teradata Database over the network.
Usage Notes
This parcel is generated by CLI at the direction of the application.
260
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Parcel Data
The following table lists field information for the Assign parcel.
Flavor Field
Body Parcel
Length
Parcel Body Fields
100
36
User Name:
32 bytes
Fields
User Name is the same as the Userid in the logon string. The Userid is to be no longer than 30
bytes; MTDP will right pad from the actual length of the Userid to 32 bytes.
AssignRsp
Purpose
The AssignRsp parcel returns the response to a message containing an Assign parcel.
Usage Notes
This parcel is generated by the Teradata Database.
Parcel Data
The following table lists field information for the AssignRsp parcel.
Flavor Field
Body Parcel
Length
101
98
Parcel Body Fields
PublicKey:
8 bytes
SesCOPAddr:
32 bytes
PublicKeyN:
32 bytes
RelArray:
6 bytes
VerArray:
14 bytes
HostId:
2 bytes
Fields
CLI does not check PublicKey and PublicKeyN, two parts of an encryption key used to encrypt
the connect and reconnect request messages, where PublicKey is the exponent portion of the
Public Key and PublicKeyN is the modulus portion.
SesCOPAddr is the address or name that the work station must use to connect to the session
COP. The format of this field depends on the network software running on the workstation.
The workstation defines the format by the flag NetAddrType in the Assign parcel.
RelArray contains the release number associated with the software.
VerArray contains the version number associated with the Teradata Database software.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
261
Chapter 9: Parcels
Parcel Descriptions
HostID contains a session’s logical host id, as an unsigned binary, in the least significant 10
bits. Hostid is specific to a given run of the Reconfig utility, since Config and Reconfig are used
to specify host id.
Cancel
Purpose
Either terminates Teradata Database output for the request, or cancels segments of request
data previously sent.
Usage Notes
The parcel is generated by CLIv2 at the direction of the application.
When used to terminate Teradata Database output, this parcel deletes spool files that contain
the results of a Teradata request. The response is an End Request parcel.
When used to cancel segments of a request, this parcel deletes segments that were previously
received by the Teradata Database. The response is a Failure parcel.
Parcel Data
The following table lists field information for the Cancel parcel.
Flavor Field
Body Parcel
Length
Parcel Body Fields
7
0
none
Cmmt2PC
Purpose
Commits the current in-doubt transaction for a 2PC session.
Usage Notes
Use of this parcel requires Teradata Database for UNIX version 2 release 2 (or later), or
Teradata DBS for TOS version 1 release 5 (or later).
CLIv2 creates this parcel at the direction of the coordinator.
The Cmmt2PC parcel should be submitted after a success response has been returned for a
vote request parcel.
262
If...
then...
there is no transaction open for the session
an Error parcel is returned.
the current transaction is not in-doubt or not
even in 2PC mode to begin with
a Failure parcel is returned.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
If...
then...
anything else
a Success parcel is returned.
Parcel Data
The following table lists field information for Cmmt2PC.
Flavor Field
Body Parcel
Length
Parcel Body Fields
117
0
none
Connect
Purpose
Establishes a connection between an application and a specific COP server that is used for
running Teradata SQL.
Usage Notes
The Connect parcel is sent from the client at the same time that a Logon parcel is sent.
This parcel is generated by CLIv2 on behalf of the application.
The response to a Connect parcel is first a Success parcel and then a RunResponse parcel.
Parcel Data
The following table lists field information for the Connect parcel.
Flavor
Field
Body
Parcel
Length
88
24
Parcel Body Fields
PartitionName:
16 bytes
LogonSequence Number:
4 bytes
Function:
2 bytes
Pad:
2 bytes
Fields
•
PartitionName is the name of the COP server to which start requests are to be sent.
•
LogonSequenceNumber contains a logon sequence number when Function contains the
value 2. At all other times it must contain zero.
•
Function contains one of the following:
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
263
Chapter 9: Parcels
Parcel Descriptions
•
Function Number
Description
0
Requests that a normal Run be performed.
1
Requests session control allocate a logon sequence number and associate the
newly allocated logon sequence number with the requesting session.
2
Requests session control to associate the logon sequence number in logon
sequence number with requesting session.
Pad is unused.
CursorDBC
Purpose
The CursorDBC parcel returns to the application a cursor row identifier to after a SELECT
FOR CURSOR statement.
Usage Notes
The information returned is meaningful only for use in a subsequent CursorHost parcel.
The CursorDBC parcel is generated by the Teradata Database.
Parcel Data
The following table lists field information for the CursorDBC parcel.
Flavor
Field
Parcel
Body
Length
121
10
Parcel Body Fields
Processor:
2 bytes
Row:
8 bytes
Fields
Processor identifies the location of the row.
Row identifies the row associated with the cursor.
CursorHost
Purpose
The CursorHost parcel returns to the server a cursor row identifier and request number that
returned the CursorDBC parcel.
Usage Notes
This parcel is generated by the application.
264
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Parcel Data
The following table lists field information for CursorHost parcel.
Flavor
Field
Parcel
Body
Length
120
14
Parcel Body Fields
Processor:
2 bytes
Row:
8 bytes
Request
4 bytes
Fields
Processor identifies the location of the row.
Row identifies the row associated with the cursor.
Request specifies the request number associated with the CursorDBC parcel from which the
processor and row were obtained.
Data
Purpose
The Data parcel sends data in Record Mode to the Teradata Database. The Data parcel follows
either a Req, IndicReq, or FMReq parcel that contains a USING modifier.
Usage Notes
This parcel is generated by CLI at the direction of the application.
Parcel Data
The following table lists field information for the Data parcel.
Flavor
Field
3
Parcel Body Length
Parcel Body Fields
1 to maximum
body size
Data: 1 to maximum body size bytes
Note: A maximum parcel body size of 65024 bytes is only approached with the Archive/
Recovery utility. The maximum size of a regular SQL parcel body is 64256 bytes, including
overhead such a presence bits and variable length columns.
Fields
The Data field contains a formatted record of data.
•
The order of the items and their data types and lengths are determined by the USING
modifier in the Teradata SQL statement.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
265
Chapter 9: Parcels
Parcel Descriptions
•
The values of the items are represented in a client internal format for details. For details,
see “Record” on page 303.
•
A null value is implicitly indicated by a specific value of the item and that value is not
necessarily unique to null. For explicit, unique indications of null values, use Indicator
Mode or Field Mode.
DataInfo
Purpose
Returns a description of the items within the Data Field of the corresponding Indicator Mode
Record parcels.
Usage Notes
DataInfo parcel is not returned if the statement was an ECHO statement. This parcel is
generated by Teradata Database.
Parcel Data
Flavor
71
Parcel Body
Length
6 to
maximum
body size
Parcel Body Fields
2 bytes
FieldCount:
Pair 1:
Data Type:
2 bytes
Length:
2 bytes
Data Type:
2 bytes
Length:
2 bytes
Data Type:
2 bytes
Length:
2 bytes
.
.
.
Pair i:
.
.
.
Pair n:
Field Notes
The following notes apply to the fields for the DataInfo parcel.
266
•
The FieldCount, n, is the number of items within the Data Field in the corresponding
Indicator Mode Record parcels. It also is the number of data type and length pairs in this
DataInfo parcel.
•
The Pair fields contains a description of the data type and length of the corresponding data
item of the record parcel. That is, the ith pair of data type and length values in the
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
DataInfo parcel corresponds to the ith data item in the Data Field of the Indicator Mode
Record parcel. See Table 16 on page 256 for available data types.
•
If the data type of the ith data item is not decimal, then the length (maximum length
for VARBYTE and VARCHAR) of the ith data item in the Indicator Mode Record
parcel is represented in the DataInfo parcel as a 16-bit signed binary.
•
If the data type of the ith data item is decimal, then the total number of digits in the ith
data item in the Indicator Mode Record parcel is represented in the DataInfo parcel in
the first byte of the parcel body length as an 8-bit signed binary, and the number of
fractional digits is represented in the second byte of the parcel body length as an 8-bit
signed binary.
DataInfoX
Purpose
For MultipartIndicator mode responses, describes the data contained in subsequent
MultipartRecord parcels.
Usage Notes
DataInfoX is not returned if the statement was ECHO.
Parcel Data
The following table lists field information for DataInfoX.
Flavor
146
Parcel Body
Length
6 to maximum
body size
Parcel Body Fields
2 bytes
FieldCount:
Pair 1:
Data Type:
2 bytes
Length:
8 bytes
Data Type:
2 bytes
Length:
8 bytes
Data Type:
2 bytes
Length:
8 bytes
.
.
.
Pair i:
.
.
.
Pair n:
Field Notes
The following notes apply to the Fields for the DataInfoX parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
267
Chapter 9: Parcels
Parcel Descriptions
•
The FieldCount, n, is the number of items within the Data Field in the corresponding
MultipartRecord parcels. It also is the number of data type and length pairs in this
DataInfoX parcel.
•
The Pair fields contains a description of the data type and length of the corresponding data
item of the multipartrecord parcel. That is, the ith pair of data type and length values in
the DataInfoX parcel corresponds to the ith data item in the Data Field of the
Multipartrecord parcel. For the possible data types, see Table 16 on page 256.
•
If the data type of the ith data item is not decimal, then the length (maximum length
for VARBYTE and VARCHAR) of the ith data item in the Multipartrecord parcel is
represented in the DataInfoX parcel as a 64bit unsigned binary.
•
If the data type of the ith data item is decimal, then the total number of digits in the ith
data item in the Multipartrecord parcel is represented in the DataInfoX parcel in the
first 4 bytes of the parcel body length as a signed binary, and the number of fractional
digits is represented in the second 4 bytes of the parcel body length as a signed binary.
ElicitData
Purpose
For MultipartIndicator mode responses, elicits a deferred MultipartIndicator response mode
large object.
Parcel Data
Flavor
Parcel Body
Length
Parcel Body Fields
150
4
Token: 4 byte
Token is a number indicating the Large Object being elicited. The first Large Object referenced
by the SQL request would have a token of 1, with subsequent Large Objects' token each being
incremented by one.
ElicitDataReceived
Purpose
For MultipartIndicator mode responses, indicates that an elicited data or file was successfully
received.
Parcel Data
268
Flavor
Parcel Body
Length
Parcel Body Fields
152
0
None
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
ElicitFile
Purpose
For MultipartIndicator mode responses, elicits a User Defined Function.
Parcel Data
The following table lists field information for ElicitFile.
Flavor
151
Parcel Body
Length
6 to maximum
body size
Parcel Body Fields
SourceLanguage: 1 byte
FileType: 1-byte unsigned integer
FileSupplied: 1 byte
Pad Byte: 1 byte
FilenameLength: 2-byte unsigned integer
Filename: variable number of characters
Usage Notes
SourceLanguage identifies the language in which the User Defined Function is programmed,
as one of the following:
0 = Not supplied
1=C
2 = C++
3 = Java
FileType identifies the type of file, chosen as one of the following:
0 = Not supplied
1 = A source file
2 = An included file
3 = An object file
FileSupplied identifies what name was supplied for the file, chosen as one of the following
•
0 = Name without location
•
1 = Name and location
•
A pad byte (a single, unused byte)
FilenameLength specifies the length, in bytes, of the filename.
Filename specifies the name of the file in characters of the session character set.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
269
Chapter 9: Parcels
Parcel Descriptions
EndMultipartData
Purpose
For MultipartIndicator mode requests when Use-presence was not requested, delimits data
associated with the SQL USING row descriptor.
Parcel Data
The following table lists field information for EndMultipartData.
Flavor
Parcel Body
Length
Parcel Body Fields
141
0
none
EndMultipartIndicData
Purpose
For MultipartIndicator mode requests when Use-presence was requested, delimits data
associated with the SQL USING row descriptor.
Parcel Data
The following table lists field information for EndMultipartIndicData.
Flavor
Parcel Body
Length
Parcel Body Fields
143
0
none
EndMultipartRecord
Purpose
For MultipartIndicator mode responses, delimits one row or selected results.
Usage Notes
The following table lists field information for EndMultipartRecord.
270
Flavor
Parcel Body
Length
Parcel Body Fields
145
0
None
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
EndRequest
Purpose
Delimits the end of a Teradata SQL response.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following table lists field information for EndRequest.
Flavor
Parcel Body
Length
Parcel Body Fields
12
0
none
EndStatement
Purpose
Delimits the end of the results of a Teradata SQL statement.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following table lists field information for EndStatement.
Flavor
Parcel Body
Length
Parcel Body Fields
11
2
StatementNo: 2 byte unsigned integer
Field Notes
The following notes apply to the fields for EndRequest.
•
StatementNo is the number of the Teradata SQL statement for which this is the last parcel
in a response.
•
Teradata SQL statements in a multi-statement Teradata SQL request are numbered 1
through n.
EndWith
Purpose
Delimits the end of a sequence of parcels that provides descriptors for, or the results of, a
summary generated by a WITH clause.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
271
Chapter 9: Parcels
Parcel Descriptions
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following table lists field information for EndWith.
Flavor
Parcel Body
Length
Parcel Body Fields
35
2
WithId: 2 byte unsigned integer
Field Notes
WithId is the summary number (1-n) for this End With clause.
Error
Purpose
Returned in response to a request that resulted in a non-database-related error.
Usage Notes
If the request is in a transaction, then the transaction is not aborted.
The invalid request can be corrected and resubmitted.
For example, the Error parcel might inform an application that the byte count in the Resp or
KeepResp parcel is too small to contain a parcel (error code 3116); in this case, the application
should reallocate the input (response) buffer, rebuild and resubmit the request.
This parcel is generated by the Teradata server.
Parcel Data
The following table lists field information for Error.
Flavor
Parcel Body
Length
Parcel Body Fields
49
8 to 263
StatementNo:
2 byte unsigned integer
Info:
2 byte unsigned integer
Code:
2 byte unsigned integer
Length:
2 byte unsigned integer
Msg:
1 to 255 bytes
Field Notes
Error Parcel field definitions are:
272
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
•
StatementNo is the number of the Teradata SQL statement in the Teradata SQL request
that failed.
•
Info is an integer value whose use depends upon the error code returned. For its contents,
look up the error code in the Messages manual.
•
Code is the error code specifying the type of error that occurred.
•
Length is the total number of bytes in the textual representation of the error code. If
Length = 0, no textual representation of the error is present.
Note: Msg is the error message in character format.
ErrorInformation
Purpose
After an Error parcel (flavor 49), provides additional information about the error.
Usage Notes
This parcel may follow an Error parcel to further describe the error. If the Error-code is 3177,
ErrorInformation indicates the minimum response buffer size. Normally this is handled
internally by CLIv2 and will not be returned to the application. But if the server requires a
response buffer larger than 65535 bytes but Maximum-parcel is not set to H, the Error and
ErrorInformation parcels will be returned.
This parcel is generated by the Teradata server.
Parcel Data
The following table lists field information for Error.
Flavor
9
Parcel Body
Length
1 to
maximum
parcel size
Parcel Body Fields
InformationId:
2 byte unsigned integer
InformationLength:
2 byte unsigned integer
Information:
Variable length
Field Notes
The parcel body consists of one or more information entries, each of which consists of:
•
InformationId indicates the type of information entry, as one of the following:
1 - Minimum Response Buffer Size
•
Information Length indicates the length of the following information.
•
Information depends upon the value of the InformationId field. For 1, a four byte integer
specifying the minimum size of the response buffer for this request required by the server.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
273
Chapter 9: Parcels
Parcel Descriptions
ExtendedKeepRespond
Purpose
Conveys the current length of the input (response) buffer.
Usage Notes
The ExtendedKeepResponse parcel requests as many response parcels as will fit in the
specified MaxMsgSize.
If the ExtendedKeepResponse parcel is used in a start request or continue request and the start
response or continue response contains the EndRequest parcel, the spool file is retained on the
Teradata Database.
In general, the spool file is deleted in any of the following situations:
•
A Cancel parcel is issued
•
The EndRequest parcel is returned in response to a continue request that contained a
Response parcel
•
An abort operation occurs
•
A logoff operation occurs
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the ExtendedKeepResponse parcel.
Flavor
Parcel
Body
Length
Parcel Body Fields
154
4
MaxMsgSize: 4 byte unsigned integer
Field Notes
MaxMsgSize is the maximum number of bytes that can be returned to the client in one
response. The minimum allowable buffer size is 256 bytes, hence MaxMsgSize must be greater
than or equal to 256. The maximum value is 4294967295.
ExtendedRespond
Purpose
Requests response data from the Teradata Database. Typically, it carries the current length of
the input (response) buffer.
Usage Notes
When the last record from a spool file is sent in response to a start or continue request
containing a Respond parcel, the spool file is deleted.
274
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the Respond parcel.
Flavor
Parcel
Body
Length
Parcel Body Fields
153
4
MaxMsgSize: 4 byte unsigned integer
Field Notes
MaxMsgSize is the maximum number of bytes that can be returned to the client in one
response. The minimum allowable buffer size is 256 bytes, hence MaxMsgSize must be greater
than or equal to 256. The maximum value is 4294967295.
Failure
Purpose
Indicates that the response to a request was not successfully processed by the Teradata server.
Usage Notes
In contrast to the Error parcel, the Failure parcel indicates that the Teradata SQL response has
been discarded and the Teradata SQL request and transaction in which it was embedded, if
any, have been aborted and backed out of the data base.
When ANSI transaction semantics are in effect, a Failure response parcel rolls back only the
request causing the error unless that error threatens the integrity of the database, in which
case the entire transaction is rolled back.
This parcel is generated by the Teradata server.
Parcel Data
The following table lists field information for Error.
Flavor
Parcel Body
Length
Parcel Body Fields
9
8 to 263
StatementNo:
2 byte unsigned integer
Info:
2 byte unsigned integer
Code:
2 byte unsigned integer
Length:
2 byte unsigned integer
Msg:
1 to 255 bytes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
275
Chapter 9: Parcels
Parcel Descriptions
Field Notes
Failure Parcel fields are defined as:
•
StatementNo is the number of the Teradata SQL statement in the Teradata SQL request
that failed.
•
Info is an integer value whose use depends upon the failure code returned. For its contents,
look up the error code in the Messages manual.
•
Code is the error code specifying the type of error that occurred.
•
Length is the total number of bytes in the textual representation of the Failure Code. If
Length = 0, no textual representation of the error is present.
•
Msg is the failure message in character format.
Field
Purpose
Contains information that is returned in Field Mode.
Usage Notes
The following usage notes apply to the Field parcel.
If Field is preceded by this parcel...
Then it contains...
RecStart
a data value of a column or it contains a string echoed
from the Teradata server
TitleStart
the title of one column.
FormatStart
the format of one column.
Parcel Data
This parcel is generated by the Teradata server.
Flavor
18
Parcel Body
Length
0 to
maximum
body size
Parcel Body Fields
Data: 0 to maximum body size
Field Notes
Data contains the value of a field in character format.
276
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Flagger
Purpose
Returns to the application non-conformances in the SQL request.
Usage Notes
The standard for judging conformance is specified in the SessionOptions parcel.
This parcel is generated by the Teradata server.
Parcel Data
The following table lists field information for Flagger.
Flavor
122
Parcel Body
Length
6 to
maximum
body size
Parcel Body Fields
Location:
2 bytes
Reason:
2 bytes
MsgLength:
2 bytes
Message:
to maximum body size
Field Notes
The flags each consist of one or more conformance flags, each containing the following
information:
•
Location is a 2-byte field that specifies the character position of the nonconforming syntax
within the statement.
For a semantic nonconformance, the value is zero.
•
Reason is a 2-byte field that specifies the nature of the nonconformance.
•
MsgLength is a 2-byte field that specifies the length of the Message field.
•
Message is a variable parcel body length that contains the text of the message.
FMReq
Purpose
Initiates a request specified by one or more Teradata SQL statements and specifies that the
results are to be returned in Field Mode.
Usage Notes
If the Teradata SQL request contains a USING row descriptor, this parcel is to be followed by a
Data or IndicData parcel.
Parcel Data
This parcel is generated by CLIv2 at the direction of the application.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
277
Chapter 9: Parcels
Parcel Descriptions
Flavor
13
Parcel Body
Length
1 to
maximum
body size
Parcel Body Fields
ReqText
Field Notes
ReqText Field contains the Teradata SQL request string.
A request string can contain one or more Teradata SQL statements.
A single-statement request does not have to end with a semicolon.
However, if a request contains more than one statement, the statements must be separated by
semicolons and the last statement does not have to end with a semicolon.
The total length of a FMReq must include semicolons.
FMRunStartup
Purpose
Executes the user’s Startup request and returns the results in Field Mode.
Usage Notes
If a startup request is not stored with the data base, the response is an Error parcel with error
code 3747.
Parcel Data
This parcel is generated by CLIv2 at the direction of the application.
Flavor Field
Body Parcel
Length
Parcel Body Fields
14
0
none
FormatEnd
Purpose
Delimits the end of a sequence of Field parcels that contain format descriptors for fields in a
Field Mode result.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the FormatEnd parcel.
278
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Flavor
Parcel Body
Length
Parcel Body Fields
23
0
none
FormatStart
Purpose
Delimits the start of a sequence of Field parcels that contain format descriptors for fields in
Field Mode.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the FormatStart parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
22
0
none
IndicData
Purpose
Sends data in Indicator Mode to the Teradata server.
Usage Notes
The IndicData parcel follows one of these parcels that contains a USING row descriptor:
•
Req
•
IndicReq
•
FMReq
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the IndicData parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
279
Chapter 9: Parcels
Parcel Descriptions
Flavor
Parcel Body Length
Parcel Body Fields
68
2 to maximum body
size
NullIndicators:
(n+7)/8 bytes where n = the number of
items in the Data Field,
organized as:
bit 1, bit 2, . . . , bit i,. . . , bit n, unused bits
Data:
1 to maximum body size - ((n+7) / 8) bytes
organized as:
item 1, item2, . . . , item i,..., item n
Field Notes
The following notes apply to IndicData fields.
The NullIndicators Field contains one bit for each item in the Data Field, stored in the
minimum number of 8-bit bytes required to hold them, with the unused bits in the rightmost
byte set to zero.
Each bit is matched on a positional basis to an item in the Data Field (that is, the ith bit in the
NullIndicators Field corresponds to the ith item in the Data Field).
If a bit is...
Then the value of the corresponding data item is...
ON
null.
OFF
not null.
Whether the null indicator bit is ON or OFF, the length of the corresponding data item is
meaningful.
For example,
If the data item is to contain...
Then...
a variable length string
length portion of the data item is set to the actual length of
the string (which is zero if the data item represents a null
value).
an integer
the data item occupies four bytes (which will be zero if the
data item represents a null value).
The Data Field contains a formatted record of data:
The order of the items and their data types and lengths are determined by the USING row
descriptor in the Teradata SQL statement.
The values of the items are represented in client internal format.
A null value is explicitly indicated by a null indicator bit, as explained above.
280
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
IndicReq
Purpose
Initiates a request composed of one or more Teradata SQL statements and specifies that the
results are to be returned in Indicator Mode.
Usage Notes
If the Teradata SQL request contains a USING row descriptor, this parcel is to be followed by a
Data or IndicData parcel.
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the IndicReq parcel.
Flavor
69
Parcel Body
Length
1 to maximum
body size
Parcel Body Fields
ReqText
Field Notes
ReqText contains the Teradata SQL request string.
A request string can contain one or more Teradata SQL statements.
A single-statement request does not have to end with a semicolon.
However, if a request contains more than one statement, the statements must be separated by
semicolons and the last statement does not have to end with a semicolon.
The total length of a IndicReq must include semicolons.
IVRunStartup
Purpose
The IVRunStartup (Indicator Mode Run Startup) parcel executes the user’s startup request
and returns the results in Indicator Mode. If a startup request is not stored with the Teradata
Database, the response parcel is an Error parcel with error code 3747.
Usage Notes
This parcel is generated by CLI at the direction of the application.
Parcel Data
The following table lists field information for the IVRunStartup parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
281
Chapter 9: Parcels
Parcel Descriptions
Flavor Field
Parcel Body
Length
Parcel Body Fields
72
0
none
KeepResp
Purpose
Typically, the KeepResp parcel conveys the current length of the input (response) buffer.
Usage Notes
The KeepResp (keep-response respond) parcel requests as many response parcels as will fit in
the specified Byte Count. If the KeepResp parcel is used in a start request or continue request
and the start response or continue response contains the EndRequest parcel, the spool file is
retained on the Teradata Database. In general, the spool file is deleted when:
•
A Cancel parcel is issued in a (dis)continue request,
•
The EndRequest parcel is returned in response to a continue request that contained a Resp
parcel,
•
An abort operation occurs, or
•
A logoff operation occurs.
This parcel is generated by CLI at the direction of the application.
Parcel Data
The following table lists field information for the KeepResp parcel.
Flavor Field
Parcel Body
Length
Parcel Body Fields
5
6
MaxMsgSize:
2 byte integer
Field Notes
MaxMsgSize is the maximum number of bytes that can be returned to the client in one
response. The minimum allowable buffer size is 256 bytes, hence MaxMsgSize must be greater
than or equal to 256. Also, MaxMsgSize must be less than or equal to the size of the input
(response) buffer. If the next parcel to be returned by the Teradata Database is larger than
MaxMsgSize, an Error parcel that specifies how large the buffer must be is returned. If the
buffer size is too small, a larger buffer must be allocated by the application program.
KeepRespond
Purpose
Conveys the current length of the input (response) buffer.
282
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Usage Notes
The KeepRespond parcel requests as many response parcels as will fit in the specified
MaxMsgSize.
If the KeepRespond parcel is used in a start request or continue request and the start response
or continue response contains the EndRequest parcel, the spool file is retained on the Teradata
Database.
In general, the spool file is deleted in any of the following situations:
•
A Cancel parcel is issued
•
The EndRequest parcel is returned in response to a continue request that contained a Resp
parcel
•
An abort operation occurs
•
A logoff operation occurs
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following information applies to the KeepRespond parcel.
Flavor Field
Parcel Body
Length
Parcel Body Fields
5
2
MaxMsgSize:
2 byte unsigned integer
Field Notes
MaxMsgSize is the maximum number of bytes that can be returned to the client in one
response. The minimum allowable buffer size is 256 bytes, hence MaxMsgSize must be greater
than or equal to 256. Also, MaxMsgSize must be less than or equal to the size of the input
(response) buffer. If the next parcel to be returned by the Teradata Database is larger than
MaxMsgSize, an Error parcel that specifies how large the buffer must be is returned. If the
buffer size is too small, a larger buffer must be allocated by the application program. The
maximum value is 65535.
Logoff
Purpose
The Logoff parcel terminates the session.
Usage Notes
This parcel is generated by CLI at the direction of the application.
Parcel Data
The following table lists field information for the Logoff parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
283
Chapter 9: Parcels
Parcel Descriptions
Flavor Field
Parcel Body
Length
Parcel Body Fields
37
0
none
Logon
Purpose
Establishes a session if the userid and password are valid
Usage Notes
If an account is not supplied, the default account for the user is used.
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following table lists field information for the Logon parcel.
Flavor Field
Body Parcel
Length
Parcel Body Fields
36
278
LogonString:
5 to 128 bytes
Field Notes
LogonString is a character string containing the following elements:
userid, password[, ‘account’]
where
The userid is the user’s identification. It must consist of at least one character and may consist
of as many as 30 characters. Each character may require 1, 2, or 3 bytes, depending on the
character set used. Therefore, up to 90 bytes may be necessary to specify the field. The userid
may be enclosed in apostrophes, each of which requires 1 byte (2 bytes if Unicode). Therefore,
the maximum length is 92 bytes.
Note that SQL terminal symbols (such as apostrophes) must always come from the shortest
repertoire; that is, 1 byte. Terminal symbols are never 3 bytes.
The userid and password must be separated by a comma.
The password is the user’s password. It must consist of at least one character, and may consist
of as many as 30 characters. Each character may require 1, 2, or 3 bytes, depending on the
character set used. Therefore, up to 90 bytes may be necessary to specify the field. The
password may be enclosed in quotation marks, each of which requires 1 byte (2 bytes if
Unicode). Therefore, the maximum length is 92 bytes.
Note that SQL terminal symbols (such as quotation marks) must always come from the
shortest repertoire; that is 1 byte. Terminal symbols are never 3 bytes.
284
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
If the account is not omitted, the password and account must be separated by a comma.
The userid, password, and account name each consists of characters from the session
character set.
When supported by the session character set, double-byte characters may be included by
preceding each contiguous group of them with the Shift-out control character, X’0E’, and
following this group with the Shift-in control character, X’0F’.
Any TDP identifier and delimiting slash must be specified in the standard EBCDIC character
set.
Neither commas nor blanks may be specified as double-byte characters.
Note: The password is usually required, but it may be optional in the logon string submitted
by the application if the site has an exit routine that validates the userid.
The account (optional) is the account under which the user is logging on.
The account may consist of as many as 30 characters, and it must be enclosed in apostrophes.
Any apostrophe in the account name must be represented by two apostrophes. The second
apostrophe is not counted toward the limit of 30 characters.
Each character may consist of 1, 2, or 3 bytes, depending on the character set used.
If the account string consists of 30 apostrophes, and is encoded in Unicode (2-byte terminal
symbols), 124 bytes are necessary to specify the field.
The userid and password must satisfy the lexical characteristics of Teradata SQL words.
See the description of lexical characteristics in Database Design and SQL Fundamentals.
MultipartData
Purpose
For requests initiated in MultipartIndicator mode when Use-presence was not requested,
provides data associated with the SQL USING row descriptor.
Usage Notes
The MultipartData parcel follows a MultipartIndicatorRequest parcel that contains a USING
row descriptor.
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following table lists field information for MultipartData.
Flavor
140
Parcel Body
Length
1 to
maximum
body size
Parcel Body Fields
Data: 1 to maximum body size
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
285
Chapter 9: Parcels
Parcel Descriptions
Field Notes
The MultipartData Field contains a formatted record of data:
•
The order of the items and their data types and lengths are determined by the USING row
descriptor in the Teradata SQL statement.
•
The values of the items are represented in a client internal format. For details, see the
Internal Formats Tables in “Record” on page 303.
•
A null value is implicitly indicated by a specific value of the item (for details, see
“Manipulating Nulls” in SQL Fundamentals) and that value is not necessarily unique to
null. For explicit, unique indications of null values, use Indicator Mode or Field Mode.
MultipartIndicData
Purpose
For requests initiated in MultipartIndicator mode when Use-presence was requested, provides
data associated with the SQL USING row descriptor.
Usage Notes
The MultipartIndicData parcel follows either an IndicReq or MultipartIndicatorRequest
parcel that contains a USING row descriptor.
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The content of the MultipartIndicData parcel is as follows.
Flavor
142
Parcel Body
Length
1 to
maximum
body size
MultipartIndicData Parcel Fields
Data: 1 to maximum body size bytes
Field Notes
The MultipartIndicData Field contains a formatted record of data:
286
•
The order of the items and their data types and lengths are determined by the USING row
descriptor in the Teradata SQL statement.
•
The values of the items are represented in a client internal format. For details, see the
Internal Formats Tables in “Record” on page 303.
•
A null value is implicitly indicated by a specific value of the item (for details, see
“Manipulating Nulls” in SQL Fundamentals) and that value is not necessarily unique to
null. For explicit, unique indications of null values, use Indicator Mode or Field Mode.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
MultipartRecord
Purpose
For MultipartIndicator mode responses, returns one row or part of one row of selected results.
Null values are explicitly indicated.
Usage Notes
The MultipartRecord parcel returns one row of selected results. In Indicator Mode, null values
are explicitly identified.
In Indicator Mode, the parcel immediately before the first Record Mode MultipartRecord
parcel is a Success parcel; in Indicator Mode, the parcel immediately before the first Indicator
Mode MultipartRecord parcel is a DataInfoX parcel, which is preceded by the Success parcel.
Note that a Teradata SQL SHOW TABLE statement returns only one MultipartRecord parcel.
Within the MultipartRecord parcel, each line of a table is separated from the next by hex 0D
(decimal 13).
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the MultipartRecord parcel (in Indicator Mode).
Flavor
144
Parcel Body
Length
1 to maximum
body size
Parcel Body Fields
NullIndicators: (n+7)/8 bytes
where:
n = the number of items in the
Data Field, organized as:
bit 1, but 2, . . . , bit i,
. . . , but n, unused bits
Data: 1 to 32000 - ((n+7) / 8) bytes
organized as: item 1, item2, . . . , item i,
. . . , item n
Field Notes
The Data Field contains items with characteristics as follows:
•
The NullIndicators Field contains one bit for each item in the DataField, stored in the
minimum number of 8-bit bytes required to hold them, with the unused bits in the
rightmost byte set to zero.
Each bit is matched on a positional basis to an item in the Data Field. That is, the ith bit in
the NullIndicators Field corresponds to the ith item in the Data Field.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
287
Chapter 9: Parcels
Parcel Descriptions
If a bit is...
Then the value of the corresponding data item is...
ON
null.
OFF
not null.
Whether the null indicator bit is ON or OFF, the length of the corresponding data item is
meaningful.
The Data Field contains a formatted record of data:
•
If the data item is to contain...
Then...
a variable length string
the length portion of the data item is set to the actual
length of the string which is zero if the data item
represents a null value.
an integer
the data item will occupy four bytes which is zeros if
the data item represents a null value.
The Data Field contains items with characteristics as follows:
•
The order of the items.
Each expression in the SELECT statement generates one data item in the Indicator
Mode MultipartRecord parcel, in the order listed in the SELECT statement.
That is, the ith data item in the Indicator Mode MultipartRecord parcel contains the
result of the ith expression in the SELECT statement.
•
The data type of each item.
Each item in the Data Field of the Indicator Mode MultipartRecord parcel has the data
type which is specified in the corresponding data type code in the DataInfoX parcel
between the Success parcel and the first Indicator Mode MultipartRecord parcel.
That is, the ith data item in the Indicator Mode MultipartRecord parcel has the ith data
type coded in the DataInfoX parcel.
•
The length of each item.
Each item in the Data Field of the Indicator Mode MultipartRecord parcel has the
length which is specified in the corresponding length in the DataInfoX parcel between
the Success parcel and first Indicator Mode MultipartRecord parcel.
That is, the ith data item in the Indicator Mode MultipartRecord parcel has the ith
length in the DataInfoX parcel.
•
The format of each item.
The contents of each item are in client internal format, as determined by the data type
(see Table 19 on page 307).
For the form that a null value takes for each of these data types, see “Manipulating
Nulls” in SQL Fundamentals.
288
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
For the form that decimals and variable length strings take, see the data type description in
“DataInfoX” on page 267.
MultipartRequest
Purpose
Initiates a request consisting of one or more SQL statements and indicates that the results are
to be returned in MultipartIndicator mode.
Usage Notes
If the SQL request contains a USING row descriptor, then this parcel is followed by either one
or more MultipartData parcels and an EndMultipartData parcel, or one or more
MultipartIndicData parcels and an EndMultipartIndicData parcel.
Parcel Data
The content of the MultipartRequest parcel is as follows.
Flavor
148
Parcel Body
Length
1 to
maximum
body size
Parcel Body Fields
ReqText
ReqText is one or more SQL statements, each separated by a semicolon, the last ending with
an optional semicolon. The characters are in the current session character set.
Multi-TSR
Purpose
Provides segments of a request that is too large to fit into the maximum parcel size. This parcel
is currently only used for the text of Stored Procedures.
Usage Notes
This parcel is generated by CLIv2 when the Segment Data option is specified by the
application.
Parcel Data
Flavor
Parcel Body
Length
128
3
Parcel Body Fields
SequenceNumber: 2 bytes
Status: 1 byte
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
289
Chapter 9: Parcels
Parcel Descriptions
Field Notes
The SequenceNumber field specifies the order of the segment, relative to other segments.
SequenceNumber is a binary value that begins at one and increments by one for each MultiTSR parcel.
The Status field specifies the type of segment. A binary one indicates that this is the last
segment. Otherwise the value is a binary zero.
NOP
Purpose
The Teradata Database will discard this parcel without taking any action.
Parcel Data
The following table lists field information for the NOP parcel.
Parcel Body
Length
Flavor Field
32
0 to maximum
parcel size
Parcel Body Fields
0 to maximum parcel size
NullField
Purpose
Returns a field stored as null, in a Field Mode response.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the NullField parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
19
0
none
OffsetPosition
Purpose
Requests that the Teradata SQL response returning a single Large-object selected by a Locator
be repositioned to a specified BLOB byte offset or CLOB character offset.
290
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Usage Notes
OffsetPosition is included in a Continue request to reposition to a particular byte in a Large
object.
If present, the OffsetPosition parcel must immediately precede either the
ExtendedKeepRespond or KeepRespond parcel.
Parcel Data
The following information applies to the OffsetPosition parcel.
Parcel Flavor
Parcel Body
Length
Parcel Body Fields
159
12
Statement Number : 2 bytes
Unused : 2 bytes
Offset : 8 bytes
OK
Purpose
First parcel returned in response to a successfully executed Field Mode Teradata SQL
statement when using Original Statement-status.
If the activity type is 33 (Echo), an echo sequence will follow.
Usage Notes
If the Warninglength is zero, there may be some slack bytes following the Warninglength. If so,
they are added into the parcel length total.
This parcel is generated by Teradata Database.
Parcel Data
The following information applies to the OK parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
17
14 to 269
StatementNo:
2 byte unsigned integer
FieldCount:
2 byte unsigned integer
ActivityCount:
4 byte unsigned integer
ActivityType:
2 byte unsigned integer
WarningCode:
2 byte unsigned integer
WarningLength:
2 byte unsigned integer
WarningMsg:
0 to 255 bytes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
291
Chapter 9: Parcels
Parcel Descriptions
Field Notes
The following notes apply to OK fields.
•
StatementNo is the number of the Teradata SQL statement for which this is the first parcel
of a response.
•
FieldCount is the total number of fields returned in each record.
•
ActivityCount is the total number of records selected, inserted, updated, or deleted.
•
ActivityType is an encoded value representing the type of Teradata SQL statement that was
processed. See “Activity Type” on page 257 for the possible activity types.
•
WarningCode is usually zero. If it is nonzero, it represents a comment on an operation that
was carried out. See the Messages manual for more information about particular code.
•
WarningLength is the length of the warning message. If WarningLength is zero, there is no
warning message.
•
WarningMsg is the text of the warning message.
Options
Specifies which statement options are used when a request is sent to Teradata Database.
Usage Notes
The Options parcel is generated by CLIv2 at the direction of an application.
Parcel Data
The following information applies to the Options parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
85
10 to 14
RequestMode: 1 byte
Function: 1 byte
Select-data: 1 byte
Continued-characters-state: 1 byte
APH-response: 1 byte
Return-statement-info: 1 byte
UDTTransformsOff: 1byte
Maximum DECIMAL precision: 1 byte
(ignored if Field Response-mode)
IdentityColumnRetrieval: 1 byte
DynamicResultSets: 1 byte
If present, SP-ReturnResult: 1 byte
292
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Parcel Body
Length
Flavor
Parcel Body Fields
If present, PeriodStructOn: 1 byte
If present, ColumnInfo: 1 byte
If present, TrustedSesions: 1 byte
Field Notes
The following information applies to Options fields.
•
RequestMode indicates which mode is used to process a response. The settings are as
follows:
•
F - specifies Field Mode
•
R - specifies Record Mode
•
I - specifies Indicator Mode
•
M - MultipartIndicator Mode
If this field contains a binary zero, the Teradata Database uses the mode specified
elsewhere (in the Req, IndicReq, or FMReq parcel) in the request.
When two or more parcels in a request specify conflicting modes, Teradata Database uses
the mode specified in the Options parcel.
•
Function corresponds to the Request Processing Option field of the DBCAREA, and
indicates whether the intent is to prepare and execute, to prepare, or to execute the request.
The settings are as follows:
•
•
E- specifies that the request should be executed.
•
A binary zero in this field is interpreted as an E.
•
P- specifies that a PrepInfo parcel is built for each statement in the request. The
statements may not contain parameterized SQL.
•
S- specifies that a PrepInfo parcel is built for each statement in the request. The
statements may contain parameterized SQL.
•
B- specifies that a PrepInfo parcel is built for each statement in the request and that the
request should be executed. The statements may contain parameterized SQL. This
setting is supported for both Indicator mode and Record mode. For SQL statements
that return no data, such as Insert, Update, Delete and DDL statements, an “empty”
PrepInfo parcel is returned. Empty means that the column count in the PreInfo parcel
is set to zero.
Select-data specifies the way data associated with a Large Object is returned, chosen as one
of the following ASCII characters:
•
I- if the actual data is to be returned in the initial response.
•
L- if a locator token associated with the data within the transaction is to be returned.
•
S- if a locator token associated with the data within the spool file is to be returned.
If the field contains a binary zero, a value of 'I' is assumed.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
293
Chapter 9: Parcels
Parcel Descriptions
•
Continued-characters-state indicates whether character data crossing response parcels is
well-formed within each parcel or only when all relevant parcels are considered. This
option has effect only for MultipartIndicator response mode because only in that mode
may data cross parcel boundaries. If not applicable, the option is ignored.
The supported values are:
•
•
•
•
•
•
294
•
L- the default, specifies that character data crossing response parcels may be in the
locked shift state
•
U- specifies that character data crossing response parcels must be in the unlocked shift
state
APH-response indicates whether response parcels may use the alternate parcel header. The
supported values are:
•
Y- specifies that alternate parcel headers may be used in response parcels
•
Binary zero- the default, if alternate parcel headers may not be used in response parcels
Return-statement-info indicates whether response parcels may use the alternate parcel
header. The supported values are:
•
'Y' specifies that StatementInformation response parcels will be returned instead of
DataInfo[X] and PrepInfo[X] response parcels. This setting will be rejected if the
ResponseMode option specifies 'F' (Field mode).
•
'N', the default, if StatementInformation response parcels may not be used.
TrustedSesions allowed indicates the trusted-request options.
•
'N' - the default. it indicates that this is not a trusted request. If the trusted user
possesses the trust-only attribute, this setting will prevent “SET QUERY_BAND
PROXYUSER...” from being affected.
•
'Y' - it indicates that this is a trusted request. If the trusted user possesses the trust-only
attribute, this setting will allow “SET QUERY_BAND PROXYUSER...” to be affected.
Maximum DECIMAL precision indicates the precision of decimal data types in responses.
The supported values are:
•
a positive value up to a maximum obtained using the DBCHQE SQL-limits query.
•
binary zero, the default, if the client default, 15, is to be used.
IdentityColumnRetrieval indicates whether data is returned in response to an SQL Insert
operation when Identity columns are involved. The supported values are:
•
binary zero, the default, that no fields are returned.
•
'C' specifies that the values for any Identity columns are returned.
•
'R' specifies that the values for all fields in an inserted row that contains Identity
columns are returned.
DynamicResultSets indicates whether stored procedures may include the results of its SQL
requests in the response to the response to the SQL CALL statement invoking the
procedure. The supported values are:
•
'N', the default, if such results may not be included.
•
'Y' if such results may be included.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
•
SP-ReturnResult indicates where the results of the associated request are to be returned.
The supported values are:
•
•
0, the default, if the results are returned to the stored procedure itself.
•
1, if the results are to be returned to the client.
•
2, if the results are to be returned to the CALLer of the stored procedure.
•
3, if the results are to be returned to both the stored procedure and the client.
•
4, if the results are to be returned to both the stored procedure and its CALLer.
PeriodStructOn indicates Period data types are treated as Structured UDTs:
•
•
'N' - Period data types are treated as simple data types.
•
'Y' - Period data types are treated as Structured UDTs in honoring the Transforms-off
option. Setting PeriodStructOn to 'Y' requires setting the UDTTransformsOff to 'Y' at
the same time. If not, the database will return an error since the support of Period as
Struct is an extension of the support of Structured UDTs.
UDTTransformsOff indicates whether Structured UDTs are transformed into their
external type:
•
•
'N' - the flag is off and Structured UDTs are transformed into their external type.
•
'Y' - the flag is on and Structured UDTs are to be returned from the server in the untranslated mode.
ColumnInfo allowed indicates whether the response parcels to this request contain large
column or extended object name size.
•
•
0 - the default. it indicates that client can not accept extended object name in response
parcels.
•
1 - it indicates that client can accept extended object name in response parcels.
RFU1 through RFU2 are reserved for future use and must be set to binary zero. An error
occurs if these fields are not set to binary zero.
PosEnd
Purpose
Delimits the end of a sequence of Position parcels that contain select-table
column-correspondence information on summary results.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the PosEnd parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
47
0
none
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
295
Chapter 9: Parcels
Parcel Descriptions
Position
Purpose
Indicates the column number whose values are being summarized.
Usage Notes
The column number in the selected results corresponds to the expression number in the main
body of the Teradata SQL SELECT statement.
If ColumnNo = 0, then the expression in the WITH clause is not the same as any of the
expressions in the main body of the Teradata SQL SELECT statement.
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the Position parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
34
2
ColumnNo: 2 byte unsigned integer
Field Notes
ColumnNo specifies the number of the column where a summary is to be displayed.
PosStart
Purpose
Delimits the start of a sequence of Position parcels that contain select-table
column-correspondence information on summary results.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the PosStart parcel.
296
Flavor
Parcel Body
Length
Parcel Body Fields
46
0
none
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
PrepInfo
Purpose
Returns a description of the return data specified by a request, when that request is sent to
Teradata Database with a Request Processing Option of Prepare and a Response Mode of
Indicator.
The parcel also contains an estimate of the time it will take to execute the statement.
Usage Notes
If the PrepInfo parcel contains zeros, the statement was an ECHO statement. The PrepInfo
parcel is generated by Teradata Database.
Parcel Data
The following information applies to the PrepInfo parcel.
Flavor
86
Parcel Body
Length
12 to
maximum
body size
Parcel Body Fields
CostEstimate:
8 byte floating
SummaryCount:
2 byte unsigned integer
The following occur once for the SELECTed columns, and
SummaryCount times for any WITH clauses.
ColumnCount:
2 byte unsigned integer
For each column, the following occur:
DataType:
2 byte unsigned integer
DataLen:
2 byte unsigned integer
ColumnName:
2 to 32 bytes of characters
ColumnFormat:
2 to 32 bytes of characters
ColumnTitle:
2 to 62 bytes of characters
Field Notes
The following notes apply to PrepInfo fields.
•
CostEstimate returns a time estimate, in milliseconds, of how long it will take to execute a
request.
The CostEstimate field is set to zero if the estimated time is negligible.
•
SummaryCount specifies the number of WITH clauses in the request.
The SummaryCount field is set to zero if no summary data is returned, that is, if the
request is not a SELECT statement or if the request is a SELECT statement without any
WITH clauses.
•
ColumnCount specifies how many sets of column-descriptive fields follow.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
297
Chapter 9: Parcels
Parcel Descriptions
The first occurrence of ColumnCount indicates the number of columns returned by the
statement.
It is immediately followed by as many sets of the column-descriptive fields as required to
describe each column.
Next, if SummaryCount is greater than zero, a group of fields is returned once for each
WITH clause.
Each group comprises a ColumnCount field that indicates the number of columns
referenced in the clause, and as many sets of the column-descriptive fields as required to
describe each column in that clause:
•
DataType specifies a code associated with a column‘s data type. For the possible data
types, see Table 16 on page 256.
•
DataLen specifies a column‘s length in bytes.
However, if a column‘s data type is DECIMAL, the first byte contains the integral digits
and the second byte contains the fractional digits.
•
ColumnName specifies a column‘s name.
The field can be from 2 to 32 bytes.
The first two bytes specify the length (as an integer) of the column name.
The column name text follows and can be from 0 to 30 bytes.
If a column is the result of an expression, the first two bytes contain a length of zero
and the text portion of the field is empty.
•
ColumnFormat specifies a column‘s format.
The field can be from 2 to 32 bytes.
The first two bytes specify the length of the column format.
The column format text follows and can be from 0 to 30 bytes.
If a column‘s format is null, the first two bytes contain a length of zero and the text
portion of the field is empty.
•
ColumnTitle specifies a column‘s title.
The field can be from 2 to 62 bytes.
The first two bytes specify the length of the column title.
The column title text follows and can be from 0 to 60 bytes.
If a column‘s title is null, the first two bytes contain a length of zero and the text
portion of the field is empty, when Return-statement-info 'Y' was not specified.
For example, consider the following SELECT statement,
SELECT Name
FROM Employee
WITH COUNT (DeptNo), SUM (Salary) BY Salary
WITH COUNT (DeptNo) BY DeptNo;
This statement produces a PrepInfo parcel with the following byte sequence:
Parcel flavor is 86 with length 124
40 4D BE B8 51 EB 85 1E 00 02 00 01 01 C0 00 0C
00 04 D5 81 94 85 00 05 E7 4D F1 F2 5D 00 04 4E
298
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
61
F0
01
F9
01
81
5D
6D
5D
E5
F9
01
99
65
F9
0F
00
F1
A8
00
00
02
0B
00
5D
02
0B
00
53
04
00
01
E2
00
75
00
0B
F1
E4
00
6D
00
E2
00
D4
0A
28
00
E4
04
4D
E9
53
06
D4
00
C4
E9
61
E2
4D
00
85
E9
6C
E4
C4
00
97
6B
61
D4
85
06
A3
E9
72
4D
97
60
D5
E9
79
E2
A3
4D
96
F9
29
81
D5
F1
5D
4B
00
93
96
The parcel fields, above, translate as follows (an explanation of each acronym follows):
CE
NL
CT
CF
DT
CF
CC
TL
CE
NL
CT
CF
DT
CF
DT
CT
CE
CN
CT
CF
DL
TL
DT
CT
CE
CN
CC
TL
DL
TL
DL
CT
CE
CN
CC
TL
NL
CT
DL
CT
CE
CN
DT
CT
NL
CT
NL
CT
CE
FL
DT
CT
FL
CT
NL
CT
CE
FL
DL
CT
FL
CT
FL
CT
SC
CF
DL
CT
CF
CT
FL
CT
SC
CF
NL
CT
CF
CT
CF
CT
CC
CF
NL
CT
CF
CT
CF
CT
CC
CF
FL
CT
CF
CT
CF
CT
DT
CF
FL
CT
CF
CT
CF
DT
TL
CF
CT
CF
CT
CF
DL
TL
CF
CT
CF
CT
CF
DL
CT
CF
CT
CF
CC
TL
CostEstimate
=
CE, 8 bytes
SummaryCount
=
SCxx, where xx is the number of WITH clauses, 2 bytes
ColumnCount
=
CCxx, where xx is the number of columns, 2 bytes
DataType
=
DT, 2 bytes
DataLength
=
DL, 2 bytes
ColumnName
=
NLxx followed by CN, where xx indicates the field‘s length and CN
represents the text, 2 to 32 bytes
ColumnFormat
=
FLxx followed by CF, where xx indicates the field‘s length and CF
represents the text, 2 to 32 bytes
ColumnTitle
=
TLxx followed by CT, where xx indicates the field‘s length and CT
represents the text, 2 to 62 bytes
PrepInfoX
Purpose
Returns a description of the return data specified by a request, when that request is sent to
Teradata Database with a Request Processing Option of Prepare and a Response Mode of
MultipartIndicator when Return-statement-info 'Y' was not specified.
The parcel also contains an estimate of the time it will take to execute the statement.
Usage Notes
If the PrepInfoX parcel contains zeros, the statement was an ECHO statement. The PrepInfoX
parcel is generated by Teradata Database.
Parcel Data
The following information applies to the PrepInfoX parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
299
Chapter 9: Parcels
Parcel Descriptions
Flavor
125
Parcel Body
Length
12 to
maximum
body size
Parcel Body Fields
CostEstimate:
8 byte floating
SummaryCount:
2 byte unsigned integer
The following occur once for the SELECTed columns, and
SummaryCount times for any WITH clauses.
ColumnCount:
2 byte unsigned integer
For decimal columns, the following occur:
DataType:
2 byte unsigned integer
DataLen:
8 bytes SmallInt
Unused:
2 bytes
ColumnName:
2 to 92 bytes of characters
ColumnFormat:
2 to 92 bytes of characters
ColumnTitle:
2 to 182 bytes of characters
For non-decimal columns, the following occur:
DataType:
2 byte unsigned integer
DataLen:
8 bytes SmallInt
CharacterType:
1 byte unsigned integer
ColumnInformation
8 bits
ColumnName:
2 to 92 bytes of characters
ColumnFormat:
2 to 92 bytes of characters
ColumnTitle:
2 to 182 bytes of characters
Field Notes
The following notes apply to PrepInfoX fields.
•
CostEstimate returns a time estimate, in milliseconds, of how long it will take to execute a
request.
The CostEstimate field is set to zero if the estimated time is negligible.
•
SummaryCount specifies the number of WITH clauses in the request.
The SummaryCount field is set to zero if no summary data is returned, that is, if the
request is not a SELECT statement or if the request is a SELECT statement without any
WITH clauses, when Return-statement-info 'Y' was not specified.
•
ColumnCount specifies how many sets of column-descriptive fields follow.
The first occurrence of ColumnCount indicates the number of columns returned by the
statement.
It is immediately followed by as many sets of the column-descriptive fields as required to
describe each column.
300
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Next, if SummaryCount is greater than zero, a group of fields is returned once for each
WITH clause.
Each group comprises a ColumnCount field that indicates the number of columns
referenced in the clause, and as many sets of the column-descriptive fields as required to
describe each column in that clause:
•
DataType specifies a code associated with a column‘s data type. For the possible data
types, see Table 16 on page 256.
•
DataLen specifies a column‘s length in bytes.
However, if a column‘s data type is DECIMAL, the first four bytes contain the integral
digits and the second four bytes contain the fractional digits.
•
CharacterType specifies a code associated with a column‘s data type, as follows:
Table 18: PrepInfoX Data Types
If the data type is...
Then the code is...
Not character data
0
Latin1
1
Unicode
2
KanjiSJIS
3
Graphic
4
Kanji1
5
•
ColumnInformation specifies whether or not the character column is case sensitive. If
so, the value is hexadecimal '80'; otherwise the value is hexadecimal '00'.
•
ColumnName specifies a column‘s name.
The field can be from 2 to 92 bytes.
The first two bytes specify the length (as an integer) of the column name, when
Return-statement-info 'Y' was not specified.
The column name text follows and can be from 0 to 90 bytes.
If a column is the result of an expression, the first two bytes contain a length of zero
and the text portion of the field is empty.
•
ColumnFormat specifies a column‘s format.
The field can be from 2 to 92 bytes.
The first two bytes specify the length of the column format.
The column format text follows and can be from 0 to 90 bytes.
If a column‘s format is null, the first two bytes contain a length of zero and the text
portion of the field is empty.
•
ColumnTitle specifies a column‘s title.
The field can be from 2 to 182 bytes.
The first two bytes specify the length of the column title.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
301
Chapter 9: Parcels
Parcel Descriptions
The column title text follows and can be from 0 to 180 bytes.
If a column‘s title is null, the first two bytes contain a length of zero and the text
portion of the field is empty.
For example, consider the following SELECT statement,
SELECT Name
FROM Employee
WITH COUNT (DeptNo), SUM (Salary) BY Salary
WITH COUNT (DeptNo) BY DeptNo;
This statement produces a PrepInfoX parcel with the following byte sequence:
Parcel flavor is 86 with length 124
40 4D BE B8 51 EB 85 1E 00 02 00 01
00 00 00 00 00 0C 01 80 00 04 D5 81
E7 4D F1 F2 5D 00 04 D5 81 94 85 00
00 00 00 00 00 00 04 00 00 00 00 00
F0 5D F9 00 0B E2 E4 D4 4D C4 85 97
01 E5 00 00 00 0F 00 00 00 02 00 00
E9 E9 E9 6B E9 E9 F9 4B F9 F9 00 0B
53 61 6C 61 72 79 29 00 01 01 F1 00
00 00 04 00 00 00 00 00 06 E2 E4 D4
81 99 A8 5D 00 0B 53 75 6D 28 44 65
29
01
94
02
06
A3
00
53
00
4D
70
C0
85
01
60
D5
00
75
00
E2
74
00
00
F1
4D
96
00
6D
00
81
4E
00
05
00
F1
5D
0A
28
00
93
6F
The parcel fields, above, translate as follows (an explanation of each acronym follows):
CE
DL
CF
DL
CF
DT
CF
CT
CF
302
CE
DL
CF
DL
CF
DT
CF
CC
CF
CE
DL
CF
DL
CF
DL
CF
CC
CF
CE
DL
CF
DL
TL
DL
CF
DT
TL
CE
DL
CF
DL
TL
UU
TL
DT
TL
CE
DL
TL
DL
CT
UU
TL
DL
CT
CE
CS
TL
DL
CT
NL
CT
DL
CT
CE
CI
CT
CS
CT
NL
CT
CS
CT
SC
NL
CT
CI
CT
FL
CT
CI
CT
SC
NL
CT
NL
CT
FL
CT
NL
CT
CC
CN
CT
NL
CT
CF
CT
NL
CT
CC
CN
CC
FL
CT
CF
CT
FL
CT
DT
CN
CC
FL
CT
CF
CT
FL
CT
DT
CN
DT
CF
CT
CF
CT
CF
CT
DL
FL
DT
CF
CT
CF
CT
CF
CT
DL
FL
DL
CF
CT
CF
CT
CF
CT
CostEstimate
=
CE, 8 bytes
SummaryCount
=
SCxx, where xx is the number of WITH clauses, 2 bytes
ColumnCount
=
CCxx, where xx is the number of columns, 2 bytes
DataType
=
DT, 2 bytes
DataLen
=
DL, 8 bytes
Unused
=
UU, 2 bytes
CharacterType
=
CS, 1 byte
ColumnInformation =
CI, 1 byte
ColumnName
=
NLxx followed by CN, where xx indicates the field‘s length and CN
represents the text, 2 to 92 bytes
ColumnFormat
=
FLxx followed by CF, where xx indicates the field‘s length and CF
represents the text, 2 to 92 bytes
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
ColumnTitle
=
TLxx followed by CT, where xx indicates the field‘s length and CT
represents the text, 2 to 182 bytes
RecEnd
Purpose
Delimits the end of a sequence of Field parcels that compose the fields of a single row of
selected results in Field Mode.
Also, the RecEnd parcel follows a Field parcel used to echo characters from the Teradata server.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the RecEnd parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
28
0
none
Record
Purpose
The Record parcel returns one row of selected results. The results are either in Record Mode or
Indicator Mode, depending on which mode is requested.
Parcel Data
The following table explains how Record Parcel modes relate to nulls.
In this mode...
Nulls are...
Record
not explicitly identified in the Record parcel.
Indicator
explicitly identified.
The Flavor and the Data Field contain the same values in the Record Mode and Indicator
Mode versions although the Data Field has a different offset in the two versions.
There is no obvious way to distinguish a Record Mode Record parcel from an Indicator Mode
Record parcel by examining the Record parcel itself.
However, the mode can be determined either by remembering the type of request parcel (Req
or IndicReq) or by noting the response context.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
303
Chapter 9: Parcels
Parcel Descriptions
In Indicator Mode, the parcel immediately before the first Record Mode Record parcel is a
Success parcel; in Indicator Mode, the parcel immediately before the first Indicator Mode
Record parcel is a DataInfo parcel, which is preceded by the Success parcel.
Record (In Indicator Mode)
Purpose
The Record parcel returns one row of selected results. In Indicator Mode, null values are
explicitly identified.
Usage Notes
In Indicator Mode, the parcel immediately before the first Record Mode Record parcel is a
Success parcel; in Indicator Mode, the parcel immediately before the first Indicator Mode
Record parcel is a DataInfo parcel, which is preceded by the Success parcel.
Note that a Teradata SQL SHOW TABLE statement returns only one Record parcel. Within
the Record parcel, each line of a table is separated from the next by hex 0D (decimal 13).
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the Record parcel (in Indicator Mode).
Flavor
10
Parcel Body
Length
2 to
maximum
body size
Parcel Body Fields
NullIndicators: (n+7)/8 bytes
where:
n = the number of items in the
Data Field, organized as:
bit 1, but 2, . . . , bit i,
. . . , but n, unused bits
Data: body length - ((n+7) / 8) bytes
organized as: item 1, item2, . . . , item i,
. . . , item n
Field Notes
The Data Field contains items with characteristics as follows:
•
The NullIndicators Field contains one bit for each item in the DataField, stored in the
minimum number of 8-bit bytes required to hold them, with the unused bits in the
rightmost byte set to zero.
Each bit is matched on a positional basis to an item in the Data Field. That is, the ith bit in
the NullIndicators Field corresponds to the ith item in the Data Field.
304
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
If a bit is...
Then the value of the corresponding data item is...
ON
null.
OFF
not null.
Whether the null indicator bit is ON or OFF, the length of the corresponding data item is
meaningful.
The Data Field contains a formatted record of data:
•
If the data item is to contain...
Then...
a variable length string
the length portion of the data item is set to the actual length
of the string which is zero if the data item represents a null
value.
an integer
the data item will occupy four bytes which is zeros if the data
item represents a null value.
The Data Field contains items with characteristics as follows:
•
The order of the items.
Each expression in the SELECT statement generates one data item in the Indicator
Mode Record parcel, in the order listed in the SELECT statement.
That is, the ith data item in the Indicator Mode Record parcel contains the result of the
ith expression in the SELECT statement.
•
The data type of each item.
Each item in the Data Field of the Indicator Mode Record parcel has the data type
which is specified in the corresponding data type code in the DataInfo parcel between
the Success parcel and the first Indicator Mode Record parcel.
That is, the ith data item in the Indicator Mode Record parcel has the ith data type
coded in the DataInfo parcel.
•
The length of each item.
Each item in the Data Field of the Indicator Mode Record parcel has the length which
is specified in the corresponding length in the DataInfo parcel between the Success
parcel and first Indicator Mode Record parcel.
That is, the ith data item in the Indicator Mode Record parcel has the ith length in the
DataInfo parcel.
•
The format of each item.
The contents of each item are in client internal format, as determined by the data type
(see Table 19 on page 307).
For the form that a null value takes for each of these data types, see “Manipulating
Nulls” in SQL Fundamentals.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
305
Chapter 9: Parcels
Parcel Descriptions
For the form that decimals and variable length strings take, see the data type
description in “DataInfo” on page 266.
Record (In Record Mode)
Purpose
In Record Mode, nulls are not explicitly identified in the Record parcel, when Returnstatement-info 'Y' was not specified.
Usage Notes
Note that a Teradata SQL SHOW TABLE statement returns only one Record parcel.
Within the Record parcel, each line of a table is separated from the next by hex 0D (decimal
13).
This parcel is generated by Teradata Database.
Parcel Data
The following information applies to the Record parcel (in Record Mode).
Flavor
10
Parcel Body
Length
1 to
maximum
body size
Parcel Body Fields
Data: organized as:
item 1, item2, . . . , item i, . . . , item n
If in Record Mode, the Record parcel for an ECHO statement does NOT contain zeros.
Field Notes
The Data Field contains items with characteristics as follows:
•
The order of the items. Each expression in the SELECT statement generates one item in
the Record Mode Record parcel, in the order listed in the SELECT statement. That is, the
ith item in the Record Mode Record parcel contains the result of the ith expression in the
SELECT statement.
•
The data type of each item. Each expression has a resulting data type, as governed by data
type conversion rules.
One method for obtaining the resulting data type of an expression is to use the HELP
COLUMN statement on that expression.
For details, see the description of the HELP COLUMN statement in the SQL Data
Definition Language.
An alternate method for obtaining the resulting data type of an expression is to consult the
data type conversion rules.
306
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
The rules begin with the data type of the elementary operands (columns in CREATE
TABLE statements, variables in USING row descriptors, constants in expressions, and
built-in values in expressions).
The rules then account for the effects of operations on the elementary operands (explicit
data type conversion in description phrases of expressions, arithmetic operations in
expressions, character operations in expressions, and functions and aggregate operations
in expressions).
For details, see SQL Data Types and Literals and SQL Functions, Operators, Expressions, and
Predicates for pointers to the rules.
•
The length and format of each item.
•
The contents of each item are in client internal format as determined by the resulting data
type of the expression.
•
For the form that a null value takes in each of these data types, see “Manipulating Nulls” in
SQL Fundamentals.
Table 19: Teradata Database Internal Format
Teradata SQL Data
Type
Teradata Database Internal Format
BYTEINT
8-bit signed two’s complement binary number (1 byte)
SMALLINT
16-bit signed two’s complement binary number, most significant byte
first (2 bytes)
INTEGER
32-bit signed two’s complement binary number, most significant byte
first (4 bytes)
FLOAT
64-bit long (double precision) floating point number, most significant
byte first, with 1 bit for fraction sign, 7 bits for unsigned power of 16
exponent (stored as actual + hex 40) and 56 bits for unsigned fraction
(8 bytes)
DECIMAL (x, y)
x-digit, signed, packed decimal in which the rightmost nibble
represents the sign (“+” is hex A, E, F or C; “-” is hex B or D) and the
remaining nibbles represent the digits (hex 0-9) which are left-padded
with zero digit if x is even (total of (x+2)/2 bytes; 8 bytes)
CHAR (n)
n bytes (either n single byte characters; (n-2)/2
double byte characters, preceded by the Shift-out control character,
X'0E', and followed by the Shift-in control character, X‘0F‘; or some
mixture of the two not exceeding n bytes). n defaults to 1 if no value is
specified.
BIGINT
Represents a signed, binary integer value from
-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.
BIGINT values are stored as eight bytes with the least significant byte
first.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
307
Chapter 9: Parcels
Parcel Descriptions
Table 19: Teradata Database Internal Format (continued)
Teradata SQL Data
Type
VARCHAR (n)
(actual length k,
where 0 <= k <= n )
Teradata Database Internal Format
SMALLINT (2 bytes) containing actual count k, followed by k bytes
(either k single byte characters; (k-2)/2 double byte characters,
preceded by the Shift-out control character, X‘0E‘, and followed by the
Shift-in control character, X'0F'; or some mixture of the two not
exceeding k bytes)
LONG VARCHAR
equivalent to VARCHAR (32000)
BYTE (n)
n bytes, n defaults to 1 if no value is specified.
VARBYTE (n)
16-bit SMALLINT (2 bytes), actual count k, followed by k bytes (total
of k+2 bytes)
(actual length k,
where 0 <= k <= n )
DATE
32-bit signed two’s complement integer, most significant byte first (4
bytes); DATE is calculated as follows: (year-1900)*10000 +
month*100 + day
GRAPHIC(n)
GRAPHIC(n), n characters (2<=n bytes), n defaults to 1 if no value is
specified.
VARGRAPHIC(n)
(actual length k, where
0 <= k <= n)
SMALLINT (2 bytes) containing actual count k, followed by k
characters (total of 2+2 <= k bytes)
LONG VARGRAPHIC
equivalent to VARGRAPHIC(16000)
NUMERIC
see description for DECIMAL
REAL
see description for FLOAT
DOUBLE
PRECISION
see description for FLOAT
RecStart
Purpose
Delimits the start of a sequence of Field parcels that constitute the fields of a single row of
selected results in Field Mode.
Also, the RecStart parcel precedes a Field parcel containing a string being echoed from the
Teradata server.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the RecStart parcel.
308
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Flavor
Parcel Body
Length
Parcel Body Fields
27
0
none
Req
Purpose
Initiates a request composed of one or more Teradata SQL statements and specifies that the
results are to be returned in Record Mode.
Usage Notes
If the Teradata SQL request contains a USING row descriptor, then this parcel is to be followed
by a Data or IndicData parcel.
This parcel is generated by CLIv2 at the direction of the application
Parcel Data
The following information applies to the Req parcel.
Flavor
1
Parcel Body
Length
1 to maximum
body size
Parcel Body Fields
ReqText
Field Notes
ReqText contains the Teradata SQL request string. A request string can contain one or more
Teradata SQL statements.
A single-statement request does not have to end with a semicolon.
However, if a request contains more than one statement, the statements must be separated by
semicolons and the last statement does not have to end with a semicolon.
The total length of a Req parcel includes semicolons.
Resp
Purpose
The Resp (Response) parcel requests response data from the Teradata Database. Typically, it
carries the current length of the input (response) buffer. When the last record from a spool file
is sent in response to a start or continue request containing a Resp parcel, the spool file is
deleted.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
309
Chapter 9: Parcels
Parcel Descriptions
Usage Notes
This parcel is generated by CLI at the direction of the application.
Parcel Data
The following table lists field information for the Resp parcel.
Flavor Field
Parcel Body
Length
Parcel Body Fields
4
2
MaxMsgSize:
2 byte integers
Fields
MaxMsgSize is the maximum number of bytes that can be returned to the client in one
response. The minimum allowable buffer size is 256 bytes, hence MaxMsgSize must be greater
than or equal to 256. Also, MaxMsgSize must be less than or equal to the size of the input
(response) buffer. If the next parcel to be returned by the Teradata Database is larger than
MaxMsgSize, an ERROR parcel that specifies how large the buffer must be is returned. If the
buffer size is too small, a larger buffer must be allocated by the application program.
Respond
Purpose
The Respond parcel requests response data from the Teradata Database. Typically, it carries
the current length of the input (response) buffer.
Usage Notes
When the last record from a spool file is sent in response to a start or continue request
containing a Respond parcel, the spool file is deleted.
This parcel is generated by CLIv2 at the direction of the application.
Parcel Data
The following table lists field information for the Resp parcel.
Flavor Field
Parcel Body
Length
Parcel Body Fields
4
2
MaxMsgSize:
2 byte integers
Field Notes
MaxMsgSize is the maximum number of bytes that can be returned to the client in one
response. The minimum allowable buffer size is 256 bytes, hence MaxMsgSize must be greater
than or equal to 256. Also, MaxMsgSize must be less than or equal to the size of the input
(response) buffer. If the next parcel to be returned by the Teradata Database is larger than
MaxMsgSize, an ERROR parcel that specifies how large the buffer must be is returned. If the
310
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
buffer size is too small, a larger buffer must be allocated by the application program. The
maximum value is 65535.
ResultSet
Purpose
Returned after a Success, OK, or ResultSummary parcel to introduce parcels returned from a
CALLed stored procedure when Result-sets-OK 'Y' was specified (corresponding to the
Options parcel (flavor 85) DynamicResultSets 'Y' option).
TRDSPBRT
Flavor
Mnemonic
172
TRDSPFRT
Field
Length
Value
PBRTRNUM
8byte unsigned integer.
row number contained in
the first response parcel
returned for this statement.
A value of zero corresponds
to parcels before those for
the actual first row's data
(Success, for example) while
a value one greater then the
number of rows corresponds
to parcels after those for the
actual last row's data
(EndRequest).
PBRTDB
2byte unsigned integer,
plus the number of
bytes specified by that
integer
Stored procedure database,
consisting of the length in
bytes of the name, followed
by that name in characters
from the current session
character set. The maximum
length of a name may be
obtained using the
DBCHQE SQL-limits query.
PBRTPN
2byte unsigned integer,
plus the number of
bytes specified by that
integer
Stored procedure name,
consisting of the length in
bytes of the name, followed
by that name in characters
from the current session
character set. The maximum
length of a name may be
obtained using the
DBCHQE SQL-limits query
ResultSet Cursor
Sent to identify the last row fetched by an External Stored Procedure for a response being
propagated to the caller or application.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
311
Chapter 9: Parcels
Parcel Descriptions
The following table lists ResultSetCursor parcel information.
TRDSPBRK
Flavor
Mnemonic
175
TRDSPFRK
Field
Length
Value
PBRKSNUM
2byte unsigned integer
statement number
containing the last row
fetched by the procedure
PBRKNUM
8byte unsigned integer
row number of the last row
fetched by the procedure for
the statement
If the ResultSetCursor parcel is sent multiple times, the last one is honored.
Upon successful completion, an EndRequest parcel is returned. Upon unsuccessful
completion, either an Error or Failure parcel is returned. For Error, if the problem can be
corrected, the ResultSetCursor parcel may be resent; for Failure, the ResultSetCursor may not
be resent.
ResultSummary
Purpose
Returned in response to a successfully executed Teradata SQL statement when usingEnhanced
Statement-status.
It also indicates successful completion of other types of requests (for example, a logon
request) when using Enhanced Statement-status.
Usage Notes
This parcel is generated by Teradata Database.
Parcel Data
The following information applies to the ResultSummary parcel.
Table 20: ResultSummary Parcel Information
Flavor
171
312
Parcel Body
Length
24 to
maximum
parcel size
Parcel Body Fields
Activity Count:
8 byte unsigned integer
Statement No:
2 byte unsigned integer
Field Count:
2 byte unsigned integer
Activity Type:
2 byte unsigned integer
See “Activity Type” on page 257.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Table 20: ResultSummary Parcel Information (continued)
Flavor
Parcel Body
Length
Parcel Body Fields
Mode:
one EBCDIC character, as one of the following:
F - if Response-mode is Field
R - if Response-mode is Record
I - is Response-mode is Indicator
M- if Response-mode is MultipartIndicator
blank if Response-mode does not apply to the
request
Reserved:
nine bytes
Optional
self-defining
extensions:
zero or more bytes
Zero or more self-defining extensions may be present to convey situation-dependent
information. When multiple extensions are present, their order is undefined. Each extension
begins with the following fields:
Field
Length
Description
Information Id
2 byte unsigned integer
Identifies the type of extension,
as one of the following, 1
Warning Message.
Information Length
2 byte unsigned integer
Specifies the length of
subsequent data in the
extension (does not include the
length of the extension header).
The Warning Message extension consists of the following fields:
Field
Length
Description
Warning-number
2 byte unsigned integer
Identifies the sever message
number of the warning
Warning-message
Length varies
The text of the server message,
in the request's character set,
associated with the Warningnumber.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
313
Chapter 9: Parcels
Parcel Descriptions
Rewind
Purpose
The Rewind parcel repositions spool file pointers to the beginning of the spool file.
Subsequent Resp or KeepResp parcels return data starting from the beginning of the spool file.
This operation may occur at any point when reading a response.
This parcel is generated by CLI at the direction of the application.
Parcel Data
The following table lists field information for the Rewind parcel.
Flavor Field
Parcel Body
Length
Parcel Body Fields
31
0
none
RowPosition
Purpose
Requests that the Teradata SQL response be repositioned to a specified row.
Usage Notes
RowPosition is included in a Continue to reposition to a particular row in the response.
If present, the RowPosition parcel must immediately proceed either the
ExtendedKeepRespond or KeepRespond parcel.
Parcel Data
The following information applies to the RowPosition parcel.
Parcel
Flavor
Parcel Body
Length
Parcel Body Fields
158
12
Statement Number : 2 bytes
Unused : 2 bytes
Offset : 8 bytes
Run
Purpose
Establishes a connection between an application and Teradata SQL.
Usage Notes
The Run parcel is sent after a logon has been completed or when the application requires a
different partition in the Teradata Database.
314
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
This parcel is generated by CLIv2 on behalf of the application.
The response to a Run parcel is a RunResponse parcel.
Parcel Data
The following information applies to the Run parcel.
Flavor
Parcel
Body
Length
Parcel Body Fields
38
16
PartitionName: 16 bytes
Field Notes
PartitionName is the name of the partition to which start requests are to be sent. If the
application submits a partition name with less than 16 bytes, CLIv2 right-pads it with blanks.
Valid PartitionName values include the following:
Partition
Name
Purpose
DBC/SQL
For sending Teradata SQL statements.
RBM
For communicating with the Resolver Base Module.
MONITOR
For communicating with the Performance Monitor.
Note: The RBM and MONITOR partitions are valid only for Teradata Database for UNIX
version 2 release 2 (or later), and for Teradata DBS for TOS version 1 release 5 (or later).
RunResponse
Purpose
Tells the TDP where to send requests.
Usage Notes
The parcel appears as a response to the Connect and Run parcels, which establish a connection
between an application and Teradata SQL.
Parcel Data
The following information applies to the RunResponse parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
315
Chapter 9: Parcels
Parcel Descriptions
Flavor
Parcel Body
Length
Parcel Body Fields
39
18
StartRequest Mailbox:
6 bytes
ContinueRequest Mailbox:
6 bytes
AbortRequest Mailbox:
6 bytes
Field Notes
StartRequest Mailbox is the destination on the Teradata server for Start requests.
ContinueRequest Mailbox is the destination on the Teradata server for Continue requests.
AbortRequest Mailbox is the destination on the Teradata server for Abort requests.
RunStartup
Purpose
The RunStartup parcel executes the user’s startup request and returns the results in Record
Mode. If a startup request is not stored with the data base, the response parcel is an Error
parcel with error code 3747.
This parcel is generated by CLI at the direction of the application.
Parcel Data
The following table lists field information for the RunStartup parcel.
Flavor Field
Parcel Body
Length
Parcel Body Fields
2
0
none
SessionOptions
Purpose
The SessionOptions parcel sets various options for a session.
Parcel Data
The following table lists field information for the SessionOptions parcel.
316
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Flavor Field
Parcel Body
Length
114
10
Parcel Body Fields
Transaction
Semantics:
type = CHAR(1)
Mode:
type = CHAR(1)
Language
Conformance:
type = CHAR(1)
DateForm:
type = CHAR(1)
utilityWorkload:
type=CHAR(1)
unused:
5 bytes
Field Notes
Semantics specifies the semantics to be used for requests within a transaction.
Valid settings are:
Setting
Description
D
Default semantics
T
Teradata semantics
A
ANSI semantics
Mode indicates that the system is in non-2PC Mode.
Two-phase commit is available only for Teradata Database for UNIX version 2 release 2 (or
later), and for Teradata DBS for TOS version 1 release 5 (or later).
The valid settings are:
Setting
Description
2
Two-phase commit (2PC) mode.
N
Non-2PC Mode.
Conformance specifies whether or not SQL requests are to be checked for conformance with a
particular language definition.
Valid settings are:
Setting
Description
N
No conformance.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
317
Chapter 9: Parcels
Parcel Descriptions
Setting
Description
2
ANSI entry-level (FIPS 127-2).
3
ANSI intermediate-level (FIPS 127-3).
Note: FIPS 127-3 conformance is not supported by the Teradata Database for
UNIX release 2.0.
utilityWorkload specifies whether or not the proprietary CHECK WORKLOAD statement will
be used.
Setting
Description
0
Proprietary CHECK WORKLOAD statement will not be used.
1
Proprietary CHECK WORKLOAD statement will be used.
Setposition
Purpose
Client, while initiating a request, informs the Server that it might request for positioning of
response later, using this parcel.
Parcel
Flavor
Parcel Body
Length
Parcel Body Fields
157
0
None
Size
Purpose
Specifies the size of a returned field.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the Size parcel.
318
Flavor
Parcel Body
Length
Parcel Body Fields
26
2
MaxFldSize: 2 byte unsigned integer
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Field Notes
MaxFldSize is the maximum size of the field that will be returned in this same relative
position.
SizeEnd
Purpose
Delimits the end of a sequence of Size parcels that specifies the maximum size of each field
returned in Field Mode.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the SizeEnd parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
25
0
none
SizeStart
Purpose
Delimits the start of a sequence of Size parcels that specifies the maximum size of each field
returned in Field Mode.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the SizeStart parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
24
0
none
SP Options
Purpose
Provides options to be used when compiling the stored procedure.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
319
Chapter 9: Parcels
Parcel Descriptions
Usage Notes
This parcel is provided by the application for the first or only segmented data request in the
Initiate Request DBCAREA extension.
Parcel Data
Flavor
Parcel Body
Length
129
2
Parcel Body Fields
Print: 1 byte (unused)
SaveSPL: 1 byte
Field Notes
The SaveSPL field specifies whether or not the source text (DDL definition) of the stored
procedure is stored in the Teradata Database. An uppercase EBCDIC 'Y' indicates that they are
saved. An uppercase EBCDIC 'N' indicates that they are not.
StatementInformation
Purpose
Returned in response to a successfully executed Teradata SQL statement when
Return-statement-info 'Y' was specified (corresponding to the Options parcel (flavor 85)
Return-statement-info 'Y' option). If more data needs be returned than will fit into a single
StatementInformation parcel, multiple parcels will be returned.
Usage Notes
This parcel is generated by Teradata Database.
Parcel Data
The following information applies to the StatementInformation parcel.
Flavor
169
Parcel Body
Length
6 to
maximum
parcel size
Parcel Body Fields
Self-defining extensions: Six or more bytes
One or more self-defining extensions are present to convey situation-dependent information.
While the extensions may require more than one StatementInformation parcel, an extension
will be wholly contained in one parcel. The extensions fall into two types: those that describe
one or more items and those with an Information Layout of End-information that end related
extensions of the first type.
Note: When multiple extensions with different Information Ids are present, their order is
undefined so may change in the future.
320
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Each extension begins with the following fields:
Field
Length
Description
PBTILOUT
2 byte
unsigned
integer
Information Layout identifies the layout of the data following the
header, as one of the following:
1 Full-layout
2 Limited-layout
3 Statistic-layout
4 End-information
Note: To allow for future enhancement, other values must be
ignored.
PBTIID
2 byte
unsigned
integer
Information Id identifies the type of extension, as one of the
following:
1 Parameter (used only when DBCAREA Request-processing-
option is 'S' (Prepare mode supporting parameterized SQL)
(corresponding to the Options parcel (flavor 85) Function 'S'
option), which describes each item specified by a parameter
(indicated by question mark) in the SQL statement.
2 Query, which describes each item (field or column) returned by
an SQL SELECT statement.
3 Summary, which describes each summary item returned by a
WITH clause of an SQL SELECT statement.
4 Identity-column, which describes each item (field or column)
returned by an SQL INSERT statement, as requested by
DBCAREA Return-identity-data (corresponding to Options
parcel (flavor 85) IdentityColumnRetrieval)
5 Stored-procedure-Output, which describes each item returned by
a stored-procedure OUT or INOUT parameter.
6 Stored-procedure-resultSet, which describes each row returned
by a stored-procedure.
7 Estimated-processing, which provides an estimate of the
execution time for the statement.
Note: To allow for future enhancement, other values must be
ignored.
PBTILEN
2 byte
unsigned
integer
Information Length specifies the length of subsequent data in the
extension (does not include the length of the extension header).
Note: To allow for future enhancement, lengths longer than
expected, along with the additional data, must be ignored.
Full-layout
The Full-layout is used for Parameter, Query, Summary, Identity-column,
Stored-procedure-output, and Stored-procedure-resultSet information, when DBCAREA
Request-processing-option is 'P' (Prepare), 'S' (Prepare mode supporting parameterized
SQL), or 'B' (Prepare and Execute) (corresponding to the Options parcel (flavor 85) Function
'P', 'S', and 'B' options). Table 21 shows the Full-layout fields:
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
321
Chapter 9: Parcels
Parcel Descriptions
Table 21: Full-layout Fields
322
Field
Length
Description
PBTIFDB
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
Database-name consisting of the length in bytes of the name,
followed by that name in characters from the current session
character set. If the name does not apply in the SQL statement's
context or is not available, the length is zero and no name is
present. The maximum length of a name may be obtained using
the DBCHQE SQL-limits query.
PBTIFTB
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
Table, View, or Procedure name consists of the length in bytes of
the name, followed by that name in characters from the current
session character set. If the name does not apply in the SQL
statement's context or is not available, the length is zero and no
name is present. The maximum length of a name may be
obtained using the DBCHQE SQL-limits query.
PBTIFCN
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
Column, User-defined Function (UDF), User-defined Method
(UDM), Stored-procedure, or parameter name consists of the
length in bytes of the name, followed by that name in characters
from the current session character set. If the name does not
apply in the SQL statement's context or is not available, the
length is zero and no name is present. The maximum length of a
name may be obtained using the DBCHQE SQL-limits query.
PBTIFCP
2 byte unsigned
integer
The relative position of the column within the table, with the
first column having a value of '1'. If the value does not apply in
the SQL statement's context (for example, the item is an
expression) or is not available, a zero is present
PBTIFAN
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
AS-name consists of the length in bytes of the column name as
renamed by an SQL AS-clause, followed by that name in
characters from the current session character set. If the name
does not apply in the SQL statement's context or is not available,
the length is zero and no name is present.
PBTIFT
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
Column Title consists of the length in bytes of the title, followed
by that title in characters from the current session character set.
If the title does not apply in the SQL statement's context (for
example, the item is an expression) or is not available, the length
is zero and no title is present.
PBTIFF
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
Column Format consists of the length in bytes of the format,
followed by that format in characters from the current session
character set. If the format does not apply in the SQL statement's
context (for example, the item is an expression) or is not
available, the length is zero and no format is present.
PBTIFDV
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
Default Value consists of the length in bytes of the default,
followed by that default in characters from the current session
character set. If the default does not apply in the SQL statement's
context (for example, the item is an expression) or is not
available, the length is zero and no default is present.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Table 21: Full-layout Fields (continued)
Field
Length
Description
PBTIFIC
1 byte character
Set to an 'Y' if the column is an Identity Column; 'N' otherwise.
If an Identity column is not involved or the information is not
available, an ASCII 'U' is set.
PBTIFDW
1 byte character
Set to an ASCII 'Y' if the column is definitely writable (that is,
the user has permission to update the column); 'N' otherwise
(the item is not a column or the user's permission is
insufficient).
PBTIFNL
1 byte character
Set to an ASCII 'Y' if NULLs can be stored in item (columns not
defined NOT NULL); 'N' otherwise (for example, the item is an
expression). If this concept does not apply in the SQL
statement's context or the information is not available, an ASCII
'U' is set.
PBTIFMN
1 byte character
Set to an ASCII 'Y' if NULLs can be returned for the item; 'N'
otherwise. If this concept does not apply in the SQL statement's
context or the information is not available, anASCII 'U' is set.
PBTIFSR
1 byte character
Set to an ASCII 'Y' if the item is permitted in a WHERE SQL
clause; 'N' otherwise (for example, the result is a Large Object
(LOB)). If this concept does not apply in the SQL statement's
context or the information is not available, an ASCII 'U' is set.
PBTIFWR
1 byte character
Set to an ASCII 'Y' if the column is writable (the item is a
modifiable column); 'N' otherwise (for example, the item is an
expression).
PBTIFDT
2 byte unsigned
integer
Specifies the data type of the item returned. If the type is
ambiguous (for example, the item is a parameter in an
expression) or is not available, a zero is set. In addition to the
data types available for the PrepInfo[X] (flavor 86 or 125) and
DataInfo[X] (flavor 71 or 146) parcels, see Table 16 on page 256
for the possible data types in addition to those in Table 22 on
page 325.
PBTIFUT
2 byte unsigned
integer
For user-defined types, a binary 1 will be set for structured
types, 2 for distinct types, or 3 for internal types. If the type is
ambiguous (for example, a parameter in an expression) or is not
available, a zero is set.
PBTIFTY
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
Type Name consists of the length in bytes of the name, followed
by that name in characters from the current session character
set. If the name does not apply in the SQL statement's context
(for example, the type is not user-defined) or is not available, the
length is zero and no name is present. The maximum length of a
name may be obtained using the DBCHQE SQL-limits query.
PBTIFMI
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
Data Type Miscellaneous Information consists of the length in
bytes of the information, followed by that information in
characters from the current session character set. If the
information does not apply in the SQL statement's context (for
example, the type has no information) or is not available, the
length is zero and no information is present.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
323
Chapter 9: Parcels
Parcel Descriptions
Table 21: Full-layout Fields (continued)
Field
Length
Description
PBTIFMDL
8 byte unsigned
integer
The total number of bytes of data that might be returned for this
item.
PBTIFND
2 byte unsigned
integer
The total number of digits if the item has a decimal or numeric
data type. For other data types, a zero is returned.
PBTIFNID
2 byte unsigned
integer
The number of interval digits if the item is a temporal data type.
For other data types, a zero is returned.
PBTIFNFD
2 byte unsigned
integer
The number of fractional digits if the item is a decimal data type
(or the deprecated temporal types such as time, timestamp,
interval ... to second, and interval second). For other data types,
a zero is returned.
PBTIFCT
1 byte unsigned
integer
The character set type of the item, as either 1 if Latin, 2 if
Unicode, 3 if Japanese Shift-JIS, 4 if Graphic, or 5 if Japanese
Kanji1. If not character data, a zero is returned.
PBTIFMNC
8 byte unsigned
integer
The total number of characters returned for this item. A value of
zero is set if not character data.
PBTIFCS
1 byte unsigned
character
Set to an ASCII 'Y' if a character item is case sensitive (column
defined CASESPECIFIC); 'N' if not or not a character item. If
this concept does not apply in the SQL statement's context or the
information is not available, an ASCII 'U' is set.
PBTIFSN
1 byte unsigned
character
Set to an ASCII 'Y' if a numeric item is signed; 'N' if unsigned
(the BYTE data type) or not a numeric item. If this concept does
not apply in the SQL statement's context or the information is
not available, an ASCII 'U' is set.
PBTIFK
1 byte unsigned
character
Set to an ASCII 'Y' if the columns uniquely describes the row; 'N'
otherwise. If this concept does not apply in the SQL statement's
context or the information is not available, an ASCII 'U' is set.
PBTIFU
1 byte unsigned
character
Set to an ASCII 'Y' if the column is the only member of a unique
index; 'N' otherwise. If this concept does not apply in the SQL
statement's context or the information is not available, an ASCII
'U' is set.
PBTIFE
1 byte unsigned
character
Set to an ASCII 'Y' if the item is an expression; 'N' otherwise. If
this concept does not apply in the SQL statement's context or the
information is not available, an ASCII 'U' is set.
PBTIFSO
1 byte unsigned
character
Set to an ASCII 'Y' if the item is permitted in an ORDERBY SQL
clause; 'N' otherwise (for example, the result is a Large Object
(LOB)). If this concept does not apply in the SQL statement's
context or the information is not available, an ASCII 'U' is set.
Note: Due to the large number of variable-length fields (fields containing a length followed by that
amount of data), great care is required to process a Full-layout extensions. To locate a field requires
that the length of all previous variable-length fields be inspected.
324
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Table 22: PBTIFDT Additional Data Types
Name
Type if
non-nullable
Type if Nullable
Type if IN
parameter
Type if INOUT
parameter
Type if OUT
parameter
TIME
760
761
1260
1261
1262
TIMESTAMP
764
765
1264
1265
1266
TIME WITH TIME ZONE
768
769
1268
1269
1270
TIMESTAMP WITH TIME ZONE
772
773
1272
1273
1274
INTERVAL YEAR
776
777
1276
1277
1278
INTERVAL YEAR TO MONTH
780
781
1280
1281
1282
INTERVAL MONTH
784
785
1284
1285
1286
INTERVAL DAY
788
789
1288
1289
1290
INTERVAL DAY TO HOUR
792
793
1292
1293
1294
INTERVAL DAY TO MINUTE
796
797
1296
1297
1298
INTERVAL DAY TO SECOND
800
801
1300
1301
1302
INTERVAL HOUR
804
805
1304
1305
1306
INTERVAL HOUR TO MINUTE
808
809
1308
1309
1310
INTERVAL HOUR TO SECOND
812
813
1312
1313
1314
INTERVAL MINUTE
816
817
1316
1317
1318
INTERVAL MINUTE TO SECOND 820
821
1320
1321
1322
INTERVAL SECOND
824
825
1324
1325
1326
PERIOD (DATE)
832
833
1332
1333
1332
PERIOD (TIME)
836
837
1336
1337
1338
PERIOD (TIME WITH TIME
ZONE
840
841
1340
1341
1342
PERIOD (TIMESTAMP
844
845
1344
1345
1346
PERIOD (TIMESTAMP WITH
TIME ZONE)
848
849
1348
1349
1350
Note: These data types may not be used in DataInfo[X] (flavor 71 or 146) request parcels.
Limited-layout
The Limited-layout is used for Query, Summary, Identity-column, Stored-procedure-output,
and Stored-procedure-resultSet information, when DBCAREA Request-processing-option is
'E' (Execute) (corresponding to the Options parcel (flavor 85) Function 'E' option). Table 23
shows the Limited-layout fields.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
325
Chapter 9: Parcels
Parcel Descriptions
Table 23: Limited-layout Fields
Field
Length
Description
PBTILDT
2 byte unsigned
integer
Specifies the data type of the item returned. If the type is
ambiguous (for example, a parameter in an expression) or is not
available, a zero is set. In addition to the data types available for
the PrepInfo[X] (flavor 86 or 125) and DataInfo[X] (flavor 71 or
146) parcels, see Table 16 on page 256 for the possible data types
in addition to those in Table 22 on page 325.
PBTILMDL
8 byte unsigned
integer
The total number of bytes of data that might be returned for this
item.
PBTILND
2 byte unsigned
integer
The total number of digits if the item has a decimal or numeric
data type. For other data types, a zero is returned.
PBTILNID
2 byte unsigned
integer
The number of interval digits if the item is a temporal data type.
For other data types, a zero is returned.
PBTILNFD
2 byte unsigned
integer
The number of fractional digits if the item is a decimal data type
(or the deprecated temporal types such as time, timestamp,
interval ... to second, and interval second). For other data types, a
zero is returned.
Statistic-layout
The Statistic-layout is used for Estimated-processing information. The following table shows
the Statistic-layout fields.
Table 24: Statistic-layout Fields
Field
Length
Description
PBTISEE
8 byte unsigned
integer
The estimated execution time for the statement, in milliseconds.
End-information layout
The End-information layout indicates there are no more items for the current information
(Parameter, Query, Summary, Identity-column, Stored-procedure-output,
Stored-procedure-resultSet, or Estimated-processing). There is no data for End-information.
StatementInformationEnd
Purpose
Returned in response to a successfully executed Teradata SQL statement when Returnstatement-info 'Y' was specified (corresponding to the Options parcel (flavor 85) Returnstatement-info 'Y' option) to indicate that no more StatementInformation parcels (flavor 169)
exist.
326
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Usage Notes
This parcel is generated by Teradata Database.
Parcel Data
The following information applies to the StatementInformationEnd parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
170
0
none
Success
Purpose
Returned in response to a successfully executed Teradata SQL statement in MultipartIndicator,
or Indicator Response-mode when using other than Original Statement-status.
It also indicates successful completion of other types of requests (for example, a logon
request).
Usage Notes
If the activity type is 33 (Echo), an echo sequence follows.
If the Warninglength is zero, there may be some slack bytes following the Warninglength. If so,
they are added into the parcel length total.
This parcel is generated by Teradata Database.
Parcel Data
The following information applies to the Success parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
8
14 to 269
StatementNo:
byte unsigned integer
ActivityCount:
4 byte unsigned integer
WarningCode:
2 byte unsigned integer
FieldCount:
2 byte unsigned integer
ActivityType:
2 byte unsigned integer
WarningLength:
2 byte unsigned integer
WarningMsg:
0 to 255 bytes
Field Notes
The following notes apply to Success fields.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
327
Chapter 9: Parcels
Parcel Descriptions
•
StatementNo is the number of the Teradata SQL statement for which this is the first parcel
of a response.
•
ActivityCount is the total number of records selected, inserted, updated or deleted.
•
WarningCode is usually zero. If it is nonzero, it represents a comment on an operation that
was carried out.
•
FieldCount is the total number of fields returned in each record.
•
ActivityType is an encoded value representing the type of Teradata SQL statement that was
processed. Refer to “Activity Type” on page 257 for the possible activity types.
•
WarningLength is the length of the warning message. If WarningLength is zero, there is no
warning message. See the Messages manual for more information about any particular
code.
•
WarningMsg is the text of the warning message.
TitleEnd
Purpose
Delimits the end of a sequence of Field parcels that provides heading information for a
response.
Usage Notes
This parcel is generated by Teradata Database.
Parcel Data
The following information applies to the TitleEnd parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
21
0
none
TitleStart
Purpose
Delimits the start of a sequence of Field parcels that provides heading information for a
response.
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the TitleStart parcel.
328
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
Flavor
Parcel Body
Length
Parcel Body Fields
20
0
none
UserNameRequest
Purpose
Requests return of the userid assigned to the session.
Parcel Data
When present, this parcel must be placed immediately after the Connect parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
136
0
None
UserNameResponse
Purpose
Returns the userid assigned to the session.
Parcel Data
This parcel may appear anywhere before the only End-request parcel.
Flavor
Parcel Body
Length
137
Useridlength: 2
The Userid-length field is a two-byte unsigned integer
containing the number of bytes in the Userid field.
Userid: 1 to 90
The Userid field is a character string encoded in the character
set of the associated request, varies in length between 1 and 90
bytes, and contains the userid assigned to the session. The
length is contained in the Userid-length field.
Parcel Body Fields
VoteRequest
Purpose
Requests a vote in a 2PC session.
Usage Notes
Two-phase commit is available only for Teradata Database for UNIX version 2 release 2 (or
later), and for Teradata DBS for TOS version 1 release 5 (or later).
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
329
Chapter 9: Parcels
Parcel Descriptions
The vote request parcel can be sent alone, or in a message (at the end of a sequence of request
and data parcels that define a Teradata SQL statement).
If the vote request is sent in the same message as a Teradata SQL statement, then the request
follows the rules for a multi-statement request; that is, all statements succeed, or all fail.
If your program is using the Initiate with Protocol-Function with the vote protocol function,
then the VoteRequest parcel is included after the request and data parcels.
The response is one of the following:
•
A Success parcel, indicating that the Teradata Database voted Yes, and that the transaction
is now in-doubt.
•
A Failure parcel, indicating either that the Teradata Database has voted No and rolled the
transaction back, or that the session is not in 2PC mode. The error code in Failure parcel
indicates why the Teradata Database did not commit the transaction
Parcel Data
The following information applies to the VoteRequest parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
115
64
Coordinator (32 bytes)
RunUnitID (32 bytes)
Field Notes
•
The Coordinator field contains the text string name of the coordinator for the protocol.
The string consists of a two-byte length, followed by a 30-byte name.
•
The RunUnitID field contains a text string identifier of the run unit currently active for the
session.
The string consists of a two-byte length, followed by a 30-byte name.
VoteTerm
Purpose
Requests a vote-and-terminate action in a 2PC session.
The VoteTerm parcel either can be sent alone or in a message (at the end of a sequence of
request and data parcels that define a Teradata SQL statement).
Usage Notes
Two-phase commit is available only for Teradata Database for UNIX version 2 release 2 (or
later), and for Teradata DBS for TOS version 1 release 5 (or later).
If the VoteTerm parcel is used with updates that change existing data, it will always result in a
commit.
330
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 9: Parcels
Parcel Descriptions
If an immediate commit is not desired, use the VoteRequest parcel instead of the VoteTerm
parcel.
If the VoteTerm parcel is sent in the same message as a Teradata SQL statement, then the vote
and terminate request follows the rules for a multi-statement request (all statements succeed,
or all fail).
If your program is using the Initiate with Protocol-Function with the vote/terminate function,
then the VoteTerm parcel is included after the request and data parcels.
The response is one of the following:
•
A Success parcel indicating that the Teradata Database has committed the transaction
•
A Failure parcel indicating that the Teradata Database has rolled back the transaction or
that the session is not in 2PC mode.
The error code in the Failure parcel indicates why the Teradata Database could not commit
the transaction.
Parcel Data
The following information applies to the VoteTerm parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
116
0
none
With
Purpose
Delimits the start of a sequence of parcels that provides descriptors for the results of a
summary generated by a WITH clause.
Usage Notes
The WithId specifies the parcels that apply to the WITH clause.
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the With parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
33
2
WithID: 2 byte unsigned integer
Field Notes
WithId is the summary number (1-n) for this WITH clause.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
331
Chapter 9: Parcels
Parcel Descriptions
332
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 10
Response Sequences
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
The Request Buffer
Defined
CLI places information to be sent to the Teradata Database in a request buffer.
Allocating the Request Buffer
CLI allocates a single request buffer per session. The allocation takes place when the session is
first established.
DBCHCL automatically:
•
Expands the buffer if it is too small to hold the request being prepared.
•
Shrinks the buffer if Request Buffer Length is less than Current Request Buffer Length.
Set the size of the send queue buffer (through which data is sent to the Teradata Database
internally) with the environment variable TCP_BUF_SIZE.
Use environment variable COPANOMLOG to acquire log information and size values of the
send/receive queue buffer.
See Teradata Tools and Utilities Installation Guide for UNIX and Linux for information how to
set TCP_BUF_SIZE.
Values
DBCHCL uses field values that the application program has placed in the DBCAREA to
determine which parcels to send to the Teradata Database and what to put in them. The
application program does not see the request buffer.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
333
Chapter 10: Response Sequences
The Response Buffer
Maximum Length
The maximum length (in bytes) needed for the request buffer can be calculated as follows:
maximum Request Buffer Length =
(4 + the maximum length of a request string) +
(4 + the maximum length of using data,
including indicator bytes if User Presence
Bits is set to ‘Y’) +
(14 if Request Processing Option = P) +
(6 for overhead)
The first and fourth lines are always included in the calculation. The second line is included
only if data is being sent to the database. The third line is included only if Request Processing
Option = P.
The Response Buffer
Defined
Information received from the Teradata Database is placed in a buffer called the response
buffer.
Making It Available
DBCHCL uses the values of Locate Mode to determine whether to make the response parcels
available to the application:
•
In the response buffer(s) (Locate Mode = Y, referred to as Locate Mode), or
•
In the user specified Move area (Locate Mode = N and Parcel Mode = Y, referred to as
Move Mode)
Replenishing the Response Buffer
CLI automatically replenishes the response buffer(s). That is, the Teradata Database
application program may call DBCHCL for the Fetch function repeatedly. The response
buffer(s) may or may not be large enough to hold all the parcels in the response, but the
application program can draw on them as if they are.
If the application program calls DBCHCL for the Rewind function, the pointer that moves
back to the first parcel is a pointer in the response stored on a spool file in the Teradata
Database, not a pointer in the response stored in the response buffer(s). Therefore, if
rewinding may take place, it is important to operate with Keep Response set to Y, even if the
whole response actually can fit in the response buffer(s).
Set the receive queue buffer size by setting environment variable TCP_BUF_SIZE.
Use environment variable COPANOMLOG to get the log information to see the values of sizes
of send/receive queue buffer.
334
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
The Response Buffer
See the Teradata Tools and Utilities Installation Guide for UNIX and Linux for information how
to set TCP_BUF_SIZE.
Holding Error or Failure Parcels
The response buffer must be at least long enough to hold an Error parcel or Failure parcel, so
that the application program can detect a problem if it arises.
If the response buffer is not long enough for the longest parcel, CLI will grow the buffer to the
required size (if less than the maximum size) at the time it encounters the longest parcel. The
growth operation costs CPU time. If an application program is being optimized for
performance and Current Response Buffer Length is higher than Response Buffer Length,
consider increasing Response Buffer Length.
When the actual row size to be returned is:
•
Less than 32K and the response buffer is not large enough to hold a parcel, the Teradata
Database returns a 3116 error. In response to it, CLI will retry with a larger buffer size.
•
Greater than 32K and the response buffer is not large enough to hold a parcel, the Teradata
Database returns a 3115 error.
CLI will retry with a larger buffer size only if Maximum Parcel is set to H. If Maximum
Parcel is set to O, CLI will not retry the 3115 error with a larger buffer size, but will instead
return the 3115 error to the user. This prevents retry looping.
Sending “Buffer-fulls”
If all the parcels in the response do not fit in one response buffer, the Teradata Database first
sends one buffer-full of the response and later, as directed by CLI, sends the remaining
response one buffer-full at a time.
A buffer-full of parcels refers to the number of whole parcels that can fit in the buffer. Parcels
do not span buffers. As a rule of thumb, the larger the response buffer, the more efficient the
transmission of the response from the Teradata Database.
Setting Save Response Buffer
If Save Response Buffer is:
•
Set to N, CLI de-allocates the buffer(s) and Request Context Block when DBCHCL is
called for the End Request function.
•
Set to Y, CLI saves one response buffer and saves the Request Context Block when
DBCHCL is called for the End Request function. If the saved buffer is too small for the
next request, the saved buffer is deleted and a new buffer of the required size is allocated.
Double Buffering
If Two Response Buffers is set to Y in the DBCAREA, CLI uses double buffering, and each
buffer is the size specified in the DBCAREA. CLI allocates the buffer(s) when DBCHCL is
called for the Connect, RunStartup, or Initiate Request function.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
335
Chapter 10: Response Sequences
The Move Area
One Request at a Time
There are times when CLI sends a request to the Teradata Database for the next buffer-full of a
response and it conflicts with a more recent request of the Teradata Database. The rule is that
a session may have the Teradata Database active on its behalf for only one request at a time.
This applies to the requests the application knows about as well as to the re-stocking requests
done “behind the scenes.” If CLI is re-stocking response buffers, CLI will return “busy” from a
call to DBCHCL for the Fetch function if Wait For Response is “N.” This phenomenon is a
possibility when a new request has been “refused.”
Note: If CLIv2 is running a FastExport application that set a buffer length (using keyword
BLOCKSIZE in the FastExport script) that is too small, CLIv2 will automatically try to fix the
problem. The CLIv2 software, in this event, will expand the buffer by between 70 and 100
bytes, depending on parcel overhead. If the buffer expansion is sufficient, the FastExport job
will run to completion The database will return the error:
3691: Specified Buffer Size is too small in FastExport
only if the buffer remains too small after the expansion has taken place.
The Move Area
The Teradata Database application program may allocate a Move area. It is similar to the
response buffer but only needs to contain room for one parcel at a time.
If the application program has allocated a Move area, when the application program sends in a
request, it may specify in the DBCAREA that the Move area is to be used. In that case, each
time DBCHCL is called for the Fetch function, DBCHCL moves the next parcel, which is the
one the application program is about to use, into the Move area instead of making the parcel
available in the response buffer.
In some application languages, such as COBOL which does not support pointers, having the
next parcel separate is critical and easily worth the small use of space for the Move area and the
small loss of time for DBCHCL to do the copy.
In other application languages, such as C, PL/1, and IBM Assembler, reading the parcel
directly from the response buffer is no problem; but using a Move area may have an advantage
such as providing word alignment for the start of the Move area. Move Mode is primarily for
use in languages that do not support pointer operations.
Typical Response Sequences
Sending the Response
The Teradata Database generates one or more parcels in response to a request it receives. The
Teradata Database sends the Teradata SQL response in portions containing whole parcels. The
number of parcels in the portion is the maximum number that can fit in that request’s
response buffer.
336
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Typical Response Sequences
Screening the Response
Response parcels are screened by CLI before the application receives them. If a problem
develops and CLI is able to resolve it, the application may not see an error returned by the
database.
For example, if CLI screens an Error parcel which indicates that the response buffer is too
small, CLI will automatically expand the buffer and request that portion of the buffer again.
The application program will not know that the error existed and that it was resolved by CLI.
Consuming the Response
The application program can consume the response parcels by calling DBCHCL repeatedly
with the fetch function. As each parcel is encountered, the application must check whether it
is an Error or Failure parcel, even when the return code from the fetch is zero. A zero return
code only indicates that CLI and TDP have encountered no problems. To learn whether the
Teradata Database has detected problems, the parcel flavor must be checked.
Parcels That Indicate Problems
Problems encountered during the execution of a Teradata SQL request are signalled to the
application via the Error and Failure parcels (flavors 49 and 9, respectively). Whenever the
application program receives a response parcel, it is possible that it will be an Error or Failure
parcel, even if previous parcels were normal.
If Teradata Database does not know whether the request is complete, an Error parcel is
returned.
Error parcels and Failure parcels have the same field layout. The distinction lies in the action
taken by Teradata Database when the problem occurs.
What Error Parcels Indicate
An Error parcel indicates that a rollback did not take place for the problem. The transaction,
either implicit or explicit, in which the request was embedded is still active. However, the
request did not perform any action due to the error reported in the parcel.
What Failure Parcels Indicate
A Failure parcel indicates that the active transaction at the time of the error has been rolled
back. This includes any requests within the scope of the transaction that had been completed
successfully prior to the error.
Failures During Multi-Statement Requests
If a failure occurs during the processing of a multi- statement request, all statements within
the request, as well as the transaction, are rolled back. Statements that have not been executed
will be discarded.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
337
Chapter 10: Response Sequences
Response Sequences: Field Mode
Parcels in Normal Sequence
The sequence of the entire Teradata SQL response, called the spool file, as held on the Teradata
Database, contains a set of parcels for each Teradata SQL statement contained in it, and, last,
an EndRequest parcel:
set of parcels for statement 1
set of parcels for statement 2
Ø
EndRequest Parcel
The sections that follow contain the Teradata SQL response sequences for typical Teradata
SQL statements.
Note: To discover the Teradata SQL response sequence for a Teradata SQL statement that is
not included here: submit the Teradata SQL statement; call DBCHCL with the fetch function,
repeatedly, to see each parcel; and stop when the EndRequest parcel is encountered.
Response Sequences: Field Mode
If the Teradata SQL statement was submitted in Field Mode (Response Mode = F), the
response sequence for a successful statement will be as follows if the SQL statement is:
•
A non-data returning statement
Ok parcel (flavor 17)
if an insert, update or delete statement,
the activity code will reflect the number
of rows affected
all other non-data returning statements
will have an activity code of 0.
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
•
A data returning statement or SELECT statement with no WITH clause
Ok parcel (flavor 17)
activity count will reflect the number of
rows returned
TitleStart parcel (flavor 20)
Field parcel (flavor 18)
one field parcel for each column returned
TitleEnd parcel (flavor 21)
FormatStart parcel (flavor 22)
Field parcels (flavor 18)
one field parcel for each column returned
FormatEnd parcel (flavor 23)
SizeStart parcel (flavor 24)
Size parcel (flavor 26)
one size parcel for each column returned
SizeEnd parcel (flavor 25)
The following parcel sequence repeats activity count times
RecStart parcel (flavor 27)
Field parcels (flavor 18)
one field parcel for each column
338
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Response Sequences: Field Mode
returned
RecEnd parcel (flavor 28)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor12)
•
A SELECT statement having one or more WITH clauses
Ok parcel (flavor 17)
activity count will reflect the number of
rows returned
TitleStart parcel (flavor 20)
Field parcel (flavor 18)
one field parcel for each column returned
TitleEnd parcel (flavor 21)
FormatStart parcel (flavor 22)
Field parcels (flavor 18)
one field parcel for each column returned
FormatEnd parcel (flavor 23)
SizeStart parcel (flavor 24)
Size parcels (flavor 26)
one size parcel for each column returned
SizeEnd parcel (flavor 25)
The following parcel sequence repeats for each WITH clause
With parcel (flavor 33)
PosStart parcel (flavor 46)
Position parcel (flavor 34)
one position parcel for each column
in WITH
PosEnd parcel (flavor 47)
TitleStart parcel (flavor 20)
Field parcels (flavor 18)
one field parcel for each column in
WITH
TitleEnd parcel (flavor 21)
FormatStart parcel (flavor 22)
Field parcels (flavor 18)
one field parcel for each column
returned
FormatEnd parcel (flavor 23)
SizeStart parcel (flavor 24)
Size parcels (flavor 26)
one size parcel for each column
returned
SizeEnd parcel (flavor 25)
EndWith parcel (flavor 35)
The following parcel sequence repeats activity count times
RecStart parcel (flavor 27)
Field parcels (flavor 18)
one field parcel for each column
returned
RecEnd parcel (flavor 28)
With parcel (flavor 33)
RecStart parcel (flavor 27)
Field parcels (flavor 18)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
339
Chapter 10: Response Sequences
Response Sequences: Indicator Mode
one field parcel for each column in
WITH
RecEmd parcel (flavor 35)
EndWith parcel (flavor 35)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
•
An ECHO request
Ok parcel (flavor 17)
RecStart parcel (flavor 27)
Field parcel (flavor 18)
RecEnd parcel (flavor 28)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
Response Sequences: Indicator Mode
If the Teradata SQL statement was submitted in Indicator Mode (Response Mode = I), the
response sequence for a successful statement will be as follows if the SQL statement is:
•
A non-data returning statement
Success parcel (flavor 8)
if an insert, update or delete statement,
the activity code will reflect the number
of rows affected
all other non-data returning statements
will have an activity code of 0.
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
•
A data returning statement or SELECT statement with no WITH clause
Success parcel (flavor 8)
the activity code will reflect the number
of rows returned
DataInfo parcel (flavor 71)
Record parcels (flavor 10)
one record parcel for each row returned.
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
•
A Select statement having one or more WITH clauses
Success parcel (flavor 8)
activity count will reflect the number of
rows returned, including summary rows.
DataInfo parcel (flavor 71)
With parcel (flavor 33)
PosStart parcel (flavor 46)
Position parcel (flavor 34)
PosEnd parcel (flavor 47)
DataInfo parcel (flavor 71)
EndWith parcel (flavor 35)
Record parcel (flavor 10)
340
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Response Sequences: Multipart Indicator Mode
one record parcel for each row returned
With parcel (flavor 33)
one for each summary row
Record parcel (flavor 10)
EndWith parcel (flavor 35)
one for each summary row
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
•
An ECHO request
Success parcel (flavor 8)
Record parcel (flavor 10) in record-mode format
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
Response Sequences: Multipart Indicator Mode
If the Teradata SQL statement is submitted in MultipartIndicator mode (Response mode M),
the response parcels for a successful statement will be as follows:
•
•
If the SQL statement is a non-data returning statement, then:
•
Success parcel (flavor 8)
•
If an insert, update or delete statement, the activity code will reflect the number of
rows affected. All other non-data returning statements will have an activity code of 0.
•
EndStatement parcel (flavor 11)
•
EndRequest parcel (flavor 12)
If the SQL statement is a data returning or a SELECT statement with no WITH clause,
then:
•
Success parcel (flavor 8)
•
The activity code will reflect the number of rows returned.
•
DataInfoX parcel (flavor 146)
Note: The following occur, once for each row returned:
•
•
One or more MultipartRecord parcels (flavor 144)
•
and an EndMultipartRecord parcel (flavor 145)
•
EndStatement parcel (flavor 11)
•
EndRequest parcel (flavor 12)
If the SQL statement is a SELECT statement having one or more WITH clauses, then:
•
Success parcel (flavor 8)
•
Activity count will reflect the number of rows returned, including summary rows.
•
DataInfoX parcel (flavor 146)
•
With parcel (flavor 33)
•
PosStart parcel (flavor 46)
•
Position parcel (flavor 34)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
341
Chapter 10: Response Sequences
Response Sequences: Record Mode
•
PosEnd parcel (flavor 47)
•
DataInfo parcel (flavor 71)
•
EndWith parcel (flavor 35)
Note: The following occur, once for each row returned:
•
•
One or more MultipartRecord parcels (flavor 144)
•
and an EndMultipartRecord parcel (flavor 145)
•
With parcel (flavor 33)
•
One for each summary row
•
EndWith parcel (flavor 35)
•
One for each summary row
•
EndStatement parcel (flavor 11)
•
EndRequest parcel (flavor 12)
If the SQL statement is a an ECHO request, then:
•
Success parcel (flavor 8)
•
One or more MultipartRecord parcels (flavor 144) and
•
an EndMultipartRecord parcel (flavor 145)
•
EndStatement parcel (flavor 11)
•
EndRequest parcel (flavor 12)
Response Sequences: Record Mode
If the Teradata SQL statement is submitted in Record Mode (Response Mode = R), the
response parcels for a successful statement will be as follows.
If the SQL statement is:
•
A non-data returning statement
Success parcel (flavor 8)
if an insert, update or delete statement,
the activity code will reflect the number
of rows affected
all other non-data returning statements
will have an activity code of 0.
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
•
A data returning statement or SELECT statement with no WITH clause
Success parcel (flavor 8)
the activity code will reflect the number
of rows returned
Record Parcel (flavor 10)
one record parcel for each row returned
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
342
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Parcel Sequences
•
A SELECT statement having one or more WITH clauses
Success parcel (flavor 8)
the activity code will reflect the number
of rows returned, including the summary
rows
Record Parcel (flavor 10)
one record parcel for each row returned,
including the summary rows
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
With parcel (flavor 33)
one for each summary row immediately
preceding the Record parcel containing the
summary row.
EndWith parcel (flavor 35)
one for each summary row immediately
following the Record parcel containing the
summary row.
•
An ECHO request
Success parcel (flavor 8)
Record parcel (flavor 10)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
Parcel Sequences
CLI constructs the correct parcel sequences to the Teradata Database based on the
information supplied in the DBCAREA.
The application should only be concerned with the response parcels returned from the
Teradata Database via CLI.
Session Control: Logon
Usage Notes
•
If Connect Type = R and if Return Code field = 33 at the time of the FETch function for
the connect request, the response parcels do not have to be scanned.
•
If Connect Type = R and if Return Code field = 0, the parcel returned is either:
Failure parcel (flavor 9), or
Error parcel (flavor 49)
•
If Connect Type = C and if Return Code field = non-zero, the response parcels do not have
to be scanned.
•
If Connect Type = C and if Return Code field = 0, and there is a problem with establishing
the connection, the parcel returned is either:
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
343
Chapter 10: Response Sequences
Issuing Requests: Field Mode
Failure parcel (flavor 9), or
Error parcel (flavor 49)
•
If Connect Type = C and if Return Code field = 0, and the connection is successfully
established, the parcels returned are:
Success parcel (flavor 8), and
EndRequest parcel (flavor 12)
Issuing Requests: Field Mode
Field Mode requests may return the following parcels:
•
EndRequest (flavor 12)
•
EndStatement (flavor 11)
•
EndWith (flavor 35)
•
Error (flavor 49)
•
Failure (flavor 9)
•
Field (flavor 18)
•
FormatEnd (flavor 23)
•
FormatStart (flavor 22)
•
NullField (flavor 19)
•
Ok (flavor 17)
•
Position (flavor 34)
•
PosEnd (flavor 47)
•
PosStart (flavor 46)
•
RecEnd (flavor 28)
•
RecStart (flavor 28)
•
Size (flavor 26)
•
SizeEnd (flavor 25)
•
SizeStart (flavor 24)
•
TitleEnd (flavor 21)
•
TitleStart (flavor 20)
•
With (flavor 33)
The following examples assume successful completion of the request.
Table 25: Update Table1 Set Field1 = 999999;
344
Parcel
Flavor
Body
Ok
17
(1, 0, 23, 3, 0, 0)
EndStatement
11
(1)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Issuing Requests: Field Mode
Table 25: Update Table1 Set Field1 = 999999; (continued)
Parcel
Flavor
EndRequest
12
Body
Table 26: Select Field1 From Table1;
Parcel
Flavor
Body
Ok
17
(1, 1, 23, 1, 0, 0)
TitleStart
20
Field
18
TitleEnd
21
FormatStart
22
Field
18
FormatEnd
23
SizeStart
24
Size
26
SizeEnd
25
RecStart (1)
27
Field
18
RecEnd (1)
28
.
.
.
.
.
.
RecStart (23)
27
Field
18
RecEnd (23)
28
EndStatement
11
EndRequest
12
(title)
(format)
(size)
(data)
(data)
(1)
Table 27: Select Field1 From Table1 With Sum (FIELD1);
Parcel
Flavor
Body
Ok
17
(1, 1, 24, 1, 0, 0)
TitleStart
20
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
345
Chapter 10: Response Sequences
Issuing Requests: Field Mode
Table 27: Select Field1 From Table1 With Sum (FIELD1); (continued)
346
Parcel
Flavor
Body
Field
18
(title)
TitleEnd
21
FormatStart
22
Field
18
FormatEnd
23
SizeStart
24
Size
26
SizeEnd
25
With
33
PosStart
46
Position
34
PosEnd
47
TitleStart
20
Field
18
TitleEnd
21
FormatStart
22
Field
18
FormatEnd
23
SizeStart
24
Size
26
SizeEnd
25
EndWith
35
RecStart (1)
27
Field
18
RecEnd (1)
28
.
.
.
.
.
.
RecStart (23)
27
Field
18
(format)
(size)
(1)
(1)
(title)
(format)
(size)
(1)
(data)
(data)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Issuing Requests: Field Mode
Table 27: Select Field1 From Table1 With Sum (FIELD1); (continued)
Parcel
Flavor
Body
RecEnd (23)
28
With
33
(1)
Field
18
(data)
EndWith
35
(1)
EndStatement
11
(1)
EndRequest
12
Table 28: Select Field1 From Table1; Select Field2 From Table2;
Parcel
Flavor
Body
Ok
17
(1, 1, 23, 1, 0, 0)
TitleStart
20
Field
18
TitleEnd
21
FormatStart
22
Field
18
FormatEnd
23
SizeStart
24
Size
26
SizeEnd
25
RecStart (1)
27
Field
18
RecEnd (1)
28
.
.
.
.
.
.
RecStart (23)
27
Field
18
RecEnd
28
EndStatement
11
(1)
Ok
17
(2, 1, 10, 1, 0, 0)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
(title)
(format)
(size)
(data)
(data)
347
Chapter 10: Response Sequences
Issuing Requests: Field Mode
Table 28: Select Field1 From Table1; Select Field2 From Table2; (continued)
Parcel
Flavor
TitleStart
20
Field
18
TitleEnd
21
FormatStart
22
Field
18
FormatEnd
23
SizeStart
24
Size
26
SizeEnd
25
RecStart (1)
27
Field
18
RecEnd (1)
28
.
.
.
.
.
.
RecStart (10)
27
Field
18
RecEnd (10)
28
EndStatement
11
EndRequest
12
Body
(title)
(format)
(size)
(data)
(data)
(2)
Table 29: Echo ‘Select Field1 From Table1’;
348
Parcel
Flavor
Body
Ok
17
(1, 1, 0, 33, 0, 0)
RecStart
27
Field
18
RecEnd
28
EndStatement
11
EndRequest
12
(data)
(1)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Issuing Requests: Indicator Mode
Issuing Requests: Indicator Mode
Indicator Mode requests may return the following parcels:
•
DataInfo (flavor 71)
•
EndRequest (flavor 12)
•
EndStatement (flavor 11)
•
EndWith (flavor 35)
•
Error (flavor 49)
•
Failure (flavor 9)
•
PosEnd (flavor 47)
•
Position (flavor 34)
•
PosStart (flavor 46)
•
Record (flavor 10)
•
Success (flavor 8)
•
With (flavor 33)
The following examples assume successful completion of the request.
Table 30: Update Table1 Set Field1 = 999999;
Parcel
Flavor
Body
Success
8
(1, 23, 0, 0, 3, 0)
EndStatement
11
(1)
EndRequest
12
Table 31: Select Field1 From Table1;
Parcel
Flavor
Body
Success
8
(1, 23, 0, 1, 1, 0)
DataInfo
71
(1, 496, 4)
Record (1)
10
(ind, data)
.
.
.
.
.
.
.
.
.
Record (23)
10
(ind, data)
EndStatement
11
(1)
EndRequest
12
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
349
Chapter 10: Response Sequences
Issuing Requests: Indicator Mode
Table 32: Select Field1 From Table1 With Sum (Field1);
Parcel
Flavor
Body
Success
8
(1, 24, 0, 1, 1, 0)
DataInfo
71
(1, 496, 4)
With
33
(1)
PosStart
46
Position
34
PosEnd
47
DataInfo
71
(1, 496, 4)
EndWith
35
(1)
Record (1)
10
(ind,data)
.
.
.
.
.
.
.
.
.
Record (23)
10
(ind,data)
With
33
(1)
Record
10
(ind,data)
EndWith
35
(1)
EndStatement
11
(1)
EndRequest
12
(1)
Table 33: Select Field1 From Table1; Select Field2 From Table2;
350
Parcel
Flavor
Body
Success
8
(1, 23, 0, 1, 1, 0)
DataInfo
71
(1, 496, 4)
Record (1)
10
(ind.data)
.
.
.
.
.
.
.
.
.
Record (23)
10
(ind.data)
EndStatement
11
(1)
Success
8
(2, 10, 0, 1, 1, 0)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Issuing Requests: Multipart Indicator Mode
Table 33: Select Field1 From Table1; Select Field2 From Table2; (continued)
Parcel
Flavor
Body
DataInfo
71
(2, 496, 4)
Record (1)
10
(ind,data)
.
.
.
.
.
.
.
.
.
Record (10)
10
(data)
EndStatement
11
(2)
EndRequest
12
Table 34: Echo ‘Select Field1 From Table1’;
Parcel
Flavor
Body
Success
8
(1, 0, 0, 1, 33, 0)
Record
10
(echoed string)
EndStatement
11
(1)
EndRequest
12
Issuing Requests: Multipart Indicator Mode
MultipartIndicator Mode requests may return the following parcels:
•
DataInfoX 146
•
EndMultipartRecord 145
•
EndRequest 12
•
EndStatement 11
•
EndWith 35
•
Error 49
•
Failure 9
•
MultipartRecord 144
•
PosEnd 47
•
Position 34
•
PosStart 46
•
Success 8
•
With 33
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
351
Chapter 10: Response Sequences
Issuing Requests: Multipart Indicator Mode
Examples
The following examples assume successful completion of the request.
Example 1
UPDATE TABLE1 SET FIELD1 999999
Parcel
Flavor
Parcel Body Fields
Success
8
(1, 23, 0, 0, 3, 0)
EndStatement
11
(1)
EndRequest
Example 2
Select field1 from table1
Parcel
Flavor
Parcel Body Fields
Success
8
(1, 23, 0, 0, 3, 0)
DataInfox
146
(1, 496, 4)
Multipart record
for row 1
144
(indicator, data)
End Multipart Record
145
Multipart record
for row 2
144
End Multipart Record
145
End Statement
11
End Request
10
(indicator, data)
Example 3
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
352
Parcel
Flavor
Parcel Body Fields
Success
8
(1, 23, 0, 0, 3, 0)
DataInfox
146
(1, 496, 4)
With
33
(1)
PosStart
46
Position
34
1
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Issuing Requests: Multipart Indicator Mode
Parcel
Flavor
Parcel Body Fields
PosEnd
47
DataInfox
146
(1, 496, 4)
EndWith
35
(1)
Multipart record
for row 1
144
(indicator, data)
End Multipart Record
145
Multipart record
for row 2
144
End Multipart Record
145
with
33
(1)
Multipart record
144
(indicator, data)
End Multipart Record
145
EndWith
35
(1)
End Statement
11
(1)
End Request
10
(indicator, data)
Example 4
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
Parcel
Flavor
Parcel Body Fields
Success
8
(1, 23, 0, 0, 3, 0)
DataInfox
146
(1, 496, 4)
Multipart record
for row 1
144
(indicator, data)
End Multipart Record
145
Multipart record
for row 2
144
End Multipart Record
145
End Statement
11
Success
8
(1, 23, 0, 0, 3, 0)
DataInfox
146
(1, 496, 4)
Multipart record
for row 1
144
(indicator, data)
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
(indicator, data)
353
Chapter 10: Response Sequences
Issuing Requests: Record Mode
Parcel
Flavor
End Multipart Record
145
Multipart record
for row 2
144
End Multipart Record
145
End Statement
11
End Request
10
Parcel Body Fields
(indicator, data)
(1)
Example 5
ECHO “SELECT FIELD1 FROM TABLE1”
Parcel
Flavor
Parcel Body Fields
Success
8
(1, 0, 0, 1, 33, 0)
Multipart record(s)
144
(ind, data)
EndMultipartRecord
145
End Statement
11
End Request
10
(1)
Issuing Requests: Record Mode
Record Mode requests may return the following parcels:
•
EndRequest (flavor 12)
•
EndStatement (flavor 11)
•
EndWith (flavor 35)
•
Error (flavor 49)
•
Failure (flavor 9)
•
Record (flavor 10)
•
Success (flavor 8)
•
With (flavor 33)
The following tables are examples that assume successful completion of the request. For a
description of the contents of a parcel body, see “Initiate-request Extensions” on page 175.
354
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 10: Response Sequences
Issuing Requests: Record Mode
Table 35: Update Table1 Set Field1=999999;
Parcel
Flavor
Body
Success
8
(1, 23, 0, 0, 3, 0)
EndStatement
11
(1)
EndRequest
12
Table 36: Select Field1 From Table1;
Parcel
Flavor
Body
Success
8
(1, 23, 0, 1, 1, 0)
Record (1)
10
(data)
.
.
.
.
.
.
.
.
.
Record (23)
10
(data)
EndStatement
11
(1)
EndRequest
12
Table 37: Select Field1 from Table1 With Sum (Field1);
Parcel
Flavor
Body
Success
8
(1, 24, 0, 1, 1, 0)
Record (1)
10
(data)
.
.
.
.
.
.
.
.
.
Record (23)
10
(data)
With
33
(1)
Record
10
(data)
EndWith
35
(1)
EndStatement
11
(1)
EndRequest
12
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
355
Chapter 10: Response Sequences
Issuing Requests: Record Mode
Table 38: Select Field1 From Table1; Select Field2 From Table2;
Parcel
Flavor
Body
Success
8
(1, 23, 0, 1, 1, 0)
Record (1)
10
(data)
.
.
.
.
.
.
.
.
.
Record (23)
10
(data)
EndStatement
11
(1)
Success
8
(2, 10, 0, 1, 1, 0)
Record (1)
10
(data)
.
.
.
.
.
.
.
.
.
Record (10)
10
(data)
EndStatement
11
(2)
EndRequest
12
Table 39: Echo ‘Select Field1 From Table1’;
356
Parcel
Flavor
Body
Success
8
(1, 0, 0, 1, 33, 0)
Record
10
(echoed string)
EndStatement
11
(1)
EndRequest
12
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 11
Return, Error, and Failure Codes
This chapter provides:
•
General information about codes
•
Specific information about:
•
•
Return codes
•
Error codes
•
Failure codes
Information about the source, timing, and types of codes.
Code Sources
There are two sources of codes:
•
On the client computer
•
For the Teradata Database
Return codes are generated by the client software. The value that is returned as a return code
from a CLI routine is generated by the CLI routine itself or is passed back from some other
client-resident module used by the CLI routine. For a full list of CLI error messages and
remedies, see the Messages manual.
Error codes and failure codes are generated by Teradata Database.
Return Code Values and Code Types
Client software uses the return code to provide information about the operation as seen on
the client.
What Code Values Mean
A return code of zero is normal, and a return code of non-zero represents an exception.
A code’s value represents the answer to a particular repeat of a particular operation. For
example, suppose CLI is restocking the response buffer and the Teradata Database is unable to
provide more of the response because the database computer has restarted. The application
program would then discover a Failure parcel in the response buffer after a number of normal
parcels.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
357
Chapter 11: Return, Error, and Failure Codes
Return Code Values and Code Types
Information Messages
Some values represent information messages. For instance, if an application program calls
DBCHCL for the Fetch function and the response buffer is in the process of being restocked,
the program will get a return code indicating that the data is not yet available. The application
program merely fetches again either immediately or after calling DBCHWAT, depending on
the technique used.
Problem Messages
Some values represent problems from which the application can be programmed to recover.
Other values represent problems from which the application cannot recover on its own.
For example, the return code EM_PUBENCRYPT indicates that the public encryption routine
failed. The programmer would need to contact the system administrator to check on these
conditions.
Coding Messages
Some values represent coding problems. For instance, one return code indicates that an illegal
combination of processing options has been set. The programmer must change the program
to use a legal combination.
For return codes, see the Messages manual.
Return Codes That Do Not Reach the Application
Some return codes do not reach the application. For example, EM_BUFSIZE (203) is detected
and corrected by CLI without the application’s intervention. Or again, the EM_NODATA
(211) and EM_DATAHERE (212) return codes are alternates, but CLI filters out
EM_DATAHERE; the application must therefore test for EM_DATAHERE by testing for the
absence of EM_NODATA.
At times, application programs may print, to stderr, messages that have the word net/oserr
and a number code. The code shown is generated by MOSI and the message is formatted by
MTDP.
Timing of Return Codes
Return codes are generated at several steps in the process of submitting a request and
consuming the response. Each return code represents the outcome of a given step in the
process.
Examples
A return code of zero from DBCHCL for the Initiate Request function indicates that the client
has sent the request toward the Teradata Database.
If DBCHWAT is used, a return code of zero indicates that a portion of the response to some
request has been received from the Teradata Database; and a return code of zero from
DBCHCL for the Fetch function indicates that the software has set a pointer to the next
358
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 11: Return, Error, and Failure Codes
Error and Failure Codes
information in the response buffer. No one return code stands as a summary of all stages in
the processing.
Similarly, a return code does not represent all repeats of a process. For example, a repeated call
to DBCHCL for the Fetch function may generate many return codes of zero and later generate
a non-zero return code if the application program continues to ask for the next parcel in the
response after consuming the final parcel.
Error and Failure Codes
Software for the Teradata Database uses error codes and failure codes to provide information
about the operation as seen on the database computer.
•
The absence of an Error parcel represents an error code of zero.
•
The absence of a Failure parcel represents a failure code of zero.
An Error parcel or Failure parcel contains a non-zero code and represents an exception.
Saving the Request
The application program should save the current Teradata SQL request and any Teradata SQL
request for which the Teradata SQL response is being held on the Teradata Database in case
they must be re-submitted.
If a transaction spans across more than one request, all the requests should be saved, in case
the transaction must be re-submitted.
Responding to Error and Failure Parcels
The guidelines for responding to the Error and Failure parcel codes are shown in Table 40:
Table 40: Error and Failure Codes
Code
Message
Action
Failure Code 2631
transaction aborted due to
deadlock
Re-submit the transaction.
Failure Code 2639
sorry, too many simultaneous
transactions
Re-submit the request.
Failure Code 2641
databasename.tablename was
restructured. Resubmit
transaction.
Re-submit the transaction.
Error Code 2825
no record of the last request
was found after DBC restart
Re-submit the Teradata SQL request.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
359
Chapter 11: Return, Error, and Failure Codes
Checking Both Code Sources
Table 40: Error and Failure Codes (continued)
Code
Message
Action
Error Code 2826
request completed but all
output was lost due to DBC
restart
Whether or not the original Teradata SQL
request should be re-submitted to obtain
the response depends on the nature of the
request. For instance, if the request was to
display certain data, the original request
can safely be re-submitted; if the request
was to multiply the values in a column by
10 and the request is re-submitted, the
column will in effect have been multiplied
by 100, so it is not safe to re-submit the
original request.
Failure Code 2827
request was aborted by user or
due to statement error
The circumstances may not warrant resubmitting anything at all; however, if resubmission is appropriate, re-submit the
transaction.
Failure Code 2828
request was rolled back during
system recovery
The transaction was lost due to a crash; resubmit the transaction.
Failure Code 2835
a unique index has been
invalidated; resubmit
transaction
Re-submit the transaction.
Failure Code 3111
the transaction has been timed Re-submit the transaction.
out
Error Code 3116
response buffer size is
Enlarge the response buffer and then
insufficient to hold one record submit a fetch. This code should be taken
care of by CLI in CLI. It should not be
seen by the application.
Failure Code 3120
the request is aborted because
of a DBC recovery
Re-submit the transaction.
Failure Code 3598
concurrent change conflict on
data base -- try again
Re-submit the transaction.
Failure Code 3603
concurrent change conflict on
table -- try again
Re-submit the transaction.
Failure Code 3897
request aborted due to DBC
system crash. Resubmit
Re-submit the transaction.
If any other code appears, stop the program and investigate the problem.
The official list of valid codes is in the Messages manual.
Checking Both Code Sources
There are times when both client and the Teradata Database sources must be checked.
360
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 11: Return, Error, and Failure Codes
Checking Both Code Sources
For example, on a call to DBCHCL for the Fetch function, a return code of zero indicates that
the client software has set a pointer to information in the response buffer. But not until the
information is examined does the application program know what the Teradata Database “has
to say.” The return code may be zero and the parcel successfully pointed to may be a Failure
parcel.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
361
Chapter 11: Return, Error, and Failure Codes
Checking Both Code Sources
362
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 12
Crash and Recovery
This chapter discusses:
•
How the Teradata Database handles crashes
•
What MTDP does during a crash
•
The AP Reset Containment (APRC) feature
•
What the application may do during a crash, including are two crash, or AP reset-related,
processing options in the DBCAREA
Handling Crashes
If the Network-Attached System Crashes
If a network-attached system crashes, the Teradata Database handles the crash as if every
session from that client had called DBCHCL for the Disconnect function.
If An Internal Error is Detected
When the Teradata Database detects an internal error that prevents it from continuing, it will
store diagnostic information and re-initialize itself. This event is called a crash or reset. After
the Teradata Database has re-initialized, it rolls back any incomplete transactions or requests
in progress. This process is called database recovery.
What the Teradata Database Does
When an application is running and the Teradata Database crashes:
•
Teradata Database sessions and session ids are preserved, and can continue to be used.
•
All outstanding Teradata Database transactions are aborted and all of the databases
involved are rolled back to the state they would have been in if the transactions had not
begun.
•
All requests that have not completed are aborted and any work they have performed is
rolled back.
•
All spool files, including those the Teradata Database has kept for completed requests, are
discarded.
•
Applications already waiting for a response before the crash/recovery occurs will be
notified (see “What MTDP Does” on page 364).
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
363
Chapter 12: Crash and Recovery
What MTDP Does
•
Applications submitting a request during the crash and recovery process may be notified,
see “What MTDP Does” on page 364.
•
Applications later using the abort, fetch, rewind, or end request function for a Teradata
SQL request aborted by the crash/recovery process, or submitting a new request in a
transaction that was in progress when the crash occurred and thus was aborted in the
recovery process, will be notified, see “What MTDP Does” on page 364.
•
If a restart occurs during a logoff request, CLI automatically resubmits the request.
What MTDP Does
When MTDP is informed that the network or the Teradata Database is down, it checks the
setting of the selfrecov option in the MTDP Control Block.
•
If it is off, MTDP will exit with an error message indicating that the session has crashed
•
If it is on, MTDP will continuously attempt to restore the virtual circuit and continue with
the transaction.
Recovery Flags
From DBCHCL, the method of recovery is controlled by two options flags:
1
Recovery flag, which determines whether MTDP should be allowed to try to automatically
reconnect the session
2
Report option, which determines if the crash should be reported to the application
If a crash occurs for a transaction with a recovery flag set to N, MTDP is not allowed to
reconnect automatically and an error message is returned to the application, regardless of the
setting of the report option.
If the recovery option is set to Y, an automatic recovery will only be attempted if the report flag
is set to N, or the session state flag maintained in the SCB indicates the session was already
crashed and the report flag is Y.
If the session was not crashed, the recovery flag was Y and the report flag was Y, an error
message is returned to the application. The application would normally turn the report flag
off and redrive the transaction to reconnect the session.
Any time MTDP returns an error indicating the session crashed, the state flag of the associated
SCB is set to reflect that the session is no longer connected to the Teradata Database.
AP Reset Containment (APRC)
APRC’s Value
AP Reset Containment (APRC), a user-transparent feature available on AP-based hardware
configurations running application programs and Teradata Database utilities, restricts the
364
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 12: Crash and Recovery
What the Application May Do
number of database restarts triggered by AP Resets to only those occurrences where a restart is
essential.
The estimated net result of this implementation is to eliminate about 75 percent of database
restarts initiated by AP Resets.
Before APRC was implemented, a database restart was automatically triggered whenever an
active AP in the current configuration was reset.
In the case of a resetting AP, there is a short delay while reconnects through other APs are
performed, but the longer delay usually associated with a database restart is not necessary.
Crash Option Aliases
The crash options formerly in use will now appear on systems with the APRC feature under
aliases.
The aliases Tell About Delay and Wait Across Delay can substitute for Tell About Crash and
Wait Across Crash, without actually replacing them.
Aliasing in this manner avoids the need to modify applications.
What APRC Does
When APRC is enabled, applications using multiple sessions will receive a database restart/AP
Reset indication on some, none or all sessions, depending on the APs through which the
sessions are connected.
In this way, if an application has session(s) connected through the resetting AP, the
application can treat the AP reset either as a database restart or just reconnect the lost sessions.
Applications that do not have session(s) connected through the resetting AP will not be
affected by the resetting AP.
If an application using CLIv2 was initiated locally on a resetting AP, the application will be
lost. Manual intervention will be necessary to restart the program.
Enabling/Disabling APRC
An AP Reset Containment Configuration utility, APRCConfig, provides the capability to
enable or disable APRC via console.
What the Application May Do
There are two crash, or AP reset-related, processing options in the DBCAREA:
•
Tell About Crash (or Tell About Delay), and
•
Wait Across Crash (or Wait Across Delay)
The following subsections describe the three combinations that are allowed.
The setting of Wait For Response has no effect on the processing shown below.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
365
Chapter 12: Crash and Recovery
Case 1: Tell and Wait
Case 1: Tell and Wait
After calling DBCHINI, set the crash/delay options as follows:
•
Tell About Crash (or Tell Across Crash) to Y
•
Wait Across Crash (or Wait Across Delay) to Y
Given this combination of options, a Teradata Database crash or AP reset can be handled as
follows:
1
The application program calls DBCHCL for some function.
2
The Teradata Database crashes or an AP resets before or after receiving information from
DBCHCL.
3
CLI returns control to the application program, with return code of EM_DBC_CRASH_B
or EM_DBC_CRASH_A.
4
The application program can tell its user of the possible crash/delay and can ask the user
whether to wait or disconnect.
5
Assuming a wait, the application program calls DBCHCL for the fetch function.
6
Teradata Database restarts or AP reset completes.
7
The application obtains results of the Fetch:
8
•
Teradata Database does not know anything about a request with that request number
(Error parcel with error code 2825)
•
Teradata Database aborted that request (Failure parcel with failure code 2828)
•
The request completed successfully but the response has been lost (Error parcel with
error code 2826)
The application program takes action appropriate to the application.
Before submitting a request, save a copy of the request in case it must be re-submitted. If a
transaction spans several requests, save a copy of each request in the transaction in case the
transaction must be re-submitted.
Note: Tell and wait may be useful to terminal-oriented applications to distinguish excessive
response time from the unlikely, but possible, Teradata Database crash or AP reset.
Case 2: Just Wait
After calling DBCHINI, set the crash/delay options as follows:
•
Tell About Crash (or Tell About Delay) to N
•
Wait Across Crash (Wait Across Delay) to Y
Given this combination, the steps if a Teradata Database crash/delay occurs are:
366
1
The application program calls DBCHCL for some function.
2
The system crashes or an AP resets before or after receiving information from DBCHCL.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 12: Crash and Recovery
Case 3: Just Tell
3
The application program is not notified of crash or reset and does not gain control.
4
The database system restarts or an AP reset completes.
5
The application program regains control from CLI with a return code of EM_OK (0).
6
When the application program calls DBCHCL for the Fetch function, it obtains
7
•
The Teradata Database does not know anything about a request with that request
number (Error parcel with error code 2825).
•
The Teradata Database aborted that request (Failure parcel with failure code 2828).
•
The request completed successfully but the response has been lost (Error parcel with
error code 2826).
The application program takes action appropriate to the application.
Before submitting a request, save a copy of the request in case it must be re-submitted. If a
transaction spans several requests, save a copy of each request in the transaction in case the
transaction must be re-submitted.
If a restart occurs during a logoff request, CLI automatically resubmits the request.
Note: The setting of Wait For Response has no effect on the processing shown above.
Case 3: Just Tell
After calling DBCHINI, set the crash/delay options as follows:
•
Tell About Crash (or Tell About Delay) to Y
•
Wait Across Crash (or Wait Across Delay) to N
Given this combination of options, a Teradata Database crash or AP reset can be handled as
follows:
1
The application program calls DBCHCL for some function.
2
The Teradata Database crashes or an AP resets before or after receiving information from
DBCHCL.
3
CLI returns control to the application program, with return code of EM_DBC_CRASH_B
or EM_DBC_CRASH_A.
4
The application program takes action appropriate to the application.
Before submitting a request, save a copy of the request in case it must be re-submitted. If a
transaction spans several requests, save a copy of each request in the transaction in case the
transaction must be re-submitted.
Tell and wait may be useful to terminal-oriented applications to distinguish excessive response
time from the unlikely, but possible, Teradata Database crash or AP reset.
Note: The application program may set Wait Across Crash to Y and proceed as in Tell and
Wait.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
367
Chapter 12: Crash and Recovery
Case 3: Just Tell
368
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 13
Stored Procedures
This chapter describes:
•
Introduction
•
Description
•
Response Processing
•
Abort, Cancel, and Restart Processing
•
Effects on Other Options
See SQL Fundamentals for additional information on stored procedures.
Introduction
It is possible to store executable procedures in the Teradata server and invoke them later using
the SQL CALL statement. Stored procedures consist of statements written in Stored Procedure
Language (SPL).
Description
If...
Then...
stored procedures are
not supported
the service will fail (return code 374).
are supported
a four-byte unsigned binary value is returned that indicates the maximum
size of a data segment (in bytes).
In such cases, if the size of the stored procedure exceeds this value, it must
be sent as multiple requests, each of which sends data no larger than this
value.
The application sends the statements comprising a procedure to the server, where they are
compiled and saved for subsequent execution. The application that creates the procedure
must do the following:
1
Ascertain whether the Teradata server supports stored procedures.
2
Send a request containing the procedure that could exceed the maximum parcel size.
3
Provide compilation options to the server.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
369
Chapter 13: Stored Procedures
Send Procedure to Server
To ascertain whether the Teradata server supports stored procedures, the CLIv2 Query service
obtains the Server Maximum Segment Size. Based on the results returned by the Query
service, one of the actions described in the next sections occurs.
Send Procedure to Server
The stored procedure is sent to the Teradata server in one or more segments using either the
Initiate Request, or the Initiate With Protocol Function CLIv2 function.
The Server Maximum Segment Size CLIv2 query obtains the maximum size of each segment.
Use of segments is indicated by the CLIv2 Segment Data option (with the Change Options
option set to 'Y').
The application divides the text of the stored procedure into pieces no larger than the
maximum segment size, and sends each piece as a separate request (the text may be divided at
any point). The first piece is identified using the Segment Data option as the first segment.
The last (or only) piece is identified as the last segment; all other pieces are identified as
intermediate segments.
Response Processing
After each segment is sent, its response should be processed as usual for any CLIv2 request.
Depending on the response parcel, one of the following actions occurs:
If this response parcel is returned...
Then...
Failure
any previous segments have been discarded by the server.
Error
any previous segments have been retained by the server,
and the failing request may be retried (if possible).
Such retry is not possible if other segments were sent
before fetching the response containing the error.
Success (if Record, Indicator, or
Extended Indicator mode)
or
OK (if Field mode)
the next segment can be sent.
When all segments have been sent, the stored procedure is compiled, and any compilation
messages are returned. If the value of the Success or OK parcel Warning Code field is 5527,
then compilation was successful but warning messages were returned; if the value is 5526, then
compilation was not successful and error messages are returned. In both cases, the Success or
OK parcel Activity Count field indicates the number of messages.
370
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 13: Stored Procedures
Abort, Cancel, and Restart Processing
The format of the messages depends upon the CLIv2 Response Mode Option. For Field mode,
each message is treated as a separate row consisting of a single VARCHAR column. For
Record, Indicator, and Extended Indicator modes, each message is in a separate Data parcel.
Abort, Cancel, and Restart Processing
Anytime a segment request is active, the CLIv2 Abort function may be used to abort
processing.
Anytime a segment request is not active and before sending the last segment, processing may
be cancelled by setting the appropriate Segment Data option and initiating another request
(the Request Pointer and Request Length are ignored). The response from such a cancellation
will be a Failure parcel.
After the first segment has been successful, segmenting is active even after CLIv2 return codes
or Error parcels, and either must be completed normally, cancelled, or the session logged off.
If the server restarts, any segments that were received will be discarded and the next segment
sent will receive a Failure response.
Effects on Other Options
Use of Segment Data impacts the use of the following options:
•
The Keep Response option must be 'N'.
•
The Request mode option must be 'P' (parcel mode).
•
The Request Processing option must be 'E' (execute request processing).
•
If the Initiate with Protocol Function function is used, the Initiate Protocol-function
option must be 'N'.
Other limitations also apply:
•
The character set for all segments is the character set of the first segment (changing the
character set between segments may result unexpected translation of segment data).
•
Only one sequence of segments may be in use within one session at a time.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
371
Chapter 13: Stored Procedures
Effects on Other Options
372
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 14
Alternate Parcel Header
The standard parcel header format (SPH) contains a 2-byte flavor field and a 2-byte length
field. This format limits the length of the parcel to 65536 bytes.
The alternate parcel header (APH), extends the limit to 1 MB. The APH format contains a
2-byte flavor field, a 2-byte reserved field, and a 4-byte length field.
Note: dbcarea.consider_APH_resps must be set to ‘Y’ to receive APH responses.
The following lists the parcel flavor, name, and description.
Table 41: Parcel Headers
Parcel
Flavor
Name
Description
1
Req
Record mode request parcel
2
RunStartup
Startup parcel
3
Data
Data parcel
4
Resp
Response parcel
5
KeepResp
Keep response parcel
7
Cancel
Cancel parcel sent to cancel the stored procedures multi-tsr
parcel
13
FMReq
Field mode request parcel
14
FMRunStartup
Field mode startup request
32
NOP
No operation parcel
68
IndicData
Data parcel containing indicator bytes
69
IndicReq
Indicator mode request parcel
71
DataInfo
Data info parcel
72
IVRunStartup
Indicator mode startup request
85
Options
Parcel for request
120
CursorHost
Cursor parcel sent by host
128
MultiTsr
Multi TSR parcel used by stored procedures
129
SPOptions
Stored procedures options parcel
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
373
Chapter 14: Alternate Parcel Header
Alternate Parcel Header Structure
Table 41: Parcel Headers (continued)
Parcel
Flavor
Name
Description
140
MultipartData
MultipartData parcel
141
EndMultipartData
End MultipartData parcel
142
MultipartIndicData
Multipart Indic data parcel
143
EndMultipartIndicData
End Multipart Indic data parcel
146
DataInfoX
Datainfox parcel
147
MultipartRunStartup
MultipartRunStartup parcel
148
MultipartRequest
MultipartRequest parcel
153
ExtResp
New extended response parcel
154
ExtKeepResp
New extended keep response parcel
157
SETPOSITION
Cursor positioning request
158
ROWPOSITION
Row position to which cursor needs to be repositioned.
159
OFFSETPOSITION
From where the LOB data should be returned.
Alternate Parcel Header Structure
The parcel APH fields are:
Field
Purpose
PclFlavor (Flavor)
The size remains 2-byte; however, the most significant bit (MSB) of the
2-byte flavor is set to indicate that an alternate parcel header is being
sent from the client to the server.
PclLength (Length)
Reserved: This is the existing length field in the old parcel header. The
size is 2-byte. This field should always be set to zero.
PclAltLength (AltLength)
This is the new field of 4-byte size, included in alternate parcel header.
The numeric value in this field describes the actual parcel length.
Client Interface Changes
Applications Using Parcel Mode
In this mode, CLI is responsible for building the parcels as per the protocol used for
submitting the requests and data (optionally) to Teradata server.
374
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 14: Alternate Parcel Header
Using the New Element Structure
CLI will always use the alternate header for the set of parcels that has the alternate parcel
support if:
•
The utilities use parcel mode (if DBCAREA option request_mode is set to “P”) for
submitting requests. The database should have the APH support for those sets of parcels.
•
DBCAREA field maximum_parcel is set to “H”. The size limit on the request buffer will
increase from 64K to 1 MB, if APH support exists.
•
The total request size (includes size of [EXTENDED] [KEEP] RESP + LAN Header +
[options parcel] exceeds 64K. CLI will return an error “REQOVFOW” 350, if APH
support doesn’t exist.
•
The DBCHQEP query item code to determine the alternate parcel header support at the
server is “QEPAREA” and has a value of 21. It returns a 2-byte unsigned binary value in
QEPAREA.
•
Value returned would be zero if no APH support exists.
•
Returns “1” if the first set of parcels, defined above, supports APH.
APH Parcels Sent to CLI Using the Extension Area in Parcel Mode
Applications have to send specific parcels with TDSP and Parameterized SQL requests, even in
parcel mode. DBCAREA extension is used for this purpose. DBCAREA contains an extension
header and the set of extension elements defined by CLI. The application chooses the set of
extension elements by setting the “eyecatcher” field of the extension header. If set to “DBCX”,
elements are defined to work only in 32-bit mode. If set to “IRX8”, elements are defined to
work in 32-bit and 64-bit mode.
Existing element structures are inadequate for sending APH parcel flavors or parcel bodies
whose size is greater than 65535 bytes. To overcome this limitation for supporting APH
parcels, the following changes are implemented in DBCAREA extension:
•
New set of element structures are defined.
•
Use of existing element structures is deprecated.
•
Use of structure elements “D8XILMNT” and “D8XILPTR” defined by 64-bit
implementation is deprecated.
Using the New Element Structure
Level field 'd8xiLvl' in the extension header (D8CAIRX) should be set to 1 and eyecatcher
should be set to "IRX8". This will completely eliminate the old element structure and all
elements in the extension must be in the new format (if the level field set to zero, elements
defined to work in 32-bit mode and 64-bit mode becomes effective)
The two new element structures can be used to deliver both APH and Non APH parcels to
CLI. These are compatible for both 32 and 64 bit modes.
typedef struct D8XIELEM {
UInt16 d8xieLen;
UInt16 d8xieTyp;
/* Length of element
/* Type of element
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
*/
*/
375
Chapter 14: Alternate Parcel Header
Using the New Element Structure
/* 0 - Use of non APH
/* 1 - Use APH
} D8XIELEM;
typedef struct D8XIEP {
UInt16
d8xiepF;
UInt16
d8xiepR1;
UInt32
d8xiepLn;
Byte
d8xiepA[4];
#ifdef CLI_64BIT
Byte
d8xiepP4[4];
#else
char*
d8xiepPt ;
#endif
#ifdef CLI_64BIT
char*
d8xiepPt;
#else
Byte
d8xiepP8[8];
#endif
Byte
d8xiepL8[8];
} D8XIEP;
/*
/*
/*
/*
/*
/*
/*
/*
Parcel flavor
Reserved: must be zero
Length of body
if d8xiepPt NULL
set d8xiepLn to 0
else
set d8xiepLn to body length
Reserved: must be zero
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
/* Reserved: must be zero
*/
/* Pointer to body,if not inline
*/
/* Pointer to body,if not inline
*/
/* Reserved: must be zero
*/
/* Reserved: must be zero
*/
The new element allows the parcel body to either be inline or pointed to.
Inline:
If d8xiepPt is set to zero or null, then the parcel body data should be stored in the element
contiguous to D8XIEP.
Extension Header- D8CAIRX
Eyecatcher -> IRX8
D8xilvl -> 1
Element Header- D8XIELEM
Element- D8XIEP
d8xiepPt -> NULL
Parcel body
376
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 14: Alternate Parcel Header
Members of New Structure Elements
Pointed to:
Extension Header- D8CAIRX
Eyecatcher -> IRX8
D8xilvl -> 1
Element Header- D8XIELEM
Element- D8XIEP
d8xiepPt -> Parcel Body
Parcel body
If d8xiepPt is not set zero or NULL, then that pointer addresses the parcel body.
If the length of the parcel body exceeds 64K, then "pointed to" method has to be used.
Members of New Structure Elements
In the new structure element D8XIELEM:
1
dbxieLen, should be used to mention the total length of the element.
•
If d8xiepPt is null then
d8xieLen = sizeof (D8XIELEM) + sizeof(D8XIEP) + sizeof (the parcel body)
•
If d8xiepPt is not null then
d8xieLen = sizeof (D8XIELEM) + sizeof(D8XIEP)
2
d8xieTyp, should be set to 1 if the element is used for sending an APH parcel should be set
to 0 if the element is used for sending a non APH parcel.
In the new structure element D8XIEP:
1
d8xiepF should be set to the parcel flavor which the application intends to send to CLI.
2
d8xiepR1, is a 2 byte reserved field and should be set to ZERO.
3
d8xiepLn
•
If d8xiepPt is not NULL
set to the length of the parcel body which is pointed to by d8xiepPt.
•
If d8xiepPtr is NULL
set to ZERO.
4
d8xiepA, is a 4 byte reserved field and must be set to zero.
5
If in 64 bit mode, then d8xiepP4 is a 4 byte reserved field and should be set to zero.
6
d8xiepPt should be set to either NULL or to the address where the parcel body is placed.
7
If in 32bit mode, d8xiepP8 is a 8 byte reserved field and should be set to zero.
8
d8xiepL8 is a 8 byte reserved field and should be set to zero.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
377
Chapter 14: Alternate Parcel Header
Members of New Structure Elements
Possible Combination of Element Structures
Parcels Sent Using Inline Method Only
Extension Header- D8CAIRX
Eyecatcher -> IRX8
D8xilvl -> 1
Element Header- D8XIELEM
Element- D8XIEP
d8xiepPt -> NULL
Parcel body
Element Header- D8XIELEM
Element- D8XIEP
d8xiepPt -> NULL
Parcel body
Parcels Sent Using Pointed to Method Only
Extension Header- D8CAIRX
Eyecatcher -> IRX8
D8xilvl -> 1
element Header- D8XIELEM
Element- D8XIEP
d8xiepPt -> Parcel body
Parcel body
Element Header- D8XIELEM
Element- D8XIEP
d8xiepPt -> Parcel body
378
Parcel body
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 14: Alternate Parcel Header
Members of New Structure Elements
Parcels Sent Using Both Inline and Pointed to Method
Extension Header- D8CAIRX
Eyecatcher -> IRX8
D8xilvl -> 1
element Header- D8XIELEM
Element- D8XIEP
d8xiepPt -> NULL
Parcel body
Element Header- D8XIELEM
Element- D8XIEP
d8xiepPt -> Parcel body
Parcel body
For Applications using Buffer Mode
If requests are submitted in buffer mode by the Utilities, then CLI will not parse those parcels
and sends them to Teradata Database wrapped with LAN message header.
New CLI Errors with APH implementation
If the application sends APH parcels using the new Extension elements and the server does not
have APH support, CLI will return an new error 393:
CLI2: NOALTSUPPORT(393): No Alternate parcel support at the Server.
Handling variable length requests
If Variable Length Request is set to Y, the address supplied in Request Pointer points to a twobyte length (in binary) field which precedes the text of the request, and the length of the
request text is not supplied in Request Length. The length provided preceding the text
measures only the length of the request text, and does not include the two bytes of its own
length. This introduces a limit on the length of the requests that can be sent using this method
to 64K. No changes are done to increase this limit as this option exists is for PL/I, whose
VARCHAR-like things start with the 2byte prefix. PL/I doesn't have any 4byte prefixes yet.
Others
New constants, APH parcel flavors to be used, are defined in parcel.h and coptypes.h. Note
that the changes done in these header files are specific to NW CLI.
Note: CLI generates APH parcels in parcel mode only if Session is logged onto "DBC/SQL"
partition.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
379
Chapter 14: Alternate Parcel Header
Members of New Structure Elements
380
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 15
Extended Message Response Size
This chapter details supporting a message with a size greater than 64K.
Note: If extended response support exists at the server there is no limit on the response buffer
that can be allocated by CLI as requested by applications using resp_buf_len.
Before connecting to a session, CLI does not have information about extended response
support, so the 64k/32K response buffer limit will still exist while connecting to a session
using CLICON.
Existing Scenario
Teradata Database supports maximum buffer size of 64k to receive response messages. This
buffer is called response buffer. It contains 58 bytes of network header followed by one or
more response parcels.
Applications using Parcel mode (request_mode='P')
CLI uses, either Response (PclRESP) or the KeepResponse (PclKEEPRESP) parcel to inform
the server about the size of response buffer allocated to receive the response message.
•
Use of 'PclRESP' or 'PclKEEPRESP' parcel is directed by the client to CLI through
DBCAREA field 'keep_resp'.
•
Initial buffer size that needs to be allocated by CLI for collecting the response messages is
directed by the client using DBCAREA field 'resp_buf_len'.
•
If this response buffer size does not fit one single response message then server sends a
'Message overflow' error (3115 or 3116) via error parcel. CLI parses this error parcel and
grows its response buffer as indicated in 'info code' of error parcel.
Currently NW CLI controls the maximum limit of the response size that can directed by the
client in DBCAREA field 'resp_buf_len' through another DBCAREA field 'maximum_parcel'.
•
If 'maximum_parcel' is set to 'O', then 'resp_buf_len' can be set to not more than 32K.
•
If 'maximum_parcel' is set to 'H', then 'resp_buf_len' can be set to not more than 64K.
Applications using Parcel mode (request_mode='B')
In this mode, CLI has no control on the parcels sent from client to server. Parcels are built by
the client utility and sent to CLI as request buffer. CLI doesn't parse these parcels. Instead, CLI
wraps a LAN message header to the request buffer and sends it to Teradata Database. Hence in
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
381
Chapter 15: Extended Message Response Size
Limitation in extending the existing Scenario
buffer mode, it is the responsibility of the client to prepare a "PclResp" or "PclKEEPRESP"
parcel and send this along with other parcels.
Limitation in extending the existing Scenario
Use of either a Response (PclRESP) or the KeepResponse (PclKEEPRESP) parcel limits the
maximum response buffer that can be indicated to the server to 64K, as size of 'MaxMsgSize' is
only 2 bytes.
struct PclRespType
{
PclFlavor
PclKind;
PclLength
Length;
Int16
MaxMsgSize;
};
/* 4 */
/* 6 */
CLI - Client Interface changes
To overcome the above limitation, two new parcels 'PclBIGRESP' (flavor 153) and
'PclBIGKEEPRESP' (flavor 154) are defined. The new parcel format used by these two parcels
is:
struct PclBigRespType
{
PclFlavor PclKind; /* 153 or 154 */
PclLength Length; /* 8 */
Int32 MaxMsgSize;
};
Using above format CLI/Client can communicate to the server response buffer size of 2**32.
Applications using Parcel mode (request_mode='P')
If extended response support exists at the server, CLI will always send the new parcels defined
'PclBIGKEEPRESP' or 'PclBIGRESP' even when the size of response buffer mentioned by the
application is less than 64K.
•
Use of 'PclBIGRESP' or 'PclBIGKEEPRESP' parcel is directed by the client to CLI through
DBCAREA field 'keep_resp'.
•
Initial buffer size that needs to be allocated by CLI for collecting the response messages is
directed by the client using DBCAREA field 'resp_buf_len'.
CLI now controls the maximum limit of the response size that can directed by the client to
CLI in DBCAREA field 'resp_buf_len ' through DBCAREA field 'maximum_parcel'.
382
•
If 'maximum_parcel' is set to 'O', set 'resp_buf_len' to not more than 32K.
•
If 'maximum_parcel' is set to 'H', set 'resp_buf_len' to any value not more than 2**32 if
extended response is supported at server.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 15: Extended Message Response Size
CLI - Client Interface changes
•
If 'maximum_parcel' is set to 'H', set 'resp_buf_len' to not more than 64K if extended
response is not supported at server.
If CLI finds that resp_buf_len is set to a value greater than 64K and extended response is not
supported at the server, CLI returns an error 302 'BADBUFRQ'.
A new DBCHQEP query item 'QEPIXRS' for the Extended Response is added and has a value
of 20. Client utilities can ascertain the support of extended response in the server by using this
query item. CLI will return a 'Y' in QEPAREA if extended response is supported at server and
a 'N' otherwise.
Applications using Parcel mode (request_mode='B')
Client Utility can use either of the extended response parcels defined or the old response
parcels to inform the server. Using one of the two parcels, the response buffer size that has
been allocated is communicated to server.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
383
Chapter 15: Extended Message Response Size
CLI - Client Interface changes
384
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 16
CLI Exit Functions
This chapter describes the CLI Exit functions:
•
Overview
•
Use
•
Parameters of CLI Exit Routines
•
CliUsrLgnExt
•
CLI Pre- and Post-Process SQL User Exits
•
User Exits for Security
•
CLI2EXITLVL Environment Variable
Overview
CLI explicitly loads user exit libraries, and the user exit libraries supplied with CLI packages
do not contain any user exit functionality. Since CLI no longer requires exit level functions,
the following options are available:
•
To implement any exit level functions, you must provide an entry point for all other
functions within the same level (1 or 2).
•
If no exit functions are implemented, the CLI2EXITLVL environment variable must not
be set. For more information, see “CLI2EXITLVL Environment Variable” on page 391.
Use
Table 42 lists the CLI Exit routines and describes how they are used.
Table 42: Use of Routines
Routine
Description
CliUsrLgnExt
What
Allows the user to check the logon sequence before it is sent to the
Teradata Database.
Where
Supported on all client platforms.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
385
Chapter 16: CLI Exit Functions
Parameters of CLI Exit Routines
Table 42: Use of Routines (continued)
Routine
Description
CliPreSQLExt
What
Allows the user to check the Teradata SQL statement before it is sent
to the Teradata Database.
Where
Supported on all client platforms.
What
Time stamps the Teradata SQL return statement.
Where
Supported on all client platforms.
What
Allows the user to check the Level 2 logon sequence before it is sent
to the Teradata Database.
Where
Supported on all client platforms.
What
Allows the user to check the Teradata SQL statement before it is sent
to the Teradata Database.
Where
Supported on all client platforms.
What
Time stamps the Teradata SQL return statement.
Where
Supported on all client platforms.
CliPostSQLExt
CliUsrLgnExt2
CliPreSQLExt2
CliPostSQLExt2
Parameters of CLI Exit Routines
Table 43 lists the parameters for the CLI Exit functions.
Table 43: CLI Routine Parameters
Routines
Parameters
CliUsrLgnExt
CliExit structure
CliPreSQLExt
CliPreSQLExit Structure
CliPostSQLExt
CliPostSQLExit structure
CliLgnExit2
CliLgnExit2 structure
CliSQLExit2
CliSQLExit2 structure
CliUsrLgnExt
CliUsrLgnExt (CLI User Logon Exit Control) allows user-defined processing to take place
upon receipt of a connection request. CliUsrLgnExt is an empty function containing a return
statement. To utilize this function, it must be modified to meet the specific needs of the user.
One file, CliLgnEx.c, is added to the 3000 CLIent Interface for CliUsrLgnExt.
386
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 16: CLI Exit Functions
CLI Pre- and Post-Process SQL User Exits
Internal Variable
An internal CLI variable, CliUsrLgnOn, controls the CLI User Logon Exit function.
CliUsrLgnOn
This variable is initialized to TRUE in CLI at startup. Setting the value to FALSE turns off the
user exit logon function, that is, if set to FALSE, CLI will not call CliUsrLgnExt.
CliUsrLgnOn is a global variable. To enable the CliUsrLgnExt() function, set this variable to
TRUE in CliLgnEx.c. By default, CliUsrLgnOn is FALSE.
Interface
struct CliExit
{
char
char
char
char
char
username[UEXUSRLEN];
password[UEXPWDLEN];
dbcname [UEXDBCLEN];
account [UEXACTLEN];
domain [DOMAINLEN];
/*
/*
/*
/*
/*
user name */
password */
DBC name */
account name */
domain name */
};
Return Value
CliUsrLgnExt returns zero (0) or EM_OK if successful; otherwise, it returns an error code.
Error Handling
If the CliUsrLgnExt function modifies the logon string to an invalid userid, password, or
account, the Teradata Database will return the following error:
8017
The UserId, Password or Account is invalid
The CLI error code:
349
(USREXT)
The user exit function failed
is available to the user. However, any error code found in the errmsg.txt file may also be
returned.
CLI Pre- and Post-Process SQL User Exits
The Pre-process and Post-process SQL User Exit feature are executed by a user routine linked
with the CLI applications. The file, CliPPS.c, has been added to the existing 3000 CLIent
Interface for CliPreSQLExt and CliPostSQLExt.
Internal Variable
An internal CLI variable, CliPPsOn, controls both the Pre-process and the Post-process SQL
User Exit function.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
387
Chapter 16: CLI Exit Functions
CLI Pre- and Post-Process SQL User Exits
CliPPsOn
Setting the value to FALSE turns off the Pre-process and Post-process SQL User Exit
functions. That is, if set to FALSE, CLI will not call either CliPreSQLExt or CliPostSQLExt.
CliPPsOn is a global variable. To enable the CliUsrLgnExt() function, set this variable to TRUE
in CliPPS.c. By default, CliPPsOn is FALSE.
CliPreSQLExt
CliPreSQLExt is the CLI Pre-process SQL User Exit function of DBCHCL. CliPreSQLExt is
used to filter SQL requests that may slow down the Teradata Database, to control SQL requests
sent to the Teradata Database and to collect time statistics of SQL requests.
Calling CliPreSQLExt
CliPreSQLExt is called just before CLIIRQ. Prior to the call to CliPreSQLExt, CLI performs
the following:
1
If not variable length request, CLI checks the SQL request to see if it can be saved in the
internal CLI Buffer.
If the request length is less than, or equal to, the internal max buffer length, the process
will continue to the next step. If not, it will abort and return an error 302.
2
The SQL request’s length is saved in the structure CliPreSQLExt.
If the request length is less than, or equal to, the internal buffer size, the process will
continue to the next step. If not, it will abort and return an error 302.
3
Caution:
After the call to CliPreSQLExt, CLI performs the following:
•
If EM_OK was returned, send the Teradata SQL to the Teradata Database.
•
If an error message is received, abort the request. Use normal CLI error logic when a
Teradata SQL request is aborted.
Do not exceed the Teradata SQL buffer size within the CliPreSQLExt function. Exceeding the
buffer size will result in damage to other areas of CLI. Damage is platform dependent.
Interface
struct CliPreSQLExit
{
char
*SQL_Request_ptr;
char
Start_date[80];
Int32 Clock_time;
char
dbcname[DBCNAMLEN];
char
username[USRNAMLEN];
char
account[ACTNAMLEN];
char
password[PWDNAMLEN];
char
domain[DOMAINLEN];
Int32 *SQL_len_ptr;
Int32 logsessid;
Int16 Process_Post;
};
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
pointer to user request */
start date in ascii */
clock time */
DBC name */
username */
account */
password */
domain */
length of user request */
logical session id */
enable post processing */
The elements Start_date[80] and Clock_time must be set manually to determine the clock
time for SQL requests.
388
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 16: CLI Exit Functions
CLI Pre- and Post-Process SQL User Exits
Return Value
CliPreSQLExt returns zero (0) if successful, otherwise it returns an error code. The variable
Process_Post is set to TRUE if the Post-process SQL function is to be executed by CLI.
Error Handling
A CLI error code 351 (SQLUSREXT) is available to the user. However, any error code found in
the errmsg.txt file may also be returned.
CliPostSQLExt
CliPostSQLExt is the CLI Post-process SQL User Exit function of DBCHCL. CliPostSQLExt is
used to collect user-supplied time statistics of SQL requests.
Calling CliPostSQLExt
CliPostSQLExt is called and executed after CLIFET. The following functionality will be added:
•
The user written function is executed when the Process_Post in CliPreSQLExt is set to 1 or
true and CliPreSQLExt is put in CliPostSQLExt.
•
The Post-process SQL flag from CliPreSQLExt is set to false so further execution of
CliPostUsrSQLExt will not occur during parcel return.
Interface
struct CliPostSQLExit
{
char
*SQL_Request_ptr;
char
Start_date[80];
Int32 Clock_time;
char
dbcname[DBCNAMLEN];
char
username[USRNAMLEN];
char
account[ACTNAMLEN];
char
password[PWDNAMLEN];
char
domain[DOMAINLEN];
Int32 *SQL_len_ptr;
Int32 logsessid;
};
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
pointer to user request */
start date in ascii */
clock time */
DBC name */
username */
account */
password */
domain */
length of user request */
logical session id */
Return Value
No values are returned by this function.
Error Handling
No special error conditions will be processed by this function. Parcel information returned by
the Teradata SQL request will be passed to the calling utility (that is, BTEQ, FastLoad, etc.) or
the user application calling CLI.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
389
Chapter 16: CLI Exit Functions
User Exits for Security
User Exits for Security
Level 2 Login and Pre & Post Exits
The User Exit structures are defined as follows:
/***************************************************************/
/* User Exit Structures for Level 2 Login and Pre&Post Exits
*/
/***************************************************************/
typedef struct CliExit2_struct
{
char
*dbcname;
UInt32
dbcname_actual_len;
UInt32
dbcname_max_len;
/* = DBCNAMLEN */
char
*username;
UInt32
username_actual_len;
UInt32
username_max_len;
/* = USRNAMLEN */
char
*password;
UInt32
password_actual_len;
UInt32
password_max_len;
/* = PWDNAMLEN */
char
*account;
UInt32
account_actual_len;
UInt32
account_max_len;
/* = ACTNAMLEN */
char
*domain;
UInt32
domain_actual_len;
UInt32
domain_max_len;
/* = DOMAINLEN */
char
*mechname;
UInt32
mechname_actual_len;
UInt32
mechname_max_len;
/* = MECNAMLEN */
char
*mechdata;
UInt32
mechdata_actual_len;
UInt32
mechdata_max_len;
/* = MAX_LOGMECH_DATA_LEN */
char
*charset;
UInt32
charset_actual_len;
UInt32
charset_max_len;
/* = CHARSETSIZ */
} CliExit2_t, *CliExit2_p;
CliLgnExit2
typedef struct CliLgnExit2_struct
{
char
eye_catcher[4];
/* “LGN ”
UInt32
level;
/* 2
CliExit2_t opts;
} CliLgnExit2_t, *CliLgnExit2_p;
*/
*/
CliSQLExit2
typedef struct CliSQLExit2_struct
{
char
eye_catcher[4];
/* “PRE ” or "POST" */
UInt32
level;
/* 2
*/
char
*SQL_Request_ptr;
char
Start_date[80];
UInt32
Clock_time;
Int32
*SQL_len_ptr;
390
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 16: CLI Exit Functions
CLI2EXITLVL Environment Variable
UInt32
logsessid;
UInt16
Process_Post; /* only applies to pre-SQL exits */
char
fill_1[2];
CliExit2_t opts;
} CliSQLExit2_t, *CliSQLExit2_p;
The maximum allowable storage is allocated by CLI before the exits are called. Those lengths
are stored in <var name>_max_len for future compatibility (and so that the exits know how
much space they have).
If the exit changes the value of any field, it must also update its <var name>_actual_len. The
charset field cannot be modified. When control returns back to CLI, the appropriate fields (all
but charset) are copied back to their respective area in the scbptr. The memory allocated
earlier by CLI is then freed (unless Process_Post is set, in which case it is freed after
CliPostSQLExt2 call). Other than memory allocation changes, the behavior is the same as the
original user exits.
CLI2EXITLVL Environment Variable
Set the CLI2EXITLVL environment variable to 1 or 2 to correspond with Level 1 or Level 2
exit routines. CLI decides which Level exits to call based on the following factors:
•
Functions not found - If the variable is set to 1 or 2 when the corresponding user exit
functions are not found in the library, CLI returns error TDUSRLOADERR(530).
•
Variable not set - If the variable is not set, CLI attempts to load the user exit library and
symbols, giving preference first to Level 2 functions, then to Level 1 functions. If the
variable is not set and no functions are found, the exits are disabled, and CLI returns no
error.
•
Invalid value - If the variable is set to a value other than 1 or 2, user exits are disabled.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
391
Chapter 16: CLI Exit Functions
CLI2EXITLVL Environment Variable
392
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 17
Large Objects (LOB) Support
This chapter contains the following:
•
Determining LOB Support
•
Inline Method
•
Deferred Method
•
Summary
•
Error Messages and Codes
Introduction
Large objects (LOBs) are either binary data (BLOBs) or character data (CLOBs). Up to 32 LOB
columns can be defined in a given table, and these columns may contain binary objects, such
as graphics, video or sound clips. LOBs are treated like any other data type (subject to certain
limitations). In many respects, they most closely resemble the existing VARBYTE data type;
the size of the variable length indicator prefix for a LOB is 8 rather than 2 bytes, however.
LOBs are fully accommodated by the database with regard to journaling, fallback, archive, and
restore. Changes to a LOB can be committed or rolled-back.
Two methods have been adopted for handling LOB data: inline and deferred. Both methods
use a Multipart Indicator response mode, in addition to the existing Field, Record, Indicator,
and Extended Indicator response modes and can be specified via the Options parcel or the
MultipartRunStartup or MultipartReq parcels. CLI provides a DBCAREA setting that can be
used by parcel request mode applications to specify that Multipart Indicator mode should be
used.
Determining LOB Support
A query type QEPIFLOB (18) can be used by an applications to determine whether LOB
support exists at the database. When applications set this query item and make a call to
DBCHQE, it will return:
•
“Y” - if the server supports the LOB data types
•
“N” - if the server does not support the LOB data types
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
393
Chapter 17: Large Objects (LOB) Support
Inline Method
Inline Method
The inline method is intended to accommodate relatively small LOBs and limit the row size
for client to server transfers to 64K, if APH is not supported at the database, and to a size of
1,024,000 if APH is supported at the Database. No such limit applies to server to client
transfers. This approach is very similar to the existing protocol used for handling non-LOB
data and, in fact, may be used for intermixed LOB and non-LOB data.
Server to Client Transfer
To retrieve one or more rows containing LOB data using the inline method, a typical parcel
mode CLI application should:
1
Set the response mode (resp_mode) to 'M' to indicate Multipart Indicator response mode.
Any other setting will result in an error condition being returned.
2
Set return_object to 'D' to indicate that data - rather than locators - should be returned.
3
Issue the SQL request (including one or more SELECTs) using DBCHCL (DBFIRQ) as
before.
4
After the request completes, retrieve the requisite parcel sequence along with the answer
set using DBCHCL (DBFFET).
5
Issue DBCHCL (DBFERQ) to close the request.
Client to Server Transfer
To send LOB data using the inline method, a typical parcel mode CLI application would:
1
Set the response mode (resp_mode) to 'M' to indicate Multipart Indicator response mode.
Any other setting will result in an error condition being returned.
2
Issue the SQL request (typically including one or more INSERTs, UPDATEs, or UPSERTs)
using DBCHCL (DBFIRQ).
3
After the request completes, retrieve the requisite parcel sequence using DBCHCL
(DBFFET).
4
Issue DBCHCL (DBFERQ) to close the request.
For an inline client to server transfer, the entire request must fit in a single TSR-request
message (currently about 64K).
Deferred Method
The deferred method allows LOB data to be processed separately from non-LOB data. There is
no size restriction, other than the 2 GB maximum LOB size imposed by the Teradata
Database. This method is somewhat more complicated and is limited to LOB data only, in
contrast to the inline method.
394
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 17: Large Objects (LOB) Support
Deferred Method
Server to Client Transfer
To retrieve one or more rows containing LOB data using the deferred method, a typical parcel
mode CLI application should perform the following tasks:
1
Set the response mode (resp_mode) to 'M' to indicate Multipart Indicator response mode.
Any other setting will result in an error condition being returned.
2
Set keep_resp = 'Y'.
3
Set return_object to 'T' to indicate that transaction-related locators should be returned (or
'S' for static locators).
4
Issue the SQL request (including one or more SELECTs) using DBCHCL (DBFIRQ).
5
After the request completes, retrieve the requisite parcel sequence along with the non-LOB
columns of the answer set using DBCHCL (DBFFET). The LOB columns will not contain
LOB data but, rather, LOB locators.
6
If the application desires to receive LOB data at this point, continue with step 7. Otherwise,
either continue receiving non-LOB data or end the request.
7
Issue the SQL SELECT request using the LOB locator returned in a previous response
(e.g., USING (A BLOB AS LOCATOR) SELECT :A;).
Note: This SELECT must be issued on the same session.
8
When appropriate, retrieve the requisite parcel sequence along with the answer set using
DBCHCL (DBFFET) until an EndMultipartRecord parcel is received.
9
Issue DBCHCL (DBFERQ) to end the request.
Client to Server Transfer
To send LOB data using the deferred method, a typical parcel mode CLI application should:
1
Set the response mode (resp_mode) to 'M' to indicate Multipart Indicator response mode.
Any other setting will result in an error condition being returned.
2
Place a unique four-byte integer token in those fields that would normally contain LOB
data.
3
The USING clause that references the LOB data types must specify AS DEFERRED.
4
Issue the SQL request (typically including one or more INSERTs, UPDATEs, or UPSERTs)
using DBCHCL (DBFIRQ).
5
After the request completes, retrieve the response from the server using DBCHCL
(DBFFET). After the request has been submitted to the server, the server will respond to
the request with an ElicitData parcel. The ElicitData parcel will contain the token of the
LOB that was placed in the MultipartData or MultipartIndicData parcel. The application
will receive the ElicitData parcel containing the token that indicates which LOB parameter
to send.
6
The application may send as much data as can be fit into the MultipartData parcel.
7
Issue DBCHCL (DBFCRQ) to send the deferred LOB data to the server with
continuation_code populated appropriately.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
395
Chapter 17: Large Objects (LOB) Support
Summary
8
Retrieve the ElicitDataReceived parcel response from the server using DBCHCL
(DBFFET).
9
Repeat starting at step 7 each time an ElicitDataReceived parcel for the current LOB is
received until there is no more data to send.
10 Repeat starting at step 6 each time an ElicitData parcel with a different token is received.
After all the LOBs have been successfully processed, the server will respond with a Success
parcel.
11 Issue DBCHCL (DBFERQ) to close the request.
The entire sequence outlined above constitutes a single, discrete request with one request
number for the life of the transaction.
Summary
Client to Server Transfer
Server to Client Transfer
Inline Mode
• Requires Multipart Indicator
response mode
• Uses MultipartData or
MultipartIndicData parcels (with
EndMultipartData or
EndMultipartIndicData parcels)
• Maximum parcel size limited to
maximum message size (~64K)
• Single, discrete request
• Requires Multipart Indicator
response mode
• Uses MultipartRecord parcel (with
EndMultipartRecord parcel)
• No practical size limit
• Signaled by setting Return_object
to 'D' in DBCAREA (default)
• Single, discrete request
Deferred Mode
• Requires Multipart Indicator
response mode
• Uses MultipartData or
MultipartIndicData parcels (with
EndMultipartData or
EndMultipartIndicData parcels)
• No practical size limit
• Data elicited by server
• Elicited data sent using DBFCRQ
• Signaled by specifying AS
DEFERRED in USING clause
• Single, discrete request
• Same protocol to be used by UDF
• Requires Multipart Indicator
response mode
• Uses MultipartRecord parcel (with
EndMultipartRecord parcel)
• No practical size limit
• Signaled by setting Return_object
to 'T' (for transaction-related
locator) or 'S' (for spool-related
locator) in DBCAREA
• Multiple, separate requests: one for
the non-LOB data and one for each
LOB column to be returned
Error Messages and Codes
CLIv2 LOB support error codes and associated messages:
396
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Chapter 17: Large Objects (LOB) Support
Error Messages and Codes
•
CLI -389
Multipart response mode is not supported by the Teradata server
Explanation: A Response Mode of 'M' was specified but it is not supported by the
requested Teradata server.
Notes: None
Remedy: Either do not specify Multipart Response Mode or specify a Teradata server that
supports its use.
•
CLI-390
Unrecognized value for Return-object option
Explanation: The value for the Return-object option was not recognized.
Notes: Supported values are 'D' (as Data), 'T' (as Transaction-related locator), and 'S' (as
Spool-related locator).
Remedy: Specify a supported value.
•
CLI-391
Unrecognized value for Continued-data option
Explanation: The value for the Continued-data option was not recognized.
Notes: Supported values are 'F' (first continuation), 'I' (intermediate continuation), 'L'
(last continuation), or 'C' (cancel continuation).
Remedy: Specify a supported value.
•
CLI-392
Inconsistent Continued-data option
Explanation: The Continued-data option specification was inconsistent with the current
continuation status. Either a first continuation was provided when a first continuation had
already been provided, an intermediate continuation was provided when no first
continuation had been provided, a cancel was requested when continuation was not in
progress, or a second last continuation or cancel request was specified before fetching the
result of the first.
Notes: None
Remedy: Specify a Continued-data option consistent with previous usage.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
397
Chapter 17: Large Objects (LOB) Support
Error Messages and Codes
398
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
CHAPTER 18
Performance Measurement
This section explains how timestamps are used to measure various CLIv2 processing times.
Overview
The time taken to process a request and its response, from the perspective of the client, may be
obtained by setting the following fields:
•
DBCAREA field 'ret_time' to 'Y'
•
DBCAREA field 'dbciTSP' to the desired precision
Timestamps are returned in Time1 and Time5. Time1-status and Time5-status values indicate
validity of these timestamps. Each Time field is four bytes long and contains an unsigned
binary timestamp.
The difference between two timestamps represents the time taken for processing. Time1 is set
when CLI sends a request to the Teradata Database. Depending on the precision requested by
the application, Time1 stores the timestamp in seconds, milliseconds, or microseconds.
Example
If CLI sends a request to the Teradata Database from a Windows client on 17th March 2002 at
23:41:35.21 and the requested precision is in seconds, then the time stored in Time1 would be
'35'. If the precision requested is in milliseconds, then the timestamp stored would be 35021.
Time5 is set when the first response is placed into the CLIv2 response buffer. The time set in
Time5 is measured with reference to Time1. Time5 stores the timestamp in seconds,
milliseconds, or microseconds depending on the precision specified by the application while
initiating the request.
If the first response received in CLI response buffer is 18th Mar 2002 at 01:00:05.32, then the
time stored in Time5 will be 4710 (assuming precision specified by the application is in
seconds). Time1-status and Time5-status contain a single ASCII character, indicating the
status of the corresponding time fields:
•
'V' if the timestamp is valid
•
'O' if the timestamp overflowed
•
Space or binary zero if the timestamp is not valid
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
399
Chapter 18: Performance Measurement
Overview
400
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
APPENDIX A
Examples of Using
DBCAREA Extension Elements
This section provides a listing of the DBCAREA extension elements.
Sending TDSP Options Parcel
Using 64-bit Implementation-Defined Extension Elements
/* Copyright 2006, by Teradata Corporation. All rights reserved.
/* Teradata PROPRIETARY AND CONFIDENTIAL-RESTRICTED
*/
/* Creates a Stored procedure using dbcarea extension pointers */
*/
/* This program demonstrates use of DBCAREA extension elements */
/* (D8XILMNT and D8XILPTR) defined for 64-bit implementation in */
/* CLI, to send MultiTSR parcels in Parcel mode
*/
/* Both 32-bit as well as
/* generated
#include
#include
#include
#include
#include
#include
#include
#include
64-bit executables can be
*/
*/
<stdio.h>
<stdlib.h>
<string.h>
<coptypes.h>
<coperr.h>
<parcel.h>
<dbcarea.h>
<dbchqep.h>
DBCAREA dbcarea;
Int16 exitout(int n1);
Int16 dbc_con();
Int16 dbc_init();
Int16 dbc_irq(char *);
Int16 dbc_erq();
void set_options();
void act_count(Word );
Int16 fetch_request(long ,long);
void Setdbcareax();
unsigned int GetSegmentSize();
#define
#define
#define
#define
CONNECTED
0
D8CAIRXSIZ
24
FIXED_ELM_LEN_8 42
D8XILMNTSIZE
4
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
401
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
#define SPOPTIONSSIZE
#define
#define
#define
#define
#define
2
NOT_CONNECTED 1
OK
0
STOP
1
FAILED
-1
MAX_SESSIONS 1
char *psLogon;
Int32 result;
char
cnta[4];
struct ERROR_FAIL_Type {
Word
StatementNo;
Word
Info;
Word
Code;
Word
Length;
char
Msg[255];
} *Error_Fail;
#ifdef WIN32
__declspec(dllimport)
__declspec(dllimport)
__declspec(dllimport)
__declspec(dllimport)
__declspec(dllimport)
#else
extern
extern
extern
extern
extern
#endif
char
char
char
char
char
char
char
char
char
char
COPCLIVersion[];
COPMTDPVersion[];
COPMOSIosVersion[];
COPMOSIDEPVersion[];
OSERRVersion[];
COPCLIVersion[];
COPMTDPVersion[];
COPMOSIosVersion[];
COPMOSIDEPVersion[];
OSERRVersion[];
/******************************************************************
*
function to print error message
*
******************************************************************/
write_error(parcel)
char *parcel;
{ int i;
Error_Fail = ((struct ERROR_FAIL_Type *) (parcel));
printf("%d : ",Error_Fail->Code);
for(i=0;i < (int)Error_Fail->Length;i++)
printf("%c",Error_Fail->Msg[i]);
printf("\n");
return(0);
}
/******************************************************************
*
function to initialize dbcarea
*
******************************************************************/
Int16 dbc_init()
402
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
{
dbcarea.total_len = sizeof(struct DBCAREA);
DBCHINI(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("\nError in initialization --%s",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/********************************************************************
*
function to logon
*
********************************************************************/
Int16 dbc_con()
{
printf("Logging on to :%s",psLogon);
dbcarea.logon_len=strlen(psLogon);
dbcarea.logon_ptr=psLogon;
dbcarea.func=DBFCON;
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK)
{
printf("\nError in Logon--%s\n",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/*********************************************************************
*
function to initiate request
*
*********************************************************************/
Int16 dbc_irq(char *str)
{
dbcarea.func = DBFIRQ;
printf("\nSubmitting request :%s",str);
dbcarea.req_ptr = str;
dbcarea.req_len = strlen(str);
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("Error in Initiating a request--%s",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/*******************************************************************
*
function to fetch parcels and check activity type
*
*******************************************************************/
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
403
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
Int16 fetch_request(request,session)
long request,session;
{
int count,i,status,rowcount;
int ShowFlag=0;
char ctc[6400];
struct CliSuccessType *SuccPcl;
struct CliOkType *OKPcl;
dbcarea.i_sess_id=session;
dbcarea.i_req_id=request;
dbcarea.func = DBFFET;
status=OK;
printf("\n");
rowcount=1;
while (status == OK){
DBCHCL(&result,cnta,&dbcarea);
count=1;
if (result == REQEXHAUST) status = STOP;
else if (result != EM_OK) status = FAILED;
else {
printf("Flavor Type : %d\n",dbcarea.fet_parcel_flavor);
switch (dbcarea.fet_parcel_flavor){
case PclSUCCESS :
SuccPcl = (struct CliSuccessType *) dbcarea.fet_data_ptr;
printf("Activity Type : %d\n",SuccPcl->ActivityType);
if (SuccPcl->ActivityType != 0)
printf("Activity Count: %d\n",SuccPcl->ActivityCount);
act_count(SuccPcl->ActivityType);
break;
case PclOK
case PclFIELD
:
printf("\nOK Parcel\n");
OKPcl = (struct CliOkType *) dbcarea.fet_data_ptr;
printf("Activity type : %d\n",OKPcl->ActivityType);
if (OKPcl->ActivityType != 0)
printf("Activity Count : %d\n",OKPcl->ActivityCount);
act_count(OKPcl->ActivityType);
if (OKPcl->ActivityType==49)
ShowFlag=1;
else
ShowFlag=0;
break;
:
for (i=0;i<dbcarea.fet_ret_data_len;i++){
if ((ShowFlag==0) ||
((rowcount>2) && (dbcarea.fet_data_ptr[i] != ' ')))
printf("%c",dbcarea.fet_data_ptr[i]);
else
count++;
if ((count <8) && (dbcarea.fet_data_ptr[i]==' ')
&& ((ShowFlag ==1) ))
if ((rowcount != 4) && (count !=2))
printf("%c",dbcarea.fet_data_ptr[i]);
}
if((ShowFlag==0)
|| ((ShowFlag == 1) && (rowcount>5)))
printf("\n");
404
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
rowcount++;
break;
case PclRECORD :
/*Returned data */
printf( " %s\n",dbcarea.fet_data_ptr);
printf( "parcel length
%d\n",(Int32)dbcarea.fet_ret_data_len);
memcpy(&ctc[0],&dbcarea.fet_data_ptr[0],1);
memcpy(&ctc[1],&dbcarea.fet_data_ptr[1],1);
memcpy(&ctc[2],&dbcarea.fet_data_ptr[2],1);
printf("first two bytes -%s\n",ctc);
printf("first two bytes -%d\n",atoi(ctc));
break;
case PclENDSTATEMENT:
break;
case PclENDREQUEST :
break;
case PclFAILURE :
printf("failure parcel PCLFAILURE\n,length %d \n",
(Int32)dbcarea.fet_ret_data_len);
/*Failure
parcel*/
break;
case PclERROR :
printf("PCLERROR");
status = STOP;
write_error(dbcarea.fet_data_ptr);
exitout(CONNECTED);
break;
/*Error parcel
*/
} /*end of switch*/
} /*end of else*/
} /*end of while*/
if(status == FAILED)
{ printf("fetch failed -- %s\n",dbcarea.msg_text);
exitout(CONNECTED);
} /*if*/
printf("\n");
return EM_OK;
}
Int16 dbc_erq()
{
dbcarea.i_sess_id = dbcarea.o_sess_id;
dbcarea.i_req_id = dbcarea.o_req_id;
dbcarea.func = DBFERQ;
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("Error in EndRequest--%s\n",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
405
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
/*********************************************************************
*
function to disconnect
*
*********************************************************************/
Int16 exitout(int n)
{
dbcarea.func = DBFDSC;
DBCHCL(&result,cnta,&dbcarea);
DBCHCLN(&result,cnta);
printf("\nExiting--%s",dbcarea.msg_text);
exit(n);
return(n);
}
/*********************************************************************
*
function to set options
*
*********************************************************************/
void set_options()
{
dbcarea.change_opts = 'Y';
dbcarea.resp_mode = 'F';
dbcarea.use_presence_bits = 'N';
dbcarea.keep_resp = 'N';
dbcarea.wait_across_crash = 'N';
dbcarea.tell_about_crash = 'Y';
dbcarea.loc_mode = 'Y';
dbcarea.var_len_req = 'N';
dbcarea.var_len_fetch = 'N';
dbcarea.save_resp_buf = 'N';
dbcarea.two_resp_bufs = 'N';
dbcarea.ret_time = 'N';
dbcarea.parcel_mode='Y';
dbcarea.wait_for_resp = 'Y';
dbcarea.req_proc_opt = 'E';
dbcarea.req_buf_len = 1024;
dbcarea.resp_buf_len = 1024;
}
void act_count(Word Activitytype)
{
switch(Activitytype){
case PclDropProcStmt :
printf("Procedure has been dropped\n");
break;
case PclRenProcStmt
:
printf("Procedure has been Renamed\n");
break;
406
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
case PclCallStmt
:
printf("Procedure has been Executed\n");
break;
case PclCreateProcStmt:
printf("Procedure has been Created\n");
break;
case PclShowStmt
:
printf("Show Procedure Successful\n\n");
break;
default
:
break;
}
return;
}
/********************************************************************
*
Function : GetSegmentSize
*
*
Purpose : Gets maximum segment size from server
*
********************************************************************/
unsigned int GetSegmentSize()
{
DBCHQEP QEPParms ;
unsigned int
MaxSegSize;
memset( &QEPParms, 0, sizeof( QEPParms ) );
QEPParms.qepLevel = QEPLEVEL;
QEPParms.qepItem = QEPIDMSS ;
QEPParms.qepRALen = sizeof( long );
QEPParms.qepRArea = &MaxSegSize;
QEPParms.qepTDP = ( long ) ( "nag2n1" );
QEPParms.qepTLen = strlen("nag2n1");
DBCHQE( &result, cnta, &QEPParms );
MaxSegSize = *(unsigned int *) QEPParms.qepRArea;
printf(" MaxSegSize :%d", MaxSegSize);
return(MaxSegSize);
}
/*********************************************************************
*
Function : Setdbcareax
*
*
Purpose : Uses the Extension pointer to send MultiTSR parcels*
**********************************************************************/
void Setdbcareax()
{
char
*ext_ptr;
D8CAIRX dbcxptr;
D8XILMNT dbxilmnt;
D8XILPTR dbxilptr;
char* SplFlag = "PY";
int temp;
dbcarea.dbriSeg='L'; /* Only one TDSP segment to send */
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
407
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
/* Allocate Memory for the extension pointer */
ext_ptr = (char *)(malloc(sizeof(D8CAIRX) +
sizeof(struct D8XILMNT) + sizeof(D8XILPTR)));
/* Initialize the extension area in DBCAREA */
dbcarea.extension_pointer = (char *)ext_ptr;
/*******************************/
/* Build the extension header */
/*******************************/
/* Set the Eyecatcher
*/
strncpy(dbcxptr.d8xiId, "IRX8", 4);
/* Set the first reserved field */
#if (defined(_LP64) || defined(__LP64__) || defined(__64BIT__) ||
defined(_WIN64))
memset(dbcxptr.d8xiNxt4, 0, 4);
#else
dbcxptr.d8xiNext = NULL;
#endif
/* Set Length of DBCAREA extension to */
/* size of Extension header + Size of Extension Elements */
dbcxptr.d8xiSize = D8CAIRXSIZ + FIXED_ELM_LEN_8;
/* set level to zero to indicate use of 64-bit */
/* compatible elements of IRX8
*/
dbcxptr.d8xiLvl = D8XIL64;
/* Set the second reserved field */
memset(dbcxptr.d8xiFil1, 0, 3);
#if (defined(_LP64) || defined(__LP64__) || defined(__64BIT__) ||
defined(_WIN64))
dbcxptr.d8xiNext = NULL;
#else
memset(dbcxptr.d8xiNxt8, 0, 8);
#endif
/* Place the extension header at begining of extension_pointer */
memcpy(ext_ptr, (char*)(&dbcxptr), sizeof(D8CAIRX));
/* Move to the end of Extension header */
ext_ptr = (char*)ext_ptr + D8CAIRXSIZ;
/* Build the element */
/* Initialize the SPOptions parcel header for TDSP */
dbxilmnt.d8xilTyp = PclSPOPTIONSTYPE;
dbxilmnt.d8xilLen = FIXED_ELM_LEN_8;
/* Set the high end bit of the element type to 1
*/
/* inorder to notify CLI that app, uses pointer type element */
dbxilmnt.d8xilTyp = (dbxilmnt.d8xilTyp | 0x8000);
memcpy(ext_ptr, (char*)(&dbxilmnt), D8XILMNTSIZE);
ext_ptr = (char*)ext_ptr + D8XILMNTSIZE;
/* Initialize the pointer Element */
408
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
/* Set first reserved field to zero */
memset(dbxilptr.d8xilpF2, 0, 2 * sizeof(Byte));
memcpy(ext_ptr, &dbxilptr.d8xilpF2, 2 * sizeof(Byte));
ext_ptr = (char *)ext_ptr + 2 * sizeof(Byte);
#if (defined(_LP64) || defined(__LP64__) || defined(__64BIT__) ||
defined(_WIN64))
/* Set second reserved field to zero */
memset(dbxilptr.d8xilpP4, 0, 4 * sizeof(Byte));
memcpy(ext_ptr, &dbxilptr.d8xilpP4, 4 * sizeof(Byte));
ext_ptr = (char *)ext_ptr + 4 * sizeof(Byte);
#else
/* Set address of the parcel body */
temp = (Int32)SplFlag;
memcpy(dbxilptr.d8xilpPt, &temp, 4);
memcpy(ext_ptr, &dbxilptr.d8xilpPt, 4 * sizeof(char));
ext_ptr = (char *)ext_ptr + 4 * sizeof(char);
#endif
/* Set third reserved field to zero */
memset(dbxilptr.d8xilpF3, 0, 4 * sizeof(UInt32));
memcpy(ext_ptr, &dbxilptr.d8xilpF3, 4 * sizeof(UInt32));
ext_ptr = (char *)ext_ptr + 4 * sizeof(UInt32);
/* Set Parcel Body Length field */
dbxilptr.d8xilpLn = SPOPTIONSSIZE;
memcpy(ext_ptr, &dbxilptr.d8xilpLn, sizeof(UInt32));
ext_ptr = (char *)ext_ptr + sizeof(UInt32);
/* Set Fourth reserved field to zero */
memset(dbxilptr.d8xilpA, 0, 4 * sizeof(Byte));
memcpy(ext_ptr, &dbxilptr.d8xilpA, 4 * sizeof(Byte));
ext_ptr = (char *)ext_ptr + 4 * sizeof(Byte);
/* 64 bit support on SPARC, HPUX, AIX, Windows */
#if (defined(_LP64) || defined(__LP64__) || defined(__64BIT__) || \
defined(_WIN64))
/* Set address of the parcel body */
memcpy(dbxilptr.d8xilpPt, &SplFlag, 8);
memcpy(ext_ptr, &dbxilptr.d8xilpPt, 8 * sizeof(char));
ext_ptr = (char *)ext_ptr + 8 * sizeof(char);
#else
/* Set reserved field to zero */
memset(dbxilptr.d8xilpP8, 0, 8 * sizeof(Byte));
memcpy(ext_ptr, &dbxilptr.d8xilpP8, 8 * sizeof(Byte));
ext_ptr = (char *)ext_ptr + 8 * sizeof(Byte);
#endif
}
/*************************************************************
*
main
*
************************************************************/
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
409
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel
main(int argc, char **argv)
{
unsigned int
MaxSegSize;
char str1[] = "replace procedure tmp(IN p1 integer,IN p2 integer, OUT
p3 integer)\n
begin\n
set p3=p1*p2;\n
end;\n";
char str2[] = "CALL tmp(2,3,p3);";
char str3[] = "RENAME PROCEDURE tmp TO tmp1;";
char str4[] = "SHOW PROCEDURE tmp1;";
char str5[] = "HELP PROCEDURE tmp1 attributes;";
char str6[] = "HELP 'spl WHILE' ;";
char str7[] = "DROP PROCEDURE tmp1;";
char psDefaultLogon[] = "dbc/systemfe,service";
psLogon = psDefaultLogon;
if (argc >= 2)
{
psLogon = argv[1];
}
if (psLogon == NULL)
{
psLogon = psDefaultLogon;
}
if (!strncmp(psLogon, "-h", 2))
{
printf ("clisamp logonstring(dbcname/username,password)\n");
exit(1);
}
printf("\nCLIv2
printf("MTDP
printf("MOSIOS
printf("MOSIDEP
printf("OSERR
version is %s\n",
version is %s\n",
version is %s\n",
version is %s\n",
version is %s\n\n",
COPCLIVersion);
COPMTDPVersion);
COPMOSIosVersion);
COPMOSIDEPVersion);
OSERRVersion);
dbc_init();
set_options();
dbc_con();
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
MaxSegSize=GetSegmentSize();
Setdbcareax();
dbc_irq(str1);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbcarea.extension_pointer=NULL;
dbcarea.dbriSeg='N';
dbc_irq(str2);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str3);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str4);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str5);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
410
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
dbc_erq();
dbc_irq(str6);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str7);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
exitout(0);
}
Sending TDSP Options Parcel Using APH
Defined Extension Elements
/*Copyright 2006, by Teradata Corporation. All rights reserved.
/* Teradata PROPRIETARY AND CONFIDENTIAL-RESTRICTED
*/
/* Creates a Stored procedure using dbcarea extension pointers */
/* This program demonstrates use of DBCAREA extension elements
/* (D8XIELEM and D8XIEP) defined for APH implementation in
/* CLI, to send MultiTSR parcels in Parcel mode
*/
*/
*/
/* Both 32-bit as well as
/* generated
*/
*/
64-bit executables can be
*/
#include<stdio.h>
#include<stdlib.h>
#include<string.h>
#include<coptypes.h>
#include<coperr.h>
#include<parcel.h>
#include <dbcarea.h>
#include <dbchqep.h>
DBCAREA dbcarea;
Int16 exitout(int n1);
Int16 dbc_con();
Int16 dbc_init();
Int16 dbc_irq(char *);
Int16 dbc_erq();
void set_options();
void act_count(Word );
Int16 fetch_request(long ,long);
void Setdbcareax();
unsigned int GetSegmentSize();
#define CONNECTED
#define
#define
#define
#define
#define
0
NOT_CONNECTED 1
OK
0
STOP
1
FAILED
-1
MAX_SESSIONS 1
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
411
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
#define
#define
#define
#define
#define
D8CAIRXSIZ
24
FIXED_ELM_LEN_8 42
D8XILMNTSIZE
4 /* sizeof (D8XIELEM) */
SPOPTIONSSIZE
2
D8XIEPSIZE
38 /* sizeof(D8XIEP) */
char logon_str[] = "nag2n1/clitst,clitst";
char *logonstr=logon_str;
Int32 result;
char
cnta[4];
struct ERROR_FAIL_Type {
Word
StatementNo;
Word
Info;
Word
Code;
Word
Length;
char
Msg[255];
} *Error_Fail;
write_error(parcel)
char *parcel;
{ int i;
Error_Fail = ((struct ERROR_FAIL_Type *) (parcel));
printf("%d : ",Error_Fail->Code);
for(i=0;i < (int)Error_Fail->Length;i++)
printf("%c",Error_Fail->Msg[i]);
printf("\n");
return(0);
}
/******************************************************************
*
function to initialize dbcarea
*
******************************************************************/
Int16 dbc_init()
{
dbcarea.total_len = sizeof(struct DBCAREA);
DBCHINI(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("\nError in initialization --%s",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/********************************************************************
*
function to logon
*
********************************************************************/
Int16 dbc_con()
{
printf("Logging on to :%s",logonstr);
dbcarea.logon_len=strlen(logonstr);
412
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
dbcarea.logon_ptr=logonstr;
dbcarea.func=DBFCON;
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK)
{
printf("\nError in Logon--%s\n",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/*********************************************************************
*
function to initiate request
*
*********************************************************************/
Int16 dbc_irq(char *str)
{
dbcarea.func = DBFIRQ;
printf("\nSubmitting request :%s",str);
dbcarea.req_ptr = str;
dbcarea.req_len = strlen(str);
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("Error in Initiating a request--%s",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/*******************************************************************
*
function to fetch parcels and check activity type
*
*******************************************************************/
Int16 fetch_request(request,session)
long request,session;
{
int count,i,status,rowcount;
int ShowFlag=0;
char ctc[6400];
struct CliSuccessType *SuccPcl;
struct CliOkType *OKPcl;
dbcarea.i_sess_id=session;
dbcarea.i_req_id=request;
dbcarea.func = DBFFET;
status=OK;
printf("\n");
rowcount=1;
while (status == OK){
DBCHCL(&result,cnta,&dbcarea);
count=1;
if (result == REQEXHAUST) status = STOP;
else if (result != EM_OK) status = FAILED;
else {
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
413
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
printf("Flavor Type : %d\n",dbcarea.fet_parcel_flavor);
switch (dbcarea.fet_parcel_flavor){
case PclSUCCESS :
SuccPcl = (struct CliSuccessType *) dbcarea.fet_data_ptr;
printf("Activity Type : %d\n",SuccPcl->ActivityType);
printf("Activity Count: %d\n",SuccPcl->ActivityCount);
act_count(SuccPcl->ActivityType);
break;
case PclOK
case PclFIELD
:
printf("\nOK Parcel\n");
OKPcl = (struct CliOkType *) dbcarea.fet_data_ptr;
printf("Activity type : %d\n",OKPcl->ActivityType);
printf("Activity Count : %d\n",OKPcl->ActivityCount);
act_count(OKPcl->ActivityType);
if (OKPcl->ActivityType==49)
ShowFlag=1;
else
ShowFlag=0;
break;
:
for (i=0;i<dbcarea.fet_ret_data_len;i++){
if ((ShowFlag==0) ||
((rowcount>2) && (dbcarea.fet_data_ptr[i] != ' ')))
printf("%c",dbcarea.fet_data_ptr[i]);
else
count++;
if ((count <8) && (dbcarea.fet_data_ptr[i]==' ')
&& ((ShowFlag ==1) ))
if ((rowcount != 4) && (count !=2))
printf("%c",dbcarea.fet_data_ptr[i]);
}
if((ShowFlag==0)
|| ((ShowFlag == 1) && (rowcount>5)))
printf("\n");
rowcount++;
break;
case PclRECORD :
/*Returned data */
printf( " %s\n",dbcarea.fet_data_ptr);
printf( "parcel length
%d\n",(Int32)dbcarea.fet_ret_data_len);
memcpy(&ctc[0],&dbcarea.fet_data_ptr[0],1);
memcpy(&ctc[1],&dbcarea.fet_data_ptr[1],1);
memcpy(&ctc[2],&dbcarea.fet_data_ptr[2],1);
printf("first two bytes -%s\n",ctc);
printf("first two bytes -%d\n",atoi(ctc));
break;
case PclENDSTATEMENT:
break;
case PclENDREQUEST :
break;
case PclFAILURE :
414
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
printf("failure parcel PCLFAILURE\n,length %d \n",
(Int32)dbcarea.fet_ret_data_len);
/*Failure
parcel*/
break;
case PclERROR :
printf("PCLERROR");
status = STOP;
write_error(dbcarea.fet_data_ptr);
exitout(CONNECTED);
break;
/*Error parcel
*/
} /*end of switch*/
} /*end of else*/
} /*end of while*/
if(status == FAILED)
{ printf("fetch failed -- %s\n",dbcarea.msg_text);
exitout(CONNECTED);
} /*if*/
printf("\n");
return EM_OK;
}
Int16 dbc_erq()
{
dbcarea.i_sess_id = dbcarea.o_sess_id;
dbcarea.i_req_id = dbcarea.o_req_id;
dbcarea.func = DBFERQ;
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("Error in EndRequest--%s\n",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/*********************************************************************
*
function to disconnect
*
*********************************************************************/
Int16 exitout(int n)
{
dbcarea.func = DBFDSC;
DBCHCL(&result,cnta,&dbcarea);
DBCHCLN(&result,cnta);
printf("\nExiting--%s",dbcarea.msg_text);
exit(n);
return(n);
}
/*********************************************************************
*
function to set options
*
*********************************************************************/
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
415
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
void set_options()
{
dbcarea.change_opts = 'Y';
dbcarea.resp_mode = 'F';
dbcarea.use_presence_bits = 'N';
dbcarea.keep_resp = 'N';
dbcarea.wait_across_crash = 'N';
dbcarea.tell_about_crash = 'Y';
dbcarea.loc_mode = 'Y';
dbcarea.var_len_req = 'N';
dbcarea.var_len_fetch = 'N';
dbcarea.save_resp_buf = 'N';
dbcarea.two_resp_bufs = 'N';
dbcarea.ret_time = 'N';
dbcarea.parcel_mode='Y';
dbcarea.wait_for_resp = 'Y';
dbcarea.req_proc_opt = 'E';
dbcarea.req_buf_len = 1024;
dbcarea.resp_buf_len = 1024;
}
void act_count(Word Activitytype)
{
switch(Activitytype){
case PclDropProcStmt :
printf("Procedure has been dropped\n");
break;
case PclRenProcStmt
:
printf("Procedure has been Renamed\n");
break;
case PclCallStmt
:
printf("Procedure has been Executed\n");
break;
case PclCreateProcStmt:
printf("Procedure has been Created\n");
break;
case PclShowStmt
:
printf("Show Procedure Successful\n\n");
break;
default
:
break;
}
return;
}
/********************************************************************
416
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
*
Function : GetSegmentSize
*
*
Purpose : Gets maximum segment size from server
*
********************************************************************/
unsigned int GetSegmentSize()
{
DBCHQEP QEPParms ;
unsigned int
MaxSegSize;
memset( &QEPParms, 0, sizeof( QEPParms ) );
QEPParms.qepLevel = QEPLEVEL;
QEPParms.qepItem = QEPIDMSS ;
QEPParms.qepRALen = sizeof( long );
QEPParms.qepRArea = &MaxSegSize;
QEPParms.qepTDP = ( long ) ( "nag2n1" );
QEPParms.qepTLen = strlen("nag2n1");
DBCHQE( &result, cnta, &QEPParms );
MaxSegSize = *(unsigned int *) QEPParms.qepRArea;
printf(" MaxSegSize :%d", MaxSegSize);
return(MaxSegSize);
}
/*********************************************************************
*
Function : Setdbcareax
*
*
Purpose : Uses the Extension pointer to send MultiTSR parcels*
**********************************************************************/
void Setdbcareax()
{
D8CAIRX
D8XIEP
D8XIELEM
void* memptr;
char * s ="PY";
*pExtArea;
*pElem;
*pElem_Typ_and_Len;
dbcarea.dbriSeg='L';
dbcarea.extension_pointer = malloc ( sizeof( D8CAIRX ) + sizeof
(D8XIELEM) + sizeof(D8XIEP));
pExtArea = (D8CAIRX *)dbcarea.extension_pointer;
memset( pExtArea, 0, sizeof( D8CAIRX ) +
( sizeof (D8XIELEM) + sizeof(D8XIEP) ));
pExtArea->d8xiId[0] = 'I';
pExtArea->d8xiId[1] = 'R';
pExtArea->d8xiId[2] = 'X';
pExtArea->d8xiId[3] = '8';
pExtArea->d8xiSize = sizeof( D8CAIRX ) + sizeof (D8XIELEM) +
sizeof(D8XIEP);
pExtArea->d8xiLvl = 1;
/* next the data parcel */
memptr = (char *)(pExtArea + 1);
pElem_Typ_and_Len = (D8XIELEM *)memptr;
pElem_Typ_and_Len->d8xieLen = D8XILMNTSIZE + D8XIEPSIZE;
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
417
Appendix A: Examples of Using DBCAREA Extension Elements
Sending TDSP Options Parcel Using APH Defined Extension Elements
pElem_Typ_and_Len->d8xieTyp = 0;
memptr = (char*)memptr +
D8XILMNTSIZE;
pElem = (D8XIEP *)memptr;
pElem->d8xiepF = PclSPOPTIONSTYPE;
pElem->d8xiepLn = 2;
pElem->d8xiepPt = s;
/* Flavor */
}
/*************************************************************
*
main
*
************************************************************/
main()
{
unsigned int
char str1[] =
p3 integer)\n
char str2[] =
char str3[] =
char str4[] =
char str5[] =
char str6[] =
char str7[] =
MaxSegSize;
"replace procedure tmp(IN p1 integer,IN p2 integer, OUT
begin\n
set p3=p1*p2;\n
end;\n";
"CALL tmp(2,3,p3);";
"RENAME PROCEDURE tmp TO tmp1;";
"SHOW PROCEDURE tmp1;";
"HELP PROCEDURE tmp1 attributes;";
"HELP 'spl WHILE' ;";
"DROP PROCEDURE tmp1;";
dbc_init();
set_options();
dbc_con();
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
MaxSegSize=GetSegmentSize();
Setdbcareax();
dbcarea.dbriSeg = 'L';
dbc_irq(str1);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbcarea.extension_pointer=NULL;
dbcarea.dbriSeg='N';
dbc_irq(str2);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str3);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str4);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str5);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str6);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str7);
418
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
exitout(0);
}
Sending a Parameterized SQL Using APH
Defined Extension Elements
/*Copyright 2006, by Teradata Corporation. All rights reserved.
/* Teradata PROPRIETARY AND CONFIDENTIAL-RESTRICTED
*/
/* Sends a NON-APH datainfo and data parcel using dbcarea
*/
/* extension for a parameterized SQL
*/
/* This program makes use of pointer elements in Extension
*/
/* designed for APH support D8XIEP, D8XIELEM
*/
/* Both 32-bit as well as
*/
64-bit execuatbles can be generated */
#include<stdio.h>
#include<stdlib.h>
#include<string.h>
#include<coptypes.h>
#include<coperr.h>
#include<parcel.h>
#include <dbcarea.h>
#include <dbchqep.h>
DBCAREA dbcarea;
Int16 exitout(int n1);
Int16 dbc_con();
Int16 dbc_init();
Int16 dbc_irq(char *);
Int16 dbc_erq();
void set_options();
void act_count(Word );
Int16 fetch_request(long ,long);
void Setdbcareax();
unsigned int GetSegmentSize();
#define CONNECTED
#define
#define
#define
#define
#define
0
NOT_CONNECTED 1
OK
0
STOP
1
FAILED
-1
MAX_SESSIONS 1
char logon_str[] = "nag2n1/clitst,clitst";
char *logonstr=logon_str;
Int32 result;
char
cnta[4];
char *psLogon;
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
419
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
struct ERROR_FAIL_Type {
Word
StatementNo;
Word
Info;
Word
Code;
Word
Length;
char
Msg[255];
} *Error_Fail;
typedef struct
{
UInt16
UInt16
UInt16
}DATAINFO;
FieldCount;
Datatype;
Length;
#ifdef WIN32
__declspec(dllimport)
__declspec(dllimport)
__declspec(dllimport)
__declspec(dllimport)
__declspec(dllimport)
#else
extern
extern
extern
extern
extern
#endif
char
char
char
char
char
char
char
char
char
char
COPCLIVersion[];
COPMTDPVersion[];
COPMOSIosVersion[];
COPMOSIDEPVersion[];
OSERRVersion[];
COPCLIVersion[];
COPMTDPVersion[];
COPMOSIosVersion[];
COPMOSIDEPVersion[];
OSERRVersion[];
write_error(parcel)
char *parcel;
{ int i;
Error_Fail = ((struct ERROR_FAIL_Type *) (parcel));
printf("%d : ",Error_Fail->Code);
for(i=0;i < (int)Error_Fail->Length;i++)
printf("%c",Error_Fail->Msg[i]);
printf("\n");
return(0);
}
/******************************************************************
*
function to initialize dbcarea
*
******************************************************************/
Int16 dbc_init()
{
dbcarea.total_len = sizeof(struct DBCAREA);
DBCHINI(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("\nError in initialization --%s",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/********************************************************************
420
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
*
function to logon
*
********************************************************************/
Int16 dbc_con()
{
printf("Logging on to :%s",psLogon);
dbcarea.logon_len=strlen(psLogon);
dbcarea.logon_ptr=psLogon;
dbcarea.func=DBFCON;
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK)
{
printf("\nError in Logon--%s\n",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/*********************************************************************
*
function to initiate request
*
*********************************************************************/
Int16 dbc_irq(char *str)
{
dbcarea.func = DBFIRQ;
printf("\nSubmitting request :%s",str);
dbcarea.req_ptr = str;
dbcarea.req_len = strlen(str);
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("Error in Initiating a request--%s",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/*******************************************************************
*
function to fetch parcels and check activity type
*
*******************************************************************/
Int16 fetch_request(request,session)
long request,session;
{
int count,status,rowcount;
int ShowFlag=0;
char ctc[6400];
struct CliSuccessType *SuccPcl;
struct CliOkType *OKPcl;
dbcarea.i_sess_id=session;
dbcarea.i_req_id=request;
dbcarea.func = DBFFET;
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
421
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
status=OK;
printf("\n");
rowcount=1;
while (status == OK){
DBCHCL(&result,cnta,&dbcarea);
count=1;
if (result == REQEXHAUST) status = STOP;
else if (result != EM_OK) status = FAILED;
else {
switch (dbcarea.fet_parcel_flavor){
/*getch();*/
printf ("%d",dbcarea.fet_parcel_flavor);
case PclSUCCESS :
SuccPcl = (struct CliSuccessType *) dbcarea.fet_data_ptr;
act_count(SuccPcl->ActivityType);
break;
case PclOK
:
OKPcl = (struct CliOkType *) dbcarea.fet_data_ptr;
act_count(OKPcl->ActivityType);
if (OKPcl->ActivityType==49)
ShowFlag=1;
else
ShowFlag=0;
break;
case PclFIELD
:
break;
case PclRECORD :
break;
/*Returned data */
case PclENDSTATEMENT:
break;
case PclENDREQUEST :
break;
case PclFAILURE :
printf("failure parcel PCLFAILURE\n,length %d \n",
(Int32)dbcarea.fet_ret_data_len);
/*Failure
parcel*/
break;
case PclERROR :
printf("PCLERROR");
status = STOP;
write_error(dbcarea.fet_data_ptr);
exitout(CONNECTED);
break;
/*Error parcel
*/
} /*end of switch*/
} /*end of else*/
} /*end of while*/
if(status == FAILED)
422
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
{ printf("fetch failed -- %s\n",dbcarea.msg_text);
exitout(CONNECTED);
} /*if*/
printf("\n");
return EM_OK;
}
Int16 dbc_erq()
{
dbcarea.i_sess_id = dbcarea.o_sess_id;
dbcarea.i_req_id = dbcarea.o_req_id;
dbcarea.func = DBFERQ;
DBCHCL(&result,cnta,&dbcarea);
if (result != EM_OK){
printf("Error in EndRequest--%s\n",dbcarea.msg_text);
exitout(1);
}
return EM_OK;
}
/*********************************************************************
*
function to disconnect
*
*********************************************************************/
Int16 exitout(int n)
{
dbcarea.func = DBFDSC;
DBCHCL(&result,cnta,&dbcarea);
DBCHCLN(&result,cnta);
printf("\nExiting--%s",dbcarea.msg_text);
exit(n);
return(n);
}
/*********************************************************************
*
function to set options
*
*********************************************************************/
void set_options()
{
dbcarea.change_opts = 'Y';
dbcarea.resp_mode = 'F';
dbcarea.use_presence_bits = 'N';
dbcarea.keep_resp = 'N';
dbcarea.wait_across_crash = 'N';
dbcarea.tell_about_crash = 'Y';
dbcarea.loc_mode = 'Y';
dbcarea.var_len_req = 'N';
dbcarea.var_len_fetch = 'N';
dbcarea.save_resp_buf = 'N';
dbcarea.two_resp_bufs = 'N';
dbcarea.ret_time = 'N';
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
423
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
dbcarea.parcel_mode='Y';
dbcarea.wait_for_resp = 'Y';
dbcarea.req_proc_opt = 'E';
dbcarea.req_buf_len = 1024;
dbcarea.resp_buf_len = 1024;
}
void act_count(Word Activitytype)
{
switch(Activitytype){
case PclDropTabStmt :
printf("\n-----------Table dropped-------------\n");
break;
case PclCTStmt:
printf("\n-----------Table Created-------------\n");
break;
case PclInsStmt
:
printf("\n-------------Insert Successful-------
-\n");
break;
case PclRetStmt
-\n");
: printf("\n-------------Select Successful--------break;
default
:
break;
}
return;
}
/********************************************************************
*
Function : GetSegmentSize
*
*
Purpose : Gets maximum segment size from server
*
********************************************************************/
unsigned int GetSegmentSize()
{
DBCHQEP QEPParms ;
unsigned int
MaxSegSize;
memset( &QEPParms, 0, sizeof( QEPParms ) );
QEPParms.qepLevel = QEPLEVEL;
QEPParms.qepItem = QEPIDMSS ;
QEPParms.qepRALen = sizeof( long );
QEPParms.qepRArea = &MaxSegSize;
QEPParms.qepTDP = ( long ) ( "nag2n1" );
QEPParms.qepTLen = strlen("nag2n1");
DBCHQE( &result, cnta, &QEPParms );
MaxSegSize = *(unsigned int *) QEPParms.qepRArea;
424
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
printf(" MaxSegSize :%d", MaxSegSize);
return(MaxSegSize);
}
void Setdbcareax()
{
D8CAIRX
*pExtArea;
D8XIEP
*pElem;
D8XIELEM
*pElem_Typ_and_Len;
void* memptr;
int* data;
DATAINFO* datainfo;
datainfo = malloc (sizeof(DATAINFO));
data = malloc(sizeof(data));
*data =1;
datainfo->FieldCount =1;
datainfo->Datatype
=496;
datainfo->Length
=4;
dbcarea.extension_pointer = malloc ( sizeof( D8CAIRX ) + (2 *(
sizeof(D8XIELEM) + sizeof(D8XIEP) )));
pExtArea = (D8CAIRX *)dbcarea.extension_pointer;
memset( pExtArea, 0, sizeof( D8CAIRX ) +
(2 * (( sizeof (D8XIELEM) + sizeof(D8XIEP) ))) );
pExtArea->d8xiId[0] = 'I';
pExtArea->d8xiId[1] = 'R';
pExtArea->d8xiId[2] = 'X';
pExtArea->d8xiId[3] = '8';
pExtArea->d8xiSize = sizeof( D8CAIRX ) +(2 * (( sizeof (D8XIELEM) +
sizeof(D8XIEP) ))) ;
pExtArea->d8xiLvl = 1;
/* next the data parcel */
memptr = (char *)(pExtArea + 1);
pElem_Typ_and_Len = (D8XIELEM *)memptr;
pElem_Typ_and_Len->d8xieLen = sizeof (D8XIELEM) + sizeof(D8XIEP);
pElem_Typ_and_Len->d8xieTyp = 0;
memptr = (char*)memptr +
sizeof (D8XIELEM);
pElem = (D8XIEP *)memptr;
pElem->d8xiepF = PclDATAINFO;
/* Flavor */
pElem->d8xiepLn = sizeof(DATAINFO);
pElem->d8xiepPt = datainfo;
memptr = (char*)memptr + sizeof (D8XIEP);
pElem_Typ_and_Len = (D8XIELEM *)memptr;
pElem_Typ_and_Len->d8xieLen = sizeof (D8XIELEM) + sizeof(D8XIEP);
pElem_Typ_and_Len->d8xieTyp = 0;
memptr = (char*)memptr + sizeof (D8XIELEM);
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
425
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
pElem = (D8XIEP *)memptr;
pElem->d8xiepF = PclDATA;
pElem->d8xiepLn = sizeof(int);
pElem->d8xiepPt = data;
/* Flavor */
}
/*************************************************************
*
main
*
************************************************************/
main(int argc, char **argv)
{
char str0[]= "drop table samp";
char str1[] = "create table samp ( i int)";
char str2[] = "insert into samp (1)";
char str3[] = "select * from samp where i=?";
char psDefaultLogon[] = "dbc/systemfe,service";
psLogon = psDefaultLogon;
if (argc >= 2)
{
psLogon = argv[1];
}
if (psLogon == NULL)
{
psLogon = psDefaultLogon;
}
if (!strncmp(psLogon, "-h", 2))
{
printf ("clisamp logonstring(dbcname/username,password)\n");
exit(1);
}
printf("\nCLIv2
printf("MTDP
printf("MOSIOS
printf("MOSIDEP
printf("OSERR
version is %s\n",
version is %s\n",
version is %s\n",
version is %s\n",
version is %s\n\n",
COPCLIVersion);
COPMTDPVersion);
COPMOSIosVersion);
COPMOSIDEPVersion);
OSERRVersion);
dbc_init();
set_options();
dbc_con();
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str0);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbc_irq(str1);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
dbcarea.extension_pointer=NULL;
dbcarea.dbriSeg='N';
dbc_irq(str2);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
426
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
dbc_erq();
Setdbcareax();
dbc_irq(str3);
fetch_request(dbcarea.o_req_id,dbcarea.o_sess_id);
dbc_erq();
exitout(0);
}
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
427
Appendix A: Examples of Using DBCAREA Extension Elements
Sending a Parameterized SQL Using APH Defined Extension Elements
428
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Glossary
A
ABORT In Teradata SQL, a statement that stops a transaction in progress and backs out
changes to the database only if the conditional expression associated with the abort statement
is true.
administrator
A special user responsible for allocating resources to a community of users.
ANSI American National Standards Institute. ANSI maintains a standard for SQL. For
information about Teradata compliance with ANSI SQL, see SQL Fundamentals.
API Application Program Interface. An interface (calling conventions) by which an
application program accesses an operating system and other services. An API is defined at
source code level and provides a level of abstraction between the application and the kernel
(or other privileged utilities) to ensure the portability of the code.
An API can also provide an interface between a high level language and lower level utilities
and services written without consideration for the calling conventions supported by compiled
languages. In this case, the API may translate the parameter lists from one format to another
and the interpret call-by-value and call-by-reference arguments in one or both directions.
ASCII American Standard Code for Information Interchange, a character set used
primarily on personal computers.
B
BLOB An acronym for binary large object. A BLOB is a large database object that can be
anything that doesn’t require character set conversion. This includes MIDI, MP3, PDF,
graphics and much more. BLOBS can be up to 2 GB in size.
BTEQ Basic Teradata Query facility. A utility that allows users on a workstation to access
data on a Teradata Database, and format reports for both print and screen output.
C
Call-Level Interface Version 2 (CLIv2) A library of routines that enable an application
program to access data stored in Teradata Database. When used with network-attached
clients, CLIv2 contains the following components:
CLI (Call-Level Interface)
• MTDP (Micro Teradata Director Program
• MOSI (Micro Operating System Interface)
•
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
429
Glossary
Version 2 of the CLI interface. A collection of callable service routines that provide an
interface to a Teradata Database. The interface between the application program and the
MTDP (for network-attached clients) or TDP (for channel-attached clients).
channel-attached A mainframe computer that communicates with a server (for example, a
Teradata Database) through a channel driver.
character set A grouping of alphanumeric and special characters used by computer systems
to support different user languages and applications. Various character sets have been codified
by the American National Standards Institute (ANSI).
client
A computer that can access Teradata Database.
CLOB An acronym for character large object. A CLOB is a pure character-based large object
in a database. It can be a large text file. HTML, RTF or other character-based file. CLOBs can
be up 2 GB in size. Also see BLOB and LOB.
column In the relational model of Teradata SQL, databases consist of one or more tables. In
turn, each table consists of fields, organized into one or more columns by zero or more rows.
All of the fields of a given column share the same attributes.
D
Data Definition Language (DDL) In Teradata SQL, the statements and facilities that
manipulate database structures (such as CREATE, MODIFY, DROP, GRANT, REVOKE, and
GIVE) and the Data Dictionary information kept about those structures. In the typical, prerelational data management system, data definition and data manipulation facilities are
separated, and the data definition facilities are less flexible and more difficult to use than in a
relational system.
DB2 IBM DATABASE 2
DDL Data definition language, which supports manipulating database structures and the
Data Dictionary information kept about these structures.
DEFINE Statement A statement preceding the INSERT statement that describes the fields
in a record before the record is inserted in the table. This statement is similar to the SQL
USING clause.
delimiter In Teradata SQL, a punctuation mark or other special symbol that separates one
clause in a Teradata SQL statement from another, or that separates one Teradata SQL
statement from another.
DLL Dynamic-link library. A feature of the Windows family of operating systems that allows
executable routines to be stored separately as files with .dll extensions and to be loaded only
when needed by a program.
domain name A group of computers whose host names (the unique name by which a
computer is known on a network) share a common suffix, that is the domain name.
430
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Glossary
EBCDIC Extended binary coded decimal interchange code. An IBM code that uses 8 bits to
represent 256 possible characters. It is used primarily in IBM mainframes, whereas personal
computers use ASCII.
exit routine Specifies a predefined action to be performed whenever certain significant
events occur during a MultiLoad job.
F
failure Any condition that precludes complete processing of a Teradata SQL statement. Any
failure will abort the current transaction.
field The basic unit of information stored in the Teradata Database. A field is either null, or
has a single numeric or string value. See also column, database, row, table.
function User-defined functions (UDF) are extensions to Teradata SQL. Users can write
UDFs to analyze and transform data already stored in their data warehouse in ways that are
beyond the functionality of Teradata’s native functions.
G
Gateway
A device that connects networks having different protocols.
GSS Generic Security Services. An application level interface (API) to system security
services. It provides a generic interface to services which may be provided by a variety of
different security mechanisms. Vanilla GSS-API supports security contexts between two
entities (known as "principals").
I
In-Doubt A transaction that was in process on two or more independent computer
processing systems when an interruption of service occurred on one or more of the systems.
The transaction is said to be in doubt because it is not known whether the transaction was
successfully processed on all of the systems.
internet protocol (IP) Data transmission standard; the standard that controls the routing
and structure of data transmitted over the Internet.
I/O Input/output.
J
JIS Japanese Industrial Standards specify the standards used for industrial activities in
Japan. The standardization process is coordinated by Japanese Industrial Standards
Committee and published through Japanese Standards Association.
L
LAN Local Area Network. LANs supported by Teradata products must conform to the IEEE
802.3 standard (Ethernet LAN).
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
431
Glossary
LOB An acronym for large object. A large object is a database object that is large in size.
LOBs can be up to 2 gigabytes. There are two types of LOBs, CLOBs and BLOBs. CLOBs are
character-based objects, BLOBs are binary-based objects.
log A record of events. A file that records events. Many programs produce log files. Often
you will look at a log file to determine what is happening when problems occur. Log files have
the extension .log.
M
macro a file that is created and stored on the Teradata Database, and is executed in response
to a Teradata SQL EXECUTE statement
methods In object-oriented programming, methods are the programming routines by
which objects are manipulated.
MOSI Micro Operating System Interface. A library of routines that implement operating
system dependent and protocol dependent operations on the workstation.
MTDP Micro Teradata Director Program. A library of routines that implement the session
layer on the workstation. MTDP is the interface between CLI and the Teradata Database.
multi-threading An option that enables you to speed up your export and import operations
with multiple connections.
N
network
In the context of the Teradata Database, a LAN (see LAN).
network attached A computer that communicates over the LAN with a server (for example,
a Teradata Database).
null
The absence of a value for a field.
O
object In object-oriented programming, a unique instance of a data structure defined
according to the template provided by its class. Each object has its own values for the variables
belonging to its class and can respond to the messages, or methods, defined by its class.
P
parameter A variable name in a macro for which an argument value is substituted when the
macro is executed.
privilege A user’s right to perform the Teradata SQL statements granted to him against a
table, database, user, macro, or view. Also known as access right.
procedure Short name for Teradata stored procedure. Teradata provides Stored Procedural
Language (SPL) to create stored procedures. A stored procedure contains SQL to access data
from within Teradata and SPL to control the execution of the SQL.
432
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Glossary
protocol The rules for the format, sequence and relative timing of messages exchanged on a
network.
R
records When using the Teradata utilities, both formatted and unformatted records are
accepted for loading. A formatted record, in the Teradata Database world, consists of a record
created by a Teradata Database utility, such as BTEQ, where the record is packaged with beginand end-record bytes specific to the Teradata Database. Unformatted records are any records
not originating on a Teradata Database These files contain records that must be defined before
loading onto the Teradata Database.
request In host software, a message sent from an application program to the Teradata
Database.
result The information returned to the user to satisfy a request made of the Teradata
Database.
results table/file In the Schedule Request environment, a results table or file is a database
table or a Windows file into which result data for a schedule request that is not self-contained
are stored.
row Whether null or not, that represent one entry under each column in a table. The row is
the smallest unit of information operated on by data manipulation statements.
RowID join In Teradata SQL, this join occurs when one of the join tables has a non-unique
primary index constant, and another column of that table matches weakly with a non-unique
secondary index column of the second table.
S
script
A file that contains a set of BTEQ commands and/or SQL statements.
server A computer system running the Teradata Database. Typically, a Teradata Database
server has multiple nodes, which may include both TPA and non-TPA nodes. All nodes of the
server are connected via the Teradata BYNET or other similar interconnect.
session In client software, a logical connection between an application program on a host
and the Teradata Database that permits the application program to send one request to and
receive one response from the Teradata Database at a time.
source database
Warehouse.
The database from which data will be extracted or copied into the Data
SQL Structured Query Language. An industry-standard language for creating, updating
and, querying relational database management systems. SQL was developed by IBM in the
1970s for use in System R. It is the de facto standard as well as being an ISO and ANSI
standard. It is often embedded in general purpose programming languages.
Programming language used to communicate with the Teradata Database.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
433
Glossary
SSO Single Sign-On, an authentication option that allows users of the Teradata Database on
Windows systems to access the Teradata Database based on their authorized network
usernames and passwords. This feature simplifies the procedure requiring users to enter an
additional username and password when logging on to Teradata Database via client
applications.
statement A request for processing by the Teradata Databasethat consists of a keyword verb,
optional phrases, operands and is processed as a single entity.
statistics These are the details of the processes used to collect, analyze, and transform the
database objects used by a given query.
stored procedure Teradata Version 2 Release 4 and later supports stored procedures. A
stored procedure is a combination of SQL statements and control and conditional handling
statements that run using a single call statement.
T
table A set of one or more columns with zero or more rows that consist of fields of related
information.
target database The database in which data will be loaded or inserted.
target table
TCP/IP
A user table where changes are to be made by an MLOAD task.
Transmission Control Protocol/Internet Protocol.
TDPID Teradata Director Program Identifier. The name of the Teradata Database being
accessed.
Teradata SQL The Teradata Database dialect of the relational language SQL, having data
definition and data manipulation statements. A data definition statement would be a CREATE
TABLE statement and a data manipulation statement would be a data retrieval statement (a
SELECT statement).
TDP Teradata Director Program; TDP provides a high-performance interface for messages
communicated between the client and the Teradata system.
title In Teradata SQL, a string used as a column heading in a report. By default, it is the
column name, but a title can also be explicitly declared by a TITLE phrase.
transaction A set of Teradata SQL statements that is performed as a unit. Either all of the
statements are executed normally or else any changes made during the transaction are backed
out and the remainder of the statements in the transaction are not executed. The Teradata
Database supports both ANSI and Teradata transaction semantics.
trigger One or more Teradata SQL statements associated with a table and executed when
specified conditions are met.
type An attribute of a column that specifies the representation of data values for fields in
that column. Teradata SQL data types include numerics and strings.
434
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Glossary
U
UDF
User-defined function
Unicode A fixed-width (16 bits) encoding of virtually all characters present in all languages
in the world.
user In Teradata SQL, a database associated with a person who uses the Teradata Database.
The database stores the person’s private information and accesses other Teradata Databases.
UTF-16
A 16-bit Unicode Translation Format.
V
varbyte A data type that represents a variable-length binary string.
varchar A data type that represents a variable-length non-numeric character.
vargraphic
A data type that represents a variable-length string of characters.
view An alternate way of organizing and presenting information in a Teradata Database. A
view, like a table, has rows and columns. However, the rows and columns of a view are not
directly stored by the Teradata Database. They are derived from the rows and columns of
tables (or other views) whenever the view is referenced.
W
workstation
A network-attached client.
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
435
Glossary
436
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Index
Symbols
*qepMsgP 222
*qepRArea 222
Numerics
qepRsv1 222
A
aborting
requests 53
transactions 52
alarms, setting 36
all-or-nothing property 30
AP Reset Containment (APRC). See Crashes
APH Defined Extension Elements 411, 419
application control block 28
Assign parcel 260
AssignRsp parcel 261
Asynchronous connections 196
B
buffering 44, 47
C
calls, directly to CLI 26
Change Options field 88, 89, 93, 97, 111, 113, 132, 137, 140,
145, 160, 161, 167, 168, 170, 171
Character Set Pointer field 91
Character Set Type 92
CLICON
connecting one or more sessions 141
maximum buffer size 141
clispb.dat
accessing 65
contents of 66
names 68
system parameter block 28
COBOL
DATE-FORM 98
DBCAREA-0-REQ-ID 130
DBCAREA-CHANGE-OPTS 88
DBCAREA-CONFORMANCE 111
DBCAREA-CONNECT-TYPE 93
DBCAREA-CUR-REQ-BUF-LEN 95
DBCAREA-CUR-RESP-BUF-LEN 96
DBCAREA-EXT-PTR 100
DBCAREA-EYECATCHER 101
DBCAREA-FET-ERROR-IND 104
DBCAREA-FET-PARCEL-FLAVOR 105
DBCAREA-FET-RET-DATA-LEN 106
DBCAREA-FUNC 108
DBCAREA-I-DBCPATH 108
DBCAREA-I-REQ-ID 109
DBCAREA-I-SESS-ID 109
DBCAREA-KEEP-RESP 110
DBCAREA-LOC-MODE 112
DBCAREA-LOGON-LEN 114
DBCAREA-LOGON-PTR 114
DBCAREA-MAX-NUM-SESS 119
DBCAREA-MSG-LEN 124
DBCAREA-MSG-TEXT 126
DBCAREA-O-DBCPATH 129
DBCAREA-O-DBC-SESS-ID 128
DBCAREA-O-HOST-ID 129
DBCAREA-O-SESS-ID 131
DBCAREA-PARCEL-MODE 132
DBCAREA-REQ-BUF-LEN 135
DBCAREA-REQ-LEN 136
DBCAREA-REQ-PROC-OPT 139
DBCAREA-REQ-PTR 138
DBCAREA-REQUEST-MODE 137
DBCAREA-RESP-BUF-LEN 141
DBCAREA-RESP-MODE 141
DBCAREA-RETURN-CD 142
DBCAREA-RUN-LEN 145
DBCAREA-RUN-PTR 146
DBCAREA-SEMANTICS 157
DBCAREA-TELL-ABOUT-CRASH 150
DBCAREA-TOKEN 155
DBCAREA-TOTAL-LEN 156
DBCAREA-USE-PRESENCE-BITS 160
DBCAREA-USING-DATA-LEN 162
DBCAREA-USING-DATA-PTR 164, 165, 166
DBCAREA-VAR-LEN-FETCH 167
DBCAREA-VAR-LEN-REQ 168
DBCAREA-WAIT-ACROSS-CRASH 169
DBCAREA-WAIT-FOR-RESP 170
MAXIMUM-PARCEL 121
MESSAGE AREA LENGTH 122
MESSAGE AREA POINTER 123
common routines
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
437
Index
DBCHCL 34
DBCHINI 34
Connect parcel 263
Connect Type field 137
Connect Wait field 93
connecting one or more sessions, CLICON 141
COP 39
Crashes
application, response to 365
just tell 367
just wait 366
tell and wait 366
APRC and 364
MTDP, response to 364
Teradata Database, response to 363
Current Request Buffer Length field 95
Current Response Buffer Length field 96
D
Data Encryption field 96
Data parcel 265
data structures 28
data types
indicator mode 288, 305
IndicData parcel 280
internal format 307
record mode 306
DataInfo parcel 349
ECHO statement 266
Date Form field 97
DBCAREA 36
allocating 74
as interface 73
data structure 27
defined 27
fields
Change Options 88, 93, 97, 111, 113, 132, 137, 140, 145,
160, 161, 167, 168, 170, 171
Character Set Pointer 91
Character Set Type 92
Connect Type 137
Connect Wait 93
Current Request Buffer Length 95
Current Response Buffer Length 96
Data Encryption 96
Date Form 97
Extension Pointer 100
Eyecatcher 101
Fetch Data Pointer 107, 113, 168
Fetch Data Pointer, Locate Mode 103
Fetch Data Pointer, Move Mode 102
Fetch Error Indicator 104, 113
Fetch Maximum Data Length field 113
438
Fetch Parcel Flavor 105, 113
Fetch Returned Data Length 106, 113, 168
Function 107
Input DBCpath 108
Input Request Id 109, 131
Input Session Id 109, 131
Keep Response 110, 138
Language Conformance 111
Locate Mode 103, 106, 112, 113, 168
Logon Length 113
Logon Pointer 114
Maximum Parcel 120, 136, 141
Message Length 124
Message Text 126
Move Mode 102, 107, 113
MTDP Received 127
MTDP Sent 127
not used 173
Output DBC Session Id 128
Output DBCpath 129
Output Host Id 129
Output Request Id 109, 130
Output Session Id 110, 131, 197, 237
Parcel Mode Fetch 102, 103, 106, 113, 132, 171
Request Buffer Length 135
Request Length 136, 169
Request Mode 137, 138
Request Pointer 138, 169
Request Processing Option 139
Response Buffer Length 141
Response Buffer Size 138
Response Mode 141
Return Code 126, 142, 145
Return Time 127, 128, 144
Run Length 145
Run Pointer 145, 146
TDP Request Number 131
Tell About Crash 149, 365
Token 155
Total Length 156
Transaction Semantics 157
Two Response Buffers 159
Use Presence Bits 160, 161, 163, 165
Using Data Length 161, 162
Using Data Length Array 163
Using Data Pointer 161, 164
Using Data Pointer Array 165
Variable Length Fetch 106, 113, 167, 168
Variable Length Request 137, 138, 168, 169
Wait Across Crash 169, 365
Wait for Response 170
Wait For Response field 365
fields, mnemonic names of 71
logical sections of 82
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Index
DBCAREA Extension Elements 411, 419
DBCAREA.H
change_opts 88
connect_type 93
cur_req_buf_len 95
cur_resp_buf_len 96
date_form 98
extension_pointer 100
eyecatcher 101
fet_error_ind 104
fet_parcel_flavor 105
fet_ret_data_len 106
func 108
i_dbcpath 108
i_req_id 109
i_sess_id 109
keep_resp 110
lang_conformance 111
loc_mode 112
logon_len 114
logon_ptr 114
max_num_sess 119
maximum_parcel 121
message_area_length 122
message_area_pointer 123
msg_len 124
msg_text 126
mtdp_received 127
mtdp_sent 128
o_dbc_sess_id 128
o_dbcpath 129
o_host_id 129
o_req_id 130
o_sess_id 131
parcel_mode 132
req_buf_len 135
req_proc_opt 139
req_ptr 138
req-len 136
request_mode 137
resp_buf_len 141
resp_mode 141
return_cd 142
run_len 145
run_ptr 146
tell_about_crash 150
token 155
total_len 156
tr_semantics 157
use_presence_bits 160
using_data_len 162
using_data_ptr 164, 165, 166
var_len_fetch 167
var_len_req 168
wait_across_crash 169
wait_for_resp 170
DBCAREA.H, defined 87
DBCAREAC, defined 87
DBCHCL. See routines
DBCHFER. See routines
DBCHINI. See routines
DBCHPEC. See routines
DBCHQE. See routines
DBCHREL. See routines
DBCHSAD. See routines
DBCHUE. See routines
DBCHUEC. See routines
DBCHWAT. See routines
DBFABT. See routines (DBCHCL)
DBFCON 193
DBFCON. See routines (DBCHCL)
DBFDSC. See routines (DBCHCL)
DBFERQ. See routines (DBCHCL)
DBFFET. See routines (DBCHCL)
DBFIRQ. See routines (DBCHCL)
DBFREW. See routines (DBCHCL)
DBFRSUP. See routines (DBCHCL)
Direct sign-on 197
E
ECHO statement
DataInfo parcel 266
PrepInfo parcel 297, 299
record mode 306
Record parcel 306
EndRequest parcel 344, 349, 354
EndStatement parcel 344, 349, 354
EndWith parcel 344, 349, 354
environment variable
GUILOGON 197
THREADONOFF 62
error codes 357
Error parcel
described 337
error codes 359
Field Mode 344
Indicator Mode 349
KeepResp parcel and 272
purpose 272
Record Mode 354
Resp parcel and 272
typical response sequence 337
exit functions
CliPostSQLExt 389
CliPreSQLExt 388
CliUsrLgnExt 386
overview 385
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
439
Index
parameters 386
Extension Pointer field 100
Eyecatcher field, DBCAREA 101
purpose 282
Kerberos 76
KRB5C 77
F
L
failure codes 357
Failure parcel 337, 344, 349, 354, 359
Fetch Data Pointer (Locate Mode) field 103
Fetch Data Pointer (Move Mode) field 102
Fetch Data Pointer field 107, 113, 168
Fetch Error Indicator field 104, 113
Fetch Maximum Data Length field 105, 113
Fetch Parcel Flavor field 105, 113
Fetch Returned Data Length field 106, 113, 168
Field parcel 344
Fields in DBCAREA
Time5 152
Time5-status 154, 155
Timing Precision 153
find software release number with DBCHREL routine 236
find version number, DBCHREL routine 216
format of Teradata 307
FormatEnd parcel 344
FormatStart parcel 344
Function field 107
Language Conformance field 111
LDAP 78
Locate Mode field 103, 106, 112, 113, 168
logical structure 26
Logoff parcel 283
Logon Length field 113
Logon Pointer field 114
G
GUILOGON 197
I
M
Maximum Parcel field 120, 136, 141
Message Length field 124
Message Text field 126
MOSI, used by CLI 26
Move area 336
Move Mode field 107, 113
MTDP
control block 28
Received field 127
relation to CLI 26
Sent field 127
multiple DBCAREAs 36
multi-session management 33
multi-statement management 32
multi-thread management 32
Multi-TSR 289
Indicator mode
DataInfo parcel 288, 305
null indicator 288, 305
Response parcel 287, 304
SELECT statement and 288, 305
IndicData parcel, data type 280
information flow
all-or-nothing property 30
thread, defined 32
with Teradata Database 29
Initiate With Protocol-Function 331
Input DBCpath field 108
Input Request Id field 109, 131
Input Session Id field 109, 131
internal format of data 307
IVRunStartup parcel 281
N
K
parallel operations 31
parameterized SQL 419
Parcel
Assign 260
AssignRsp 261
Keep Response field 110, 138
KeepResp parcel
Error parcel, relation to 272
440
NTLM 77
NTLMC 78
NullField parcel 290, 344
O
Ok parcel 344
options processing 57, 89
Output DBC Session Id field 128
Output DBCpath field 129
Output Host Id field 129
Output Request Id field 109, 130
Output Session Id field 110, 131, 197, 237
P
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Index
body 249
Connect 263
Data 265
DataInfo 349
defined 245
EndRequest 344, 349, 354
EndStatement 344, 349, 354
EndWith 344, 349, 354
Error 272, 337, 344, 349, 354, 359
Failure 337, 344, 349, 354, 359
Field 344
flavor 245
FormatEnd 344
FormatStart 344
header 245
IVRunStartup 281
KeepResp 282
Logoff 283
NullField 290, 344
Ok 344
PosEnd 344, 349
Position 344, 349
PosStart 344, 349
RecEnd 344
Record 287, 303, 304, 349, 354
RecStart 344
Resp 274, 309
Rewind 314
RunStartup 316
sequence 338
Size 344
SizeEnd 344
SizeStart 344
structure 245
Success 349, 354
TitleEnd 344
TitleStart 344
types
request 249, 250
response 250, 252
With 344, 349, 354
Parcel Mode Fetch field 102, 103, 106, 113, 132, 171
partition name values 315
passwords 36
Performance Monitor, sending requests to 315
PosEnd parcel 344, 349
Position parcel 344, 349
Positioning-action 133
PosStart parcel 344, 349
PrepInfo parcel, ECHO statement 297, 299
product version numbers 3
Q
QEP64K 225
qepConn 222
QEPIACS 229
QEPIALM 230
QEPIAOP 226
QEPIAPH 230
QEPIASL 228
QEPIC2L 231
QEPICCS 233
QEPICL2R 225
QEPIDAP 233
QEPIDBR 231
QEPIDCS 230
QEPIDMSS 225
field defined 225
QEPIDPF 225
QEPIDRS 232
QEPIDTSM 224
QEPIENC 229
QEPIEPU 227
QEPIESS 230
QEPIFLCS 224
QEPIFLOB 226
QEPIFMRG 226
QEPIFRFI 224
QEPIFSSO 225
QEPIFTSM 224
QEPIFUCR 224
QEPIFUPS 226
QEPIIDE 232
QEPIIID 224
QEPILEU 232
QEPILNS 233
QEPIMIU 232
QEPIPD 232
QEPIQBS 232
QEPIRCA 231
QEPIRID 232
QEPIRMR 229
QEPIRPO 229
QEPISC 224
QEPISCS 233
QEPISIS 231
QEPISQL 231
QEPISU 226
QEPITDPR 225
qepItem 221
QEPITOU 234
QEPITPR 226
QEPITRS 234
QEPITSS 233
QEPIUD 227
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
441
Index
QEPIUDT 230
QEPIUS 233
QEPIXRS 226
qepLevel 221
qepMLen 222
qepMLid 222
qepMsg 222
qepMsgM 222
qepRALen 222
qepRC 222
qepRDLen 222
qepRMLen 223
qepRMRC 223
qepRsv2 222
qepTDP 222
qepTLen 221
R
RecEnd parcel 344
Record mode
data type 306
ECHO statement 306
null 307
Response parcel 287, 304, 306
Record parcel 287, 303, 304, 349, 354
ECHO statement 306
indicator mode. See Indicator mode
Record Parcel, Record mode. See Record mode
RecStart parcel 344
Request buffer 333
Request Buffer Length field 135
request control block 28
Request Length field 136, 169
Request Mode field 137, 138
Request parcels, overview 250
Request Pointer field 138, 169
request, defined 29
requests
aborting 53
ending normally 51
Field mode 344
Indicator mode 349
Record mode 354
submitting 42
Resolver Base Module, sending requests to 315
Response buffer 334
Response Buffer Length field 141
Response Buffer Size field 138
Response Mode field 141
Response parcels
deletion of 274
Error parcel, relation to 272
overview 252
442
purpose 309
Response Processing Option field 139
Response sequence
defined 336
Field mode 338
Indicator mode 340
Record mode 342
response, defined 29
Return Code field 126, 142, 145
return codes 357
Return Time field 127, 128, 144
Rewind parcel 314
rewinding
double buffering 47
single buffering 44
routines 187, 215
DBCHCL 191
DBFABT 204
DBFDSC 212
DBFERQ 210
DBFFET 206
DBFIRQ 201
DBFREW 208
DBFRSUP 198
DBCHCLN 213
DBCHFER 218
DBCHINI 189, 193
DBCHPEC 220
DBCHQE 220
DBCHREL 236
DBCHSAD 237
DBCHUEC 239
DBCHWAT 240
parameters for 188, 217
Run Length field 145
Run Pointer field
purpose 146
Run Length 145
RunStartup parcel 316
S
Segment Data
described 147
processing options 90
SequenceNumber, Multi-TSR field 290
Session control block 28
Session control, CLI 343
session operations
clean up 55
COPs 39
preparations for 37
terminating 54
Single Sign-On 80, 197
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Index
Size parcel 344
SizeEnd parcel 344
SizeStart parcel 344
software release number 216, 236
SP Options parcel 319
spool file, defined 338
SSO 80
startup requests 41
Status, Multi-TSR parcel field 290
stored procedures 369
Success parcel 349, 354
Supported Mechanisms 76
system parameter block
clispb.dat 28, 65
defined 28
internal SPB 28
overriding values 68
processing 65
values used 72
V
Variable Length Fetch field 106, 113, 167, 168
Variable Length Request field 137, 138, 168, 169
version numbers 3
VoteTerm parcel 331
W
Wait Across Crash field 169, 365
Wait Across Delay. See Wait Across Crash
Wait for Response 365
Wait for Response field 170
With parcel 344, 349, 354
T
TD1 79
TD2 79
tdmst 40
TDP Request Number field 131
TDSP Options Parcel 411
Tell About Crash field 149, 365
Tell About Delay. See Tell About Crash
Third-party sign-on 197
THREADONOFF 62
TitleEnd parcel 344
TitleStart parcel 344
Token field 155
Total Length field 156
Transaction Semantics field 157
transactions
aborting 52
defined 31
semantics 31
Two Response Buffers field 159
U
Use Presence Bits field
defined 160
with Using Data Length field 163
with Using Data Pointer 165
User Exits 387
Using Data Length Array field 163
Using Data Length field 161, 162
Using Data Pointer Array field 165
Using Data Pointer field 161, 164
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
443
Index
444
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems