Teradata Call-Level Interface
Version 2
Reference for Channel-Attached Systems
Release 13.10
B035-2417-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: teradata-books@lists.teradata.com
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 © 1996-2010 by Teradata Corporation. All Rights Reserved.
Preface
Purpose
This book provides information about Teradata® Call-Level Interface Version 2 for
Channel-Attached Systems (CLIv2), which is a Teradata Tools and Utilities product. CLIv2 is
a library of routines that enable an application program to access data on a Teradata Database.
An overview of the product and its components is presented and a description of its
operational functions and features.
Audience
This book is intended for use by:
•
System and application programmers responsible for writing programs to access data on
the Teradata Database
•
System administrators
•
Database administrators and relational database developers
Supported Releases
This book supports the following releases:
•
Teradata Database 13.10
•
Teradata Tools and Utilities 13.10
•
Product Version 13.10
To locate detailed supported-release information:
1
Go to http://www.info.teradata.com.
2
Under Online Publications, click General Search.
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 Versions
spreadsheet associated with this release.
The spreadsheet includes supported Teradata Database versions, platforms, and product
release numbers.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
3
Preface
Prerequisites
Prerequisites
The following prerequisite knowledge is required for this product:
•
Basic computer technology, database management systems, and utilities that load and
retrieve data.
•
System programming functions for z/OS or VOS3, depending on the operating system
that you are using to interface to the Teradata Database.
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 Release
Definition associated with this release.
Date and Release
Description
February 2010
Updated Teradata Call-Level Interface Version 2 Reference for ChannelAttached Systems to reflect Teradata products added and updated for
Teradata Tools and Utilities Release 13.10.
13.10
• Added a new Trusted-session-support query that allows applications to
learn of the Trusted Session feature. See “Trusted-session-support” on
page 335.
• Added a new LOB-Name-support query that allows applications to
learn of LOB names. See “LOB-Name-support” on page 335.
• Added a new ElicitName parcel to support LOBs in Teradata Database.
See “ElicitName” on page 432.
• Added StmtInfo UDT Transforms off. See “Transforms-off ” on
page 182.
• Added support for database object names. See “Column-info” on
page 80.
• Added support for StmtInfo PD as STRUCT. See “Period-as-Struct” on
page 131.
• Honored Mandatory Access Controls. See “Parcel Flavors” on page 473
• Added support for Trusted Request. See “Trusted-request” on page 182.
• Added support for FastExportNoSpool. See “Activity Type” on
page 425.
• Added support for Check Workload. See “Utility-workload” on
page 195.
• Discontinued support for z/VM.
• Accommodated latest direction in external release numbering. See
“CLIv2-release” on page 300; “TDP-release” on page 302; and
“Request-message-release” on page 316.
• Removed Teradata Workload Manager and Teradata Manager
references. Products discontinued.
4
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Preface
Changes to This Book
Date and Release
Description
August 2008
13.00
• Added a new Column-correlation-support query to define whether SQL
CREATE, UPDATE, DROP, and HELP CORRELATION statements are
supported. See “Column-correlation-support” on page 333.
• Added a new field (PBTIFTP) to the full-layout section of
“StatementInformation Responses” on page 459 to support Teradata
Database changes.
• Clarified the performance of the Session-character-set query. See
“QEPITEM Field” on page 294.
• Added support for twelve new character sets supported by Teradata
Database. See “Character Set Pointer” on page 78 and “Logon Pointer”
on page 110.
• Added a new StatementInformation field for requests so TDP can
indicate its presence to CLIv2. See “StatementInformation Requests” on
page 490 and “StatementInformationEnd Returns” on page 495.
• Corrected the default value of for DECIMALDIGITS from 15 to 18. See
“Max-decimal-returned” on page 113, “HSHSPB Assembler Source” on
page 234, and “QEPITEM Field” on page 294.
• Added a new Utility-session query that returns the database node-id
associated with an active session (currently used only for internal
processing). See “Utility-session” on page 334.
• Changed the HSHSPB default for the distributed assembler source of
IBCFBRL to match the distributed macro value, even though they are
independent values, to avoid confusion if one of the values is
customized. See Table 7 on page 236.
• In support of temporal tables and queries, added a new field to the
ConfigurationResponse parcel and the StatementInformation
Responses response parcel, and PBTIFTC in the “Full-Layout” section.
• Corrected a reference to MODIFY TABLE to ALTER TABLE. See
“Activity Type” on page 425.
• Added an overview to describe security considerations for CLIv2. See
“Security Considerations” on page 29.
• Clarified character set values. See “CHARSET” on page 408.
• Added a new Database-access-path query that returns the access path
for a particular session. See “Database-access-path” on page 334.
• Added periodic data types. See Table 1 on page 35 and Table 65 on
page 424.
• Corrected pad byte information in the ElicitFile parcel description. See
“ElicitFile” on page 431.
• Clarified the impact of BLOBs and CLOBs. See “DBCHCL CRQ
Function” on page 258.
• Corrected the size of the Length element for the DataInfoX and
PrepInfoX parcels. See “DataInfoX” on page 430 and “PrepInfoX” on
page 446.
• Clarified the impact of user-defined functions (UDFs), which use the
ElictData, ElicitFile, and ElicitName parcels. See “Communicating with
the Teradata Database” on page 33 and “Continuing a Teradata SQL
Request” on page 61.
Teradata Call-Level Interface Version 2 Reference for Channel-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 following table. 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 to ensure 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.
Late information
6
2 Under Online Publications, click General Search.
4 Click Search.
5 Select the appropriate Release Definition from
the search results.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Preface
Additional Information
Type of Information
Description
Access to Information
Additional product
information
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.
2 Under the Online Publications subcategory,
Browse by Category, click Data Warehousing.
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.
Other books related to Teradata Call-Level
Interface Version 2 for Channel-Attached Systems
are:
• Teradata Director Program Reference
B035-2416-mmyx
• IBM IMS/DC Interface for Teradata Reference
B035-2447-mmyx
• IBM CICS Interface for Teradata Reference
B035-2448-mmyx
• Teradata Tools and Utilities Installation Guide
for IBM z/OS
B035-2458-mmyx
• Messages
B035-1096-mmyx
• Teradata Tools and Utilities Command Summary
B035-2401-mmyx
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.
2 Under the Online Publications subcategory,
Browse by Category, click Data Warehousing.
3 Click CD-ROM List and Images.
4 Follow the ordering instructions.
Ordering
information for
manuals
Use the Teradata Information Products
web site to order printed versions of
manuals.
1 Go to http://www.info.teradata.com.
2 Under Print & CD Publications, click How to
Order.
3 Follow the ordering instructions.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
7
Preface
Additional Information
Type of Information
Description
Access to Information
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
8
Teradata Call-Level Interface Version 2 Reference for Channel-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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Logical Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Communicating with the Teradata Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Executing Programs in Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
34
38
38
Parallel Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-Statement Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-Request Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi-Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
40
40
41
Multi-application Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Coordination with Other Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Common Routines Supporting CLIv2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chapter 2:
Session Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Preparing to Use CLIv2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Setting DBCAREA Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
9
Table of Contents
Compatibility Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Character Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Return Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Messages for Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Explicitly Establishing a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Password Expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Executing a RunStartUp Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Submitting a Teradata SQL Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Fetching the Response for a Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Continuing a Teradata SQL Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Rewinding to the Beginning of a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Ending a Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Aborting a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Terminating a Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Single Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Multiple Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Implicitly Establishing a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Chapter 3:
DBCAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Anticipated Number of Concurrent Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
APH-response-OK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Change Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Character Set Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Column-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Connect Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Continued-characters-state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Continued-data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Country Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Current Request Buffer Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Current Response Buffer Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
C2S Conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Data-encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Date Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Delegate-user-identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
10
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Table of Contents
Extension Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Eyecatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Fetch Data Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Fetch Maximum Data Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Fetch Parcel Flavor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Fetch Returned Data Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Input CLIv2 Connection Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Input CLIv2 Request Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Input TDP Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Keep Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Language Conformance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Language Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Locate Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Logon Length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Logon Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Max-decimal-returned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Maximum Parcel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Mechanism-data-encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Mechanism-data-len. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Mechanism-data-ptr. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Mechanism-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Message Area Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Message Area Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Message Charset Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Message Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Message Return Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Message Text Length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Message Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Open Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Output CLIv2 Connection Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Output CLIv2 Request Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Output Host Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Output TDP Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Output TDP Session Id. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Parcel Mode Fetch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Period-as-Struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
11
Table of Contents
Positioning-action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Positioning-statement-number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Positioning-value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Protocol-Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Refresh-cached-data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
Request Buffer Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Request Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
Request Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Request-parcel-format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Request Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Request Processing Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Request-token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Response Buffer Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Response Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Result-sets-OK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Return Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Return-identity-data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Return-objects-as . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Return-statement-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Return-result-to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Return Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Route Description Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Run Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Run Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Save Response Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Segment Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Session-desc-length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Session-desc-pointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
Session Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
Set Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Statement-status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
S2C Conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
TDP-receipt-timestamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
TDP Request Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
Tell if Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Time1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
Time2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
Time3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
12
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Table of Contents
Time4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Time5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Time1-status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Time2-status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Time3-status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Time4-status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Time5-status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Timing-precision. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Total Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Transaction Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Transforms-off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Trusted-request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Two Response Buffers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Use-default-conn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Use Presence Bits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Using-data-count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Using Data Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Using Data Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Using-data-length-vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Using-data-pointer-vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Utility-workload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Variable Length Fetch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Variable Length Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Wait During Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Wait-exclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Wait For Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Workload-length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Workload-pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
2PC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Chapter 4:
DBCAREA Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
DBCAIRX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
DBCAIRX Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
DBCACNX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
13
Table of Contents
Chapter 5:
Release Tapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Finding Files on the Release Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
DBCAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
DBCAIRX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
DBCACNX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
DBCHMEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
DBCHQEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
DBCHQER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
DBCHUEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
HSHSPB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
TRDSPB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
TC2XPH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
TRD0LENU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
System Parameter Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
Overriding the Defaults from an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
HSHSPB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Where to Find HSHSPB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Changing Options Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
HSHSPB Assembler Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
Chapter 6:
Common Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
Uses of CLIv2 Parameters: Tabular Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240
Summary of CLIv2 Routine Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
DBCHINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
DBCHCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
DBCHCL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
DBCHCL CON Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
DBCHCL RSUP Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
DBCHCL IRQ Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
DBCHCL IWPF Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
DBCHCL CRQ Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
DBCHCL CMD Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
14
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Table of Contents
DBCHCL ABT Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHCL FET Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHCL ERQ Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHCL REW Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHCL DSC Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHCLN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
263
265
267
269
270
271
Chapter 7:
Other CLIv2 Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Uses of CLIv2 Routines: Tabular Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Parameters of CLIv2 Routines: Tabular Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHMEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHPEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHSAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHUEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHWAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBCHWL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
274
276
278
279
280
281
283
284
286
Chapter 8:
CLIv2 Query Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
DBCHQE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Available-logon-mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CLIv2-limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SQL-limits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Integer/decimal-enlargement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Result-sets-support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QueryBand-support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Merge-into-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging-errors-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Procedure-data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Utility-session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transforms-off-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transforms-request-support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
289
290
319
321
322
328
329
330
331
331
332
334
336
336
15
Table of Contents
Chapter 9:
Response Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339
Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339
Request Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339
Response Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .340
Move Area. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
Typical Teradata SQL Response Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Typical Teradata Response Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Submitting Requests In Field Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Submitting Requests In Record Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345
Submiting Requests—MultipartIndicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .346
Submitting Requests In Indicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
Parcel Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349
Issuing Requests—Field Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
Issuing Requests—Record Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Issuing Requests—MultipartIndicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .358
Issuing Requests—Indicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
Parcels in Normal Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364
Parcels That Indicate Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364
Field Layouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364
Error Parcels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365
Failure Parcels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365
Chapter 10:
Error and Failure Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367
Error and Failure Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367
Chapter 11:
Crash and Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
TDP or Client System Crashes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
Unusable CP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
AP Reset Containment (APRC). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
Teradata Database Crash and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
What the Application Does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
Tell and Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
Just Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372
16
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Table of Contents
Tell and Logoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Chapter 12:
Character Set Codepoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Description of Codepage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
EBCDIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
EBCDIC037_0E. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
EBCDIC273_0E. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
EBCDIC277_0E. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
HANGULEBCDIC933_1II. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
KANJIEBCDIC5026_0I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
KANJIEBCDIC5035_0I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
KATAKANAEBCDIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
SCHEBCDIC935_2IJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
TCHEBCDIC937_3IB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Chapter 13:
User-Defined Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHARSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
END. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UNICODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
407
408
411
411
Chapter 14:
Message Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Comment Formatting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
17
Table of Contents
Chapter 15:
Parcels for Basic Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419
Parcel Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419
Parcel Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
Request Parcels: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .421
Response Parcels: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .421
Common Parcel Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .424
Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .424
Activity Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .425
Parcel Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428
DataInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .429
DataInfoX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .430
ElicitData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .431
ElicitDataReceived . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .431
ElicitFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .431
ElicitName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .432
EndMultipartRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433
EndRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433
EndStatement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .434
EndWith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .434
Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435
Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435
Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436
Flagger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .437
FormatEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .438
FormatStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .438
MultipartRecord. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .439
NullField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .441
OK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .441
PosEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .442
Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .443
PosStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .443
PrepInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .444
PrepInfoX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .446
RecEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450
Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450
Record (In Indicator Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .451
Record (In Record Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453
RecStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .454
ResultSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .455
ResultSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
18
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Table of Contents
Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SizeEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SizeStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
StatementInformation Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
StatementInformationEnd Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Success. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TitleEnd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TitleStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
With. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
458
458
458
459
466
467
468
468
469
Chapter 16:
Parcels for Advanced Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Parcel Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Parcel Flavors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
Parcel Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
Request Parcels: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Response Parcels: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Parcel Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CursorDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CursorHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DataInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DataInfoX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EndMultipartData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EndMultipartIndicData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FMReq. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IndicData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IndicReq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MultipartData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MultipartIndicData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MultipartRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Req. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SP Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
StatementInformation Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
StatementInformationEnd Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
475
475
476
477
477
478
480
480
480
481
482
483
484
484
485
489
489
490
495
19
Table of Contents
Chapter 17:
Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .497
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .497
SQL Stored Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .497
Using the Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500
External Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500
Using the Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .500
Dynamic Result Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .501
Chapter 18:
Resolver Base Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .503
Using the Resolver Base Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .503
Request Parcel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .504
Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .505
Chapter 19:
2PC Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .507
Sync Point Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .507
Enabling 2PC Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .508
Starting 2PC Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .508
Using Coordinators to Synchronize Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509
The 2PC Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509
In-Doubt Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .510
CLIv2 Application Requirements for 2PC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .511
Appendix A:
How to Read Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .513
Syntax Diagram Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .513
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .515
Multiple Legitimate Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .517
Sample Syntax Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .518
Diagram Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .518
20
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Table of Contents
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
21
Table of Contents
22
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
List of Figures
Figure 1: CLIv2: Logical Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Figure 2: CLIv2: Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Figure 3: DBCAIRX Header Fields (Eyecatcher is ‘IRX8‘) . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Figure 4: Deprecated DBCAIRX Header Fields (Eyecatcher = ‘IRX‘) . . . . . . . . . . . . . . . . . . 210
Figure 5: Deprecated DBCAIRX Header Fields (Eyecatcher = ‘DBCX‘) . . . . . . . . . . . . . . . . 210
Figure 6: DBCAIRX Element When Eyecatcher is 'IRX8‘ and Level 1. . . . . . . . . . . . . . . . . . 211
Figure 7: Deprecated DBCAIRX Element Containing Actual Data . . . . . . . . . . . . . . . . . . . . 211
Figure 8: DBCAIRX Element When Eyecatcher is 'IRX8‘ and Level 0. . . . . . . . . . . . . . . . . . 212
Figure 9: Deprecated DBCAIRX Element When Eyecatcher is 'IRX' or 'DBCX' . . . . . . . . . 212
Figure 10: DBCACNX Header Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Figure 11: DBCACNX Element Fields When Level = 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
23
List of Figures
24
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
List of Tables
Table 1: Teradata SQL Data Type and Mainframe Internal Format . . . . . . . . . . . . . . . . . . . . 35
Table 2: Order of the DBCAREA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Table 3: Order of the Enlarged DBCAREA When Level > 0. . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Table 4: Change Options Scanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Table 5: Length of Returned Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Table 6: HSHSPB Source Default Settings That Are Safe to Change . . . . . . . . . . . . . . . . . . . 234
Table 7: HSHSPB Source Default Settings That Should Probably Not Be Changed . . . . . . 236
Table 8: HSHSPB Source Default Settings That Should Never Be Changed . . . . . . . . . . . . . 237
Table 9: Uses of Routine and Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Table 10: Parameters of CLIv2 Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Table 11: DBCAREA Input Fields Required for the Connect Function . . . . . . . . . . . . . . . . 247
Table 12: DBCAREA Input Fields Optional for the Connect Function. . . . . . . . . . . . . . . . . 248
Table 13: DBCAREA Output Fields Always Set for the Connect Functions . . . . . . . . . . . . . 249
Table 14: DBCAREA Output Fields Set by Successful Connect Functions . . . . . . . . . . . . . . 249
Table 15: DBCAREA Input Fields Required for the RunStartup Function . . . . . . . . . . . . . . 250
Table 16: DBCAREA Output Fields Optional for the RunStartup Function . . . . . . . . . . . . 250
Table 17: DBCAREA Output Fields Always Set by the RunStartup Function . . . . . . . . . . . 251
Table 18: DBCAREA Output Fields Set by Successful RunStartup Functions . . . . . . . . . . . 251
Table 19: DBCAREA Input Fields Required for the Initiate Request Function . . . . . . . . . . 252
Table 20: DBCAREA Input Fields Optional for the Initiate Request Function . . . . . . . . . . 252
Table 21: DBCAREA Input Fields Required for Initiate With Protocol-function . . . . . . . . 255
Table 22: DBCAREA Input Fields Optional for Initiate With Protocol-function . . . . . . . . 256
Table 23: DBCAREA Output Fields always set by Initiate With Protocol-function. . . . . . . 257
Table 24: DBCAREA Output Fields Set by Successful Initiate With Protocol-function . . . 257
Table 25: DBCAREA Input Fields Required for the Continue Request Function . . . . . . . . 258
Table 26: DBCAREA Input Fields Optional for the Continue Request Function. . . . . . . . . 259
Table 27: DBCAREA Output Fields always set by the Continue Request Function . . . . . . . 259
Table 28: DBCAREA Output Fields set by Successful Continue Request Functions . . . . . . 259
Table 29: DBCAREA Input Fields Required for the Command Function . . . . . . . . . . . . . . 260
Table 30: DBCAREA Input Fields Optional for the Command Function. . . . . . . . . . . . . . . 261
Table 31: DBCAREA Output Fields always set by the Command Function . . . . . . . . . . . . . 261
Table 32: DBCAREA Output Fields set by Successful Command Functions . . . . . . . . . . . . 261
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
25
List of Tables
Table 33: DBCAREA Output Fields always set by the Fetch Function . . . . . . . . . . . . . . . . . .266
Table 34: DBCAREA Output Fields set by Successful Fetch Functions . . . . . . . . . . . . . . . . . .266
Table 35: DBCAREA Input Fields Required for the EndRequest Function . . . . . . . . . . . . . .267
Table 36: DBCAREA Input Fields Optional for the EndRequest Functions . . . . . . . . . . . . . .267
Table 37: DBCAREA Output Fields Always Set for the EndRequest Function . . . . . . . . . . . .267
Table 38: DBCAREA Output Fields Set by Successful EndRequest Functions . . . . . . . . . . . .268
Table 39: Uses of CLIv2 Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Table 40: Parameters of CLIv2 Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Table 41: QEPITEM Field Valid Item Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
Table 42: Response Parcel Sequence in Field Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Table 43: Response parcel sequence in Record Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345
Table 44: Response Sequence in MultipartIndicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . .346
Table 45: Response Parcel Sequence Indicator Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
Table 46: Error and Failure Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367
Table 47: Teradata EBCDIC Codepage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
Table 48: Teradata EBCDIC037_0E Codepage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
Table 49: Teradata EBCDIC273_0E Codepage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .378
Table 50: Teradata EBCDIC277_0E Codepage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .379
Table 51: Single-byte Teradata HANGULEBCDIC933_1II Codepage . . . . . . . . . . . . . . . . . .380
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II. . . . . . . . . . . . . . .381
Table 53: Single-byte Teradata KANJIEBCDIC5026_0I Codepage . . . . . . . . . . . . . . . . . . . . .386
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I . . . . . . . . . . . . . . . . . . .386
Table 55: Single-byte Teradata KANJIEBCDIC5035_0I Codepage . . . . . . . . . . . . . . . . . . . . .392
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I . . . . . . . . . . . . . . . . . . .393
Table 57: Single-byte Teradata KATAKANAEBCDIC Codepage. . . . . . . . . . . . . . . . . . . . . . .398
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC . . . . . . . . . . . . . . . . .399
Table 59: Single-byte Teradata SCHEBCDIC935_2IJ Codepage . . . . . . . . . . . . . . . . . . . . . . .404
Table 60: Single-byte Teradata TCHEBCDIC937_3IB Codepage . . . . . . . . . . . . . . . . . . . . . .406
Table 61: Language Module Suffixes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414
Table 62: Language and Country Keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .416
Table 63: Parcel flavors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419
Table 64: Response Parcel Flavors, Names, And Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .421
Table 65: Data Type Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .424
Table 66: Activity Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .425
Table 67: PrepInfoX Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .448
Table 68: ResultSummary Parcel Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
26
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
List of Tables
Table 69: Full-layout Fields for Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Table 70: PBTIFDT Additional Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Table 71: Limited-layout Fields for Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Table 72: Statistic-layout fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Table 73: Original Parcel Header (TPH0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Table 74: Alternate Parcel Header (TPH1). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Table 75: Parcel Flavors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
Table 76: Request Parcel Flavors, Names, And Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Table 77: Response Parcel Flavors, Names, And Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Table 78: Full-layout Fields for Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Table 79: Limited-layout Fields for Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Table 80: Untransformed limited-layout Fields for Requests . . . . . . . . . . . . . . . . . . . . . . . . . 494
Table 81: Untransformed imited-layout Fields for Requests . . . . . . . . . . . . . . . . . . . . . . . . . 494
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
27
List of Tables
28
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 1
Introduction
This chapter discusses the following general aspects of Call-Level Interface Version2 (CLIv2):
•
Overview
•
Logical Structure
•
Data Structures
•
Communicating with the Teradata Database
•
Parallel Processing
•
Multi-application Management
•
Coordination with Other Events
•
Common Routines Supporting CLIv2
Overview
CLIv2 is a collection of callable service routines that provide the interface between
applications and the Teradata Director Program (TDP) on an IBM mainframe client. TDP is
the interface between CLIv2 and Teradata Database.
CLIv2 can operate with all versions of z/OS, VOS3, MSP, CICS, and IMS. CLIv2 sends
requests to Teradata Database, and provides the application with a response returned from
the server.
CLIv2 provides support for the following:
•
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 Teradata Database at the same time
•
Communicating with two-phase commit coordinators for CICS and IMS transactions
•
Generally insulating the application from details in communicating with Teradata
Database
Security Considerations
Because CLIv2 callable routines are simply subroutines of an application, they operate in the
same execution environment as the application.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
29
Chapter 1: Introduction
Logical Structure
•
No special operating system authorization is required (for example, Authorized Program
Facility [APF] for z/OS). CLIv2 functions no differently if an application is authorized.
•
No datasets or files are accessed, so system access rights for the current system userid are
not implicitly extended by CLIv2 to other objects. CLIv2 accesses only its own load
modules from the normal system module search order.
•
No devices or communication facilities, such as TCP/IP, are accessed. CLIv2
communicates only with TDP. The CLIv2 internal trace is not recorded by the operating
system unless permitted by CLIv2 customization in HSHSPB.
•
Neither application SQL data nor Teradata Database logon passwords are retained beyond
their need, nor are they passed anyplace, except to TDP. Such data is not included in any
internal trace. The exception is storage capture initiated outside CLIv2, such as a z/OS
ABEND dump.
•
Only minimal standard operating system services or their equivalent in specialized
environments, such as CICS, are used.
Preprocessors
Many applications can use one of the Teradata SQL preprocessors and thus be shielded from
the details of the CLIv2 interface. Applications coded in languages for which Teradata does
not provide a preprocessor, or applications requiring features not provided by the
preprocessor, call CLIv2 directly.
TDP
TDP is a Teradata product that serves as an interface between CLIv2 and Teradata Database. It
executes on the same mainframe as a different job or virtual machine than the application and
CLIv2. An individual TDP is associated with one logical Teradata Database; however, any
number of TDPs can simultaneously operate and be accessed by CLIv2 on the same
mainframe. Each TDP is referred to by the application with an identifier called the TDPid
(TDP2, for example) that is unique in a mainframe.
Teradata Database implements the actual relational database that processes requests received
from CLIv2 by way of TDP.
Logical Structure
Applications that manipulate data on Teradata Database communicate with it indirectly by
means of CLIv2. The application calls CLIv2, which acts as a subroutine of the application,
sharing the same environment. CLIv2 executes as part of the same job, terminal session,
virtual machine, or transaction.
Figure 1 illustrates the logical structure of the client-server interface.
30
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: Introduction
Logical Structure
Figure 1: CLIv2: Logical Structure
Application
Program
CLIv2
Stub
Requests
Responses
CLIv2
Runtime
TDP
Teradata
Database
2414A025
CLIv2 Stub
The CLIv2 stub is a routine that is generally included with the application. It defines all the
CLIv2 routines described in this book for use by the application. The stub locates the data
structure called the CLIv2 System Parameter Block (HSHSPB). Then it locates and invokes
the CLIv2 runtime routines.
24-Bit and 31-Bit Addressing
CLIv2 fully supports applications using both 24-bit and 31-bit addressing. CLIv2 can reside in
either type of storage and can be passed control in either mode. If called in 24-bit addressing
mode, CLIv2 allocates 31-bit storage for internal use; therefore, limited VirtualStorage
Constraint Relief occurs for 24-bit applications.
If the application calls CLIv2 in 31-bit addressing mode to initiate various requests, the
request and response buffers will be allocated in 31-bit storage. This mode requires that
subsequent CLIv2 calls to obtain these responses also be in 31-bit addressing mode so that the
previously allocated buffers are accessible.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
31
Chapter 1: Introduction
Data Structures
Runtime
The runtime includes all CLIv2 programs called when an application runs. It resides in a
module called DBCHMODS. While it can be included with an application, it is generally
located by the stub during execution. Not only does this eliminate the need to alter the
application when maintenance is applied to the HSHSPB, but it also reduces the size of the
application.
Data Structures
Figure 2 shows the data structures used in the communication between the application
program and CLIv2:
•
DBCAREA and extensions
•
CLIv2 system parameter block (HSHSPB)
•
Message definitions
Figure 2: CLIv2: Data Structures
Application
CLIv2
Stub
DBCAREA
Extensions
HSHSPB
DBCAREA
User-Defined
Character
Sets
Message
Definitions
CLIv2
Runtime
2417A008
DBCAREA
The DBCAREA is the communication structure between an application and CLIv2.
Applications use it to forward control and data information. CLIv2 uses it to return control
and data information. An application may use a single DBCAREA or multiple DBCAREAs.
CLIv2 retains no knowledge of a particular DBCAREA across multiple CLIv2 calls. CLIv2 is
concerned only with the values for DBCAREA that are meaningful to the routine called.
32
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: Introduction
Communicating with the Teradata Database
DBCAREA Extensions
A DBCAREA extension is addressed by a DBCAREA, and allows specialized applications to
provide additional information to CLIv2. The extensions may be chained together, thus
allowing more than one extension for a single request.
HSHSPB
HSHSPB (CLIv2 system parameter block) is a data structure that is examined during
initialization. HSHSPB is the source of the default DBCAREA values if these values are not set
in the DBCAREA by an application.
User Defined Character Sets
User-defined character sets are character sets not supplied by a server but rather defined by a
customer. In addition to be defined to a server, they must also be described to CLIv2. For
more information, see Chapter 13: “User-Defined Character Sets.”
Message Definitions
A message definition defines the text of all CLI messages in a particular language. The message
definition for the specified language is used when a message is returned in the DBCAREA. For
more information, see “Chapter 14 Message Definitions.”.
Communicating with the Teradata Database
Information flow between an application and Teradata Database functions is as follows:
•
An 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, then returns response information to the
application.
Sessions
A session is an authenticated, logical connection between the application and a Teradata
Database. Sessions are explicitly connected and disconnected, and while connected provide
the vehicle for all communication between an application and Teradata Database.
Teradata Partitions
Teradata Database supports several different types of request processors, or partitions. A
partition is specified when a session is established by the CLIv2 Run String addressed in the
DBCAREA. CLIv2 operates identically for all partitions. Although the structures of requests
and responses are the same for all partitions, the contents vary by partition. The following
partitions are supported by the server for general use:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
33
Chapter 1: Introduction
Communicating with the Teradata Database
•
DBC/SQL - The partition that processes SQL requests. The remaining chapters of this
manual assume the use of this partition.
•
Monitor - The partition that processes performance monitor requests, available only for
systems running at least Teradata Database for UNIX, Version 2 Release 2, or Teradata
DBS for TOS, Version 1 Release 5. Use of this partition is described in Performance
Management, Workload Management API: PM/API and Open API, and Teradata Manager
User Guide.
•
RBM (Resolver Base Module) - The partition that processes two-phase commit (2PC) indoubt resolution requests, available only for systems running Teradata Database for
UNIX, Version 2 Release 2, or Teradata DBS for TOS, Version 1 Release 5. See Chapter 18:
“Resolver Base Module.”
Requests and Responses
Requests are sent by an application to Teradata Database to initiate an action. Responses are
sent by 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 Teradata Database at the same time are called a Teradata
SQL request. Having several statements in the same request saves message transfer time, a
factor of interest to CPU-bound and I/O-bound programs or sites, since, for example, a twostatement multi-statement request uses half the 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 insert a large database field, such as a picture or a program
that runs within the database, first prompt CLIv2 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 CLIv2 allows
applications to manipulate request parcels directly, most applications let CLIv2 handle them.
However, applications must process responses parcel by parcel. Each type of parcel is uniquely
identified by its flavor. For more information, see Chapter 15: “Parcels for Basic
Applications.”
When the request consists of multiple statements, a successful response contains the results
for all statements. The parcels for each statement begin with either a Success, OK, or
ResultSummary parcel (depending on the Response-mode or Statement-status.) and end with
an EndStatement parcel. For unsuccessful statements, the Error or Failure parcel contains the
statement number.
Three response parcels (ElicitData, ElicitFile, and ElicitName) prompt CLIv2 to provide
additional information needed to complete requests. The application continues the request by
providing the additional information.
Character Sets
A character set specifies which characters are available (for example, whether the Japanese
characters are available) and how those characters are represented (for example, as EBCDIC
34
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: Introduction
Communicating with the Teradata Database
or ASCII). Character data in logon strings, request data, response data, and error messages are
affected by which character set is being used.
For more information about character sets, see “Character Sets” on page 50.
Response-mode
The types of parcels returned in a response that selects database fields are determined when
the request is made. Four such response modes exist:
•
Field mode, which returns database fields formatted as character data. (Large Objects
[LOBs] return errors.)
•
Record Mode, which returns non-null fields as unformatted data. (LOBs return errors.)
•
Indicator Mode, which returns all fields as unformatted data. (LOBs return errors.)
•
MultipartIndicator mode, which returns all fields, including LOBs, as unformatted data
with additional character set detail.
When unformatted data is returned for Record, MultipartIndicator, and Indicator modes, it is
presented in a data structure that is meaningful to the application. Table 1 describes the data
structure for applications on channel-attached systems.
Table 1: Teradata SQL Data Type and Mainframe Internal Format
Teradata SQL Data
Type
Mainframe Internal Format
BYTEINT
8-bit signed integer (1 byte)
SMALLINT
16-bit signed integer (2 bytes)
INTEGER
32-bit signed integer (4 bytes)
FLOAT
64-bit floating point number 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)
REAL
DOUBLE
PRECISION
DECIMAL (x, y)
NUMERIC
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 Channel-Attached Systems
35
Chapter 1: Introduction
Communicating with the Teradata Database
Table 1: Teradata SQL Data Type and Mainframe Internal Format (continued)
Teradata SQL Data
Type
VARCHAR (n)
(actual length k,
where 0 <= k <= n )
Mainframe 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)
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)
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 integer (4 bytes); DATE is calculated as follows:
(year-1900)*10000 + month*100 + day
PERIOD (DATE)
Two 4-byte signed integers, each calculated as:
( year – 1900 ) × 10000 + ( month × 100 ) + day
The first integer is the period's beginning date; the second integer is the
period's ending date.
PERIOD (TIME)
Two 6-byte areas, each consisting of the following:
• A 4-byte signed integer for the number of seconds (scaled with the
rightmost six decimal digits that contain fractional seconds)
• A 1-byte unsigned integer for the hours
• A 1-byte unsigned integer for the minutes
The first area is the beginning time for the period; the second area is the
ending time.
36
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: Introduction
Communicating with the Teradata Database
Table 1: Teradata SQL Data Type and Mainframe Internal Format (continued)
Teradata SQL Data
Type
Mainframe Internal Format
PERIOD (TIME
WITH TIMEZONE)
Two 8-byte areas, each consisting of the following:
PERIOD
(TIMESTAMP WITH
TIMEZONE)
Two 12-byte areas, each consisting of the following:
• A 4-byte signed integer for the number of seconds (scaled with the
rightmost six decimal digits that contain fractional seconds).
• A 1-byte unsigned integer for the hours.
• A 1-byte unsigned integer for the minutes.
• A 1-byte unsigned integer for the hourly displacement of the timezone
normalized to 16. (Values less than 16 represent a negative
displacement, a value of 16 is zero displacement, and values greater
than 16 represent a positive displacement.)
• A 1-byte unsigned integer for the timezone's minutes of displacement.
The first area is the beginning time for the period; the second area is the
ending time.
• A 4-byte signed integer for the number of seconds (scaled with the
rightmost six decimal digits containing fractional seconds).
• A 2-byte signed integer for the year.
• A 1-byte unsigned integer for the month.
• A 1-byte unsigned integer containing the day.
• A 1-byte unsigned integer containing the hour.
• A 1-byte unsigned integer containing the minute.
• A 1-byte unsigned integer containing the timezone's hourly
displacement normalized to 16. (Values less than 16 represent a
negative displacement, a value of 16 is zero displacement, and values
greater than 16 represent a positive displacement.)
• A 1-byte unsigned integer containing the timezone's minutes of
displacement.
The first area is the beginning timestamp for the period; the second area is
the ending timestamp.
Response Repositioning
Within Teradata Database, a response to a request is kept within a spool file. To satisfy Fetch
requests by an application, CLIv2 interacts with the server to obtain all or part of the spooled
response. How long the response is spooled and how it is processed is controlled by the
application, as follows.
Specified Option
Result
Keep-response=N
The response is discarded once the last parcel is fetched, and parcels may
only be fetched once, in sequential order.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
37
Chapter 1: Introduction
Communicating with the Teradata Database
Specified Option
Result
Keep-response=Y
The response is kept until the EndRequest function is called, and parcels
may be fetched in sequential order, the Rewind function called, and
fetched again, the process repeated any number of times.
Keep-response=Y
and an SQL Select
statement includes the
FOR CURSOR phrase
The response is kept until the EndRequest function is called, and parcels
may be fetched in random order by row, sequentially within that row
using the CursorDBC and CursorHost parcels.
Keep-response=P
The response is kept until the EndRequest function is called, and parcels
may be fetched in random order by row, sequentially within that row
using the Positioning-action, Positioning-statement-number, and
Positioning-value DBCAREA settings.
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, CLIv2 supports large object (LOB) fields. If LOBs exceed
the maximum statement size, they are deferred using the AS DEFERRED phrase in the
USING row descriptor for the request string instead of being entirely included in the initial
request, such as (USING BLOB AS DEFERRED) or (USING BLOB AS DEFERRED BY
NAME). In this case, Teradata Database includes an ElicitData or ElicitName parcel in the
response to prompt CLIv2 to add the LOB.
Executing Programs in Teradata Database
It is possible to use SQL statements to execute user-defined programs in Teradata Database.
To do this, first define the programs using the SQL statements CREATE FUNCTION,
CREATE METHOD, or CREATE PROCEDURE. These SQL statements create an ElicitFile
parcel in the response that prompts CLIv2 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. They are
similar to the read statements used to read records from a file.
Occasionally an application requires that a set of Teradata SQL statements must all 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.
38
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: Introduction
Communicating with the Teradata Database
Action
Result
If the first statement is completed
The money would vanish
If the second statement is completed
The money would be counted twice
Statements and Transactions
An application can enforce the all-or-nothing property, but it is much simpler for Teradata
Database to enforce it. The server will enforce the all-or-nothing property if the server has the
information that the statements constitute a transaction. Then, if one of the statements fails,
the server 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
When working with Teradata Database for UNIX release 2 (or later), two modes of
transactions are available:
•
Teradata
•
ANSI
If Teradata transaction semantics are used, three types of transactions differ in the way an
application identifies which statements share the all-or-none property. All three methods
back out all statements if any statement fails:
•
Explicit (user-generated)- Precedes the statements by a BEGIN TRANSACTION
statement and follows them with an END TRANSACTION statement.
•
Implicit - Submits the statements as a single request.
•
2PC (two-phase commit) - The action depends on CICS or IMS sync point services to
commit or roll back transactions. The use of the sync point services guarantees that all
updates performed within a logical unit of work will either all commit or all roll back. 2PC
requires Teradata Database for UNIX version 2 release 2 (or later), or Teradata DBS for
TOS version 1 release 5 (or later).
ANSI Transaction Semantics
ANSI transaction semantics are supported for Teradata Database for UNIX version 2 release 2
(or later). If ANSI transaction semantics are used, 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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
39
Chapter 1: Introduction
Parallel Processing
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 Processing
Teradata Database can simultaneously process multiple requests from one or more
applications, automatically managing the processors to optimize an application-initiated
Teradata SQL request. No special programming is necessary to take advantage of the parallel
processing capabilities of Teradata Database.
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 techniques that enable an application to overlap the processing of Teradata SQL
requests:
•
Multi-statement management
•
Multi-request management
•
Multi-session management
Multi-Statement Management
Two or more Teradata SQL statements, separated by semicolons, can be combined into a
single request. Teradata Database attempts to execute these statements in parallel. A single
response is returned, consisting of the results for each statement, which the application
processes until all are exhausted.
If a statement fails, an Error or Failure parcel is present. If a statement succeeds, the first
parcel is a Success, OK, or ResultSummary parcel; various parcels follow, ending with an
EndStatement parcel. The last parcel is an EndRequest parcel.
The first parcel always contains the statement number, which normally corresponds to the
ordinal position of the statement in the request; however, if a statement is an SQL CALL, and
the DBCAREA Result-sets-OK options allows the called procedure to return response parcels,
each such returned response will also increment the statement number, the ActivityType will
be 176. The presence of the ResultSet parcel indicates such additional statement numbers.
Multi-Request Management
Two or more responses can be processed simultaneously for a session. Once a request is
initiated, no other request can be initiated for that session until the previous one completes.
Once a request completes, the entire response need not be processed before initiating another
request. In this way, the application may process multiple responses in parallel.
The response being processed is identified by its request number, which is returned to the
application when a request is initiated. CLIv2 maintains the last parcel processed for each
response, so as appropriate, the application processes the next parcel until all are exhausted.
Up to sixteen responses can be processed simultaneously.
40
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: Introduction
Parallel Processing
Note that this facility is primarily a functional, not a performance, enhancement. It supports
techniques functionally similar to multi-session techniques, but on a single session.
Identifying a Request
An application identifies a request by its session number and request number. A request can
also be identified by an assigned token that is used with DBCHWAT and a request number.
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, initiate
other requests, or both, as desired. The request number is the input argument for subsequent
Fetch, Rewind, and EndRequest operations against the request.
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.
No more than one Teradata SQL request can be active at one time per session.
Multi-Session Management
Two or more sessions can be connected simultaneously to the same (or different) servers.
Each session can process two or more requests simultaneously as previously discussed for
multi-request management.
Prior to considering a multi-session approach, an 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. In addition, depending on the application, multi-session techniques can result
in deadlocks and open timing windows that can leave the database in an inconsistent state.
Nevertheless, CLIv2 provides facilities to assist implementation of multi-session applications.
Because each session can have an active request, an application can either:
•
wait for completion of a particular request on a particular session, just as it would if only
one session existed,
•
wait for the completion of any of the active requests, or
•
wait for any combination of the previous two.
Waiting for completion of a particular request is the simplest from a programming
standpoint, but it may result in more time spent waiting than is necessary because other
requests might complete before the one being waited upon, and the application could be
processing those responses.
Waiting for the completion of any request is more complex programming, but results in the
minimum amount of time waiting because the application is never waiting when a response is
available for processing.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
41
Chapter 1: Introduction
Parallel Processing
How It Works
Each concurrent request can be identified to CLIv2 by using both 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 these functions:
•
Connect
•
Initiate Request
•
RunStartUp
•
Initiate with Protocol-Function
•
Command
Using Tokens
An application can also supply a token for each request when it is initiated. That token is
returned by the DBCHWAT routine when a request response arrives. An application can have
requests pending on several sessions simultaneously.
One way for an application to wait is to call DBCHWAT. The wait ends when any request
completes. The advantage of this first method is that it maximizes throughput by reducing
session idle time. The application can handle the response and dispatch another request as
soon as the previous request completes.
Using Fetch
An alternate way for an application to wait is to call DBCHCL for the Fetch function, using
the session id of an active session. The wait ends when the specified request completes. The
problem with this method is that the application cannot know which of the active requests
will complete first. 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.
42
Language
Location of Sample on the Release Tape
IBM Assembler
EX2
COBOL
CLI2MCB
PL/I
CLI2MPB
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: Introduction
Multi-application Management
Multi-application Management
In general, all use of CLIv2 facilities by an operating system dispatchable unit, such as an z/OS
task, is related. That is, any CLIv2 resource, such as sessions or requests, can be used from any
caller in that dispatchable unit.
Conversely, all callers of CLIv2 within a dispatchable unit must coordinate with each other.
However, there are instances in which such knowledge is not possible, such as use of CLIv2 in
an exit provided by an application that itself uses CLIv2. To prevent a session established by
the exit from interfering with the application (for example, by the application calling
DBCHWAT and being returned completion of a request issued by the exit), crude support is
provided. The exit may specify the Wait-exclusion DBCAREA option when it Connects a
session. Such sessions will be excluded from any DBCHWAT processing by the application.
If needed, the exit would then use DBCHWL to wait for only its session (Wait-exclusion has
no impact on DBCHWL processing). Since there is no explicit Connect for the Command
function, it also honors Wait-exclusion. No other CLIv2 resources support Wait-exclusion: in
particular, 1) user events and master events will affect all types of wait processing, so cannot
be used either by the application or the exit; 2) a DBCHCLN call by either the application or
exit will free all CLIv2 resources for that dispatchable unit.
Coordination with Other Events
An application can have events other than requests for a Teradata session. Depending upon
the particular function, calls to DBCHCL may require communication with Teradata
Database. If so, control is not returned to the application until Teradata Database responds.
But until DBCHCL returns control, the application will be unaware of other events that might
have been completed. For example, an application might need to establish a timer and abort a
Teradata request that does not complete before the timer interval expires. The three responses
follow:
•
Allow DBCHCL to suspend
Suspending DBCHCL is the default and simplest handling. DBCHCL is called normally
and control is not returned to the application until the request is completed. The
application cannot check for completion of other events until control is returned. The
DBCAREA Wait-for-Response option is set or defaulted to 'Y'.
•
Retry if DBCHCL would suspend
DBCHCL is called but never waits if a response from Teradata Database is required.
Instead, control is returned to the application with return code 150 and the application
must call DBCHCL later to retry the operation. The DBCAREA Wait-for-Response option
is set to 'N'.
•
Suspend only in the application
DBCHCL is called but never waits if a response from the Teradata Database is required.
Instead, control is returned to the application with return code 150, the application
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
43
Chapter 1: Introduction
Common Routines Supporting CLIv2
chooses when to suspend, then the application must call DBCHCL later to retry the
operation. The DBCAREA Wait-for-Response option is set to 'N' and the CLIv2
DBCHWAT or DBCHWL service is used. Both DBCHWAT and DBCHWL identify event
completions, they differ only in that DBCHWAT responds to any event while DBCHWL
responds only to specified events. The following techniques can be used:
•
Call DBCHWAT or DBCHWL when suspension is allowed. If suspension can be
tolerated at times, then DBCHWAT or DBCHWL can be called to suspend if necessary
until a Teradata request completes. When DBCHWAT or DBCHWL returns control,
the completed request is indicated and DBCHCL can be retried.
•
Include another event when calling DBCHWAT or DBCHWLD. These calls can be
informed of another event using the DBCHUE service and DBCHWAT, or DBCHWL
can be called to suspend if necessary until either a Teradata event or the other event
completes. A return code 160 indicates that the other event completed; otherwise, the
completed event is indicated and DBCHCL can be retried
•
Include Teradata events in another event. The completion of a Teradata request can be
included into another event by using the DBCHME service. The application then
suspend on that event using an operating system service. When completion is
indicated, the application must determine whether the other event completed. If not,
then a Teradata request has completed and DBCHWAT or DBCHWL is called to
identify the request so that DBCHCL can be retried. Since it is known that some
Teradata request has completed, it is known that DBCHWAT or DBCHWL will not
suspend.
Common Routines Supporting CLIv2
The following common routines are used in most basic applications.
Routine
Description
DBCHINI
Initializes the DBCAREA, which is shared by an application and most CLIv2
routines. DBCHINI also does the internal initialization of CLIv2.
DBCHCL
•
•
•
•
•
•
•
DBCHCLN
Cleans up after an application is finished using Teradata Database.
Connects a session on Teradata Database (the database itself).
Checks that the logon was successful.
Ends the Connect request.
Sends Teradata SQL statements (for example, selects rows from a table).
Process the response (for example, obtains rows from table).
Ends the request.
Disconnects the session.
When DBCHCLN is called and the return code is zero, data structures allocated
internally during the calls to CLIv2 routines have been deallocated.
44
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: Introduction
Common Routines Supporting CLIv2
For more information about CLIv2 routines, see Chapter 6: “Common Routines.”
For information about routines that provide information about CLIv2, TDP, or Teradata
Database, see Chapter 8: “CLIv2 Query Routine.”
For information about CLIv2 routines that perform additional services, see Chapter 7: “Other
CLIv2 Routines.”
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
45
Chapter 1: Introduction
Common Routines Supporting CLIv2
46
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 2
Session Operations
This chapter describes how an application and Teradata Database interact through CLIv2:
•
Preparing to Use CLIv2
•
Setting DBCAREA Options
•
Return Codes
•
Messages for Return Codes
•
Explicitly Establishing a Session
•
Executing a RunStartUp Request
•
Submitting a Teradata SQL Request
•
Fetching the Response for a Request
•
Continuing a Teradata SQL Request
•
Rewinding to the Beginning of a Response
•
Ending a Request
•
Aborting a Request
•
Terminating a Session
•
Examples
•
Implicitly Establishing a Session
Note: Implied waiting (Wait For Response = Y) is applicable to the discussion that follows.
Preparing to Use CLIv2
An application must first establish a storage area referred to as the DBCAREA, which is the
communication structure between an application and CLIv2.
Allocating DBCAREA
Depending on the client language in which the program is coded (for example, 370
Assembler, C, COBOL, PL/I), the DBCAREA can be allocated as follows:
•
Using program storage by coding or copying the DBCAREA structure directly into the
program
•
Dynamically allocating storage and referencing the area obtained within the program
•
Passing the structure from a higher-level routine
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
47
Chapter 2: Session Operations
Setting DBCAREA Options
Initializing DBCAREA
Once it is allocated, the DBCAREA must be initialized before a call to CLIv2 requesting CLIv2
services can be attempted. The application initializes the DBCAREA by putting the total
length of the DBCAREA into the DBCAREA Total Length field of the structure and calling
DBCHINI (see Chapter 6: “Common Routines” for a description of the call to DBCHINI).
Return Code.
Result
0
DBCHINI completed successfully and DBCAREA can be used to
communicate with CLIv2.
anything else
a major system error occurred and the application cannot communicate
with CLIv2.
How Many DBCAREAs to Use
The application can use one DBCAREA for all the requests or a separate DBCAREA for each
request, or use any combination in between. This choice is available for either multi-sessions
or multi-requests.
Application Status
Result
facing space
limitations
Reuse the one DBCAREA, which involves 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.
Since 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.
Applications may append fields to the DBCAREA for their own use. While allocating storage
for, and use of, such fields are the responsibility of the application, associating them with a
DBCAREA may be useful to the application, especially if multiple DBCAREAs are used.
Setting DBCAREA Options
The DBCAREA contains option values used by the CLIv2 routines. These options are initially
set by DBCHINI based on the HSHSPB defaults provided to the program. The application
may alter any of these options as necessary for the particular processing required. Note that
not all options (and in some cases, none) are used by all calls to CLIv2.
48
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Setting DBCAREA Options
A change in an option is indicated to CLIv2 by setting the Change Options field to ‘Y‘. All
options may then be copied by CLIv2 for use. CLIv2 will verify the settings for the options as
necessary.
Change Options
The Connect function will always validate and save the DBCAREA options, regardless of the
Change Options. The options remain in effect until another Connect function is requested or
the values are changed when an Initiate Request, Initiate With Protocol-function, or
RunStartUp function call is made (Change Options = Y).
Note: Implicit logon processing will also always validate and save the DBCAREA options. For
more information, see “Implicitly Establishing a Session” on page 66.
Compatibility Options
For CLIv2 to provide a stable environment for existing applications, any enhancements to
Teradata Database that might adversely affect applications must be specified as a DBCAREA
option to allow their use. While DBCAREA specification is necessary for compatibility, this
requires applications needing such enhancements to specify the new options. Since new
applications should normally allow the enhancements, they should specify these DBCAREA
options. Specifically, new applications should consider specifying the following options when
establishing a session:
•
APH-response-OK=Y (DBRIAPH) should always be specified.
•
Column-info=E (DBRICINE) should always be specified.
•
Connect-type=C (DBOCTYPE) should always be specified.
•
Maximum-parcel=H (DBCIMP) should always be specified. For PL/I applications, the
Variable-length-request=Y and Variable-length-fetch=Y options cannot then be used.
•
Request-parcel-format=A (DBRIRPF) should always be specified.
•
Response-mode=M (DBORMOD) instead of 'R', 'I', or 'X' should be specified ('F'
provides other functionality) unless the application must support old versions of the
Teradata Database, which would reject its use. The CLIv2 Query routine QEPILOB (or
QEPIASL) can be used to ascertain if the server supports this enhancement.
•
Statement-status=E (DBCNISS) should be specified unless the application must support
old versions of the Teradata Database, which would reject its use. The CLIv2 Query
routine QEPIESS (or QEPIASL) can be used to ascertain if the server supports this
enhancement.
For applications that support multiple releases of CLIv2, a downlevel CLIv2 might not
support an enlarged DBCAREA. To ensure that a DBCAREA of the size provided to the
DBCHIN service was honored, the DBCAREA Level field should be verified.
Miscellaneous Functions
The Disconnect, Fetch, Rewind, Abort, and End Request functions will reference the options
set by the last Connect, Initiate Request, Initiate With Protocol-function, or RunStartUp
function executed.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
49
Chapter 2: Session Operations
Setting DBCAREA Options
Character Sets
A character set specifies which characters are available (for example, whether the Japanese
characters are available) and how those characters are represented (for example, EBCDIC or
ASCII). Character data in logon strings, request data, response data, and error messages are
affected by the choice of character set. An application can specify character sets; if the
character set is not specified, the default from the HSHSPB or Teradata Database is used.
Once a character set is used for a request, it will continue to be used for subsequent requests in
that session until another character set is specified.
Teradata Database processes strings from left to right, even for character sets associated with
right-to-left or bidirectional languages, such as Hebrew or Arabic.
Allowing a default character set to be used will often cause the following problems in
applications:
•
Because the logon string and request data use the character set, if the default changes, so
must the logon string or request data.
•
Because the response data and error messages use the character set, an application that
inspects this information must consider the character set. Such considerations might be
minor (EBCDIC compared to EBCDIC277_0E) but they could be major (EBCDIC
compared to UTF16). While the used character set might be obtained after a session is
established (using the DBCHQE service's Session-character-set query), doing so is too late
to ensure the logon string is in the proper character set. The application may obtain the
default before establishing a connection using the DBCHQE service's
Default-character-set query. Once the default character set is known, the application could
either reject its use or perform any character conversions necessary for its use.
If the TDPid is specified as a prefix to the logon string, then even if a Teradata Database
default character set is acceptable to an application, it should be obtained and explicitly
specified when the session is established. This is necessary because the database default
character set cannot be known by CLIv2 until the TDPid is known, but to obtain the TDPid
from the logon string requires the character set be known. If no character set is specified or
defaulted using the HSHSPB, an attempt will be made to obtain the TDPid from the logon
string using EBCDIC, which might not have the same characteristics as the database default
character set. So the TDPid might not be found, the default TDPid from the HSHSPB used,
and the wrong database might be assumed. Even if the default TDPid is the expected TDPid,
the database will fail the attempt because CLIv2 cannot remove the TDPid prefix from the
logon string.
Character sets can be supplied by the server or defined by the customer. The names of all
character sets supplied the server are known to CLIv2. Character sets defined by the customer
must also be defined to CLIv2. For more information, see Chapter 13: “User-Defined
Character Sets.”
50
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Setting DBCAREA Options
Variable Length Request Option
The setting of the Variable Length Request option affects the setting of the following:
•
Logon Pointer
•
Logon Length
•
Mechanism-data-ptr
•
Mechanism-data-length
•
Run Pointer
•
Run Length
•
Request Pointer
•
Request Length
•
Session-desc-pointer
•
Session-desc-length
•
Using Data Pointer
•
Using Data Length
•
Workload-pointer
•
Workload-length
Setting
Result
N
The xxxx_pointer contains the starting address of the actual logon string, run string,
Teradata SQL request, or using data.
The xxxx_length is set to the length of the corresponding data.
Y
The xxxx_pointer contains the address of a two-byte length, which must immediately
precede the actual text or data.
The length provided measures only the length of the text or data and does not include
the two bytes of its own length. The xxxx_length field is ignored.
If the Maximum Parcel option is set to H, then the two-byte length is considered to be an
unsigned value. Because PL/I does not support unsigned integers, you cannot use the Variable
Length Request option to allow the PL/I VARYING attribute for the Request Pointer or the
Using Data Pointer for requests greater than 32767.
Since the maximum value that can be contained in the two-byte length is 65535, larger lengths
cannot use Variable-length-requests.
Maximum Parcel Option
Newer databases are being defined with fields or rows greater than 32767 bytes; as a result,
applications will need to support larger parcel sizes. Therefore, we recommend that the
Maximum Parcel option be set to H for all future applications, thus indicating that the
application can support parcel sizes greater than 32767 bytes.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
51
Chapter 2: Session Operations
Setting DBCAREA Options
The logic of the application is not affected, only certain uses of signed two-byte unsigned
integers. Because values greater than 32767 exceed the capacity of such integers on IBM
mainframes, applications must insure that any value that is based on parcel length must use
longer integers or unsigned integers. If this is not done, CLIv2 could return a length that could
be considered to be a negative value, with unpredictable results.
Since the maximum value that can be contained in the two-byte length is 65535, requests with
larger lengths cannot use Variable-length-request. Responses with Variable-length-fetch that
require larger lengths will be rejected.
Because PL/I does not support unsigned integers, you cannot use the Variable Length Request
option to allow the PL/I VARYING attribute for the Request Pointer or the Using Data
Pointer for requests greater than 32767. This same consideration also applies to use of the
Variable Length Fetch option and the Fetch Data pointer.
When using Move Mode, you may need to increase the Fetch Maximum Data Length to
accommodate the larger parcels.
Performance Measurement
The Return-time and Timing-precision options can be used to determine the amount of time
needed to process a request and its response from the perspective of the client. If Return-time
requests such timing, up to five timestamps are returned in Time1 through Time5. The
determination of which timestamps are returned and to which points in the processing they
apply are platform-dependent. The returned Time1-status through Time5-status values
indicate which Time values are valid. Each Time is four bytes long and contains an unsigned
binary timestamp.
On channel-connected systems:
•
Time1 is set when TDP accepts a request from CLIv2
•
Time2 is set when a request is passed to the Teradata Database
•
Time3 is set when the response is received from the server
•
Time4 is set when the response leaves TDP
•
Time5 is set when the response is placed into the CLIv2 response buffer.
The difference between two timestamps represents the elapsed time between the two points in
processing. The precision for the timestamps is indicated by Timing-precision. On
channel-connected systems, timestamps are formed by manipulating the IBM standard
Time-of-Day (TOD) clock as indicated by the following Assembler code:
STCK area
LM R0,R1,area
SR R15,R15
IC R15,DBCITSP
SRDL R0,12(R15)
ST R1,DBCTIMEn
52
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Return Codes
Time1-status through Time5-status each contain a single EBCDIC character that indicates of
the status of the corresponding Time. The status values are:
•
'V' if the timestamp is valid
•
'O' if the timestamp overflowed four-bytes
•
A ‘space’ or ‘binary zero’ if the timestamp is not valid
Return Codes
Return codes are generated by client software; error codes and failure codes are generated by
Teradata Database.
Client Return Codes
Client software uses return codes to provide information about operations on the client. The
value that is returned as a return code from a CLIv2 routine is generated by the CLIv2 routine
itself or is passed back from some other client-resident module used by the CLIv2 routine. A
return code of zero is normal, and a return code of nonzero represents an exception.
A return code can appear in three areas:
•
In the Assembler register 15 (the most direct and reliable location to find a return code)
•
In a parameter in the call itself (if CLIv2 cannot access this parameter, the return code will
not appear here)
•
In the Return Code field of the DBCAREA (if CLIv2 cannot access the DBCAREA or this
field, the return code will not appear here)
Teradata Error and Failure Codes
Teradata Database uses error codes and failure codes to provide information about
operations. 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
nonzero code and represents an exception. For more information, see Chapter 10: “Error and
Failure Codes” and Chapter 11: “Crash and Recovery.”
Sometimes, both client and Teradata Database sources must be checked. For instance, on a
call to DBCHCL for the Fetch function, a return code of zero means that the client software
has set a pointer to information in the response buffer. Not until the information is examined
does the application know what the Teradata Database “has to say.” For example, the return
code may be zero and the parcel successfully pointed to may be a Failure parcel.
A code value represents the answer to a particular repeat of a particular operation. For
instance, suppose CLIv2 is obtaining a response buffer and Teradata Database is unable to
provide more of the response because the system has restarted. The application would then
discover a Failure parcel in the response buffer after a number of normal parcels.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
53
Chapter 2: Session Operations
Return Codes
Timing
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. For example, a return code of zero from DBCHCL for the Initiate Request function
means that the client has sent the request to Teradata Database; if DBCHWAT is used, a
return code of zero means that a portion of the response to some request has been received
from Teradata Database, and a return code of zero from DBCHCL for the Fetch function
means that the software has set a pointer to the next 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 nonzero return code if an application continues to ask for the next parcel in the
response after consuming the final parcel.
Types
Some values represent informational messages. For example, if an application calls DBCHCL
for the Fetch function and the response buffer is in the process of being obtained, the
application receives a return code that indicates the data is not yet available. The application
merely fetches again either immediately or after calling DBCHWAT, depending on the
technique used.
Some values represent problems from which the application can be programmed to recover.
For example, one return code indicates that the move area provided for a move-mode fetch
was not large enough for the next available parcel; the application must therefore supply a
larger area of at least the size specified by Fetch Returned Data Length in the DBCAREA and
fetch again. For more information, see Chapter 10: “Error and Failure Codes” and
Chapter 11: “Crash and Recovery.”
Other values represent problems that applications cannot recover from on their own. For
example, the return code 157 indicates the HSHSPB is missing. In this case, a programmer
must contact their system administrator to check on these conditions.
Most values represent coding problems. For example, one return code indicates that an illegal
combination of processing options has been set. In this case, a programmer must change the
program to use a legal combination.
Return codes for various clients are not necessarily the same. For example, the return code
indicating an invalid TDpid (one with valid characters but no such TDpid) is 36 on z/OS.
For more information about return codes, see the chapter on (IBM) Mainframe Client
Messages in Messages.
Messages for Return Codes
When a CLIv2 routine that uses the DBCAREA returns a non-zero return code, an associated
error message is also returned. The message will be contained either in Message Text within
the DBCAREA or in the area addressed by Message Area Pointer. A message is never returned
in both places.
54
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Explicitly Establishing a Session
•
If Message Area Pointer is specified, it is used; otherwise, Message Text is used.
•
Message Text is a fixed size field in the DBCAREA, so the maximum length of a message is
the size of that area, 76 bytes. Message Text Length contains the actual number of bytes in
the message.
•
Message Area Pointer addresses an area supplied by the application whose length is
specified by Message Area Length.
•
Message Length contains the actual number of bytes in the message. The maximum value
of this field is 65535.
Messages are normally built using the character set specified for the session when the request
is initiated; however, if an error is detected before this character set is known, the default
CLIv2 character set is used. The character set used to construct the message is indicated by
Message Charset Used.
If an error occurs while building a message, the Message Return Code field contains a CLIv2
return code. When this code is not zero, the text of the message may or may not be usable,
depending on the nature of the error.
Each message begins with the three characters “CLI” followed by a four-digit message
number. If the actual message text cannot be used, one of the following parenthesized phrases
is used:
•
'(UNDEFINED MESSAGE NUMBER)' if an invalid message number was requested.
•
'(REQUIRED MESSAGE TABLE IS NOT AVAILABLE)' if messages were not available
in the specified language.
The message language for each session is specified by the Language Id and Country Id options.
Caution:
Because the message language can differ for every request, the appropriate message definitions
are loaded into virtual storage when messages must be built and deleted from virtual storage
afterwards. These actions involve a certain performance penalty that is normally negligible
since CLIv2 return codes are unusual events. However, the design of applications should
consider the potential penalty in numerous invocations of CLIv2 routines that return error
messages when errors are expected, such as continuous invocations until a transient error
condition clears (a communication loss, for example).
Explicitly Establishing a Session
Before Teradata Database can process requests, one or more sessions must be established on a
server. If a large number of sessions need to be simultaneously connected by an application,
the DBCISMAX setting should reflect this when the first session is connected. Doing so will
improve performance by allowing CLIv2 to optimize its internal processing. To establish a
session, an application must perform the following
1
Modify the DBCAREA.
a
Set the Function to CONNECT.
b
Optionally, set the following:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
55
Chapter 2: Session Operations
Explicitly Establishing a Session
•
Mechanism-name
•
As required by that name, sets the following:
- Mechanism-data-len
- Mechanism-data-ptr
- Mechanism-data-encoding
- Delegate-user-identity
c
If required, set the Logon Pointer.
d
If required, set the Logon Length.
e
Optionally set the following:
Request Buffer Length
•
Request-parcel-format
•
Response Buffer Length
•
Anticipated Number of Concurrent Sessions
•
Request-token
•
Input TDPpath
•
Run Pointer
•
Run Length
•
Message Area Pointer
•
Message Area Length
•
Session-desc-pointer
•
Session-desc-length
•
]Workload-pointer
•
Workload-length
•
Any option values required
2
Call DBCHCL to perform the Connect function.
3
Check the return code from DBCHCL.
•
•
56
•
If the return code is anything but 0:
•
Process the return code and DBCAREA message.
•
Call DBCHCL to perform the Disconnect function (see “Terminating a Session”
on page 64).
If the return code is 0, call DBCHCL to perform a Fetch function (see “Fetching the
Response for a Request” on page 60) to get the final status of the connect request:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Executing a RunStartUp Request
Connect
Type
Return Code
Result
R
33
A session is established and the Teradata SQL processing can
continue.
0
Process the failure/error parcels.
anything else
An abnormal situation occurred. Use the Fetch function
(“Fetching the Response for a Request” on page 60) to
process.
0
Process parcels from Teradata Database.
C
If a success parcel returns, then a session is established and
Teradata SQL processing can continue.
If anything else returns, process the failure/error parcel.
anything else
4
An abnormal situation occurred. Use the Fetch function
(“Fetching the Response for a Request” on page 60) to
process.
Call DBCHCL to perform the End Request function (see “Ending a Request” on page 63).
If the Connect attempt is not successful at any point, the program can retry the Connect after
calling DBCHCL for the End Request function.
If the application requires multiple active requests, multiple sessions can be established by
following the aforementioned steps for each session desired.
In addition, the Session Id field in the DBCAREA should be saved to request Teradata SQL
processing for that session at a later time.
Password Expiration
When an application sends a connect request with an expired password, a conditional session
is established with 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 when the user is already logged on
in another session, the logon attempt fails and the session is not established.
Executing a RunStartUp Request
The user’s startup string is not automatically executed when a connection is established
through CLIv2. Instead, the startup string is executed by issuing a RunStartUp request. The
RunStartUp request can be issued at any time during the execution of the program.
The following information is presented as though the connection to Teradata Database is
already established.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
57
Chapter 2: Session Operations
Executing a RunStartUp Request
To run a startup string once the session is established, an application must perform the
following steps:
1
2
3
Modify the DBCAREA.
a
Set the Function to RunStartUp.
b
Set the Input CLIv2 Session Id to the Output CLIv2 Session Id obtained when the
session was established.
c
Optionally set the following:
•
Request Buffer Length
•
Request-parcel-format
•
Response Buffer Length
•
Anticipated Number of Concurrent Sessions
•
Request-token
•
Using Data Pointer
•
Using Data Length
•
Using-data-count
•
Using-data-length-vector
•
Using-data-pointer-vector
•
Data-encryption
•
Message Area Pointer
•
Message Area Length
•
Any option values required (remember to set Change Options = Y if any option
values are changed)
Call DBCHCL to perform the RunStartUp function, then checks the return code from
DBCHCL:
Return Code.
Result
0
Call DBCHCL to perform a Fetch function (see “Fetching the Response
for a Request” on page 60) until the complete response has been
processed.
anything else
Process the return code and DBCAREA message.
Call DBCHCL to perform the End Request function (see “Ending a Request” on page 63).
The runstartup string can contain either a macro requiring input parameters or a request with
a USING row descriptor. In this situation, the application must pass the address and length of
the data area to CLIv2. The Using Data Pointer and Using Data Length fields of the
DBCAREA are provided for this purpose.
58
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Submitting a Teradata SQL Request
Submitting a Teradata SQL Request
A Teradata SQL request must be submitted to Teradata Database for processing by using the
Initiate Request function. To initiate a request once a session is established, an application
must perform the following steps:
1
Modify the DBCAREA.
a
Set the Function to Initiate Request.
b
Set the Input CLIv2 Session Id to the Output CLIv2 Session Id obtained when the
session was established.
c
Set the Request Pointer.
d
Set the Request Length.
e
Optionally set the following:
•
Positioning-action
•
Positioning-statement-number
•
Positioning-value
•
Request Buffer Length
•
Request-parcel-format
•
Response Buffer Length
•
Anticipated Number of Concurrent Sessions
•
Request-token
•
Using Data Pointer
•
Using Data Length
•
Using-data-count
•
Using-data-length-vector
•
Using-data-pointer-vector
•
Data-encryption
•
Message Area Pointer
•
Message Area Length
•
Any option values required (remember to set Change Options = Y if any option
values are changed)
2
Call DBCHCL to perform the Initiate Request function.
3
Check the return code from DBCHCL:
Return Code
Results
0
Call DBCHCL to perform a Fetch function (see “Fetching the Response for a
Request” on page 60) until the complete response has been processed.
anything else
Process the return code and DBCAREA message.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
59
Chapter 2: Session Operations
Fetching the Response for a Request
4
Call DBCHCL to perform the End Request function. See “Ending a Request” on page 63.
The Teradata SQL request might require input data. In this situation, an application must
pass the address and length of the data area to CLI. The Using Data Pointer and Using Data
Length fields of the DBCAREA are provided for this purpose.
Fetching the Response for a Request
The final status and any response information for a request are obtained by the Fetch
function. To fetch the final status and any response once the session is established, an
application must perform the following steps:
1
Modify the DBCAREA.
a
Set the Function to Fetch.
b
Set the Input CLIv2 Session Id used to initiate the request.
c
Set the Input CLIv2 Request Id to the Output CLIv2 Request Id obtained when the
request was initiated.
d
Optionally set the following:
•
Positioning-action
•
Positioning-statement-number
•
Positioning-value
•
Fetch Maximum Data Length
•
Fetch Data Pointer
•
Message Area Pointer
•
Message Area Length
2
Call DBCHCL to perform the Fetch function.
3
Check the return code from DBCHCL.
Return Code
Results
0
Process the parcels.
This step depends on the setting of the options when the request was initiated
and any changes from an Initiate Request, Initiate With Protocol-function, or
RunStartUp function.
The first fetch returns the outcome of the request (ok, success, failure, or
error).
The effect of the option switches on fetch processing may be found in the
descriptions of the options in Chapter 3: “DBCAREA,” and under the heading
“Fetch Function” in Chapter 6: “Common Routines.”
anything else
60
Process the return code and DBCAREA message.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Continuing a Teradata SQL Request
The first fetch returns the following:
•
If any statement in the request causes an implicit rollback to occur, a failure parcel for the
entire request is returned.
•
If no implicit rollback happened, the ok, success, or error parcel information returned
pertains to the first (or only) statement of the submitted request.
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, an
application must perform the following steps:
1
Modify the DBCAREA.
a
Set the Function to 15 (ContinueRequest).
b
Set the Input CLIv2 Session Id to the Output CLIv2 Request Id returned when the
session was established.
c
Set the Input CLIv2 Request Id to the Output CLIv2 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
•
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
2
Call DBCHCL to perform the ContinueRequest function.
3
Check the return code from DBCHCL:
Return Code.
Result
0
Call 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 for a Request” on page 60.
anything else
Process the return code and DBCAREA message.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
61
Chapter 2: Session Operations
Rewinding to the Beginning of a Response
4
Call DBCHCL to perform the End Request function. For more information, see “Ending a
Request” on page 63.
Rewinding to the Beginning of a Response
The response for a request may be reprocessed from the beginning if an application requires.
The ability to rewind to the start of the response sequence is dependent on the setting of the
Keep Response option when the request is initiated.
Keep Response
Result
N
The response is discarded as it is processed and rewind is unavailable.
Y
The application has the option of rewinding to the beginning of the
response and reprocessing.
To rewind to the start of the response once the session has been established, an application
must performs the following steps:
1
62
Modify the DBCAREA.
a
Set the Function to Rewind.
b
Set the Input CLIv2 Session Id used to initiate the request.
c
Set the Input CLIv2 Request Id to the Output CLIv2 Request Id obtained when the
request was initiated.
d
Optionally set the following:
•
Message Area Pointer
•
Message Area Length
2
Call DBCHCL to perform the Rewind function.
3
Check the return code from DBCHCL:
Return Code
Results.
0
Call DBCHCL to perform a Fetch function (see “Fetching the Response for a
Request” on page 60) to get the final status of the rewind and the first part of
the response.
anything else
Process the return code and DBCAREA message.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Ending a Request
Ending a Request
Storage is acquired both by Teradata Database and CLIv2; therefore, an application needs to
release resources by letting CLIv2 know the application has finished processing the request
(either successfully or because an error has occurred).
The End Request function releases the resources associated with a particular request. To end a
request, an application must performs the following steps:
1
Modify the DBCAREA.
•
Set the Function to End Request.
•
Set the Input CLIv2 Session Id used to initiate the request.
•
Set the Input CLIv2 Request Id to the Output CLIv2 Request Id obtained when the
request was initiated.
•
Optionally set the following:
•
Message Area Pointer
•
Message Area Length
2
Call DBCHCL to perform the End Request function.
3
Check the return code from DBCHCL:
Return Code
Results.
0
The request is successfully ended.
anything else
Process the return code and DBCAREA message and resubmit the End
Request.
Aborting a Request
If an application must terminated a request prior to its completion, an asynchronous abort
can be attempted. To abort a request, an application must perform the following steps:
1
2
Modify the DBCAREA.
a
Set the Function to Abort.
b
Set the Input CLIv2 Session Id used to initiate the request.
c
Set the Input CLIv2 Request Id to the Output CLIv2 Request Id obtained when the
request was initiated.
d
Optionally set the following:
•
Message Area Pointer
•
Message Area Length
Check the return code from DBCHCL.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
63
Chapter 2: Session Operations
Terminating a Session
Return Code
Results
0
Call DBCHCL to perform a Fetch function (see “Fetching the Response for a
Request” on page 60) to await the final status of the original request.
A failure indication should be returned with a code of “user abort” (3110) if
the abort is successful.
anything else
Process the return code and DBCAREA message.
Terminating a Session
After all processing is complete for a session, an application must terminate the session by
performing the following steps:
1
Modify the DBCAREA.
2
a
Set the Function to Disconnect.
b
Set the Input CLIv2 Session Id to the Output CLIv2 Session Id obtained when the
session was established.
c
Optionally set the following:
•
Message Area Pointer
•
Message Area Length
Call DBCHCL to perform the Disconnect function.
Examples
Two examples follow; the first is for a single session, and the second is for multiple sessions.
Single Session
Each horizontal item below represents a call to DBCHCL, with function code set as in the left
column.
Function
Description
Connect
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.
64
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session Operations
Examples
Function
Description
Fetch
Fetch response data, always one of the following parcels:
Success
Error
Failure
Initiate Request
Send Teradata SQL request to the Teradata Database.
Application must set address and length of the Teradata SQL request and
optional using data.
Fetch
Fetch response data. DBCHCL will return address and length of first parcel
(or buffer, if in buffer mode).
The DBCHCL does the following, depending on whether dual buffering is
specified and the status of the current buffer:
• If dual buffering is specified and the current buffer is not the last response
buffer, DBCHCL immediately dispatches 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 specified and the current buffer is in any status,
DBCHCL transparently dispatches the continue request when the current
buffer is exhausted.
End Request
Clean up request-related context.
Disconnect
Log off from the Teradata Database and free the session-related control
blocks
Multiple Sessions
Each horizontal item that follows represents a call to DBCHCL with the function code set as
in the left column.
Function
Description
Connect/Fetch
Same as for a single session
Initiate Request
Send Teradata SQL request to the Teradata Database.
(Session 1)
Application must set address and length of Teradata SQL request and
optional using data. Application must save the Output CLIv2 Request Id.
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 Session Id and DBCAREA to id of session to be used
set Request Id to id of request to be accessed
End Request
Clean up request-related context (Stream 1 and 2)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
65
Chapter 2: Session Operations
Implicitly Establishing a Session
Function
Description
Disconnect
Log off from the Teradata Database and free the session-related control
blocks
(for each session)
Implicitly Establishing a Session
CLIv2 can attempt to establish a session implicitly for any of the following functions:
•
Connect
•
RunStartUp
•
Initiate Request
•
Initiate With Protocol-function
If no logon string is supplied, or if only a partial logon string is given, the Connect function
attempt an implicit logon. RunStartUp, Initiate Request, and Initiate With Protocol-function
attempts an implicit connection if no active sessions exist at the time they are invoked.
The DBCAREA parameters that apply for the Connect function can be supplied to the
RunStartUp, Initiate Request, and Initiate With Protocol-function if the implicit logon is to
be attempted. The implicit logon is issued for the TDP specified in the DBCAREA or
defaulted from the HSHSPB.
If the user exit is not active for the given TDP, an application will receive an error indicating
an unsuccessful logon attempt. Likewise, if the information the logon exit supplies for the
logon attempt is incorrect, an appropriate error will be returned to the application.
66
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 3
DBCAREA
The DBCAREA is a data structure shared between the application and CLIv2. It defines the
interface between CLIv2 and an application.
•
An application sets values in the DBCAREA to transfer information to CLIv2.
•
CLIv2 sets values in the DBCAREA to transfer information back to an application.
How Applications Use DBCAREA
The DBCAREA is allocated by an application, then passed to DBCHINI where it is cleared and
some fields are initialized to their default values. After initialization, an application sets
appropriate input values in the DBCAREA before each call to DBCHCL. When an application
regains control from DBCHCL, it can obtain the appropriate output values from the
DBCAREA.
Field Descriptions
The DBCAREA contains seven logical sections:
•
Header
•
General Inputs
•
General Outputs
•
Function Specific
•
Options
•
Message
Each logical section consists of multiple fields, which are presented in their physical order in
Table 4 on page 76.
For each of the fields described in the following sections, a table that lists the language used
and the corresponding variable name.
Function Abbreviations
Functions are abbreviated as follows:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
67
Chapter 3: DBCAREA
Field Descriptions
Abbreviations
Call to DBCHCL for this function
CON
Connect
RSUP
RunStartUp
IRQ
Initiate Request
CRQ
Continue-request
IWPF
Initiate With Protocol-Function
REW
Rewind
ERQ
End Request
ABT
Abort
DSC
Disconnect
CMD
Command
FET
Fetch
Input Fields
The input fields are used by an application to indicate an action to be taken, to set processing
options, and to pass data to CLIv2. Some of the fields are used to construct parcels for
Teradata Database.
Output Fields
The output fields are used by CLIv2 to provide the return code from the action requested and
to pass back information from CLIv2 (for example, a pointer to a parcel in the response).
Include files, which define this area, are provided for the supported languages, which are any
language that supports standard IBM call linkage.
Note: Some fields are treated differently in different functions and by different clients.
Table 2: Order of the DBCAREA
Byte Offset
(in decimal)
000
000
001
002
003
Eyecatcher, 8 bytes
004
68
008
Total Length, 4 bytes
012
Function, 4 bytes
016
Input CLIv2 Connection Id, 4 bytes
020
Input CLIv2 Request Id, 4 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Field Descriptions
Table 2: Order of the DBCAREA (continued)
Byte Offset
(in decimal)
000
001
002
003
024
Request Buffer Length, 4 bytes
028
Response Buffer Length, 4 bytes
032
Anticipated Number of Concurrent Sessions, 4 bytes
036
Request-token, 4 bytes
040
Return Code, 4 bytes
044
Output CLIv2 Connection Id, 4 bytes
048
Output CLIv2 Request Id, 4 bytes
052
Output TDP Path, 8 bytes
056
060
064
Output TDP Session Id, 4 bytes
Output Host Id, 2 bytes
Session Status,
1 byte
068
TDP Request Number, 4 bytes
072
Current Request Buffer Length, 4 bytes
076
Current Response Buffer Length, 4 bytes
080
Input TDP Path, 8 bytes
Unused, 1 byte
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
124
Reserved for internal use, 10 bytes
128
Unused, 2 bytes
132
Open Request, 4 bytes
136
Fetch Maximum Data Length, 4 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
69
Chapter 3: DBCAREA
Field Descriptions
Table 2: Order of the DBCAREA (continued)
Byte Offset
(in decimal)
000
001
002
140
Fetch Data Pointer, 4 bytes
144
Fetch Returned Data Length, 4 bytes
148
Fetch Parcel Flavor, 4 bytes
152
Unused, 4 bytes
156
TDP-receipt-timestamp, 8 bytes
003
160
164
Time1, 4 bytes
168
Time2, 4 bytes
172
Time3, 4 bytes
176
Time4, 4 bytes
180
Time5, 4 bytes
184
Character Set Pointer, 4 bytes
188
(reserved for network use, 8 bytes)
192
196
200
Unused, 16 bytes
204
208
212
70
Extension Pointer, 4 bytes
216
Change Options,
1 byte
Response Mode,
1 byte
Use Presence Bits,
1 byte
Keep Response,
1 byte
220
Wait During Delay,
1 byte
Tell if Delay,
1 byte
Reserved for
network use, 1 byte
Locate Mode,
1 byte
224
Variable Length
Request, 1 byte
Variable Length
Fetch, 1 byte
Save Response
Buffer, 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
Reserved for
network use, 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
Language
Conformance, 1
byte
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Field Descriptions
Table 2: Order of the DBCAREA (continued)
Byte Offset
(in decimal)
240
000
001
002
Unused, 2 byte
003
Message Text Length, 2 bytes
244
|.....|
Message Text, 76 bytes
316
320
Route Description Codes, 4 bytes
324
Unused, 4 bytes
328
Reserved for internal use, 4 bytes
332
Unused, 8 bytes
336
340
344
C2S Conversion,
1byte
S2C Conversion,
1 byte
Language Id, 2 bytes
Date Form,
1 byte
Maximum
Parcel, 1 byte
Country Id, 2 bytes
348
Segment Data, 1byte
Return-objects-as,
1 byte
Continued-data,
1 bytes
Data-encryption,
1 byte
352
Request-parcelformat, 1 byte
Statement-status,
1 byte
Continuedcharacters-state,
1 byte
APH-response-OK,
1 byte
356
Return-statementinfo
Return-identitydata
Positioning-statement-number, 2 bytes
Positioning-value, 8 bytes
360
364
368
372
376
380
Positioning-action, 2 bytes
Level, 1 byte
Message Charset
Used, 1 byte
Message Length, 2 bytes
Timing-precision, 2 bytes
Message Return Code, 2 bytes
Message Area Length, 2 bytes
Message Area Pointer, 4 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
71
Chapter 3: DBCAREA
Field Descriptions
When the Level field is not binary '0', the following fields are also present:
Table 3: Order of the Enlarged DBCAREA When Level > 0
Byte Offset
(in decimal)
000
001
002
003
384
|....|
Unused, 148 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
Wait-exclusion,
1 byte
Use-default-conn, 1
byte
540
Using-data-count, 4 bytes
544
Mechanism-name, 8 bytes
548
552
Unused, 4 bytes
556
Mechanism-data-ptr, 4 bytes
560
Mechanism-data-len, 4 bytes
564
Result-sets-OK,
1 byte
Return-result-setsto, 1 byte
568
Unused, 4 bytes
572
Using-data-pointer-vector, 4bytes
576
Unused, 4 bytes
580
Using-data-length-vector, 4 bytes
584
Max-decimal-returned, 2 bytes
Transforms-off
1 byte
588
Workload-length, 4 bytes
592
Unused, 4 bytes
596
Workload-pointer, 4 bytes
600
Unused, 4 bytes
604
Session-desc-pointer, 4 bytes
608
Session-desc-length, 4 bytes
612
616
72
Mechanism-dataencoding, 1byte
Trusted-request
1 byte
Column-info
1 byte
Utility-workload
1 byte
Delegate-useridentity, 1 byte
Period-as-Struct
1 byte
Unused 1 byte
Unused, 20 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Anticipated Number of Concurrent Sessions
Table 3: Order of the Enlarged DBCAREA When Level > 0 (continued)
Byte Offset
(in decimal)
000
001
636
002
Unused, 3 bytes
003
Refresh-cacheddata, 4 bytes
Anticipated Number of Concurrent Sessions
Anticipated Number of Concurrent Sessions is a four-byte field that refers to the maximum
number of sessions expected to be concurrently established.
Language
Variable
COBOL
DBCAREA-MAX-NUM-SESS
PL/I
MAX_NUM_SESS
C
max_num_sess
IBM Assembler
DBCISMAX
Routine
Action
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; IWPF; CMD)
DBCHWAT
Maximum Number of Sessions is used by...
To...
applications
write
The value of zero for Anticipated Number of Concurrent Sessions indicates that the default
value from the HSHSPB is used for the Anticipated Number of Concurrent Sessions. The
application may change the value of Anticipated Number of Concurrent Sessions by
supplying the preferred value in the DBCAREA. The minimum value is 1, and the maximum
value is 999.
Anticipated Number of Concurrent Sessions is used for two purposes. When CLIv2 must wait
for one or more sessions to complete, it must build a list of system-dependent control blocks
on which it will wait. If CLIv2 obtains a list of a particular size and then on a subsequent call
needs a larger list, it must free the existing list and obtain a larger one. You can avoid this
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
73
Chapter 3: DBCAREA
APH-response-OK
overhead by obtaining an appropriately sized list the first time. CLIv2 rounds the specified
value up to the next multiple of 16 and obtains a list of this size.
When a request or response is processed, CLIv2 must lookup the CLIv2 internal information
for that session. The larger the number of simultaneous sessions, the less efficient such session
lookup can be. CLIv2 uses the value set for the Anticipated Number of Concurrent Sessions
when the first session is connected to optimize the internal lookup algorithm. So setting an
accurate value initially can reduce the CPU used by CLIv2 on all subsequent calls.
APH-response-OK
APH-response-OK specifies whether response parcels may use the alternate parcel header.
Applications that use buffer-mode to fetch responses must be changed to properly handle
such alternate parcel headers, then specify this option to indicate such support exists. Other
applications require no changes except the specification of this option. If a response parcel
exceeds 65535 bytes but this option is not specified, error code 3177 will be returned.
74
In this language...
The variable name for APH-response-OK is...
COBOL
DBRIAPH
PL/I
DBRIAPH
C
dbriAPH
IBM Assembler
DBRIAPH
This routine...
Does this forAPH-response-OK...
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
APH-response-OK is used by...
To...
applications
write.
If...
Then set APH-response-OK to...
response parcels may not use alternate parcel
headers
'N'
response parcels may use alternate parcel headers
'Y'
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Change Options
Note: For new applications, APH-response-OK should always be set to ‘Y‘.
Mnemonics should be used for the codes. Mnemonics are provided in the language definition
file for the DBCAREA.
Change Options
Change Options is a one-byte field that specifies whether any options have been changed since
the last time they were scanned by CLIv2.
In this language...
The variable name for Change Options is...
COBOL
DBCAREA-CHANGE-OPTS
PL/I
CHANGE_OPTS
C
change_opts
IBM Assembler
DBOSETO
This routine...
Does this for Change Options...
DBCHINI
writes
DBCHCL
reads and writes (CON; CMD; RSUP; IRQ; CRQ; IWPF)
Change Options is used by...
To...
applications
write.
Interaction with Other Data Structures
Options are always scanned for a connect (CON) request, regardless of the setting for the
field. Change Options are honored on subsequent requests that initiate the following
functions:
•
IRQ
•
CRQ
•
RSUP
•
CMD
•
IWPF
If the value provided is not appropriate for the application, before calling DBCHCL for the
connect option, an application can change the value according to the following generalized
procedure:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
75
Chapter 3: DBCAREA
Change Options
1
Set Change Options to ‘Y‘.
2
Change the value for <option> as follows.
If the application requires...
Then set <option> to...
<desired condition>
<option that specifies the desired condition>
Performance Issues
Options processing is expensive, so it is prudent to use it only when necessary, but such
processing might be necessary immediately after a call to DBCHINI to establish
application-specific defaults. After that, it is only necessary if some processing option is
changed. CLIv2 sets Change Options back to N.
Options Scanned When Set to Y
Table 4 summarizes the options that scanned for each function if Change Options is set to ‘Y‘.
Table 4: Change Options Scanning
no
no
no
no
no
APH-response-OK
no
yes
yes
yes
no
no
no
no
no
no
no
Column-info
no
no
yes
yes
yes
no
no
no
no
no
no
Connect Type
yes
no
no
no
no
no
no
no
no
no
no
Continue-data
no
no
no
no
no
yes
no
no
no
no
no
Continued-characters-state
no
yes
yes
yes
no
no
no
no
no
no
no
C2S Conversion
yes
yes
yes
yes
no
yes
no
no
no
no
no
Data-encryption
no
yes
yes
yes
no
no
no
no
no
no
no
Date Form
yes
no
no
no
no
no
no
no
no
no
no
Delegate-user-identity
yes
no
no
no
no
no
no
no
no
no
no
Country Id
yes
no
no
no
no
no
no
no
no
no
no
Keep Response
no
yes
yes
yes
yes
no
no
no
no
no
no
Language Conformance
yes
no
no
no
no
no
no
no
no
no
no
Language Id
yes
no
no
no
no
no
no
no
no
no
no
Locate Mode
yes
yes
yes
no
yes
yes
no
no
no
no
no
76
Fetch
no
Disconnect
yes
Abort
yes*
End Request
yes*
Rewind
yes*
Continue-request
Initiate Within
Protocol-Function
no
Command
Initiate Request
Anticipated Num Sessions
Options Scanned
Connect
RunStartUp
Function
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Change Options
Table 4: Change Options Scanning (continued)
Fetch
Disconnect
Abort
End Request
Rewind
Continue-request
Command
Initiate Within
Protocol-Function
Initiate Request
RunStartUp
Options Scanned
Connect
Function
Maximum-decimal-returned
no
yes
yes
yes
no
no
no
no
no
no
no
Maximum Parcel
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Mechanism-data-encoding
yes
yes*
yes*
yes*
no
no
no
no
no
no
no
Parcel Mode Fetch
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Period-as-Struct
no
no
yes
yes
yes
no
no
no
no
no
no
Positioning-action
no
no
no
no
no
no
no
no
no
no
yes
Positioning-statement-number
no
no
no
no
no
no
no
no
no
no
yes
Positioning-value
no
no
no
no
no
no
no
no
no
no
yes
Protocol-Function
no
no
yes
no
no
no
no
no
no
no
no
Request Buffer Length
yes
yes*
yes*
yes*
no
no
no
no
no
no
no
Refresh-cached-data
no
yes
yes
yes
no
no
no
no
no
no
no
Request Mode
yes
yes
yes
yes
no
yes
no
no
no
no
no
Request-parcel-format
yes
yes
yes
yes
no
no
no
no
no
no
no
Request Processing Option
yes
yes
yes
yes
no
no
no
no
no
no
no
Response Buffer Length
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Response Mode
yes
yes
yes
yes
yes
no
no
no
no
no
no
Result-sets-OK
no
yes
yes
yes
no
no
no
no
no
no
no
Return-identity-data
no
yes
yes
yes
no
no
no
no
no
no
no
Return-objects-as
yes
yes
yes
yes
no
no
no
no
no
no
no
Return-result-to
no
yes
yes
yes
no
no
no
no
no
no
no
Return-statement-info
no
yes
yes
yes
no
no
no
no
no
no
no
Return Time
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Save Response Buffer
yes
yes
yes
yes
no
yes
no
no
no
no
no
Segment Data
yes
no
yes
yes
no
no
no
no
no
no
no
Set Character Set
yes
yes
yes
yes
no
no
no
no
no
no
no
Statement-status
yes
yes*
yes*
yes*
no
no
no
no
no
no
no
S2C Conversion
yes
yes
yes
yes
no
yes
no
no
no
no
no
Tell if Delay
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
77
Chapter 3: DBCAREA
Character Set Pointer
Table 4: Change Options Scanning (continued)
Fetch
Disconnect
Abort
End Request
Rewind
Continue-request
Command
Initiate Within
Protocol-Function
Initiate Request
Options Scanned
RunStartUp
Connect
Function
Timing-precision
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Transaction Semantics
yes
no
no
no
no
no
no
no
no
no
no
Transforms-off
no
no
yes
yes
yes
no
no
no
no
no
no
Trusted-request
no
no
yes
yes
yes
no
no
no
no
no
no
Two Response Buffer
yes
yes
yes
yes
no
no
no
no
no
no
no
2PC
yes
no
no
no
no
no
no
no
no
no
no
Use-default-conn
yes
yes*
yes*
yes*
no
no
no
no
no
no
no
Use Presence Bits
yes
yes
yes
yes
yes
no
no
no
no
no
no
Utility-workload
no
yes
yes
yes
yes
no
no
no
no
no
no
Variable Length Fetch
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Variable Length Request
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Wait During Delay
yes
yes
yes
yes
yes
yes
no
no
no
no
no
Wait-exclusion
yes
yes*
yes*
yes*
yes
no
no
no
no
no
no
Wait For Response
yes
yes
yes
yes
yes
yes
no
no
no
no
no
* These values are needed only for an implicit Connect.
Character Set Pointer
Character Set Pointer is a four-byte field that specifies the address of a 30-byte character set
name to be used on the current and subsequent requests and responses. A character set name
can only contain characters from the standard EBCDIC character set.
CLIv2 recognizes the following character sets, which have EBCDIC characteristics supplied by
Teradata Database:
78
•
“EBCDIC” on page 375
•
“EBCDIC037_0E” on page 377
•
“EBCDIC273_0E” on page 378
•
“EBCDIC277_0E” on page 379
•
“HANGULEBCDIC933_1II” on page 380
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Character Set Pointer
•
“KANJIEBCDIC5026_0I” on page 385
•
“KANJIEBCDIC5035_0I” on page 391
•
“KATAKANAEBCDIC” on page 397
•
“SCHEBCDIC935_2IJ” on page 403
•
“TCHEBCDIC937_3IB” on page 405
CLIv2 also recognizes the following character sets, which have ASCII characteristics supplied
by Teradata Database:
•
ARABIC1256_6A0, defined by Microsoft code
•
ASCII, defined by IBM code
•
CYRILLIC1251_2A0, defined by Microsoft code
•
HANGUL949_7R0, defined by Microsoft code
•
HANGULKSC5601_2R4, defined by IBM code
•
HEBREW1255_5A0, defined by Microsoft code
•
KANJI932_1S0, defined by Microsoft code
•
KANJIEUC_0U, defined by IBM code
•
KANJISJIS_0S, defined by IBM code
•
LATIN1_0A, defined by IBM code
•
LATIN1250_1A0, defined by Microsoft code
•
LATIN1252_3A0, defined by Microsoft code
•
LATIN1254_7A0, defined by Microsoft code
•
LATIN1258_8A0, defined by Microsoft code
•
LATIN9_0A, defined by ISO/IEC 8859-15
•
SCHGB2312_1T0, defined by IBM code
•
SCHINESE936_6R0, defined by Microsoft code
•
TCHBIG5_1R0 defined by IBM code
•
UTF8, defined by ISO/IEC 10646
•
UTF16, defined by ISO/IEC 10646
The characteristics of user-defined character sets are described to CLIv2 using the TRD2XUT
utility program. See Chapter 13: “User-Defined Character Sets” for details.
User-defined character sets that have not been described to CLIv2 can be used, but their
characteristics (codepoints for Space, Apostrophe, Quotation Mark, Slash, the Substitute
control character, any character that appears in a TDPid, and the encoding scheme) are
assumed to be the same as for EBCDIC.
Language
Variable Name for Character Set Pointer
COBOL
DBCAREA-CSC-PTR
PL/I
CSC_PTR
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
79
Chapter 3: DBCAREA
Column-info
Language
Variable Name for Character Set Pointer
C
inter_ptr
IBM Assembler
DBCCSNP or DBCCSCP
Routine
Action for Character Set Pointer
DBCHINI
writes
DBCHCL
reads
Character Set Pointer is used by...
To...
applications
write
Interaction with Other Data Structures
This field is used in conjunction with the Set Character Set field in the options fields. The
character set pointer is initialized from the HSHSPB.
Column-info
Column-info is a one byte EBCDIC 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.
80
In this language...
The variable name for Column-info is...
COBOL
COLUMN-INFO
PL/I
COLUMN-INFO
C
columnInfo
IBM Assembler
DBRICIN
This routine...
Does this for Column-info...
DBCHINI
writes
DBCHCL
reads (CON; IRQ; RSUP)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Connect Type
Column-info is used by...
To...
applications
write.
One of the following values may be set before initiating a request: 'O' (DBRICINO for
Assembler, DBC_ColInfoOrig for C, ORIGINAL for COBOL, DBC_COL_INFO_ORIG for
PL/I), indicates varying-length column name, title, and format information in existing
response parcels cannot be longer than the existing maximum. 'E' (DBRICINE for Assembler,
DBC_ColInfoExt for C, EXTENDED for COBOL, DBC_COL_INFO_EXT for PL/I) indicates
varying-length column name, title, and format information in existing response parcels can
be longer than the existing maximum.
If not specified, the default from the HSHSPB is used, which as distributed is 'O'.
Connect Type
Connect Type is a one-byte field that specifies whether CLIv2 should send a separate logon
and run to the Teradata Database or a combined logon and connect. For new applications,
Connect-type should always be set to 'C' since all recent Teradata Databases support its use.
In this language...
The variable name for Connect Type is...
COBOL
DBCAREA-CONNECT-TYPE
PL/I
CONNECT_TYPE
C
connect_type
IBM Assembler
DBOCTYPE
This routine...
Does this for Connect Type...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ)
Connect Type is used by...
To...
applications
write.
Connect Type is initialized to the default value provided for Connect Type in the site‘s
HSHSPB. If the value provided is not appropriate for an application, before calling DBCHCL
for the connect option, the application can change the value as follows:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
81
Chapter 3: DBCAREA
Continued-characters-state
1
Set Change Options to ‘Y‘.
2
Change the value for Connect Type as follows.
Note: For new applications, Request-parcel-format should always be set to ‘H‘.
If...
Then set Connect Type to...
a separate logon and run should be sent to the Teradata
R
Database
a combined logon and connect should be sent to the Teradata
C
Database
Continued-characters-state
Continued-characters-state specifies whether character data crossing multiple response
parcels in MultipartIndicator mode is well-formed within each parcel or only when all parcels
are considered. This option has effect only if the character set being used supports lockingshifts (such as the Shift-out and Shift-in control characters).
In this language...
The variable name for Continued-characters-state is...
COBOL
DBRICCS
PL/I
DBRICCS
C
dbriCCS
IBM Assembler
DBRICCS
This routine...
Takes this action for Continued-characters-state...
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
Continued-characters-state is used by...
To...
applications
write
One of the following values can be set before initiating a request:
82
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Continued-data
If...
Then set Connect Type to...
the default, indicates that character data crossing multiple
response parcels is well-formed only when all parcels are
considered. This is appropriate if the data from all parcels
containing the data are to be concatenated.
'L'
indicates that character data crossing multiple response
parcels in MultipartIndicator mode is well-formed within
each parcel. This is appropriate if the data in each parcel is
processed separately.
'U'
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Continued-data
Continued-data specifies the processing to be performed when the Continue-request function
is invoked. The value indicates whether the request is for the first, intermediate, or last
continuation, or whether processing is to be cancelled.
In this language...
The variable name for Continued-data is...
COBOL
DBNICNT
PL/I
DBNICNT
C
dbniCnt
IBM Assembler
DBNICNT
This routine...
Takes this action for Continued-data...
DBCHINI
DBCHINI does not initialize this value. When the Continue-request function is
needed by the application, the following procedure must be followed before
calling DBCHCL for the Continue-request function:
1 Set Change-options to 'Y'
2 Set the value for Continued-data as follows:
first segment, F
intermediate segment, I
last segment, L
cancel Continued-request, C
Note: Use mnemonics for the codes. Mnemonics are provided in the language
definition file for the DBCAREA.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
83
Chapter 3: DBCAREA
Country Id
This routine...
Takes this action for Continued-data...
DBCHCL
reads.
CRQ
Continued-data is used by...
To...
applications
write
Country Id
Country Id is a two-byte field that specifies the country variant of the language to be used for
all CLIv2 error messages returned in the Message Text DBCAREA field, and that were
associated with the session being connected. The value specifies a two-character Country Id.
Because the Country Id qualifies the language, Language Id must also be specified. When a
language is commonly used in several countries, the Country Id may be specified to select
messages that are unique to that country.
The Country Id is defined by the ISO 3166-1 standard. The value is in EBCDIC, and both
lowercase and uppercase characters are permitted.
84
In this language...
The variable name for Country Id is...
COBOL
DBCNICID
PL/I
DBCNICID
C
dbcniCid (case is significant)
IBM Assembler
DBCNICID
This routine...
Does this for Country Id. . .
DBCHINI
writes
DBCHCL
reads CON
Country Id is used by...
To...
applications
write
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Country Id
DBCHINI initializes the Country Id to the default value provided in the HSHSPB being used.
The distributed HSHSPB provides no default for Country Id; therefore, unless a Country is
specified, the Language Id alone defines the message language.
If a Country Id is appropriate for an application, the application should perform the following
procedure before calling DBCHCL for the connect function:
1
Set Change Options to ‘Y‘.
2
Change the value for Country Id as follows:
If the language is...
Then set Country Id to...
Arabic
No country differentiation supported.
Danish (Denmark)
DK
German (Germany)
DE
German (Switzerland)
CH
Greek (Greece)
GR
English (United States)
US
English (United Kingdom)
GB
Spanish (Spain)
ES
Finnish (Finland)
FI
French (France)
FR
French (Belgium)
BE
French (Canada)
CA
French (Switzerland)
CH
Hebrew (Israel)
IL
Icelandic (Iceland)
IS
Italian (Italy)
IT
Italian (Switzerland)
CH
Japanese (Japan)
JP
Korean (Republic of Korea)
KR
Dutch (Netherlands)
NL
Dutch (Belgium)
BE
Norwegian (Norway)
NO
Portuguese (Portugal)
PT
Portuguese (Brazil)
BR
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
85
Chapter 3: DBCAREA
Current Request Buffer Length
If the language is...
Then set Country Id to...
Romansh/Grishun (Switzerland)
CH
Russian (Russian Federation)
RU
Swedish (Sweden)
SE
Thai (Thailand)
TH
Turkish (Turkey)
TR
Chinese (China)
CN
Chinese (Taiwan)
TW
Messages are distributed in United States English (Language Id 'EN', optional Country Id
'US') only, although customers or Teradata Corporation in the various countries might
provide additional languages. The mechanism by which the CLIv2 error messages are be
defined in other languages is described in Chapter 13: “User-Defined Character Sets.”.
If a message must be returned, but messages are not available in the specified language, then
the message number with fixed message text of '(REQUIRED MESSAGE TABLE IS NOT
AVAILABLE)' in United States English is returned. For example, the message 'CLI0538
REQUEST REJECTED BY DELAY' would be presented as:
CLI0538 (REQUIRED MESSAGE TABLE IS NOT AVAILABLE)
Current Request Buffer Length
Current Request Buffer Length is a four-byte field that is the actual length of the request
buffer at the time the request is made.
86
In this language...
The variable name for Current Request Buffer
Length is...
COBOL
DBCAREA-CUR-REQ-BUF-LEN
PL/I
CUR_REQ_BUF_LEN
C
cur_req_buf_len
IBM Assembler
DBCORBLA
This routine...
Takes this action for Current Request Buffer
Length...
DBCHINI
writes
DBCHCL
writes (CON; RSUP; IRQ; IWPF; CMD; CRQ)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Current Response Buffer Length
Current Request Buffer Length is used by...
To...
applications
read.
Current Response Buffer Length
Current Response Buffer Length is a four-byte field that is the actual length of the response
buffer at the time the request is made.
In this language...
The variable name for Current Response Buffer
Length is...
COBOL
DBCAREA-CUR-RESP-BUF-LEN
PL/I
CUR_RESP_BUF_LEN
C
cur_resp_buf_len
IBM Assembler
DBCOFBLA
This routine...
Does this for Current Response Buffer Length...
DBCHINI
writes
DBCHCL
writes (CON; RSUP; IRQ; FET; IWPF; CMD; CRQ)
Current Response Buffer Length is used by...
To...
applications
read.
After regaining control from a call to DBCHCL with function code set to any function except
Disconnect, an application can obtain the value of the actual response buffer length in
Current Response Buffer Length.
C2S Conversion
C2S Conversion is a one-byte field that specifies the action to be taken when data provided in
the client character set contains a character that does not exist in the character set of Teradata
Database.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
87
Chapter 3: DBCAREA
C2S Conversion
In this language...
The variable name for C2S Conversion is...
COBOL
DBCAREA-C2S-CONVERSION
PL/I
C2S_CONVERSION
C
c2s_conversion
IBM Assembler
DBCIC2SC
This routine...
Does this for C2S Conversion...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; IWPF; CRQ)
C2S Conversion is used by...
To...
applications
write
C2S Conversion is initialized to the default value provided for C2S Conversion in the site‘s
HSHSPB. But if the value is not appropriate for the application, the application may, before
calling DBCHCL for Initiate or Initiate With Protocol-Function, change the value as follows:
1
Set Change Options to ‘Y‘.
2
Change the value for C2S Conversion as follows:
If...
Then set C2S
Conversion to...
such conversions are to be rejected and terminate the request
R
such conversions are to be ignored (and the unacceptable character
replaced by the character in the client‘s character set defined to be used
to represent invalid characters)
I
the Teradata Database default C2S Conversion setting is to be used
D
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
88
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Data-encryption
Data-encryption
Data-encryption specifies whether the data for a request and the associated response is to be
encrypted. If encryption is specified but not supported, the request will be rejected.
Encryption is currently not supported for a channel- attached system.
In this language...
The variable name for Data-encryption is...
COBOL
DBRIDEN
PL/I
DBRIDEN
C
dbriDEn
IBM Assembler
DBRIDEN
This routine...
Takes the action for Data-encryption. . .
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
Data-encryption is used by...
To...
applications
write
One of the following values may be set before calling the Fetch function:
If...
Then set Data-encryption to...
do not encrypt the data (default)
N
encrypt the data
Y
Mnemonics are provided in the language definition file for the DBCAREA and should be used
for the codes.
Date Form
Date Form is a one-byte field that specifies whether dates are stored in Teradata or ANSI
format. When Date-Form 'A' is specified, Connect-type 'C' must also be specified.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
89
Chapter 3: DBCAREA
Date Form
In this language...
The variable name for Date Form is...
COBOL
DATE-FORM
PL/I
DATE_FORM
C
date_form
IBM Assembler
DBCNIDF
This routine...
Takes the action for Date Form...
DBCHINI
writes
DBCHCL
reads (CON)
Date Form is used by...
To...
applications
write
Date Form is initialized to the default value provided for Date Form in the site‘s HSHSPB. If
the value is not appropriate for an application, the application may, before calling DBCHCL
for Connect, change the values as follows:
1
Set Change Options to ‘Y‘.
2
Change the value for Date Form as follows:
Then change the
value for Date Form
to...
If...
dates are stored using the default setting for the user (if such a default is
associated with the user) or for the server
D
date are stored in Teradata format
T
dates are stored in ANSI format
A
Note: T may always be specified, but A is rejected if the server does not support ANSI date
formats.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
90
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Delegate-user-identity
Delegate-user-identity
Delegate-user-identity is a one-byte EBCDIC field that indicates whether the new
connection's user identity is made available to applications on Teradata Database so that they
may act on behalf of the user. The identity is an internal representation of the identity, not
simply a cleartext password.
Use of this option requires specification of a Mechanism-name.
Delegate-user-identity exists only when DBCHINI had been called for a DBCAREA with
Total-length set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Delegate-user-identity is ignored.
Note: Logon mechanisms are currently not supported for a channel-connected system.
In this language...
The variable name for Delegate-user-identity is...
COBOL
DELEGATE-USER-IDENTITY
PL/I
DELEGATE_USER_IDENTITY
C
delegateUserIdentity
IBM Assembler
DBCNIDI
This routine...
Does this for Delegate-user-identity...
DBCHINI
writes
DBCHCL
reads (RCON)
C
delegateUserIdentity
IBM Assembler
DBCNIDI
Delegate-user-identity is used by...
To...
applications
write
One of the following values can be set before initiating a request:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
91
Chapter 3: DBCAREA
Extension Pointer
If...
Then set Connect Type to...
indicates that a new connection is established.
'N'
•
•
•
•
indicates that the new connection's user identity
is delegated to the Teradata Database for use by
application there.
DBCNIDIN for Assembler
DBC_DelegateIdNo for C
DBC-NO for COBOL
DBC_DELEGATE_ID_NO for PL/I
'Y'
•
•
•
•
DBCNIDIY for Assembler
DBC_DelegateIdYes for C
DBC-YES for COBOL
DBC_DELEGATE_ID_YES for PL/I
Extension Pointer
Extension Pointer is a four-byte field that specifies the address of the first or only DBCAREA
extension.
In this language...
The variable name for Extension Pointer is...
COBOL
DBCAREA-EXT-PTR
PL/I
EXT_PTR
C
extension_pointer
IBM Assembler
DBCAXP
This routine...
Takes the action for Extension Pointer...
DBCHINI
writes
DBCHCL
reads (IRQ; IWPF)
Extension Pointer is used by...
To...
applications
write
Each extension applies only to particular functions, so care must be taken to address the
proper extension before invoking a function and clearing the Extension Pointer when that
function is complete.
92
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Eyecatcher
For more information about DBCAREA extensions, see Chapter 4: “DBCAREA Extensions.”
Eyecatcher
The Eyecatcher field is an eight-byte field that is used for self-documentation and debugging.
Eyecatcher is set to DBCAREA by a call to DBCHINI.
In this language...
The variable name for Eyecatcher is...
COBOL
DBCAREA-EYECATCHER
PL/I
EYECATCHER
C
eyecatcher
IBM Assembler
DBCAID
This routine...
Does this for Eyecatcher...
DBCHINI
writes
Fetch Data Pointer
Fetch Data Pointer is a four-byte field that has different meanings in Move Mode and Locate
Mode. The following discussion covers the common properties of Fetch Data Pointer in Move
or Locate Mode.
In this language...
The variable name for Fetch Data Pointer is...
COBOL
DBCAREA-FET-DATA-PTR
PL/I
FET_DATA_PTR
C
fet_data_ptr
IBM Assembler
DBFXFDP
Fetch Data Pointer—Move Mode
In the Move Mode, Fetch Data Pointer is where an application specifies the address of its
move area before fetching results from the listed requests.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
93
Chapter 3: DBCAREA
Fetch Data Pointer
This routine...
Does this for Fetch Data Pointer in Move Mode...
DBCHINI
writes
DBCHCL
reads (FET)
The following table explains how Fetch Data Pointer works in Move Mode (Locate Mode =
N) when DBCHCL is called for the following functions:
•
Connect
•
RunStartUp
•
Command
•
Initiate Request
•
Initiate with Protocol-Function
IF Variable Length Fetch is set to this
value in DBCAREA...
THEN the address in Fetch Data Pointer points to the ...
N
first byte of the parcel body.
Y
two-byte length field that precedes the returned data.
In Move Mode, only the number of bytes that constitute the length are affected in the move
area. The bytes beyond are unaffected.
In Move Mode, Fetch Data Pointer is used by...
To...
applications
write (FET)
Fetch Data Pointer—Locate Mode
In the Locate Mode, DBCHCL places Fetch Data Pointer in the DBCAREA when the fetch
function completes. Thus, Fetch Data Pointer is available when the application regains
control with a return code of zero from a call to DBCHCL for the fetch function.
This routine...
Does this for Fetch Data Pointer in Locate Mode...
DBCHINI
writes
DBCHCL
writes (FET)
The following table explains how Fetch Data Pointer works in Locate Mode (Locate Mode =
‘Y‘) when DBCHCL is called for the following functions:
94
•
Connect
•
RunStartUp
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Fetch Maximum Data Length
•
Initiate with Protocol-Function
•
Command
•
Initiate Request.
If you use this
mode...
And you set
Variable Length
Fetch in
DBCAREA to
this value...
And you set
Parcel Mode
Fetch in
DBCAREA to
this value...
Then the address in Fetch Data Pointer
points to the...
parcel
N
none
first byte of the parcel body.
parcel
Y
none
two byte length field that precedes the
returned data.
buffer
N
N
first byte of the buffer, which is the first
byte of the parcel header of the first parcel.
In Locate Mode, Fetch Data Pointer is used by...
To...
applications
read (FET)
Fetch Maximum Data Length
Fetch Maximum Data Length is a four byte field that specifies the length in bytes of the move
area, if any, allocated by the application.
In this language...
The variable name for Fetch Maximum Data Length is...
COBOL
DBCAREA-FET-MAX-DATA-LEN
PL/I
FET_MAX_DATA_LEN
C
fet_max_data_len
IBM Assembler
DBFIFDL
This routine...
Does this for Fetch Maximum Data Length...
DBCHINI
writes
DBCHCL
reads (FET)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
95
Chapter 3: DBCAREA
Fetch Parcel Flavor
Fetch Maximum Data Length is used by...
To...
applications
write
Review the following conditions before calling DBCHCL for any of the following functions:
•
Connect
•
RunStartUp
•
Initiate with Protocol-Function
•
Command
•
Initiate Request
If an application is using Move Mode for processing the parcels in the response (that is, Locate
Mode is set to N and Parcel Mode Fetch is set to Y in the DBCAREA), then the application
must allocate the move area and place its length in Fetch Maximum Data Length.
If Maximum Data Length is set to...
Then the largest parcel body is...
O
32763
H
2,147,483,639
Whether Variable Length Fetch is set to N or Y, the length of the move area must be large
enough for the largest parcel body. If Variable Length Fetch is set to Y, two more bytes are
required for the preceding length field.
Fetch Parcel Flavor
Fetch Parcel Flavor is a four-byte field that is the flavor of the parcel containing the returned
data.
96
In this language...
The variable name for Fetch Parcel Flavor is...
COBOL
DBCAREA-FET-PARCEL-FLAVOR
PL/I
FET_PARCEL_FLAVOR
C
fet_parcel_flavor
IBM Assembler
DBFOPFLV
This routine...
Does this for Fetch Parcel Flavor...
DBCHINI
writes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Fetch Returned Data Length
This routine...
Does this for Fetch Parcel Flavor...
DBCHCL
writes (FET)
Fetch Parcel Flavor is used by...
To...
applications
read
After a fetch function completes and the application regains control with a return code of
zero, the application can obtain the flavor or type of parcel returned. This is true only if Parcel
Mode Fetch was set to Y in the DBCAREA when DBCHCL was called for any of the following
functions:
•
Connect
•
RunStartUp
•
Initiate with Protocol-Function
•
Command
•
Initiate Request
Fetch Returned Data Length
Fetch Returned Data Length is a four-byte field that specifies the length in bytes of the
returned data.
In this language...
The variable name for Fetch Returned Data
Length is...
COBOL
DBCAREA-FET-RET-DATA-LEN
PL/I
FET_RET_DATA_LEN
C
fet_ret_data_len
IBM Assembler
DBFOFDL
This routine...
Does this for Fetch Returned Data Length...
DBCHINI
writes
DBCHCL
writes (FET)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
97
Chapter 3: DBCAREA
Function
Fetch Returned Data Length is used by...
To...
applications
read
After a call to DBCHCL for the fetch function, an application 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 any of the following functions:
•
Connect
•
RunStartUp
•
Initiate Request
Table 5 shows how the location and meaning of “length” varies depending upon mode
settings.
Table 5: Length of Returned Data
Locate
Mode
Variable
Length
Parcel
Mode Fetch Fetch
Length of What?
Where Length is Provided
Y or N
Y
N
Parcel body
Fetch Returned Data Length
Y or N
Y
Y
Parcel body
The first two bytes at the
address in Fetch Data Pointer
Y
N
N
The grand total of all
parcels (headers and
bodies) in the response
buffer
Fetch Returned Data Length
Y
N
Y
Nothing. These settings
produce an error.
DBCHCL places Fetch Returned Data Length, if used, in the DBCAREA when the Fetch
function completes. Thus, Fetch Data Pointer is available when an application regains control
with a return code of zero from a call to DBCHCL for the Fetch function.
Function
Function is a four-byte field that is used by an application to specify the operation to be
carried out by DBCHCL. Each of the following codes represents a different operation:
98
Code
Operation
1
Connect
2
Disconnect
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Function
Code
Operation
3
RunStartUp
4
Initiate Request
5
Fetch
6
Rewind
7
Abort
8
End Request
11
Initiate With Protocol-Function
14
Command
15
ContinueRequest
In this language...
The variable name for Function is...
COBOL
DBCAREA-FUNC
PL/I
FUNC
C
func
IBM Assembler
DBCAFUNC
This routine...
Does this for Function...
DBCHINI
writes
DBCHCL
reads
Function is used by...
To...
applications
write
An application must set the Function field to the appropriate nonzero value before calling
DBCHCL. Use mnemonics for the codes. Mnemonics are provided in the language definition
file for the DBCAREA.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
99
Chapter 3: DBCAREA
Input CLIv2 Connection Id
Input CLIv2 Connection Id
The Input CLIv2 Connection Id is a four-byte field that specifies the session to be acted on by
DBCHCL.
In this language...
The variable name for Input CLIv2 Connection Id is...
COBOL
DBCAREA-I-SESS-ID
PL/I
I_SESS_ID
C
i_sess_id
IBM Assembler
DBCICONN
This routine...
Does this for Input CLIv2 Connection Id...
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; FET; REW; ERQ; ABT; DSC; CMD; IWPF; CRQ)
Input CLIv2 Connection
Id is used by...
To...
applications
write
Applications copy the value from Output CLIv2 Connection Id into Input CLIv2 Connection
Id. If an application uses the same DBCAREA to run sessions concurrently, it should save
Output CLIv2 Connection Id from each session logon.
Applications must store the appropriate value of Output CLIv2 Connection Id in Input CLIv2
Connection Id whenever then need the next DBCHCL call to affect a different session.
When DBCHCL is called for the RunStartUp, Command, Initiate with Protocol-Function, or
Initiate Request function, an implicit Connect function takes place first if Input CLIv2
Connection Id is zero.
Input CLIv2 Request Id
Input CLIv2 Request Id is a four-byte field that specifies the request to be acted on by
DBCHCL.
100
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Input TDP Path
In this language...
The variable name for Input CLIv2 Request Id is...
COBOL
DBCAREA-I-REQ-ID
PL/I
I_REQ_ID
C
i_req_id
IBM Assembler
DBCIREQN
This routine...
Does this for Input CLIv2 Request id...
DBCHINI
writes
DBCHCL
reads (FET; REW; ERQ; ABT; IWPF; CMD; CRQ)
Input CLIv2 Request Id is used by...
To...
applications
write
Applications copy the value that was placed by the Connect, RunStartUp, Initiate with
Protocol-Function, or Initiate Request function in Output CLIv2 Request Id into Input CLIv2
Request Id. If an application uses the same DBCAREA for more than one concurrent request
or more than one session, it should save the Output CLIv2 Request Id from each request‘s
submission.
Applications must store the appropriate value of Output CLIv2 Request Id in Input CLIv2
Request Id whenever they need the next DBCHCL call to affect a different request.
Input TDP Path
Input TDP Path is an eight-byte field that specifies the route to Teradata Database if it is not
specified (as TDpid) in the logon string.
In this language...
The variable name for Input TDP Path is...
COBOL
DBCAREA-I-DBCPATH
PL/I
I_DBCPATH
C
i_dbcpath
IBM Assembler
DBCNITDP
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
101
Chapter 3: DBCAREA
Keep Response
This routine...
Does this for Input TDP Path...
DBCHINI
writes
DBCHCL
reads (CON)
CON
Input TDP Path is used by...
To...
applications
write
The specified TDP identifier (TPpid) must only contain characters from the standard
EBCDIC character set. When DBCHCL is called for the Connect function, TDpid is obtained
from the logon string if one is provided and if it contains a TDpid. If TDpid is not available
from the logon string, then DBCHCL takes tdpid from Input TDP Path. If the first character
of Input TDP Path is hex 00 or 40, DBCHCL obtains TDpid from MVSTDP for z/OS in the
HSHSPB.
On z/OS, TDpid specifies the z/OS subsystem name, which must have the form TDPx, where
x is 0-9, A-Z (not case specific), $, #, or @. The first three characters must be TDP.
Keep Response
Keep Response is a one-byte field that specifies whether Teradata Database is to keep the spool
file after it sends the last parcel of the Teradata SQL response to the client.
Within an External Stored Procedure, a request initiated with the DBCAREA Return-result-to
option, a Keep-response setting of 'N' is not permitted. A setting of 'Y' indicates that the
results are non-scrollable so are positioned to the next unfetched row, with fetched rows not
propagated; while a setting of 'P' indicates that results are scrollable so the propagated results
are positioned to the last row fetched, with earlier fetched rows also propagated.
If the procedure used a multi-statement request (multiple SQL statements separated by
semicolons) to return results, the response to each of these requests is reflected. If the
procedure positioned to other than the first of these responses, the earlier ones are positioned
beyond the end of their rows. While scrollable results may be repositioned to these earlier
statement rows, non-scrollable results cannot.
102
In this language...
The variable name for Keep Response is...
COBOL
DBCAREA-KEEP-RESP
PL/I
KEEP_RESP
C
keep_resp
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Keep Response
In this language...
The variable name for Keep Response is...
IBM Assembler
DBOKRSP
This routine...
Does this for Keep Response...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; IWPF; CMD)
Keep Response is used by...
To...
applications
write.
Keep Response is initialized by DBCHINI to the default value provided for Keep Response in
the HSHSPB. When the value for Keep Response is not appropriate for the application, the
application should perform the following procedure before calling DBCHCL for any of these
functions:
•
RunStartUp
•
Initiate with Protocol-Function
•
Command
•
Initiate Request
1
Set Change Options to ‘Y‘.
2
Change the value for Keep Response as follows.
If the spool file is to...
Then change the value for
Keep Response to...
be retained by the Teradata Database even after the last parcel of
the Teradata SQL response has been sent to the client
Y
be discarded by the Teradata Database after the last parcel of the
Teradata SQL response has been sent
N
retain both the SQL response parcels and their original row
locations so that the client may reposition the response directly to
particular rows using Positioning-action
P
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
A call to DBCHCL for the Rewind function fails if Keep Response was N on the original
request. Keep Response is not directly tied to Open Requests. Even if Keep Response is set to
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
103
Chapter 3: DBCAREA
Language Conformance
N and the last parcel has been sent so that the Teradata Database discards the spool file, Open
Requests is not decremented.
Applications must still call DBCHCL for the End Request function in order to decrement
Open Requests and formally close the request, regardless of the setting of Keep Response, no
matter how much of the response an application has been sent, and regardless of the actual
state of the spool file.
Language Conformance
Language Conformance is a one-byte field that specifies whether SQL requests are to be
checked for conformance with a particular standard. When Language-conformance is
specified, Connect-type 'C' must also be specified.
In this language...
The variable name for Language Conformance is...
COBOL
DBCAREA-CONFORMANCE
PL/I
LANG_CONFORMANCE
C
lang_conformance
IBM Assembler
DBCNILCS
This routine...
Does this for Language Conformance...
DBCHINI
writes
DBCHCL
reads (CON)
Language Conformance is
used by...
To...
applications
write.
DBCHINI initializes Language Conformance to the default value provided for it in the
HSHSPB for your site. When the value for Language Conformance is not appropriate for an
application, perform the following procedure before calling DBCHCL for the connect
function.
104
1
Set Change Options to ‘Y‘.
2
Change the value for Language Conformance as follows.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Language Id
If conformance checking is to be done at this level...
Then change the
value for Language
Conformance to...
None
N
This is always acceptable.
Entry-level ANSI (FIPS 127-2).
2
If the Teradata Database does not support language conformance, it
rejects this selection.
Intermediate-level ANSI (FIPS 127-3).
3
If the Teradata Database does not support language conformance, it
rejects this selection.
Note: While the client software supports this conformance level, the
release 2 database software does not.
Language Id
Language Id is a four-byte field that specifies the language to be used for all CLIv2 error
messages returned in the Message Text DBCAREA field, and that were associated with the
session being connected. The value specifies a two-character Language Id.
If a language is commonly used in several countries, the Country Id can be used to select
messages that are unique to that country. The Language Id is defined by the ISO 639 standard.
The entire value is in EBCDIC, and both lowercase and uppercase characters are permitted.
In this language...
The variable name for Language Id is...
COBOL
DBCNILID
PL/I
DBCNILID
C
dbcniLid (case is significant)
IBM Assembler
DBCNILID
This routine...
Does this for Language Id. . .
DBCHINI
writes
DBCHCL
reads (CON)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
105
Chapter 3: DBCAREA
Language Id
Language Id is used by...
To...
applications
write
DBCHINI initializes the Language Id to the default value provided in the HSHSPB being
used. If the default value for Language Id is not appropriate for an application, perform the
following procedure before calling DBCHCL for the connect function:
106
1
Set Change Options to ‘Y‘.
2
Change the value for Language Id as follows:
If the language is...
Then set Language Id to...
Arabic
AR
Danish
DA
German
DE
Greek
EL
English
EN
Spanish
ES
Finnish
FI
French
FR
Hebrew
IW
Icelandic
IS
Italian
IT
Japanese
JA
Korean
KO
Dutch
NL
Norwegian
NO
Portuguese
PT
Romansh/Grishun
RM
Russian
RU
Swedish
SV
Thai
TH
Turkish
TR
Chinese
ZH
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Level
Messages are distributed in United States English (Language Id 'EN', optional Country Id
'US') only, although customers or Teradata Corporation in various countries can provide
additional languages.
The mechanism by which the CLIv2 error messages may be defined in other languages is
described in Chapter 13: “User-Defined Character Sets.”
If a message must be returned, but messages are not available in the specified language, then
the message number with fixed message text of '(REQUIRED MESSAGE TABLE IS NOT
AVAILABLE)' in United States English will be returned. For example, the message 'CLI0538
REQUEST REJECTED BY DELAY' would be presented as:
CLI0538 (REQUIRED MESSAGE TABLE IS NOT AVAILABLE)
Level
Level is a one-byte field that indicates the format of the DBCAREA:
•
Binary '0' indicates the initial level consisting of 384 bytes.
•
Binary '1': Indicates the current level consisting of 640 bytes.
Note: Level is returned by CLIv2, it is not set by applications.
In this language...
The variable name for Level is...
COBOL
DBCLEVEL
PL/I
DBCLEVEL
C
dbcLevel
IBM Assembler
DBCLEVEL
This routine...
Does this for Level...
DBCHINI
writes
Level is used by...
To...
application
reads
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
107
Chapter 3: DBCAREA
Locate Mode
Locate Mode
Locate Mode is a one-byte field that specifies where the data returned is to be made available.
In this language...
The variable name for Locate Mode is...
COBOL
DBCAREA-LOC-MODE
PL/I
LOC_MODE
C
loc_mode
IBM Assembler
DBOFLOC
This routine...
Does this for Locate Mode...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; CMD; CRQ)
Locate Mode is used by...
To...
applications
write.
Locate Mode is initialized by DBCHINI to the default value provided for Locate Mode in the
HSHSPB. When the value for Locate Mode is not appropriate for an application, perform the
following procedure before calling DBCHCL for Connect, RunStartUp, Command, or Initiate
Request functions:
1
Set Change Options to ‘Y‘.
2
Change the value for Locate Mode as follows.
If the data returned is to be...
Then change the value for Locate Mode to...
made available in the response buffer
Y
made available in the move area
N
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Within this manual, the following conventions apply:
108
•
Locate Mode of Y is known as Locate Mode.
•
Locate Mode of N with Parcel Mode Fetch of Y is known as Move Mode.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Logon Length
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, and Fetch Parcel Flavor.
Note: Variable Length Fetch and Locate Mode can be set to 'Y' at the same time.
When using Locate mode, applications should not change the data whose pointer is returned.
This data resides in the response buffer allocated and controlled by CLIv2 and altering it may
impact CLIv2 in unpredictable ways. Locate mode is provided as a performance option for
applications that need only inspect the data. Performance is improved by not copying the data
to the application's storage. But if the data must be modified, Locate mode should not be
used.
Logon Length
Logon Length is a four-byte field that is the length in bytes of the logon string.
In this language...
The variable name for Logon Length is...
COBOL
DBCAREA-LOGON-LEN
PL/I
LOGON_LEN
C
logon_len
IBM Assembler
DBCNILSL
This routine...
Does this for Logon Length...
DBCHINI
writes
DBCHCL
reads (CON)
Logon Length is used by...
To...
applications
write
The value of Logon Length must be positive, with an absolute maximum value (after removal
of any TDP identifier and delimiting slash) of one of the following:
•
32763, if Maximum Parcel is set to O
•
65531, if Maximum Parcel is set to H. Note however, that the actual maximum value is
based on the size of the longest logon string allowed, with that string encoded with the
character set that uses the most number of bytes per character. Currently, the maximum
value is 278 bytes.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
109
Chapter 3: DBCAREA
Logon Pointer
Calls to DBCHCL
Before a call to DBCHCL for the Connect function, applications set Variable Length Request
either to Y or N, with the following results:
When Variable
Length
Request is set
to...
Then...
Y
the Logon Length field is ignored and the Logon Pointer must point to the
two-byte area containing the length of the logon string, which is followed by the
actual logon string.
N
the application must supply the length information separately from the logon
string, in Logon Length.
For more information, see “Variable Length Request” on page 198.
Logon Pointer
Logon Pointer is a four-byte field that specifies the address of the logon string for a session.
110
In this language...
The variable name for Logon Pointer is...
COBOL
DBCAREA-LOGON-PTR
PL/I
LOGON_PTR
C
logon_ptr
IBM Assembler
DBCNILSP
This routine...
Does this for Logon Pointer...
DBCHINI
writes
DBCHCL
reads (CON)
Logon Pointer is used by...
To...
applications
write.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Logon Pointer
Calls to DBCHCL
Before calling DBCHCL for the Connect function, applications can build a logon string and
provide its address in Logon Pointer. A logon string has the following format:
[tdpid/]userid, password[, ‘acctid‘]
where:
Syntax element...
Is the ...
tdpid
TDP id, which is the name of the TDP to be used to reach the Teradata
Database.
Under z/OS, the tdpid is the subsystem name of the target TDP subsystem.
Unicode Delimited identifier (U&"..."), with or without Unicode escape
sequences (/nnnn), or the Teradata "..."XN notation may not be used for the
TDPid.
If only one character is specified, it is assumed to be an abbreviation for a four
character TDP identifier that begins with TDP, and the omitted characters are
supplied. Note that such abbreviation is deprecated, and its use is not
recommended.
userid
The userid on the corresponding Teradata Database.
The maximum length of userid is 30 characters and is not case-specific.
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 UTF16). Unicode Delimited identifier (U&"..."), with or without Unicode
escape sequences (/nnnn), or the Teradata "..."XN notation may not be used
for the TDPid. Therefore, the maximum length is 94 bytes.
Note that SQL terminal symbols (such as apostrophes) must always come
from the shortest repertoire, that is, single-byte, 2 for UTF16, unaccented
Latin characters, except for UTF16. Terminal symbols are never 3 bytes.
The dollar sign ($) is allowed anywhere in the userid.
password
The password on the corresponding Teradata Database.
At sites with an exit routine to add a password, the password may not be
required.
The maximum length of a password is 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 UTF16). Unicode Delimited identifier (U&"..."), with or without
Unicode escape sequences (/nnnn), or the Teradata "..."XN notation may not
be used for the TDPid. 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, single-byte unaccented Latin characters,
except for UTF16. Terminal symbols are never 3 bytes.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
111
Chapter 3: DBCAREA
Logon Pointer
Syntax element...
Is the ...
‘acctid‘
account id to be charged on the mainframe client.
The acctid may be omitted. If acctid is present, it may consist of as many as 30
characters, and it must be enclosed in apostrophes.
Each character may consist of 1, 2, or 3 bytes, depending on the character set
used.
If the acctid includes an apostrophe, that apostrophe must be preceded by an
apostrophe. Therefore, if the account string consists of 30 apostrophes, and is
encoded in UTF16 (2-byte terminal symbols), 124 bytes are necessary to
specify the field. Unicode Delimited identifier (U&"..."), with or without
Unicode escape sequences (\nnnn), or the Teradata "..."XN notation may not
be used for the TDPid.
The userid, password, and account name each consists of characters from the session
character set.
Any TDPid and delimiting slash consist of fixed-length characters from the session character
set. If the character set supports multi-byte characters, they cannot be used for this
information.
Multibyte Character Support
The following specifications apply to multibyte character sets.
Session Character Set
Specification
HANGULEBCDIC933_1II,
KANJIEBCDIC5026_0I,
KANJIEBCDIC5035_0I,
KATAKANAEBCDIC,
SCHEBCDIC935_2IJ, or
TCHEBCDIC937_3IB
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').
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.
Any TDP identifier and all delimiters (slash, commas, blanks,
quotation marks, apostrophes) must be specified as single-byte
characters.
Any TDP identifier and all delimiters (slash, commas, blanks,
quotation marks, apostrophes) must be specified as single-byte
characters.
HANGUL949_7R0,
HANGULKSC5601_2R4,
KANJI932_1S0,
KANJISJIS_0S,
SCHGB2312_1T0,
SCHINESE936_6R0,
TCHBIG5_1R0, or
TCHINESE950_8R0
112
Each character requires one or two bytes. Any TDP identifier and
all delimiters (slash, commas, blanks, quotation marks,
apostrophes) must be specified as single-byte characters.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Max-decimal-returned
Session Character Set
Specification
UTF8
Each character requires between one and three bytes. Any TDP
identifier and all delimiters (slash, commas, blanks, quotation
marks, apostrophes) must be specified as single-byte characters.
UTF16
Each character requires two bytes. Any TDP identifier and all
delimiters (slash, comma, blanks, quotation marks, apostrophes)
must be from the basic repertoire, that is, unaccented Latin
characters.
Logon Strings
Do not end the logon string with a semicolon.
A TDP exit routine that adds or modifies the logon string might have been created during
installation. If so, all or part of the logon string in the DBCAREA might be optional. For more
details, check with your system administrator.
Value of the Variable Length
Request.
Purpose of the Logon Pointer
N
Points to the beginning of the logon string.
Y
Points to the two-byte length field immediately preceding the logon
string.
User-defined or invalid character set names are treated as EBCDIC to parse the logon string
for the TDPid. For more information, see “Character Sets” on page 50 and “Character Set
Pointer” on page 78.
Max-decimal-returned
Max-decimal-returned specifies the maximum precision of DECIMAL values in a response
mode. The option is ignored for Field Response-mode. Max-decimal-returned exists only
when DBCHINI had been called for a DBCAREA with Total-length set to at least 640 (that is,
the returned DBCAREA Level value is at least 1). For a smaller DBCAREA, Max-decimalreturned is ignored.
Language
Returned Max-decimal-returned Value
COBOL
MAX-DECIMAL-RETURNED
PL/I
MAX_DECIMAL_RETURNED
C
maxDecimalReturned
IBM Assembler
DBRIMDR
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
113
Chapter 3: DBCAREA
Maximum Parcel
Routine.
Action for Max-decimal-returned
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
Max-decimal-returned is used by...
To...
applications
write.
Teradata Database rejects any value greater than the decimal precision value obtained using
the DBCHQE SQL-limits query. If Max-decimal-returned is omitted or specified as zero, the
client default of 18 is assumed, unless the HSHSPB MDR specification is used to specify a
different default.
Maximum Parcel
Maximum Parcel is a one-byte field that specifies whether the maximum parcel length is
32767 or the maximum size supported by the server, up to 2,147,483,647 bytes.
114
In this language...
The variable name for Maximum Parcel is...
COBOL
MAXIMUM-PARCEL
PL/I
MAXIMUM_PARCEL
C
maximum-parcel
IBM Assembler
DBCIMP
This routine...
Takes the action for Maximum Parcel...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; IWPF; CMD; CRQ)
Maximum Parcel is used by...
To...
applications
write.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Mechanism-data-encoding
Maximum Parcel is initialized to the default value provided for Maximum Parcel in the site‘s
HSHSPB. If the value is not appropriate for an application, the application can, before calling
DBCHCL for Connect, change the values as follows:
1
Set Change Options to 'Y'.
2
Change the value for Maximum Parcel as follows:
If...
Then change the value
for Maximum Parcel
to...
the original limit of 32767 is the maximum size of one parcel
O
if the higher limit of 2,147,483,647 bytes is the maximum size of one
parcel
H
Note: For new applications, Maximum-parcel=H should always be specified.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
A Maximum-parcel value of 'H' is required for a Response-buffer-length greater than 32767.
If the server requires a response buffer larger than 65535 bytes but Maximum-parcel is not set
to H, then an Error parcel with error code 3177 will be returned.
Mechanism-data-encoding
If additional data is required by the specified Mechanism-name, Mechanism-data-encoding
optionally specifies the character set of the area addressed by Mechanism-data-ptr. If
Mechanism-data-ptr is not specified, this option is validated but not otherwise processed.
While the data may be encoded in any supported session character set, if overridden by this
option, only UTF8 and UTF16 can be specified.
Mechanism-data-encoding exists only when DBCHINI had been called for a DBCAREA with
Total-length set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Mechanism-data-encoding is ignored.
Note: Logon mechanisms are currently not supported for a channel-connected system.
In this language...
The variable name for Mechanism-data-encoding is...
COBOL
MECHANISM-DATA-ENCODING
PL/I
MECHANISM_DATA_ENCODING
C
mechanismDataEncoding
IBM Assembler
DBCNIME
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
115
Chapter 3: DBCAREA
Mechanism-data-len
This routine...
Does this for Mechanism-data-encoding...
DBCHINI
writes
DBCHCL
reads (CON)
Mechanism-data-encoding is
used by...
To...
applications
write
One of the following numeric values can be set before establishing a connection:
Value Used
Mechanism-data-encoding Settings and Mneumonics
Session character set default
0
DBCNIMES ('DBC_MechCodingSession' for C,
SESSION for COBOL, DBC_MECH_CODING_SESSION for PL/I)
UTF8
3
DBCNIMET ('DBC_MechCodingUTF8' for C,
UTF8 for COBOL, DBC_MECH_CODING_UTF8 for PL/I)
Also, when UTF8 is specified, each character in Mechanismdata-ptr requires between one and three bytes.
UTF16
4
DBCNIME2 ('DBC_MechCodingUTF16' for C,
UTF16 for COBOL, DBC_MECH_CODING_UTF16 for PL/I)
Also, when UTF16 is specified, each character in Mechanismdata-ptr requires two bytes.
Mechanism-data-len
If additional data is required by the specified Mechanism-name, Mechanism-data-length
specifies the length, in bytes, of the area addressed by Logon-mechanism-data-pointer. If a
Mechanism-name is not specified, the value will be ignored.
Mechanism-data-len exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Mechanism-data-len is ignored.
Note: Logon mechanisms are currently not supported for a channel-connected system.
116
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Mechanism-data-ptr
In this language...
The variable name for Mechanism-data-length is...
COBOL
MECHANISM-DATA-LEN
PL/I
MECHANISM_DATA_LEN
C
mechanismDataLen
IBM Assembler
DBCNIMDL
This routine...
Does this for Mechanism-data-length...
DBCHINI
writes
DBCHCL
reads (CON)
Mechanism-data-length is
used by...
To...
applications
write
The value must be positive with a maximum value of:
•
32763 if the Maximum-parcel option is set to O, or
•
65531 if the Maximum-parcel option is set to H.
This field is ignored if Variable-length-request is set to Y, in which case
Logon-mechanism-data-pointer addresses a two-byte area containing the length of the data,
followed by the data itself.
Mechanism-data-ptr
If additional data is required by the specified Mechanism-name, Mechanism-data-ptr
addresses that data, specified in the character set specified by Mechanism-data-encoding. If
Variable-length-request is set to 'N', the data itself is addressed and its length is specified by
Mechanism-data-len. If Variable-length-request is set to 'Y', the data follows a two-byte field
that contains the length of the data (Mechanism-data-len is ignored). If a Mechanism-name is
not specified, the value will be ignored.
Mechanism-data-ptr exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Mechanism-data-ptr is ignored.
Note: Logon mechanisms are currently not supported for a channel-connected system.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
117
Chapter 3: DBCAREA
Mechanism-name
In this language...
The variable name for Mechanism-data-ptr is...
COBOL
MECHANISM-DATA-PTR
PL/I
MECHANISM_DATA_PTR
C
mechanismDataPtr
IBM Assembler
DBCNIMDP
This routine...
Does this for Mechanism-data-ptr...
DBCHINI
writes
DBCHCL
reads (CON)
Mechanism-data-ptr is used
by...
To...
applications
write
Mechanism-name
Mechanism-name specifies the name (in case-independent EBCDIC, left-justified, padded
with spaces) of the logon mechanism to authenticate the connection. A name is ignored if it
consists solely of spaces or binary zeroes. If required, additional data for the mechanism can
be supplied using the Mechanism-data-ptr and Logon-mechanism-data-length. If the
specified mechanism is not supported, the request will be rejected.
Mechanism-name exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Mechanism-name is ignored.
Note: Logon mechanisms are currently not supported for a channel-connected system.
118
In this language...
The variable name for Mechanism-name is...
COBOL
MECHANISM-NAME
PL/I
MECHANISM_NAME
C
mechanismName
IBM Assembler
DBCNIMNM
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Message Area Length
This routine...
Does this for Mechanism-name...
DBCHINI
writes
DBCHCL
reads (CON)
Mechanism-name is used
by...
To...
applications
write
Upon return from the Connect function, Mechanism-name contains the mechanism name
used, monocased as necessary.
Message Area Length
Message Area Length is a two-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. CLIv2 does not alter this value, so once set, it remains unless changed by
the application.
In this language...
The variable name for Message Area Length is...
COBOL
DBCIMSGM
PL/I
DBCIMSGM
C
dbciMsgM
IBM Assembler
DBCIMSGM
This routine...
Does this for Message Area Length...
DBCHINI
writes
DBCHCL
reads
Message Area Length is used
by...
To...
applications
write
If the Message Area Pointer is not specified, this value is ignored.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
119
Chapter 3: DBCAREA
Message Area Pointer
Message Area Pointer
Message Area Pointer is a four-byte field that specifies the address of an area into which any
error message will be placed when a non-zero return code occurs. The Message Area Length
field specifies the length of the addressed area. CLIv2 does not alter this value, so once set, it
remains unless changed by an application.
In this language...
The variable name for Message Area Pointer is...
COBOL
DBCIMSGP
PL/I
DBCIMSGP
C
dbciIMsgP
IBM Assembler
DBCIMSGP
This routine...
Does this for Message Area Pointer...
DBCHINI
writes
DBCHCL
reads
Message Area Pointer is used
by...
To...
applications
writes
An error message is returned when a CLIv2 routine that uses the DBCAREA ends with a nonzero return code. The message is 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 Message Area Pointer is not specified, the Message Text field contains the
message and Message Text Length returns the length of the message. If Message Area Pointer
is specified, the area addressed contains the message and Message Length returns the length of
the message.
If an error occurs while building the message, the Message Return Code field contains a CLIv2
return code. When this code is not zero, the text of the message may or may not be usable,
depending on the nature of the error.
The character set used to construct the message is indicated by Message Charset Used. The
session character set is always used if it is known, but if the error occurred before this
character set is known, the default CLIv2 character set is used.
120
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Message Charset Used
When a CLIv2 routine that uses the DBCAREA ends with a zero return code, any text from a
previous error is overwritten with spaces in the character set indicated by Message Charset
Used, and the length of the message is zeroed.
Message Charset Used
Message Charset Used is a one-byte field that indicates which character set was used to
construct the message. The value is returned by CLIv2; it is not set by an application.
In this language...
The variable name for Message Charset Used is...
COBOL
DBCOMSGC
PL/I
DBCOMSGC
C
dbcoMsgC
IBM Assembler
DBCOMSGC
This routine...
Does this for Message Charset Used...
DBCHINI
writes
DBCHCL
writes
Message Charset Used is used
by...
To...
applications
read
An EBCDIC 'S' indicates that the session character set when the request was issued was used
while a 'D' indicates that the default CLIv2 character set (EBCDIC) was used. The session
character set is always used if it is known, but if an error occurs before this character set is
known, the default CLIv2 character set is used.
Message Length
Message Length is the length in bytes of the message returned in the area addressed by
Message Area Pointer.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
121
Chapter 3: DBCAREA
Message Return Code
In this language...
The variable name for Message Length is...
COBOL
DBCOMSGL
PL/I
DBCOMSGL
C
dbcoMsgL
IBM Assembler
DBCOMSGL
This routine...
Does this for Message Length. . .
DBCHINI
writes
DBCHCL
writes
Message Length is used by...
To...
applications
read
If the Message Area Pointer is not specified, this value is not returned.
Message Return Code
Message Return Code is a two-byte field that is the CLIv2 return code for any error that
occurred while constructing the message. If no error occurs, binary zeroes are returned.
122
In this language...
The variable name for Message Return Code is...
COBOL
DBCOMSGR
PL/I
DBCOMSGR
C
dbcoMsgR
IBM Assembler
DBCOMSGR
This routine...
Does this for Message Return Code...
DBCHINI
writes
DBCHCL
writes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Message Text Length
Message Return Code is used
by...
To...
applications
read
Message Text Length
Message Text Length is a two-byte field that is the length in bytes of a message in Message
Text.
In this language...
The variable name for Message Text Length is...
COBOL
DBCAREA-MSG-LEN
PL/I
MSG_LEN
C
msg_len
IBM Assembler
DBCMSGL
This routine...
Does this for Message Text Length...
DBCHINI
writes
DBCHCL
writes
Message Text Length is used
by...
To...
applications
read
If the Message Area Pointer is specified, this value is not returned.
Message Text
Message Text is a 76-byte field that is the text of the message indicated by Return Code. The
language of the text is specified by the Language Id and the Country Id options
In this language...
The variable name for Message Text is...
COBOL
DBCAREA-MSG-TEXT
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
123
Chapter 3: DBCAREA
Open Requests
In this language...
The variable name for Message Text is...
PL/I
MSG_TEXT
C
msg_text
IBM Assembler
DBCMSG
This routine...
Does this for Message Text...
DBCHINI
writes
DBCHCL
writes
Message Text is used by...
To...
applications
read
An error message is returned when a CLIv2 routine that uses the DBCAREA ends with a nonzero return code. The message is 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 Message Area Pointer is not specified, the Message Text field contains the
message and Message Text Length returns the length of the message. If Message Area Pointer
is specified, the area addressed contains the message and Message Length returns the length of
the message.
If an error occurs while building the message, the Message Return Code field contains a CLIv2
return code. When this code is not zero, the text of the message may or may not be usable,
depending on the nature of the error.
The character set used to construct the message is indicated by Message Charset Used. The
session character set is always used if it is known, but if the error occurred before this
character set is known, the default CLIv2 character set is used.
If the character set requires more than one byte per character, it may exceed the size of
Message Text. Message Area Pointer may be used to provide a larger area for the message.
When a CLIv2 routine that uses the DBCAREA ends with a zero return code, any text from a
previous error is overwritten with spaces in the character set indicated by Message Charset
Used, and the length of the message is zeroed.
Open Requests
Open Requests is a four-byte field that specifies the DBCHCL count of the open requests in a
session.
124
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Open Requests
In this language...
The variable name for Open Requests is...
COBOL
DBCAREA-OPEN-REQS
PL/I
OPEN_REQS
C
open_reqs
IBM Assembler
DBROREQC
This routine...
Does this for Open Requests...
DBCHINI
writes.
DBCHCL
writes (CON; RSUP; IRQ; ERQ; IWPF; CMD)
Open Requests is used by...
To...
applications
read.
Open Requests Calculations
DBCHCL calculates the value of Open Requests as follows:
Open Request is the number of calls to DBCHCL for Connect function
+
the number of calls to DBCHCL for RunStartUp function
+
the number of calls to DBCHCL for Initiate Request function
+
the number of calls to DBCHCL for Initiate with Protocol-Function function
+
the number of calls to DBCHCL for Command function
–
the number of calls to DBCHCL for End Request function
Note: The calculation does not keep track of End Request parcels as received by the client nor
does it keep track of the return code from the call to DBCHCL.
The application must explicitly close a request with an End Request function in order to have
Open Requests decremented.
Miscellaneous Notes
Open Requests is a count of requests that have not been ended. These requests do not
necessarily still have spool files.
As long as the application keeps Open Requests less than or equal to 16, the number of spool
files on the Teradata Database will be less than or equal to 16.
The Teradata Database allows no more than 16 spool files at one time per session.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
125
Chapter 3: DBCAREA
Output CLIv2 Connection Id
For optimal performance, the application should operate so that Open Requests is no more
than 16.
You should program your applications to close requests explicitly with a call to DBCHCL for
the End Request function as soon as the response generated by the request is no longer
needed.
DBCHCL updates Open Requests in the DBCAREA as soon as DBCHCL is called for a
request-generating function.
Open Requests is available after the application regains control from DBCHCL, even for a
connect operation.
Output CLIv2 Connection Id
Output TDP Path is an eight byte field that specifies the route used to send session data to and
from the Teradata Database. On channel-attached systems, this is the TDPid. This
information is also available using the Database-access-path DBCHQE query.
In this language...
The variable name for Output CLIv2 Connection Id is...
COBOL
DBCAREA-O-SESS-ID
PL/I
O_SESS_ID
C
o_sess_id
IBM Assembler
DBCOCONN
This routine...
Does this for Output CLIv2 Connection Id...
DBCHINI
writes
DBCHCL
writes (CON)
Output CLIv2 Connection Id is
used by...
To...
applications
read
After the application regains control from a call to DBCHCL for the Connect function, the
logical session id is available in the DBCAREA in Output CLIv2 Connection Id.
Before using the DBCAREA again to call DBCHCL for the session, the application must copy
the value to Input CLIv2 Connection Id.
Compare with “Output TDP Session Id” on page 129.
126
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Output CLIv2 Request Id
Note that both the TDP and CLIv2 have a number for each session, and that the two numbers
are not identical.
Output CLIv2 Request Id
Output CLIv2 Request Id is a four byte field that is the CLIv2 logical identifier for a given
request on the Teradata Database.
In this language...
The variable name for Output CLIv2 Request Id is...
COBOL
DBCAREA-O-REQ-ID
PL/I
O_REQ_ID
C
o_req_id
IBM Assembler
DBCOREQN
This routine...
Does this for Output CLIv2 Request Id...
DBCHINI
writes
DBCHCL
writes (CON; RSUP; IRQ; IWPF; CMD)
Output CLIv2 Request Id is
used by...
To...
applications
read
When the application regains control from a call to DBCHCL for any of the following
functions, the logical request is available in the DBCAREA in Output CLIv2 Request id.
•
Connect
•
RunStartUp
•
Command
•
Initiate with Protocol-Function
•
Initiate Request
Before using the DBCAREA again to call DBCHCL for an operation related to that request,
the application must copy the value to Input CLIv2 Request Id.
Compare with “TDP Request Number” on page 169.
Note that CLIv2 and the TDP have a number for each request and that the numbers are not
identical.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
127
Chapter 3: DBCAREA
Output Host Id
Output Host Id
Output Host Id is a two-byte field that specifies the host id for a database configuration of
related resources. It is provided for diagnostic purposes, audit logs, and so forth.
In this language...
The variable name for Output Host Id is...
COBOL
DBCAREA-O-HOST-ID
PL/I
O_HOST_ID
C
o_host_id
IBM Assembler
DBCOSILH
This routine...
Does this for Output Host Id...
DBCHINI
writes
DBCHCL
writes (FET) associated with connect operation
Output Host Id is used by...
To...
applications
read.
Output Host Id is available in the DBCAREA when the application regains control (with
return code zero) from calling DBCHCL for the first Fetch function 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 TDP Path
Output TDP Path is an eight byte field that specifies the route used to send session data to and
from the Teradata Database.
It is provided for diagnostic purposes, audit logs, and so forth.
128
In this language...
The variable name for Output TDP Path is...
COBOL
DBCAREA-O-DBCPATH
PL/I
O_DBCPATH
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Output TDP Session Id
In this language...
The variable name for Output TDP Path is...
C
o_dbcpath
IBM Assembler
DBCOSID
This routine...
Does this for Output TDP Path...
DBCHINI
writes
DBCHCL
writes (FET) associated with connect operation
Output TDP Path is used by...
To...
applications
read
After regaining control from a call to DBCHCL for the Connect function, the application can
obtain the route used from Output TDP Path.
Output TDP Path contains the name of the TDP used for the session, the TDP-assigned
session number, and your Teradata Database’s host id.
Output TDP Path is available in the DBCAREA when the application regains control, with
return code zero, from calling DBCHCL for the first Fetch function that is associated with the
connect operation.
Output TDP Session Id
Output TDP Session Id is a four byte field that is the actual, not logical, identifier assigned to
the session by TDP.
It is provided for diagnostic purposes, audit logs, and so on.
In this language...
The variable name for Output TDP Session Id is...
COBOL
DBCAREA-O-DBC-SESS-ID
PL/I
O_DBC_SESS_ID
C
o_dbc_sess_id
IBM Assembler
DBCOSISN
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
129
Chapter 3: DBCAREA
Parcel Mode Fetch
This routine...
Does this for Output TDP Session Id...
DBCHINI
writes
DBCHCL
writes (FET) associated with connect operation
Output TDP Session Id is used
by...
To...
applications
read
Output TDP Session Id is available in the DBCAREA after the application regains control
from a call to DBCHCL for the first Fetch function associated with the connect.
Compare with “Output CLIv2 Connection Id” on page 126.
Parcel Mode Fetch
Parcel Mode Fetch is a one byte field that specifies whether fetches are to provide the next
parcel or the next buffer full of returned data.
In this language...
The variable name for Parcel Mode Fetch is...
COBOL
DBCAREA-PARCEL-MODE
PL/I
PARCEL_MODE
C
parcel_mode
IBM Assembler
DBOBTPM
This routine...
Does this for Parcel Mode Fetch...
DBCHINI
writes.
DBCHCL
reads (CON; RSUP; IRQ; IWPF; CMD; CRQ)
Parcel Mode Fetch is used by...
To...
applications
write
Buffer Mode is not allowed with either Variable Length Fetch or Move Mode (that is, Move
Mode can only move one parcel at a time).
130
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Period-as-Struct
If buffer Mode is in effect, each fetch results in a new buffer full of parcels. It is assumed that
the application has processed the previous buffer full of parcels. Whether any of the parcels
have the alternate header depends upon the Request-mode and Request-parcel-format
options. To prevent an unexpected alternate parcel header in a returned buffer, CLIv2 will not
use the alternate header if Request-mode=P and Parcel-mode-fetch=N are both specified.
Once the application is adjusted to support the alternate header in a response buffer,
Request-parcel-format=A may be specified to allow CLIv2 to use the alternate header if
possible.
Parcel Mode Fetch is initialized by DBCHINI to the default value provided for Parcel Mode in
the HSHSPB. If the value provided is not appropriate for the application, the program may set
Change Options to Y and change Parcel Mode Fetch to either of the following:
If...
Then set Parcel Mode to...
the application wants each fetch to provide the next parcel
Y
the application wants each fetch to provide the next buffer full of
parcels
N
before calling DBCHCL for any of these functions:
•
Connect
•
RunStartUp
•
Command
•
Initiate with Protocol-Function
•
Initiate Request
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Period-as-Struct
Period-as-Struct is a one byte EBCDIC 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.
In this language...
The variable name for Period-as-Struct is...
COBOL
PERIOD-AS-STRUCT
PL/I
PERIOD-AS-STRUCT
C
PERIOD-AS-STRUCT
IBM Assembler
DBRIPAS
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
131
Chapter 3: DBCAREA
Positioning-action
This routine...
Does this for Period-as-Struct...
DBCHINI
writes.
DBCHCL
reads (RSUP; IRQ; IWPF)
Period-as-Struct is used by...
To...
applications
write.
One of the following values may be set before initiating a request: 'N' (DBRIPASN for
Assembler, DBC_periodAsStructNo for C, DBC-NO for COBOL,
DBC_PERIOD_AS_STRUCT_NO for PL/I), indicates that Period data types are treated as
simple data types. 'Y' (DBRIPASY for Assembler, DBC_periodAsStructYes for C, DBC-YES
for COBOL, DBC_PERIOD_AS_STRUCT_YES for PL/I) indicates that Period data types are
treated as Structured UDTs in honoring the Transforms-off option.
The default setting is "N".
Positioning-action
Positioning-action specifies the position in the response from which the Fetch is to be
performed.
In this language...
The variable name for Positioning-action is...
COBOL
DBFIPACT
PL/I
DBFIPACT
C
dbfiPAct
IBM Assembler
DBFIPACT
This routine...
Does this for Positioning-action...
DBCHINI
writes.
DBCHCL
reads.
FET
132
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Positioning-statement-number
Positioning-action is used by...
To...
applications
write.
One of the following values may be set before calling the Fetch function:
To...
Set Positioning-action
fetch the next parcel (default).
U
fetch the first parcel in the row number specified by Positioning-value for the
statement specified by Positioning-statement-number.
T
fetch bytes in the Binary Large Object (BLOB) beginning at the byte offset
specified by Positioning-value for the statement specified by Positioningstatement-number. This may be done only if a single BLOB was selected
using a locator.
2
fetch characters in the Character Large Object (CLOB), beginning at the
character offset specified by Positioning-value for the statement specified by
Positioning-statement-number. This may be done only if a single CLOB was
selected using a locator.
3
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
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 is
honored whatever the setting of Change-option.
Positioning-statement-number
Positioning-statement-number specifies the statement number from which the Fetch is to be
performed when Positioning-action indicates other than Next-parcel.
A request can consist of multiple statements, each of which contributes to the response. The
first statement is numbered one and any subsequent statements are assigned subsequent
ascending integers.
Successful response parcels for each statement begin with either a Success, OK, or
ResultSummary parcel and end with an EndStatement parcel, both of which contain the
statement number. For unsuccessful statements, the Error or Failure parcel contains the
statement number.
In this language...
The variable name for Positioning-statement-number is...
COBOL
DBFIPSNM
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
133
Chapter 3: DBCAREA
Positioning-value
In this language...
The variable name for Positioning-statement-number is...
PL/I
DBFIPSNM
C
dbfiPSNm
IBM Assembler
DBFIPSNM
This routine...
Does this for Positioning-statement-number...
DBCHINI
writes
DBCHCL
reads (FET)
Positioning-statement-number is
used by...
To...
applications
write
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
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, OK, or ResultSummary). 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 or ResultSummary, Data-information-extended, and No-operation
parcels before the Multipart-record parcel for the start of the data.
134
In this language...
The variable name for Positioning-value is...
COBOL
DBFIPVAL
PL/I
DBFIPVAL
C
dbfiPVal
IBM Assembler
DBFIPVAL
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Protocol-Function
This routine...
Does this for Positioning-value...
DBCHINI
writes
DBCHCL
reads (FET)
Positioning-value is used by...
To...
applications
write
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.
Protocol-Function
Protocol-Function is a one byte field that specifies the 2PC optimizations that are being used.
This feature requires one of the following Teradata software releases:
•
Teradata Database for UNIX version 2 release 2 (or later)
•
Teradata DBS for TOS version 1 release 5 (or later)
In this language...
The variable name for Protocol-Function is...
COBOL
DBCAREA-IWPF-FUNCTION
PL/I
IWPF_FUNCTION
C
iwpf_function
IBM Assembler
DBRIPF
This routine...
Does this for Protocol-Function...
DBCHINI
writes
DBCHCL
reads (IWPF)
Protocol-Function is used by...
To...
applications
write
You can set the following in IWPF:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
135
Chapter 3: DBCAREA
Refresh-cached-data
M...
Then set Protocol-Function to
no Protocol-Function is used
'N'
vote is to be appended
'V'
vote and terminate is to be appended
'T'
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Refresh-cached-data
Refresh-cached-data specifies whether response data previously processed by CLIv2 can be reused or must be reread from the Teradata Database.
Refresh-cached-data exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Refresh-cached-data is ignored.
In this language...
The variable name for Refresh-cached-data is...
COBOL
DBRIRCD
PL/I
DBRIRCD
C
dbriRCD
IBM Assembler
DBRIRCD
This routine...
Does this for Refresh-cached-data...
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
Refresh-cached-data is
used by...
To...
applications
write
One of the following values may be set before initiating a request:
136
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Request Buffer Length
If the previously processed response...
Then set Refresh-cached-data to...
indicates that response data previously
processed by CLIv2 can be re-used (default)
'N'
indicates that response data previously
processed by CLIv2 must be reread from the
Teradata Database.
'Y'
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Request Buffer Length
Request Buffer Length is a four byte field that specifies the desired length of the buffer in
which requests are placed for sending to the Teradata Database.
In this language...
The variable name for Request Buffer Length is...
COBOL
DBCAREA-REQ-BUF-LEN
PL/I
REQ_BUF_LEN
C
req_buf_len
IBM Assembler
DBCIRBRL
This routine...
Does this for Request Buffer Length...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; IWPF; CMD; CRQ)
Request Buffer Length is used
by...
To...
applications
write
The value of zero indicates that DBCHCL is to use the default value from the HSHSPB for the
Request Buffer Length.
The application may change the value in Request Buffer Length. The minimum value is 256,
and the maximum value is 2147483647.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
137
Chapter 3: DBCAREA
Request Length
When less than the maximum is specified, CLIv2 increases the size of the request buffer as
needed.
Note: The maximum size request that can be specified for the Initiate Request function is 10,
12, or 24 bytes less than this buffer size, depending on support by the server. These bytes are
used by CLIv2 to add a parcel header and a Respond-type parcel.
Request Length
Request Length is a four byte field that is the length (in bytes) of the request string.
In this language...
The variable name for Request Length is...
COBOL
DBCAREA-REQ-LEN
PL/I
REQ_LEN
C
req_len
IBM Assembler
DBRIRQL
This routine...
Does this for Request Length...
DBCHINI
writes
DBCHCL
reads (IRQ; CMD; IWPF; CRQ)
Request Length is used by...
To...
applications
write.
When Request Mode is set to...
Then...
B
CLIv2 does not validate the length further
P
If the maximum parcel is set to O, the maximum value is
approximately 32763.
If the maximum parcel is set to H, the maximum value is
approximately 65531.
The actual maximum may vary slightly with the version of the Teradata Database being used,
but may be obtained using the DBCHQE CLIv2-limits query.
When sending segments of a stored procedure (refer to Chapter 17: “Stored Procedures” for
details), the actual maximum may vary slightly with the version of the Teradata Database
138
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Request Mode
being used; the value may be obtained using the DBCHQE CLIv2-limits query (or the
deprecated Maximum-segment-size query).
When using the Continue-request function, the total size of a large object may be obtained
using the DBCHQE SQL-limits query.
Setting Up the Call to DBCHCL
The following applies to setting the value for Variable Length Request prior to making a call to
DBCHCL.
If the
application
sets Variable
Length
Request to...
Then the ...
Y
Request Length field is ignored and the Request Pointer must point to the two-byte
area containing the length of the request string, which is followed by the actual
request string.
N
application must supply the length information separately from the request string,
in Request Length. See “Variable Length Request” on page 198.
Request Mode
Request Mode is a one byte field that specifies the form that a request and optional data are
passed from the application to CLIv2.
In this language...
The variable name for Request Mode is ...
COBOL
DBCAREA-REQUEST-MODE
PL/I
REQUEST_MODE
C
request_mode
IBM Assembler
DBOQMOD
This routine...
Does this for Request Mode...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IEPF; CRQ)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
139
Chapter 3: DBCAREA
Request-parcel-format
Request Mode is used by
To...
applications
write
Request Mode is initialized to the default value provided for Request Mode (IBOQMOD) in
the HSHSPB.
When the value for Request Mode is not appropriate for the application, you should perform
the following procedure before calling DBCHCL for the Initiate Request function:
1
Set Change Options to ‘Y‘.
2
Change the value for Request Mode as follows.
If the application is passing to CLIv2...
Then change the
value for Request
Mode to...
the Request parcel body and, optionally, the Using Data parcel body and
parcel elements in a DBCAREA extension
P
a pre-built buffer containing parcels
B
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
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. If any of the request parcels have the alternate parcel header then any of the
response parcels may also have the alternate header. If the response requires use of the
alternate header because the size of the parcel body will exceed 65535 bytes, then at least one
of the request parcels built by the application must use the alternate header.
Note: The parcels included are 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 of the defined protocols of Teradata, such as FastLoad, Hut, and
MultiLoad. It is not recommended for use in Teradata sessions.
Variable Length Request Mode is supported with Buffer Mode Request Mode.
Request Mode is read by the call to DBCHCL for the connect and runstartup options and
stored in the appropriate control blocks, but it is not used during either function.
Request-parcel-format
Request-parcel-format specifies whether CLIv2 uses alternate parcel headers to build request
parcels when supported by the server.
140
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Request-parcel-format
The following table describes the Request-parcel-format variable.
In this language...
The variable name for Request-parcel-format is...
COBOL
DBRIRPF
PL/I
DBRIRPF
C
dbriRPF
IBM Assembler
DBRIRPF
This routine...
Does this for Request-parcel-format...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; IWPF)
Request-parcel-format is used
by...
To...
applications
write
Set one of the following values before calling the Fetch function:
If Request-parcel-format is set
to...
Then Request-parcel-format...
'A'
allows CLIv2 to use whichever parcel header is supported by
the server.
'D'
('D' is a deprecated value now treated as 'A')
'O'
forces use of original parcel headers
Note: For new applications, Request-parcel-format should always be set to ‘A‘.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
141
Chapter 3: DBCAREA
Request Pointer
Request Pointer
Request Pointer is a four byte field that specifies the address of the request string.
In this language...
The variable name for Request Pointer is...
COBOL
DBCAREA-REQ-PTR
PL/I
REQ_PTR
C
req_ptr
IBM Assembler
DBRIRQP
This routine...
Does this for Request Pointer...
DBCHINI
writes
DBCHCL
reads (IRQ; IWPF; CMD; CRQ)
Request Pointer is used by...
To...
applications
write
Before calling DBCHCL for the Initiate Request function, the application must build a request
string, such as a Teradata SQL request.
If Variable Length Request is
set to...
Then Request Pointer must contain the address of...
N
the beginning of the request string.
Y
the two-byte length field immediately preceding the request string
(see “Variable Length Request” on page 198).
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.
Request Pointer and the Using row descriptor
If a USING row descriptor is included in the Teradata SQL request, the USING row descriptor
must be the very first clause in the request.
142
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Request Processing Option
The USING row descriptor 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. The maximum number of fields may
be obtained using the DBCHQE SQL-limits query.
An example of a valid request follows:
USING x1 (INTEGER), x2 (CHAR (2) )
SELECT * FROM t1 WHERE c1 = :x2;
SELECT * FROM t2 WHERE c2 = :x2;
The USING row descriptor is also used for macro arguments, as in the following example:
USING x1 (INTEGER) EXEC MACRO (:x1);
For more information about the nature of the USING row descriptor and where it is placed in
relation to other information, see SQL Fundamentals.
Request Processing Option
Request Processing Option is a one byte field that specifies whether the Teradata Database is
to return the data described in the request string or return information about the data
described in the request string.
In this language...
The variable name for Request Processing Option is...
COBOL
DBCAREA-REQ-PROC-OPT
PL/I
REQ_PROC_OPT
C
req_proc_opt
IBM Assembler
DBOFUNT
This routine...
Does this for Request Processing Option...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IWPF; CMD; IRQ)
Request Processing Option is
used by...
To...
applications
write
Request Processing Option is initialized by DBCHINI to the default value provided for
Request Processing Option in the HSHSPB.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
143
Chapter 3: DBCAREA
Request Processing Option
When the value for Request Processing Option is not appropriate for the application, you
should perform the following procedure before calling DBCHCL for the Connect,
RunStartUp, Command, Initiate with Protocol-Function, or Initiate Request function:
1
Set Change Options to ‘Y‘.
2
Change Request Processing Option as follows:
If the Teradata Database is to...
Then change the
value for Request
Processing Option
to...
execute the request and send back the returned data
E
Analyze each statement in the request. The statements may not contain
parameterized SQL.
P
If the request is valid, the Teradata Database will send back a time
estimate and format information about the data that it would return if
the request were executed.
Note that the time estimate is the same as EXPLAIN returns.
Analyze each statement in the request. The statements may contain
parameterized SQL. If the request is valid, the Teradata Database 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.
S
Analyze each statement in the request, then execute the request. The
statements may contain parameterized SQL. If the request is valid, the
Teradata Database 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. Note that
the time estimate is the same as EXPLAIN returns.
B
The difference between "P" and "S" is that "P" does not support parameterized SQL while "S"
does.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
If the request is not valid, the Teradata Database sends back an Error or Failure parcel, the
same as if Request Processing Option is set to E.
If "S" or "B" is specified but the Teradata Database does not support that option, a Failure
parcel with error code 3749 will be returned.
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.
144
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Request-token
Request-token
Request-token is a four byte field that is used to specify a user-defined identifier for the
request.
In this language...
The variable name for Request-token is...
COBOL
DBCAREA-Request-token
PL/I
Request-token
C
Request-token
IBM Assembler
DBCIURQN
This routine...
Does this for Request-token...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IWPF; CMD; IRQ)
DBCHWAT
uses
Request-token is used by...
To...
applications
write
Request-token is maintained for each request and is returned by DBCHWAT when a pending
request has completed its transfer.
At the discretion of the application programmer, Request-token may be used in whatever way
is useful.
Request-token is primarily used by applications running concurrent requests or sessions,
most often to index into or point to some application-maintained request context so that an
actual request id and session id can be retrieved for later calls to fetch, rewind, abort, or end a
request.
Response Buffer Length
Response Buffer Length is a four byte field that specifies the desired length of the buffer in
which responses received from the Teradata Database are made available to the application.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
145
Chapter 3: DBCAREA
Response Mode
In this language...
The variable name for Response Buffer Length is...
COBOL
DBCAREA-RESP-BUF-LEN
PL/I
RESP_BUF_LEN
C
resp_buf_len
IBM Assembler
DBCIFBRL
This routine...
Does this for Response Buffer Length...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IWPF; CMD; IRQ; CRQ)
Response Buffer Length is
used by...
To...
applications
write
The value of zero indicates that DBCHCL is to use the default value from the HSHSPB bytes
for the Response Buffer Length.
The application may change the value in Response Buffer Length. The minimum value is 256.
The maximum value is approximately. . .
If Maximum Parcel is set to...
32767
O
65535
H
2,147,483,639
H, and the Teradata Database supports
ExtendedRespond, as indicated by the DBCHQE
Extended-response-support query.
The actual maximum may vary slightly with the version of the Teradata Database being used;
the value may be obtained using the DBCHQE CLIv2-limits query.
If Two Response Buffers in the DBCAREA is set to ‘Y‘, each response buffer is the specified
size.
Response Mode
Response Mode is a one byte field that specifies the mode in which data is to be packaged by
the Teradata Database for return to the client.
146
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Response Mode
When MultipartIndicator Response-mode is selected, the Continued-characters-state option
is also be relevant.
In this language...
The variable name for Response Mode is...
COBOL
DBCAREA-RESP-MODE
PL/I
RESP_MODE
C
resp_mode
IBM Assembler
DBORMOD
This routine...
Does this for Response Mode...
DBCHINI
writes
DBCHCL
reads (CON; RSPF; IWPF; IRQ)
Response Mode is used by...
To...
applications
write
Response Mode is initialized by DBCHINI to the default value provided for Response Mode
in the HSHSPB.
When the value for Response Mode is not appropriate for the application, you should
perform the following procedure before calling DBCHCL for any of the following functions:
When the value for Response Mode is not appropriate for the application, you should
perform the following procedure before calling DBCHCL for Connect, RunStartUp, Initiate
with Protocol-Function, or Initiate Request:
1
Set Change Options to ‘Y‘.
2
Change the value for Response Mode as follows.
Note: Unless a new application must support old versions of the Teradata Database,
which would reject its use, Response-mode should always be set to ‘M‘. The CLIv2 Query
routine QEPILOB (or QEPIASL) can be used to ascertain if the server supports this
enhancement.
If the response is to be packaged in this mode...
Then change the value for Response Mode
to...
Field
F
Record
R
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
147
Chapter 3: DBCAREA
Result-sets-OK
If the response is to be packaged in this mode...
Then change the value for Response Mode
to...
MultipartIndicator
M
Indicator
I
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Result-sets-OK
Result-sets-OK is a one byte EBCDIC field that indicates whether SQL results selected by SQL
or External Stored Procedures may be propagated to the application.
Result-sets-OK exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Result-sets-OK is ignored.
In this language...
The variable name for Result-sets-OK is...
COBOL
RESULT-SETS-OK
PL/I
RESULT_SETS_OK
C
resultSetsOK
IBM Assembler
DBRIRSO
This routine. . .
Does this for Result-sets-OK. . .
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
Result-sets-OK are used by. . .
To...
applications
write
One of the following values may be set before initiating a request:
148
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Return Code
If...
Then set Connect Type to...
indicates that a new connection is established.
'N'
• DBRIRSON for
Assembler
• DBC_RsltSetsNo for C
• DBC-NO for COBOL
• DBC_RSLT_SETS_NO
for PL/I
indicates that the connection used to call the procedure is
used.
'Y'
•
•
•
•
DBRIRSOY for Assembler
DBC_RsltSetsYes for C
DBC-YES for COBOL
DBC_RSLT_SETS_YES
for PL/I
If not specified, the default from the HSHSPB is used, which as distributed is "N". This default
is provided to allow the possible return of results from a procedure in diagnostic situations.
The procedure could always attempt to return diagnostic information but this information is
received by the application only if the HSHSPB default is changed. If such use is envisioned,
the application should allow for the ResultSet parcel and data even though it is not expected
under normal circumstances.
For details on External Stored Procedures, refer to Chapter 17: “Stored Procedures.”
Return Code
Return Code is a four byte field that specifies the state of the call as known by DBCHCL and
TDP.
In this language...
The variable name for Return Code is...
COBOL
DBCAREA-RETURN-CD
PL/I
RETURN_CD
C
return_cd
IBM Assembler
DBCRCODE
This routine...
Does this for Return Code...
DBCHINI
writes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
149
Chapter 3: DBCAREA
Return-identity-data
This routine...
Does this for Return Code...
DBCHCL
writes
Return Code is used by...
To...
applications
read
Applications should access the return code using a more reliable method than using the
Return Code in the DBCAREA.
Some recommended options include the following:
•
Use the Assembler register 15 (the most direct method for getting the return code).
•
Include a parameter in the call itself, in which the return code will be placed (note that if
CLIv2 cannot access this parameter, the return code will not be placed in it).
After regaining control from DBCHCL, the application can use the Return Code as the first
indicator (initial status) of the success of the call, from the point of view of CLIv2 and the
TDP.
For more information on return codes, see “Return Code” on page 149.
Return-identity-data
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 the
'GENERATED ... AS IDENTITY' SQL syntax.
150
In this language...
The variable name for Return-identity-data is...
COBOL
RETURN-IDENTITY-DATA
PL/I
RETURN_IDENTITY_DATA
C
returnIdentityData
IBM Assembler
DBRIRID
This routine...
Takes this action for Return-identity-data...
DBCHINI
writes
DBCHCL
reads (IRQ; RSUP; IWPF)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Return-objects-as
Return-identity-data is used by...
To...
applications
write
One of the following values may be set before initiating a request:
If Return-identity-data is set to...
Then Return-identity-data...
'N'
indicates that no fields are returned.
'C'
indicates that the values for any Identity columns is
returned.
'R'
indicates that the values for all fields in an inserted row
that contains Identity columns are returned.
Note: If not specified, "N" is assumed.
Return-objects-as
Return-objects-as specifies how large objects are to be returned to the application. The value
indicates whether the actual data is returned or simply locators to the actual data.
In this language...
The variable name for Return-objects-as is...
COBOL
DBRIROB
PL/I
DBRIROB
C
dbriROb
IBM Assembler
DBRIROB
This routine...
Takes this action for Return-objects-as...
DBCHINI
writes
DBCHCL
reads (IRQ; RSUP; IWPF)
Return-objects-as is used by...
To...
applications
write
Return-objects-as is initialized to the default value provided in the site's HSHSPB.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
151
Chapter 3: DBCAREA
Return-statement-info
If the default is not appropriate for the
application...
Set Change-options to...
before calling DBCHCL for the Initiate,
Initiate With Protocol-function, or Run
Startup function.
'Y'
data
'D'
transaction-related locator
'T'
spool-related locator
'S'
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Return-statement-info
Return-statement-info specifies whether StatementInformation response parcels may be
returned instead of DataInfo[X] or PrepInfo[X] response parcels. The Teradata Database will
reject use of this option in Response-mode 'F' (Field mode).
In this language...
The variable name for Return-statement-info is...
COBOL
RETURN-STATEMENT-INFO
PL/I
RETURN_STATEMENT_INFO
C
returnStatementInfo
IBM Assembler
DBRIRSI
This routine...
Takes this action for Return-statement-info...
DBCHINI
writes
DBCHCL
reads (IRQ; RSUP; IWPF)
Return-statement-info is used by...
To...
applications
write
One of the following values may be set before initiating a request:
152
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Return-result-to
If Return-statement-info is set to...
Then Return-statement-info...
'N'
indicates that StatementInformation response parcels
may not be used.
'Y'
indicates that StatementInformation response parcels
may be used.
Note: If not specified, "N" is assumed.
Return-result-to
Return-result-to is a one byte unsigned integer that an External Stored Procedure calling
CLIv2 may provide 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 requesting procedure, the caller of
the procedure, or the application. If propagated to the caller or application, the parcels are
preceded by a ResultSet response parcel.
Return-result-to exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Return-result-to is ignored.
In this language...
The variable name for Return-result-to is...
COBOL
RETURN-RESULT-TO
PL/I
RETURN_RESULT_TO
C
returnResultTo
IBM Assembler
DBRIRR
This routine. . .
Does this for Return-result-to. . .
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
Return-result-to are used by. . .
To...
applications
write
One of the following values may be set before initiating a request:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
153
Chapter 3: DBCAREA
Return Time
If...
Then set Connect Type to...
indicates that the results are returned only the
procedure making the request.
'1'
indicates that the results are returned only to the
application invoking a procedure.
'2'
indicates that the results are return only to the
procedure caller.
'3'
indicates that the results are returned to both the
requester and the application.
indicates that the results are returned to both the
requester and the caller.
•
•
•
•
•
•
•
•
•
•
•
•
DBRIRRR for Assembler
DBC_RetnRsltRqstr for C
RQSTR for COBOL
DBC_RETN_RSLT_RQSTR for PL/I
DBRIRRA for Assembler
DBC_RetnRsltAppl for C
APPL for COBOL
DBC_RETN_RSLT_APPL for PL/I
DBRIRRC for Assembler
DBC_RetnRsltCaller for C
CALLER for COBOL
DBC_RETN_RSLT_CALLER for PL/I
'4'
•
•
•
•
DBRIRRRA for Assembler
DBC_RetnRsltRqstrAppl for C
RQSTR-APPL for COBOL
DBC_RETN_RSLT_RQSTR_APPL for
PL/I
'5'
• DBRIRRRC for Assembler
• DBC_RetnRsltRqstrCaller for C
• RQSTR-CALLER for COBOL
• DBC_RETN_RSLT_RQSTR_CALLER
for PL/I
If not specified, the default from the HSHSPB is used, which as distributed is 'R'.
If a value other than 1 (return the results to other than the procedure making the request) is
specified, then the DBCAREA Keep-response option must specify either 'Y' or 'P'.
For details on External Stored Procedures, refer to Chapter 17: “Stored Procedures.”
Return Time
Return Time is a one byte field that specifies if time stamps are to be generated for the
application.
154
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Return Time
In this language...
The variable name for Return Time is...
COBOL
DBCAREA-RET-TIME
PL/I
RET_TIME
C
ret_time
IBM Assembler
DBORTS
This routine...
Does this for Return Time...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IWPF; IRQ; CRQ)
Return Time is used by...
To...
applications
write
Return Time is initialized by DBCHINI to the default value provided for Return Time in the
HSHSPB.
When the value for Return Time is not appropriate for the application, you should perform
the following procedure before calling DBCHCL:
1
Set Change Options to ‘Y‘.
2
Change the value for Return Time as follows.
If time stamps are...
Then change the value for Return Time to...
to be provided
Y
not to be provided
N
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
When time stamps are specified for the Fetch function, the time stamps provided are valid
only on the first call to DBCHCL for the Fetch function.
The time stamps may be changed later. For example, if DBCHCL exchanges information with
the Teradata Database to keep the response buffer stocked.
You should only use the time stamp capability for diagnostic applications.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
155
Chapter 3: DBCAREA
Route Description Codes
Route Description Codes
Route Description Codes is a four byte field that is formatted in a manner that allows an
application written in IBM Assembler to build a WTO parameter list directly in the
DBCAREA.
In this language...
The variable name for Route Description Codes is...
COBOL
DBCAREA-ROUTE-DESC-CODES
PL/I
ROUTE_DESC_CODES
C
route_desc_codes
IBM Assembler
DBCMSGRD
This routine...
Does this for Route Description Codes...
DBCHINI
writes
DBCHCL
nothing
Route Description Codes is
used by...
To...
applications
write
Note: The application must ensure that the message area is padded with trailing blanks.
For more information on issuing a WTO, see an IBM z/OS system macros manual.
Run Length
Run Length is a four byte field that specifies the length in bytes of the run string for existing
applications that set Connect Type to R (the HSHSPB default).
156
In this language...
The variable name for Run Length is...
COBOL
DBCAREA-RUN-LEN
PL/I
RUN_LEN
C
run_len
IBM Assembler
DBCNIRSL
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Run Length
This routine...
Does this for Run Length...
DBCHINI
writes
DBCHCL
reads (CON)
Run Length is used by...
To...
applications
write
The value of Run Length must be positive.
If Connect Type is set to...
Then...
C
the maximum value is 24
R
the maximum value after reduction for any leading blanks is 16
If Run Pointer is ...
Then...
0
DBCHCL uses the default value of 7 for Run Length.
anything else
the Connect function, before calling DBHCL.
The application does the following, depending on the setting:
• Y - the Run Length field is ignored. The Run Pointer must
point to the two-byte area containing the length of the run
string, which is then followed by the actual run string.
• N - the application must supply the length information in Run
Length. See “Variable Length Request” on page 198.
If the Connect Type is set to ‘C‘, a connect parcel will be built based on the value set in Run
Length.
If the value for Run Length is...
Then...
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.
17 to 24
the value Run Pointer points to is moved into a connect parcel,
left-justified and zero-filled to the right.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
157
Chapter 3: DBCAREA
Run Pointer
Run Pointer
Run Pointer is a four byte field that specifies a particular set of services to be used by the
session.
In this language...
The variable name for Run Pointer is...
COBOL
DBCAREA-RUN-PTR
PL/I
RUN_PTR
C
run_ptr
IBM Assembler
DBCNIRSP
This routine...
Does this for Run Pointer...
DBCHINI
writes
DBCHCL
reads (CON)
Run Pointer is used by...
To...
applications
write
If Run Pointer is zero, DBCHCL uses DBC/SQL as the default value.
The application 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
one of the following addresses:
•
the run string for the Run parcel
•
the connect parcel body before calling DBCHCL for the Connect function
DBC/SQL is an allowed value. Run string is not case-sensitive.
158
If Variable Length Request is...
Then Run Pointer is the address of the...
N
beginning of the run string.
Y
two-byte length field that precedes the run string.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Save Response Buffer
Save Response Buffer
Save Response Buffer is a one byte field that specifies whether the response buffer is saved
when DBCHCL is called for the End Request function.
In this language...
The variable name for Save Response Buffer is...
COBOL
DBCAREA-SAVE-RESP-BUF
PL/I
SAVE_RESP_BUF
C
save_resp_buf
IBM Assembler
DBOFSVB
This routine...
Does this for Save Response Buffer...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; CMD; IWPF; IRQ; CRQ)
Save Response Buffer is used
by...
To...
applications
write
Save Response Buffer is initialized by DBCHINI to the default value provided for Save
Response Buffer in the HSHSPB.
When the value for Save Response Buffer is not appropriate for the application, you should
perform the following procedure before calling DBCHCL for any of the following functions:
•
Connect
•
RunStartUp
•
Initiate with Protocol-Function
•
Command
•
Initiate Request
1
Set Change Options to ‘Y‘.
2
Change the value for Save Response Buffer as follows.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
159
Chapter 3: DBCAREA
Segment Data
If the response buffer is to be...
Then change the value for Save Response
Buffer to...
saved and reused for another response buffer
request
Y
deallocated
N
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
If Save Response Buffer is set to ‘Y‘, one response buffer with its associated Request Context
Block is saved.
However, if the next request requires a buffer larger than the one saved, the saved buffer is
freed and another is allocated.
Note: Proper use of this option can reduce the CPU overhead that would be incurred by
always allocating a buffer for a call to DBCHCL for the Connect, RunStartUp, Initiate with
Protocol-Function, Command, or Initiate Request function and always deallocating it with a
call to DBCHCL for the End Request function.
Segment Data
Segment Data is a one byte field that specifies the processing to be performed when statements
of an SQL 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.
160
In this language...
The variable name for Segment Data is...
COBOL
DBRISEG
PL/I
DBRISEG
C
dbriSeg
IBM Assembler
DBRISEG
This routine...
Does this for Segment Data. . .
DBCHINI
writes
DBCHCL
Reads (IRQ; IWPF)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Session-desc-length
Segment Data is used by...
To...
applications
write
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 the desired segmenting is. . .
Then change the value for Segment Data to...
no segmenting
N
first segment
F
intermediate segment
I
last (or only) segment
L
cancel segmenting
C
Use mnemonics for the codes. Mnemonics are provided in the language definition for the
DBCAREA.
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'
•
2PC option must be 'N'
•
Initiate Protocol-function option must be 'N' if the Initiate with Protocol Function
function is used.
For details on SQL Stored Procedures, refer to Chapter 17: “Stored Procedures.”
Session-desc-length
Session-desc-length is a four-byte field: when the Variable-length-request option is “N” it
contains the number of bytes addressed by the Session-desc-pointer field; when the Variablelength-request option is “Y”, Session-desc-length is ignored.
Use of Session-desc requires a Connect-type setting of “C”.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
161
Chapter 3: DBCAREA
Session-desc-pointer
Session-desc-length exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Session-desc-length is ignored.
In this language...
The variable name for Session-desc-length...
COBOL
SESS-DESC-LEN
PL/I
SESS_DESC_LEN
C
sessDescLen
IBM Assembler
DBCNISDL
This routine...
Does this for Session-desc-length...
DBCHINI
writes
DBCHCL
reads (RCON)
Session-desc-length is used by...
To...
applications
write
The value must be positive. The sum of this length and the length used for Workload-pointer
must be less than or equal to one of the following values:
The maximum value is approximately. . .
If Maximum Parcel is set to...
32,725
O
64,493
H
2,147,483,602
H, and the Teradata Database supports
ExtendedResponse, as indicated by the
DBCHQE Extended-response-support query.
The actual maximum may vary slightly with the version of the Teradata Database being used;
the value may be obtained using the DBCHQE CLIv2-limits query.
Session-desc-pointer
Session-desc-pointer is a four-byte field: when the Variable-length-request option is “N”, if
Session-desc-length is non-zero, it contains the address of an EBCDIC character string of that
number of bytes, while if Session-desc-length is zero, Session-desc-pointer is ignored; when
162
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Session-desc-pointer
the Variable-length-request option is “Y”, it contains the address of a two-byte unsigned
integer containing the number of bytes in an EBCDIC character string followed by that string,
and Session-desc-length is ignored.
Use of Session-desc requires a Connect-type setting of “C”.
Session-desc-pointer exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Session-desc-pointer is ignored.
In this language...
The variable name for Session-desc-pointer...
COBOL
SESS-DESC-PTR
PL/I
SESS_DESC_PTR
C
sessDescPtr
IBM Assembler
DBCNISDP
This routine...
Does this for Session-desc-pointer...
DBCHINI
writes
DBCHCL
reads (RCON)
Session-desc-pointer is used by...
To...
applications
write
The character string has no meaning beyond that determined by the application. Any nongraphic codepoints are translated to dashes, as are any opening or closing parentheses. The
string is prefixed by “SESSDESC(“, suffixed with “)”, and added to the LogonSource column
of DBC.SessionTbl.
The sum of the lengths used for Session-desc-pointer and Workload-pointer must be less than
or equal to one of the following values:
The maximum value is approximately. . .
If Maximum Parcel is set to...
32,725
O
64,493
H
2,147,483,602
H, and the Teradata Database supports
ExtendedRespond, as indicated by the DBCHQE
Extended-response-support query.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
163
Chapter 3: DBCAREA
Session Status
The actual maximum may vary slightly with the version of the Teradata Database being used;
the value may be obtained using the DBCHQE CLIv2-limits query.
However, TDP will reject Connect requests of excessive length, and the length of the
LogonSource column is limited by the Database, and TDP will truncate any string that
exceeds that length.
Session Status
Session Status is a one byte field that designates the state of the session.
In this language...
The variable name for Session Status is...
COBOL
DBCAREA-SESS-STATUS
PL/I
SESS_STATUS
C
sess_status
IBM Assembler
DBCOFLG1
This routine...
Does this for Session Status...
DBCHINI
writes
DBCHCL
writes (FET)
Session Status is used by...
To...
applications
read.
DBCHCL places Session Status in the DBCAREA when the Fetch function initiates. If Wait
For Response is set to N, Session Status is available at the completion of the request.
There are four flags in Session Status:
164
Flag Name
Description
Pool session
This bit is set by FET at Connect completion.
Set bit X‘80‘ to this...
If the session was...
1
assigned from a session pool.
0
not assigned from a session pool.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Set Character Set
Flag Name
Description
In transaction
Set bit X‘40‘ to this...
If the session...
1
had a transaction in progress when the bit was
set.
0
did not have a transaction in session when the
bit was set.
Set bit X‘20‘ to this...
If the default database...
1
has changed or if there are still spool files.
0
has not changed or if there are not still spool
files.
Set bit X‘10‘ to this...
If a 2PC session is...
1
in doubt.
0
not in doubt.
Cleanup needed
In-Doubt
Note: The In transaction and Cleanup needed flags are dependent on timing.
A fetch is a request-level operation and the flag is a session-level report. Therefore, the current
session state may be changed by a subsequent request.
Set Character Set
Set Character Set is a one byte field that is initialized to the default value provided for Set
Character Set in the HSHSPB.
In this language...
The variable name for Set Character Set is...
COBOL
DBCAREA-SET-CHAR-SET
PL/I
SET_CHAR_SET
C
charset_type
IBM Assembler
DBOSCSP
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
165
Chapter 3: DBCAREA
Statement-status
This routine...
Does this for Set Character Set...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IWP; IRQ)
Set Character Set is used by...
To...
applications
write
When the value for Set Character Set is not appropriate for the application, you should
perform the following procedure before calling DBCHCL for any function.
1
Set Change Options to ‘Y‘.
2
Change the value for Set Character Set to N.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Statement-status
Statement-status specifies whether the server may return parcels rather than Success or
ResultSummary or OK parcels. When Statement-status 'E' is specified, Connect-type 'C' must
also be specified.
166
In this language...
The variable name for Statement-status is...
COBOL
DBCNISS
PL/I
DBCNISS
C
dbcniSS
IBM Assembler
DBCNISS
This routine...
Does this for Statement-status. . .
DBCHINI
writes
DBCHCL
Reads (CON, IRQ, IWPF)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
S2C Conversion
Statement-status is used by...
To...
applications
write
If ResultSummary...
Statement-status to
indicates that Success or OK parcels are
returned
'O'
indicates that ResultSummary parcels may be
returned
'E'
Note: Unless a new application must support old versions of the Teradata Database, which
would reject its use, Statement-status should always be set to 'E'. The CLIv2 Query routine
QEPIESS (or QEPIASL) can be used to ascertain if the server supports this enhancement.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
S2C Conversion
S2C Conversion is a one byte field that specifies the action to be taken when data in the
character set of the Teradata Database contains a character that does not exist in the client‘s
character set.
In this language...
The variable name for S2C Conversion is...
COBOL
DBCAREA-S2C-CONVERSION
PL/I
S2C_CONVERSION
C
s2c_conversion
IBM Assembler
DBCIS2CC
This routine...
Does this for S2C Conversion...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; IWPF; CRQ)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
167
Chapter 3: DBCAREA
TDP-receipt-timestamp
S2C Conversion is used by...
To...
applications
write
S2C Conversion is initialized to the default value provided for S2C Conversion in the site‘s
HSHSPB. But if the value is not appropriate for the application, the application may, before
calling DBCHCL for Initiate or Initiate With Protocol-Function, change the value as follows:
1
Set Change Options to ‘Y‘.
2
Change the value for S2C Conversion as follows:
If...
Then set S2C
Conversion to...
such conversions are to be rejected and terminate the request
R
such conversions are to be ignored (and the unacceptable character
replaced by the character in the client‘s character set defined to be
used to represent invalid characters)
I
the Teradata Database default C2S Conversion setting is to be used
D
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
TDP-receipt-timestamp
TDP-receipt-timestamp is an eight byte field that specifies the actual time and date CLIv2 sent
the request to the TDP. TDP-receipt-timestamp is deprecated because its format is dependent
on the hardware architecture of certain channel-attached systems.
168
In this language...
The variable name for TDP-receipt-timestamp is...
COBOL
DBCAREA-HSISVC-TIME
PL/I
HSISVC_TIME
C
hsisvc_time
IBM Assembler
DBCTSTMP
This routine...
Does this for TDP-receipt-timestamp...
DBCHINI
writes
DBCHCL
writes (FET)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
TDP Request Number
HSISVC Time is used by . ..
To...
applications
read
After a call to DBCHCL for the first Fetch function on the specified request, if Return Time is
set to ‘Y‘, the application can obtain the value of TDP-receipt-timestamp.
The time is stored in STCK (TOD clock) format.
This time stamp is the full 8-byte contents of the TOD clock.
TDP Request Number
TDP Request Number is a four byte field that is the TDP identifier of the request.
In this language...
The variable name for TDP Request Number is...
COBOL
DBCAREA-TDP-REQ-NO
PL/I
TDP_REQ_NO
C
tdp_req_no
IBM Assembler
DBCOARQN
This routine...
Does this for TDP Request Number...
DBCHINI
writes
DBCHCL
writes (CON; RSUP; IWPF; CMD; IRQ)
TDP Request Number is used
by...
To...
applications
read.
The request id is available in TDP Request Number after the application regains control from
a call to DBCHCL with function code set to any of the following:
•
Connect
•
RunStartUp
•
Command
•
Initiate with Protocol-Function
•
Initiate Request
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
169
Chapter 3: DBCAREA
Tell if Delay
DBCHCL puts TDP Request Number in the DBCAREA as soon as DBCHCL is called for a
request-generating function.
TDP Request Number is available after the application regains control from DBCHCL, even
with a connect operation.
Compare with “Output CLIv2 Request Id” on page 127.
Tell if Delay
Tell if Delay is a one byte field that specifies whether the application is to be informed of a loss
of communication with a Teradata Database while waiting for the restart to complete.
Note: Tell About Crash is a deprecated name for Tell if Delay.
If a restart is detected during logoff processing, CLIv2 reconnects the session and resubmits
the logoff request.
Tell if Delay is initialized by DBCHINI to the default value provided for Tell if Delay in the
HSHSPB
In this language...
The variable name for Tell if Delay is...
COBOL
DBCAREA-TELL-IF_DELAY
PL/I
TELL_IF_DELAY
C
tell_if_delay
IBM Assembler
DBODLYT
This routine...
Does this for Tell if Delay...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IRQ; CRQ)
Tell if Delay is used by...
To...
applications
write
The combination of Wait During Delay set to ‘N‘ and Tell if Delay set to N is not allowed.
If Wait During Delay and Tell if Delay are both set to ‘Y‘, an intermediate return code of 286 is
returned when communication is lost with the Teradata Database. If the request is still
pending, the response‘s final status is returned after communication is restored.
170
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Time1
Time1
Time1 is a four byte field that records when the request arrives at the TDP from CLIv2.
In this language...
The variable name for Time1 is...
COBOL
DBCAREA-TDPWAIT-TIME
PL/I
TDPWAIT_TIME
C
tdpwait_time
IBM Assembler
DBCTIME1
This routine...
Does this for Time1...
DBCHINI
writes
DBCHCL
writes (FET)
Time1 is used by...
To...
applications
read
After a call to DBCHCL for the first fetch function on the specified request and if Return Time
is set to ‘Y‘, the application can obtain the value of Time1.
The 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.
Time2
Time2 is a four byte field that records when the TDP sends the request to the Teradata
Database.
In this language...
The variable name for Time2 is...
COBOL
DBCAREA-TDPDBO-TIME
PL/I
TDPDBO_TIME
C
tdpdbo_time
IBM Assembler
DBCTIME2
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
171
Chapter 3: DBCAREA
Time3
This routine...
Does this for Time2...
DBCHINI
writes
DBCHCL
writes (FET)
Time2 is used by...
To...
applications
read
After a call to DBCHCL for the first fetch function on the specified request and if Return Time
is set to ‘Y‘, the application can obtain the value of Time2.
The Time2 field is four bytes long and contains an unsigned binary timestamp. The difference
between Time2 and Time1 yields the elapsed time between those two points in processing the
request. The precision for Time2, or the differences between Time2 and Time1, is specified by
the Timing-precision option. The validity of the Time2 field is indicated by the Time2-status
field.
Time3
Time is a four byte field that records when the response arrives at the TDP from the Teradata
Database.
172
In this language...
The variable name for Time3 is...
COBOL
DBCAREA-TDPDBI-TIME
PL/I
TDPDBI_TIME
C
tdpdbi_time
IBM Assembler
DBCTIME3
This routine...
Does this for Time3...
DBCHINI
writes (FET)
DBCHCL
writes
Time3 is used by...
To...
applications
read
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Time4
After a call to DBCHCL for the first fetch function on the specified request and if Return Time
is set to ‘Y‘, the application can obtain the value of Time3.
The Time3 field is four bytes long and contains an unsigned binary timestamp. The difference
between Time3 and either Time1 or Time2 yields the elapsed time between those two points
in processing the request. The precision for Time3, or the differences between Time3 and
another Time, is specified by the Timing-precision option. The validity of the Time3 field is
indicated by the Time3-status field.
Time4
Time4 is a four byte field that records when the TDP sends the response to CLIv2.
In this language...
The variable name for Time4 is...
COBOL
DBCAREA-TDPXMM-TIME
PL/I
TDPXMM_TIME
C
tdpxmm_time
IBM Assembler
DBCTIME4
This routine...
Does this for Time4...
DBCHINI
writes
DBCHCL
writes
Time4 is used by...
To...
applications
read
After a call to DBCHCL for the first fetch function on the specified request and if Return Time
is set to ‘Y‘, the application can obtain the value of Time4.
The Time4 field is four bytes long and contains an unsigned binary timestamp. The difference
between Time4 and any of Time1 through Time3 yields the elapsed time between those two
points in processing the request. The precision for Time4, or the differences between Time4
and another Time, is specified by the Timing-precision option. The validity of the Time4 field
is indicated by the Time4-status field.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
173
Chapter 3: DBCAREA
Time5
Time5
Time5 is a four byte field that records when the response arrives in the CLIv2 response buffer.
In this language...
The variable name for Time5 is...
COBOL
DBCAREA-SRBSCHED-TIME
PL/I
SRBSCHED_TIME
C
srbsched_time
IBM Assembler
DBCTIME5
This routine...
Does this for Time5...
DBCHINI
writes
DBCHCL
writes (FET)
Time5 Time is used by...
To...
applications
read.
After a call to DBCHCL for the first fetch function on the specified request and if Return Time
is set to ‘Y‘, the application can obtain the value of Time5.
The Time5 field is four bytes long and contains an unsigned binary timestamp. The difference
between Time5 and any of Time1 through Time2 yields the elapsed time between those two
points in processing the request. The precision for Time5, or the differences between Time5
and another Time, is specified by the Timing-precision option. The validity of the Time5 field
is indicated by the Time5-status field.
Time1-status
Time1-status is a single-byte EBCDIC character that indicates the status of Time1.
Time1-status exists only when DBCHINI had been called for a DBCAREA with Total-length
set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a smaller
DBCAREA, Time1-status is not returned.
174
In this language...
The variable name for Time1-status is...
COBOL
DBCOTSS1
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Time2-status
In this language...
The variable name for Time1-status is...
PL/I
DBCOTSS1
C
dbcoTSS1
IBM Assembler
DBCOTSS1
This routine...
Does this for Time1-status...
DBCHCL
writes
Time1-status is used by...
To...
applications
reads
If Time1-status is a...
Then...
V
the timestamp is valid.
O
the timestamp overflowed. Could not be contained in fourbytes.
Space
or
binary zero
the timestamp is not valid.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Time2-status
Time2-status is a single-byte EBCDIC character that indicates the status of Time2.
Time2-status exists only when DBCHINI had been called for a DBCAREA with Total-length
set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a smaller
DBCAREA, Time2-status is not returned.
In this language...
The variable name for Time2-status is...
COBOL
DBCOTSS2
PL/I
DBCOTSS2
C
dbcoTSS2
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
175
Chapter 3: DBCAREA
Time3-status
In this language...
The variable name for Time2-status is...
IBM Assembler
DBCOTSS2
This routine...
Does this for Time2-status...
DBCHCL
writes
Time2-status is used by...
To...
applications
read
If Time2-status is a...
Then...
V
the timestamp is valid.
O
the timestamp overflowed. Could not be contained in fourbytes.
Space
or
binary zero
the timestamp is not valid.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Time3-status
Time3-status is a single-byte EBCDIC character that indicates the status of Time3.
Time3-status exists only when DBCHINI had been called for a DBCAREA with Total-length
set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a smaller
DBCAREA, Time3-status is not returned.
176
In this language...
The variable name for Time3-status is...
COBOL
DBCOTSS3
PL/I
DBCOTSS3
C
dbcoTSS3
IBM Assembler
DBCOTSS3
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Time4-status
This routine...
Does this for Time3-status...
DBCHCL
writes
Time3-status is used by...
To...
applications
read
If Time3-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.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Time4-status
Time4-status is a single-byte EBCDIC character that indicates the status of Time4.
Time4-status exists only when DBCHINI had been called for a DBCAREA with Total-length
set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a smaller
DBCAREA, Time4-status is not returned.
In this language...
The variable name for Time4-status is...
COBOL
DBCOTSS4
PL/I
DBCOTSS4
C
dbcoTSS4
IBM Assembler
DBCOTSS4
This routine...
Does this for Time4-status...
DBCHCL
writes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
177
Chapter 3: DBCAREA
Time5-status
Time4-status is used by...
To...
applications
read
If Time4-status is a...
Then...
V
the timestamp is valid.
O
the timestamp overflowed. Could not be contained in fourbytes.
Space
or
binary zero
the timestamp is not valid.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Time5-status
Time5-status is a single-byte EBCDIC character that indicates the status of Time5.
Time5-status exists only when DBCHINI had been called for a DBCAREA with Total-length
set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a smaller
DBCAREA, Time5-status is not returned.
178
In this language...
The variable name for Time5-status is...
COBOL
DBCOTSS5
PL/I
DBCOTSS5
C
dbcoTSS5
IBM Assembler
DBCOTSS5
This routine...
Does this for Time5-status...
DBCHCL
writes
Time5-status is used by...
To...
applications
read
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Timing-precision
If Time5-status is a...
Then...
V
the timestamp is valid.
O
the timestamp overflowed. Could not be contained in fourbytes.
Space
or
binary zero
the timestamp is not valid.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Timing-precision
Timing-precision is a signed two-byte value that specifies the precision of Time1 through
Time5.
In this language...
The variable name for Timing-precision is...
COBOL
DBCITSP
PL/I
DBCITSP
C
dbciTSP
IBM Assembler
DBCITSP
This routine...
Does this for Timing-precision...
DBCHCL
reads (CON; RSUP; IWPF; CMD; IRQ; CRQ)
DBCHINI
writes
Timing-precision is used by...
To...
applications
write
Timing-precision specifies the power of two by which a timestamp in microseconds is raised.
The default is 8, in which case the Time values are in units of 2**8, or 256, microseconds. The
minimum value is 0, the maximum 20.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
179
Chapter 3: DBCAREA
Total Length
Total Length
Total Length is a four byte field that specifies the length of the DBCAREA in bytes.
In this language...
The variable name for Total Length is...
COBOL
DBCAREA-TOTAL-LEN
PL/I
TOTAL_LEN
C
total_len
IBM Assembler
DBCSIZE
This routine...
Does this for Total length...
DBCHINI
reads
DBCHCL
reads
Total Length is used by...
To...
applications
write
Total Length must be initialized by the application 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. For lengths greater than 384 but not equal to 640, the excess is
assumed to be an application appendage to the DBCAREA. In Assembler, the mnemonic
DBCAREAL reflects the maximum DBCAREA size, currently 640. The mnemonic
DBCAOLEN is the original length of 384.
Note: In the IBM Assembler macro, the symbol DBCAREAL holds the results of the
calculation of the length by the assembler.
Transaction Semantics
Transaction Semantics is a one byte field that specifies the semantics to be used for requests
within a transaction. When Transaction-semantics 'A' or 'D' is specified, Connect-type 'C'
must also be specified.
180
In this language...
The variable name for Transaction Semantics is...
COBOL
DBCAREA-SEMANTICS
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Transaction Semantics
In this language...
The variable name for Transaction Semantics is...
PL/I
TX_SEMANTICS
C
tx_semantics
IBM Assembler
DBCNITSM
This routine...
Does this for Transaction Semantics...
DBCHINI
writes
DBCHCL
reads (CON)
Transaction Semantics is used
by...
To...
applications
write
DBCHCL initializes Transaction Semantics to the default value provided for it in the HSHSPB
for your site.
When the value for Transaction Semantics is not appropriate for the application, you should
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.
If the transaction semantics to be used for the application is ...
Then change the value for
Transaction Semantics to...
the Teradata Database default.
D
This value is always acceptable.
ANSI
A
This value is rejected if either the Teradata Database or the
environment does not support the selection of transaction
semantics. This feature requires Teradata Database for UNIX
version 2 release 2 (or later).
Teradata
T
This value is always acceptable.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
181
Chapter 3: DBCAREA
Transforms-off
Transforms-off
Transforms-off is a one byte EBCDIC field that indicates whether SQL Structured User
Defined Types (UDTs) are transformed into their external data type or left as their constituent
attributes.
In this language...
The variable name for Transforms-off is...
COBOL
TRANSFORMS-OFF
PL/I
TRANSFORMS-OFF
C
transformsOff
IBM Assembler
DBRITO
This routine...
Does this for Transforms-off...
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
Transforms-off is used by...
To...
applications
write
One of the following values may be set before initiating a request: 'N' (DBRITON for
Assembler, DBC_XformsOffNo for C, DBC-NO for COBOL, DBC_XFORMS_OFF_NO for
PL/I), indicates that Structured UDTs are transformed into their external type. 'Y' (DBRITOY
for Assembler, DBC_XformsOffYes for C, DBC-YES for COBOL, DBC_XFORMS_OFF_YES
for PL/I) indicates that Structured UDTs are not transformed.
The default setting is "N".
Trusted-request
Trusted-request is a one byte EBCDIC 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.
182
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Two Response Buffers
In this language...
The variable name for Trusted-request is...
COBOL
TRUSTED-REQUEST
PL/I
TRUSTED-REQUEST
C
trustedRequest
IBM Assembler
DBRITRQ
This routine...
Does this for Trusted-request...
DBCHINI
writes
DBCHCL
reads (RSUP; IRQ; IWPF)
Trusted-requests is used by...
To...
applications
write
One of the following values may be set before initiating a request: 'N' (DBRITRQN for
Assembler, DBC_TrustRqstNo for C, DBC-NO for COBOL, DBC_TRUST_RQST_NO for
PL/I), indicates the request may not use the Teradata SQL SET
QUERY_BAND='PROXYUSER=...' statement to change the session userid. 'Y' (DBRITRQY
for Assembler, DBC_TrustRqstYes for C, DBC-YES for COBOL, DBC_TRUST_RQST_YES
for PL/I) indicates the request may use the Teradata SQL SET
QUERY_BAND='PROXYUSER=...' statement to change the session userid.
The default setting is "N".
Two Response Buffers
Two Response Buffers is a one byte field that specifies whether double-buffering is to be used
for the response.
In this language...
The variable name for Two Response Buffers is...
COBOL
DBCAREA-TWO-RESP-BUFS
PL/I
TWO_RESP_BUFS
C
two_resp_bufs
IBM Assembler
DBO2FBU
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
183
Chapter 3: DBCAREA
Two Response Buffers
This routine...
Does this for Two Response Buffers...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IWPF; IRQ)
Two Response Buffers is used
by...
To...
applications
write
Two Response Buffers is initialized by DBCHINI to the default value provided for Two
Response Buffers in the HSHSPB.
When the value for Two Response Buffers is not appropriate for the application, you should
perform the following procedure before calling DBCHCL for any of the following functions:
•
Connect
•
RunStartUp
•
Initiate with Protocol-Function
•
Initiate Request
1
Set Change Options to ‘Y‘.
2
Change the value for Two Response Buffers as follows.
If the response is to be...
Then change the value for Two Response Buffers to...
double-buffered
Y
single-buffered
N
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
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.
DBCHCL automatically restocks the response buffers.
The application may have to wait for data to arrive if the application is consuming the data
faster than the Teradata Database can restock the buffer, but it does not have to arrange for
data to arrive.
184
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Use-default-conn
Note: The response for the connect request 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.
Use-default-conn
Use-default-conn is a one byte EBCDIC field that indicates whether a connection being
established by an External Stored Procedure calling CLIv2 and executing in the Teradata
Database is a new connection or the connection used by the application to call the procedure.
Use-default-conn exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Use-default-conn is ignored.
In this language...
The variable name for Use-default-conn is...
COBOL
USE-DEFAULT-CONN
PL/I
USE_DEFAULT_CONN
C
useDefaultConn
IBM Assembler
DBCNIDC
This routine...
Does this for...
DBCHINI
writes
DBCHCL
reads (CON; IRQ; IWPF)
Use-default-conn is used by...
To..
applications
write
One of the following values may be set before initiating a request:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
185
Chapter 3: DBCAREA
Use Presence Bits
If...
Then set Connect Type to...
'N', indicates that a new connection is
established.
•
•
•
•
DBCNIDCN for Assembler
DBC_DfltConnNo for C
DBC-NO for COBO
DBC_DFLT_CONN_NO for PL/I)
'Y', indicates that the connection used to call the
procedure is used.
•
•
•
•
DBCNIDCY for Assembler
DBC_DfltConnYes for C
DBC-YES for COBOL,
DBC_DFLT_CONN_YES for PL/I
If not specified 'N' is assumed.
If Use-default-conn is set to 'Y', since a new connection is not being established, the following
DBCAREA settings that would normally apply to the Connect function are ignored: Connecttype, Delegate-user-identity, input-TDP-pat, Logon-length, Logon-pointer, Mechanismdata-encoding, Mechanism-data-len, Mechanism-data-ptr, Mechanism-name, Run-length,
and Run-pointer.
If Use-default-conn is set to “Y” since session-wide settings from the existing connection are
used, the following DBCAREA options that would normally apply to the Connect function
are ignored: Date-form, Language-conformance, Statement-status, Transaction-semantics,
and 2PC.
For details on External Stored Procedures, refer to Chapter 17: “Stored Procedures.”
Use Presence Bits
Use Presence Bits is a one byte field that specifies the mode in which the client will package
data to send to the Teradata Database.
186
In this language...
The variable name for Use Presence Bits is...
COBOL
DBCAREA-USE-PRESENCE-BITS
PL/I
USE_PRESENCE_BITS
C
use_presence_bits
IBM Assembler
DBOIDTA
This routine...
Does this for Use Presence Bits...
DBCHINI
writes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Use Presence Bits
This routine...
Does this for Use Presence Bits...
DBCHCL
reads (CON; RSUP; IWPF; IRQ)
Use Presence Bits is used by...
To...
applications
write
Use Presence Bits is initialized by DBCHINI to the default value provided for Use Presence
Bits in the HSHSPB.
When the value for Use Presence Bits is not appropriate for the application, you should
perform the following procedure before calling DBCHCL for the following functions:
•
Connect
•
RunStartUp
•
Initiate with Protocol-Function
•
Initiate Request
1
Set Change Options to ‘Y‘.
2
Change the value for Use Presence Bits as follows.
If the data string has been prepared
in this mode...
Then change the value for Use Presence Bits to...
indicator (IndicData)
Y
record
N
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
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: Since DBCHCL does not parse the request string, it is the responsibility of the
application to check whether the request string contains a USING row descriptor and to set
Use Presence Bits, Using Data Pointer, and Using Data Length appropriately.
See “Variable Length Request” on page 198, for the preparation of the input data string: the
order of the two-byte length field (if used), the bytes containing indicator bits (if used), and
the bytes containing data values.
Although Use Presence Bits is read during the call to DBCHCL for the Connect function and
the RunStartUp function and is stored in the appropriate session and Request Control Blocks,
it is not usually used by the functions. Neither function sends an input data string to the
Teradata software, unless a macro that accepts the Use Presence Bits parameters is set up for
the RunStartUp function.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
187
Chapter 3: DBCAREA
Using-data-count
Using-data-count
Using-data-count is a four byte field that when not zero indicates Using-data-pointer-vector
addresses a vector of pointers to areas containing data that is associated with the USING
clause in the request string. The number of pointers in the vector is the value of
Using-data-count. If Variable-length-request is not specified, Using-data-length-vector
addresses a vector 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.
A Using-data-count of one (along with the associated data and length) 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 query may be used to ascertain whether the
server supports this feature.
Using-data-count exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Using-data-count is ignored.
In this language...
The variable name for Using-data-count is...
COBOL
DBRIUDC
PL/I
DBRIUDC
C
dbriUDC
IBM Assembler
DBRIUDC
This routine...
Does this for Using-data-count...
DBCHINI
writes
DBCHCL
reads (RSUP; IWPF; IRQ)
Using-data-count is used by...
To...
applications
write
Before calling DBCHCL for the Initiate Request function when the request contains a USING
modifier, the application must provide the associated using-data. Variable Length Request
applies as follows:
188
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Using Data Length
When Variable Length
Request is set to this
value...
Then...
Y
Using-data-length-vector is ignored and each data area addressed by
Using-data-pointer-vector must point to the two-byte area containing the
length of using-data, which is followed by the actual using-data.
N
the entries of Using-data-length-vector specify the length for each area.
See “Variable Length Request” on page 198.
Since CLIv2 does not parse the request string, it is the application's responsibility to set any
using-data appropriately.
Using Data Length
Using Data Length is a four byte field that has three meanings, relating to the following:
•
Contents of the request string
•
Contents of the data string
•
Length in bytes of the data string
In this language...
The variable name for Using Data Length is...
COBOL
DBCAREA-USING-DATA-LEN
PL/I
USING_DATA_LEN
C
using_data_len
IBM Assembler
DBRIUDL
This routine...
Does this for Using Data Length...
DBCHINI
writes
DBCHCL
reads (IRQ; IWPF)
Using Data Length is used by...
To...
applications
write
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
189
Chapter 3: DBCAREA
Using Data Pointer
The value of Using Data Length
must be positive, with a
maximum value of
approximately. . .
If Maximum Parcel is set to...
32763
O
65531
H
The actual maximum may vary slightly with the version of the Teradata Database being used;
the value may be obtained using the DBCHQE CLIv2-limits query
Before calling DBCHCL for the Initiate Request function and if the request contains a USING
row descriptor, the application must build a data string.
The data string must contain the data described by the USING row descriptor, and the
Variable Length Request will be set to either of the following:
When Variable Length Request is set to this
value...
Then...
Y
the Using Data Length field is ignored and the Using
Data Pointer must point to the two-byte area
containing the length of the using data string, which is
followed by the actual using data string.
N
the application must supply the length information in
Using Data Length
See “Variable Length Request” on page 198.
Since DBCHCL does not parse the request string, it is the application‘s responsibility to check
whether the request string contains a USING row descriptor and then to set Using Data
Length appropriately.
Using Data Pointer
Using Data Pointer is a four byte field that specifies the address of the data string that is
referred to by the USING row descriptor in the request string. DBCHCL does not parse the
request string.
If Using-data-count contains zero, Using-data-pointer addresses a single area containing
using-data. Any other value indicates that Using-data-pointer addresses a list of pointers to
areas containing using-data. The number of pointers in the list is the value of Using-datacount.
It is the application‘s responsibility to be certain that a data string exists and that it is pointed
to by Using Data Pointer if a USING row descriptor is in the request string. The maximum
190
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Using Data Pointer
number of fields in the Teradata SQL USING row descriptor may be obtained using the
DBCHQE SQL-limits query.
In this language...
The variable name for Using Data Pointer is...
COBOL
DBCAREA-USING-DATA-PTR
PL/I
USING_DATA_PTR
C
using_data_ptr
IBM Assembler
DBRIUDP
This routine...
Does this for Using Data Pointer...
DBCHINI
writes
DBCHCL
reads (IWPF; IRQ)
Using Data Pointer is used by...
To...
applications
write
When Using Data
Pointer has this
value...
Then the following things are true:
0
No USING row descriptor 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 nonexistent data string is zero
anything else
A USING row descriptor begins the request string
A data string accompanies the request (thus, Using Data Pointer and Use
Presence Bits contain meaningful information)
If Variable Length
Request is set to
this value...
Then the length of the data string (including the bytes
containing presence bits, if any) is provided as the...
N
value of Using Data Length.
Y
two-byte length field preceding the data string
Before calling DBCHCL for the Initiate Request function and if the request contains a USING
row descriptor, the application must build a data string.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
191
Chapter 3: DBCAREA
Using-data-length-vector
The data string must contain the data described by the USING row descriptor, and the
Variable Length Request will be set to either of the following:
When Variable Length Request is set to this
value...
Then...
Y
the Using-data-length-vector is ignored and the each
data area addressed by Using-data-pointer-vector
must point to the two-byte area containing the length
of the using data string, which is followed by the actual
using data string.
N
the application must supply the length information in
the entries of Using-data-length-vector.
Since DBCHCL does not parse the request string, it is the application‘s responsibility to check
whether the request string contains a USING row descriptor and then to set the using-data
appropriately.
IF the data...
THEN the application...
cannot contain nulls
sets Use Presence Bits to N in the DBCAREA.
can contain nulls
inserts bytes containing indicator bits at the front of the data string and sets
Use Presence Bits to ‘Y‘. See “Use Presence Bits” on page 186.
The application does the following, depending on the setting:
• N - place the address of the string or of the first byte of presence bits, if
any, in Using Data Pointer.
• Y - insert a two-byte length field in front of the presence bytes or data
string, if there are no presence bytes, and place the address of the first
byte of the two-byte length field in Using Data Pointer. See “Variable
Length Request” on page 198..
If there is no USING row descriptor in the request string, Using Data Length should be set to
zero or Using Data Pointer should be set to zero or to hex FF000000 (PL/I nil pointer).
Using-data-length-vector
When Using-data-count is not zero, Using-data-length-vector is a four byte pointer to a
vector of four byte lengths. The lengths specify the amount of data addressed by
corresponding pointers in the Using-data-pointer-vector when Variable-length-request is not
specified. When Variable-length-request is specified, Using-data-length-vector is ignored.
The number of entries in the vector is given by Using-data-count.
Using-data-length-vector exists only when DBCHINI had been called for a DBCAREA with
Total-length set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Using-data-length-vector is ignored.
192
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Using-data-pointer-vector
In this language...
The variable name for Using-data-length-vector is...
COBOL
DBRIUDLV
PL/I
DBRIUDLV
C
dbriUDLV
IBM Assembler
DBRIUDLV
This routine...
Does this for Using-data-length-vector...
DBCHINI
writes
DBCHCL
reads (RSUP; IWPF; IRQ)
Using-data-length-vector is used
by...
To...
applications
write
The value of EACH Length must be
positive, with a maximum value of
approximately. . .
If Maximum Parcel is set to...
32763
O
65531
H
The actual maximum may vary slightly with the version of the Teradata Database being used;
the value may be obtained using the DBCHQE CLIv2-limits query.
Using-data-pointer-vector
When Using-data-pointer-vector is not zero, Using-data-pointer-vector is a four byte pointer
to a vector of pointers to data that is referred to by the USING row descriptor in the request
string. When Variable-length-request is not specified, the lengths of the data are specified by
corresponding entries in the Using-data-length-vector. When Variable-length-request is
specified, the length of the data precedes the data itself. The number of entries in the list is
given by Using-data-count.
Using-data-pointer-vector exists only when DBCHINI had been called for a DBCAREA with
Total-length set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Using-data-pointer-vector is ignored.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
193
Chapter 3: DBCAREA
Using-data-pointer-vector
In this language...
The variable name for Using-data-pointer-vector is...
COBOL
DBRIUDPV
PL/I
DBRIUDPV
C
dbriUDPV
IBM Assembler
DBRIUDPV
This routine...
Does this for Using-data-pointer-vector...
DBCHINI
writes
DBCHCL
reads (RSUP; IWPF; IRQ)
Using-data-pointer-vector is used
by...
To...
applications
write
Before calling DBCHCL for the Initiate Request function and if the request contains a USING
row descriptor, the application must build a data string.
The data string must contain the data described by the USING row descriptor, and the
Variable Length Request will be set to either of the following:
When Variable Length Request is set to this
value...
Then...
Y
the Using-data-length-vector is ignored and the each
data area addressed by Using-data-pointer-vector
must point to the two-byte area containing the length
of the using data string, which is followed by the actual
using data string.
N
the application must supply the length information in
the entries of Using-data-length-vector.
Since DBCHCL does not parse the request string, it is the application‘s responsibility to check
whether the request string contains a USING row descriptor and then to set the using-data
appropriately. The maximum number of fields in the Teradata SQL USING row descriptor
may be obtained using the DBCHQE SQL-limits query.
194
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Utility-workload
IF the data...
THEN the application...
cannot contain nulls
sets Use Presence Bits to N in the DBCAREA.
can contain nulls
inserts bytes containing indicator bits at the front of the data string and sets
Use Presence Bits to ‘Y‘. See “Use Presence Bits” on page 186.
The application does the following, depending on the setting:
• N - Places the address of the string or of the first byte of presence bits, if
any, in the data addressed by each vector entry of Using-data-pointervector.
• Y - Inserts a two-byte length field in front of the presence bytes or data
string, if there are no presence bytes, and place the address of the first
byte of the two-byte length field in the data addressed by each vector
entry of Using-data-pointer-vector. See “Variable Length Request” on
page 198.
If there is no USING row descriptor in the request string, set Using-data-count to zero.
Utility-workload
Utility-workload is a one byte EBCDIC 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.
In this language...
The variable name for Utility-workload is...
COBOL
UTILITY_WORKLOAD
PL/I
UTILITY_WORKLOAD
C
utilityWorkload
IBM
DBCNIUW
This routine...
Does this for Utility-workload...
DBCHINI
writes
DBCHCL
reads (RCON, IRQ, IWPF)
Utility-workload is used by...
To...
applications
write
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
195
Chapter 3: DBCAREA
Variable Length Fetch
One of the following values may be set before initiating a request: 'N' (DBCNIUWN for
Assembler, DBC_UtilWorkloadNo for C, DBC-NO for COBOL,
DBC_UTIL_WORKLOAD_NO for PL/I), indicates the proprietary CHECK WORKLOAD
statement will not be used. 'Y' (DBCNIUWY for Assembler, DBC_UtilWorkloadYes for C,
DBC-YES for COBOL, DBC_UTIL_WORKLOAD_YES for PL/I) indicates the proprietary
CHECK WORKLOAD statement will be used.
Variable Length Fetch
Variable Length Fetch is a one byte field that specifies the location of the length information
for the data made available from the response.
In this language...
The variable name for Variable Length Fetch is...
COBOL
DBCAREA-VAR-LEN-FETCH
PL/I
VAR_LEN_FETCH
C
var_len_fetch
IBM
DBOFVAR
This routine...
Does this for Variable Length Fetch...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; CMD; IWPF; IRQ; CRQ)
Variable Fetch Length is used
by...
To...
applications
write
Variable Length Fetch is initialized by DBCHINI to the default value provided for Variable
Length Fetch in the HSHSPB.
When the value for Variable Length Fetch is not appropriate for the application, you should
perform the following procedure before calling DBCHCL for Connect, RunStartUp,
Command, Initiate with Protocol-Function, or Initiate Request:
196
1
Set Change Options to ‘Y‘.
2
Change the value for Variable Length Fetch as follows.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Variable Length Fetch
Then change the value for Variable Length
Fetch to...
If the length information is to...
precede immediately the string to which it
applies
Y
be supplied separately from the string to which
it applies
N
For a parcel of data made available by DBCHCL from the response, DBCHCL supplies to
the application both the length and the address of the data.
If Variable Length Fetch is set to this value...
Then the address in Fetch Data Pointer points to...
N
the beginning of the parcel body and the length of
the parcel body is supplied separately in Fetch
Returned Data Length.
Y
a two-byte length (in binary) field that precedes
the parcel body, and the length of the parcel body
is not supplied in Fetch Returned Data Length.
You can set Variable Length Fetch to ‘Y‘ only if
Parcel Mode Fetch is set to ‘Y‘.
If the Maximum Parcel option is set to H, then the two-byte length is considered to be an
unsigned value. Because PL/I does not support unsigned integers, you cannot use the
Variable Length Fetch option to allow the PL/I VARYING attribute for the Fetch Data
pointer for responses greater than 32767.
Since the maximum value that can be contained in the two-byte length is 65535, responses
with Variable-length-fetch that require larger lengths will be rejected.
Fetch Data Pointer
parcel body
length
Fetch Returned Data Length
Fetch Data Pointer
length
parcel body
length
2417A006
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
197
Chapter 3: DBCAREA
Variable Length Request
Variable Length Request
Variable Length Request is a one byte field that specifies the location of the length information
for the data (for example, the request string, logon string, logon-mechanism data string, using
data string, or input data string session-desc or Workload).
In this language...
The variable name for Variable Length Request is...
COBOL
DBCAREA-VAR-LEN-REQ
PL/I
VAR_LEN_REQ
C
var_len_req
IBM Assembler
DBORVAR
This routine...
Does this for Variable Length Request...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IWPF; IRQ; CRQ)
Variable Length Request is
used by...
To...
applications
write
Variable Length Request is initialized by DBCHINI to the default value provided for Variable
Length Request in the HSHSPB.
When the value for Variable Length Request is not appropriate for the application, you should
perform the following procedure before calling DBCHCL.
1
Set Change Options to ‘Y‘.
2
Change the value for Variable Length Request as follows.
If the length information is to...
Then change the value
for Variable Length
Request to...
precede immediately the data to which it applies
Y
be supplied separately from the data to which it applies
N
The following figures show what the DBCAREA must contain in either of the above cases.
198
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Variable Length Request
If Variable Length
Request is set to this
value...
Then the address supplied in the appropriate pointer field points to...
Y
a two-byte (in binary) area that precedes the data.
The corresponding DBCAREA length field (for example, Request
Length, Run Length, and so on) is not used.
The length value reflects only the length of the data, and does not
include the two bytes of its own length, as shown in the following
figure.
N
the beginning of the data.
The length of the data is supplied in the appropriate DBCAREA
length field, as shown in the following figure.
If the Maximum Parcel option is set to H, then the two-byte length is considered to be an
unsigned value. Because PL/I does not support unsigned integers, you cannot use the
Variable Length Request option to allow the PL/I VARYING attribute for the Request
Pointer or the Using Data Pointer for requests greater than 32767.
Since the maximum value that can be contained in the two-byte length is 65535, larger
lengths cannot use Variable-length-request.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
199
Chapter 3: DBCAREA
Variable Length Request
In DBCAREA:
- Variable Length Request field (Y)
- Pointer field
value of
length
data
length
In DBCAREA:
- Variable Length Request field (N)
- Length field (value of length)
- Pointer field
data
length
2417A007
The setting of Variable Length Request affects the request string, logon string, run string,
using data string, and input data string.
Note: The fragments of the string must be in the following order, if applicable:
1) two-byte length information
2) n-byte indicator information
3) bytes containing the text or value information
The only string to which all three fragments apply is a data string if Variable Length Request is
‘Y‘ and Use Presence Bits is ‘Y‘.
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.
200
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Wait During Delay
Wait During Delay
Wait During Delay is a one byte field that specifies how CLIv2 should handle a request that it
is unable to initialize or complete because communication has been lost with the Teradata
Database.
Note: Wait Across Crash is a deprecated name for Wait During Delay.
In this language...
The variable name for Wait During Delay is...
COBOL
DBCAREA-WAIT-DURING-DELAY
PL/I
WAIT_DURING_DELAY
C
wait_during_delay
IBM Assembler
DBODLYW
This routine...
Does this for Wait During Delay...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; IWPF; IRQ; CRQ)
Wait During Delay is used by...
To...
applications
write
Wait During Delay is initialized by DBCHINI to the default value provided for Wait During
Delay in the HSHSPB.
When the value for Wait During Delay is not appropriate for the application, you should
perform the following procedure before calling DBCHCL.
1
Set Change Options to ‘Y‘.
2
Change the value for Wait During Delay as follows.
If CLIv2 is to return control to the application...
Then change the value for Wait
During Delay to...
after communication with the Teradata Database is
restored
Y
as soon as the crash/restart is detected with a Return
Code 286
N
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
201
Chapter 3: DBCAREA
Wait-exclusion
If a restart occurs during a logoff request, CLIv2 reconnects the session and resubmits the
logoff request.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Note: If Wait During Delay is set to N the session is logged off by TDP. The result of the
request is indeterminate.
Wait During Delay cannot be set to N if Tell if Delay is set to N. For more information, see
“Tell if Delay” on page 170.
Wait-exclusion
Wait-exclusion specifies whether DBCHWAT will include or exclude requests for the session
from its processing. DBCHWL processing is unaffected by the option.
Wait-exclusion exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Wait-exclusion is ignored.
No other CLIv2 resources support Wait-exclusion. Therefore:
•
User events and master events will affect all types of wait processing
•
A DBCHCLN call by either the application or exit will free all CLIv2 resources
In this language...
The variable name for Wait-exclusion is...
COBOL
WAIT-EXCLUSION
PL/I
WAIT-EXCLUSION
C
waitExclusion
IBM Assembler
DBCNIWE
This routine...
Does this for Wait-exclusion...
DBCHINI
writes
DBCHCL
reads (CON and RCMD)
Wait-exclusion is used by...
To...
applications
write
One of the following values may be set before initiating a request:
202
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Wait For Response
If the application...
Then set Wait-exclusion to...
indicates that requests for the session will be
processed by DBCHWAT
N
indicates that requests for the session will
not be processed by DBCHWAT
Y
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Wait For Response
Wait For Response is a one byte field that specifies whether DBCHCL is to retain control or
return control to the application in two situations:
•
When the application has called DBCHCL for some function and DBCHCL cannot send
that request to the Teradata Database because another request in the same session is active,
DBCHCL is unable to initiate that function.
•
When the application 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)
because the buffer is being restocked, DBCHCL is unable to complete the fetch function.
In this language...
The variable name for Wait For Response is...
COBOL
DBCAREA-WAIT-FOR-RESP
PL/I
WAIT_FOR_RESP
C
wait_for_resp
IBM Assembler
DBOBSYW
This routine...
Does this for Wait For Response...
DBCHINI
writes
DBCHCL
reads (CON; RSUP; CMD; IWPF; IRQ; CRQ)
Wait For Response is used by...
To...
applications
write
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
203
Chapter 3: DBCAREA
Wait For Response
Wait For Response is initialized by DBCHINI to the default value provided for Wait For
Response in the HSHSPB.
When the value for Wait For Response is not appropriate for the application, you should
perform the following procedure before calling DBCHCL.
1
Set Change Options to ‘Y‘.
2
Change the value for Wait For Response as follows.
If DBCHCL is...
Then change the value
for Wait For Response
to...
not to return control until it is able to initiate or complete
Y
to return control as soon as the function‘s request has been sent to
the Teradata Database, in which case the application must use some
other method to detect when the function‘s response arrives
N
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
If Wait For Response is set to N, and one of the two situations described earlier occurs, the
return code is set to 150.
The application may try again. There are two ways to decide when it is reasonable to perform
a retry.
•
Call DBCHWAT.
When control is returned from DBCHWAT, try again. This method ties up fewer system
resources while waiting.
Several tries may be necessary.
Occasionally CLIv2 may finish one operation and start another immediately.
In that case, DBCHWAT will return control when one operation is over, but the next call
by the application to DBCHCL will not be accepted because CLIv2 has already started
another operation.
Allow for the possibility of multiple tries.
•
Try again immediately and keep trying until the call is accepted.
If you use this method, there should be a time delay coded between fetch attempts.
Note: If one of the two situations above occurs and Wait For Response is set to N, the
original call to DBCHCL was not accepted. CLIv2 is reporting “I was not able to do that;
try again later.”
Wait For Response set to ‘Y‘ is incompatible with the use of a master ECB and will result in
an error return code.
Note: Neither the Abort function nor the Disconnect function is affected by the setting of
Wait For Response.
204
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
Workload-length
Workload-length
Workload-length is a four-byte field: when the Variable-length-request option is “N” it
contains the number of bytes addressed by the Workload-pointer field; when the Variablelength-request option is “Y”, Workload-length is ignored.
Use of Workload requires a Connect-type setting of “C”.
Workload-length exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Workload-length is ignored.
In this language...
The variable name for Workload-length is...
COBOL
WORKLOAD-LEN
PL/I
WORKLOAD_LEN
C
workloadLen
IBM Assembler
DBCNIWLL
This routine...
Does this for Workload-length. . .
DBCHINI
writes
DBCHCL
reads (RCON)
Workload-length is used by...
To...
applications
write
The value must be positive. The sum of this length and the length used for Session-descpointer must be less than or equal to one of the following values:
The maximum value is approximately. . .
If Maximum Parcel is set to...
32,725
O
64,493
H
2,147,483,602
H, and the Teradata Database supports
ExtendedRespond, as indicated by the DBCHQE
Extended-response-support query.
The actual maximum may vary slightly with the version of the Teradata Database being used;
the value may be obtained using the DBCHQE CLIv2-limits query.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
205
Chapter 3: DBCAREA
Workload-pointer
Workload-pointer
Workload-pointer is a four-byte field: when the Variable-length-request option is “N”, if
Workload-length is non-zero, it contains the address of an EBCDIC character string of that
number of bytes, while if Workload-length is zero, Workload-pointer is ignored; when the
Variable-length-request option is “Y”, it contains the address of a two-byte unsigned integer
containing the number of bytes in an EBCDIC character string followed by that string, and
Workload-length is ignored.
Use of Workload requires a Connect-type setting of “C”.
Workload-pointer exists only when DBCHINI had been called for a DBCAREA with Totallength set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a
smaller DBCAREA, Workload-pointer is ignored.
In this language...
The variable name for Workload-pointer is...
COBOL
WORKLOAD-PTR
PL/I
WORKLOAD_PTR
C
workloadPtr
IBM Assembler
DBCNIWLP
This routine...
Does this for Workload-pointer. . .
DBCHINI
writes
DBCHCL
reads (RCON)
Workload-pointer is used by...
To...
applications
write
The character string provides application information to the Database, which defines its
format and meaning. Any non-graphic codepoints are translated to dashes, as are any opening
or closing parentheses. The string is prefixed by "WORKLOAD(", suffixed with ")", and added
to theLogonSource column of DBC.SessionTbl.
The sum of the lengths used for Workload-pointer and Session-desc-pointer must be less than
or equal to one of the following values:
206
The maximum value is approximately. . .
If Maximum Parcel is set to...
32,725
O
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA
2PC
The maximum value is approximately. . .
If Maximum Parcel is set to...
64,493
H
2,147,483,602
H, and the Teradata Database supports
ExtendedRespond, as indicated by the DBCHQE
Extended-response-support query.
The actual maximum may vary slightly with the version of the Teradata Database being used;
the value may be obtained using the DBCHQE CLIv2-limits query.
However, TDP will reject Connect requests of excessive length, and the length of the
LogonSource column is limited by the Database, and TDP will truncate any string that
exceeds that length.
2PC
2PC is a one byte field that specifies whether the session is using the 2PC protocol. When 2PC
'Y' is specified, Connect-type 'C' must also be specified.
This feature requires Teradata Database for UNIX version 2 release 2 (or later), or Teradata
DBS for TOS version 1 release 5 (or later).
In this language...
The variable name for 2PC is...
COBOL
DBCAREA-TWO-PHASE-COMMIT
PL/I
TWO_PHASE_COMMIT
C
two_phase_commit
IBM Assembler
DBO2PC
This routine...
Does this...
DBCHINI
writes
DBCHCL
reads (CON)
2PC is used by...
To...
applications
write
2PC can be set to either ‘Y‘ or ‘N‘.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
207
Chapter 3: DBCAREA
2PC
If the application...
Then set 2PC to...
uses the 2PC protocol
Y
does not use the 2PC protocol
N
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the
DBCAREA.
Note: 2PC is not valid with ANSI transaction semantics.
208
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 4
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 DBCAREA extensions are available:
•
DBCAIRX (Initiate-request)
•
DBCACNX (Connect)
DBCAIRX
DBCAIRX is 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 DBCAIRX. DBCAIRX does not exist if there
is a zero in the DBCAREA Extension Pointer field.
The prologue for the Assembler, COBOL, C, and PL/I mappings of the DBCAIRX provides
language-dependent information in constructing an extension and should be consulted.
The application should set unused fields to binary zeroes. This will allow successful execution
of existing applications should these fields ever be used.
DBCAIRX Field Descriptions
The DBCAIRX extension contains two logical sections:
•
Header
•
Element
DBCAIRX Header
Three possible header formats are available for the DBCAIRX.
•
Figure 3 illustrates the header if the Eyecatcher field is set to 'IRX8'. The Total Size field of
four bytes in length is used and additional fields are present at the end of the header and
pointer-element.
•
Figure 4 illustrates the header if the Eyecatcher field set to ‘IRX‘, the Total Size field of 4
bytes in length is used.
•
Figure 5 illustrates the header if the Eyecatcher field set to ‘DBCX‘, the Total Length field
of 2 bytes in length is used.
Note: New development should use only the 'IRX8' form. The others are deprecated.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
209
Chapter 4: DBCAREA Extensions
DBCAIRX
Figure 3: DBCAIRX Header Fields (Eyecatcher is ‘IRX8‘)
bytes
0
Eyecatcher, 4 bytes
4
Next Pointer, 4 bytes
8
Total Size, 4 bytes
12
Level, 1 bytes
Unused, 3 bytes
Unused, 8 bytes
16
20
2417A014
Deprecated Headers
Figure 4: Deprecated DBCAIRX Header Fields (Eyecatcher = ‘IRX‘)
offset
0
Eyecatcher, 4 bytes
4
Next Pointer, 4 bytes
8
Total Size, 4 bytes
2417A016
Figure 5: Deprecated DBCAIRX Header Fields (Eyecatcher = ‘DBCX‘)
offset
0
Eyecatcher, 4 bytes
4
Next Pointer, 4 bytes
8
Total Length, 2 bytes
Unused, 2 bytes
2417A015
DBCAIRX Elements
Immediately following the header are one or more elements. Each element will either:
210
•
Contain the actual data
•
Address the actual data
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCAIRX
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. Such elements are described by
Figure 6.
Figure 6: DBCAIRX Element When Eyecatcher is 'IRX8‘ and Level 1
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
20
Unused, 8 bytes
24
28
Unused, 8 bytes
Parcel Data (no mandatory length)
2417A023
Deprecated Elements
When either the Eyecatcher field contains 'IRX8' and the Level field contains a value of '0', the
Eyecatcher field contains 'IRX', or the Eyecatcher field contains 'DBCX', there are two element
formats, one format contains the data and the other format addresses the data. The Element
Type field indicates which; if the leftmost bit is '0' the element contains the data; if '1', the
element addresses the data. Elements containing the data are described by Figure 7.
Figure 7: Deprecated DBCAIRX Element Containing Actual Data
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 Channel-Attached Systems
211
Chapter 4: DBCAREA Extensions
DBCAIRX
Elements addressing the data have one of two forms, depending upon the value of the
Eyecatcher field. When the Eyecatcher field is 'IRX8' and Level = '0', Figure 8 describes the
element; when the Eyecatcher field is 'IRX' or 'DBCX', Figure 9 describes the element.
Figure 8: DBCAIRX Element When Eyecatcher is 'IRX8‘ and Level 0
offset
0
Element Type, 2 bytes
Element Length, 2 bytes
4
Unused, 2 bytes
Data Address, 4 bytes
Data Address (continued)
Unused, 4 bytes
12
Unused (continued)
Data Size, 4 bytes
16
Data Size (continued)
Unused, 4 bytes
20
Unused (continued)
8
Unused, 8 bytes
24
28
2417A019
Figure 9: Deprecated DBCAIRX Element When Eyecatcher is 'IRX' or 'DBCX'
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 sections that follow describe each of the fields in DBCAIRX. The fields are given in
alphabetical order.
Data Address
The Data Address field specifies the address of the parcel body. The symbolic name depends
upon the Eyecatcher field.
212
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCAIRX
The variable name for Data Address is...
In this language...
IRX8
IRX & DBCX
COBOL
D8XILPPT
DBXILPPT
PL/I
D8XILPPT
DBXILPPT
C
d8xilpPt
dbxilpPt
IBM Assembler
D8XILPPT
DBXILPPT
This routine...
Does this for Data Address...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Data Address is used by...
To...
applications
write
Data Length
When the Eyecatcher is ‘IRX‘ or ‘DBCX‘ the Data Length field specifies the length of the
parcel body addressed by the Data Address field.
The minimum value is 0 and:
The maximum value is...
If Maximum Parcel is set to...
32763
O
65531
H
In this language...
The variable name for Data Length is...
COBOL
DBXILPLN
PL/I
DBXILPLN
C
dbxilpLn
IBM Assembler
DBXILPLN
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
213
Chapter 4: DBCAREA Extensions
DBCAIRX
This routine...
Does this for Data Length...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Data Length is used by...
To...
applications
write
Data Size
When the Eyecatcher is ‘IRX8‘ the Data Size field specifies the length of the parcel body
addressed by the Data Address field.
The minimum value is 0 and:
The maximum value is...
If Maximum Parcel is set to...
32763
O
65531
H
The symbolic name depends upon both the Eyecatcher and Level fields:
The variable name for Data Size is...
214
In this language...
IRX8 and Level 0
IRX8 and Level 1
COBOL
D8XILPLN
D8XIEPLN
PL/I
D8XILPLN
D8XIEPLN
C
d8xilpLn
d8xiepLn
IBM Assembler
D8XILPLN
D8XIEPLN
This routine...
Does this for Data Size...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCAIRX
Data Size is used by...
To...
applications
write
Element Length
Element Length contains the length of the individual element.
The maximum value is...
If Maximum Parcel is set to...
32767
O
65535
H
The symbolic name depends upon the Eyecatcher field.
The variable name for Element Length is...
In this language...
IRX8
IRX & DBCX
COBOL
D8XILLEN
DBXILLEN
PL/I
D8XILLEN
DBXILLEN
C
d8xilLen
dbxilLen
IBM Assembler
D8XILLEN
DBXILLEN
This routine...
Does this for Element Length...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Element Length is used by...
To...
applications
write
Element Type
When the Eyecatcher field contains 'IRX8' and the Level field contains '1', Element Type
indicates the type of element; currently only a Parcel element is supported and is indicated by
an Element Type of '1' (mnemonic of 'D8XIETP' in all languages).
When either the Eyecatcher field contains 'IRX8' and the Level field contains '0', the
Eyecatcher field contains 'IRX', or the Eyecatcher field contains 'DBCX', the Element Type not
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
215
Chapter 4: DBCAREA Extensions
DBCAIRX
only indicates whether the parcel data is in the element or simply addressed by the element,
but also specifies the parcel flavor. If the leftmost 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.
The symbolic name depends upon both the Eyecatcher and Level fields:
The variable name for Element Type is...
In this language...
IRX8 and Level 0
IRX8 and Level 1
IRX & DBCX
COBOL
D8XILTYP
D8XIETYP
DBXILTYP
PL/I
D8XILTYP
D8XIETYP
DBXILTYP
C
d8xilTyp
d8xieTyp
dbxilTyp
IBM Assembler
D8XILTYP
D8XIETYP
DBXILTYP
This routine...
Does this for Element Type...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Element Type is used by...
To...
applications
write
A mnemonic is provided for the high-order bit and should be used. The symbolic name
depends upon the Eyecatcher field. The name is the same for all languages, including C. For
'IRX' and 'DBCX' the name is DBXILTP. For ‘IRX8‘ the name is D8BXILTP.
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 Database.
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. Element Length in this case always
contains 10.
Eyecatcher
Eyecatcher in the DBCAIRX is used for self-documentation, validation, and debugging. The
symbolic name depends upon the Eyecatcher field.
216
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCAIRX
The variable name is...
In this language. . .
for Eyecatcher and ‘IRX8‘
for Eyecatcher and ‘IRX‘ or ‘DBCX‘
IBM Assembler,
COBOL, or PL/I
D8XIID
DBXIID
C
d8xiId
dbxiId
This routine...
Does this for Eyecatcher...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Eyecatcher is used by...
To...
applications
write
Eyecatcher is set to ‘IRX8‘, ‘IRX‘, or ‘DBCX‘ by the application before calling DBCHCL for
the Initiate Request function.
Note: Apostrophes are not used in Eyecatcher.
New development should use only the 'IRX8' form. The others are deprecated.
Level
When the Eyecatcher is “‘IRX8‘,” the Level field specifies the format of the extension.
In this language...
The variable name for Level is...
IBM Assembler, COBOL, or PL/I
D8XCLVL
C
d8xcLvl
This routine...
Does this for Level...
DBCHINI
n/a
DBCHCL
reads (CON)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
217
Chapter 4: DBCAREA Extensions
DBCAIRX
Level is used by...
To...
applications
write
Level may have values of “1” or “0”. If the value is:
"1" it indicates that only one element format exists. New development should use only this
value.
"0" it indicates that two element formats exist. This value is deprecated.
Next Pointer
If nonzero, Next Pointer points to another DBCAIRX to form a linked list of DBCAIRX
extensions. For implicit Connects, Connect extensions (DBCACNX) may also be included.
The symbolic name depends upon the Eyecatcher field.
The variable name for Next Pointer is...
In this language...
IRX8
IRX & DBCX
IBM Assembler,
COBOL, or PL/I
D8XINEXT
DBXINEXT
C
d8xiNext
dbxiNext
This routine...
Does this for Next Pointer...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Next Pointer is used by...
To...
applications
write
The sequence in which the DBCAIRX extensions are linked is the same sequence in which the
parcels contained in DBCAIRXs are built in the request buffer.
If there is only one DBCAIRX, or if this is the last DBCAIRX in the linked list, then set Next
Pointer to zero or PL/I null pointer.
Parcel Flavor
The Parcel Flavor field specifies the flavor of the parcel.
218
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCAIRX
In this language...
The variable name for Parcel Flavor is...
IBM Assembler, COBOL, or PL/I
D8XIEPF
C
d8xiePF
This routine...
Does this for Parcel Flavor...
DBCHCL
reads (IRQ; IWPF)
Total Length
If ‘DBCX‘ was specified in Eyecatcher, Total Length specifies the length of one DBCAIRX in
bytes.
In this language...
The variable name for Total Length is...
IBM Assembler, COBOL, or PL/I
DBXILEN
C
dbxiLen
This routine...
Does this for Total Length...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Total Length is used by...
To...
applications
write
Total Length must be set by the application before calling DBCHCL. This length is validated
against the sum of the lengths of the individual elements in the DBCAIRX plus the header. If it
is not correct, the Teradata Database sends a nonzero return code.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
219
Chapter 4: DBCAREA Extensions
DBCACNX
Total Size
If ‘IRX8 or IRX‘ was specified in Eyecatcher, Total Size specifies the length of one DBCAIRX
in bytes.
The variable name for Total Size is...
In this language...
IRX8
IRX
IBM Assembler,
COBOL, or PL/I
D8XISIZE
DBXISIZE
C
d8xiSize
dbxiSize
This routine...
Does this for Total Size...
DBCHINI
n/a
DBCHCL
reads (IRQ; IWPF)
Total Size is used by...
To...
applications
write
Total Size must be set by the application before calling DBCHCL. This size is validated against
the sum of the sizes of the individual elements in the DBCAIRX plus the header. If it is not
correct, the Teradata Database sends a nonzero return code.
DBCACNX
The DBCACNX extension applies only to the explicit Connect, or an implicit Connect for the
RunStartup, Initiate Request, or Initiate request With Protocol-function, and only when the
Connect-type 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 the function. The Extension Pointer should be zeroed after the function to prevent
subsequent functions from attempting to use it.
The prologue for the Assembler, COBOL, C, and PL/I, mappings of the DBCACNX provides
language-dependent information in constructing an extension and should be consulted.
Note: the DBCACNX currently provides no data used by channel-connected systems and is
documented here only for completeness.
220
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCACNX
DBCACNX Field Descriptions
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.
Figure 10 lists the sequential order of the header fields. Figure 11 lists the sequential order of
the element fields.
Figure 10: DBCACNX Header Fields
offset
0
Eyecatcher, 4 bytes
4
Next Pointer, 4 bytes
8
Length, 4 bytes
12
Level, 1 byte
Unused, 3 bytes
2417A020
When the Level field contains a value of '2', there is an additional header field as shown below:
offset
16
Unused, 8 bytes
20
2417A022
New development should use only the level 2 form. The level 1 form is deprecated.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
221
Chapter 4: DBCAREA Extensions
DBCACNX
Figure 11: DBCACNX Element Fields When Level = 2
offset
0
Element Type, 2 bytes
Element Length, 2 bytes
4
Unused, 2 bytes
Data Type, 2 bytes
8
Data Length, 4 bytes
12
Data Pointer, 4 bytes
Unused, 4 bytes
(Level 2 only)
16
20
Unused, 8 bytes
(Level 2 only)
24
Data (no fixed length)
16 or 28
2417A021
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.
The variable name for Data-length is...
222
In this language...
Level 2
Level 1
COBOL
D8XCEDLN
DBXCEDLN
PL/I
D8XCEDLN
DBXCEDLN
C
d8xcedLn
dbxcedLn
IBM Assembler
D8XCEDLN
DBXCEDLN
This routine...
Does this for Data-length. . .
DBCHINI
n/a
DBCHCL
reads (CON)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCACNX
Data-length is used by...
To...
applications
write
Note: If the length of an element would exceed 65535 (32767 for PL/I), then the data may not
be part of the element and Data-pointer must be used to address the data.
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.
The variable name for Data-pointer is...
In this language...
Level 2
Level 1
COBOL
D8XCEDPT
DBXCEDPT
PL/I
D8XCEDPT
DBXCEDPT
C
d8xcedPt
dbxcedPt
IBM Assembler
D8XCEDPT
DBXCEDPT
This routine...
Does this for Data-pointer. . .
DBCHINI
n/a
DBCHCL
reads (CON)
Data-pointer is used by...
To...
applications
write
Data-type
Data-type is a two-byte unsigned integer field into which the type of data is placed.
The variable name for Data-type is...
In this language...
Level 2
Level 1
COBOL
D8XCEDTY
DBXCEDTY
PL/I
D8XCEDTY
DBXCEDTY
C
d8xcedTy
dbxcedTy
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
223
Chapter 4: DBCAREA Extensions
DBCACNX
The variable name for Data-type is...
IBM Assembler
D8XCEDTY
DBXCEDTY
This routine...
Does this for Data-type. . .
DBCHINI
n/a
DBCHCL
reads (CON)
Data-type is used by...
To...
applications
write
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.
The variable name for Element-length is...
224
In this language...
Level 2
Level 1
COBOL
D8XCLLEN
DBXCLLEN
PL/I
DB8XCLLEN
DBXCLLEN
C
d8xclLen
dbxclLen
IBM Assembler
D8XCLLEN
DBXCLLEN
This routine...
Does this for Element-length. . .
DBCHINI
n/a
DBCHCL
reads (CON)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCACNX
Element-length is used by...
To...
applications
write
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.
The variable name for Element-type is...
In this language...
Level 2
Level 1
COBOL
D8XCLTYP
DBXCLTYP
PL/I
D8XCLTYP
DBXCLTYP
C
d8xclTyp
dbxclTyp
IBM Assembler
D8XCLTYP
DBXCLTYP
This routine...
Does this for Element-type. . .
DBCHINI
n/a
DBCHCL
reads (CON)
Element-type is used by...
To...
applications
write
The mnemonic DBXCETD should be used to define a data element.
Eyecatcher
Eyecatcher is a four-byte field into which the EBCDIC characters 'CNX ' must be placed.
The variable name for Eyecatcher is...
In this language...
Level 2
Level 1
COBOL
D8XCID
DBXCID
PL/I
D8XCID
DBXCID
C
d8xcId
dbxcId
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
225
Chapter 4: DBCAREA Extensions
DBCACNX
The variable name for Eyecatcher is...
IBM Assembler
D8XCID
DBXCID
This routine...
Does this for Eyecatcher. . .
DBCHINI
n/a
DBCHCL
reads (CON)
Eyecatcher is used by...
To...
applications
write
The mnemonic DBXCICNX contains 'CNX ' and should be used to initialize this field.
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.
The variable name for Length is...
226
In this language...
Level 2
Level 1
COBOL
D8XCLEN
DBXCLEN
PL/I
D8XCLEN
DBXCLEN
C
d8xcLen
dbxcLen
IBM Assembler
D8XCLEN
DBXCLEN
This routine...
Does this for Length. . .
DBCHINI
n/a
DBCHCL
reads (CON)
Length is used by...
To...
applications
write
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA Extensions
DBCACNX
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.
The variable name for Level is...
In this language...
Level 2
Level 1
COBOL
D8XCLVL
DBXCLVL
PL/I
D8XCLVL
DBXCLVL
C
d8xcLvl
dbxcLvl
IBM Assembler
D8XCLVL
DBXCLVL
This routine...
Does this for Level...
DBCHINI
n/a
DBCHCL
reads (CON)
Level is used by...
To...
applications
write
The mnemonic DBXCLVLC should be used to initialize this field.
Next-pointer
Next-pointer is a four-byte 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.
The variable name for Next-pointer is...
In this language...
Level 2
Level 1
COBOL
D4XCNEXT
DBXCNEXT
PL/I
D4XCNEXT
DBXCNEXT
C
d4xcNext
dbxcNext
IBM Assembler
D4XCNEXT
DBXCNEXT
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
227
Chapter 4: DBCAREA Extensions
DBCACNX
228
This routine...
Does this for Next-pointer...
DBCHINI
n/a
DBCHCL
reads (CON)
Next-pointer is used by...
To...
applications
write
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 5
Release Tapes
This chapter describes:
•
Finding Files on the Release Tape
•
System Parameter Block
•
System Parameter Block (HSHSPB)
•
HSHSPB Assembler Source
Finding Files on the Release Tape
DBCAREA
Definitions for the DBCAREA, provided for each program language, are located on a release
tape as shown below:
For this Language...
Definitions for DBCAREA are located in the...
IBM Assembler
DBCAREA in library SAMPLIB (z/OS).
C
DBCAREAH in library SAMPLIB (z/OS).
COBOL
DBCAREAC in library SAMPLIB (z/OS).
DBCHQACC maps the Available-character-sets query response;
DBCHQERC maps all other query responses.
PL/I
DBCAREAP in library SAMPLIB (z/OS)
DBCAIRX
Definitions for DBCAREA extensions (DBCAIRX), provided for each program language, are
located as shown below:
For this language...
Definitions for DBCAIRX are located in the. . .
IBM Assembler
DBCAIRX in library SAMPLIB (z/OS).
C
DBCAIRXH in library SAMPLIB (z/OS).
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
229
Chapter 5: Release Tapes
Finding Files on the Release Tape
For this language...
Definitions for DBCAIRX are located in the. . .
COBOL
DBCAIRXC, DBCAIREC, and DBCAIRLC in library SAMPLIB
(z/OS) .
Note: DBCAIRXC maps the extension header and DBCAIRLC
maps the extension element. DBCAIRLC maps a deprecated
extension element.
PL/I
DBCAIRXP in library SAMPLIB (z/OS).
DBCACNX
Definitions for DBCACNX (DBCAREA Connect-extension), provided for each programming
language, are located as shown below:
For this language...
Definitions for DBCACNX are located in the. . .
IBM Assembler
DBCACNX in library SAMPLIB (z/OS).
C
DBCACNXH in library SAMPLIB (z/OS).
COBOL
DBCACNXC and DBCACNLC in library SAMPLIB (z/OS).
Note: DBCACNXC maps the extension header and DBCACNLC maps
the extension element.
PL/I
DBCACNXP in library SAMPLIB (z/OS).
DBCHMEP
Definitions for DBCHMEP (DBCHME parameters), provided for each programming
language, are located as shown below:
For this language...
Definitions for DBCHMEP are located in the. . .
IBM Assembler
DBCHMEP in library SAMPLIB (z/OS).
C
DBCHMEPH in library SAMPLIB (z/OS).
COBOL
DBCHMEPC in library SAMPLIB (z/OS).
PL/I
DBCHMEPP in library SAMPLIB (z/OS).
DBCHQEP
Definitions for DBCHQEP, provided for each program language, are located as shown below:
230
For this language...
Definitions for DBCHQEP are located in the. . .
IBM Assembler
DBCHQEP in library SAMPLIB (z/OS).
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 5: Release Tapes
Finding Files on the Release Tape
For this language...
Definitions for DBCHQEP are located in the. . .
C
DBCHQEPH in library SAMPLIB (z/OS).
COBOL
DBCHQEPC in library SAMPLIB (z/OS).
PL/I
DBCHQEPP in library SAMPLIB (z/OS).
DBCHQER
Definitions for DBCHQER (Query Results), provided for each programming language, are
located as shown below:
For this language...
Definitions for DBCHQER are located in the. . .
IBM Assembler
DBCHQER in library SAMPLIB (z/OS).
C
DBCHQERH in library SAMPLIB (z/OS).
COBOL
DBCHQERC, DBCHQACC, and DBCHQAMC in library SAMPLIB
(z/OS).
DBCHQACC maps the Available-character-sets query response;
DBCHQAMC maps the Available-logon-mechanism query response;
DBCHQERC maps all other query responses.
PL/I
DBCHQERP in library SAMPLIB (z/OS).
DBCHUEP
Definitions for DBCHUEP (DBCHUE parameters), provided for each programming
language, are located as shown below:
For this language...
Definitions for DBCHUEP are located in the. . .
IBM Assembler
DBCHUEP in library SAMPLIB (z/OS).
C
DBCHUEPH in library SAMPLIB (z/OS).
COBOL
DBCHUEPC in library SAMPLIB (z/OS).
PL/I
DBCHUEPP in library SAMPLIB (z/OS).
HSHSPB
Definitions for HSHSPB are located in library SAMPLIB (z/OS).
Caution:
Because the DBCAREA and the DBCAIRX may be revised from time to time, we strongly
recommend that you use them as provided on the release tape. If you prefer another name for
a field, redefine or “equivalence” the release version.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
231
Chapter 5: Release Tapes
System Parameter Block
TRDSPB
Definitions for TRDSPB, provided in each programming language, are located as shown
below:
For this language...
Definitions for TRDSPB are located in the. . .
IBM Assembler
TRDSPB in library SAMPLIB (z/OS).
TC2XPH
Definitions for TC2XPH, provided in each programming language, are located as shown
below:
For this language...
Definitions for TC2XPH are located in the. . .
IBM Assembler
TC2XPH in library SAMPLIB (z/OS).
C
TC2XPHH in library SAMPLIB (z/OS).
COBOL
TC2XPHC in library SAMPLIB (z/OS).
PL/I
TC2XPHP in library SAMPLIB (z/OS).
TRD0LENU
The Message Definitions file for United States English is named TRD0LENU; it is provided on
a release tape.
The Assembler file for TRD0LENU is on the z/OS release tape as member CL2ASSEM.
No action is required to use this file for messages in United States English. The file is provided
to be used as the basis for creation of message definitions in other languages. Refer to
Chapter 14: “Message Definitions,” for details.
System Parameter Block
Default Values
Depending on your programming environment, you use one of two possible data structures
(HSHSPB or HSHSPBC) to pass default values to DBCHINI.
232
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 5: Release Tapes
HSHSPB
In this programming
environment...
The name for the data
structure containing default
values to pass to DBCHINI
is...
z/OS batch
HSHSPB
The accessible default for applications
running in the named environments.
HSHSPBC
A block containing information to
manage globally CLIv2 memory usage.
z/OS TSO
Description
IMS/DC
CICS/VS
CICS
Used only under CICS.
As provided on the release tape or disks, the accessible structures contain 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.
The revised defaults are placed in the DBCAREA when an application calls DBCHINI.
Overriding the Defaults from an Application
In general, application programmers can override the defaults in the DBCAREA in order to
reflect conditions appropriate for the application.
The application does not directly access the HSHSPB.
The settings in the DBCAREA after calling DBCHINI are copies of the values contained in the
HSHSPB and can be modified by the program.
CLIv2 must be able to get defaults from the accessible HSHSPB. The program will fail if the
HSHSPB is not available.
HSHSPB
Where to Find HSHSPB
The HSHSPB is provided on the release tape for IBM mainframe clients.
Administration
The HSHSPB data area module is assembled by the site manager at installation.
HSHSPB can be placed in the CLIv2 runtime library, or it can be included in the application.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
233
Chapter 5: Release Tapes
HSHSPB Assembler Source
Under this operating
system...
The application can
include HSHSPB at...
If HSHSPB is...
z/OS
link time
in STEPLIB/JOBLIB/LINKLIST
Under z/OS, if HSHSPB has not been included earlier, CLIv2 will LOAD it at runtime.
The values in HSHSPB are copied to the DBCAREA when the application calls DBCHINI.
Changing Options Arguments
The application may specify values in the DBCAREA for the various option arguments before
calling DBCHCL for these functions:
•
Connect
•
RunStartUp
•
Command
•
Initiate with Protocol-Function
•
Initiate Request
The program indicates to CLIv2 that changes to the options are to be honored by setting the
value of Change Options to ‘Y‘ in the DBCAREA.
Any legal values of processing options are used by DBCHCL, and any blank values of
processing options default to the installation-specified values from the HSHSPB.
HSHSPB Assembler Source
Introduction
The HSHSPB allows default values to be specified for some DBCAREA fields. These defaults
will be used by applications that do not explicitly specify a value for those DBCAREA fields. If
an application does specify a value, that HSHSPB default will be ignored.
If a default value is changed, the HSHSPB must be assembled and link-edited. The resulting
load module will be used by any application with the resulting load module in its search order
at execution time. Any number of HSHSPBs may exist, but since all have the same module
name, only one will be used for a particular execution of any application.
The default for the following values can be safely changed for any application:
Table 6: HSHSPB Source Default Settings That Are Safe to Change
234
Keyword
Default
Description
MVSTDP
'TDP0'
The default for the Input-TDP-path (DBCNITDP) value when
executing under z/OS, chosen as an EBCDIC four-character value
beginning with TDP.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 5: Release Tapes
HSHSPB Assembler Source
Table 6: HSHSPB Source Default Settings That Are Safe to Change (continued)
Keyword
Default
Description
IBODLYW
'Y'
The default for the Wait-during-delay (DBODLYN) option, chosen as
either 'Y' or 'N'.
(The deprecated keyword IBOCRSW is equivalent to IBODLYN.)
IBOFSVB
'Y'
The default for the Save-response-buffer (DBOFSVB) option, chosen as
either 'Y' or 'N'.
IBO2FBU
'Y'
The default for the Two-response-buffers (DBO2FBU) option, chosen
as either 'Y' or 'N'.
IBORTS
'N'
The default for the return-time (DBORTS) option, chosen as either 'Y'
or 'N'.
IBCSMAX
16
The default for the Anticipated-number-of-concurrent-sessions
(DBCISMAX) value, chosen as a value between 1 and 999.
IBCRBRL
1024
The default for the Request-buffer-length (DBCIRBRL) value, chosen
as a value between 256 and 2147483639.
IBCFBRL
1024
The default for the Response-buffer-length (DBCIFBRL) value, chosen
as a value between 256 and 32767, 65535, or 2147483639. The actual
maximum depends upon the setting of the Maximum-parcel option.
IBODEN
'N'
The default for the Data-encryption (DBRIDEN) option, chosen as
either 'Y' or 'N'.
'N'
The default for the Refresh-cached-data (DBRIRCD) option, chosen as
either 'Y' or 'N'.
IBORPF
'D'
The default for the Request-parcel-format (DBRIRPF) option, chosen
as either 'A' or 'O'.
(The deprecated value 'D' is now equivalent to 'A'.)
IBOTRAK
'N'
For diagnostic use under the direction of Teradata Support personnel,
the status of internal CLIv2 tracking, chosen as either 'N', 'I', 'E', or 'A'.
IBOTRPG
0
For diagnostic use under the direction of Teradata Support personnel,
the number of 4096byte areas to be used for internal CLIv2 tracking,
chosen as a value from 0 to 255.
IBOTRCM
'00000000'
For diagnostic use under the direction of Teradata Support personnel,
the component mask for CLIv2 internal tracking, chosen as an eight
character hexadecimal value.
DUI
'N'
The default for the Delegate-user-identity value, chosen as either 'N' or
'Y'.
RCD
The default for the following values can be changed for any application, but depending on the
design of the application may result in errors indicated by the Teradata Database when the
application is executed.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
235
Chapter 5: Release Tapes
HSHSPB Assembler Source
Table 7: HSHSPB Source Default Settings That Should Probably Not Be Changed
Keyword
Default
Description
IBOKRSP
'N'
The default for the Keep-response (DBCNITSM) option, chosen as
either 'Y', 'N', or 'P'.
IBOSCS
(No default
provided)
The default for the Set-character-set (DBOSCSP) option, chosen as
either null or 'N'. The name of the character set is given by the IBCCSN
keyword.
(The deprecated value 'C' should not be used).
IBCCSN
(No default
provided)
If the Set-character-set (DBOSCSP) option is 'Y', the default for the
Character set name, chosen as one of the defined EBCDIC one to thirty
character values.
(The IBCCSC keyword is deprecated and should not be used.)
IBOTSM
'D'
The default for the Transaction-semantics (DBCNITSM) option,
chosen as either 'D', 'A', or 'T'.
IBOLCS
'N'
The default for the Language-conformance (DBCNILCS) option,
chosen as either 'N', '2', or '3'.
IBOC2SC
'D'
The default for the C2S-conversion (DBCIC2SC) option, chosen as
either 'R', 'I', or 'D'.
IBOC2SCC
'D'
The default for the S2C-conversion (DBCIS2CC) option, chosen as
either 'R', 'I', or 'D'.
IBODF
'D'
The default for the Date-form (DBCNIDF) option, chosen as either 'D',
'T', or 'A'.
LANG
'EN'
The default for the Language-id (DBCNILID) value, chosen as one of
the defined EBCDIC two-character values.
COUNTRY
(No default
provided)
The default for the Country-id (DBCNICID) value, chosen as null or
one of the defined EBCDIC two-character values.
RR
(No default
provided
The default for the Return-result-to value, chosen as either 1, 2, 3, 4, or
5.
RSO
'N'
The default for the Result-sets-OK value, chosen as either 'N' or 'Y'.
TSP
'8'
The default for the Timing-precision (DBCITSP) value, chosen as a
value between 0 and 20.
CIN
'O'
The default for the Column-info value, chosen as either 'O' or 'E'.
IBOS2CC
The default for the following values should never be changed without a detailed analysis of the
design of every affected application (that is, an application will very likely exhibit
programming errors if these defaults are changed). Defaults for these should not have been
provided but are maintained for compatibility:
236
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 5: Release Tapes
HSHSPB Assembler Source
Table 8: HSHSPB Source Default Settings That Should Never Be Changed
Keyword
Default
Description
IBORMOD
'R'
The default for the Response-mode (DBORMOD) option, chosen as
either 'F', 'R', 'M', 'I' or 'X'.
IBOIDTA
'N'
The default for the Use-presence (DBOIDTA) option, chosen as either
'Y' or 'N'.
IBODLYT
'Y'
The default for the Tell-if-delay (DBODLYT) option, chosen as either
'Y' or 'N'. (The deprecated keyword IBOCRTL is equivalent to
IBODLYT.)
IBOFLOC
'Y'
The default for the Locate-mode (DBOFLOC) option, chosen as either
'Y' or 'N'.
IBORVAR
'N'
The default for the Variable-length-request (DBORVAR) option,
chosen as either 'Y' or 'N'.
IBOFVAR
'N'
The default for the Variable-length-fetch (DBOFVAR) option, chosen
as either 'Y' or 'N'.
IBOBSYW
'Y'
The default for the Wait-for-response (DBOBSYW) option, chosen as
either 'Y' or 'N'
IBOBTPM
'Y'
The default for the Parcel-mode-fetch (DBOBTPM) option, chosen as
either 'Y' or 'N'.
IBOFUNT
'E'
The default for the Request-processing-option (DBOFUNT) option,
chosen as either 'E', 'P', 'S', or 'B'.
IBOQMOD
'P'
The default for the Request-mode (DBOQMOD) option, chosen as
either 'P' or 'B'
IBOCTYP
'R'
The default for the Connect-type (DBOCTYPE) value, chosen as either
'R' or 'C'.
IBO2PC
'N'
The default for the 2PC (DBO2PC) option, chosen as either 'Y' or 'N'.
IBOMP
'O'
The default for the Maximum-parcel (DBCIMP) option, chosen as
either 'O' or 'H'
IBOROB
'D'
The default for the Return-objects-as (DBRIROB) option, chosen as
either 'D', 'T', or 'S'.
IBOAPH
'N'
The default for the APH-response-OK (DBRIAPH) option, chosen as
either 'Y' or 'N'.
MDR
0
The default for the Max-decimal-returned (DBRIMDR) option, chosen
as any value not greater than the decimal precision value obtained using
the DBCHQE SQL-limits query. A zero is equivalent to the client
default, 18.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
237
Chapter 5: Release Tapes
HSHSPB Assembler Source
238
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 6
Common Routines
This chapter describes the three always-used CLIv2 routines. They are:
•
DBCHINI
•
DBCHCL, including its functions:
•
•
DBCHCL CON Function
•
DBCHCL RSUP Function
•
DBCHCL IRQ Function
•
DBCHCL IWPF Function
•
DBCHCL CRQ Function
•
DBCHCL CMD Function
•
DBCHCL ABT Function
•
DBCHCL FET Function
•
DBCHCL REW Function
•
DBCHCL ERQ Function
•
DBCHCL DSC Function
DBCHCLN
Other CLIv2 routines are described in:
•
Chapter 7: “Other CLIv2 Routines”
•
Chapter 8: “CLIv2 Query Routine”
Introduction
CLIv2 routines are used in the following circumstances:
•
When no preprocessor exists for the application language
•
When the application must use Teradata Database facilities not supported by the
preprocessors
Standard OS linkage conventions are required by the CLIv2 routines. The following CLIv2
routines reside in the CLIv2 library.
The functions used with DBCHCL are described sequentially under DBCHCL.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
239
Chapter 6: Common Routines
Uses of CLIv2 Parameters: Tabular Summary
Uses of CLIv2 Parameters: Tabular Summary
The following table lists the use of three most common CLIv2 routines and describes how
they are used.
Table 9: Uses of Routine and Function
Routine
Description
DBCHINI
What
Initializes the application allocated DBCAREA.
Why
Prepares for interaction with CLIv2.
What
Manages interaction with the Teradata Database; each type of interaction is called a
function
Why
Sends/receives Teradata SQL requests/responses to/from the Teradata Database.
DBCHCL
DBCHCLN
240
Function
Name
What It Represents
Use
CON
Connect
Logs a session on to the Teradata Database and
specifies a set of services
RSUP
RunStartUp
Submits a request to execute the startup request
stored on the Teradata Database
IRQ
Initiate Request
Submits a Teradata SQL request from the
application
IWPF
Initiate With
Protocol-Function
Submits a Teradata SQL request from the
application and allows Teradata Database 2PC
sync point performance optimization
CRQ
Continue Request
Provides data requested by the Teradata Database
to complete an SQL request.
CMD
Command
Issues a TDP command within a CLIv2 program
ABT
Abort
Aborts a request asynchronously
FET
Fetch
Makes available the next parcel or buffer (which
one depends on the setting of Parcel Mode) of the
Teradata SQL response
REW
Rewind
Repositions to start of Teradata SQL response
(spool file)
ERQ
End Request
Closes a Teradata SQL request and has the
Teradata Database discard the response
DSC
Disconnect
Logs off and deletes a session
What
Logs off all sessions and releases the internal CLIv2 memory areas allocated by DBCHINI
Why
To clean up after interacting with the Teradata Database
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
Summary of CLIv2 Routine Parameters
Summary of CLIv2 Routine Parameters
The following table lists the parameters for the routines in this chapter
Table 10: Parameters of CLIv2 Routines
Routine
Parameters
DBCHINI
ReturnCode Address
ContextArea Address
DBCAREA Address
DBCHCL
ReturnCode Address
ContextArea Address
DBCAREA Address
DBCHCLN
ReturnCode Address
ContextArea Address
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
241
Chapter 6: Common Routines
DBCHINI
DBCHINI
Purpose
Sets up the CLIv2 environment.
The application must provide the DBCAREA and then call DBCHINI to initialize it.
Note: The alternate six-character name for DBCHINI is DBCHIN.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHINI(ReturnCode,ContextArea,DBCAREA)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
DBCAREA
The DBCAREA structure.
Usage Notes
242
•
The application must declare or allocate the DBCAREA and call DBCHINI to initialize the
fields prior to using CLIv2 functions.
•
Total Length must be filled in by the application before calling DBCHINI. DBCHINI
verifies this value prior to any initialization attempt. The length must be at least 384, the
size of the smallest DBCAREA. If the length is at least 640, the enlarged DBCAREA will be
formatted. For lengths greater than 384 but not equal to 640, the excess is assumed to be
an application appendage to the DBCAREA: it will be zeroed by DBCHINI but is
otherwise unused by CLIv2. When not appending fields to the DBCAREA, mnemonics
should be used to set the Total-length field to the largest DBCAREA. When appending
fields to the DBCAREA, depending on the application development environment it may
be better to use hardcoded values rather than mnemonics. For example, if the total size of
the DBCAREA plus application fields must be less than some size, it might be unwise to
allow the DBCAREA size to increase.
•
DBCHINI obtains default values from the HSHSPB currently available to the application.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHINI
•
The return code will either be 0 (if the initialization is completed successfully) or 126 if the
Total Length value is insufficient for the smallest DBCAREA (384 bytes). After the call, the
return code variable contains a return code.
•
After the call, CLIv2 changes ContextArea for its own purposes.
•
DBCHINI initializes the DBCAREA allocated by the application. DBCHINI does not
initialize any DBCAREA extensions addressed by the DBCAXP DBCAREA field.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
243
Chapter 6: Common Routines
DBCHCL
DBCHCL
Purpose
Calls the functions to be used by the application.
An overview of the functions relative to DBCHCL is given in the first table in the section
“Summary of CLIv2 Routine Parameters” on page 241. Each function is described in detail
later in this chapter.
Process
Before each call to DBCHCL, the application 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, then passes back to the caller the
DBCAREA, which contains, among other things, a return code. The application checks the
return code in the DBCAREA, which is where CLIv2 and TDP indicate any problem they find.
If the call results in a delivery of parcels to the response buffer, the program checks the first
parcel, which may be one of the following:
•
Success
•
Error
•
Failure
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHCL(ReturnCode,ContextArea,DBCAREA)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
244
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
DBCAREA
The DBCAREA structure.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL
Usage Notes
•
Before DBCHCL is called, the application must have called DBCHINI to initialize the
DBCAREA to be used by DBCHCL.
•
After the call, CLIv2 will change ContextArea for its own purposes.
•
The DBCAREA address must always be passed to DBCHCL.
•
•
•
In addition, the function code must be supplied.
•
Other fields in the DBCAREA must be set as appropriate to the function requested.
If Wait for Response is set to N (set and used by the Connect, Initiate Request, Command,
Initiate with Protocol, and RunStartUp functions; used by the Fetch, Abort, Rewind, End
Request, and Disconnect functions) and CLIv2 is waiting for a response from the Teradata
Database, the application will receive a return code of 150 (busy).
•
The application may handle the busy response by calling routine DBCHWAT and
waiting for control to return to the application.
•
If the return code is 0, resubmit the DBCHCL function that initially returned the busy
indication.
If Return Code is nonzero for any function, the Message Length and Message Text fields of
the DBCAREA will be set.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
245
Chapter 6: Common Routines
DBCHCL Functions
DBCHCL Functions
This section describes the DBCHCL functions listed below.
Function Name
Description
CON
Connect
RSUP
RunStartUp Request
IRQ
Initiate Request
IWPF
Initiate With Protocol-Function
CRQ
Continue Request
CMD
Command
ABT
Abort
FET
Fetch
REW
Rewind and Fetch
ERQ
End Request
DSC
Disconnect
General Notes
For each function, there is a list of the required and optional input and output arguments and
a general description of how DBCHCL processes the function.
The interpretation of some of the arguments may depend on the setting of the DBCAREA
options (for more information, see “Setting DBCAREA Options” on page 48.
For instance, input/output string pointers may 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.
246
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL CON Function
DBCHCL CON Function
Purpose
CON (Connect) logs on to the Teradata Database and arranges to have the specified services
available for all requests on that session.
Connect also allocates internal control structures that CLIv2 uses to store session context.
Usage Notes
•
If no Logon String is supplied or logon mechanism, a TDP logon exit must furnish the
necessary information to complete the logon request. If a TDP logon exit does not exist or
is disabled, the connect will be rejected by TDP.
•
The application should call the ERQ function after processing the CON function,
regardless of the success or failure of the connect. This releases internal resources used
during connect processing.
•
DSC must be performed for each CON request. If the CON results in a nonzero return
code, DSC should be called immediately. Otherwise, DSC should be called when the
application has completed all work for the session.
•
If Return Code is 0, the application must invoke the FET function to obtain the final status
of the connect call.
•
•
•
If Connect Type was R, the FET call results in a Return Code of 33 if the connect was
successful.
•
If Connect Type was C, the parcels must be processed to determine success or failure
of the connect.
The FET returns three additional DBCAREA fields set only when CON is being processed.
These fields are:
•
Output TDP Path
•
Output TDP Session Id
•
Output Host Id.
Additional fields will be set as normal by the FET call.
For a discussion of the call and the fields used, see “DBCHCL FET Function” on page 265.
DBCAREA Input Fields
Before using the Connect function, the application must set the DBCAREA fields in the first
table and may optionally set those in the second table depending on the application's
requirements.
Table 11: DBCAREA Input Fields Required for the Connect Function
DBCAREA Input Fields Required for the Connect Function
Function
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
247
Chapter 6: Common Routines
DBCHCL CON Function
Table 12: DBCAREA Input Fields Optional for the Connect Function
DBCAREA Input Fields Optional for the Connect Function
2PC
Anticipated Number of Concurrent Sessions
Change Options
Character Set Pointer
Connect Type
Country Id
C2S Conversion
Data-encryption
Date Form
Delegate-user-identity
Input TDP Path
Keep Response
Language Conformance
Language Id
Locate Mode
Logon Length
Mechanism-data-encoding
Mechanism-data-len
Mechanism-data-ptr
Mechanism-name
Logon Pointer
Maximum Parcel
Message Area Pointer
Message Area Length
Parcel Mode
Request Buffer Length
Request Processing Option
Response Buffer Length
Response Mode
Request Mode
Request-parcel-format
Request-token
Return Time
Run Length
Run Pointer
Save Response Buffer
Session-desc-length
Session-desc-pointer
Set Character Set
Statement-status
S2C Conversion
Tell if Delay
Transaction Semantics
Two Response Buffers
Use-default-conn
Use Presence Bits
Utility-workload
Variable Length Fetch
Variable Length Request
Wait During Delay
Wait-exclusion
Wait For Response
Workload-length
Workload-pointer
DBCAREA Output Fields
Upon completion of the Connect function, CLIv2 will always set DBCAREA fields
in the first table and will set those in the second table if the function was successful.
248
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL CON Function
Table 13: DBCAREA Output Fields Always Set for the Connect Functions
DBCAREA Output Fields Always Set for the Connect Functions
Message Return Code
Message Length
Message Text
Message Text Length
Current Response Buffer Length
Output CLIv2 Request Id
Output CLIv2 Connection Id
Return Code
Table 14: DBCAREA Output Fields Set by Successful Connect Functions
DBCAREA Output Fields Set by Successful Connect Functions
Current Request Buffer Length
Mechanism-name
Open Requests
Session Status
TDP Request Number
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
249
Chapter 6: Common Routines
DBCHCL RSUP Function
DBCHCL RSUP Function
Purpose
RSUP (RunStartUp) sends a request to the Teradata Database to execute the startup request
stored on the Teradata Database.
Usage Notes
•
The application should call the ERQ function after processing RunStartUp, regardless of
the success or failure of the startup. This will release internal resources used during startup
processing.
•
If RunStartUp is called without first calling Connect, RunStartUp will perform the
Connect. In this case, the information needed for a Connect call should be supplied when
doing the RunStartUp call.
•
If Return Code is 0, the application must invoke the FET function to process the response.
DBCAREA Input Fields
Before using the Run Start-up function, the application must set the DBCAREA fields in the
first table and may optionally set those in the second table depending on the application's
requirements.
Table 15: DBCAREA Input Fields Required for the RunStartup Function
DBCAREA Input Fields Required for the RunStartup Function
Function
Input CLIv2 Connection Id
Table 16: DBCAREA Output Fields Optional for the RunStartup Function
DBCAREA Output Fields Optional for the RunStartup Function
250
Anticipated Number of Concurrent Sessions
APH-response-OK
Change Options
Column-info
C2S Conversion
Continued-character-state
Data-encryption
Input TDP Path
Keep Response
Locate Mode
Logon Length
Logon Pointer
Max-decimal-returned
Maximum Parcel
Parcel Mode
Period-as-Struct
Refresh-cached-data
Request Buffer Length
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL RSUP Function
Table 16: DBCAREA Output Fields Optional for the RunStartup Function (continued)
DBCAREA Output Fields Optional for the RunStartup Function
Request-parcel-format
Request Processing Option
Request-token
Response Buffer Length
Response Mode
Return Time
Return-identity-data
Result-sets-OK
Return-result-to
Return-statement-info
Run Length
Run Pointer
Save Response Buffer
S2C Conversion
Tell if Delay
Transforms-off
Trusted-requestf
Two Response Buffers
Use Presence Bits
Variable Length Request
Variable Length Fetch
Wait During Delay
Wait-exclusion
Wait For Response
DBCAREA Output Fields
Upon completion of the Run Start-up function, CLIv2 will always set DBCAREA fields in the
first table and will set those in the second table if the function was successful.
Table 17: DBCAREA Output Fields Always Set by the RunStartup Function
DBCAREA Output Fields Always Set by the RunStartup Function
Current Response Buffer Length
Message Return Code
Message Text
Message Text Length
Output CLIv2 Request Id
Return Code
Table 18: DBCAREA Output Fields Set by Successful RunStartup Functions
DBCAREA Output Fields Set by Successful RunStartup Functions
Current Request Buffer Length
Message Return Code
Message Text
Message Text Length
Open Requests
TDP Request Number
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
251
Chapter 6: Common Routines
DBCHCL IRQ Function
DBCHCL IRQ Function
Purpose
IRQ (Initiate Request) sends a request to the Teradata Database to be processed.
Usage Notes
•
If Initiate Request is called without first calling CON, Initiate Request performs the CON.
In this case, the information needed for a CON call should be supplied when doing the
Initiate Request call.
•
If Return Code is 0, the application must invoke the FET function to process the response.
Once the response has been totally processed, the application must invoke the ERQ
function to release resources used by the Initiate Request.
•
When initiating a request in a 2PC session, Initiate Request will be rejected if the session
has a 2PC vote or terminate activity in progress.
•
Once started, activities such as vote and terminate must be completed by the
coordinator.
•
The vote can result from a previous Initiate with Protocol-Function (IWPF) function.
•
The terminate could have resulted from an Abort or Logoff or from any response that
contained a Failure parcel.
•
If any of these occur, the coordinator must be requested to perform a syncpoint.
DBCAREA Input Fields
Before using the Initiate Request function, the application must set the DBCAREA fields in
the first table and may optionally set those in the second table depending on the application's
requirements.
Table 19: DBCAREA Input Fields Required for the Initiate Request Function
DBCAREA Input Fields Required for the Initiate Request Function
Function
Input CLIv2 Connection Id
Request Length
Request Pointer
Table 20: DBCAREA Input Fields Optional for the Initiate Request Function
DBCAREA Input Fields Optional for the Initiate Request Function
252
Anticipated Number of Concurrent Sessions
APH-response-OK
Change Options
Character Set
C2S Conversion
Column-info
Continued-character-state
Data-encryption
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL IRQ Function
Table 20: DBCAREA Input Fields Optional for the Initiate Request Function (continued)
DBCAREA Input Fields Optional for the Initiate Request Function
Extension Pointer
Input TDP Path
Keep Response
Locate Mode
Logon Length
Logon Pointer
Max-decimal-returned
Maximum Parcel
Message Area Length
Message Area Pointer
Parcel Mode
Period-as-Struct
Pointer
Refresh-cached-data
Request Buffer Length
Request Mode
Request-parcel-format
Request Processing Option
Request-token
Response Buffer Length
Response Mode
Result-sets-OK
Return-identity-data
Return-result-to
Return-statement-info
Return Time
Run Length
Run Pointer
Save Response Buffer
Session Id
Set Character Set
Statement-status
S2C Conversion
Tell if Delay
Transforms-off
Trusted-requestf
Two Response Buffers
Using Data Pointer
Using Data Length
Use Presence Bits
Variable Length Fetch
Variable Length Request
Wait During Delay
Wait-exclusion
Wait For Response
DBCAREA Output Fields
Upon completion of the Initiate Request function, CLIv2 will always set DBCAREA fields in
the first table and will set those in the second table if the function was successful.
DBCAREA Output Fields always set by the Initiate Request Function
Current Response Buffer Length
Message Return Code
Message Text
Message Text Length
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
253
Chapter 6: Common Routines
DBCHCL IRQ Function
DBCAREA Output Fields always set by the Initiate Request Function
Output CLIv2 Request Id
Return Code
DBCAREA Output Fields set by Successful Initiate Request Functions
Current Request Buffer Length
Open Requests
TDP Request Number
254
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL IWPF Function
DBCHCL IWPF Function
Purpose
IWPF (Initiate with Protocol-Function) enables an application to send a request to the
Teradata Database.
It contains additional protocol functions for 2PC sessions, for use in specialized applications.
Note: This function can not be used when ANSI transaction semantics are enabled.
Usage Notes
•
A 2PC request can be initiated using the Initiate with Protocol-Function.
•
The IWPF function is similar to the Initiate Request (Initiate Request) function, except for
the following differences:
•
•
IWPF does not support the Locate mode.
•
When IWPF is used with 2PC sessions, the additional protocol functions of vote, and
vote and terminate can be used to optimize syncpoint processing in specialized
applications.
In IWPF, you can set the following:
Code
Meaning
N
No protocol function.
This is the default.
V
Vote protocol function to be appended.
T
Vote & Terminate protocol function to be appended.
DBCAREA Input Fields
Before using the Initiate With Protocol-function function, the application must set the
DBCAREA fields in the first table and may optionally set those in the second table depending
on the application's requirements.
Table 21: DBCAREA Input Fields Required for Initiate With Protocol-function
DBCAREA Input Fields Required for the Initiate With Protocol-function Function
Function
Input CLIv2 Connection Id
Request Length
Request Pointer
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
255
Chapter 6: Common Routines
DBCHCL IWPF Function
Table 22: DBCAREA Input Fields Optional for Initiate With Protocol-function
DBCAREA Input Fields Optional for the Initiate With Protocol-function Function
Anticipated Number of Concurrent Sessions
APH-response-OK
Change Options
Character Set
C2S Conversion
Column-info
Continued-character-state
Extension Pointer
Input TDP Path
Keep Response
Length
Logon Length
Logon Pointer
Max-decimal-returned
Maximum Parcel
Message Area Length
Message Area Pointer
Parcel Mode
Period-as-Struct
Pointer
Protocol Function
Refresh-cached-data
Request Buffer Length
Request Mode
Request-parcel-format
Request Processing Option
Request-token
Response Buffer
Response Mode
Result-sets-OK
Return-identity-data
Return-result-to
Return-statement-info
Return Time
Run Length
Run Pointer
Save Response Buffer
Session Id
Set Character Set
Statement-status
S2C Conversion
Tell if Delay
Transforms-off
Trusted-requestf
Two Response Buffers
Using Data Length
Using Data Pointer
Use Presence Bits
Variable Length Fetch
Variable Length Request
Wait During Delay
Wait-exclusion
Wait For Response
256
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL IWPF Function
DBCAREA Output Fields
Upon completion of the Initiate With Protocol-function function, CLIv2 will always set
DBCAREA fields in the first table and will set those in the second table if the function was
successful.
Table 23: DBCAREA Output Fields always set by Initiate With Protocol-function
DBCAREA Output Fields always set by the Initiate With Protocol-function Function
Message Return Code
Current Response Buffer Length
Message Length
Message Text
Message Text Length
Output CLIv2 Request Id
Return Code
Table 24: DBCAREA Output Fields Set by Successful Initiate With Protocol-function
DBCAREA Output Fields set by Successful Initiate With Protocol-function Functions
Current Request Buffer Length
Open Requests
TDP Request Number
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
257
Chapter 6: Common Routines
DBCHCL CRQ Function
DBCHCL CRQ Function
Purpose
CRQ (Continue Request) sends data requested by the Teradata Database to complete an SQL
request. The need for such completion must be indicated by one of the following SQL
requests:
•
A USING row descriptor that specifies CLOB or BLOB AS DEFERRED. The result is an
ElicitData parcel in the response that contains the token specified as the Using-data for the
AS DEFERRED field.
•
A CREATE or REPLACE for an executable item, such as FUNCTION, that specifies the
EXTERNAL NAME clause. The result is one of the following:
•
An ElicitFile parcel that contains the filename specified by the EXTERNAL clause.
•
An ElicitName parcel in the response which contains the name specified in the BY
NAME phrase.
When either parcel is received, the application then sends data to complete the SQL request
using the ContinueRequest function.
Usage Notes
The application should call the CRQ function after processing an ElicitData or ElicitFile
response parcel. If return Code is zero, the application must invoke the FET function to
process the response. If more data exists, these steps are repeated as many times as necessary.
DBCAREA Input Fields
Before using the Continue Request function, the application must set the DBCAREA fields in
the first table and may optionally set those in the second table depending on the application's
requirements.
Table 25: DBCAREA Input Fields Required for the Continue Request Function
DBCAREA Input Fields Required for the Continue Request Function
Continued-data
Function
Input CLIv2 Connection Id
Input CLIv2 Request Id
Request Length
Request Pointer
When processing an ElicitData parcel, the Request-pointer addresses data for the Large Object
(LOB). The LOB begins with an 8-byte unsigned integer that contains the length, in bytes, of
the data. If the length is not known when the start of the LOB is sent, the length field might be
zero.
When processing an executable item, the Request-pointer addresses its statements, which do
not begin with a length field.
258
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL CRQ Function
Table 26: DBCAREA Input Fields Optional for the Continue Request Function
DBCAREA Input Fields Optional for the Continue Request Function
Change Options
C2S Conversion
Fetch Buffer Length
Locate Mode
Maximum Parcel
Message Area Length
Message Area Pointer
DBCAREA Output Fields
Upon completion of the Continue Request function, CLIv2 will always set DBCAREA fields in
the first table and will set those in the second table if the function was successful.
Table 27: DBCAREA Output Fields always set by the Continue Request Function
DBCAREA Output Fields always set by the Continue Request Function
Message Length
Message Return Code
Message Return Code
Message Text
Message Text Length
Message Return Code
Return Code
Table 28: DBCAREA Output Fields set by Successful Continue Request Functions
DBCAREA Output Fields set by Successful Continue Request Functions
Current Request Buffer Length
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Current Response Buffer Length
259
Chapter 6: Common Routines
DBCHCL CMD Function
DBCHCL CMD Function
Purpose
CMD (Command) issues a TDP command within a CLIv2 program.
This function is used to send the TDP command, specifying a buffer and length that contain
the command text.
Usage Notes
•
Use the CMD function to send a TDP command, specifying a buffer and length for the
command text.
•
If the Return Code is 0, a pseudo-connection number and a request number are returned.
To process the response, issue a FETch function with the returned pseudo-connection
number and request number.
The response data is composed of various parcels in the following order:
1
A Success parcel with an activity count that indicates the number of subsequent Record
parcels
2
The Record parcels themselves (one Record parcel for each line of command output)
3
An End Statement parcel
4
An End Request parcel
•
Once the response has been completely processed, the application must invoke the ERQ
function to release the fetch buffer used by the CMD.
Since the application doesn‘t establish a connection, no DISCONN function may be used
for the pseudo-connection number. Rewind and Abort functions are not supported.
If the specified response buffer is too small for the entire response, a code of 535 is
returned, either as a warning code in the Success parcel or as a return code from the CLIv2
call.
DBCAREA Input Fields
Before using the Command function, the application must set the DBCAREA fields in the first
table and may optionally set those in the second table depending on the application's
requirements.
Table 29: DBCAREA Input Fields Required for the Command Function
DBCAREA Input Fields Required for the Command Function
Function
260
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL CMD Function
Table 30: DBCAREA Input Fields Optional for the Command Function
DBCAREA Input Fields Optional for the Command Function
Anticipated Number of Concurrent Sessions
Change Options
Character Set
Input TDP Path
Length
Locate Mode
Maximum Parcel
Message Area Length
Message Area Pointer
Parcel Mode
Pointer
Request Buffer
Request Length
Request Mode
Request Pointer
Request Processing Option
Response Buffer Length
Response Mode
Return Time
Set Character Set
Tell if Delay
Request-token
Two Response Buffers
Use Presence Bits
Variable Length Fetch
Variable Length Request
Wait During Delay
Wait-exclusion
Wait For Response
DBCAREA Output Fields
Upon completion of the Command function, CLIv2 will always set DBCAREA fields in the
first table and will set those in the second table if the function was successful.
Table 31: DBCAREA Output Fields always set by the Command Function
DBCAREA Output Fields always set by the Command Function
Current Response Buffer Length
Message Length
Message Return Code
Message Text
Message Text Length
Output CLIv2 Request Id
Output CLIv2 Connection Id
Return Code
Table 32: DBCAREA Output Fields set by Successful Command Functions
DBCAREA Output Fields set by Successful Command Functions
Current Request Buffer Length
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Open Requests
261
Chapter 6: Common Routines
DBCHCL CMD Function
Table 32: DBCAREA Output Fields set by Successful Command Functions (continued)
DBCAREA Output Fields set by Successful Command Functions
TDP Request Number
262
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL ABT Function
DBCHCL ABT Function
Purpose
ABT (Abort) attempts to abort a request and the transaction in which it is embedded. This is
known as an asynchronous abort.
Abort may be used within an External Stored Procedure to indicate that the results of a
request initiated with the DBCAREA Return-result-to option will not be reflected to the
CALLer or the application.
Usage Notes
•
If the Return Code is 0, the abort has been sent to the Teradata Database. However, 0 does
not mean the request has been aborted. The application must perform FET to check the
final disposition of the original request and ERQ to release the request context.
•
If the abort reaches the Teradata Database before it completes the request, the request will
be aborted and the containing transaction rolled back. Storage associated with the request
is kept until ERQ is issued for the request.
•
If the abort reaches the Teradata Database after the request has completed, the abort is
ignored.
•
If the application has an active transaction and is between requests, issue Initiate Request
with a ROLLBACK statement rather than calling ABT to perform the abort.
•
If the session is running in 2PC mode, ABT ensures that the current session is aborted at
syncpoint. This occurs even if the abort had no effect (for example, if the request
completed before ABT could abort it).
DBCAREA Input Fields
Before using the Abort function, the application must set the DBCAREA fields in the first
table and may optionally set those in the second table depending on the application's
requirements.
DBCAREA Input Fields Required for the Abort Function
Function
Input CLIv2 Request Id
Input CLIv2 Connection Id
DBCAREA Input Fields Optional for the Abort Function
Message Area Length
Message Area Pointer
DBCAREA Output Fields
Upon completion of the Abort function, CLIv2 will always set DBCAREA fields in the table.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
263
Chapter 6: Common Routines
DBCHCL ABT Function
DBCAREA Output Fields always set by the Abort Function
Message Return Code
Message Length
Message Text
Message Text Length
Return Code
264
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL FET Function
DBCHCL FET Function
Purpose
FET (Fetch) delivers a pointer to the next parcel of the response.
Usage Notes
•
If Return Code is 0, the application may process the response from the Teradata Database.
FET may be invoked repeatedly until the entire response has been processed.
•
For 2PC sessions, Fetch ensures that the current session is aborted at syncpoint if a failure
parcel is received in response to a request.
•
In addition, the first FET after a CON call will return the following fields:
•
Output TDP Path
•
Output TDP Session Id
•
Output Host Id
DBCAREA Input Fields
Before using the Fetch function, the application must set the DBCAREA fields in the first table
and may optionally set those in the second table depending on the application's requirements.
DBCAREA Input Fields Required for the Fetch Function
Function
Input CLIv2 Connection Id
Input CLIv2 Request Id
DBCAREA Input Fields Optional for the Fetch Function
Fetch Data Pointer
Fetch Maximum Data Length
Message Area Length
Message Area Pointer
Positioning-action
Positioning-statement-number
Positioning-value
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
265
Chapter 6: Common Routines
DBCHCL FET Function
DBCAREA Output Fields
Upon completion of the Fetch function, CLIv2 will always set DBCAREA fields in the first
table and will set those in the second table if the function was successful.
Table 33: DBCAREA Output Fields always set by the Fetch Function
DBCAREA Output Fields always set by the Fetch Function
Current Response
Return Code
Session Status
Message Length
Message Return Code
Message Text
Table 34: DBCAREA Output Fields set by Successful Fetch Functions
DBCAREA Output Fields set by Successful Fetch Functions
Buffer Length
Data Length
Fetch Data Pointer
Fetch Parcel Flavor
Fetch Returned
Message Text Length
Output TDP
Output Host Id
TDP-receipt-timestamp
Time1
Time1-status
Time2
Time2-status
Time3
Time3-status
Time4
Time4-status
Time5
Time5-status
266
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL ERQ Function
DBCHCL ERQ Function
Purpose
ERQ (End Request) explicitly closes a request, discard its response, and deallocated internal
data structures related to the request.
Usage Notes
•
If Return Code is 0, the ERQ has successfully completed.
•
CLIv2 will keep the response buffer if Save Response Buffer was Y when the request was
submitted. This permits CLIv2 to reuse the response buffer for the next Initiate Request
without allocating a new one.
DBCAREA Input Fields
Before using the End Request function, the application must set the DBCAREA fields in the
first table and may optionally set those in the second table depending on the application's
requirements.
Table 35: DBCAREA Input Fields Required for the EndRequest Function
DBCAREA Input Fields Required for the EndRequest Function
Function
Input CLIv2 Request Id
Input CLIv2 Connection Id
Table 36: DBCAREA Input Fields Optional for the EndRequest Functions
DBCAREA Input Fields Optional for the EndRequest Functions
Message Area Length
Message Area Pointer
DBCAREA Output Fields
Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the
first table and will set those in the second table if the function was successful.
Table 37: DBCAREA Output Fields Always Set for the EndRequest Function
DBCAREA Output Fields Always Set for the EndRequest Function
Message Text
Message Length
Message Text Length
Return Code
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
267
Chapter 6: Common Routines
DBCHCL ERQ Function
Table 38: DBCAREA Output Fields Set by Successful EndRequest Functions
DBCAREA Output Fields Set by Successful EndRequest Functions
Open Requests
268
Message Return Code
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCL REW Function
DBCHCL REW Function
Purpose
REW (Rewind) repositions to the beginning of the response from the Teradata Database.
Keep Response must have been set to Y at the time of the Initiate Request for the request.
Since Keep-response does not apply to Connect requests, the response to a Connect cannot be
rewound.
Usage Notes
If Return Code is 0, the application may use FET to process the response.
DBCAREA Input Fields
Before using the Rewind function, the application must set the DBCAREA fields in the first
table and may optionally set those in the second table depending on the application's
requirements.
DBCAREA Input Fields Required for the Rewind Function
Function
Input CLIv2 Request Id
Input CLIv2 Connection Id
DBCAREA Input Fields Optional for the Rewind Function
Message Area Length
Message Area Pointer
DBCAREA Output Fields
Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the
first table and will set those in the second table if the function was successful.
DBCAREA Output Fields always set by the Rewind Function
Message Return Code
Message Text
Message Length
Message Text Length
Return Code
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
269
Chapter 6: Common Routines
DBCHCL DSC Function
DBCHCL DSC Function
Purpose
DSC (Disconnect) logs a session off the Teradata Database.
Usage Notes
•
Check the Return Code; if zero, the disconnect was successfully completed.
•
If the session has a pending request, a return code of 336 (request may be aborted) is
returned to the application. The session is still logged off but the response is lost.
•
If there is an active transaction at the time of the DSC, the Teradata Database rolls back
all work performed within that transaction prior to completing the logoff.
•
DSC should be used to clean up session context even if the connect was not successful
(initial or final status).
•
In 2PC mode, Disconnect ensures that the current session is aborted at syncpoint if the
session has performed any uncommitted Teradata SQL requests.
DBCAREA Input Fields
Before using the Disconnect function, the application must set the DBCAREA fields in the
first table and may optionally set those in the second table depending on the application's
requirements.
DBCAREA Input Fields Required for the Disconnect Function
Function
Input CLIv2 Connection Id
DBCAREA Input Fields Optional for the Disconnect Function
Message Area Length
Message Area Pointer
DBCAREA Output Fields
Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the
table.
DBCAREA Output Fields always set by the Disconnect Function
270
Message Return Code
Message Lenth
Message Text
Message Text Lenth
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common Routines
DBCHCLN
DBCHCLN
Purpose
Logs off all sessions and free all internal memory and context information allocated by CLIv2.
Note: The alternate six-character name for DBCHCLN is DBCHCN.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHCLN(ReturnCode,ContextArea)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
Usage Notes
•
The application invokes the DBCHCLN routine when all processing requiring interfacing
with the Teradata Database is complete.
•
DBCHCLN does the following:
•
logs off any idle sessions
•
awaits completion of any active sessions and then logs them off
•
frees all internal memory and context information allocated by CLIv2.
•
DBCHCLN deallocates internal data structures that were allocated by DBCHINI.
•
DBCHCLN returns control to the application once all sessions have been logged off and
all internal context has been cleaned up.
•
After control returns from DBCHCLN, the variable contains a code whose value
represents success or failure to clean up.
A return code of zero indicates success.
A nonzero return code indicates failure, and the value specifies the reason for the failure.
After the call, the return code variable will contain a return code.
•
After the call, CLIv2 changes ContextArea for its own purposes.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
271
Chapter 6: Common Routines
DBCHCLN
•
The call to DBCHCLN does not deallocate the DBCAREA.
The application may itself deallocate the DBCAREA if the programming language
provides that ability.
•
272
Termination of the application has the same effect as DBCHCLN, but it is good
programming practice to call DBCHCLN for cleanup.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 7
Other CLIv2 Routines
This chapter describes the following CLIv2 routines:
•
DBCHME
•
DBCHMEC
•
DBCHPEC
•
DBCHSAD
•
DBCHUE
•
DBCHUEC
•
DBCHWAT
•
DBCHWL
The CLIv2 query routine is described in Chapter 8: “CLIv2 Query Routine”.
Uses of CLIv2 Routines: Tabular Summary
Table 39 lists the remaining routines and describes how they are used.
Table 39: Uses of CLIv2 Routines
Routine
Description
DBCHME
What
Adds master event in place of session event
Why
For the convenience of the application
What
A deprecated routine now replaced by DBCHME.
Why
For the convenience of the application
What
Posts an ECB
Why
To return control to the application when some event occurs (like
terminal attention)
Why
To enable the application to obtain environmental information
What
Stores specified value at specified address
Why
To provide pointer support in languages that do not support pointer
manipulation
DBCHMEC
DBCHPEC
DBCHSAD
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
273
Chapter 7: Other CLIv2 Routines
Parameters of CLIv2 Routines: Tabular Summary
Table 39: Uses of CLIv2 Routines (continued)
Routine
Description
What
Adds user-provided event to CLIv2‘s internal wait list
Why
To set up a way for the application to regain control if some event is
detected (like terminal attention)
What
A deprecated routine now replaced by DBCHUE.
Why
To set up a way for the application to regain control if some event is
detected (like terminal attention)
What
Waits for event to occur (an event refers to the arrival of some response
from the Teradata Database)
DBCHUE
DBCHUEC
DBCHWAT
If DBCHUE has been invoked, an event also refers to the occurrence of
some application-defined event
DBCHWL
Why
To provide a mechanism for explicit waits for events; also simplifies
handling of concurrent sessions
What
Waits for one of a list of events to occur.
Why
To provide a mechanism to explicitly wait for only some events.
Parameters of CLIv2 Routines: Tabular
Summary
Table 40 lists the parameters for the routines described in this chapter.
Table 40: Parameters of CLIv2 Routines
Routines
Parameters
DBCHME
ReturnCode
ContextArea
MasterECB
Parameter Area
DBCHMEC
ReturnCode
ContextArea
MasterECB
DBCHPEC
ReturnCode
UserECB
274
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 Routines
Parameters of CLIv2 Routines: Tabular Summary
Table 40: Parameters of CLIv2 Routines (continued)
Routines
Parameters
DBCHSAD
ReturnCode
Target Address
Source Value
DBCHUE
ReturnCode
Context Area
UserECB
Parameter Area
DBCHUEC
ReturnCode
Context Area
UserECB
DBCHWAT
ReturnCode
ContextArea
ConnectionNumber
Request-token
DBCHWL
ReturnCode
ContextArea
SessionList
ConnectionNumber
Request-token
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
275
Chapter 7: Other CLIv2 Routines
DBCHME
DBCHME
Purpose
Called by the application to establish a master event in place of individual session events.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHME(ReturnCode,ContextArea,MasterECB,FunctionCode)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
MasterECB
When defining a master event (DBCHMEP function code 1), the area
allocated by the application for use as the master ECB.
When deleting a master event (DBCHMEP function code 2), this parameter
must be present but is not used by DBCHME.
FunctionCode
The DBCHMEP area.
Usage Notes
•
Set Wait For Response to N.
•
DBCHME may only be used when no sessions exist; that is, either before any session has
been connected or after all sessions have been disconnected.
•
After the call, the return code variable contains a return code.
•
After the call, CLIv2 changes ContextArea for its own purposes.
For more information on ECBs, see IBM manuals.
Master Event Parameters (MEP)
The following table defines the DBCHMEP area. The field is set by the application.
The field names in all languages are the same, except that the C field names are case-sensitive.
276
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 Routines
DBCHME
Field Name
Offset
Length
Description
MEPFUNC
(mepFunc)
00
4
Unsigned numeric function to be performed.
Valid function codes and their descriptions are listed in the
table following this table.
The MEPFUNC Field
In the MEPFUNC field, the following are valid function codes:
Function Code
Name
Mnemonic for All
Languages, Including C
Description
1
Define
MEPFDEF
Define a master event.
2
Delete
MEPFDEL
Delete a master event.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
277
Chapter 7: Other CLIv2 Routines
DBCHMEC
DBCHMEC
Purpose
A deprecated routine now replaced by DBCHME.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHMEC(ReturnCode,ContextArea,MasterECB)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
278
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
MasterECB
The area allocated by the application for use as the master ECB.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 Routines
DBCHPEC
DBCHPEC
Purpose
Posts an ECB, including the one established by DBCHUE.
Note: The alternate six-character name for DBCHPEC is DBCHPE.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHPEC(ReturnCode,ECB)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ECB
The application allocated area for use as the ECB.
Usage Notes
•
After control returns from DBCHPEC, the variable contains a code whose value
represents success or failure. A return code of zero indicates success, a nonzero return
code indicates failure, and the value specifies the reason for the failure.
•
After the call, the return code variable contains a return code.
•
For more information on ECBs, see IBM manuals.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
279
Chapter 7: Other CLIv2 Routines
DBCHSAD
DBCHSAD
Purpose
Stores the address of a variable at a specified location.
Note: The alternate six-character name for DBCHSAD is DBCHSA.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHSAD(ReturnCode,Target,Source)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
Target
The area where the source address will be stored.
Source
Address to be stored.
Usage Notes
DBCHSAD is intended for use in COBOL and other languages that do not support pointer
manipulation.
280
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 Routines
DBCHUE
DBCHUE
Purpose
Called by the application to add a user-provided event to CLIv2‘s internal wait list.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHUE(ReturnCode,ContextArea,User event,DBCHUEP)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
UserECB
When defining a user event (DBCHUEP function code 1), address of the
application allocated area for use as the User ECB. When deleting a user event
(DBCHUEP function code 2), this parameter must be present but is not used
by DBCHUE.
DBCHUEP
User Event Parameters (UEP)
Usage Notes
•
Only one User ECB is honored at a time; only the last one added has an effect.
•
For compatibility with the DBCHUEC service, the User ECB may be deleted by specifying
a User ECB address of binary zeroes. The preferred method to delete a user event is to use
a function code of 2.
•
The User ECB remains in effect until explicitly removed.
•
CLIv2 reflects the completion of the event associated with the User ECB by a return code
of 160. Any time CLIv2 must wait for the completion of an event, the User ECB is checked.
Before reflecting this return code to the application, the indicator that it has been posted
in the User ECB is cleared.
•
After the call, the return code variable will contain a return code.
•
After the call, CLIv2 will change ContextArea for its own purposes.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
281
Chapter 7: Other CLIv2 Routines
DBCHUE
User Event Parameters
The following table defines the DBCHUEP area. The field is set by the application.
The field names in all languages are the same, except that the C field names are case-sensitive.
Field Name
Offset
Length
Description
UEPFUNC
(uepFunc)
00
4
Unsigned numeric function to be performed.
Valid function codes and their descriptions are listed in
the table following this table.
The UEPFUNC Field
In the UEPFUNC field, the following are valid function codes:
282
Function
Code
Name
Mnemonic for All
Languages, Including C
Description
1
Define
UEPFDEF
Define a user event.
2
Delete
UEPFDEL
Delete a user event.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 Routines
DBCHUEC
DBCHUEC
Purpose
A deprecated routine now replaced by DBCHUE.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHUEC(ReturnCode,ContextArea,UserECB)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
UserECB
The application allocated area for use as the User ECB.
For CICS applications, the User ECB must be in SHARED storage.
Usage Notes
The user ECB may be cancelled by specifying a User ECB address of binary zeroes.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
283
Chapter 7: Other CLIv2 Routines
DBCHWAT
DBCHWAT
Purpose
Waits for an event, such as the arrival of a response from the Teradata Database or some other
occurrence defined by the application.
Note: The alternate six-character name for DBCHWAT is DBCHWT.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHWAT(ReturnCode,ContextArea,ConnectionNumber,Request-token)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed
by CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
ConnectionNumber
An area to receive a four-byte unsigned integer representing the logical
session id of the first active request to complete.
Request-token
An area to receive a four-byte unsigned integer user-supplied token
associated with the first active request to complete.
Usage Notes
•
Each call to DBCHWAT reflects completion of one event. If multiple events have
completed, none are lost. Rather, their completions are reflected on subsequent calls to
DBCHWAT. Each completed event is reflected only once.
For example, if two events complete, the first call to DBCHWAT reflects one event, the
second call reflects the second event, and the third call waits for completion of another
event, if any responses are pending. When multiple responses have arrived, they are
reflected to the application in the order in which their requests were initiated, not the
order in which they arrived. This ensures that repeated use of a request that completes
quickly does not prevent reflection of longer-running responses.
•
284
If DBCHUE has been used to provide a User-event, its completion is reflected before the
arrival of any response.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 Routines
DBCHWAT
•
DBCHWAT is normally used when an application has multiple sessions, allowing the
application to be notified immediately of the first completion.
•
If there are no responses whose arrival is pending, a return code 123 results. If DBCHUE
has been used to provide a User-event, it is ignored. That is, when there are no pending
responses, the User-event is neither checked for completion nor does suspension occur for
the event's completion. A User-event is honored only when a request has been issued but
not yet completed.
•
When the DBCHME service has been used to include Teradata requests in another event,
DBCHWAT never waits. If no events have completed, a return code 162 is reflected,
allowing the application to wait for the master event using an operating system service.
•
After the call, the return code variable contains a return code.
•
After the call, CLIv2 changes ContextArea for its own purposes.
•
Requests for sessions that specify the Wait-exclusion option are ignored by DBCHWAT.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
285
Chapter 7: Other CLIv2 Routines
DBCHWL
DBCHWL
Purpose
Waits for one of a list of events, such as the completion of a response from the Teradata
Database or some user event defined by the application.
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHWL(ReturnCode,ContextArea,SessionList,ConnectionNumber,
Request-token)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
SessionList
a list of contiguous 12 byte entries, each consisting of three unsigned
integer fields. The first contains the connection number of a session; the
other two are unused and should be initialized to zero; the last entry in the
list must contain a connection number of binary zeroes.
ConnectionNumber
A 4 byte unsigned integer field into which the connection number
associated with a completed request will be placed by CLIv2 if a request
completes; if a user event completes binary zeroes will be returned.
Request-token
A 4 byte unsigned integer field into which the DBCAREA Request-token
when the request was initiated will be placed by CLIv2 if a request
completes; if a user event completes binary zeroes will be returned.
Usage Notes
•
286
Each call to DBCHWL reflects completion of one event. If multiple events have
completed, none are lost. Rather, their completions are reflected on subsequent calls to
DBCHWL. Each completed event is reflected only once. For example, if two events
complete, the first call to DBCHWL reflects one event, the second call reflects the second
event, and the third call waits for completion of another event, if any responses are
pending.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 Routines
DBCHWL
•
When multiple responses have completed, they are reflected to the application in the order
in which their requests were initiated, not the order in which they completed. This ensures
that repeated use of a request that completes quickly does not prevent reflection of longerrunning responses.
•
The session list may contain any valid connection number, whether or not a response is
pending for that session. Each time DBCHWL is called, any connection number for which
no response is pending is ignored.
•
If DBCHUEC has been used to provide a user event, its completion is reflected before the
completion of any response.
•
If there are no responses whose completion is pending, a return code 123 results. If
DBCHUEC has been used to provide a user event, it is ignored. That is, when there are no
pending responses, the user event is neither checked for completion nor does suspension
occur for the event's completion. A user event is honored only when a request has been
issued but not yet completed.
•
When the DBCHME service has been used to include Teradata requests in another event,
DBCHWL never waits. If no events have completed, a return code 162 is reflected,
allowing the application to wait for the master event using an operating system service.
•
After the call, the return code field contains a return code.
•
After the call, CLIv2 may have changed the ContextArea field for its own purposes.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
287
Chapter 7: Other CLIv2 Routines
DBCHWL
288
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 8
CLIv2 Query Routine
This chapter describes the CLIv2 query routine, DBCHQE, which is used to obtain
information about CLIv2, TDP, or Teradata Database.
DBCHQE
DBCHQE is called by a CLIv2 application to obtain information about its execution
environment. When used by an application supporting multiple releases of CLIv2, TDP, or
Teradata Database, some return codes that indicate downlevel versions of these components
must be handled by the application, most often as equivalent to the information not being
available.
•
202 - CLIv2 does not support the query item
•
359 - the Database does not provide the information
•
365 - TDP does not provide the information
•
451 - TDP does not support the query item
For queries that return collections of items (Aggregate-support-list, Procedure-data, and
Utility-data), these applications should also allow for downlevel versions of CLIv2 by ensuring
that items of interest are present by checking the returned length (QEPRALEN).
Interface
This routine is called with the following parameters, stylistically presented (the actual syntax
varies according to the programming language being used):
DBCHQE(ReturnCode,ContextArea,DBCHQEP,...)
In high-level languages, the details of the parameter list are handled by the compiler. For
Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit
address of a parameter. The last address has the first bit set to one to indicate the end of the
list.
The parameters for this routine are:
Argument
Content
ReturnCode
A 4 byte unsigned integer field into which the return code will be placed by
CLIv2.
ContextArea
A 4 byte unsigned integer field for internal use by CLIv2.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
289
Chapter 8: CLIv2 Query Routine
DBCHQE
Argument
Content
DBCHQEP
The DBCHQEP structure.
...
Zero or more additional DBCHQEP structures.
Usage Notes
•
There can be multiple DBCHQEP addresses.
•
Each DBCHQEP address contains the address of a DBCHQEP
•
Each such area queries one piece of environmental information, such as the
installation id that is defined in the HSISPB.
•
When the query is successful (QEPRC contains zero), the area addressed by the QEPRAP
field contains the requested information, and the QEPRDLEN field contains the number
of bytes of the data returned. QEPRMLEN is set to zero, and any provided message area is
filled with spaces in the specified, or default, character set.
•
When the query is unsuccessful (QEPRC contains a CLIv2 return code), the area
addressed by the QEPRAP field is unchanged, and the QEPRDLEN field contains zero. If a
message area if provided, QEPRMLEN indicates the length in bytes of the message in the
specified, or default, character set. The contents of the area are the Query Environment
Results (QER) which is described as the DBCHQER area.
Upon completion, the return code will be the first or only DBCHQEP's QEPRC value.
Query Environment Parameters (QEP)
The following table defines the DBCHQEP area. All fields are set by the application with the
exception of QEPRDLEN, which is set by CLIv2. The field names in all languages are the
same, except that the C field names are case-sensitive. They appear in the following table in
upper and lower case immediately below the field names in Assembler, COBOL and PL/I.
A mnemonic is provided for QEPLEVEL. The name is the same for all languages, including C,
and is QEPLVLC.
Field Name
Offset
Length
Description
QEPLEVEL
00
1
Unsigned numeric format of the parameter list.
(qepLevel)
QEPITEM
Must be set to 4.
01
1
(qepItem)
QEPTLEN
(qepTLen)
Unsigned numeric item to be queried.
Valid item codes and their descriptions are listed in the
table following this table.
02
2
Unsigned numeric length of the TDP identifier
addressed by QEPTIDP, if one is provided.
When a TDP identifier is required but a length of zero
is specified, the default identifier in the HSHSPB is
used.
290
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Field Name
Offset
Length
Description
QEPTIDP
04
4
Pointer to an area containing the TDP identifier, if one
is provided.
(qepTIDP)
The full TDP identifier must be specified. One
character abbreviations are valid only within a logon
string.
If the TDP identifier is not specified, the syntax of the
TDP identifier is described in.
QEPCONN
04
4
Unsigned numeric CLIv2 connection number, if
required.
08
3
Not used.
(qepConn)
QEPFILL1
Must be set to 0.
QEPVRF
11
1
(varyingResult
Fmt for C;
VARYING-RE
SULT-FMT for
COBOL;
VARYING_RE
SULT_FMT for
PL/I))
QEPRALEN
• 0, the default, or just characters as an unsigned
1-byte integer that specifies the format of variablelength character results, where 0 has a mnemonic of
QEPVRFC (QER_varRsltFmtChar for C, CHAR for
COBOL; QER_VAR_RSLT_FMT_CHAR for PL/I)
• 2 for a 2-byte unsigned integer that contains the
number of characters followed by the characters,
where 2 has a mnemonic of QEPVRF2C
(QER_varRsltFmtShIntChar for C,
LEN9999-CHAR for COBOL;
QER_VAR_RSLT_FMT_VARCHAR for PL/I).
The use of QEPVRF2C increases the size of the result
by two bytes. While the specification must always be
valid, it has no effect for results that do not consist of a
variable-length character string (currently only
Database-access-path).
12
2
Unsigned numeric length of the area in which the
result of the query is returned.
14
2
Unsigned numeric length of the data returned.
(qepRALen)
QEPRDLEN
(qepRDLen)
QEPRAP
Varying-result-format must be one of the following:
Set to the length of the data returned (up to the size of
the area as specified by the QEPRALEN field).
16
4
(qepRAP)
Pointer to the area in which the result of the query is
returned.
The area pointed to is defined by CLIv2.
QEPMLID
(qepMLid)
20
2
Characters specifying the language to be used for any
CLIv2 error message associated with the request. When
a language is commonly used in several countries the
Country Id may be specified to select messages that are
unique to that country.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
291
Chapter 8: CLIv2 Query Routine
DBCHQE
Field Name
Offset
Length
Description
The Language Id is defined by the ISO 639 standard.
The value is in EBCDIC, and both lower and upper
case characters are permitted (lower case characters are
permitted since ISO 639 favors them for the Language
Id).
If not specified, the default value provided in the
HSHSPB is used. If no HSHSPB default exists, EN is
assumed. Refer to “DBCHUEP” on page 231 for derails
of each supported language.
Note: The only language for which messages are
distributed is United States English (Language Id of
'EN', optional Country Id of 'US'), although Teradata
in the various countries or customers may provide
additional languages.
The mechanism by which the CLIv2 error messages
may be defined in other languages is described in
“Chapter 14 Message Definitions” on page 413.
If a message must be returned but messages are not
available in the specified language, then the message
number with fixed message text of '(REQUIRED
MESSAGE TABLE IS NOT AVAILABLE)' in United
States English will be returned.
For example, the message 'CLI0187 MISSING
PARAMETER' would be presented as:
CLI0187 (REQUIRED MESSAGE TABLE IS NOT
AVAILABLE)
QEPMCID
(qepMCid)
22
2
Characters specifying the country variant of the
language to be used for any CLIv2 error message
associated with the request. The value specifies a two
character Country Id. Since the Country Id qualifies
the language, Language Id must also be specified.
When a language is commonly used in several
countries, the Country Id may be used to select
messages that are unique to a specific country.
The Country Id is defined by the ISO 3166-1 standard.
The value is in EBCDIC, and both lower and upper
case characters are permitted (lower case characters are
permitted to prevent confusion in remembering which
ISO standard favors lower case).
If not specified, the default value provided in the
HSHSPB is used. If no HSHSPB default exists, US is
assumed. Refer to “Country Id” on page 84 for details
of supported countries.
292
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Field Name
Offset
Length
Description
If a message must be returned but messages are not
available in the specified language, then the message
number with fixed message text of '(REQUIRED
MESSAGE TABLE IS NOT AVAILABLE)' in United
States English will be returned.
For example, the message 'CLI0187 MISSING
PARAMETER' would be presented as:
CLI0187 (REQUIRED MESSAGE TABLE IS NOT
AVAILABLE)
QEPMSGCS
24
4
(qepMsgCS)
Pointer to a 30 byte area that contains the name of the
character set to be used for messages. The value is in
upper case EBCDIC.
If not specified, the default value provided in the
HSHSPB is used. If no HSHSPB default exists,
EBCDIC is assumed.
Refer to “Character Set Pointer” on page 78 for details
on the supported character set names.
QEPMSGP
28
4
(qepMsgP)
Pointer to an area into which any error message will be
placed when a non-zero return code occurs.
QEPMSGM specifies the length of the area pointed to
by QEPMSGP. If an error occurred while building the
message, QEPRMRC will contain a CLIv2 return code.
When this code is not zero, the text of the message may
or may not be usable, depending on the nature of the
error.
The character set used to construct the message is
indicated by QEPMSGCS. If not specified, the default
value provided in the HSHSPB is used. If no HSHSPB
default exists, EBCDIC is assumed.
When a zero return code is reflected, any text from a
previous error is overwritten with spaces in the
character set indicated by QEPMSGCS, and
QEPRMLEN is zeroed.
QEPMSGM
32
2
Unsigned numeric length in bytes of the area pointed
to by QEPMSGP. The value is equivalent to the
maximum length of a message that can be returned in
that area. If QEPMSGP is not specified, this value is
ignored.
34
2
Unsigned numeric length in bytes of the message
returned in the area addressed by QEPMSGP. If
QEPMSGP is not specified, this value is not returned.
36
2
Unsigned numeric CLIv2 return code for any error that
occurred while constructing the message. If no error
occurred, binary zeroes are returned.
(qepMsgM)
QEPRMLEN
(qepRMLen)
QEPRMRC
(qepRMRC)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
293
Chapter 8: CLIv2 Query Routine
DBCHQE
Field Name
Offset
Length
Description
QEPRC
38
2
Unsigned numeric CLIv2 return code that occurred
while processing this DBCHQEP. If no error occurred,
binary zeroes are returned.
40
8
Reserved, must be binary zeroes.
48
8
Reserved, must be binary zeroes.
56
8
Reserved, must be binary zeroes.
64
8
Reserved, must be binary zeroes.
72
4
Unsigned numeric CLIv2 request number, if required.
76
4
Binary token, initially zero, thereafter as returned by
the previous incomplete query Available-character-sets
request
(qepRC)
QEPTIDP8
(qepTIdP8)
QEPRAP8
(qepRAP8)
QEPMCSP8
(qepMCSP8)
QEPMSGP8
(qepMsgP8)
QEPRQST
(qepRqst)
QEPTOKEN
(qepToken)
QEPITEM Field
In the QEPITEM field, the following are valid item codes:
Table 41: QEPITEM Field Valid Item Codes
294
Item Code
Name
Description
1
Installation-Id
The Installation-id
2
Session-character-set
A session's character set name.
This item code is deprecated by item code
46, which provides exactly the same
functionality.
3
Transaction-semantics-support
Defines whether Transaction-semantics
are supported
4
Language-conformance-support
Defines whether Language-conformance is
supported
5
Updatable-cursor-support
Defines whether Updateble-cursors are
supported
6
Referential-integrity-support
Defines whether Referential-integrity is
supported
7
Default-transaction-semantics
A server's default Transaction-semantics
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Table 41: QEPITEM Field Valid Item Codes (continued)
Item Code
Name
Description
8
Extended-parcel-size-support
Defines whether parcel sizes greater than
32767 bytes are supported
9
CLIv2-release
The CLIv2 release
10
Server-parallelism-factor
The extent of a server's parallel processing
11
Maximum-segment-size
The maximum size of a data segment
12
TDP-release
A TDP's release information
13
Single-signon-support
Defines whether Single-signon is
supported
14
Session-userid
A session's userid
15
UPSERT-support
Defines whether UPSERT SQL is
supported
16
Array-operations-support
Defines whether EXECUTE-FOR SQL is
supported
17
MERGE-INTO-support
Defines whether MERGE-INTO SQL is
supported
18
Large-object-support
Defines whether Large-objects are
supported
19
Timing-precision-range
The range of Timing-precision values
20
Extended-response-support
Defines whether response sizes greater
than 65535 bytes are supported
21
Expanded-parcel-header-usage
Defines which parcels allow the alternate
parcel header
22
Timestamp-types-support
Defines whether Timestamp-types are
supported
23
Utility-data
Data of interest only to proprietary
utilities.
24
Aggregate-support-list
List of selected other query items.
25
Response-positioning-support
Defines whether repositioning of response
data is supported.
26
Data-encryption-support
Whether data-encryption is supported.
27
Request-message-release
Message table release information.
28
Available-character-sets
The names of the server's available
character sets.
29
Enhanced-statement-status-support
Whether the server supports enhanced
statement results.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
295
Chapter 8: CLIv2 Query Routine
DBCHQE
Table 41: QEPITEM Field Valid Item Codes (continued)
296
Item Code
Name
Description
30
User-defined-types-support
Whether SQL supports user-defined data
types.
31
APH-response
Defines which response parcels permit the
alternate parcel header.
32
Available-logon-mechanisms
The names of the available logon
mechanisms.
33
Default-character-set
The default character set name from either
the HSHSPB or a Teradata Database's
default character set.
34
Database-release
The Teradata Database release and version.
35
CLIv2-limits
Teradata Database limits affecting an
application's values for CLIv2 settings.
36
SQL-limits
Teradata Database limits affecting an
application's use of SQL statements.
37
Relaxed-call-args
Defines whether relaxation of SQL CALL
arguments is supported.
38
Statement-info-support
Defines whether StatementInformation
parcels are supported.
39
Integer/decimal-enlargement
Defines whether the BIGINT data type is
supported, precision for DECIMAL data
types may exceed 18, or the maximum
precision for decimal data types in
responses may be specified.
40
Return-Identity-Data-support
Defines whether data may be returned in
response to an SQL Insert operation when
Identity columns are involved.
41
Result-sets-support
Defines whether stored procedures may
return the results of their SQL statements
to the application.
42
QueryBand-support
Defines whether the Teradata SQL SET
QUERY_BAND statement is supported.
43
Merge-into-usage
Defines whether and how the SQL MERGE
INTO statement is supported.
44
Logging-errors-usage
Defines whether and how the Teradata
SQL LOGGING ERRORS clause is
supported.
45
Procedure-data
Data of interest to external Stored
Procedures.
46
Session-character-set
The name of the character set for the
session.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Table 41: QEPITEM Field Valid Item Codes (continued)
Item Code
Name
Description
47
Column-correlation-support
Defines whether the Teradata SQL
CREATE, UPDATE, DROP, and HELP
CORRELATION statements are
supported.
48
Utility-session
Session date. Used internally, only by
Teradata utilities.
49
Database-access-path
For channel-attached systems, defines a
TDPid used to access the requested
database.
50
Trusted-session-support
Defines whether the Teradata SQL SET
QUERY_BAND PROXYUSER statement is
honored rather than silently ignored.
51
LOB-Name-support
Defines whether the BY NAME phrase is
permitted in the USING row descriptor in
a request string.
52
Transforms-off-usage
Defines whether the constituent attributes
of SQL Structured User Defined Types
(UDTs) may be referenced.
53
Trusted-request-support
Defines whether a request may indicate
whether it is trusted to use the Teradata
SQL SET
QUERY_BAND='PROXYUSER=...'
statement to change the session userid.
Installation-id
The Installation-id might be used on title pages or in heading or footing lines on output
generated by the application.
Refers to the invoked CLIv2.
Returns the installation Id for your site.
Response DBQERIID (DbqerIid for C)
Item
Code
Mnemonic
Field
Value
1
QEPIIID
QERIID
('id' for C)
Forty EBCDIC characters, left-justified and
padded on the right with blanks.
Transaction-semantics-support
Transaction-semantics-support might be used to ascertain whether ANSI may be specified for
the DBCAREA Transaction-semantics option without being rejected by CLIv2.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
297
Chapter 8: CLIv2 Query Routine
DBCHQE
Refers to the session whose CLIv2 connection number is specified in the QEPCONN field.
Returns the type of transaction semantics supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Response DBQERTSM (DbqerTSm for C)
Item
Code
Mnemonic
Field
Value
3
QEPITSM
QERTSM
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERTSMN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERTSMY
(QER_Supported for C)
Language-conformance-support
Language-conformance-support might be used to ascertain whether the DBCAREA
Language-conformance-standard option may be specified without being rejected by CLIv2.
Refers to the session whose CLIv2 connection number is specified in the QEPCONN field.
Returns the type of SQL standard supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Response DBQERLCS (DbqerLCS for C)
Item
Code
Mnemonic
Field
Value
4
QEPILCS
QERLCS
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERLCSN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERLCSY
(QER_Supported for C)
Updatable-cursor-support
Updatable-cursor-support might be used to ascertain whether an SQL Select statement may
contain a FOR CURSOR clause without being rejected by the Teradata Database.
Refers to the Teradata Database whose TDP identifier is addressed by the QEPTIDP field and
has the length of the identifier is specified by the QEPTLEN field.
Returns whether Updatable cursors are supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
298
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERUCR (DbqerUCr for C)
Item
Code
Mnemonic
Field
Value
5
QEPIUCR
QERUCR
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERUCRN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERUCRY
(QER_Supported for C)
Referential-integrity-support
Referential-integrity-support might be used to ascertain whether the Teradata Database
supports Referential Integrity.
Refers to the Teradata Database whose TDP identifier is addressed by the QEPTIDP field and
has the length of the identifier is specified by the QEPTLEN field.
Returns whether referential integrity is supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Response DBQERRFI (DbqerRfI for C)
Item
Code
Mnemonic
Field
Value
6
QEPIRFI
QERRFI
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERRFIN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERRFIY
(QER_Supported for C)
Default-transaction-semantics
The Default-transaction-semantics might be used to ascertain the Teradata Database default
value for Transaction-semantics to understand the impact on transaction execution.
Refers to the Teradata Database whose TDP identifier is addressed by the QEPTIDP field and
has the length of the identifier is specified by the QEPTLEN field.
Returns the default transaction semantics for the identified Teradata Database to the area
pointed to by QEPRAREA.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
299
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERDTS (DbqerDTS for C)
Item
Code
Mnemonic
Field
Value
7
QEPIDTS
QERDTS
('semantics' for C)
One of the following EBCDIC characters:
‘A‘ with mnemonic QERDTSA
(QER_SemanticsANSI for C)
‘T‘ with mnemonic QERDTST
(QER_SemanticsTeradata for C)
Extended-parcel-size-support
Extended-parcel-size-support might be used to ascertain whether a response buffer larger
than 32767 bytes will be used.
Refers to the Teradata Database whose TDP identifier is addressed by the QEPTIDP field and
has the length of the identifier is specified by the QEPTLEN field.
Returns whether parcels greater than 32767 bytes are supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Response DBQEREPS (DbqerEPS for C)
Item
Code
Mnemonic
Field
Value
8
QEPIEPS
QEREPS
('semantics' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QEREPS
(QER_NotSupported for C)
‘Y‘ with mnemonic QEREPSY
(QER_Supported for C)
CLIv2-release
The CLIv2-release might be used to aid in problem diagnosis.
Refers to the release of CLIv2 being invoked.
Returns the release identifier for the CLIv2 being used.
Note: The intent of the data is not to deduce CLIv2 functionality, but simply to provide the
release information for whatever diagnostic use it may be. The value should not be parsed for
any reason since its format is subject to change.
300
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERC2R (DbqerC2R for C)
Item
Code
Mnemonic
Field
Value
9
QEPIC2R
QERC2R
('release' for C)
The returned information consists of up to eleven
EBCDIC characters: the two-character offering
number; the two-character maintenance release
number; and an optional two-character E-tape
number (spaces if omitted); each separated by
periods.
Server-parallelism-factor
The Server-parallelism-factor might be used to compare the degree of parallelism on the
Teradata Database.
Refers to the Teradata Database whose TDP identifier is addressed by the QEPTIDP field and
has length specified by the QEPTLEN field.
Returns a dimensionless value that indicates the extent of parallel processing used internally
by the server.
Response DBQERSPF (DbqerSPF for C)
Item
Code
Mnemonic
Field
Value
10
QEPISPF
QERSPF
('factor' for C)
A four-byte unsigned integer.
Maximum-segment-size
This item is deprecated: new development should use Segment-length from the CLIv2-limits
query.
The Maximum-segment-size is used to obtain the size limit when using the DBCAREA
Segment-data option.
Refers to the Teradata Database whose TDP identifier is addressed by the QEPTIDP field and
has length specified by the QEPTLEN field.
Returns the maximum size of a segment.
Response DBQERMSS (DbqerMSS for C)
Item
Code
Mnemonic
Field
Value
11
QEPIMSS
QERMSS
('maximum' for C)
A four-byte unsigned integer
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
301
Chapter 8: CLIv2 Query Routine
DBCHQE
TDP-release
The TDP-release might be used to aid in problem diagnosis.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field
Returns the release identifiers for the TDP being used.
Note: The intent of this data is not to deduce TDP functionality, but simply to provide the
current TDP release identification for whatever diagnostic value it may be. The value should
not be parsed for any reason since its format is subject to change.
Response DBQERTDR (DbqerTDR for C)
Item
Code
Mnemonic
Field
Value
12
QEPITDR
QERTDR
('release' for C)
Up to fifty-one EBCDIC characters, identifying
from one to three TDP components, separated by
commas.
The first, which begins with 'TDP.', is present if
available and identifies TDP itself.
The second, which begins with either 'PC', 'SVC',
or 'IUCV' and is enclosed in parentheses, is
always present and identifies the interface from
CLIv2 to TDP.
The third, which begins with either 'SXMS' or
'OSSI' and is enclosed in parentheses, is present if
applicable and available, and identifies the
interface from TDP to CLIv2.
Each identifier is normally eight characters
consisting of a two-character offering number;
the one-character major release number and onecharacter minor release number; and the
two-character maintenance release number; each
separated by periods. Each may also end with a
period followed by a two-character E-tape
number, but this is omitted if not applicable.
Single-signon-support
Single-signon-support might be used to avoid having to specify a password if the Teradata
Database honors userid authentication performed using a network security mechanism.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether single-signon is supported by TDP and the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Note: Currently, no version of TDP supports single-signon.
302
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERSSO (DbqerSSo for C)
Item
Code
Mnemonic
Field
Value
13
QEPISSO
QERSSO
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERSSON
(QER_NotSupported for C)
‘Y‘ with mnemonic QERSSOY
(QER_Supported for C)
Session-userid
The Session-userid might be used to obtain the userid for the session without having to parse
the logon string.
Refers to the session whose CLIv2 connection number is specified in the QEPCONN field.
The session must have been established using a value of C for the Connect Type option.
Returns the userid associated with the session. Older Database releases whose object names
are thirty characters long return the userid left-justified padded on the right with blanks.
Newer Database that support longer object names trim trailing blanks.
Response DBQERSUI (DbqerSUi for C)
Item
Code
Mnemonic
Field
Value
14
QEPISUI
QERSUI
('userid' for C)
Between one and 2304 bytes long, encoded in the
character set specified when the session was
established.
UPSERT-support
UPSERT-support might be used to ascertain whether the SQL UPSERT statement is
supported by the Teradata Database.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether the UPSERT SQL statement is supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
303
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERUPS (DbqerUps for C)
Item
Code
Mnemonic
Field
Value
15
QEPIUPS
QERUPS
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERUPSN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERUPSY
(QER_Supported for C)
Array-operations-support
Array-operations-support might be used to ascertain whether a Using-data-count greater
than one may be specified without being rejected by CLIv2.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether the array operations is supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Response DBQERAOP (DbqerAOp fo C)
Item
Code
Mnemonic
Field
Value
16
QEPIAOP
QERAOP
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERAOPN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERAOPY
(QER_Supported for C)
MERGE-INTO-support
This item is deprecated: new development should use the Merge-into-usage query.
MERGE-INTO-support might be used to ascertain whether the MERGE-INTO SQL
statement is supported by the Teradata Database.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether the MERGE-INTO SQL statement for single-rows is supported by the
Teradata Database.
This item is also included in the Aggregate-support-list query item.
304
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERMRI (DbqerMrI for C)
Item
Code
Mnemonic
Field
Value
17
QEPIMRI
QERMRI
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERMRIN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERMRIY
(QER_Supported for C)
Large-object-support
Large-object-support might be used to ascertain whether the Teradata Database supports
large objects (BLOBs or CLOBs).
Refers to the TDP whose TDP identifier is addressed by the QEPTDP field and has length
specified by the QEPTLEN field.
Returns whether Large Objects are supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item
Response DBQERLOB (DbqerLOb for C)
Item
Code
Mnemonic
Field
Value
18
QEPILOB
QERLOB
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERLOBN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERLOBY
(QER_Supported for C)
Timing-precision-range
Timing-precision-range is used to obtain the minimum and maximum values acceptable for
the DBCAREA Timestamp-precision option.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns the minimum and maximum values for Timing-precision supported by TDP.
Response DBQERTPR (DbqerTPR for C)
Item
Code
Mnemonic
Fields
Value
19
QEPITPR
QERTPRMN
('minimum' for C)
A two-byte signed integer containing the
minimum value.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
305
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERTPR (DbqerTPR for C)
Item
Code
Mnemonic
Fields
Value
QERTPRMX
('maximum' for C)
A two-byte signed integer containing the
maximum value.
Extended-response-support
Extended-response-support might be used to ascertain whether a response buffer larger than
65535 bytes will be used.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether response buffers greater than 65535 bytes are supported by the Teradata
Database.
This item is also included in the Aggregate-support-list query item
Response DBQERERS (DbqerERs for C)
Item
Code
Mnemonic
Field
Value
20
QEPIERS
QERERS
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERERSN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERERSY
(QER_Supported for C)
Expanded-parcel-header-usage
Expanded-parcel-header-usage might be used to ascertain whether Teradata Database allows
use of the Alternate Parcel Header before constructing a parcel in Request-mode.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether parcels greater than 65535 bytes are supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item
306
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQEREPH (DbqerEPH for C)
Item
Code
Mnemonic
Field
Value
21
QEPIEPH
QEREPH
(requestUsage for
C)
A two-byte unsigned integer containing either:
‘0‘ with mnemonic QEREPHN
(QER_RequestUsageNone for C)
The maximum size of all parcels is limited to
32767 or 65535, depending on the supported
setting of the Maximum-parcel option.
‘1‘ with mnemonic QEREPHI
(QER_RequestUsageSubset1 for C)
The maximum size of the following parcel flavors
may exceed 65535: 1-5, 7, 13-14, 31-32, 68-69, 7172, 85, 102, 115-118, 120, 128-129, 140-143, 146148, 153-154, 157-159.
Note: In addition to those parcel flavors
associated with a value of 1, the maximum size of
the following parcel flavors may also exceed
65535: 36-38, 41, 45, 52-57, 59-61, 63-65, 73, 75,
77-79, 81, 83, 88-89, 103, 106, 114, 135, 138, 155.
‘2‘ with mnemonic QEPEPHA
(QER_RequestUsageSubset2 for C)
Note: only those flavors used by normal
parcel-mode applications are described elsewhere
in this document
Timestamp-types-support
Timestamp-types-support might be used to ascertain whether the Teradata Database will
implicitly convert Timestamp data to Date data.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether distinct datatypes for timestamps are supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item
Response DBQERTMT (DbqerTmT for C)
Item
Code
Mnemonic
Field
Value
22
QEPITMT
QERTMT
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERTMTN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERTMTY
(QER_Supported for C)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
307
Chapter 8: CLIv2 Query Routine
DBCHQE
Utility-data
Utility-data is used by proprietary utilities and is not intended for other applications. It is
described here simply for completeness.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns information for internal use by the Teradata utilities. New items may be added;
therefore, the length of the result may vary depending on the version of CLIv2 or TDP.
Response DBQERUD (DbqerUD for C)
Item
Code
Mnemonic
Field
Value
23
QEPIUD
QERUDCI
(intervalStatus for
C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERUDCIN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERUDCIY
(QER_Supported for C)
QERUDCW
(workloadStatus for
C, WORKLOADSTATUS for
COBOL,
WORKLOAD_STA
TUS for PL/I)
One of the following EBCDIC characters:
QERUDEU
(exportUsage for C,
EXPORT-USAGE
for COBOL,
EXPORT_USAGE
for PL/I)
A two-byte unsigned integer containing either:
"N" with mnemonic QERUDCWN
(QER_NotSupported for C, NOT-SUPPORTED
for COBOL, QER_NOT_SUPPORTED for PL/I)
"Y" with mnemonic QERUDCWY
(QER_Supported for C, SUPPORTED for
COBOL, QER_SUPPORTED for PL/I)
'0' with mnemonic QERUDEUS
(QER_UtilData_ExportSpool for C,
SPOOL for COBOL,
QER_UTILDATA_EXPORT_SPOOL for PL/I)
'1' with mnemonic QERUDEUN
(QER_UtilData_ExportNoSpool for C,
NO-SPOOL for COBOL,
QER_UTILDATA_EXPORT_NO_SPOOL for
PL/I)
Aggregate-support-list
Aggregate-support-list might be used to obtain the results for several queries useful when
establishing a connection.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns a list of pre-determined items that also can be queried individually. The format of,
and values returned for, each item are exactly the same as when that item is queried
individually. As new support-type items are added in the future, they will also be added to this
308
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
aggregate list. Therefore, the length of the result may vary depending on the version of CLIv2
or TDP.
Note: Since there is only one return code for all items, item-specific errors cannot all be
reported. Instead, that item will return a value of 'N' (no support).
Response DBQERASL(DbqerASL for C)
Item
Code
Mnemonic
Field
Value
24
QEPIASL
QERASLTS
(semanticsStatus for C)
is Transaction- semantics-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERTSMN
(QER_NotSupported for C)
(QERASLTSN for COBOL)
‘Y‘ with mnemonic QERTSMY
(QER_Supported for C)
(QERASLTSY for COBOL)
QERASLLC
(conformanceStatus for C)
is Language- conformance-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERLCSN
(QER_NotSupported for C)
(QERASLLCN for COBOL)
‘Y‘ with mnemonic QERLCSY
(QER_Supported for C)
(QERASLLCY for COBOL)
QERASLUC (UpdatableCursorStatus
for C)
is Updatable-cursor-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERUCRN
(QER_NotSupported for C)
(QERASLUCN for COBOL)
‘Y‘ with mnemonic QERUCRY
(QER_Supported for C)
(QERASLUCY for COBOL)
QERASLRI (referentialIntegrityStatus
for C)
is Referential- integrity-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERRFIN
(QER_NotSupported for C)
(QERASLRIN for COBOL)
‘Y‘ with mnemonic QERRFIY
(QER_Supported for C)
(QERASLRIY for COBOL)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
309
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERASL(DbqerASL for C)
Item
Code
Mnemonic
Field
Value
QERASLEP
(extendedParcelStatus for C)
is Extended-parcel- size-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QEREPSN
(QER_NotSupported for C)
(QERASLEPN for COBOL)
‘Y‘ with mnemonic QEREPSY
(QER_Supported for C)
(QERASLEPY for COBOL)
QERASLSS
(singleSignonStatus for C)
is Single-signon-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERSSON
(QER_NotSupported for C)
(QERASLSSN for COBOL)
‘Y‘ with mnemonic QERSSOY
(QER_Supported for C)
(QERASLSSY for COBOL)
QERASLUP (upsertStatus for C)
is UPSERT-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERUPSN
(QER_NotSupported for C)
(QERASLUPN for COBOL)
‘Y‘ with mnemonic QERUPSY
(QER_Supported for C)
(QERASLUPY for COBOL)
QERASLAO
(arrayOpsStatus for C)
is Array-operations-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERAOPN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERAOPY
(QER_Supported for C)
QERASLMI
(mergeIntoStatus for C)
is MERGE-INTO-support
This value is deprecated: new
development should use the
QERASLMU value later in this list.
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERMRIN
(QER_NotSupported for C)
(QERASLMIN for COBOL)
‘Y‘ with mnemonic QERMRIY
(QER_Supported for C)
(QERASLMIY for COBOL)
310
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERASL(DbqerASL for C)
Item
Code
Mnemonic
Field
Value
QERASLLO (lobStatus for C)
is Large-object-support
‘N‘ with mnemonic QERLOBN
(QER_NotSupported for C)
(QERASLLON for COBOL)
‘Y‘ with mnemonic QERLOBY
(QER_Supported for C)
(QERASLLOY for COBOL)
QERASLER (extendedResponseStatus
for C)
is Extended-response-support
‘N‘ with mnemonic QERERSN
(QER_NotSupported for C)
(QERASLERN for COBOL)
‘Y‘ with mnemonic QERERSY
(QER_Supported for C)
(QERASLERY for COBOL)
QERASLTT
(timingTypesStatus for C)
is Timestamp-types-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERTMTN
(QER_NotSupported for C)
(QERASLTTN for COBOL)
‘Y‘ with mnemonic QERTMTY
(QER_Supported for C)
(QERASLTTY for COBOL)
QERASLEH (requestUsage for C)
is Expanded-parcel-header-usage
A two-byte unsigned integer
containing either:
‘N‘ with mnemonic QEREPHN
(QER_RequestUsageNone for C)
(QERASLEHN for COBOL)
‘1‘ with mnemonic QEREPHY
(QER_RequestUsageSubset1 for
C)
(QERASLEHY for COBOL)
‘2‘ with mnemonic QEREPHA
(QER_RequestUsageSubset2 for
C)
(QERASLEHI for COBOL)
QERASLRP
(responsePositioningStatus for C)
is Response-positioning-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERRPON
(QER_NotSupported for C)
(QERASLRPN for COBOL)
‘Y‘ with mnemonic QERRPOI
(QER_Supported for C)
(QERASLRPI for COBOL)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
311
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERASL(DbqerASL for C)
Item
Code
Mnemonic
Field
Value
QERASLES (statementStatusStatus for
C)
is Enhanced-statement-status-support
‘N‘ with mnemonic QERESSN
(QER_NotSupported for C)
(QERASLESN for COBOL)
‘Y‘ with mnemonic QERESSY
(QER_Supported for C)
(QERASLESY for COBOL)
QERASLUT
(userTypesStatus for C)
is User-defined-types-support
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERUDTN
(QER_NotSupported for C)
(QERASLUTN for COBOL),
‘Y‘ with mnemonic QERUDTY
(QER_Supported for C)
(QERASLUTY for COBOL)
QERASLRA
(relaxedArgsStatus for C,
RELAXED-ARGS-STATUS for
COBOL, RELAXED_ARGS_STATUS
for PL/I)
is Relaxed-call-args-support
One of the following EBCDIC
characters:
'N' is QERRCAN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED
for PL/I)
'Y' is QERRCAY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED for PL/I)
QERASLSI
(statementInfoStatus for C,
STATEMENT-INFO-STATUS
for COBOL,
STATEMENT_INFO_STATUS
for PL/I)
is Statement-info-support
One of the following EBCDIC
characters:
'N' is QERSISN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED
for PL/I)
'Y' is QERSISY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED for PL/I
312
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERASL(DbqerASL for C)
Item
Code
Mnemonic
Field
Value
QERASLID
(integerDecimalStatus for C,
INTEGE-DECIMAL-STATUS for
COBOL,
INTEGER-DECIMAL_STATUS
for PL/I)
is Statement-info-support
One of the following EBCDIC
characters:
'N' is QERIDEN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED
for PL/I)
'Y' is QERIDEY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED for PL/I)
QERASLRD
(returnDataStatus for C,
RETURN-DATA-STATUS for
COBOL, RETURN_DATA_STATUS
for PL/I)
is Return-Identity-Data-support
One of the following EBCDIC
characters:
'N' is QERRIDN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED
for PL/I)
'Y' is QERRIDY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED for PL/I)
QERASLRS
resultSetsStatus for C,
RESULT-SETS-STATUS for COBOL,
RESULT_SETS_STATUS for PL/I) is
Result-sets-support
One of the following EBCDIC
characters:
'N' is QERRSSN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED for PL/
I)
'Y' is QERRSSY (QER_Supported
for C, SUPPORTED for COBOL,
QER_SUPPORTED for PL/I).
QERASLQB
(queryBandStatus for C,
QUERYBAND-STATUS for COBOL,
QUERYBAND_STATUS for PL/I) is
QueryBand-support
One of the following EBCDIC
characters:
'N' is QERQBSN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED for PL/
I)
'Y' is QERQBSY (QER_Supported
for C, SUPPORTED for COBOL,
QER_SUPPORTED for PL/I)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
313
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERASL(DbqerASL for C)
Item
Code
Mnemonic
Field
Value
QERASLCC (columnCorrStatus for C,
COLUMN-CORR-STATUS for
COBOL, COLUMN_CORR_STATUS
for PL/I) is Column-correlation-status
One of the following EBCDIC
characters:
'N' is QERCCSN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED for PL/
I)
'Y' is QERCCSY (QER_Supported
for C, SUPPORTED for COBOL,
QER_SUPPORTED for PL/I).
For applications that support
multiple releases of CLIv2, a
downlevel CLIv2 could return
binary zeroes, which is interpreted
as 'N'.
QERASLMU
(mergeIntoUsage for C,
MERGE-INTO-USAGE for COBOL,
MERGE_INTO_USAGE for PL/I) is
Merge-into-usage
A two-byte unsigned integer
containing one of the following
values:
0 is QERMIUN
(QER_MergeUsageNone for C,
NOT_SUPPORTED for COBOL,
QER_MERGE_USAGE_NONE
for PL/I)
1 is QERMIUS
(QER_MergeUsageSingleRow for
C, SINGLE-ROW for COBOL,
QER_MERGE_USAGE_SINGLE_
ROW for PL/I)
2 is QERMIUM
(QER_MergeUsageMultiRow for
C, MULTI-ROW for COBOL,
QER_MERGE_USAGE_MULTI_
ROW for PL/I)
QERASLLE
(loggingerrorsUsage for C,
LOGGING-ERRORS-USAGE for
COBOL,
LOGGING_ERRORS_USAGE for PL/
I) is Logging-errors-usage
A two-byte unsigned integer
containing one of the following
values:
0 is QERLEUN
(QER_LoggingUsageNone for C,
NOT_SUPPORTED for COBOL,
QER_LOGGING_USAGE_NONE
for PL/I),
1 is QERLEUM
(QER_LoggingUsageMerge for C,
QERASLLEM for COBOL,
QER_LOGGING_USAGE_MERG
E for PL/I)
314
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERASL(DbqerASL for C)
Item
Code
Mnemonic
Field
Value
QERASLTO
(transformsOffUsage for C,
TRANSFORMS-OFF-USAGE
for COBOL,
TRANSFORMS_OFF_USAGE
for PL/I) is Transforms-off-usage
A two-byte unsigned integer
containing one of the following
values:
0 is QERTOUN
(QER_XformsOffUsageNone
for C,
NOT_SUPPORTED for COBOL,
QER_XFORMS_OFF_NONE
for PL/I),
1 is QERTOUS
(QER_XformsOffUsageStruct for
C, STRUCTURED for COBOL,
QER_XFORMS_OFF_STRUCT
for PL/I)
2 is QERTOUP
(QER_XformsOffUsagePeriod for
C, PERIOD for COBOL,
QER_XFORMS_OFF_PERIOD
for PL/I)
Response-positioning-support
Response-positioning-support might be used to ascertain whether the DBCAREA
Positioning-action option may be specified without being rejected by CLIv2.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether response positioning is supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Response DBQERRPO (DbqerRPo for C)
Item
Code
Mnemonic
Field
Value
25
QEPIRPO
QERRPO
('status' for C)
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERRPON
(QER_NotSupported for C)
‘Y‘ with mnemonic QERRPOY
(QER_Supported for C)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
315
Chapter 8: CLIv2 Query Routine
DBCHQE
Data-encryption-support
Data-encryption-support might be used to ascertain whether sensitive data is encrypted when
sent to or received from the Teradata Database.
Refers to the session whose CLIv2 connection number is specified in the QEPCONN field.
Returns whether data encryption is supported by TDP and the Teradata Database.
Note: Currently no version of TDP supports Data-encryption.
Response DBQERDEN (DbqerDEN for C)
Item
Code
Mnemonic
Field
Value
26
QEPIDEN
QERDEN
('status' for C)
One of the following EBCDIC
characters:
‘N‘ with mnemonic QERDENN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERDENY
(QER_Supported for C)
Request-message-release
Request-message-release might be used to aid in problem diagnosis.
Refers to 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.
Returns the CLIv2 release identifier and any customization information for the message table
that will be used for the request.
Note: The intent of the data is not to deduce CLIv2 functionality, but simply to provide the
release information for whatever diagnostic use it may be. The value should not be parsed for
any reason since its format is subject to change.
Response QEPIRMR (DbqerRMR for C)
Item Code
Mnemonic
Field
Value
27
QEPIRMR
DBQERRMR
('release' for C)
The returned information consists of up to
forty-eight EBCDIC characters, consisting of
one or two identifiers separated by a comma.
The first, which begins with 'CL2.', identifies the
CLIv2 release identifier: the two-character
offering number; the one-character major
release number and one-character minor release
number; the two-character maintenance release
number; and an optional two-character E-tape
number; each separated by periods.
316
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response QEPIRMR (DbqerRMR for C)
Item Code
Mnemonic
Field
Value
QERRMR
('release' for C)
The second presents any optional customization
identification provided by the message table. It
is free-format information between one and
thirty-two characters.
Available-character-sets
Available-character-sets might be used to allow selection of a character set name from a list of
all character sets supported by the Teradata Database.
Refers the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns the names of the character sets available on the server. The response consists of four
fixed fields followed by a variable number of character set names. As many whole character set
names as will fit into the response area whose length is indicated by QEPRALEN will be
returned. If all names are not returned, another query may be issued specifying the returned
token to indicate that names after those already returned are processed.
Response DBQERACS (DbqerACS for C)
Item Code
Mnemonic
Field
Value
28
QEPIACS
QERACSTK
('token' for C)
a 4byte 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
(namesRemaining for C)
a 2byte unsigned integer indicating the
number of character set names not
returned.
QERACSNP
(namesPresent for C)
a 2byte unsigned integer indicating the
number of character set names returned.
QERACSLN
(nameLen for C)
a 2byte unsigned integer indicating the
length of each character set name.
Immediately following are the number of
names, in EBCDIC, indicated by
QERACSNP, each of length indicated by
QERACSLN.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
317
Chapter 8: CLIv2 Query Routine
DBCHQE
Enhanced-statement-status-support
Enhanced-statement-status-support might be used to ascertain whether the DBCAREA
Statement-status option may request that ResultSummary parcels be returned by the Teradata
Database.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether Enhanced-statement-status is supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Response DBQERES (DbqerES for C)
Item
Code
Mnemonic
Field
Value
29
QEPIESS
QERESS
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic ERESSN
(QER_NotSupported for C)
Does not supports enhanced statement status.
‘Y‘ with mnemonic QERESSY
(QER_Supported for C)
Supports enhanced statement status.
User-defined-types-support
User-defined-types-support might be used to ascertain whether the Teradata Database will
allow creation of user-defined SQL data types.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns whether User-defined-types is supported by the Teradata Database.
This item is also included in the Aggregate-support-list query item.
Response DBQERUT (DbqerUT for C)
Item Code
Mnemonic
Field
Value
30
QEPIUDT
QERUDT
('status' for C)
One of the following EBCDIC characters:
‘N‘ with mnemonic QERUDTN
(QER_NotSupported for C)
‘Y‘ with mnemonic QERUDTY
(QER_Supported for C)
APH-response
There is no known use for the APH-response query.
318
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Refers to the TDP whose TDP identifier addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns an indication of which, if any, response parcels may exceed 65535 bytes.
Response DBQERAPH (DbqerAPH for C)
Item
Code
Mnemonic
Field
Value
31
QEPIAPH
QERAPH
(responseUsage for C)
A two-byte unsigned integer containing either:
‘0‘ with mnemonic QERAPHN:
(QER_ResponseUsageNone for C)
The maximum size of all response parcels is
limited to 65535
‘1‘ with mnemonic QERAPHI:
(QER_ResponseUsageSubset1 for C)
The maximum size of the following parcel
flavors may exceed 65535:
8-12, 17-19, 20-29, 33-35, 46-47, 51, 71, 86,
105, 120-122, 125, 144-146, 149-152
Available-logon-mechanisms
When a TDPid is specified, Available-logon-mechanisms might be used to allow selection of a
logon mechanism from a list of all usable logon mechanisms, which also indicates a default
mechanism. When a TDPid is not supplied, there is no known use for the query.
If no TDP identifier is provided, refers to the logon mechanisms supported by CLIv2 itself. If
a TDP identifier is provided by the QEPTIDP field of length specified by the QEPTLEN field,
refers to the logon mechanisms supported by both CLIv2 and the Teradata Database.
Returns a list of logon mechanism names supported. The response consists of four fixed fields
followed by a variable number of entries. As many whole entries as will fit into the response
area whose length is indicated by QEPRALEN will be returned. If all entries are not returned,
another query may be issued specifying the returned token to indicate that entries after those
already returned are processed.
Note: Logon mechanisms are currently not supported for a channel-connected system.
Response DBQERALM (DbqerALM for C)
Item
Code
Mnemonic
Field
Value
32
QEPIALM
QERALMTK
('token' for C, COBOL,
and PL/I)
A 4 byte token to be placed into
QEPTOKEN to retrieve any additional
entries. The content of the token is
undefined and must not be altered by the
application.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
319
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERALM (DbqerALM for C)
Item
Code
Mnemonic
Field
Value
QERALMNR
(entriesRemaining for C,
ENTRIES-REMAINING
for COBOL,
ENTRIES_REMAINING
for PL/I)
A 2byte unsigned integer indicating the
number of entries not returned.
QERALMNP
(entriesPresent for C,
ENTRIES-PRESENT for
COBOL,
ENTRIES_PRESENT for
PL/I)
A 2byte unsigned integer indicating the
number of entries returned.
QERALMLN
(entryLen for C,
ENTRY-LEN for
COBOL, ENTRY_LEN
for PL/I)
A 2byte unsigned integer indicating the
length of each entry.
Immediately following are the number of entries indicated by
QERALMNP, each of length indicated by QERALMLN. Each entry
consists of:
QERALENM
('name' for C, COBOL,
and PL/I)
An 8byte logon mechanism name, in
EBCDIC.
QERALEA
('attr' for C, COBOL,
and PL/I)
A 1 byte EBCDIC value containing either
"D", with mnemonic QERALEAD
('QER_MechAttrDefault' for C,
QER_MECH_ATTR_DEFAULT for PL/I) if
this is the default mechanism, or a space,
with mnemonic QERALEAN
(QER_MechAttrNone for C, NONE for
COBOL, QER_MECH_ATTR_NONE for
PL/I) otherwise. The default attribute is not
meaningful to CLIv2 but may be used by the
application in selecting a mechanism.
Seven unused bytes.
Default-character-set
Default-character-set name might be used to determine if the character set that will be used if
none is specified is acceptable to the application.
Refers to the TDP whose TDP identifier is addressed by the QEPTIDP field and has length
specified by the QEPTLEN field.
Returns the default character set name from the HSHSPB or, if no such default exists, the
Teradata Database's default character set name. Note that any default character set code in the
320
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
HSHSPB is ignored since its use has long been deprecated, so the Database default is returned
with a return code of 1127 to warn of the ignored code.
DBQERDCS (DbqerDCS for C)
Item Code
Mnemonic
Field
Value
33
QEPIDCS
QERDCS
('name' for C,
COBOL, and PL/I)
Thirty EBCDIC characters, left-justified,
padded on the right with spaces.
Database-release
Database-release might be used to aid in problem diagnosis.
Refers to the Teradata Database associated with the TDP whose TDP identifier is
addressed by the QEPTIDP field and has length specified by the QEPTLEN field.
Returns the Teradata Database's release and version. The response consists of two fields
totalling sixty-two bytes.
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.
Response DBQERDBR (DbqerDBR for C)
Item
Code
Mnemonic
Fields
Value
34
QEPIDBR
QERDBRR
('release' for C and
PL/I)
Thirty EBCDIC characters identifying the
Database release. This information is the
EBCDIC equivalent of the InfoData field for
the row whose InfoKey column contains
'RELEASE' in DBC.DBCInfoTbl.
QERDBRV
('version' for C, COBOL,
and PL/I)
Thirty-two EBCDIC characters identifying
the Database version. This information is
the EBCDIC equivalent of up to the first
thirty-two characters of the InfoData field
for the row whose InfoKey column contains
'VERSION' in DBC.DBCInfoTbl, leftjustified and padded with spaces as
necessary.
CLIv2-limits
CLIv2-limits might be used either to choose CLIv2 settings to optimize its execution for the
accessed Teradata Database or to prevent errors caused by exceeding limits.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
321
Chapter 8: CLIv2 Query Routine
DBCHQE
Returns limits for the Teradata Database affecting an application's values for CLIv2 settings.
The response consists of four fields totalling thirty-two bytes.
DBQERC2L (DbqerC2L for C)
Item
Code
Mnemonic
Fields
Value
35
QEPIC2L
QERC2LQL
('requestLen' for C,
REQUEST-LEN for
COBOL,
REQUEST_LEN for PL/
I) is the maximum
Request-length
An eight-byte unsigned integer. In C
compilers not supporting 64bit integers, an
array named 'requestLenHalf' consisting of
two four-byte unsigned integers, each
containing four bytes of the value, is used.
QERC2LGL
('segmentLen' for C,
SEGMENT-LEN for
COBOL,
SEGMENT_LEN for PL/
I) is the maximum
segment Request-length
for SQL Stored
Procedures (refer to
Chapter 17: “Stored
Procedures”)
An eight-byte unsigned integer. In C
compilers not supporting 64bit integers, an
array named 'segmentLenHalf' consisting of
two four-byte unsigned integers, each
containing four bytes of the value, is used.
QERC2LUL ('usingLen'
for C, USING-LEN for
COBOL, USING_LEN
for PL/I) is the
maximum
Using-data-len
An eight-byte unsigned integer. In C
compilers not supporting 64bit integers, an
array named 'usingLenHalf' consisting of
two four-byte unsigned integers, each
containing four bytes of the value, is used.
QERC2LSL
('responseLen' for C,
RESPONSE-LEN for
COBOL,
RESPONSE_LEN for PL/
I) is the maximum
Response-len
An eight-byte unsigned integer. In C
compilers not supporting 64bit integers, an
array named 'responseLenHalf' consisting of
two four-byte unsigned integers, each
containing four bytes of the value, is used.
SQL-limits
The SQL-limits might be used either to construct SQL statements to optimize its execution for
the accessed Teradata Database or to prevent errors caused by exceeding limits.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns limits for the Teradata Database affecting an application's use of SQL statements. The
response consists of twenty-four field totalling one-hundred four bytes.
322
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
DBQERSQL (DbqerSQL for C)
Item
Code
Mnemonic
Fields
Value
36
QEPISQL
QERSQLRL ('rowLen' for C,
ROW-LEN for COBOL,
ROW_LEN for PL/I) is the
number of usable bytes in a
database row.
An eight-byte unsigned integer. In C
compilers not supporting 64bit
integers, an array named
'rowLenHalf' consisting of two fourbyte unsigned integers, each
containing four bytes of the value, is
used.
QERSQLLL ('lobLen' for C,
LOB-LEN for COBOL,
LOB_LEN for PL/I) is the
maximum number of bytes for a
large object, either a binary or
character object.
An eight-byte unsigned integer. In C
compilers not supporting 64bit
integers, an array named 'lobLenHalf'
consisting of two four-byte unsigned
integers, each containing four bytes of
the value, is used.
QERSQLNL ('nameCharlen' for
C, NAME-CHARLEN for
COBOL, NAME_CHARLEN for
PL/I) is the maximum number of
single-byte characters in a
Teradata name (such as a userid,
table name, column name). The
presence of multi-byte characters
will correspondingly lower the
effective maximum.
A four-byte unsigned integer.
QERSQLKT ('tableColumns' for
C, TABLE-COLUMNS for
COBOL, TABLE_COLUMNS
for PL/I) is the maximum
number of columns in a table.
A four-byte unsigned integer.
QERSQLTS ('selectTables' for C,
SELECT-TABLES for COBOL,
SELECT_TABLES for PL/I) is the
maximum number of tables that
may be specified in a SELECT
statement.
A four-byte unsigned integer.
QERSQLKS
('expressionColumns' for C,
EXPRESSION-COLUMNS for
COBOL,
EXPRESSION_COLUMNS for
PL/I) is the maximum number of
columns that may be specified in
a SELECT statement expression.
A four-byte unsigned integer.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
323
Chapter 8: CLIv2 Query Routine
DBCHQE
DBQERSQL (DbqerSQL for C)
Item
Code
324
Mnemonic
Fields
Value
QERSQLKG ('groupbyColumns'
for C, GROUPBY-COLUMNS
for COBOL,
GROUPBY_COLUMNS for PL/
I) is the maximum number of
columns that may be specified in
a GROUPBY SQL clause.
A four-byte unsigned integer.
QERSQLKO ('orderbyColumns'
for C,
ORDERBY-COLUMNS
for COBOL,
ORDERBY_COLUMNS for PL/
I) is the maximum number of
columns that may be specified in
a ORDERBY SQL clause.
A four-byte unsigned integer.
QERSQLLC ('charLitCharlen'
for C, CHAR-LIT-CHARLEN
for COBOL,
CHAR_LIT_CHARLEN for PL/
I) is the maximum number of
single-byte characters for a
CHARACTER literal (a string of
characters enclosed by
apostrophes). The presence of
multi-byte characters will
correspondingly lower the
effective maximum.
A four-byte unsigned integer.
QERSQLLH ('hexLitCharlen' for
C, HEX-LIT-CHARLEN for
COBOL, HEX_LIT_CHARLEN
for PL/I) is the maximum
number of single-byte characters
for a HEXADECIMAL literal (a
string of hexadecimal characters
enclosed by apostrophes and
followed by at least the letter X).
The presence of multi-byte
characters will correspondingly
lower the effective maximum.
A four-byte unsigned integer.
QERSQLKL ('columnLen' for C,
COLUMN-LEN
for COBOL, COLUMN_LEN for
PL/I) is the maximum number of
bytes for a column.
A four-byte unsigned integer.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
DBQERSQL (DbqerSQL for C)
Item
Code
Mnemonic
Fields
Value
QERSQLC ('charCharlen' for C,
CHAR-CHARLEN for COBOL,
CHAR_CHARLEN for PL/I) is
the maximum number of singlebyte characters in a column of
data type CHARACTER. The
presence of multi-byte characters
will correspondingly lower the
effective maximum.
A four-byte unsigned integer.
QERSQLVC ('varcharCharlen'
for C, VARCHAR-CHARLEN
for COBOL,
VARCHAR_CHARLEN for PL/
I) is the maximum number of
single-byte characters in a
column of data type VARCHAR.
The presence of multi-byte
characters will correspondingly
lower the effective maximum.
A four-byte unsigned integer.
QERSQLG ('graphicCharlen' for
C, GRAPHIC-CHARLEN for
COBOL, GRAPHIC_CHARLEN
for PL/I) is the maximum
number of two-byte characters in
a column of data type
GRAPHIC.
A four-byte unsigned integer.
QERSQLVG
('vargraphicCharlen' for C,
VARGRAPHIC-CHARLEN for
COBOL,
VARGRAPHIC_CHARLEN for
PL/I) is the maximum number of
two-byte characters in a column
of data type VARGRAPHIC.
A four-byte unsigned integer.
QERSQLB ('byteLen' for C,
BYTE-LEN for COBOL,
BYTE_LEN for PL/I) is the
maximum number of bytes in a
column of data type BYTE.
A four-byte unsigned integer.
QERSQLVB ('varbyteLen' for C,
VARBYTE-LEN for COBOL,
VARBYTE_LEN for PL/I) is the
maximum number of bytes in a
column of data type VARBYTE.
A four-byte unsigned integer.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
325
Chapter 8: CLIv2 Query Routine
DBCHQE
DBQERSQL (DbqerSQL for C)
Item
Code
326
Mnemonic
Fields
Value
QERSQLPD ('decimalPrecision'
for C, DECIMAL-PRECISION
for COBOL,
DECIMAL_PRECISION for PL/
I) is the maximum precision
(number of digits) in a column
of data type DECIMAL or
NUMERIC.
A four-byte unsigned integer.
QERSQLET ('timeScale' for C,
TIME-SCALE for COBOL,
TIME_SCALE for PL/I) is the
maximum scale (number of
digits to the right of the decimal
point; sometimes referred to as
the fractionalized precision) in a
column of data type TIME
[WITH TIME ZONE].
A four-byte unsigned integer.
QERSQLEP ('timestampScale'
for C, TIMESTAMP-SCALE for
COBOL, TIMESTAMP_SCALE
for PL/I) is the maximum scale
(number of digits to the right of
the decimal point; sometimes
referred to as the fractionalized
precision) in a column of data
type TIMESTAMP [WITH
TIME ZONE].
A four-byte unsigned integer.
QERSQLES
('intervalSecondScale' for C,
INTERVAL-SECOND-SCALE
for COBOL,
INTERVAL_SECOND_SCALE
for PL/I) is the maximum scale
(number of digits to the right of
the decimal point; sometimes
referred to as the fractionalized
precision) in a column of data
type INTERVAL DAY TO
SECOND, INTERVAL HOUR
TO SECOND, INTERVAL
MINUTE TO SECOND, or
INTERVAL SECOND.
A four-byte unsigned integer.
QERSQLUN ('usingValues' for
C, USING-VALUES for COBOL,
USING_VALUES for PL/I) is the
maximum number Teradata
SQL USING row descriptor
fields.
A four-byte unsigned integer.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
DBQERSQL (DbqerSQL for C)
Item
Code
Mnemonic
Fields
Value
QERSQLPQ ('requestParms' for
C, REQUEST-PARMS for
COBOL, REQUEST_PARMS for
PL/I) is the maximum number of
variable names in a Teradata/
SQL parameterized query
request.
A four-byte unsigned integer.
QERSQLPP ('procedureParms'
for C, PROCEDURE-PARMS for
COBOL, PROCEDURE_PARMS
for PL/I) is the maximum
number of parameters to a stored
procedure.
A four-byte unsigned integer.
Relaxed-call-args
The Relaxed-call-args might be used to simplify construction of SQL CALL statements.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns whether CALL OUT-type argument requirements are relaxed by allowing such
names on the CALL statement to differ from those on the PROCEDURE statement, to be
specified as host variables (':name'), or to be specified as placeholders ('?'). These host variable
names need not be defined in the USING clause.
This item is also included in the Aggregate-support-list query item.
Response DBQERRCA (DbqerRCA for C)
Item
Code
Mnemonic
Field
Value
37
QEPIRCA
QERRCA
('status' for C and PL/I)
One of the following EBCDIC
characters:
'N' with mnemonic QERRCAN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED
for PL/I)
'Y' with mnemonic QERRCAY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED for PL/I)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
327
Chapter 8: CLIv2 Query Routine
DBCHQE
Statement-info-status
Statement-info-status might be used to ascertain if the StatementInformation parcels may be
requested by the DBCAREA Return-statement-info option.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns whether StatementInformation parcels are supported.
This item is also included in the Aggregate-support-list query item.
DBQERSIS (DbqerSIS for C)
Item
Code
Mnemonic
Field
Value
38
QEPISIS
QERSIS
('status' for C and PL/I)
One of the following EBCDIC
characters:
'N' with mnemonic QERSISN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED)
for PL/I)
'Y' with mnemonic QERSISY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED) for PL/I)
Integer/decimal-enlargement
Integer/decimal-enlargement might be used to ascertain wheter the DBCAREA
Max-decimal-returned option is supported by Teradata Database.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns whether the maximum size of the decimal data type in responses may be specified.
This item is also included in the Aggregate-support-list query item.
DBQERIDE (DbqerIDE for C
Item
Code
Mnemonic
Field
Value
39
QEPIIDE
QERIDE
('status' for C and PL/I)
One of the following EBCDIC
characters:
'N' with mnemonic QERIDEN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED)
for PL/I)
328
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
DBQERIDE (DbqerIDE for C
Item
Code
Mnemonic
Field
Value
'Y' with mnemonic QERSISY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED) for PL/I)
Return-Identity-Data-support
Return-Identity-Data-support might be used to ascertain whether the DBCAREA
Return-identity-data option may be specified to request data be returned in response to an
SQL Insert operation when Identity columns are involved.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns whether returning data for SQL Inserts when Identity columns are involved.
This item is also included in the Aggregate-support-list query item.
DBQERRID (DbqerRID for C)
Item
Code
Mnemonic
Field
Value
40
QEPIRID
QERRID
('status' for C and PL/I)
One of the following EBCDIC
characters:
'N' with mnemonic QERRIDN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED)
for PL/I)
'Y' with mnemonic QERRIDY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED) for PL/I)
Result-sets-support
Result-sets-support might be used to ascertain whether the DBCAREA Result-sets-OK or
Return-Result-to options may be specified.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns whether stored procedures may return the results of their SQL statements to the
application.
This item is also included in the Aggregate-support-list query item.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
329
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERRSS (DbqerRSS for C)
Item
Code
Mnemonic
Field
Value
41
QEPIRSS
QERRSS
('status' for C and PL/I)
One of the following EBCDIC
characters:
One of the following EBCDIC
characters: 'N' with mnemonic
QERRSSN (QER_NotSupported
for C, NOT-SUPPORTED for
COBOL,
QER_NOT_SUPPORTED for PL/
I)
'Y' with mnemonic QERRSSY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED for PL/I)
QueryBand-support
QueryBand-support might be used to ascertain whether the Teradata SQL SET
QUERY_BAND statement may be used to associate descriptive information with a session or
transaction.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns whether Teradata Database supports the SQL SET QUERY_BAND statement.
This item is also included in the Aggregate-support-list query item.
Response DBQERQBS (DbqerQBS for C)
Item
Code
Mnemonic
Field
Value
42
QEPIQBS
QERQBS
('status' for C and PL/I)
One of the following EBCDIC
characters:
'N' with mnemonic QERQBSN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED for PL/
I)
'Y' with mnemonic QERQBSY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED for PL/I)
330
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Merge-into-usage
Merge-into-usage might be used to ascertain the degree to which the Database supports the
SQL MERGE INTO statement.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns the degree of support for the SQL MERGE INTO statement.
This item is also included in the Aggregate-support-list query item.
DBQERMIU (DbqerMIU for C)
Item
Code
Mnemonic
Field
Value
43
QEPIMIU
QERMIU
('usage' for C and PL/I)
A two-byte unsigned integer
containing one of the following
values:
0 with mnemonic QERMIUN
(QER_MergeUsageNone for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED for PL/
I) if the statement is not supported.
(This is equivalent to an 'N' for the
deprecated Merge-into-support
query.)
1 with mnemonic QERMIUS
(QER_MergeUsageSingleRow for
C, SINGLE-ROW for COBOL,
QER_MERGE_USAGE_SINGLE_
ROW for PL/I) if only single-row
MERGE INTO is supported. (This
is equivalent to a 'Y' for the
deprecated Merge-into-support
query.)
2 with mnemonic QERMIUM
(QER_MergeUsageMultiRow for
C, MULTI-ROW for COBOL,
QER_MERGE_USAGE_MULTI_R
OW for PL/I) if multi-row MERGE
INTO is supported.
Logging-errors-usage
Logging-errors-usage might be used to ascertain the degree to which the Database supports
the Teradata SQL LOGGING ERRORS clause.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns the degree of support for the Teradata SQL LOGGING ERRORS clause.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
331
Chapter 8: CLIv2 Query Routine
DBCHQE
This item is also included in the Aggregate-support-list query item.
DBQERLEU (DbqerLEU for C)
Item
Code
Mnemonic
Field
Value
44
QEPILEU
QEPILEU
('usage' for C and PL/I)
A two-byte unsigned integer
containing one of the following
values:
0 with mnemonic QERLEUN
(QER_LoggingUsageNone for C,
NOT-SUPPORTED for COBOL,
QER_LOGGING_USAGE_NONE
for PL/I) if the clause is not
supported.
1 with mnemonic QERLEUM
(QER_LoggingUsageMerge for C,
QERLEUM for COBOL,
QER_LOGGING_USAGE_MERG
E for PL/I) if the clause is
supported for MERGE INTO,
INSERT, and SELECT statements.
Procedure-data
Procedure-data might be used by an External Stored Procedure to ascertain whether the
DBCAREA Use-default-conn option is honored.
Refers to the CLIv2 being invoked.
Returns information for use by a External Stored Procedure. New items may be added;
therefore, the length of the result may vary depending on the version of CLIv2 or Teradata
Database.
DBQERPD (DbqerPD for C)
332
Item
Code
Mnemonic
Field
Value
45
QEPIPD
QERPDDC
('dfltConnStatus' for C,
DFLT-CONN-STATUS for
COBOL, DFLT_CONN_STATUS
for PL/I)
One of the following EBCDIC
characters:
'N' with mnemonic QERPDDCN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED for PL/
I) if the DBCAREA
Use-default-conn option is not
honored.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
DBQERPD (DbqerPD for C)
Item
Code
Mnemonic
Field
Value
'Y' with mnemonic QERPDDCY
(QER_Supported for C,
SUPPORTED for COBOL,
QER_SUPPORTED for PL/I) if the
DBCAREA Use-default-conn
option is honored.
Session-character-set
Session-character-set obtains the name of a character set that is not explicitly specified.
Refers to the session whose CLIv2 connection number is specified in the QEPCONN field.
Returns the name of the session character set.
Response DBQERSCS (DbqerSCS for C)
Item
Code
Mnemonic
Field
Value
46
QEPISCS
QERSCS
('name' for C)
Between 1 and 30 EBCDIC characters.
Column-correlation-support
Use Column-correlation-support to ascertain whether the Teradata SQL CREATE
CORRELATION statement is supported.
Refers to the Teradata Database associated with the TDP, whose TDP identifier is addressed
by the QEPTIDP field, and whose length is specified by the QEPTLEN field.
Returns information about whether Teradata Database supports SQL CREATE, UPDATE,
DROP, and HELP CORRELATION statements.
This item is also included in the Aggregate-support-list query item.
Response DBQERCCS (DbqerCCS for C)
Item
Code
Mnemonic
Field
Value
47
QEPICCS
QERCCS
('status' for C and
PL/I)
One of the following EBCDIC characters:
'N' with mnemonic QERCCSN
(QER_NotSupported for C, NOT-SUPPORTED
for COBOL, QER_NOT_SUPPORTED for PL/I) '
Y' with mnemonic QERCCSY (QER_Supported
for C, SUPPORTED for COBOL,
QER_SUPPORTED for PL/I)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
333
Chapter 8: CLIv2 Query Routine
DBCHQE
Utility-session
Utility-session is used internally only by Teradata utilities, and is not intended for other
applications.
Refers to the session whose CLIv2 connection number is specified in the QEPCONN field.
Returns information for internal use by Teradata utilities. Because new items might be added
in the future, the length of the result might vary depending on the active version of CLIv2 or
TDP.
Response DBQERIUS (DbqerUS for C)
Item
Code
Mnemonic
Field
Value
48
QEPIUS
QERUSNI
('nodeid' for C,
NODE-ID for Cobol, and
NODE_ID for PL/I))
A two-byte unsigned integer containing the
unformatted Teradata Database node-id
associated with the session. A value of zero
indicates that the node-id is not available.
Note: Currently, no version of the Teradata
Database provides the node-id to
channel-attached systems, so the value is
always zero.
Database-access-path
Use Database-access-path to find the TDPid used, regardless of how it was determined.
Refers to the session whose CLIv2 connection number is specified in the QEPCONN field.
Returns the path used to access the request Teradata Database. On channel-attached systems,
the path is the TDPid. The value is also returned in the DBCAREA Output-path-id field.
This item is included in the Aggregate-support-list query item.
Response DBQERDAP (DbqerDAP for C)
Item
Code
Mnemonic
Field
Value
49
QEPIDAP
QERDAP
('path' for C,
COBOL, and PL/I)
One of the following:
• If the QEP Varying-result-format is specified
as QEPVRFC, a variable number of EBCDIC
characters.
• If the QEP Varying-result-format is specified
as QEPVRF2C, a 2-byte unsigned integer
followed by that number of EBCDIC
characters.
The returned value contains no leading or trailing blanks.
334
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Trusted-session-support
Of no use to normal applications. If an application establishes its own Teradata session and
subsequently uses that session to perform its own requests using the security credentials of
another userid, then Trusted-session-support determines whether the Teradata SQL SET
QUERY_BAND PROXYUSER is honored rather than silently ignored.
Refers to the Teradata Database whose TDP identifier is both addressed in the QEPTIDP field
and has its length specified by the QEPTLEN field.
Returns whether a Teradata Database honors rather than ignores the Teradata SQL SET
QUERY_BAND PROXYUSER statement.
Response DBQERTSS (DbqerTSS for C)
Item
Code
Mnemonic
Field
Value
50
QEPITSS
QERLTSS
('status' for C and
PL/I)
One of the following EBCDIC:
• 'N' with mnemonic QERTSSN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED for PL/I)
• 'Y' with mnemonic QERTSSY
(QER_Supported for C, SUPPORTED for
COBOL, QER_SUPPORTED for PL/I)
LOB-Name-support
Determines whether a DEFERRED LOB can be identified by name.
Refers to the Teradata Database whose TDP identifier is both addressed in the QEPTIDP field
and has its length specified by the QEPTLEN field.
Returns whether the BY NAME phrase is permitted in the USING row descriptor in the
request string.
Response DBQERLNS (DbqerLNS for C)
Item
Code
Mnemonic
Field
Value
51
QEPILNS
QERLNS
('status' for C and
PL/I)
One of the following EBCDIC:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
• 'N' with mnemonic QERLNSN
(QER_NotSupported for C,
NOT-SUPPORTED for COBOL,
QER_NOT_SUPPORTED for PL/I)
• 'Y' with mnemonic QERLNSY
(QER_Supported for C, SUPPORTED for
COBOL, ER_SUPPORTED for PL/I)
335
Chapter 8: CLIv2 Query Routine
DBCHQE
Transforms-off-usage
Transforms-off-usage might be used to ascertain the degree to which the Database supports
referencing the constituent attributes of SQL Structured User Defined Types (UDTs).
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns the degree of support for referencing the constituent attributes of SQL Structured
User Defined Types (UDTs).
This item is also included in the Aggregate-support-list query item.
Response DBQERTOU (DbqerTOU for C)
Item
Code
Mnemonic
Field
Value
52
QEPITOU
QERTOU
('usage' for C and
PL/I)
A two-byte unsigned integer containing one of
the following values:
0 with mnemonic QERTOUN
(QER_XformsOffUsageNone for C, NOTSUPPORTED for COBOL,
QER_XFORMS_OFF_NONE for PL/I) if no
UDTs may be transformed.
1 with mnemonic QERTOUS
(QER_XformsOffUsageStruct for C,
STRUCTURED for COBOL,
QER_XFORMS_OFF_STRUCT for PL/I) if
Structured UDTs may be transformed.
2 with mnemonic QERTOUP
(QER_XformsOffUsagePeriod for C, PERIOD for
COBOL, QER_XFORMS_OFF_Period for PL/I)
if Period data types may be transformed.
Transforms-request-support
There is no known use for the Trusted-request-support query.
Refers to the Teradata Database associated with the TDP whose TDP identifier is addressed by
the QEPTIDP field and has length specified by the QEPTLEN field.
Returns whether the DBCAREA Trusted-request option will be honored or ignored.
336
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query Routine
DBCHQE
Response DBQERTRS (DbqerTRS for C)
Item
Code
Mnemonic
Field
Value
53
QEPITRS
QERTRS
('usage' for C and
PL/I)
One of the following EBCDIC characters:
'N' with mnemonic QERTRSN
(QER_NotSupported for C, NOT-SUPPORTED
for COBOL, QER_NOT_SUPPORTED for PL/I)
'Y' with mnemonic QERTRSY
(QER_Supported for C, SUPPORTED for
COBOL, QER_SUPPORTED for PL/I)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
337
Chapter 8: CLIv2 Query Routine
DBCHQE
338
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 9
Response Sequences
This chapter describes:
•
Buffers
•
Typical Teradata SQL Response Sequences
•
Typical Teradata Response Sequences
•
Parcels in Normal Sequences
•
Parcels That Indicate Problems
Buffers
The following buffers hold parcels being sent to and from the Teradata Database.
Request Buffer
Information to be sent to the Teradata Database is placed by CLIv2 in a request buffer. CLIv2
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.
DBCHCL uses field values that the application has placed in the DBCAREA to determine
which parcels to send to the Teradata Database and what to put in them. The application does
not see the request buffer.
How to Calculate Maximum Length
The maximum length (in bytes) needed for the request buffer can be calculated as follows:
maximum Request Buffer Length =
(14 if Request Processing Option = ‘P‘) +
(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‘) +
(length of parcels in any {DBCAIRX extension} +
(6 for overhead)
The second and fifth lines are always included in the calculation. The third line is included
only if data is being sent to the Teradata Database. The first line is included only if Request
Processing Option = P.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
339
Chapter 9: Response Sequences
Buffers
Response Buffer
Information received from the Teradata Database is placed in a buffer called the response
buffer. If Two Response Buffers is set to ‘Y‘ in the DBCAREA, CLIv2 uses double buffering,
and each buffer is the size specified in the DBCAREA. CLIv2 allocates the buffers when
DBCHCL is called for any of the following functions:
•
Connect
•
RunStartUp
•
Initiate with Protocol-Function
•
Command
•
Initiate Request function
If Save
Response Buffer
is set to...
Then CLIv2...
N
deallocates the buffers when DBCHCL is called for the End Request function.
Y
saves one response buffer 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.
Parcels received from the Teradata Database are stored in the response buffers in the
following ways.
If the value for Locate Mode is...
Then DBCHC makes the response parcels available...
Y (Locate Mode)
to the application in the response buffers
N (Mode Mode) and Parcel Mode
is Y
in the user-specified move area
CLIv2 automatically replenishes the response buffers. That is,
the application may call DBCHCL for the Fetch function
repeatedly.
The response buffers may or may not be large enough to hold all the parcels in the response,
but the application can draw on them as if they are.
Response Buffers and Rewind
If the application 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 buffers. 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 or buffers.
The response buffer must be at least long enough to hold an Error parcel or Failure parcel, so
that the application can detect a problem if it arises. If the response buffer is not long enough
for the longest parcel, CLIv2 expands the buffer to the required size (if less than the maximum
340
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Buffers
size) at the time it encounters the longest parcel. If the server requires a response buffer larger
than 32767 bytes but Maximum-parcel is not set to H, then an Error parcel with error code
3115 will be returned.
An Error parcel with error code 3115, 3116, or 3177 may also be returned if that parcel
contains an invalid information field (zero, greater than 32767 when Maximum-parcel is set
to O, or not greater than the existing buffer size).
Response Buffer Length and Performance
The growth operation costs CPU time. If an application is being optimized for performance
and Current Response Buffer Length is higher than Response Buffer Length, consider
increasing Response Buffer Length. 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 CLIv2, 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.
Active Buffers Per Request
There are times when CLIv2‘s sending in to the Teradata Database for the next buffer full of a
response conflicts with CLIv2‘s sending in a new request to the Teradata Database. The rule in
effect 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 restocking
requests done “behind the scenes.” If CLIv2 is restocking response buffers, CLIv2 returns 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.
Move Area
The application can 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 has allocated a move area, then, when
the application 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 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 do 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/I, 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. Mode Move is primarily for
use in languages that do not support pointer operations.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
341
Chapter 9: Response Sequences
Typical Teradata SQL Response Sequences
Typical Teradata SQL Response Sequences
Teradata Database generates one or more parcels in response to a request it receives. It then
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 the buffer for that request.
Response parcels are screened by CLIv2 before the application receives them. If a problem
develops and CLIv2 is able to resolve it, the application may not see an error returned by the
Teradata Database. For example, if CLIv2 screens an Error parcel which indicates that the
response buffer is too small, CLIv2 will automatically expand the buffer and request that
portion of the buffer again. The application will not know that the error existed and that it
was resolved by CLIv2.
The application can process 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 CLIv2 and TDP have encountered no problems. To learn whether the Teradata
Database has detected problems, the parcel flavor must be checked.
Typical Teradata Response Sequences
The following sections contain the Teradata SQL response sequences for typical Teradata SQL
statements. Examples are provided throughout this chapter.
To discover the Teradata SQL response sequence for a Teradata SQL statement that is not
included here, do the following:
1
Submit the Teradata SQL statement.
2
Call DBCHCL with the fetch function, repeatedly, to see each parcel.
3
Stop when the EndRequest parcel is encountered.
Submitting Requests In 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:
Table 42: Response Parcel Sequence in Field Mode
If the Teradata SQL
statement is...
Then the response parcels are as follows...
non-data returning
OK parcel (flavor 17) or ResultSummary (flavor 171), the activity count will
reflect the number of rows affected if an insert, update or delete statement;
the activity count is zero for all other non-data returning statements.
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
342
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Table 42: Response Parcel Sequence in Field Mode (continued)
If the Teradata SQL
statement is...
Then the response parcels are as follows...
data returning, or a
Select statement with
no WITH clause
OK parcel (flavor 17) or ResultSummary (flavor 171), the activity count will
reflect the number of rows returned.
TitleStart parcel (flavor 20)
The following parcel is repeated once for each column returned:
Field parcel (flavor 18)
TitleEnd parcel (flavor 21)
FormatStart parcel (flavor 22)
The following parcel is repeated once for each column returned:
Field parcel (flavor 18)
FormatEnd parcel (flavor 23)
SizeStart parcel (flavor 24)
The following parcel is repeated once for each column returned:
Size parcel (flavor 26)
SizeEnd parcel (flavor 25)
The following parcels are repeated activity-count number of times:
RecStart parcel (flavor 27)
The following parcel is repeated once for each column returned:
Field parcel (flavor 18)
RecEnd parcel (flavor 28)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
a Select statement
having one or more
WITH clauses
OK parcel (flavor 17) or ResultSummary (flavor 171), the activity count will
reflect the number of rows returned.
TitleStart parcel (flavor 20)
The following parcel is repeated once for each column returned:
Field parcel (flavor 18)
TitleEnd parcel (flavor 21)
FormatStart parcel (flavor 22)
The following parcel is repeated once for each column returned:
Field parcel (flavor 18)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
343
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Table 42: Response Parcel Sequence in Field Mode (continued)
If the Teradata SQL
statement is...
Then the response parcels are as follows...
FormatEnd parcel (flavor 23)
SizeStart parcel (flavor 24)
The following parcel is repeated once for each column returned:
Size parcel (flavor 26)
SizeEnd parcel (flavor 25)
The following parcels repeat for each WITH clause:
With parcel (flavor 33)
PosStart parcel (flavor 46)
The following parcel is repeated once for each column in WITH clause:
Position parcel (flavor 34)
PosEnd parcel (flavor 47)
TitleStart parcel (flavor 20)
The following parcel is repeated once for each column in WITH clause:
Field parcel (flavor 18)
TitleEnd parcel (flavor 21)
FormatStart parcel (flavor 22)
The following parcel is repeated once for each column in WITH clause:
Field parcel (flavor 18)
FormatEnd parcel (flavor 23)
SizeStart parcel (flavor 24)
The following parcel is repeated once for each column in WITH clause:
Size parcel (flavor 26)
SizeEnd parcel (flavor 25)
EndWith parcel (flavor 35)
The following parcels are repeated activity-count number of times
RecStart parcel (flavor 27)
The following parcel is repeated once for each column returned:
Field parcel (flavor 18)
RecEnd parcel (flavor 28)
344
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Table 42: Response Parcel Sequence in Field Mode (continued)
If the Teradata SQL
statement is...
Then the response parcels are as follows...
With parcel (flavor 33)
RecStart parcel (flavor 27)
The following parcel is repeated once for each column in WITH clause:
Field parcel (flavor 18)
RecEnd parcel (flavor 28)
EndWith parcel (flavor 35)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
an ECHO request
OK parcel (flavor 17) or ResultSummary (flavor 171)
RecStart parcel (flavor 27)
Field parcel (flavor 18)
RecEnd parcel (flavor 28)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
Submitting Requests In 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:
Note: These response parcels are not necessarily in the order in which they are returned. See
“Parcel Sequences” on page 349 for the correct return sequence.
Table 43: Response parcel sequence in Record Mode
If the Teradata SQL
statement is...
Then the response parcels are as follows...
non-data returning
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity code
will reflect the number of rows affected if an insert, update or delete
statement; the activity count is zero for all other non-data returning
statements.
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
345
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Table 43: Response parcel sequence in Record Mode (continued)
If the Teradata SQL
statement is...
Then the response parcels are as follows...
data returning, or a
Select statement with
no WITH clause
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity
count will reflect the number of rows returned.
The following parcel is repeated activity-count number of times:
Record parcel (flavor 10)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
a Select statement
having one or more
WITH clauses
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity count
will reflect the number of rows returned, including summary rows resulting
from WITH clauses.
The following parcel is repeated activity-count number of times:
Record parcel (flavor 10)
The following parcels are repeated for each summary row:
With parcel (flavor 33)
Record parcel (flavor 10)
EndWith parcel (flavor 35)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
an ECHO request
Success parcel (flavor 8) or ResultSummary (flavor 171)
Record parcel (flavor 10)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
Submiting Requests—MultipartIndicator 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:
Table 44: Response Sequence in MultipartIndicator Mode
If the Teradata SQL
statement is...
non-data returning
346
Then the response parcels are as follows...
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity count
will reflect the number of rows affected if an insert, update, or delete
statement; the activity count is zero for all other non-data returning
statements.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Table 44: Response Sequence in MultipartIndicator Mode (continued)
If the Teradata SQL
statement is...
Then the response parcels are as follows...
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
data returning, or a
Select statement with
no WITH clause
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity count
will reflect the number of rows returned.
DataInfoX parcel (flavor 146) or StatementInformation (flavor 169) and
StatementInformationEnd (flavor 170)
The following parcel is repeated activity-count number of times:
One or more MultipartRecord parcels (flavor 144)
EndMultipartRecord parcel (flavor 145)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
a Select statement
having one or more
WITH clauses
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity count
will reflect the number of rows returned, including summary rows resulting
from WITH clauses
DataInfoX parcel (flavor 146) or StatementInformation (flavor 169) and
StatementInformationEnd (flavor 170)
With parcel (flavor 33)
PosStart parcel (flavor 46)
Position parcel (flavor 34)
PosEnd parcel (flavor 47)
EndWith parcel (flavor 35)
DataInfoX parcel (flavor 146) or StatementInformation (flavor 169) and
StatementInformationEnd (flavor 170)
The following parcels are repeated activity-count number of times:
One or more MultipartRecord parcels (flavor 144)
EndMultipartRecord parcel (flavor 145)
The following parcels are repeated for each summary row:
With parcel (flavor 33)
One or more MultipartRecord parcels (flavor 144)
EndMultipartRecord parcel (flavor 145)
EndWith parcel (flavor 35)
EndStatement parcel (flavor 11)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
347
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Table 44: Response Sequence in MultipartIndicator Mode (continued)
If the Teradata SQL
statement is...
Then the response parcels are as follows...
EndRequest parcel (flavor 12)
an ECHO request
Success parcel (flavor 8) or ResultSummary (flavor 171).
One or more MultipartRecord parcels (flavor 144)
EndMultipartRecord parcel (flavor 145)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
Submitting Requests In 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:
Table 45: Response Parcel Sequence Indicator Mode
If the Teradata SQL
statement is...
Then the response parcels are as follows...
non-data returning
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity code
will reflect the number of rows affected if an insert, update or delete
statement; the activity count is zero for all other non-data returning
statements.
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
data returning, or a
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity count
Select statement with will reflect the number of rows returned.
no WITH clause
DataInfo parcel (flavor 71) or StatementInformation (flavor 169) and
StatementInformationEnd (flavor 170)
The following parcel is repeated activity-count number of times:
Record parcel (flavor 10)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
a Select statement
having one or more
WITH clauses
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity count
will reflect the number of rows returned, including summary rows resulting
from WITH clauses.
DataInfo parcel (flavor 71) or StatementInformation (flavor 169) and
StatementInformationEnd (flavor 170)
With parcel (flavor 33)
348
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Table 45: Response Parcel Sequence Indicator Mode (continued)
If the Teradata SQL
statement is...
Then the response parcels are as follows...
PosStart parcel (flavor 46)
Position parcel (flavor 34)
PosEnd parcel (flavor 47)
EndWith parcel (flavor 35)
DataInfo parcel (flavor 71) or StatementInformation (flavor 169) and
StatementInformationEnd (flavor 170)
The following parcel is repeated activity-count number of times:
Record parcel (flavor 10)
The following parcels are repeated for each summary row:
With parcel (flavor 33)
Record parcel (flavor 10)
EndWith parcel (flavor 35)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
an ECHO request
Success parcel (flavor 8) or ResultSummary (flavor 171)
Record parcel (flavor 10)
EndStatement parcel (flavor 11)
EndRequest parcel (flavor 12)
Parcel Sequences
CLIv2 constructs the correct parcel sequences to the Teradata Database software based on the
information supplied in the DBCAREA. The application should only be concerned with the
response parcels returned from the Teradata Database via CLIv2.
The following table explains parcel return sequences for various combinations of connect
types and return code fields.
Connect
Type.
Return Code
field is...
R
33
And...
Then...
code is 33 at the time the Fetch
function is issued for the
connect request
the response parcels do not have to be
scanned.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
349
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Connect
Type.
Return Code
field is...
R
0
And...
Then...
the parcel returned is one of the
following:
Failure parcel (flavor 9)
Error parcel (flavor 49)
C
non-zero
C
0
the response parcels do not have to be
scanned.
there is a problem establishing
the connection
the parcel returned will be one of the
following:
Failure parcel (flavor 9)
Error parcel (flavor 49)
C
0
the connection is successfully
established
the parcels returned will be both of
the following:
Success parcel (flavor 8) or
ResultSummary (flavor 171)
EndRequest parcel (flavor 12)
Issuing Requests—Field Mode
Field Mode requests may return the following parcels:
350
Name
Flavor
Failure
9
Error
49
OK
17
ResultSummary
171
Field
18
With
33
EndWith
35
FormatStart
22
FormatEnd
23
NullField
19
PosStart
46
Position
34
PosEnd
47
RecStart
28
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Name
Flavor
RecEnd
28
SizeStart
24
Size
26
SizeEnd
25
TitleStart
20
TitleEnd
21
EndStatement
11
EndRequest
12
The following examples assume successful completion of the request when using Original
Statement-status. If using Enhanced Statement-status, OK parcels will be replaced by
ResultSummary parcels. See Chapter 15: “Parcels for Basic Applications” or Chapter 16:
“Parcels for Advanced Applications” for detailed descriptions of parcels.
UPDATE TABLE1 SET FIELD1 = 999999;
Parcel
Flavor
Body
OK
17
(1, 0, 23, 3, 0, 0)
EndStatement
11
(1)
EndRequest
12
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
(title)
(format)
(size)
351
Chapter 9: Response Sequences
Typical Teradata Response Sequences
SELECT FIELD1 FROM TABLE1;
Parcel
Flavor
SizeEnd
25
RecStart (1)
27
Field
18
RecEnd (1)
28
.
.
.
.
.
.
RecStart (23)
27
Field
18
RecEnd (23)
28
EndStatement
11
EndRequest
12
Body
(data)
(data)
(1)
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1)
352
Parcel
Flavor
Body
OK
17
(1, 1, 24, 1, 0, 0)
TitleStart
20
Field
18
TitleEnd
21
FormatStart
22
Field
18
FormatEnd
23
SizeStart
24
Size
26
SizeEnd
25
With
33
PosStart
46
Position
34
(title)
(format)
(size)
(1)
(1)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1)
Parcel
Flavor
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
.
.
.
.
.
.
Body
(title)
(format)
(size)
(1)
(data)
RecStart (23)
27
Field
18
RecEnd (23)
28
With
33
(1)
Field
18
(data)
EndWith
35
(1)
EndStatement
11
(1)
EndRequest
12
(data)
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
Parcel
Flavor
Body
OK
17
(1, 1, 23, 1, 0, 0)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
353
Chapter 9: Response Sequences
Typical Teradata Response Sequences
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
354
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
.
.
.
.
Body
(title)
(format)
(size)
(data)
RecStart (23)
27
Field
18
RecEnd
28
EndStatement
11
(1)
OK
17
(2, 1, 10, 1, 0, 0)
TitleStart
20
Field
18
TitleEnd
21
FormatStart
22
Field
18
FormatEnd
23
SizeStart
24
Size
26
SizeEnd
25
RecStart (1)
27
(data)
(title)
(format)
(size)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
Parcel
Flavor
Body
Field
18
(data)
RecEnd (1)
28
.
.
.
.
.
.
RecStart (10)
27
Field
18
RecEnd (10)
28
EndStatement
11
EndRequest
12
(data)
(2)
ECHO ‘SELECT FIELD1 FROM TABLE1‘;
Parcel
Flavor
Body
OK
17
(1, 1, 0, 33, 0, 0)
RecStart
27
Field
18
RecEnd
28
EndStatement
11
EndRequest
12
(data)
(1)
Issuing Requests—Record Mode
Record Mode requests may return the following parcels:
Name
Flavor
Failure
9
Error
49
Success
8
ResultSummary
171
Record
10
With
33
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
355
Chapter 9: Response Sequences
Typical Teradata Response Sequences
Name
Flavor
EndWith
35
EndStatement
11
EndRequest
12
The following examples assume successful completion of the request when using Original
Statement-status. If using Enhanced Statement-status, OK parcels will be replaced by
ResultSummary parcels. See Chapter 15: “Parcels for Basic Applications” or Chapter 16:
“Parcels for Advanced Applications” for detailed descriptions of parcels.
UPDATE TABLE1 SET FIELD1 = 999999;
Parcel
Flavor
Body
Success
8
(1, 23, 0, 0, 3, 0)
EndStatement
11
(1)
EndRequest
12
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
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
356
Parcel
Flavor
Body
Success
8
(1, 24, 0, 1, 1, 0)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
Parcel
Flavor
Body
Record (1)
10
(data)
.
.
.
.
.
.
.
.
.
Record (23)
10
(data)
With
33
(1)
Record
10
(data)
EndWith
35
(1)
EndStatement
11
(1)
EndRequest
12
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
.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
357
Chapter 9: Response Sequences
Typical Teradata Response Sequences
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—MultipartIndicator Mode
MultipartIndicator Mode requests may return the following parcels:
Name
Flavor
Failure
9
Error
49
Success
8
ResultSummary
171
DataInfoX
146
MultipartRecord
144
StatementInformation
169
StatementInformationEnd
170
EndMultipartRecord
145
With
33
EndWith
35
PosStart
46
Position
34
PosEnd
47
EndStatement
11
EndRequest
12
The following examples assume successful completion of the request when using Original
Statement-status. If using Enhanced Statement-status, OK parcels will be replaced by
ResultSummary parcels. See Chapter 15: “Parcels for Basic Applications” or Chapter 16:
“Parcels for Advanced Applications” for detailed descriptions of parcels.
358
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
The following examples assume that the Return-statement-info 'Y' option was not specified; if
specified, DataInfoX parcels will be replaced by StatementInformation and
StatementInformationEnd parcels.
UPDATE TABLE1 SET FIELD1 = 999999
Parcel
Flavor
Body
Success
8
(1, 23, 0, 0, 3, 0)
EndStatement
11
(1)
EndRequest
12
UPDATE TABLE1 SET FIELD1 = 999999
Parcel
Flavor
Body
Success
8
(1, 23, 0, 1, 1, 0)
DataInfoX
146
(1, 496, 4)
MultipartRecord(s) for row 1
144
(ind, data)
EndMultipartRecord
145
(ind, data)
MultipartRecord(s) for row 23
144
(ind, data)
EndMultipartRecord
145
(ind, data)
EndStatement
11
(1)
EndRequest
12
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
Parcel
Flavor
Body
Success
8
(1, 24, 0, 1, 1, 0)
DataInfoX
146
(1, 496, 4)
With
33
(1)
PosStart
46
Position
34
PosEnd
47
DataInfoX
146
(1, 496, 4)
EndWith
35
(1)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
(1)
359
Chapter 9: Response Sequences
Typical Teradata Response Sequences
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
Parcel
Flavor
Body
MultipartRecord(s) for row 1
144
(ind, data)
EndMultipartRecord
145
MultipartRecord (s)for row 23
144
EndMultipartRecord
145
With
33
(1)
MultipartRecord(s)
144
(ind,data)
EndMultipartRecord
145
EndWith
35
(1)
EndStatement
11
(1)
EndRequest
12
(ind, data)
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
360
Parcel
Flavor
Body
Success
8
(1, 23, 0, 1, 1, 0)
DataInfoX
146
(1, 496, 4)
MultipartRecord(s) for row 1
144
(ind, data)
EndMultipartRecord
145
MultipartRecord(s) for row 23
144
EndMultipartRecord
145
EndStatement
11
(1)
Success
8
(2, 10, 0, 1, 1, 0)
DataInfoX
71
(2, 496, 4)
MultipartRecord(s) for row 1
144
(ind, data)
EndMultipartRecord
145
MultipartRecord(s) for row 10
144
EndMultipartRecord
145
EndStatement
11
EndRequest
12
(ind, data)
(ind, data)
(2)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
ECHO ‘SELECT FIELD1 FROM TABLE1‘;
Parcel
Flavor
Body
Success
8
(1, 0, 0, 1, 33, 0)
MultipartRecord(s)
144
(ind, data)
EndMultipartRecord
145
EndStatement
11
EndRequest
12
(1)
Issuing Requests—Indicator Mode
Indicator Mode requests may return the following parcels:
Name
Flavor
Failure
9
Error
49
Success
8
ResultSummary
171
DataInfo
71
StatementInformation
169
StatementInformationEnd
170
Record
10
With
33
EndWith
35
PosStart
46
Position
34
PosEnd
47
EndStatement
11
EndRequest
12
The following examples assume successful completion of the request when using Original
Statement-status. If using Enhanced Statement-status, OK parcels will be replaced by
ResultSummary parcels. See Chapter 15: “Parcels for Basic Applications” or Chapter 16:
“Parcels for Advanced Applications” for detailed descriptions of parcels.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
361
Chapter 9: Response Sequences
Typical Teradata Response Sequences
The following examples assume that the Return-statement-info 'Y' option was not specified; if
specified, DataInfoX parcels will be replaced by StatementInformation and
StatementInformationEnd parcels.
UPDATE TABLE1 SET FIELD1 = 999999;
Parcel
Flavor
Body
Success
8
(1, 23, 0, 0, 3, 0)
EndStatement
11
(1)
EndRequest
12
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
(continued)
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
362
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)
(1, 496, 4)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Typical Teradata Response Sequences
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
Parcel
Flavor
Body
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
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
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)
DataInfo
71
(2, 496, 4)
Record (1)
10
(ind,data)
.
.
.
.
.
.
.
.
.
Record (10)
10
(data)
EndStatement
11
(2)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
363
Chapter 9: Response Sequences
Parcels in Normal Sequences
EndRequest
12
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
Parcels in Normal Sequences
The sequence of the entire Teradata SQL response (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
Parcels That Indicate Problems
Problems encountered during 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 receives a response parcel, there is a possibility that it will be an Error or Failure
parcel, even if previous parcels were normal.
Field Layouts
Error parcels and Failure parcels have the same field layout. The distinction lies in the action
taken by the Teradata Database when the problem occurs.
364
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response Sequences
Parcels That Indicate Problems
Error Parcels
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.
Failure Parcels
A Failure parcel indicates that the active transaction at the time of the error has been rolled
back. In Teradata transaction mode, this includes any requests within the scope of the
transaction that had been completed successfully prior to the error. If a failure occurs during
the processing of a multi-statement request, all statements within the request are rolled back
as well as the transaction.
In ANSI transaction mode, a Failure response parcel 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. Statements which have not been executed will be discarded.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
365
Chapter 9: Response Sequences
Parcels That Indicate Problems
366
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 10
Error and Failure Codes
This chapter provides information pertaining to error and failure codes.
Error and Failure Codes
The application should save the current Teradata SQL request and any Teradata SQL request
for which the response is being held on the Teradata Database, in case they must be
resubmitted. If a transaction spans more than one request, all the requests should be saved, in
case the transaction must be resubmitted.
The guidelines for responding to the error and failure parcel codes are listed in Table 46:
Table 46: Error and Failure Codes
Code
Message
Action
Failure Code 2631
transaction aborted due to deadlock.
Resubmit the transaction
Failure Code 2639
sorry, too many simultaneous transactions.
Resubmit the request
Failure Code 2641
databasename.tablename was restructured.
Resubmit the transaction
Error Code 2825
no record of the last request was found after the
Teradata Database restart.
Resubmit the Teradata SQL request
Error Code 2826
request completed but all output was lost due to
the Teradata Database restart.
Whether or not the original Teradata SQL
request should be resubmitted 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
resubmitted. If the request was to multiply the
values in a column by 10 and the request is
resubmitted, the column will in effect have been
multiplied by 100, so it is not safe to resubmit 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, resubmit 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.
Resubmit the transaction
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
367
Chapter 10: Error and Failure Codes
Error and Failure Codes
Table 46: Error and Failure Codes (continued)
Code
Message
Action
Failure Code 3111
the transaction has been timed out.
Resubmit the transaction
Error Code 3115
a response parcel greater than 32767 bytes but the Specify the Maximum Parcel option to allow
CLIv2 Maximum Parcel option to allow larger
larger parcels
parcels was not specified.
an invalid value was returned by the server for the Report the server problem to the Global Support
Error parcel information field, being either 0 or
Center
not greater than the existing buffer size.
Error Code 3116
an invalid value was returned by the server for the Report the server problem to the Global Support
Error parcel information field (being either zero Center
or greater than 32767) when Maximum-parcel
was specified as O.
Error Code 3117
Maximum-parcel was specified as 'O' but the
server requires 'H', or an invalid value was
returned by the server for the data in a
MinimumResponseBuffer entry in an
ErrorInformation parcel, or that parcel was
missing or malformed.
If Maximum-parcel was specified as 'H', report
the server problem to Technical Support.
Failure Code 3120
the request is aborted because of a Teradata
Database recovery.
Resubmit the transaction
Failure Code 3598
concurrent change conflict on data base - try
again.
Resubmit the transaction
Failure Code 3603
concurrent change conflict on table - try again.
Resubmit the transaction
Failure Code 3897
request aborted due to system crash. Resubmit.
Resubmit the transaction
Note: If any other code appears, stop the program and investigate the problem.
The official list of retryable codes is in “Retryable Errors,” located in Messages.
368
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 11
Crash and Recovery
This chapter discusses the following topics:
•
TDP or Client System Crashes
•
Unusable CP
•
AP Reset Containment (APRC)
•
Teradata Database Crash and Recovery
•
What the Application Does
TDP or Client System Crashes
Teradata Database is unaware of a TDP crash. In-progress requests continue, and responses
are still available. When the TDP is restarted, it sends a cold client start, which causes Teradata
Database to log off all sessions and roll back any uncommitted work. If the 2PC protocol is
being used and there is a TDP crash, any in-doubt sessions will remain active and must be
resolved by the coordinator
Unusable CP
A Channel Processor (CP) is a communication path using the mainframe channel between
TDP and the Teradata Database. Since more than one CP is often installed, the failure of one
does not prevent communication with the Database, but it does have a dramatic impact on
requests that are using the failed CP. Unlike a Database restart in which all requests are
terminated, leaving the sessions in a known, usable state, the failure of a CP does not cleanup
current requests but since their state cannot be ascertained by TDP, TDP must logoff the
affected sessions. A return code of 544 indicates this condition. If the application is to recover
it must connect that session again, ascertain whether the requests successfully completed, and
continue processing as appropriate. However, the return code is presented immediately but it
may take an indeterminate amount of time for TDP to abort the original request and logoff
the original session, so any Database resources associated with that request and session may
not yet have been freed so may not yet be available.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
369
Chapter 11: Crash and Recovery
AP Reset Containment (APRC)
AP Reset Containment (APRC)
AP Reset Containment (APRC) is a user-transparent feature available on AP-based hardware
configurations running application programs and Teradata utilities. An AP Reset
Containment Configuration utility program, APRCConfig, provides the capability to enable
or disable APRC via the console.
Note: APRC is not applicable to SMP and MPP systems running the UNIX operating system.
How APRC Works
APRC restricts the number of Teradata Database restarts triggered by AP resets to only those
occurrences where a restart is essential. The estimated net result of enabling APRC is the
elimination of from 75 to 90 percent of restarts initiated by AP Resets. (Before APRC was
implemented, a 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 restart is not necessary.
Crash Options
The crash options formerly in use will now appear on systems with the APRC feature under
new aliases. The aliases “Tell if Delay” and “Wait During Delay” have replaced “Tell About
Crash” and “Wait Across Crash”, respectively.
When APRC is enabled, applications using multiple sessions will receive a restart/AP Reset
indication on some, none, or all sessions, depending on the APs through which the sessions
are connected.
Teradata Database Crash and Recovery
When the Teradata Database detects an internal error that prevents it from continuing, it will
store diagnostic information and reinitialize itself. This event is called a crash (or reset). After
the Teradata Database has reinitialized, it rolls back any incomplete transactions or requests
in progress. This process is called a recovery.
When an AP on an AP/1012 or 3600 system is taken down or encounters an internal error that
prevents it from continuing, it will shut down. This event is called an AP reset. Any
incomplete transactions or requests in progress for sessions connected through that AP will be
rolled back. Sessions connected through any other APs are unaffected.
When Crash or AP Reset Occurs
When an application is running and either a Teradata Database crash or AP reset occurs, the
following steps occur:
•
370
The Teradata session ids are preserved and can continue to be used.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 11: Crash and Recovery
What the Application Does
•
If a restart is detected during logoff processing, CLIv2 reconnects the session and
resubmits the logoff request.
•
Affected Teradata 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.
•
Affected requests that have not completed are aborted, and any work they have performed
is rolled back.
•
Affected spool files on the Teradata Database, including those that the Teradata Database
has kept for completed requests, are discarded.
•
Applications already waiting for a response before the event occurs will be notified. (For
when and how, see “What the Application Does” on page 371.)
•
Applications submitting a request during the crash and recovery process may be notified.
See “What the Application Does” on page 371.
•
Applications later using the abort, fetch, rewind, or end request function for a Teradata
SQL request aborted by the event, or submitting a new request in a transaction that was in
progress when the event occurred and thus was aborted in the recovery process, will be
notified. See “What the Application Does” on page 371.
What the Application Does
During recovery from a Teradata Database crash or an AP Reset, communication with the
affected sessions is essentially lost. Since this loss will delay the use of such sessions, the
applications specify what actions to take when so delayed.
The DBCAREA has two crash-related processing options: Tell if Delay and Wait During
Delay. The following sections passages the three combinations that are allowed.
Note: The setting of Wait For Response has no effect on the processing shown below.
Tell and Wait
After calling DBCHINI, set the delay options as follows:
Delay Option
Setting
Wait During Delay
Y
Tell if Delay
Y
Given this combination of options, a delay can be handled as follows:
•
The application calls DBCHCL for some function
•
The Teradata Database delay occurs before or after receiving information from DBCHCL
•
CLIv2 returns control to the application, with return code of 286
•
The application can tell its user of the possible delay and can ask user whether to wait or
disconnect, assuming wait
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
371
Chapter 11: Crash and Recovery
What the Application Does
•
The application calls DBCHCL for the fetch function
•
Communication is re-established
•
The application obtains results of the Fetch, which may be as follows:
•
•
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 takes action appropriate to the application
Note: Before submitting a request, save a copy of the request in case it must be
resubmitted. If a transaction spans several requests, save a copy of each request in the
transaction in case the transaction must be resubmitted.
Note: Tell and wait may be useful to terminal-oriented applications to distinguish
excessive response time.
Just Wait
After calling DBCHINI, set the delay options as follows.
Delay Option
Setting
Wait During Delay
Y
Tell If Delay
N
Given this combination, the steps if a delay occurs are as follows:
•
The application calls DBCHCL for some function
•
The delay occurs before or after receiving information from DBCHCL
•
The application is not notified of the delay and does not gain control
•
Communication is re-established
•
The application regains control from CLIv2 with a return code of zero
•
When the application calls DBCHCL for the Fetch function, it obtains the following:
•
•
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 takes action appropriate to the application
Note: Before submitting a request, save a copy of the request in case it must be
resubmitted. (If a transaction spans several requests, save a copy of each request in the
transaction in case the transaction must be resubmitted.)
372
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 11: Crash and Recovery
What the Application Does
Note: If Wait For Response is set to N, CLIv2 logs the session off when it encounters the
delay. CLIv2 sends the logoff request to the Teradata Database when communication is reestablished.
Tell and Logoff
After calling DBCHINI, set the delay options as follows.
Delay Option
Setting
Wait During Delay
N
Tell If Delay
Y
Given this combination of options, a delay can be handled as follows:
•
The application calls DBCHCL for some function
•
The delay occurs before or after receiving information from DBCHCL
•
CLIv2 returns control to the application, with a return code of 286
•
The application takes action appropriate to the application
Before submitting a request, save a copy of the request in case it must be resubmitted. If a
transaction spans several requests, save a copy of each request in the transaction in case the
transaction must be resubmitted.
CLIv2 logs the session off when it encounters the delay. CLIv2 sends the logoff request to the
Teradata Database when communication is re-established.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
373
Chapter 11: Crash and Recovery
What the Application Does
374
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 12
Character Set Codepoints
This chapter describes the various codepages that can be used when communicating with
Teradata Database. The character sets contained in this chapter include:
•
EBCDIC
•
EBCDIC037_0E
•
EBCDIC273_0E
•
EBCDIC277_0E
•
HANGULEBCDIC933_1II
•
KANJIEBCDIC5026_0I
•
KANJIEBCDIC5035_0I
•
KATAKANAEBCDIC
•
SCHEBCDIC935_2IJ
•
TCHEBCDIC937_3IB
Description of Codepage
Architecturally, each codepage consists of 256 possible values (codepoints) represented as
hexadecimal values in the range X'00' to X'FF'. Each character is identified by a codepoint that
is comprised of a row/column digit combination. The leftmost digit represents the row
number and the rightmost digit represents the column number. Codepoints range from '00'
(upper left corner) to 'FF' (lower right corner). For example, in the EBCDIC codpage, the
codepoint for the '!' character is 5A.
EBCDIC
The character set on the Teradata Database named EBCDIC is intended as a basic EBCDIC
character set consisting of 1-byte per character. Architecturally, the EBCDIC encoding
scheme consists of 256 possible values (codepoints) represented as hexadecimal values in the
range X'00' to X'FF'.
EBCDIC codepoint assignments are:
•
X'00' and X'3F' reserved for control characters
•
X'FF' reserved for the Eight Ones character
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
375
Chapter 12: Character Set Codepoints
EBCDIC
•
X'40' is the 'Space' character
•
X'41' through X'FE' are available to represent graphic characters
Table 47: Teradata EBCDIC Codepage
x0
x1
x2
x3
x4
x5
x6
x7
x8
x9
xA
xB
xC
xD
xE
xF
0x
NUL
SOH
STX
ETX
¤
HT
©
DEL
Ñ
Ò
Ó
VT
FF
CR
SO
SI
1x
DLE
DC1
DC2
DC3
Ô
Õ
BS
Ö
CAN
EM
Œ
Ø
IS4
IS3
IS2
IS1
2x
å
æ
Ù
ç
è
LF
ETB
ESC
é
Ð
ñ
ò
ó
ENQ
ACK
BEL
3x
ô
õ
SYN
ö
œ
É
ø
EOT
ù
â
ã
ä
DC4
NAK
à
4x
SP
¨
´
¸
×
÷
SSA
ESA
HTS
HTJ
PLD
.
<
(
+
RI
5x
&
PU1
PU2
STS
CCH
MW
SPA
EPA
SOS
UC1
!
$
*
)
;
^
6x
-
/
CSI
OSC
¢
£
ý
¥
¦
§
|
,
%
_
>
?
7x
Á
Â
Ã
Ä
Å
Æ
Ç
È
¡
`
:
#
@
'
=
"
8x
RSP
a
b
c
d
e
f
g
h
i
VTS
À
PLU
SHY
SS2
SS3
9x
DCS
j
k
l
m
n
o
p
q
r
SCI
ð
ST
½
PM
APC
Ax
š
~
s
t
u
v
w
x
y
z
ª
«
¬
[
®
¯
Bx
°
±
²
³
Ý
µ
¶
·
Š
¹
º
»
¼
]
¾
¿
Cx
{
A
B
C
D
E
F
G
H
I
Ê
Ë
Ì
Í
Î
Ï
Dx
}
J
K
L
M
N
O
P
Q
R
Ú
Û
Ü
Ÿ
þ
ß
Ex
\
á
S
T
U
V
W
X
Y
Z
ê
ë
ì
í
î
ï
Fx
0
1
2
3
4
5
6
7
8
9
ú
û
ü
ÿ
Þ
€
Control character codepoints
Reserved codepoints
The server will reject character data containing the reserved codepoint.
This is not a well-formed EBCDIC encoding because graphic characters appear in the range
reserved for control characters, non-EBCDIC control characters appear in the range reserved
for graphic characters, all common control characters are not present, and a graphic character
appears in the X'FF' codepoint reserved for the Eight Ones character.
No special processing is performed by the server for control characters. This includes the Shift
Out control character since all codepoints are single-byte. Similarly, the non-EBCDIC control
characters Single Shift Two and Single Shift Three imply nothing about subsequent
codepoints.
376
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
EBCDIC037_0E
EBCDIC037_0E
The character set on the Teradata Database named EBCDIC037_0E is intended as a basic
EBCDIC character set consisting of one byte per character. Architecturally, the EBCDIC
encoding scheme consists of 256 possible values (codepoints) represented as hexadecimal
values in the range X'00' to X'FF'.
Table 48: Teradata EBCDIC037_0E Codepage
x0
x1
x2
x3
x4
x5
x6
x7
x8
x9
xA
xB
xC
xD
xE
xF
0x
NUL
SOH
STX
ETX
ST
HT
SSA
DEL
EPA
RI
SS2
VT
FF
CR
SO
SI
1x
DLE
DC1
DC2
DC3
OSC
BS
ESA
CAN
EM
PU2
SS3
IS4
IS3
IS2
IS1
LF
ETB
ESC
HTS
HTJ
VTS
PLD
PLU
ENQ
ACK
BEL
2x
3x
DCS
PU1
SYN
STS
CCH
MW
SPA
EOT
SOS
UC1
SCI
CSI
DC4
NAK
PM
4x
SP
RSP
â
ä
à
á
ã
å
ç
ñ
¢
.
<
(
+
|
5x
&
é
ê
ë
è
í
î
ï
ì
ß
!
$
*
)
;
¬
6x
-
/
Â
Ä
À
Á
Ã
Å
Ç
Ñ
¦
,
%
_
>
?
7x
ø
É
Ê
Ë
È
Í
Î
Ï
Ì
`
:
#
@
'
=
"
8x
Ø
a
b
c
d
e
f
g
h
i
«
»
ð
ý
þ
±
9x
°
j
k
l
m
n
o
p
q
r
ª
º
æ
¸
Æ
¤
Ax
µ
~
s
t
u
v
w
x
y
z
¡
¿
Ð
Ý
Þ
®
Bx
^
£
¥
·
©
§
¶
¼
½
¾
[
]
¯
¨
´
¥
Cx
{
A
B
C
D
E
F
G
H
I
SHY
ô
ö
ò
ó
õ
Dx
}
J
K
L
M
N
O
P
Q
R
¹
û
ü
ù
ú
ÿ
Ex
\
÷
S
T
U
V
W
X
Y
Z
²
Ô
Ö
Ò
Ó
Õ
Fx
0
1
2
3
4
5
6
7
8
9
³
Û
Ü
Ù
Ú
APC
Control character codepoints
Reserved codepoints
The server will reject character data containing any reserved codepoint and will not identify
which invalid codepoint was present.
Graphic characters adhere to the standard definition for IBM code page 00037. The control
characters and Eight Ones character do not. This is true because a non-EBCDIC control
character appears in the range reserved for control characters, all common control characters
are not present, and a non-EBCDIC control character replaces the Eight Ones character.
No special processing is performed by the server for control characters. This includes the Shift
Out control character since all codepoints are single-byte. Similarly, the non-EBCDIC control
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
377
Chapter 12: Character Set Codepoints
EBCDIC273_0E
characters Single Shift Two and Single Shift Three imply nothing about subsequent
codepoints.
EBCDIC273_0E
The character set on the Teradata Database named EBCDIC273_0E is intended as a basic
EBCDIC character set consisting of one byte per character. Architecturally, the EBCDIC
encoding scheme consists of 256 possible values (codepoints) represented as hexadecimal
values in the range X'00' to X'FF'.
Table 49: Teradata EBCDIC273_0E Codepage
x0
x1
x2
x3
x4
x5
x6
x7
x8
x9
xA
xB
xC
xD
xE
xF
0x
NUL
SOH
STX
ETX
ST
HT
SSA
DEL
EPA
RI
SS2
VT
FF
CR
SO
SI
1x
DLE
DC1
DC2
DC3
OSC
BS
ESA
CAN
EM
PU2
SS3
IS4
IS3
IS2
IS1
LF
ETB
ESC
HTS
HTJ
VTS
PLD
PLU
ENQ
ACK
BEL
2x
3x
DCS
PU1
SYN
STS
CCH
MW
SPA
EOT
SOS
UC1
SCI
CSI
DC4
NAK
PM
4x
SP
RSP
â
{
à
á
ã
å
ç
ñ
Ä
.
<
(
+
!
5x
&
é
ê
ë
è
í
î
ï
ì
~
Ü
$
*
)
;
^
6x
-
/
Â
[
À
Á
Ã
Å
Ç
Ñ
ö
,
%
_
>
?
7x
ø
É
Ê
Ë
È
Í
Î
Ï
Ì
`
:
#
§
'
=
"
8x
Ø
a
b
c
d
e
f
g
h
i
«
»
ð
ý
þ
±
9x
°
j
k
l
m
n
o
p
q
r
ª
º
æ
¸
Æ
¤
Ax
µ
ß
s
t
u
v
w
x
y
z
¡
¿
Ð
Ý
Þ
®
Bx
¢
£
¥
·
©
@
¶
¼
½
¾
¬
|
¯
¨
´
¥
Cx
ä
A
B
C
D
E
F
G
H
I
SHY
ô
¦
ò
ó
õ
Dx
ü
J
K
L
M
N
O
P
Q
R
¹
û
}
ù
ú
ÿ
Ex
Ö
÷
S
T
U
V
W
X
Y
Z
²
Ô
\
Ò
Ó
Õ
Fx
0
1
2
3
4
5
6
7
8
9
³
Û
]
Ù
Ú
APC
Control character codepoints
Reserved codepoints
The server will reject character data containing any reserved codepoint and will not identify
which invalid codepoint was present.
While graphic characters adhere to the standard definition for IBM code page 0273, the
control characters and Eight Ones character do not because a non-EBCDIC control character
378
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
EBCDIC277_0E
appears in the range reserved for control characters, all common control characters are not
present, and a non-EBCDIC control character replaces the Eight Ones character.
No special processing is performed by the server for control characters. This includes the Shift
Out control character since all codepoints are single-byte. Similarly, the non-EBCDIC control
characters Single Shift Two and Single Shift Three imply nothing about subsequent
codepoints.
EBCDIC277_0E
The character set on the Teradata Database named EBCDIC277_0E is intended as a basic
EBCDIC character set consisting of one byte per character. Architecturally, the EBCDIC
encoding scheme consists of 256 possible values (codepoints) represented as hexadecimal
values in the range X'00' to X'FF'.
Table 50: Teradata EBCDIC277_0E Codepage
x0
x1
x2
x3
x4
x5
x6
x7
x8
x9
xA
xB
xC
xD
xE
xF
0x
NUL
SOH
STX
ETX
ST
HT
SSA
DEL
EPA
RI
SS2
VT
FF
CR
SO
SI
1x
DLE
DC1
DC2
DC3
OSC
BS
ESA
CAN
EM
PU2
SS3
IS4
IS3
IS2
IS1
LF
ETB
ESC
HTS
HTJ
VTS
PLD
PLU
ENQ
ACK
BEL
2x
3x
DCS
PU1
SYN
STS
CCH
MW
SPA
EOT
SOS
UC1
SCI
CSI
DC4
NAK
PM
4x
SP
RSP
â
ä
à
á
ã
}
ç
ñ
#
.
<
(
+
!
5x
&
é
ê
ë
è
í
î
ï
ì
ß
¤
Å
*
)
;
^
6x
-
/
Â
Ä
À
Á
Ã
$
Ç
Ñ
ø
,
%
_
>
?
7x
¦
É
Ê
Ë
È
Í
Î
Ï
Ì
`
:
Æ
Ø
'
=
"
8x
@
a
b
c
d
e
f
g
h
i
«
»
ð
ý
þ
±
9x
°
j
k
l
m
n
o
p
q
r
ª
º
{
¸
[
]
Ax
µ
ü
s
t
u
v
w
x
y
z
¡
¿
Ð
Ý
Þ
®
Bx
¢
£
¥
·
©
§
¶
¼
½
¾
¬
|
¯
¨
´
¥
Cx
æ
A
B
C
D
E
F
G
H
I
SHY
ô
ö
ò
ó
õ
Dx
å
J
K
L
M
N
O
P
Q
R
¹
û
~
ù
ú
ÿ
Ex
\
÷
S
T
U
V
W
X
Y
Z
²
Ô
Ö
Ò
Ó
Õ
Fx
0
1
2
3
4
5
6
7
8
9
³
Û
Ü
Ù
Ú
APC
Control character codepoints
Reserved codepoints
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
379
Chapter 12: Character Set Codepoints
HANGULEBCDIC933_1II
The server will reject character data containing any reserved codepoint and will not identify
which invalid codepoint was present.
While graphic characters adhere to the standard definition for IBM code page 0277, the
control characters and Eight Ones character do not because a non-EBCDIC control character
appears in the range reserved for control characters, all common control characters are not
present, and a non-EBCDIC control character replaces the Eight Ones character.
No special processing is performed by the server for control characters. This includes the Shift
Out control character since all codepoints are single-byte. Similarly, the non-EBCDIC control
characters Single Shift Two and Single Shift Three imply nothing about subsequent
codepoints.
HANGULEBCDIC933_1II
The character set on the Teradata Database named HANGULEBCDIC933_1II is intended as
an extended EBCDIC character set consisting of both one and two-bytes per character.
Architecturally, the EBCDIC encoding scheme consists of 256 possible values (codepoints)
represented as hexadecimal values in the range X'00' to X'FF'.
To support more than 256 codepoints, the EBCDIC encoding scheme is extended by defining
the Shift-out control character to switch from one byte per character to two bytes per
character until the Shift-in control character is encountered. The first byte of codepoints
between the Shift-out and Shift-in control characters is always between X'41' and X'FE'.
Currently, the second byte is also between X'41' and X'FE'. The X'4040' codepoint is defined
as the Double-byte Space character. No double-byte control characters exist. The double-byte
characters are not described.
Table 51: Single-byte Teradata HANGULEBCDIC933_1II Codepage
x0
x1
x2
x3
0x
NUL
SOH
STX
ETX
1x
DLE
DC1
DC2
DC3
x4
x5
HT
x7
LF
x8
x9
xA
DEL
BS
2x
3x
x6
ETB
SYN
CAN
xB
xC
xD
xE
xF
VT
FF
CR
SO
SI
IS4
IS3
IS2
IS1
ENQ
ACK
BEL
EM
ESC
EOT
DC4
NAK
SUB
4x
SP
¢
.
<
(
+
|
5x
&
!
$
*
)
;
^
6x
-
|
,
%
_
>
?
7x
[
:
#
@
'
=
"
8x
]
/
`
a
b
c
d
e
f
g
h
i
9x
j
k
l
m
n
o
p
q
r
Ax
~
s
t
u
v
w
x
y
z
380
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
HANGULEBCDIC933_1II
Table 51: Single-byte Teradata HANGULEBCDIC933_1II Codepage (continued)
Bx
^
]
Cx
{
A
B
C
D
E
F
G
H
I
Dx
}
J
K
L
M
N
O
P
Q
R
Ex
\
S
T
U
V
W
X
Y
Z
Fx
0
2
3
4
5
6
7
8
9
\
1
´
Control character codepoints
Reserved codepoints
Hangul codepoints. Refer to Table 52 on page 381 for details.
The server will reject character data containing any single or double byte reserved codepoint
and will not identify which invalid codepoint was present.
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
42
SP490000
Korean fill (NULL)
U+FFA0
Halfwidth Hangul Filler
OG000000
Hangul 'G'
U+FFA1
Halfwidth Hangul Letter kiyeok
OG100000
Hangul 'GG'
U+FFA2
Halfwidth Hangul Letter ssangkiyeok
OG20000
Hangul 'GS'
U+FFA3
Halfwidth Hangul Letter kiyeok-sios
ON00000
Hangul 'N'
U+FFA4
Halfwidth Hangul Letter nieun
ON150000
Hangul 'NJ'
U+FFA5
Halfwidth Hangul Letter nieun-cieuc
ON100000
Hangul 'NH'
U+FFA6
Halfwidth Hangul Letter nieun-hieuh
OD000000
Hangul 'D'
U+FFA7
Halfwidth Hangul Letter tikeut
43
44
45
46
47
48
49
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
381
Chapter 12: Character Set Codepoints
HANGULEBCDIC933_1II
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
52
OD100000
Hangul 'DD'
U+FFA8
Halfwidth Hangul Letter ssangtikeut
OL000000
Hangul 'L'
U+FFA9
Halfwidth Hangul Letter rieul
OL200000
Hangul 'LG'
U+FFAA
Halfwidth Hangul Letter rieul-kiyeok
OL400000
Hangul 'LM'
U+FFAB
Halfwidth Hangul Letter rieul-mieum
OL100000
Hangul 'LB'
U+FFAC
Halfwidth Hangul Letter rieul-pieup
OL600000
Hangul 'LS'
U+FFAD
Halfwidth Hangul Letter rieul-sios
OL700000
Hangul 'LT'
U+FFAE
Halfwidth Hangul Letter rieul-thieuth
OL500000
Hangul 'LP'
U+FFAF
Halfwidth Hangul Letter rieul-phieuph
OL300000
Hangul 'LH'
U+FFB0
Halfwidth Hangul Letter rieul-hieuh
OM000000
Hangul 'M'
U+FFB1
Halfwidth Hangul Letter mieum
OB000000
Hangul 'B'
U+FFB2
Halfwidth Hangul Letter pieup
OB100000
Hangul 'BB'
U+FFB3
Halfwidth Hangul Letter ssangpieup
OB2000000
Hangul 'BS'
U+FFB4
Halfwidth Hangul Letter pieup-sios
OS0000000
Hangul 'S'
U+FFB5
Halfwidth Hangul Letter sios
53
54
55
56
57
58
59
62
63
64
65
66
67
382
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
HANGULEBCDIC933_1II
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
68
OS100000
Hangul 'SS'
U+FFB6
Halfwidth Hangul Letter ssangsios
ON2000000
Hangul 'NG'/'W'
U+FFB7
Halfwidth Hangul Letter ieung
OJ000000
Hangul 'J'
U+FFB8
Halfwidth Hangul Letter cieuc
OJ100000
Hangul 'JJ'
U+FFB9
Halfwidth Hangul Letter ssangcieuc
OC200000
Hangul 'CH'
U+FFBA
Halfwidth Hangul Letter chieuch
OK000000
Hangul 'K'
U+FFBB
Halfwidth Hangul Letter khieukh
OT000000
Hangul 'T'
U+FFBC
Halfwidth Hangul Letter thieuth
OP000000
Hangul 'P'
U+FFBD
Halfwidth Hangul Letter phieuph
OH000000
Hangul 'H'
U+FFBE
Halfwidth Hangul Letter hieuh
OA000000
Hangul 'A'
U+FFC2
Halfwidth Hangul Letter 'A'
OA200000
Hangul 'AE'
U+FFC3
Halfwidth Hangul Letter 'AE'
OY200000
Hangul 'YA'
U+FFC4
Halfwidth Hangul Letter 'YA'
OY250000
Hangul 'YAE'
U+FFC5
Halfwidth Hangul Letter 'YAE'
OE200000
Hangul 'EO'
U+FFC6
Halfwidth Hangul Letter 'EO'
69
72
73
74
75
76
77
78
8A
8B
8C
8D
8E
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
383
Chapter 12: Character Set Codepoints
HANGULEBCDIC933_1II
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
8F
OE000000
Hangul 'E'
U+FFC7
Halfwidth Hangul Letter 'E'
OY400000
Hangul 'YEO'
U+FFCA
Halfwidth Hangul Letter 'YEO'
OY300000
Hangul 'YE'
U+FFCB
Halfwidth Hangul Letter 'YE'
OO000000
Hangul 'O'
U+FFCC
Halfwidth Hangul Letter 'O'
OO100000
Hangul 'OA'
U+FFCD
Halfwidth Hangul Letter 'WA'
OO200000
Hangul 'OAE'
U+FFCE
Halfwidth Hangul Letter 'WAE'
OO300000
Hangul 'OI'
U+FFCF
Halfwidth Hangul Letter 'OE'
OY500000
Hangul 'YO'
U+FFD2
Halfwidth Hangul Letter 'YO'
OU000000
Hangul 'U'
U+FFD3
Halfwidth Hangul Letter 'U'
OU300000
Hangul 'UEO'
U+FFD4
Halfwidth Hangul Letter 'WEO'
OU200000
Hangul 'UE'
U+FFD5
Halfwidth Hangul Letter 'WE'
OU400000
Hangul 'UI'
U+FFD6
Halfwidth Hangul Letter 'WI'
OY600000
Hangul 'YU'
U+FFD7
Halfwidth Hangul Letter 'YU'
OE300000
Hangul 'EU'
U+FFDA
Halfwidth Hangul Letter 'EU'
9A
9B
9C
9D
9E
9F
AA
AB
AC
AD
AE
AF
BA
384
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KANJIEBCDIC5026_0I
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
BB
OE400000
Hangul 'EUI'
U+FFDB
Halfwidth Hangul Letter 'YI'
OI000000
Hangul 'I'
U+FFDC
Halfwidth Hangul Letter 'I'
BC
Graphic characters do not correspond to a known IBM codepage (given its CCSID of 00933,
the single-byte codepage should be 00833). The control characters and Eight Ones character
are non-standard because non-EBCDIC control characters appear in the range reserved for
control characters, all common control characters are not present, and the Eight Ones
character is not supported. Codepoint X'5F' should be a Logical NOT but the server defines it
as a Circumflex accent. Codepoint X'6A' should be a Broken Vertical line but the server
defines it as a Vertical Line. Codepoint X'A0' should be an Overline but to the server it is
unsupported. Codepoint X'E0' should be Won but the server defines it as Backslash.
The server incorrectly returns a X'4F' codepoint as a X'6A' codepoint. The server incorrectly
returns a X'5F' codepoint as a X'B0' codepoint. The server incorrectly returns an X'80'
codepoint as a X'BD' codepoint. The server incorrectly returns a X'B2' codepoint as an X'E0'
codepoint.
No special processing is performed by the server for control characters, except for Shift Out
and Shift In, which switch to and from double-byte codepoints.
KANJIEBCDIC5026_0I
The character set on the Teradata Database named KANJIEBCDIC5026_0I is intended as an
extended EBCDIC character set consisting of both one and two-bytes per character.
Architecturally, the EBCDIC encoding scheme consists of 256 possible values (codepoints)
represented as hexadecimal values in the range X'00' to X'FF'.
To support more than 256 codepoints, the EBCDIC encoding scheme is extended by defining
the Shift-out control character to switch from one byte per character to two bytes per
character until the Shift-in control character is encountered. The first byte of codepoints
between the Shift-out and Shift-in control characters is always between X'41' and X'FE'.
Currently, the second byte is also between X'41' and X'FE'. The X'4040' codepoint is defined
as the Double-byte Space character. No double-byte control characters exist. The double-byte
characters are not described.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
385
Chapter 12: Character Set Codepoints
KANJIEBCDIC5026_0I
Table 53: Single-byte Teradata KANJIEBCDIC5026_0I Codepage
0x
x0
x1
x2
x3
NUL
SOH
STX
ETX
x4
x5
x6
x7
x9
xA
xB
xC
xD
xE
xF
VT
FF
CR
SO
SI
IS4
IS3
IS2
IS1
ESC
ENQ
ACK
BEL
EOT
NAK
HT
1x
BS
2x
LF
3x
x8
ETB
SYN
CAN
EM
4x
SP
£
.
<
(
+
|
5x
&
!
¥
*
)
;
¬
6x
-
/
a
b
c
d
e
f
g
h
,
%
_
>
?
7x
[
i
j
k
l
m
n
o
p
`
#
@
'
=
"
8x
]
:
q
9x
r
Ax
~
¯
Bx
^
¢
\
t
u
v
w
x
y
z
Cx
{
A
B
C
D
E
F
G
H
I
Dx
}
J
K
L
M
N
O
P
Q
R
Ex
$
S
T
U
V
W
X
Y
Z
Fx
0
2
3
4
5
6
7
8
9
1
Control character codepoints
Reserved codepoints.
Katakana codepoints. Refer to Table 54 on page 386 for details.
The server will reject character data containing any single or double byte reserved codepoint
and will not identify which invalid codepoint was present.
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
41
JQ700000
Katakana full stop
U+FF61
Halfwidth Ideographic Full Stop
JQ710000
Katakana left Bracket
U+FF62
Halfwidth Left Corner Bracket
42
386
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KANJIEBCDIC5026_0I
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
43
JQ720000
Katakana right Bracket
U+FF63
Halfwidth Right Corner Bracket
JQ730000
Katakana comma
U+FF64
Halfwidth Ideographic Comma
JQ74000
Katakana conjunctive symbol
U+FF65
Halfwidth Katakana Middle Dot
JW500000
Katakana 'WO'
U+FF66
Halfwidth Katakana Letter 'WO'
JA010000
Katakana 'a'
U+FF67
Halfwidth Katakana Letter Small 'a'
JI010000
Katakana 'i'
U+FF68
Halfwidth Katakana Letter Small 'i'
JU010000
Katakana 'u'
U+FF69
Halfwidth Katakana Letter Small 'u'
JE010000
Katakana 'e'
U+FF6A
Halfwidth Katakana Letter Small 'e'
JO010000
Katakana 'o'
U+FF6B
Halfwidth Katakana Letter Small 'o'
JY110000
Katakana 'ya'
U+FF6C
Halfwidth Katakana Letter Small 'ya'
JY310000
Katakana 'yu'
U+FF6D
Halfwidth Katakana Letter Small 'yu'
JY510000
Katakana 'yo'
U+FF6E
Halfwidth Katakana Letter Small 'yo'
JT310000
Katakana 'tu'/'tsu'
U+FF6F
Halfwidth Katakana Letter Small 'tu'
JX700000
Katakana prolonged sound symbol
U+FF70
Halfwidth Katakana-Hiragana prolonged sound symbol
44
45
46
47
48
49
51
52
53
54
55
56
58
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
387
Chapter 12: Character Set Codepoints
KANJIEBCDIC5026_0I
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
81
JA000000
Katakana 'A'
U+FF71
Halfwidth Katakana Letter 'A'
JI000000
Katakana 'I'
U+FF72
Halfwidth Katakana Letter 'I'
JU000000
Katakana 'U'
U+FF73
Halfwidth Katakana Letter 'U'
JE000000
Katakana 'E'
U+FF74
Halfwidth Katakana Letter 'E'
JO000000
Katakana 'O'
U+FF75
Halfwidth Katakana Letter 'O'
JK100000
Katakana 'KA'
U+FF76
Halfwidth Katakana Letter 'KA'
JK200000
Katakana 'KI'
U+FF77
Halfwidth Katakana Letter 'KI'
JK300000
Katakana 'KU'
U+FF78
Halfwidth Katakana Letter 'KU'
JK400000
Katakana 'KE'
U+FF79
Halfwidth Katakana Letter 'KE'
JK500000
Katakana 'KO'
U+FF7A
Halfwidth Katakana Letter 'KO'
LQ010000
'q' Small
U+0071
Latin Small Letter 'q'
JS100000
Katakana 'SA'
U+FF7B
Halfwidth Katakana Letter 'SA'
JS200000
Katakana 'SI'
U+FF7C
Halfwidth Katakana Letter 'SI'
JS300000
Katakana 'SU'
U+FF7D
Halfwidth Katakana Letter 'SU'
82
83
84
85
86
87
88
89
8A
8B
8C
8D
8E
388
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KANJIEBCDIC5026_0I
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
8F
JS400000
Katakana 'SE'
U+FF7E
Halfwidth Katakana Letter 'SE'
JS500000
Katakana 'SO'
U+FF7F
Halfwidth Katakana Letter 'SO'
JT100000
Katakana 'TA'
U+FF80
Halfwidth Katakana Letter 'TA'
JT200000
Katakana 'TI'
U+FF81
Halfwidth Katakana Letter 'TI'
JT300000
Katakana 'TU'
U+FF82
Halfwidth Katakana Letter 'TU'
JT400000
Katakana 'TE'
U+FF83
Halfwidth Katakana Letter 'TE'
JT500000
Katakana 'TO'
U+FF84
Halfwidth Katakana Letter 'TO'
JN100000
Katakana 'NA'
U+FF85
Halfwidth Katakana Letter 'NA'
JN200000
Katakana 'NI'
U+FF86
Halfwidth Katakana Letter 'NI'
JN300000
Katakana 'NU'
U+FF87
Halfwidth Katakana Letter 'NU'
JN140000
Katakana 'NE'
U+FF88
Halfwidth Katakana Letter 'NE'
JN500000
Katakana 'NO'
U+FF89
Halfwidth Katakana Letter 'NO'
JH100000
Katakana 'HA'
U+FF8AD
Halfwidth Katakana Letter 'HA'
JH200000
Katakana 'HI'
U+FF8B
Halfwidth Katakana Letter 'HI'
90
91
92
93
94
95
96
97
98
99
9A
9D
9E
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
389
Chapter 12: Character Set Codepoints
KANJIEBCDIC5026_0I
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
9F
JH300000
Katakana 'HU'/'FU'
U+FF8C
Halfwidth Katakana Letter 'HU'
LS010000
Katakana 'HE'
U+0073
Halfwidth Katakana Letter 'HE'
LT010000
Katakana 'HO'
U+0074
Halfwidth Katakana Letter 'HO'
LU010000
Katakana 'MA'
U+0075
Halfwidth Katakana Letter 'MA'
LV010000
Katakana 'MI'
U+0076
Halfwidth Katakana Letter 'MI'
LW010000
Katakana 'MU'
U+0077
Halfwidth Katakana Letter 'MU'
LX010000
Katakana 'ME'
U+0078
Halfwidth Katakana Letter 'ME'
LY010000
Katakana 'MO'
U+0079
Halfwidth Katakana Letter 'MO'
LZ010000
Katakana 'YA'
U+007A
Halfwidth Katakana Letter 'YA'
SM210000
Katakana 'YU'
U+00AA
Halfwidth Katakana Letter 'YU'
SM660000
Katakana 'YO'
U+00AC
Halfwidth Katakana Letter 'YO'
SM060000
Katakana 'RA'
U+005B
Halfwidth Katakana Letter 'RA'
SM530000
Katakana 'RI'
U+00AE
Halfwidth Katakana Letter 'RI'
SM150000
Katakana 'RU'
U+00AF
Halfwidth Katakana Letter 'RU'
A2
A3
A4
A5
A6
A7
A8
A9
AA
AC
AD
AE
AF
390
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KANJIEBCDIC5035_0I
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
BA
JR400000
Katakana 'RE'
U+FF9A
Halfwidth Katakana Letter 'RE'
JR500000
Katakana 'RO'
U+FF9B
Halfwidth Katakana Letter 'RO'
JW100000
Katakana 'WA'
U+FF9C
Halfwidth Katakana Letter 'WA'
JN000000
Katakana 'N'
U+FF9D
Halfwidth Katakana Letter 'N'
JX710000
Voiced sound symbol
U+FF9E
Halfwidth Katakana Voiced sound Mark
JX720000
Semi-voiced sound symbol
U+FF9F
Halfwidth Katakana Semi-voiced sound Mark
BB
BC
BD
BE
BF
While graphic characters adhere to the standard definition for IBM code page 00290, the
control characters and Eight Ones character do not because all common control characters
are not present, and a non-EBCDIC control character replaces the Eight Ones character.
The server defines the Overline character for KANJIEBCDIC5026_0I,
KANJIEBCDIC5035_0I, KATAKANA, and SCHEBCDIC935_2IJ differently than for the
other character sets. So if sent to the server using a character set in one group but received
from the server using a character set in the other group, the codepoint will change.
Note: The server incorrectly returns codepoint X'5F' as an X'3F' codepoint.
No special processing is performed by the server for control characters, except for Shift Out
and Shift In, which switch to and from double-byte codepoints.
KANJIEBCDIC5035_0I
The character set on the Teradata Database named KANJIEBCDIC5035_0I is intended as an
extended EBCDIC character set consisting of both one and two-bytes per character.
Architecturally, the EBCDIC encoding scheme consists of 256 possible values (codepoints)
represented as hexadecimal values in the range X'00' to X'FF'.
To support more than 256 codepoints, the EBCDIC encoding scheme is extended by defining
the Shift-out control character to switch from one byte per character to two bytes per
character until the Shift-in control character is encountered. The first byte of codepoints
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
391
Chapter 12: Character Set Codepoints
KANJIEBCDIC5035_0I
between the Shift-out and Shift-in control characters is always between X'41' and X'FE'.
Currently, the second byte is also between X'41' and X'FE'. The X'4040' codepoint is defined
as the Double-byte Space character. No double-byte control characters exist. The double-byte
characters are not described.
Table 55: Single-byte Teradata KANJIEBCDIC5035_0I Codepage
0x
x0
x1
x2
x3
NUL
SOH
STX
ETX
x4
x5
x6
x7
x9
xA
xB
xC
xD
xE
xF
VT
FF
CR
SO
SI
IS4
IS3
IS2
IS1
ESC
ENQ
ACK
BEL
EOT
NAK
HT
1x
BS
2x
LF
3x
x8
ETB
SYN
CAN
EM
4x
SP
¢
.
<
(
+
|
5x
&
!
$
*
)
;
¬
6x
-
,
%
_
>
?
#
@
'
=
"
/
7x
`
8x
a
b
c
d
e
f
g
h
i
9x
j
k
l
m
n
o
p
q
r
t
u
v
w
x
y
z
Ax
¯
~
s
Bx
^
£
¥
Cx
{
A
B
C
D
E
F
G
H
I
Dx
}
J
K
L
M
N
O
P
Q
R
Ex
\
S
T
U
V
W
X
Y
Z
Fx
0
2
3
4
5
6
7
8
9
1
:
[
]
Control character codepoints
Reserved codepoints
Katakana codepoints. Refer to Table 56 on page 393 for details.
The server will reject character data containing any single or double byte reserved codepoint
and will not identify which invalid codepoint was present.
392
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KANJIEBCDIC5035_0I
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
42
JQ700000
Katakana full stop
U+FF61
Halfwidth Ideographic Full Stop
JQ710000
Katakana left Bracket
U+FF62
Halfwidth Left Corner Bracket
JQ720000
Katakana right Bracket
U+FF63
Halfwidth Right Corner Bracket
JQ730000
Katakana comma
U+FF64
Halfwidth Ideographic Comma
JQ74000
Katakana conjunctive symbol
U+FF65
Halfwidth Katakana Middle Dot
JW500000
Katakana 'WO'
U+FF66
Halfwidth Katakana Letter 'WO'
JA010000
Katakana 'a'
U+FF67
Halfwidth Katakana Letter Small 'a'
JI010000
Katakana 'i'
U+FF68
Halfwidth Katakana Letter Small 'i'
JU010000
Katakana 'u'
U+FF69
Halfwidth Katakana Letter Small 'u'
JE010000
Katakana 'e'
U+FF6A
Halfwidth Katakana Letter Small 'e'
JO010000
Katakana 'o'
U+FF6B
Halfwidth Katakana Letter Small 'o'
JY110000
Katakana 'ya'
U+FF6C
Halfwidth Katakana Letter Small 'ya'
JY310000
Katakana 'yu'
U+FF6D
Halfwidth Katakana Letter Small 'yu'
JY510000
Katakana 'yo'
U+FF6E
Halfwidth Katakana Letter Small 'yo'
43
44
45
46
47
48
49
51
52
53
54
55
56
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
393
Chapter 12: Character Set Codepoints
KANJIEBCDIC5035_0I
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
57
JT310000
Katakana 'tu'/'tsu'
U+FF6F
Halfwidth Katakana Letter Small 'tu'
JX700000
Katakana prolonged sound symbol
U+FF70
Halfwidth Katakana-Hiragana prolonged sound mark
JA000000
Katakana 'A'
U+FF71
Halfwidth Katakana Letter 'A'
JI000000
Katakana 'I'
U+FF72
Halfwidth Katakana Letter 'I'
JU000000
Katakana 'U'
U+FF73
Halfwidth Katakana Letter 'U'
JE000000
Katakana 'E'
U+FF74
Halfwidth Katakana Letter 'E'
JO000000
Katakana 'O'
U+FF75
Halfwidth Katakana Letter 'O'
JK100000
Katakana 'KA'
U+FF76
Halfwidth Katakana Letter 'KA'
JK200000
Katakana 'KI'
U+FF77
Halfwidth Katakana Letter 'KI'
JK300000
Katakana 'KU'
U+FF78
Halfwidth Katakana Letter 'KU'
JK400000
Katakana 'KE'
U+FF79
Halfwidth Katakana Letter 'KE'
JK500000
'Katakana 'KO'
U+FF7A
Halfwidth Katakana Letter 'KO'
JS100000
Katakana 'SA'
U+FF7B
Halfwidth Katakana Letter 'SA'
JS200000
Katakana 'SI'/'SHI'
U+FF7C
Halfwidth Katakana Letter 'SI'
58
59
62
63
64
65
66
67
68
69
70
71
72
394
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KANJIEBCDIC5035_0I
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
73
JS300000
Katakana 'SU'
U+FF7D
Halfwidth Katakana Letter 'SU'
JS400000
Katakana 'SE'
U+FF7E
Halfwidth Katakana Letter 'SE'
JS500000
Katakana 'SO'
U+FF7F
Halfwidth Katakana Letter 'SO'
JT100000
Katakana 'TA'
U+FF80
Halfwidth Katakana Letter 'TA'
JT200000
Katakana 'TI'/'CHI'
U+FF81
Halfwidth Katakana Letter 'TI'
JT300000
Katakana 'TU'/'TSU'
U+FF82
Halfwidth Katakana Letter 'TU'
JT400000
Katakana 'TE'
U+FF83
Halfwidth Katakana Letter 'TE'
JT500000
Katakana 'TO'
U+FF84
Halfwidth Katakana Letter 'TO'
JN100000
Katakana 'NA'
U+FF85
Halfwidth Katakana Letter 'NA'
JN200000
Katakana 'NI'
U+FF86
Halfwidth Katakana Letter 'NI'
JN300000
Katakana 'NU'
U+FF87
Halfwidth Katakana Letter 'NU'
JN400000
Katakana 'NE'
U+FF88
Halfwidth Katakana Letter 'NE'
JN500000
Katakana 'NO'
U+FF89
Halfwidth Katakana Letter 'NO'
JH100000
Katakana 'MH'
U+FF8A
Halfwidth Katakana Letter 'MH'
74
75
76
77
78
8A
8B
8C
8D
8E
8F
9A
9B
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
395
Chapter 12: Character Set Codepoints
KANJIEBCDIC5035_0I
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
9C
JH200000
Katakana 'HI'
U+FF8B
Halfwidth Katakana Letter 'HI'
JH300000
Katakana 'HU'/'FU'
U+FF8C
Halfwidth Katakana Letter 'HU'
JH400000
Katakana 'HE'
U+FF8D
Halfwidth Katakana Letter 'HE'
JH500000
Katakana 'HO'
U+FF8E
Halfwidth Katakana Letter 'HO'
JM100000
Katakana 'MA'
U+FF8F
Halfwidth Katakana Letter 'MA'
JM200000
Katakana 'MI'
U+FF90
Halfwidth Katakana Letter 'MI'
JM300000
Katakana 'MU'
U+FF91
Halfwidth Katakana Letter 'MU'
JM400000
Katakana 'ME'
U+FF92
Halfwidth Katakana Letter 'ME'
JM500000
Katakana 'MO'
U+FF93
Halfwidth Katakana Letter 'MO'
JY100000
Katakana 'YA'
U+FF94
Halfwidth Katakana Letter 'YA'
JY300000
Katakana 'YU'
U+FF95
Halfwidth Katakana Letter 'YU'
JY500000
Katakana 'YO'
U+FF96
Halfwidth Katakana Letter 'YO'
JR100000
Katakana 'RA'
U+FF97
Halfwidth Katakana Letter 'RA'
JR200000
Katakana Letter 'RI'
U+FF98
Halfwidth Katakana Letter 'RI'
9D
9E
9F
AA
AB
AC
AE
AF
B3
B4
B5
B6
B7
396
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KATAKANAEBCDIC
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
B8
JR300000
Katakana 'RU'
U+FF99
Halfwidth Katakana Letter 'RU'
JR400000
Katakana 'RE'
U+FF9A
Halfwidth Katakana Letter 'RE'
JR500000
Katakana 'RO'
U+FF9B
Halfwidth Katakana Letter 'RO'
JW100000
Katakana 'WA'
U+FF9C
Halfwidth Katakana Letter 'WA'
JN000000
Katakana 'N'
U+FF9D
Halfwidth Katakana Letter 'N'
JX710000
Voiced sound symbol
U+FF9E
Halfwidth Katakana Voiced sound Mark
JX720000
Semi-voiced sound symbol
U+FF9F
Halfwidth Katakana Semi-voiced sound Mark
B9
BA
BB
BC
BE
BF
While graphic characters adhere to the standard definition for IBM code page 01027, the
control characters and Eight Ones character do not because all common control characters
are not present, and the Eight Ones character is not included.
The server defines the Overline character for KANJIEBCDIC5026_0I,
KANJIEBCDIC5035_0I, Katakana, and SCHEBCDIC935_2IJ differently than for the other
character sets. So if sent to the server using a character set in one group but received from the
server using a character set in the other group, the codepoint will change.
No special processing is performed by the server for control characters, except for Shift Out
and Shift In, which switch to and from double-byte codepoints.
KATAKANAEBCDIC
The character set on the Teradata Database named KATAKANAEBCDIC5026_0I is intended
as an extended EBCDIC character set consisting of both one and two-bytes per character.
Architecturally, the EBCDIC encoding scheme consists of 256 possible values (codepoints)
represented as hexadecimal values in the range X'00' to X'FF'
To support more than 256 codepoints, the EBCDIC encoding scheme is extended by defining
the Shift-out control character to switch from one byte per character to two bytes per
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
397
Chapter 12: Character Set Codepoints
KATAKANAEBCDIC
character until the Shift-in control character is encountered. The first byte of codepoints
between the Shift-out and Shift-in control characters is always between X'41' and X'FE'.
Currently, the second byte is also between X'41' and X'FE'. The X'4040' codepoint is defined
as the Double-byte Space character. No double-byte control characters exist. The double-byte
characters are not described.
Table 57: Single-byte Teradata KATAKANAEBCDIC Codepage
x0
x1
x2
x3
0x
NUL
SOH
STX
ETX
1x
¢
¬
/
x4
x5
x7
x8
HT
a
2x
LF
3x
x6
SYN
x9
xA
y
BS
b
ETB
ESC
c
CAN
xB
xC
xD
xE
xF
VT
FF
CR
SO
SI
IS4
IS3
IS2
IS1
ENQ
ACK
BEL
EM
EOT
~
NAK
4x
SP
£
.
<
(
+
|
5x
&
!
¥
*
)
;
^
6x
-
/
7x
p
q
Ax
[
¯
Bx
]
Cx
{
Dx
}
Ex
$
Fx
0
d
e
f
g
h
i
j
,
%
_
>
?
r
s
t
u
v
w
x
´
:
#
@
'
=
"
A
B
C
D
E
F
G
H
I
z
k
l
m
n
o
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
2
3
4
5
6
7
8
9
8x
9x
1
Control character codepoints
Reserved codepoints
Katakana codepoints. Refer to Table 58 on page 399 for details.
The server will reject character data containing any single or double byte reserved codepoint
and will not identify which invalid codepoint was present.
398
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KATAKANAEBCDIC
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
41
JQ700000
Katakana full stop
U+FF61
Halfwidth Ideographic Full Stop
JQ710000
Katakana left Bracket
U+FF62
Halfwidth Left Corner Bracket
JQ720000
Katakana right Bracket
U+FF63
Halfwidth Right Corner Bracket
JQ730000
Katakana comma
U+FF64
Halfwidth Ideographic Comma
JQ74000
Katakana conjunctive symbol
U+FF65
Halfwidth Katakana Middle Dot
JW500000
Katakana 'WO'
U+FF66
Halfwidth Katakana Letter 'WO'
JA010000
Katakana 'a'
U+FF67
Halfwidth Katakana Letter Small 'a'
JI010000
Katakana 'i'
U+FF68
Halfwidth Katakana Letter Small 'i'
JU010000
Katakana 'u'
U+FF69
Halfwidth Katakana Letter Small 'u'
JE010000
Katakana 'e'
U+FF6A
Halfwidth Katakana Letter Small 'e'
JO010000
Katakana 'o'
U+FF6B
Halfwidth Katakana Letter Small 'o'
JY110000
Katakana 'ya'
U+FF6C
Halfwidth Katakana Letter Small 'ya'
JY310000
Katakana 'yu'
U+FF6D
Halfwidth Katakana Letter Small 'yu'
JY510000
Katakana 'yo'
U+FF6E
Halfwidth Katakana Letter Small 'yo'
42
43
44
45
46
47
48
49
51
52
53
54
55
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
399
Chapter 12: Character Set Codepoints
KATAKANAEBCDIC
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
56
JT310000
Katakana 'tu'/'tsu'
U+FF6F
Halfwidth Katakana Letter Small 'tu'
JX700000
Katakana prolonged sound symbol
U+FF70
Halfwidth Katakana-Hiragana prolonged sound mark
JA000000
Katakana 'A'
U+FF71
Halfwidth Katakana Letter 'A'
JI000000
Katakana 'I'
U+FF72
Halfwidth Katakana Letter 'I'
JU000000
Katakana 'U'
U+FF73
Halfwidth Katakana Letter 'U'
JE000000
Katakana 'E'
U+FF74
Halfwidth Katakana Letter 'E'
JO000000
Katakana 'O'
U+FF75
Halfwidth Katakana Letter 'O'
JK100000
Katakana 'KA'
U+FF76
Halfwidth Katakana Letter 'KA'
JK200000
Katakana 'KI'
U+FF77
Halfwidth Katakana Letter 'KI'
JK300000
Katakana 'KU'
U+FF78
Halfwidth Katakana Letter 'KU'
JK400000
Katakana 'KE'
U+FF79
Halfwidth Katakana Letter 'KE'
JK500000
Katakana 'KO'
U+FF7A
Halfwidth Katakana Letter 'KO'
JS100000
Katakana 'SA'
U+FF7B
Halfwidth Katakana Letter 'SA'
JS200000
Katakana 'SI'/'SHI'
U+FF7C
Halfwidth Katakana Letter 'SI'
58
81
82
83
84
85
86
87
88
89
8A
8C
8D
400
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
KATAKANAEBCDIC
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
8E
JS300000
Katakana 'SU'
U+FF7D
Halfwidth Katakana Letter 'SU'
JS400000
Katakana 'SE'
U+FF7E
Halfwidth Katakana Letter 'SE'
JS500000
Katakana 'SO'
U+FF7F
Halfwidth Katakana Letter 'SO'
JT100000
Katakana 'TA'
U+FF80
Halfwidth Katakana Letter 'TA'
JT200000
Katakana 'TI'/'CHI'
U+FF81
Halfwidth Katakana Letter 'TI'
JT300000
Katakana 'TU'/'TSU'
U+FF82
Halfwidth Katakana Letter 'TU'
JT400000
Katakana 'TE'
U+FF83
Halfwidth Katakana Letter 'TE'
JT500000
Katakana 'TO'
U+FF84
Halfwidth Katakana Letter 'TO'
JN100000
Katakana 'NA'
U+FF85
Halfwidth Katakana Letter 'NA'
JN200000
Katakana 'NI'
U+FF86
Halfwidth Katakana Letter 'NI'
JN300000
Katakana 'NU'
U+FF87
Halfwidth Katakana Letter 'NU'
JN400000
Katakana 'NE'
U+FF88
Halfwidth Katakana Letter 'NE'
JN500000
Katakana 'NO'
U+FF89
Halfwidth Katakana Letter 'NO'
JH100000
Katakana 'HA'
U+FF8A
Halfwidth Katakana Letter 'HA'
8F
90
91
92
93
94
95
96
97
98
99
9A
9D
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
401
Chapter 12: Character Set Codepoints
KATAKANAEBCDIC
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
9E
JH200000
Katakana 'HI'
U+FF8B
Halfwidth Katakana Letter 'HI'
JH300000
Katakana 'HU'/'FU'
U+FF8C
Halfwidth Katakana Letter 'HU'
JH400000
Katakana 'HE'
U+FF8D
Halfwidth Katakana Letter 'HE'
JH500000
Katakana 'HO'
U+FF8E
Halfwidth Katakana Letter 'HO'
JM100000
Katakana 'MA'
U+FF8F
Halfwidth Katakana Letter 'MA'
JM200000
Katakana 'MI'
U+FF90
Halfwidth Katakana Letter 'MI'
JM300000
Katakana 'MU'
U+FF91
Halfwidth Katakana Letter 'MU'
JM400000
Katakana 'ME'
U+FF92
Halfwidth Katakana Letter 'ME'
JM500000
Katakana 'MO'
U+FF93
Halfwidth Katakana Letter 'MO'
JY100000
Katakana 'YA'
U+FF94
Halfwidth Katakana Letter 'YA'
JY300000
Katakana 'YU'
U+FF95
Halfwidth Katakana Letter 'YU'
JY500000
Katakana 'YO'
U+FF96
Halfwidth Katakana Letter 'YO'
JR100000
Katakana 'RA'
U+FF97
Halfwidth Katakana Letter 'RA'
JR200000
Katakana 'RI'
U+FF98
Halfwidth Katakana Letter 'RI'
9F
A2
A3
A4
A5
A6
A7
A8
A9
AA
AC
AD
AE
402
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
SCHEBCDIC935_2IJ
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)
IBM GCGID
IBM description
codepoint
Unicode code
Unicode name
AF
JR300000
Katakana 'RU'
U+FF99
Halfwidth Katakana Letter 'RU'
JR400000
Katakana 'RE'
U+FF9A
Halfwidth Katakana Letter 'RE'
JR500000
Katakana 'RO'
U+FF9B
Halfwidth Katakana Letter 'RO'
JW100000
Katakana 'WA'
U+FF9C
Halfwidth Katakana Letter 'WA'
JN000000
Katakana 'N'
U+FF9D
Halfwidth Katakana Letter 'N'
JX710000
Voiced sound symbol
U+FF9E
Halfwidth Katakana Voiced sound Mark
JX720000
Semi-voiced sound symbol
U+FF9F
Halfwidth Katakana Semi-voiced sound Mark
BA
BB
BC
BD
BE
BF
This is not a well-formed EBCDIC encoding because graphic characters appear in the range
reserved for control characters, all common control characters are not present, and the
codepoint reserved for the Eight Ones character is not included.
The server intentionally returns lower case English alphabetic characters as their upper-case
equivalents. That is, codepoints X'14', X'17', X'35', X'64' through X'6A', X'CB' through X'CF',
X'70' through X'78', X'09', and X'CA' are returned as X'C1' through X'C9', X'D1' through
X'D9', and X'E2' through X'E9', respectively.
The server defines the Overline character for KANJIEBCDIC5026_0I,
KANJIEBCDIC5035_0I, KATAKANAEBCDIC, and SCHEBCDIC935_2IJ differently than for
the other character sets. So if sent to the server using a character set in one group but received
from the server using a character set in the other group, the codepoint will change.
No special processing is performed by the server for control characters, except for Shift Out
and Shift In, which switch to and from double-byte codepoints.
SCHEBCDIC935_2IJ
The character set on the Teradata Database named SCHEBCDIC935_2IJ is intended as an
extended EBCDIC character set consisting of both one and two-bytes per character.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
403
Chapter 12: Character Set Codepoints
SCHEBCDIC935_2IJ
Architecturally, the EBCDIC encoding scheme consists of 256 possible values (codepoints)
represented as hexadecimal values in the range X'00' to X'FF'
To support more than 256 codepoints, the EBCDIC encoding scheme is extended by defining
the Shift-out control character to switch from one byte per character to two bytes per
character until the Shift-in control character is encountered. The first byte of codepoints
between the Shift-out and Shift-in control characters is always between X'41' and X'FE'.
Currently, the second byte is also between X'41' and X'FE'. The X'4040' codepoint is defined
as the Double-byte Space character. No double-byte control characters exist. The double-byte
characters are not described.
Table 59: Single-byte Teradata SCHEBCDIC935_2IJ Codepage
x0
x1
x2
x3
x4
x5
x6
x7
x8
x9
xA
xB
xC
xD
xE
xF
0x
NUL
SOH
STX
ETX
ST
HT
SSA
DEL
EPA
RI
SS2
VT
FF
CR
SO
SI
1x
DLE
DC1
DC2
DC3
OSC
NEL
BS
ESA
CAN
EM
PU2
SS3
IS4
IS3
IS2
IS1
2x
UC1
UC2
BPH
NBH
UC3
LF
ETB
ESC
HTS
HTJ
VTS
PLD
PLU
ENQ
ACK
BEL
3x
DCS
PU1
SYN
STS
CCH
MW
SPA
EOT
SOS
UC4
SCI
CSI
DC4
NAK
PM
4x
SP
£
.
<
(
+
|
5x
&
!
¥
*
)
;
¬
6x
-
¦
,
%
_
>
?
:
#
@
'
=
"
[
]
/
7x
`
8x
a
b
c
d
e
f
g
h
i
9x
j
k
l
m
n
o
p
q
r
¯
s
t
u
v
w
x
y
z
Ax
~
Bx
^
Cx
{
A
B
C
D
E
F
G
H
I
Dx
}
J
K
L
M
N
O
P
Q
R
Ex
$
S
T
U
V
W
X
Y
Z
Fx
0
2
3
4
5
6
7
8
9
\
1
APC
Control character codepoints
Reserved codepoints
The server will reject character data containing any single or double byte reserved codepoint
and will not identify which invalid codepoint was present.
While graphic characters adhere to the standard definition for IBM code page 00836, the
control characters and Eight Ones character do not because non-EBCDIC control characters
appear in the range reserved for control characters, all common control characters are not
present, and a non-EBCDIC control character replaces the Eight Ones character.
404
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set Codepoints
TCHEBCDIC937_3IB
While IBM GCGIDs differentiate the Yen (SC050000) from the Yuan (SC120000) and here
codepoint X'5B' is the Yuan, Unicode and the server do not and use U+00A5 for both.
The server defines the Overline character for KANJIEBCDIC5026_0I,
KANJIEBCDIC5035_0I, KATAKANAEBCDIC, and SCHEBCDIC935_2IJ differently than for
the other character sets. So if sent to the server using a character set in one group but received
from the server using a character set in the other group, the codepoint will change.
No special processing is performed by the server for control characters, except for Shift Out
and Shift In, which switch to and from double-byte codepoints. The non-EBCDIC control
characters Single Shift Two and Single Shift Three imply nothing about subsequent
codepoints.
TCHEBCDIC937_3IB
The character set on the Teradata Database named TCHEBCDIC937_3IB is intended as an
extended EBCDIC character set consisting of both one and two-bytes per character.
Architecturally, the EBCDIC encoding scheme consists of 256 possible values (codepoints)
represented as hexadecimal values in the range X'00' to X'FF'
To support more than 256 codepoints, the EBCDIC encoding scheme is extended by defining
the Shift-out control character to switch from one byte per character to two bytes per
character until the Shift-in control character is encountered. The first byte of codepoints
between the Shift-out and Shift-in control characters is always between X'41' and X'FE'.
Currently, the second byte is also between X'41' and X'FE'. The X'4040' codepoint is defined
as the Double-byte Space character. No double-byte control characters exist. The double-byte
characters are not described.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
405
Chapter 12: Character Set Codepoints
TCHEBCDIC937_3IB
Table 60: Single-byte Teradata TCHEBCDIC937_3IB Codepage
x0
x1
x2
x3
x4
x5
x6
x7
x8
x9
xA
xB
xC
xD
xE
xF
0x
NUL
SOH
STX
ETX
ST
HT
SSA
DEL
EPA
RI
SS2
VT
FF
CR
SO
SI
1x
DLE
DC1
DC2
DC3
OSC
NEL
BS
ESA
CAN
EM
PU2
SS3
IS4
IS3
IS2
IS1
2x
UC1
UC2
BPH
NBH
UC3
LF
ETB
ESC
HTS
HTJ
VTS
PLD
PLU
ENQ
ACK
BEL
3x
DCS
PU1
SYN
STS
CCH
MW
SPA
EOT
SOS
UC4
SCI
CSI
DC4
NAK
PM
4x
SP
¢
.
<
(
+
|
5x
&
!
$
*
)
;
¬
6x
-
¦
,
%
_
>
?
:
#
@
'
=
"
[
]
/
7x
¡
`
8x
a
b
c
d
e
f
g
h
i
9x
j
k
l
m
n
o
p
q
r
Ax
~
s
t
u
v
w
x
y
z
Bx
^
Cx
{
A
B
C
D
E
F
G
H
I
Dx
}
J
K
L
M
N
O
P
Q
R
Ex
\
S
T
U
V
W
X
Y
Z
Fx
0
2
3
4
5
6
7
8
9
1
APC
Control character codepoints
Reserved codepoints
The server will reject character data containing any single or double byte reserved codepoint
and will not identify which invalid codepoint was present.
Graphic characters do not correspond to a known IBM codepage (given its CCSID of 00937,
the single-byte codepage should be 00037). The control characters and Eight Ones character
are non-standard because non-EBCDIC control characters appear in the range reserved for
control characters, all common control characters are not present, and a non-EBCDIC
control character replaces the Eight Ones character.
No special processing is performed by the server for control characters, except for Shift Out
and Shift In, which switch to and from double-byte codepoints. The non-EBCDIC control
characters Single Shift Two and Single Shift Three imply nothing about subsequent
codepoints.
406
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 13
User-Defined Character Sets
The Teradata Database supplies several character sets whose attributes are also known to
CLIv2. The customer may define additional character sets to the server, and these are known
as user-defined character sets. The attributes of such character sets must also be defined to
CLIv2. This is done using the CLIv2 TRD2XUT utility, which accepts descriptions of one or
more user-defined character sets and creates a load module named TRD2XCI that may then
be made available to the CLIv2 runtime routines. All user-defined character sets available to
the CLIv2 runtime are defined in one TRD2XCI load module. The description of character
sets supplied by the server cannot be altered. If this is done, no error will be generated,
although the standard definition will always be used.
The utility may be run under either z/OS or VOS3. Execution as a CICS or IMS transaction is
not supported. For z/OS and VOS3, a sample JCL cataloged procedure is distributed as
TRD2XUT SAMPz/OS.
The input to the TRD2XUT utility consists of records of fixed or unspanned varying length. If
the records are fixed 80 byte records, columns 73 through 80 are reserved for traditional
sequence numbers and are ignored; otherwise, the entire record is used. Records containing
only blanks are ignored. If the first non-blank characters of a record are /*, the record is
considered a comment and ignored.
Statements may be continued onto multiple records using continuation characters. If the last
non-blank character is a minus sign, the minus sign is discarded and the statement continues
with the first column of the next record. If the last non-blank character is a plus sign, the plus
sign is discarded and the statement continues with the first non-blank column of the next
record. A statement may be continued onto any number of records. A semicolon may be
added to the end of any statement. The semicolon is discarded before the statement is
processed.
Directives
Each statement contains a directive or is associated with a directive. A directive identifies the
purpose of the statement. The following directives are supported:
Directive
Description
CHAR
Ignored by CLIv2, allowing the same file to be used by both CLIv2 and
TDP.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
407
Chapter 13: User-Defined Character Sets
Directives
Directive
Description
CHARSET
Explicitly begins a definition and identifies the encoding scheme.
END
Ends processing of records in the file.
MONOCASE
Ignored by CLIv2, allowing the same file to be used by both CLIv2 and
TDP.
SANITIZE
Ignored by CLIv2, allowing the same file to be used by both CLIv2 and
TDP.
UNICODE
Defines single-byte codepoints in the character set.
A file describes one or more character sets. Each description begins with a CHARSET directive
and ends with the next CHARSET directive, the END directive, or the last record in the file.
The CHAR, MONOCASE, SANITIZE, and UNICODE directives may appear in any order
within a description.
The following sections provide information and syntax diagrams for each directive. Refer to
Appendix A: “How to Read Syntax Diagrams,” for additional information on syntax
diagrams.
CHARSET
The CHARSET directive explicitly begins a definition and indicates the encoding scheme.
Syntax
CHARSET
CHARS
NAME
NAM
character_set_name
ENCODING
ENC
EBCDIC
E
IBMSOSI
I
ASCII
A
BIGFIVE
R
SJIS
S
UHC
EUC-CN
EUC-KR
T
EUC-JP
U
UTF8
UTF-16
2417C005
Usage
NAME identifies the character set to which the description applies. The name may include a
standard suffix that defines the encoding scheme. The standard suffix consists of an
408
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 13: User-Defined Character Sets
Directives
underscore, a number not relevant to CLIv2, the encoding character (A, E, I, R, S, T, or U),
and an optional character not relevant to CLIv2. Each suffix corresponds to an ENCODING
operand value:
•
E - EDBDIC
•
I - IBMSOSI
•
A - ASCII
•
R - BIGFIVE
•
S - SJIS
•
T - EUC-CN or EUC-KR
•
U - EUC-JP
ENCODING optionally identifies the encoding scheme for the character set. If omitted, the
character set must contain a standard suffix that indicates the encoding. If such a suffix exists,
then the encoding cannot be overridden using this operand. The following character sets are
available in CLIv2.
ENCODING
Meaning
Characteristics
EBCDIC
Extended Binary-CodedDecimal Interchange Code
• Single-byte (EBCDIC) codepoints:
X'00' through X'FF'
IBMOSI
IBM Shift-out/Shift-in
• Single-byte (EBCDIC) codepoints:
X'00' through X'FF'
• Double-byte (EBDCIC) codepoints:
Shift-out (X'0E') through Shift-in (X'0E')
ASCII
American Standard Code for
Information Interchange
• Single-byte (ASCII) codepoints:
X'00' through X'FF'
BIGFIVE
Big Five Plus
• Single-byte (ASCII) codepoints:
X'00' through X'80', and X'FF'
• Double-byte (ASCII) codepoints:
X'81' through X'FE'
EUC-CN
Extended Unix Code - China
• Single-byte (ASCII) codepoints:
X'00' through X'7F'
• Double-byte (ASCII) codepoints:
X'80' through X'FF'
EUC-JP
Extended Unix Code - Japan
• Single-byte (ASCII) codepoints:
X'00' through X'8D'
X'90' through X'FF'
• Double-byte (ASCII) codepoints:
Single-shift1 (X'8E')
• Triple-byte (ASCII) codepoints:
Single-shift2 (X'8F)'
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
409
Chapter 13: User-Defined Character Sets
Directives
ENCODING
Meaning
Characteristics
EUC-KR
Extended Unix Code - Korea
• Single-byte (ASCII) codepoints:
X'00' through X'7F'
• Double-byte (ASCII) codepoints:
X'80' through X'FF'
SJIS
Shift-JIS (Japanese Industrial
Standard)
• Single-byte (ASCII) codepoints:
X'00' through X'80'
X'A0' through X'DF'
X'FD' through X'FF'
• Double-byte (ASCII) codepoints:
X'81' through X'9F'
X'E0' through X'FC'
UHC
Unified Hangul Code
• Single-byte (ASCII) codepoints:
X'00' through X'80', and X'FF'
• Double-byte (ASCII) codepoints:
X'81' through X'FE'
UTF8
UCS (Universal Character Set)
Transformation Format 8-bit
• Single-byte (Unicode) codepoints:
X'00' through X'7F'
• Double-byte (Unicode) codepoints:
X'C0' through X'DF'
• (Most) triple-byte (Unicode) codepoints:
X'E0' through X'FE'
Most four-byte codepoints (X'F0' through X'F4')
are not supported by Teradata Database.
UTF16
UCS (Universal Character Set)
Transformation Format- 16-bit
• Single-byte (Unicode) codepoints:
X'0000' through X'D7FF'
X'E000' through X'FFFF'
Surrogates (four-byte codepoints that begin or
end with the two-byte codepoints X'D800'
through X'DBFF') are not supported by Teradata
Database.
While all codepoints are reflected to and from Teradata Database, for character sets that allow
mixtures of single and multi-byte characters, only the single-byte characters are meaningful to
CLIv2.
Example
Begin definition for IBM Code Page 833, the single-byte component for IBM CCSID 933.
CHARSET NAME KOREAN_EBCDIC933 ENCODING IBMSOSI
410
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 13: User-Defined Character Sets
Directives
END
The END directive ends processing of records in the file.
Syntax
END
2417A012
Usage
Any remaining records in the file are not read.
Example
END
UNICODE
The UNICODE directive defines all single-byte codepoints in the character set. The relevant
syntactic characters in the character set that must be defined are those that have the Unicode
codepoints of 0020 (Space), 0022 (Quotation Mark), 0027 (Apostrophe), and 002F (Slash),
and 001A (the Substitute control character). In addition, all characters that are valid in a TDP
identifier must be defined.
Syntax
UNICODE
UNI
2417A013
Usage
The actual information is contained on statements that immediately follow the UNICODE
directive. Each such statement has the following syntax:
target_codepoint1<-target_codepoint2>: data_codepoint ...
target_codepoint1 specifies the first character in the user-defined character set that is defined
on this statement, target_codepoint2 optionally specifies the last character defined on this
statement, and data_codepoint defines the equivalent character in Unicode.
A codepoint is the hexadecimal representation of a character. The number of characters
needed to specify a target codepoint is dependent on the encoding scheme for the character
set. For the characters of interest to CLIv2, the length is always two except for UTF16
encoding, for which the length is four. The length of a data codepoint is always four.
If the second target codepoint is specified, then one data codepoint is required for each
character in the range between the two target codepoints. If the second target codepoint is
omitted, then any number of data codepoints may be specified, each associated with
codepoint one greater than the previous.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
411
Chapter 13: User-Defined Character Sets
Directives
All statements after the UNICODE directive that contain a colon are associated with the
UNICODE directive. Lack of a colon indicates that the statement is a new directive and ends
that UNICODE directive.
The order of data codepoints among different statements is not significant.
The UNICODE directive may be specified only once for each character set.
If the same character is defined more than once for a character set, the last value is used.
Example
Define the Unicode equivalents for IBM Code Page 833, the single-byte component for IBM
CCSID 933.
UNICODE
40-47: 0020
48-4F: 11AD
50-57: 0026
58-5F: 11B4
60-67: 002D
68-6F: 110A
70-77: 005B
78-7F: 1112
80-87: 005D
88-8F: 0068
90-97: 001A
98-9F: 0071
A0-A7: 00AF
A8-AF: 0079
B0-B7: 005E
B8-BF: 001A
C0-C7: 007B
C8-CF: 0048
D0-D7: 007D
D8-DF: 0051
E0-E7: 20A9
E8-EF: 0059
F0-F7: 0030
F8-FF: 0038
412
001A
1103
001A
11B5
002F
110B
001A
0060
0061
0069
006A
0072
007E
007A
001A
001A
0041
0049
004A
0052
001A
005A
0031
0039
115F
00A2
1104
0021
11B6
00A6
110C
003A
0062
1161
006B
1167
0073
116D
005C
1173
0042
001A
004B
001A
0053
001A
0032
001A
1100
002E
1105
0024
1106
002C
110D
0023
0063
1162
006C
1168
0074
116E
001A
1174
0043
001A
004C
001A
0054
001A
0033
001A
1101
003C
11B0
002A
1107
0025
110E
0040
0064
1163
006D
1169
0075
116F
001A
1175
0044
001A
004D
001A
0055
001A
0034
001A
1115
0028
11B1
0029
1108
005F
110F
0027
0065
1164
006E
116A
0076
1170
001A
001A
0045
001A
004E
001A
0056
001A
0035
001A
1102
002B
11B2
003B
1121
003E
1110
003D
0066
1165
006F
116B
0077
1171
001A
001A
0046
001A
004F
001A
0057
001A
0036
001A
11AC
007C
11B3
00AC
1109
003F
1111
0022
0067
1166
0070
116C
0078
1172
001A
001A
0047
001A
0050
001A
0058
001A
0037
001A
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 14
Message Definitions
This chapter describes how to create Message Definitions in the following topics:
•
Introduction
•
Suffixes
•
Comment Formatting
•
Keywords
Introduction
The Message Definitions file for United States English is named TRD0LENU; it is provided on
a release tape. The Assembler file for TRD0LENU is on the z/OS release tape as member
CL2ASSEM. No action is required to use this file for messages in United States English. The
file is provided as the basis for creating message definitions in other languages.
Message definitions are created though the use of Assembler macros that are assembled and
link-edited (or bound) to produce a load module. Each load module contains all the CLIv2
messages for one language for a country. The distributed TRD0LENU also contains a second
item to identify the current CLIv2 release.
This information is used by the DBCHQE Request-message-release query. While not
required, this information can also be included in a customized message module during
linkage editor or binder processing by including the distributed TRD0LENU module after the
customized version (since all message table Control Sections are named TRD0L, the
distributed one will be ignored since the customized one was first, but the other Control
Section, named TRD2XRLS, does not exist in the customized version so will be included). But
if included, it must not be first in the module: TRD0L, the Control Section name for the
message table itself, must always be first, otherwise CLIv2 will abnormally terminate when
attempting to construct a message.
Suffixes
The names of all CLIv2 message modules begin with the characters TRD0L, and are suffixed
with three characters that indicate the language of the messages in that module. These
characters are the IBM national language identifiers defined in the publication IBM Standard
Packaging Rules for MVS-based Products.
The module suffixes for each defined language are as follows:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
413
Chapter 14: Message Definitions
Suffixes
Table 61: Language Module Suffixes
414
Language
Suffix
Arabic
ARA
Danish
DAN
German (Germany)
DEU
German (Switzerland)
DES
Greek
ELL
English (United States)
ENU
English (United Kingdom)
ENG
Spanish
ESP
Finnish
FIN
French (France)
FRA
French (Belgium)
FRB
French (Canada)
FRC
French (Switzerland)
FRS
Hebrew
HEB
Icelandic
ISL
Italian (Italy)
ITA
Italian (Switzerland)
ITS
Japanese
JPN
Korean
KOR
Dutch (Netherlands)
NLD
Dutch (Belgium)
NLB
Norwegian
NOR
Portuguese (Portugal)
PTG
Portuguese (Brazil)
PTB
Romansh/Grishun
RMS
Russian
RUS
Swedish
SVE
Thai
THA
Turkish
TRK
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 14: Message Definitions
Comment Formatting
Table 61: Language Module Suffixes (continued)
Language
Suffix
Chinese (China)
CHS
Chinese (Taiwan)
CHT
Comment Formatting
TRD0LENU contains the macros used to define the messages, and the comments that are
used by Teradata to produce the message documentation. The comments begin with the
characters "*." (for message definitions in other languages the lines beginning with the *.
characters serve no purpose and may be removed). The TRDXXMHD and TRDXXMSG
macros are used to define the messages. TRDXXMHD appears only once as the start of the
file, before any TRDXMGEN macros. It generates a header that describes the content of the
file. The relevant syntax is:
TRDXXMHD CLI,LANG=xx[,COUNTRY=(yy<,OPTIONAL>)]
where:
Syntax Element
Definition.
CLI
Required start of the message prefix.
xx
Two-character Language Id (in uppercase EBCDIC)
yy
Optional two-character Country Id (in uppercase EBCDIC).
OPTIONAL
Optional second COUNTRY value if the Country Id is the
default country for this language.For example, the distributed
TRD0LENU specifies LANG=EN,
COUNTRY=(US,OPTIONAL), thus indicating that the United
States is the default country for English.
An application that requests either Language Id of EN alone, or
both a Language Id of EN and a Country Id of US can use
TRD0LENU.
Keywords
To ensure portability of applications using Language Ids, the following are the recommended
LANG and COUNTRY keywords:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
415
Chapter 14: Message Definitions
Keywords
Table 62: Language and Country Keywords
416
Language
Keywords
Arabic
LANG=AR
Danish
LANG=DA,COUNTRY=(DK,OPTIONAL)
German (Germany)
LANG=DE,COUNTRY=(DE,OPTIONAL)
German (Switzerland)
LANG=DE,COUNTRY=CH
Greek
LANG=EL,COUNTRY=(GR,OPTIONAL)
English (United States)
LANG=EN,COUNTRY=(US,OPTIONAL)
English (United Kingdom)
LANG=EN,COUNTRY=GB
Spanish
LANG=ES,COUNTRY=(ES,OPTIONAL)
Finnish
LANG=FI,COUNTRY=(FI,OPTIONAL)
French (France)
LANG=FR,COUNTRY=(FR,OPTIONAL)
French (Belgium)
LANG=FR,COUNTRY=BE
French (Canada)
LANG=FR,COUNTRY=CA
French (Switzerland)
LANG=FR,COUNTRY=CH
Hebrew
LANG=IW,COUNTRY=(IL,OPTIONAL)
Icelandic
LANG=IS,COUNTRY=(IS,OPTIONAL)
Italian (Italy)
LANG=IT,COUNTRY=(IT,OPTIONAL)
Italian (Switzerland)
LANG=IT,COUNTRY=CH
Japanese
LANG=JA,COUNTRY=(JP,OPTIONAL)
Korean
LANG=KO,COUNTRY=(KR,OPTIONAL)
Dutch (Netherlands)
LANG=NL,COUNTRY=(NL,OPTIONAL)
Dutch (Belgium)
LANG=NL,BELGIUM=BE
Norwegian
LANG=NO,COUNTRY=(NO,OPTIONAL)
Portuguese (Portugal)
LANG=PT,COUNTRY=(PT,OPTIONAL)
Portuguese (Brazil)
LANG=PT,COUNTRY=BR
Romansh/Grishun
LANG=RM,COUNTRY=(CH,OPTIONAL)
Russian
LANG=RU,COUNTRY=(RU,OPTIONAL)
Swedish
LANG=SV,COUNTRY=(SE,OPTIONAL)
Thai
LANG=TH,COUNTRY=(TH,OPTIONAL)
Turkish
LANG=TR,COUNTRY=(TR,OPTIONAL)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 14: Message Definitions
Keywords
Table 62: Language and Country Keywords (continued)
Language
Keywords
Chinese (China)
LANG=ZH,COUNTRY=(CN,OPTIONAL)
Chinese (Taiwan)
LANG=ZH,COUNTRY=TW
TRDXXMSG appears once for each message; it defines the message number and message text.
The relevant syntax is:
TRDXXMSG number,'text'
where number is the numeric message number, and text is the actual message text, enclosed in
apostrophes.
For use with CICS, each message definition module must be defined in the PPT or CSD, as
appropriate. The TRD0LENU entries in the DFHPPTT4 and DFHCSDTD samples serve as a
guides for the proper specification.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
417
Chapter 14: Message Definitions
Keywords
418
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 15
Parcels for Basic Applications
This chapter describes parcels used by basic applications:
•
Parcel Definition
•
Parcel Types
•
Response Parcels: Overview
•
Parcel Descriptions
•
Individual parcels used by basic applications in alphabetical order
For information about the CLIv2 parcels used with Performance Monitor, see Performance
Management.
Parcel Definition
A parcel is a discrete logical unit of information consisting of two parts:
•
The parcel header that contains a flavor field and a parcel body length
•
The parcel body that contains any data associated with the parcel
The parcel flavors and content of the body are symbolically defined in the TRDSPB file.
Parcel headers are not of concern to basic applications. CLIv2 constructs parcel headers as
appropriate for requests and removes parcel headers for responses. For responses, the parcel
flavor is returned in the Fetch-parcel-flavor DBCAREA field.
Parcel Flavors
Each parcel type has a unique number and a unique name corresponding to it. The following
table lists the basic parcels by flavor number:
Table 63: Parcel flavors
Flavor
Parcel Name
Flavor
Parcel Name
8
Success
9
Failure
10
Record
11
EndStatement
12
EndRequest
17
OK
18
Field
19
NullField
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
419
Chapter 15: Parcels for Basic Applications
Parcel Types
Table 63: Parcel flavors (continued)
Flavor
Parcel Name
Flavor
Parcel Name
20
TitleStart
21
TitleEnd
22
FormatStart
23
FormatEnd
24
SizeStart
25
SizeEnd
26
Size
27
RecStart
28
RecEnd
33
With
34
Position
35
EndWith
46
PosStart
47
PosEnd
49
Error
71
DataInfo
86
PrepInfo
122
Flagger
125
PrepInfoX
144
MultipartRecord
145
EndMultipartRecord
146
DataInfoX
150
ElicitData
151
ElicitFile
152
ElicitDataReceived
164
ErrorInformation
169
StatementInformation
170
StatementInformationEnd
171
ResultSummary
172
ResultSet
178
ElicitName
When Parcel-mode applications fetch the results of a request, the parcel flavor is returned in
the DBCAREA DBCOPFLV field, the length of the body of the parcel in the DBFOFDL field,
and the address of the parcel body in the DBFXFDP field. Thus, such applications do not
concern themselves with the actual parcel header, only the parcel body. While the length of
the original parcel included the length of the header, the length returned in the DBCAREA
does not.
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:
420
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Types
Parcel type...
Is generated for...
Request
requests sent to the Teradata Database
Response
responses sent from the Teradata Database to a client
Request Parcels: Overview
The basic request parcels are constructed by CLIv2 on behalf of the application; therefore,
they are not normally visible to the application. Request parcels may be constructed by
applications that use a DBCAREA Request-mode of B (commonly referred to as Buffer-mode
applications) or by applications that use the DBCAREA Initiate-request extension
(DBCAIRX). For such applications, see Chapter 16: “Parcels for Advanced Applications” for
details of the various Request Parcels.
Response Parcels: Overview
Response parcels are generated by the Teradata Database in response to an application's
request. Not every parcel appears in every response.
The following table lists the response parcels by flavor, name, use, length, and the names of
fields contained in the parcel body.
Table 64: Response Parcel Flavors, Names, And Uses
Flavor
Parcel Name
Use
8
Success
Indicates that the specified Teradata SQL
statement completed successfully in other than
Field Response-mode when using Original
Statement-status.
9
Failure
Indicates that the specified statement has failed and
the entire transaction was rolled back.
10
Record
Returns one row of selected results.
(Record Mode)
10
Record
Returns one row of selected results.
(Indicator Mode)
11
EndStatement
Delimits the end of the results from the specified
Teradata SQL statement.
12
EndRequest
Delimits the end of a Teradata SQL response to a
Teradata SQL request.
17
OK
Indicates that the specified Teradata SQL
statement completed successfully (Field Mode) in
Field Response-mode when using Original
Statement-status.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
421
Chapter 15: Parcels for Basic Applications
Parcel Types
Table 64: Response Parcel Flavors, Names, And Uses (continued)
422
Flavor
Parcel Name
Use
18
Field
Contains returned information (data value, title,
format, or echo).
19
NullField
Returns a null data value for a field.
20
TitleStart
Delimits the start of a set of Title parcels.
21
TitleEnd
Delimits the end of a set of Title parcels.
22
FormatStart
Delimits the start of a set of format-containing
Field parcels.
23
FormatEnd
Delimits the end of a set of format-containing Field
parcels.
24
SizeStart
Delimits the start of a set of Size parcels.
25
SizeEnd
Delimits the end of a set of Size parcels.
26
Size
Specifies the width of a column of selected results.
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.
28
RecEnd
Delimits the end of a set of data-value-containing
Field and Null-Field parcels or a set of echoed
string-containing Field parcels.
33
With
Delimits the start of a set of parcels for the specified
WITH clause, when Return-statement-info 'Y' was
not specified.
34
Position
Specifies the column number being summarized,
when Return-statement-info 'Y' was not specified.
35
EndWith
Delimits the end of a set of parcels for the specified
WITH clause, when Return-statement-info 'Y' was
not specified.
46
PosStart
Delimits the start of a set of Position parcels, when
Return-statement-info 'Y' was not specified.
47
PosEnd
Delimits the end of a set of Position parcels, when
Return-statement-info 'Y' was not specified.
49
Error
Indicates that the specified statement has an error
not serious enough to cause rollback.
71
DataInfo
Returns a description of the following Indicator
Mode Record parcels, when Return-statement-info
'Y' was not specified.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Types
Table 64: Response Parcel Flavors, Names, And Uses (continued)
Flavor
Parcel Name
Use
86
PrepInfo
Returns column information from the Teradata
Database when a Teradata SQL statement has been
sent with a Request Processing Option of Prepare
and a Response Mode of Indicator, when
Return-statement-info 'Y' was not specified.
122
Flagger
Returns language non-conformances.
125
PrepInfoX
Returns column information from the Teradata
Database when a Teradata SQL statement has been
sent with a Request Processing Option of Prepare
and a Response Mode of MultiportIndicator, when
Return-statement-info 'Y' was not specified.
144
MultipartRecord
For MultipartIndicator mode responses, returns
one row or part of one row of selected results.
145
EndMultipartRecord
For MultipartIndicator mode responses, delimits
one row or selected results.
146
DataInfoX
For MultipartIndicator mode responses, describes
the data contained in subsequent MultipartRecord
parcels, when Return-statement-info 'Y' was not
specified.
150
ElicitData
For MultipartIndicator mode responses, elicits a
deferred MultipartIndicator response mode large
object.
151
ElicitFile
For MultipartIndicator mode responses, elicits a
User Defined Function.
152
ElicitDataReceived
For MultipartIndicator mode responses, indicates
that an elicited data or file was successfully
received.
164
ErrorInformation
After an Error parcel (flavor 49), provides
additional information about the error
169
StatementInformation
Returns a description of the data, when
Return-statement-info 'Y' was specified.
170
StatementInformationEnd
Delimits related StatementInformation parcels.
171
ResultSummary
Indicates that the specified Teradata SQL
statement completed successfully when using
Enhanced Statement-status.
172
ResultSet
Introduce parcels returned from a CALLed stored
procedure.
178
ElicitName
For MultipartIndicator mode responses, elicits a
deferred large object.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
423
Chapter 15: Parcels for Basic Applications
Common Parcel Fields
Common Parcel Fields
There are two fields that 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.
Table 65: Data Type Values
424
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
917
916
918
CLOB AS DEFERRED
420
421
920
921
922
CLOB AS LOCATOR
424
425
924
925
926
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
697
696
1197
1196
1198
DATE with DBCAREA
Date-format 'A'
748
749
1248
1249
1250
DATE with DBCAREA
Date-format 'T'
752
753
1252
1253
1254
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Common Parcel Fields
Table 65: Data Type Values (continued)
Name
Type if
non-nullable
Type if
Nullable
Type if IN
parameter
Type if INOUT
parameter
Type if OUT
parameter
BYTEINT
756
757
1256
1257
1258
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
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 INPUT parameter
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 (TIME, TIMESTAMP, TIME WITH TIME ZONE, TIMESTAMP
WITH TIME ZONE, INTERVAL YEAR, INTERVAL YEAR TO MONTH, INTERVAL
MONTH, INTERVAL DAY, INTERVAL DAY TO HOUR, INTERVAL DAY TO MINUTE,
INTERVAL DAY TO SECOND, INTERVAL HOUR, INTERVAL HOUR TO MINUTE,
INTERVAL HOUR TO SECOND, INTERVAL MINUTE, INTERVAL MINUTE TO
SECOND, INTERVAL SECOND) are given for the “StatementInformation Responses” on
page 459. 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 66: 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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
425
Chapter 15: Parcels for Basic Applications
Common Parcel Fields
Table 66: Activity Codes (continued)
426
Value
Statement
Value
Statement
Value
Statement
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
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Common Parcel Fields
Table 66: Activity Codes (continued)
Value
Statement
Value
Statement
Value
Statement
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
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
427
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Table 66: Activity Codes (continued)
Value
Statement
Value
Statement
Value
Statement
145
Replace Ordering
146
Drop Ordering
147
SQL CREATE
TRANSFORM
148
Replace Transform
149
SQL DROP
TRANSFORM
196
SQL Select for
FastExport without
Spooling
Parcel Descriptions
The following alphabetized sections describe parcels generated by basic applications and the
Teradata Database, when Return-statement-info 'Y' was not specified.
428
• DataInfo
• DataInfoX
• ElicitData
• ElicitDataReceived
• ElicitFile
• ElicitName
• EndMultipartRecord
• EndRequest
• EndStatement
• EndWith
• Error
• Failure
• Field
• Flagger
• FormatEnd
• FormatStart
• MultipartRecord
• NullField
• OK
• PosEnd
• Position
• PosStart
• PrepInfo
• PrepInfoX
• RecEnd
• Record
• Record (In Record Mode)
• Record (In Indicator Mode)
• RecStart
• ResultSet
• ResultSummary
• Size
• SizeEnd
• SizeStart
• StatementInformation Responses
• StatementInformationEnd Responses
• Success
• TitleEnd
• TitleStart
• With
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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 the 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.
•
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
DataInfo parcel corresponds to the ith data item in the Data Field of the Indicator Mode
Record parcel. See Table 65 on page 424 for the possible 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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
429
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
•
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.
430
•
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
the DataInfoX parcel corresponds to the ith data item in the Data Field of the
Multipartrecord parcel. See Table 65 on page 424 for the possible 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 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 will have a token of 1, with subsequent Large Objects tokens
each being incremented by one.
ElicitDataReceived
Purpose
For MultipartIndicator mode responses, indicates that an elicited data or file was successfully
received.
Parcel Data
Flavor
Parcel Body
Length
Parcel Body Fields
152
0
None
ElicitFile
Purpose
For MultipartIndicator mode responses, elicits a User Defined Function.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
431
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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.
ElicitName
Returned in a MultipartIndicator mode response to a request that contains a USING row
descriptor for a large object (LOB) containing AS DEFERRED BY NAME.
The following table lists field information for ElicitName.
432
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
TRDSPBEN
Flavor
Mnemonic
178
TRDSPFEN
Field
Length
Value
PBENNLEN
2-byte unsigned integer
Length, in bytes, of the name
from the USING row
descriptor AS NAME
phrase.
The maximum length of a
name may be obtained using
the DBCHQE SQL-limits
query.
PBENNAME
2-byte unsigned integer
Name from the USING row
descriptor AS NAME phrase
in characters from the
current session character set.
EndMultipartRecord
Purpose
For MultipartIndicator mode responses, delimits one row or selected results.
Usage Notes
The following table lists field information for EndMultipartRecord.
Flavor
Parcel Body
Length
Parcel Body Fields
145
0
None
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
433
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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.
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.
434
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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:
•
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.
Failure
Purpose
Indicates that the response to a request was not successfully processed by the Teradata server.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
435
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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
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.
436
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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.
Parcel Body Fields
Flavor
18
Parcel Body
Length
0 to
maximum
body size
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.
Field Notes
Data contains the value of a field in character format.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
437
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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.
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.
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.
438
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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
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).
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
439
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Parcel Body
Length
Flavor
144
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.
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:
•
440
The order of the items.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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 65 on page 424.
For the form that a null value takes for each of these data types, see “Manipulating
Nulls” in SQL Fundamentals.
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
OK
Purpose
First parcel returned in response to a successfully executed Field Mode Teradata SQL
statement when using Original Statement-status.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
441
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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 the 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
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 Table 66 on page 425 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 any 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.
PosEnd
Purpose
Delimits the end of a sequence of Position parcels that contain select-table
column-correspondence information on summary results.
442
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
443
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Parcel Data
The following information applies to the PosStart parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
46
0
none
PrepInfo
Purpose
Returns a description of the return data specified by a request, when that request is sent to the
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 the 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:
two byte unsigned integer plus the
number of bytes specified by that
integer
ColumnFormat:
ColumnTitle:
444
two byte unsigned integer plus the
number of bytes specified by that
integer
two byte unsigned integer plus the
number of bytes specified by that
integer
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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.
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. See Table 65 on
page 424 for the possible data types.
•
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, consisting of length in bytes of the name
followed by that name in characters from the current session character set. The
maximum length of a name currently may be obtained using the DBCHQE SQL-limits
query, though in the future the maximum might increase to allow character
representation information. The absolute maximum is 65535.
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, consisting of length in bytes of the
Format followed by that Format in characters from the current session character set.
The maximum length is not externally provided by the Database so the only limit
available is 65535.
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, consisting of length in bytes of the Title
followed by that Title in characters from the current session character set. The
maximum length is not externally provided by the Database so the only limit available
is 65535.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
445
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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
00 04 D5 81 94 85 00 05 E7 4D F1 F2
61 6D 65 00 02 01 F1 00 04 00 00 00
F0 5D F9 00 0B E2 E4 D4 4D C4 85 97
01 E5 0F 02 00 00 00 0A E9 E9 E9 6B
F9 F9 00 0B 53 75 6D 28 53 61 6C 61
01 01 F1 00 04 00 00 00 06 E2 E4 D4
81 99 A8 5D 00 0B E2 E4 D4 4D C4 85
5D
01
5D
06
A3
E9
72
4D
97
C0
00
60
D5
E9
79
E2
A3
00
04
4D
96
F9
29
81
D5
0C
4E
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
ColumnFormat
=
FLxx followed by CF, where xx indicates the field‘s length and CF
represents the text
ColumnTitle
=
TLxx followed by CT, where xx indicates the field‘s length and CT
represents the text
PrepInfoX
Purpose
Returns a description of the return data specified by a request, when that request is sent to the
Teradata Database with a Request Processing Option of Prepare and a Response Mode of
MultipartIndicator when Return-statement-info 'Y' was not specified.
446
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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 the Teradata Database.
Parcel Data
The following information applies to the PrepInfoX parcel.
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
Unused:
2 bytes
ColumnName:
two byte unsigned integer plus the
number of bytes specified by that
integer
ColumnFormat:
ColumnTitle:
two byte unsigned integer plus the
number of bytes specified by that
integer
two byte unsigned integer plus the
number of bytes specified by that
integer
For non-decimal columns, the following occur:
DataType:
2 byte unsigned integer
DataLen:
8 bytes
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
447
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
•
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.
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. See Table 65 on
page 424 for the possible data types.
•
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 67: PrepInfoX Data Types
448
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 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, consisting of length in bytes of the name
followed by that name in characters from the current session character set. The
maximum length of a name currently may be obtained using the DBCHQE SQL-limits
query, though in the future the maximum might increase to allow character
representation information. The absolute maximum is 65535.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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, consisting of length in bytes of the
Format followed by that Format in characters from the current session character set.
The maximum length is not externally provided by the Database so the only limit
available is 65535.
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, consisting of length in bytes of the Title
followed by that Title in characters from the current session character set. The
maximum length is not externally provided by the Database so the only limit available
is 65535.
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
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
449
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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
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.
450
In this mode...
Nulls are...
Record
not explicitly identified in the Record parcel.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
In this mode...
Nulls are...
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.
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).
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
451
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Parcel Body
Length
Flavor
10
Parcel Body Fields
2 to
maximum
body size
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.
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:
•
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:
•
452
If the data item is to contain...
The order of the items.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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.
For data types, see Table 65 on page 424.
For the form that a null value takes for each of these data types, see “Manipulating
Nulls” in SQL Fundamentals
Record (In Record Mode)
Purpose
In Record Mode, nulls are not explicitly identified in the Record parcel, when
Return-statement-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 the 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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
453
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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.
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. See Table 65 on page 424.
For the form that a null value takes in each of these data types, see “Manipulating Nulls” in
SQL Fundamentals.
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.
454
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Parcel Data
The following information applies to the RecStart parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
27
0
none
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
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.
455
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
TRDSPBRT
Flavor
Mnemonic
Field
Length
Value
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
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 the Teradata Database.
Parcel Data
The following information applies to the ResultSummary parcel.
Table 68: ResultSummary Parcel Information
Flavor
171
456
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 425 for the possible
activity types
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Table 68: 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
Warning-number.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
457
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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.
Flavor
Parcel Body
Length
Parcel Body Fields
26
2
MaxFldSize: 2 byte unsigned integer
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 Teradata Database.
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.
458
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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
StatementInformation Responses
Purpose
Returned in response to a successfully executed Teradata SQL statement when
Return-statement-info 'Y' is 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 the 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.
Each extension begins with the following fields:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
459
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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
5 Untransformed limited-layout used only in requests, for details
refer to Table 70 on page 465.
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 integers:
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.
8 - Data-attributes. Used only in requests. For details see
“StatementInformation Requests” on page 490.
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 for Responses
The Full-layout is used for Parameter, Query, Summary, Identity-column,
Stored-procedure-output, and Stored-procedure-resultSet information, when DBCAREA
460
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
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 69 describes the Full-layout fields specific to responses.
Table 69: Full-layout Fields for Responses
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. The maximum length is not
externally provided by the Database so the only limit available is
65535.
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. The
maximum length is not externally provided by the Database so
the only limit available is 65535.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
461
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Table 69: Full-layout Fields for Responses (continued)
462
Field
Length
Description
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.
PBTIFIC
1 byte character
Set to an EBCDIC 'Y' if the column is an Identity Column; 'N'
otherwise. If an Identity column is not involved or the
information is not available, an EBCDIC 'U' is set.
PBTIFDW
1 byte character
Set to an EBCDIC '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 EBCDIC '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
EBCDIC 'U' is set.
PBTIFMN
1 byte character
Set to an EBCDIC '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, an EBCDIC 'U' is set.
PBTIFSR
1 byte character
Set to an EBCDIC '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 EBCDIC 'U' is set.
PBTIFWR
1 byte character
Set to an EBCDIC '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 65 on page 424
for the possible data types. See Table 70 on page 465 for
additional data types that are also supported.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Table 69: Full-layout Fields for Responses (continued)
Field
Length
Description
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.
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 EBCDIC '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 EBCDIC 'U' is set.
PBTIFSN
1 byte unsigned
character
Set to an EBCDIC '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 EBCDIC 'U' is set.
PBTIFK
1 byte unsigned
character
Set to an EBCDIC '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
EBCDIC 'U' is set.
PBTIFU
1 byte unsigned
character
Set to an EBCDIC '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
EBCDIC 'U' is set.
PBTIFE
1 byte unsigned
character
Set to an EBCDIC '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 EBCDIC 'U' is set.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
463
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Table 69: Full-layout Fields for Responses (continued)
Field
Length
Description
PBTIFSO
1 byte unsigned
character
Set to an EBCDIC '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
EBCDIC '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.
When at least one more byte is present, the first such byte is defined as follows:
Field
Length
Description
PBTIFTP
1-byte character
Set to one of the following EBCDIC characters:
• 'I' if the item is a stored-procedure IN parameter
• 'O' if the item is a stored-procedure OUT parameter
• 'B' if the item is a stored-procedure INOUT parameter
If the item is not a stored-procedure parameter or the
information is not available, an EBCDIC 'U' set.
PBTIFDOS
2 bytes
When Transforms are off for this type of item, the depth of this
attribute of the item's structure. A value of zero indicates the
item is not a structure or Transforms are not off. Other values
indicate the nesting level of the structure
PBTIFTC
1-byte character
Set to one of the following EBCDIC characters:
•
•
•
•
464
'N' if the item is non-temporal
'V' if the item is ValidTime
'T' if the item is a TranactionTime
'U' if the information is unavailable
PBTIFUA
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
When Transforms are off for this type of item, Untransformed
Attribute Name consists of the length in bytes of the name of
this attribute in the item's structure, followed by that name in
characters from the current session character set. If the item is
not a structure or Transforms are not off, the length is zero and
no name is present. The maximum length of a name may be
obtained using the DBCHQE SQL-limits query.
PBTIFTDT
2 byte unsigned
integer
When Transforms are off for this type of item, specifies the data
type of the untransformed item. If the item is not a structure or
Transforms are not off, the value is zero. In addition to the data
types available for the PrepInfo[X] (flavor 86 or 125) and
DataInfo[X] (flavor 71 or 146) parcels, which are defined in
"DataType" Table 65 on page 424. Table 65 shows additional
types that are supported.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Table 70: 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
Note: These data types may not be used in DataInfo[X] (flavor 71 or 146) request parcels.
Limited-layout for Responses
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 71
describes the Limited-layout fields specific to responses.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
465
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Table 71: Limited-layout Fields for Responses
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 65 on page 424 for the possible data types.
See Table 70 on page 465 for additional data types that are also
supported.
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. Table 8 shows the
Statistic-layout fields.
Table 72: 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 Responses
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) to indicate that no more StatementInformation parcels
(flavor 169) exist.
466
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Usage Notes
This parcel is generated by the 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 the 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 Channel-Attached Systems
467
Chapter 15: Parcels for Basic Applications
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. See Table 66 on page 425 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 the 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.
468
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
Flavor
Parcel Body
Length
Parcel Body Fields
20
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 Channel-Attached Systems
469
Chapter 15: Parcels for Basic Applications
Parcel Descriptions
470
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 16
Parcels for Advanced Applications
This chapter describes parcels that may be used by applications that specify either a
DBCAREA Request-mode of B (commonly referred to as Buffer-mode applications) or a
DBCAREA Initiate-request extension (DBCAIRX) to add request parcels to those constructed
by CLIv2.
Parcel Structure
A parcel is a discrete physical unit of information transferred between CLIv2 or advanced
applications and the Teradata Database. It consists of two parts: the header and the body,
which may be null.
Header
Body
2417A009
Parcel Header
Flag
There are two formats of parcel headers. The parcel headers are symbolically defined in the
TC2XPH file. The format of the first is:
0
Flavor
Length
2
4
2417A010
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
471
Chapter 16: Parcels for Advanced Applications
Parcel Header
Table 73: Original Parcel Header (TPH0)
Field Name
Offset
Length
Description
PH0FLAVR
(FLAVOR-FLAG
for COBOL
'flavor' for C,
and PL/I)
00
1 bit
A binary zero, indicating this header format. The
mnemonic for the bit is PH0FALT
('Tc2ph_Alternate' for C, TPH0_ALTERNATE for PL/I)
PH0FLAVR
('flavor' for
COBOL, C,
and PL/I)
0.1
15 bits
An unsigned integer identifying the type of parcel body.
PH0LEN
('length' for C
and PL/I)
02
2 bytes
An unsigned integer specifying the length of the parcel, in
bytes, including the parcel header and any body.
Flag
The format of the second is:
Unused
Flavor
0
2
Length
4
8
2417A011
Table 74: Alternate Parcel Header (TPH1)
Field Name
Offset
Length
Description
PH1FLAVR
(FLAVOR-FLAG
for COBOL
'flavor' for C and
PL/I)
00
1 bit
A binary zero, indicating this header format. The
mnemonic for the bit is PH1FALT
('Tc2ph_Alternate' for C, TPH1_ALTERNATE for PL/I)
PH1FLAVR
('flavor' for
COBOL, C, and
PL/I)
0.1
15 bits
An unsigned integer identifying the type of parcel body.
PH1FILL1
('fill1' for
COBOL, C, and
PL/I)
02
2 bytes
Not used: Set to binary zeroes.
PH1LEN
('length' for C
and PL/I)
04
4 bytes
An unsigned integer specifying the length of the parcel, in
bytes, including the parcel header and any body.
A response will only contain a parcel with the enlarged header if the APH-response-permitted
option was specified and the Teradata Database supports the alternate header for that parcel.
472
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Flavors
Furthermore, parcels whose length is less than or equal to 65535 may use either header
format.
Parcel Flavors
The following table provides the flavor number and name of the parcels used by advanced
applications. The parcel flavors and content of the body are symbolically defined in the
TRDSPB file.
Table 75: Parcel Flavors
Flavor
Parcel Name
Flavor
Parcel Name
1
Req
3
Data
13
FMReq
68
IndicData
69
IndicReq
71
DataInfo
85
Options
120
CursorHost
121
CursorDBC
128
Multi-TSR
129
SP Options
140
MultipartData
141
EndMultipartData
142
MultipartIndicData
143
EndMultipartIndicData
146
DataInfoX
148
MultipartRequest
169
StatementInformation
170
StatementInformationEnd
188
CREATE CONSTRAINT
189
ALTER CONSTRAINT
190
DROP CONSTRAINT
Parcel Types
There are two parcel types:
Parcel type...
Is generated for...
Request
requests sent to the Teradata Database
Response
responses sent from the Teradata Database to a client
The following two sections describe request and response parcels.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
473
Chapter 16: Parcels for Advanced Applications
Parcel Types
Request Parcels: Overview
Request parcels are normally application's request. An application may generate all or some
request parcels itself. All parcels may be generated by specifying a DBCAREA Request-mode
of B (commonly referred to as Buffer-mode applications). Parcels may be added to those
generated by CLIv2 by using a DBCAREA Initiate-request extension (DBCAIRX).
Table 76 lists the request parcels by flavor, name, and use.
Table 76: Request Parcel Flavors, Names, And Uses
Flavor
Parcel Name
Use
1
Req
Initiates a request (Record Mode)
3
Data
Contains data for a Teradata SQL request (Record
Mode)
13
FMReq
Initiates a request (Field Mode)
68
IndicData
Contains data for a Teradata SQL request (Indicator
Mode)
69
IndicReq
Initiates a request (Indicator Mode)
71
DataInfo
Sends description of whichever data parcel follows it
85
Options
Provides options for a request.
120
CursorHost
Provides cursor information.
128
Multi-TSR
Segments special-purpose requests into multiple parcels.
129
SP Options
Provides options for creation of a Stored Procedure.
146
DataInfoX
For MultipartIndicator mode responses, describes the
data contained in subsequent MultipartRecord parcels.
169
StatementInformation
Describes the data items contained in the request when
those attributes are not otherwise known.
170
StatementInformationEnd
Delimits StatementInformation parcels in the request.
Response Parcels: Overview
Response parcels are generated by the Teradata Database in response to an application's
request. Not every parcel appears in every response.
Table 77 lists the response parcels by flavor, name, and use.
Table 77: Response Parcel Flavors, Names, And Uses
474
Flavor
Parcel Name
Use
121
CursorDBC
Returns cursor information
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Table 77: Response Parcel Flavors, Names, And Uses (continued)
Flavor
Parcel Name
Use
140
MultipartData
Contains data for a Teradata SQL request in
MultipartIndicator response mode when Use-presence
was not requested
141
EndMultipartData
Delimits data for a Teradata SQL request in
MultipartIndicator response mode when Use-presence
was not requested
142
MultipartIndicData
Contains data for a Teradata SQL request in
MultipartIndicator response mode when Use-presence
was requested
143
EndMultipartIndicData
Delimits data for a Teradata SQL request in
MultipartIndicator response mode when Use-presence
was requested
148
MultipartRequest
Initiates a request in MultipartIndicator response
mode
Parcel Descriptions
The following alphabetized sections describe parcels generated by advanced applications and
the Teradata Database.
• CursorDBC
• CursorHost
• Data
• DataInfo
• DataInfoX
• EndMultipartData
• EndMultipartIndicData
• FMReq
• IndicData
• IndicReq
• MultipartData
• MultipartIndicData
• MultipartRequest
• Options
• Req
• SP Options
• StatementInformation Requests
• StatementInformationEnd Returns
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
475
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
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.
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.
476
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
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.
•
The values of the items are represented in a client internal format for details. See Table 65
on page 424.
•
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 the Teradata Database.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
477
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Parcel Data
Parcel Body
Length
Flavor
71
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.
•
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
DataInfo parcel corresponds to the ith data item in the Data Field of the Indicator Mode
Record parcel. See Table 65 on page 424 for the possible 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.
478
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Usage Notes
DataInfoX is not returned if the statement was ECHO.
Parcel Data
The following table lists field information for DataInfoX.
Parcel Body
Length
Flavor
146
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 DataInfoX parcel.
•
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. See Table 65 on page 4241 for the possible 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 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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
479
Chapter 16: Parcels for Advanced Applications
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
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.
480
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Parcel Body
Length
Flavor
13
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.
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
481
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
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. See Table 65 on page 424.
A null value is explicitly indicated by a null indicator bit, as explained above.
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.
482
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Parcel Data
The following information applies to the IndicReq parcel.
Parcel Body
Length
Flavor
69
Parcel Body Fields
1 to maximum
body size
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.
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
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
483
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
•
The values of the items are represented in a client internal format. See Table 65 on
page 424.
•
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:
•
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. See Table 65 on
page 424.
•
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.
MultipartRequest
Purpose
Initiates a request consisting of one or more SQL statements and indicates that the results are
to be returned in MultipartIndicator mode.
484
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
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.
Options
Specifies which statement options are used when a request is sent to the 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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
485
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Flavor
Parcel Body
Length
Parcel Body Fields
85
10 or 11
RequestMode: 1 byte
Function: 1 byte
Select-data: 1 byte
Continued-characters-state: 1 byte
APH-response: 1 byte
Return-statement-info: 1 byte
TransformsOff: 1 byte
Maximum DECIMAL precision: 1 byte
(ignored if Field Response-mode)
IdentityColumnRetrieval: 1 byte
DynamicResultSets: 1 byte
If present, SP-ReturnResult: 1 byte
If present, PeriodAsStructs: 1 byte
If present, Extended-name Response: 1 byte
If present, Trusted-request 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, the 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:
486
•
E- specifies that the request should be executed.
•
A binary zero in this field is interpreted as an E.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
•
•
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 EBCDIC 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.
•
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:
•
•
•
•
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.
TransformsOff indicates whether SQL Structured User Defined Types (UDTs) are
transformed into their external data type or left as their constituent attributes. The
supported values are:
•
'N', the default, if Structured UDTs are transformed into their external type.
•
'Y' if Structured UDTs are not transformed.
When built by CLIv2, the value used is based on the DBCAREA Transforms-off option.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
487
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
•
•
•
•
•
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.
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.
Extended-name Response 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. The supported
values are:
•
0, the default, indicates varying-length column name, title, and format information in
existing response parcels cannot be longer than the existing maximum.
•
1 indicates varying-length column name, title, and format information in existing
response parcels can be longer than the existing maximum.
When built by CLIv2, the value used is based on the DBCAREA Column-info option.
•
PeriodsAsStructs indicates whether Period data types are treated as Structured UDTs and
supply or return information about the constituent attributes. The supported values are:
•
'N', the default, if Period data types are not transformed.
•
'Y' if Period data types are not transformed.
When built by CLIv2, the value used is based on the DBCAREA Period-as-Struct option.
•
Trusted-request indicates whether the request is trusted to use the Teradata SQL SET
QUERY_BAND='PROXYUSER=...' statement to change the session userid. The
supported values are:
•
488
'N', the default, indicates the request may not change the session userid.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
•
'Y' indicates the request may change the session userid.
When built by CLIv2, the value used is based on the DBCAREA Trusted-request option.
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.
SP Options
Purpose
Provides options to be used when compiling the stored procedure.
Usage Notes
This parcel is provided by the application for the first or only segmented data request in the
Initiate Request DBCAREA extension.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
489
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
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 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 Requests
Purpose
Describes the data items contained in the request when those attributes are not otherwise
known. If more data needs be returned than will fit into a single StatementInformation parcel,
multiple parcels may be provided.
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.
Each extension begins with the following fields:
490
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
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. Used only in responses. For details, see
“StatementInformation Responses” on page 459.
4 End-information
5 Untransformed limited-layout
PBTIID
2-byte
unsigned
integer
Information Id identifies the type of extension. Used only in
responses.
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).
2 Query
3 Summary
4 Identity-column
5 Stored-procedure-Output
6 Stored-procedure-resultSet
7 Estimated-processing
8 Data-attributes - Describes the data items contained in the
request when those attributes are not otherwise known.
For more information, see “StatementInformation Responses” on
page 459.
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).
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
491
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Full-layout for Requests
The Full-layout is used for Data-attributes, when DBCAREA Request-processing-option is 'P'
(Prepare) or 'B' (Prepare and Execute) (corresponding to the Options parcel [flavor 85]
Function 'P', and 'B' options). Table 78 shows the Full-layout fields. Full-layout field not listed
in this table are used only in responses. For details, see “StatementInformation Responses” on
page 459.
Table 78: Full-layout Fields for Requests
Field
Length
Description
PBTIFDT
2-byte unsigned
integer
Specifies the data type of the item. 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 65 on page 424 for the
possible data types. See Table 70 on page 465 for additional data
types that are also supported.
PBTIFMDL
8-byte unsigned
integer
The total number of bytes of data that might be sent for this
item.
PBTIFND
2-byte unsigned
integer
The total number of digits if the item has a decimal or numeric
data type.
PBTIFNID
2-byte unsigned
integer
The number of interval digits if the item is a temporal data type.
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).
Note: While only five fields are honored, all full-layout fileds must be present. (See Table 69 on
page 461.) Fields with a two-byte length followed by text also of that length must be valid. That is,
the length must correspond to the number of bytes of text.
When at least one more byte is present, the first such byte is defined as follows:
Field
Length
Description
PBTIFTP
1-byte character
Set to one of the following EBCDIC characters:
• 'I' if the item is a stored-procedure IN parameter
• 'O' if the item is a stored-procedure OUT parameter
• B' if the item is a stored-procedure INOUT parameter
• 'U' if the item is not a stored-procedure parameter, or if the
information is unavailable
492
PBTILDOS
2 bytes
When Transforms are off for this type of item, the depth of this
attribute of the item's structure. A value of zero indicates the
item is not a structure or Transforms are not off. Other values
indicate the nesting level of the structure.
PBTIFTC
1-byte character
Used only in responses. See “StatementInformation Responses”
on page 459.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Field
Length
Description
PBTILUA
2 byte unsigned
integer plus the
number of bytes
specified by that
integer
When Transforms are off for this type of item, Untransformed
Attribute Name consists of the length in bytes of the name of
this attribute in the item's structure, followed by that name in
characters from the current session character set. If the item is
not a structure or Transforms are not off, the length is zero and
no name is present. The maximum length of a name may be
obtained using the DBCHQE SQL-limits query.
PBTILTDT
2 byte unsigned
integer
When Transforms are off for this type of item, specifies the data
type of the untransformed item. If the item is not a structure or
Transforms are not off, the value is zero. In addition to the data
types available for the PrepInfo[X] (flavor 86 or 125) and
DataInfo[X] (flavor 71 or 146) parcels, which are defined in
“Data Type” on page 424. Table 65 on page 424 conatins a list of
the possible data types. See Table 70 on page 465 for additional
data types that are also supported.
Limited-layout for Requests
The Limited-layout is used for Data-attributes when DBCAREA Request-processing-option is
'E' (Execute) (corresponding to the Options parcel (flavor 85) Function 'E' option). Table 79
describes the Limited-layout fields specific for requests.
Table 79: Limited-layout Fields for Requests
Field
Length
Description
PBTILDT
2 byte unsigned
integer
Specifies the data type of the item. In addition to the data types
available for the PrepInfo[X] (flavor 86 or 125) and DataInfo[X]
(flavor 71 or 146) parcels, which are defined in “Data Type” on
page 424. Table 65 on page 424 conatins a list of the possible data
types. See Table 70 on page 465 for additional data types that are
also supported.
PBTILMDL
8 byte unsigned
integer
The total number of bytes of data that might be sent for this item.
PBTILND
2 byte unsigned
integer
The total number of digits if the item has a decimal or numeric
data type.
PBTILNID
2 byte unsigned
integer
The number of interval digits if the item is a temporal data type.
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).
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
493
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
Untransformed limited-layout
The Untransformed limited-layout is used for Data-attributes when DBCAREA
Request-processing-option is 'E' (Execute) (corresponding to the Options parcel (flavor 85)
Function 'E' option). Table 79 describes the Untransformed limited-layoutt fields specific for
requests.
Table 80: Untransformed limited-layout Fields for Requests
Field
Length
Description
PBTIUDT
2 byte unsigned
integer
Specifies the data type of the item. In addition to the data types
available for the PrepInfo[X] (flavor 86 or 125) and DataInfo[X]
(flavor 71 or 146) parcels, which are defined in “Data Type” on
page 424. Table 65 on page 424 conatins a list of the possible data
types. See Table 70 on page 465 for additional data types that are
also supported.
PBTIUMDL
8 byte unsigned
integer
The total number of bytes of data that might be sent for this item.
PBTIUND
2 byte unsigned
integer
The total number of digits if the item has a decimal or numeric
data type.
PBTIUNID
2 byte unsigned
integer
The number of interval digits if the item is a temporal data type.
PBTIUNFD
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).
When at least one more byte is present, the first such additional is defined as follows:
Table 81: Untransformed imited-layout Fields for Requests
Field
Length
Description
PBTIUTDT
2 byte unsigned
integer
When Transforms are off for this type of item, specifies the data
type of the untransformed item. If the item is not a structure or
Transforms are not off, the value is zero. In addition to the data
types available for the PrepInfo[X] (flavor 86 or 125) and
DataInfo[X] (flavor 71 or 146) parcels, which are defined in
“Data Type” on page 424. See Table 70 on page 465 for additional
data types that are also supported.
End-information layout
The End-information layout indicates there are no more items for the current information
(Data-attibutes). No data exists for End-information.
494
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
StatementInformationEnd Returns
Purpose
Indicates that no more StatementInformation parcels (flavor 169) exist.
Parcel Data
The following information applies to the StatementInformationEnd parcel.
Flavor
Parcel Body
Length
Parcel Body Fields
170
0
none
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
495
Chapter 16: Parcels for Advanced Applications
Parcel Descriptions
496
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 17
Stored Procedures
This chapter describes:
•
Introduction
•
SQL Stored Procedures
•
External Stored Procedures
•
Dynamic Result Sets
Refer to SQL Stored Procedures and Embedded SQL for additional information on stored
procedures.
Introduction
You can store executable procedures in the Teradata Database and invoke them later using the
SQL CALL statement. There are two types of stored procedures:
•
SQL, consisting of statements written in the SQL Stored Procedure Language (SPL).
•
External, consisting of statements written in a standard programming language such as C,
C++, or Java, and able to call CLIv2.
SQL Stored Procedures
The application sends the statements composing a procedure to the database, where they are
compiled and saved for subsequent execution. The application that creates the procedure
must do the following:
1
Ascertain whether the Teradata Database supports stored procedures.
2
Send a request containing the procedure that could exceed the maximum parcel size.
3
Provide compilation options to the database.
To ascertain if the Teradata Database supports stored procedures, the CLIv2 Query service is
used to obtain the Maximum-Segment-Size. Based on the results returned by the Query
service, one of the following actions occurs:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
497
Chapter 17: Stored Procedures
SQL Stored Procedures
If...
Then...
stored procedures are
not supported
the service will fail (return code 351).
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.
Send Procedure to Database
A stored procedure is sent to Teradata Database in one or more segments using either the
Initiate Request, or the Initiate With Protocol Function CLIv2 function.
The 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.
When sending segments of a stored procedure, the maximum value for Request-length may
vary slightly with the version of the Teradata Database being used; the value may be obtained
using the DBCHQE CLIv2-limits query (or deprecated Maximum-segment-size query).
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
database.
Error
any previous segments have been retained by the
database, 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.
498
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 17: Stored Procedures
SQL Stored Procedures
If this response parcel is returned...
Then...
Success (if Record, Indicator, or
MultipartIndicator Response-mode)
or OK (if Field Response-mode) when
using Original Statement-status; or
ResultSummary when using Enhanced
Statement-status.
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, OK, or ResultSummary 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, OK, or ResultSummary parcel Activity Count field indicates the
number of messages.
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 and Indicator modes, each message is in a separate Data parcel.
Abort, Cancel, and Restart Processing
Any time a segment request is active, the CLIv2 Abort function may be used to abort
processing. Any time 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 database 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 these other 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)
•
the 2PC option must be 'N' (no two-phase commit)
•
if the Initiate with Protocol Function function is used, the Initiate Protocol-function
option must be 'N' (because two-phase commit is not supported).
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 Channel-Attached Systems
499
Chapter 17: Stored Procedures
External Stored Procedures
To provide compilation options, an Initiate-Request extension to the DBCAREA must be
used to provide a Stored Procedure Options request parcel (flavor 129). This parcel must be
provided with the first segment.
For example, the following Assembler instructions (which assume use of the DBCAIRX
macro) initialize an extension providing a Stored Procedure Options request parcel that
would be addressed by the DBCAXP field in the DBCAREA when the first segment is sent:
MVC
XC
MVC
MVI
MVC
MVC
MVI
MVI
D8XIID(4),=A(D8XIIIRX) Set Eyecatcher
D8XINEXT(4),D8XINEXT
No more extensions
D8XISIZE(4),=A(D8XIHDSZ+D8XILMSZ+2) Ext. length
D8XILVL,D8XIL64
D8XILTYP(2),=H'129'
Parcel flavor
D8XILLEN(2),=Y(D8XILMSZ+2) Parcel length
D8XILDAT,C'P'
"PRINT" compile option
D8XILDAT+1,C'Y'
"SPL" compile option
Using the Procedure
To invoke a previously compiled and saved procedure, an SQL CALL statement is sent to the
Database.
External Stored Procedures
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').
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
500
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 17: Stored Procedures
Dynamic Result Sets
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.
Dynamic Result Sets
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,
Return-statement-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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
501
Chapter 17: Stored Procedures
Dynamic Result Sets
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
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.
502
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 18
Resolver Base Module
This chapter describes how the Resolver Base Module (RBM) resolves 2PC (two-phase
commit) sessions that have in-doubt Teradata transactions. Topic include:
•
Using the Resolver Base Module
•
Request Parcel
•
Responses
Using the Resolver Base Module
To use the Resolver Base Module (RBM), you must be using Teradata Database for UNIX
version 2 release 2 (or later), or Teradata DBS for TOS version 1 release 5 (or later).
In-doubt transactions can be resolved the following ways:
•
CLIv2 program that accesses the RBM (information included in this section)
•
TDP commands (see Teradata Director Program Reference)
•
The TPCCONS utility on the operator‘s console (see the Utilities manual)
Accessing the Resolver Base Module
You can write a CLIv2 program that accesses the RBM when in-doubt transactions exist, so
that more of the recovery process is automated. To communicate with the RBM, you need to
log on to a special kind of session and use special kinds of request and response parcels. The
RBM does not accept Teradata SQL statements.
Note: All sequences and dialogs presented assume that Teradata semantics is being used.
Procedure
To log on to this special session, do the following:
1
Make sure you have the EXECUTE privilege on the TwoPCRule macro.
The Database Administrator (DBA) must grant EXECUTE privilege on the TwoPCRule
macro to all users who need to communicate with the RBM.
2
Use the correct logon string, which contains your userid and password.
3
Use the correct run pointer.
Set the 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 Call-Level Interface Version 2 Reference for Channel-Attached Systems
503
Chapter 18: Resolver Base Module
Request Parcel
4
Use the correct run string.
The partition name in the Run parcel or the Connect parcel should be RBM.
5
Use the correct Request parcel.
Use the Request parcel format shown on the next page to send requests to the Teradata
Database in a CLIv2 program.
6
Get the response.
To get the response, use the CLIv2 Fetch function. The responses for the RBM are
described in “Responses” on page 505.
Request Parcel
Teradata Database generates one or more parcels in response to a request it receives. It then
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. The RBM
does not accept Teradata SQL statements. It accepts only parcels in record mode.
Executing a Function
To execute a function, the RBM accepts a standard parcel sequence consisting of a request and
a respond (Resp or KeepResp) parcel. The module accepts only record mode parcels. Note,
however, that the mode is appropriate only when executing a list function. The sequence can
be generated using the Initiate Request function after setting the appropriate parameters in
DBCAREA. The length of the request string, and a pointer to it, are placed in DBCAREA
(Request Length and Request Pointer) prior to calling CLIv2.
Request String Format
The format of the request string is as follows:
String Element
Length
(bytes)
Description
Function Code
2
Indicates the operation to be performed.
Allowable values are as follows:
• 1 - Return a list of in-doubt Teradata transactions
• 2 - Commit all in-doubt Teradata transactions
• 3 - Commit in-doubt Teradata transactions in sessions specified in
session array
• 4 - Roll back all in-doubt Teradata transactions
• 5 - Roll back specified in-doubt Teradata transactions
• 6 - Return a list of coordinators
504
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 18: Resolver Base Module
Responses
String Element
Length
(bytes)
Logoff flag
1
Description
When set to binary 1, it indicates that the resolved sessions were to be
logged off.
Otherwise, set to binary zero.
Logical Host Id
2
Identifies the client submitting the request.
Coordinator
length
2
Indicates the number of bytes in the subsequent coordinator string.
Coordinator
30
max
Identifies the coordinator responsible for the in-doubt transactions
that are to be listed, committed, or rolled back.
Number of IDs
2
Indicates the number of session IDs in the Session ID array.
Session ID array
4 per
ID
Contain the TDP-assigned identifiers of the sessions that are to be
terminated.
The array is used with function codes 3 and 5 only.
For all other function codes, the array is empty.
Responses
The Teradata Database generates one or more parcels in response to a request it receives. It
then 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.
Output Parcels
When using CLIv2, the Fetch function returns the output parcels. The output parcel sequence
is as follows:
•
Success or a Failure parcel:
•
If Failure is returned, the error code defines the reason for the failure. For example, if a
parcel is malformed, a failure response is generated.
•
If Success is returned, the activity count reports the number of transactions or
coordinators affected.
•
Record parcel (for requests that execute a list function)
•
EndStatement
•
EndRequest
The following sections describe the responses for each of the function codes in the Request
parcel shown on the previous page.
Response to Function Code 1 (List Transactions)
If in-doubt Teradata transactions are found, the Success parcel activity count indicates how
many transactions were found. The response includes one record parcel for each transaction.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
505
Chapter 18: Resolver Base Module
Responses
The record parcel includes the following:
Flavor
Field
Length
Field
Parcel Body Fields
10
11 to 40
SessionNo:
4 byte unsigned integer
StringLength:
2 byte unsigned integer
RunUnitID:
1 to 30 bytes
•
SessionNo is the session number assigned by the TDP to the session creating the
transaction. This session number has an implicit qualifier of the host identifier for the
TDP.
•
StringLength is the number of bytes in the RunUnitID.
•
RunUnitID is the run unit identifier assigned to the transaction by the vote request.
Response to Function Codes 2 and 4 (Terminate All)
The Success parcel activity count indicates the number of completed Teradata transactions.
Response to Function Codes 3 and 5 (Terminate Some)
The Success parcel activity count indicates the number of terminated Teradata transactions. If
a specified session either is not found or does not have an in-doubt transaction, then a failure
parcel will be returned and no action will be taken on any sessions.
Response to Function Code 6 (List Coordinators)
The response will include one record parcel for each coordinator that has in-doubt sessions
on the Teradata Database. The record parcel includes:
506
Flavor
Field
Length
Field
Parcel Body Fields
10
7 to 36
StringLength:
2 bytes
CoordinatorID:
1 to 30 bytes
•
StringLength is a 2-byte field that contains the length of the bytes that follow in
CoordinatorID.
•
CoordinatorID (30 bytes maximum) identifies the coordinator responsible for the
in-doubt transactions.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
CHAPTER 19
2PC Protocol
This chapter describes the 2PC (two-phase commit) protocol, including:
•
Sync Point Services
•
Enabling 2PC Protocol
•
Starting 2PC Sessions
•
Using Coordinators to Synchronize Processing
•
The 2PC Process
•
In-Doubt Resolution
•
CLIv2 Application Requirements for 2PC
Introduction
If you use CICS or IMS applications to update both the Teradata Database and any other
recoverable resource or database within the same logical unit of work, consider using the 2PC
(two-phase commit) protocol. 2PC is available only for the following releases of the Teradata
Database:
•
Teradata Database for UNIX, version 2 release 2 (or later)
•
Teradata DBS for TOS, version 1 release 5 (or later).
If you attempt to use the 2PC mode in an unsupported environment, CLIv2 rejects the
attempt with the return code of “CLI0200 TWO PHASE COMMIT OPTION REQUIRES A
COORDINATOR.” ANSI environments do not support 2PC.
When you do not use the 2PC protocol, an application is subject to failure windows that can
leave the databases in an inconsistent or indeterminate state. The 2PC protocol eliminates
those failure windows.
For information on how the Teradata Database participates in the 2PC protocol, see the
Database Administration manual or the Database Design manual.
Sync Point Services
With 2PC, the CICS or IMS applications can access the Teradata Database as a sync point
participant. In this way, Teradata Database updates are committed or rolled back through the
use of CICS or IMS sync point services. The use of the sync point services guarantees that all
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
507
Chapter 19: 2PC Protocol
Enabling 2PC Protocol
updates performed within a logical unit of work will either all commit or all roll back. The
Teradata Database and the CICS or IMS Attachment Facilities support the sync point
manager and its use of the 2PC protocol. In the 2PC protocol, CICS or IMS act as the
coordinator, and the Teradata Databases act as participants.
Note: 2PC applications must use a coordinator such as IMS or CICS. They cannot run as
batch applications.
Enabling 2PC Protocol
The CLIv2 application specifies whether it is operating in 2PC mode or non-2PC mode at
connect time. To initiate the protocol for a session, the application can perform either of the
following actions:
•
Set a field option in DBCAREA and execute a CLIv2 Connect function in the individual
application
•
Set a 2PC mode default for all applications through the HSHSPB
A CLIv2 application can set the DBCAREA field for the CLIv2 Connect directly.
For more information on setting the 2PC field for the Connect function, see “DBCHCL” on
page 244. There is no limit to the number of sessions running in either mode, other than the
maximum number allowed for the system.
To use this option as the default mode...
Specify this setting in IBO2PC in the system
parameter block (HSHSPB)...
2PC
Y
non-2PC
N
If a protocol (2PC or non-2PC) is set in the DBCAREA, the HSHSPB protocol setting is
ignored.
Starting 2PC Sessions
CLIv2 applications logging on any sessions to the Teradata Database can request that either a
single session or multiple sessions be established. All the 2PC sessions established by an
application are considered part of the same commit-and-recovery unit. (Note that an
application can have separate non-2PC sessions.) Individual 2PC sessions can log on using the
Connect function DBO2PC option (values are Y or N).
An existing 2PC session can use the IRQ (Initiate Request) or IWPF (Initiate With Protocol
Function) to initiate a request. The IWPF function is similar to the Initiate Request function,
except that the Locate mode is not supported and optional 2PC optimizations can be used.
Session pools can be started from the TDP. To establish a session pool that is in 2PC mode,
508
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 19: 2PC Protocol
Using Coordinators to Synchronize Processing
use the TDP command, START POOL, with the TWOPC keyword. The TDP will start a pool
that contains only 2PC sessions.
For more information on using session pools with 2PC, see the Teradata Director Program
Reference.
Using Coordinators to Synchronize Processing
The following three main components are involved with 2PC protocol:
•
CLIv2 application
•
Participants (the databases)
•
Coordinator (IMS or CICS)
An application using the 2PC protocol must establish a 2PC session, initiate requests, and
manage sync point processing. The actual synchronization is handled by the coordinator.
When work is to be synchronized, the application requests that the coordinator communicate
with the other participants to complete the synchronization. Teradata provides
coordinator-participant communications services, not the actual coordinators. The internal
communications services (Coordinator-Participant Interface, or CPI) are provided as
extensions to CLIv2.
The 2PC Process
In a successful database update in a 2PC session, there are several critical events that take place
in the following order:
1
The application reads or updates (or both) the participant databases.
2
Once all database accesses in the logical unit of work have completed successfully, the
application directs the coordinator to commit the updates.
3
The coordinator sends a prepare to commit request to all participants.
4
If the participant can commit the work, it externalizes its journal entries, retains any write
locks obtained in the logical unit of work, and responds affirmatively to the coordinator‘s
prepare to commit request.
5
The coordinator collects all the responses to the prepare to commit request and, if all are
affirmative, enters the commit phase and sends commit requests to all participants.
6
The participants irrevocably commit the updates and release the write locks.
7
The participants respond to the coordinator‘s commit request with a confirmation that
the commit has been successfully completed.
8
The application receives control at the statement following its commit request from step 2,
above.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
509
Chapter 19: 2PC Protocol
In-Doubt Resolution
In-Doubt Resolution
If there is a site or communication failure (for example, a power failure, operating system
error, or telecommunication failure) during the process just described, there are different
recovery actions, depending on the step at which the failure occurred.
If the failure occurs at this
point in the 2PC process...
Then the participant...
before step 4
rolls back the updates.
during step 6
after the participant has received and logged the coordinator‘s
commit request, the participant continues with the commit process.
after step 4, but before step 6
is said to be in-doubt as to whether it should commit or roll back
the updates, so it cannot take any unilateral action.
The participant must wait for in-doubt resolution to complete the
transaction.
There are two forms of in-doubt resolution: automatic and manual.
They are explained later in further detail.
Automatic In-Doubt Resolution
After a failure in either the coordinator or any participants, automatic in-doubt resolution is
accomplished when the communication between the coordinator and the participants is
reestablished. When the interface to the participants is started using /START SUBSYS (for
IMS) or DAFC START (for CICS), the participants’ logs are presented to the coordinator. For
each in-doubt logical unit of work, the coordinator informs the participants whether the
updates should be committed or rolled back, based on information recorded in the
coordinator log.
Manual In-Doubt Resolution
When automatic in-doubt resolution is unavailable or unsuccessful, it may be necessary to
manually resolve the in-doubt sessions. This is because the in-doubt sessions could be holding
locks on database objects that block the progress of other work that is executing against that
Teradata Database.
Warning:
Incorrect use of manual in-doubt resolution can damage the database.
You can use any of the following interfaces to accomplish manual in-doubt resolution:
510
•
The TDP commands DISPLAY INDOUBT, COMMIT, and ROLLBACK
•
The TPCCONS utility on the operator‘s console
•
A CLIv2 program to log on to the Resolver Base Module (RBM) with the CLIv2 Run
parcel and resolving the sessions using the TPCCONS commands
•
Using CLIv2 applications to issue TDP commands using the CMD function (for more
information on the CMD function, see “DBCHCL” on page 244.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 19: 2PC Protocol
CLIv2 Application Requirements for 2PC
For more information on 2PC in-doubt resolution, see the following documents:
•
IBM CICS Interface for Teradata Reference
•
IIBM IMS/DC Interface for Teradata Reference
•
IBM Database 2 V1 R1-CICS/VS Interface Guide, document number GG24-1632-00, from
IBM
•
IBM Database 2 V1 R1-IMS/VS Interface Guide, document number GG24-1637-00, from
IBM
CLIv2 Application Requirements for 2PC
The following requirements apply to CLIv2 applications that use the 2PC protocol:
•
The application must establish a 2PC session, initiate requests, and use the coordinator‘s
sync point facilities to commit the updates rather than issue direct commands to the
participant.
•
Any connection used for 2PC requests must be specified as a 2PC connection.
For example, you can use the CON function‘s 2PC option in the DBCAREA or set the 2PC
default in the HSHSPB.
•
An END TRANSACTION statement must have a corresponding BEGIN TRANSACTION
preceding it. For applications in 2PC mode, both of these commands can be used only in
inner nested transactions.
•
The application must use CICS/VS or IMS/VS syncpoint processing to commit or abort
the transaction (not END TRANSACTION, ROLLBACK WORK, COMMIT WORK, or
ABORT).
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
511
Chapter 19: 2PC Protocol
CLIv2 Application Requirements for 2PC
512
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
APPENDIX A
How to Read Syntax Diagrams
This appendix describes the rules that apply to the syntax diagrams used in this book.
Syntax Diagram Conventions
Notation Conventions
Item
Definition / Comments
Letter
An uppercase or lowercase alphabetic character ranging from A through Z.
Number
A digit ranging from 0 through 9.
Do not use commas when typing a number with more than 3 digits.
Word
Variables and reserved words.
• UPPERCASE LETTERS represent a keyword.
Syntax diagrams show all keywords in uppercase, unless operating system
restrictions require them to be in lowercase.
• lowercase letters represent a keyword that you must type in lowercase, such as a
UNIX command.
• lowercase italic letters represent a variable such as a column or table name.
Substitute the variable with a proper value.
• lowercase bold letters represent a variable that is defined immediately
following the diagram that contains the variable.
• UNDERLINED LETTERS represent the default value.
This applies to both uppercase and lowercase words.
Spaces
Use one space between items such as keywords or variables.
Punctuation
Type all punctuation exactly as it appears in the diagram.
Paths
The main path along the syntax diagram begins at the left with a keyword, and proceeds, left
to right, to the vertical bar, which marks the end of the diagram. Paths that do not have an
arrow or a vertical bar only show portions of the syntax.
The only part of a path that reads from right to left is a loop.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
513
Appendix A: How to Read Syntax Diagrams
Syntax Diagram Conventions
Continuation Links
Paths that are too long for one line use continuation links. Continuation links are circled
letters indicating the beginning and end of a link:
A
A
FE0CA002
When you see a circled letter in a syntax diagram, go to the corresponding circled letter and
continue reading.
Required Entries
Required entries appear on the main path:
SHOW
FE0CA003
If you can choose from more than one entry, the choices appear vertically, in a stack. The first
entry appears on the main path:
SHOW
CONTROLS
VERSIONS
FE0CA005
Optional Entries
You may choose to include or disregard optional entries. Optional entries appear below the
main path:
SHOW
CONTROLS
FE0CA004
If you can optionally choose from more than one entry, all the choices appear below the main
path:
514
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Appendix A: How to Read Syntax Diagrams
Syntax Diagram Conventions
READ
SHARE
ACCESS
JC01A010
Some commands and statements treat one of the optional choices as a default value. This
value is UNDERLINED. It is presumed to be selected if you type the command or statement
without specifying one of the options.
Strings
Strings appear in single quotes:
'msgtext'
JC01A004
If the string text includes a single quote or a blank space, the string appears in double quotes:
''abc'd"
''abc d"
JC01A005
Abbreviations
If a keyword or a reserved word has a valid abbreviation, the unabbreviated form always
appears on the main path. The shortest valid abbreviation appears beneath.
SHOW
CONTROLS
CONTROL
FE0CA042
In the above syntax, the following formats are valid:
•
SHOW CONTROLS
•
SHOW CONTROL
Loops
A loop is an entry or a group of entries that you can repeat one or more times. Syntax
diagrams show loops as a return path above the main path, over the item or items that you can
repeat:
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
515
Appendix A: How to Read Syntax Diagrams
Syntax Diagram Conventions
,
,
(
cname
3
4
)
JC01B012
Read loops from right to left.
The following conventions apply to loops:
Loop Convention
Description
A maximum number of entries is
allowed.
The number appears in a circle on the return path.
A minimum number of entries is
required.
The number appears in a square on the return path.
A separator character is required
between entries.
The character appears on the return path.
In the example, you may type cname a maximum of 4 times.
In the example, you must type at least three groups of column
names.
If the diagram does not show a separator character, use one
blank space.
In the example, the separator character is a comma.
A delimiter character is required
around entries.
The beginning and end characters appear outside the return
path.
Generally, a space is not needed between delimiter characters
and entries.
In the example, the delimiter characters are the left and right
parentheses.
Excerpts
Sometimes a piece of a syntax phrase is too large to fit into the diagram. Such a phrase is
indicated by a break in the path, marked by (|) terminators on either side of the break. The
name for the excerpted piece appears between the terminators in boldface type.
516
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Appendix A: How to Read Syntax Diagrams
Syntax Diagram Conventions
The boldface excerpt name and the excerpted phrase appears immediately after the main
diagram. The excerpted phrase starts and ends with a plain horizontal line:
LOCKING
excerpt
A
A
HAVING
con
excerpt
where_cond
,
cname
,
col_pos
JC01A014
Multiple Legitimate Phrases
In a syntax diagram, it is possible for any number of phrases to be legitimate:
dbname
DATABASE
tname
TABLE
vname
VIEW
JC01A016
In this example, any of the following phrases are legitimate:
•
dbname
•
DATABASE dbname
•
tname
•
TABLE tname
•
vname
•
VIEW vname
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
517
Appendix A: How to Read Syntax Diagrams
Syntax Diagram Conventions
Sample Syntax Diagram
,
viewname
CREATE VIEW
AS
cname
CV
A
LOCKING
LOCK
ACCESS
dbname
A
DATABASE
SHARE
FOR
IN
tname
READ
TABLE
WRITE
EXCLUSIVE
vname
VIEW
EXCL
,
B
SEL
B
MODE
expr
,
FROM
tname
qual_cond
C
.aname
C
HAVING cond
;
qual_cond
,
WHERE cond
GROUP BY
cname
,
col_pos
JC01A018
Diagram Identifier
The alphanumeric string that appears in the lower right corner of every diagram is an internal
identifier used to catalog the diagram. The text never refers to this string.
518
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Glossary
A
abend Abnormal end of task. Termination of a task prior to its completion because of an
error condition that cannot be resolved by the recovery facilities during execution.
account The distinct portion of a system account string, excluding the performance group
designation. Accounts can be employed wherever a user object can be specified.
administrator
AP
A special user responsible for allocating resources to a community of users.
Application Processor
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, which is a set of calling conventions by which an
application accesses an operating system and other services. An API is defined in the source
code and provides a level of abstraction between an 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 can 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.
APRC
Application Processor Reset Containment
ASCII American Standard Code for Information Interchange, a character set used primarily
on personal computers.
B
BLOB Binary large object, which is a large database object (up to 2 GB) that doesn‘t require
character set conversion, including MIDI, MP3, PDF, graphics, and more.
C
Call-Level Interface Version 2 (CLIv2) A collection of callable service routines that provide
an interface between an application and the MTDP (for network-attached clients) or TDP
(for channel-attached). CLI builds parcels that are sent to Teradata Database and provides the
application with a pointer to each of the parcels returned from Teradata Database.
CASE Computer-Aided Software Engineering
channel-attached A mainframe computer that communicates with a server (for example,
Teradata Database) through a channel driver.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
519
Glossary
character set A grouping of alphanumeric and special characters used by computer systems
to support user languages and applications. Various character sets have been codified by the
American National Standards Institute (ANSI).
CICS
Customer Information Control System
client
A computer that can access the Teradata Database.
CLIv2so Call-Level Interface Version 2 Shared Object, which is the program that installs the
CLI libraries required by other utilities. When CLIv2so submits a request to Teradata
Database, CLI Library components transform the request into Teradata Database formats.
The CLI Library sends requests to, and receives responses from, Teradata Database over a
network.
CLOB Character large object, which is a large character-based (such as HTML, RTF)
database object up to 2 GB.
COBOL
Common Business-Oriented Language
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.
CPU
Central processing unit
D
database A related set of tables that share a common space allocation and owner. A
collection of objects that provide a logical grouping for information. The objects include
tables, views, macros, triggers, and stored procedures.
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.
DBA
Database administrator
DDL Data definition language, which supports manipulating database structures and the
Data Dictionary information kept about these structures.
delimiter In Teradata SQL, a punctuation mark or other special symbol that separates
clauses in a Teradata SQL statement or separates one Teradata SQL statement from another.
EBCDIC Extended binary coded decimal interchange code, which is an IBM code that uses
8 bits to represent 256 possible characters. It is used primarily in IBM mainframes, whereas
personal computers use ASCII.
EUC Extended UNIX Code. For Japanese and Traditional-Chinese, EUC defines a set of
encoding rules that can support from 1 to 4 character sets.
extract The copying of a subset of data from a source to a target environment.
520
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Glossary
exit routine Specifies a predefined action to be performed whenever certain significant
events occur during a job.
F
field The basic unit of information stored in Teradata Database. A field is either null, or has
a single numeric or string value.
FIPS
Federal Information Processing Standards
I
IPT
I/Os per transaction
in-doubt A transaction in process on two or more independent computer processing
systems when an interruption of service occurs on one or more of the systems. The
transaction is said to be in doubt because it is not known whether the transaction is
successfully processed on all of the systems.
I/O Input/output
ISO International Standards Organization
J
JCL Job Control Language is a language for describing jobs (units of work) to z/OS and VSE
operating systems (OSs), which run on IBM z800/900 large server (mainframe) computers.
These OSs allocate their time and space resources among the total number of jobs started in a
computer. Jobs then break down into job steps. All the statements required to run a particular
program constitute a job step. Jobs are background (sometimes called batch) units of work
that run without user interaction (for example, print jobs). The OS manages interactive
(foreground) user requests that initiate units of work. In general, foreground work is given
priority over background work.
JIS Japanese Industrial Standards specify the standards for industrial activities in Japan. The
standardization process is published through Japanese Standards Association.
L
LOB Large object, which is a database object that is up to 2 gigabytes. LOBs can be
character-based (CLOBs) or binary-based (BLOBs).
log A file that records events. Many programs produce log files. Log files can help determine
what happened during an processing failure. Log files have the extension “.log”.
M
macro A file that is created and stored on Teradata Database, and executed in response to a
Teradata SQL EXECUTE statement
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
521
Glossary
MTDP Micro Teradata Director Program, which is a library of routines that implement the
session layer on the workstation. MTDP is the interface between CLI and Teradata Database.
MPP Massively parallel processing
MVS (Multiple Virtual Storage) One of the primary operating systems for large IBM
computers.
N
name A word supplied by a user that refers to an object, such as a column, database, macro,
table, user, or view.
null
The absence of a value for a field.
P
parameter A variable name in a macro for which an argument value is substituted when the
macro is executed.
physical action A basic action type, such as <Send a Page>, <Send an E-Mail>, etc. Physical
actions must be encapsulated by logical actions in order to be used in an alert policy.
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.
protocol The rules for the format, sequence, and relative timing of messages exchanged on a
network.
R
request In host software, a message sent from an application program to the Teradata
Database.
result The information returned to a user to satisfy a request made of the Teradata
Database.
row Whether null or not, a row represents one entry under each column in a table. The row
is the smallest unit of information operated on by data manipulation statements.
S
server A computer system running Teradata Database. Typically, a Teradata Database
server has multiple nodes, which can include both TPA and non-TPA nodes. All nodes of the
server are connected via the Teradata BYNET or other similar interconnect.
session A session begins when a user logs on to Teradata Database and ends when the user
logs off. Also called a Teradata Database session.
SMP
522
Symmetric multi-processing
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Glossary
statement A request for processing by Teradata Database that consists of a keyword verb,
optional phrases, and operands, and that is processed as a single entity.
statistics The details of a process used to collect, analyze, and transform the database objects
used by a given query.
stored procedure 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.
TCP/IP
Transmission Control Protocol/Internet Protocol.
TDPID Teradata Director Program Identifier, which is the name of the Teradata Database
being accessed.
TDP Teradata Director Program, which provides a high-performance interface for
messages communicated between the client and the Teradata system.
test system A Teradata Database where you want to import Optimizer-specific information
to emulate a target system and create new queries or test new features.
title In Teradata SQL, a string used as a column heading in a report. By default, the title is
the column name, but a title can also be explicitly declared by a TITLE phrase.
TPA
Trusted parallel application
TOS
Teradata operating system
transaction A set of Teradata SQL statements 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. 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.
two-phase commit The process by which a relational database ensures that distributed
transactions are performed in an orderly manner. Transactions are terminated by either
committing them or rolling them back.
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.
U
UDF
User-defined functions
Unicode A fixed-width (16 bits) encoding of virtually all characters present in all languages
in the world.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
523
Glossary
user In Teradata SQL, a database associated with a person who uses Teradata Database. The
database stores the person‘s private information and accesses other Teradata Databases.
user A database associated with a person who uses Teradata Database. The database stores
the person‘s private information and accesses other Teradata Databases.
UTF-8 In simple terms, UTF-8 is an 8 bit encoding of 16 bit Unicode to achieve an
international character representation.
In more technical terms, in UTF-8, characters are encoded using sequences of 1 to 6 octets.
The only octet of a sequence of one has the higher-order bit set to 0, the remaining 7 bits are
used to encode the character value. UTF-8 uses all bits of an octet, but has the quality of
preserving the full US-ASCII range. The UTF-8 encoding of Unicode and UCS avoids the
problems of fixed-length Unicode encodings because an ASCII file encoded in UTF is exactly
same as the original ASCII file and all non-ASCII characters are guaranteed to have the most
significant bit set (bit 0x80). This means that normal tools for text searching work as expected.
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 Teradata Database. A
view, like a table, has rows and columns; however, the rows and columns of a view are not
directly stored by Teradata Database, rather they are derived from the rows and columns of
tables (or other views).
Z
z/OS
One of the primary operating systems for large IBM computers.
z/VM (Virtual Machine)
524
One of the primary operating systems for large IBM computers.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
Numerics
2PC 207
Coordinator’s Participant Interface
defined 509
field 207
in-doubt resolution 510
session, starting Connect function 508
using in CLIv2 application 507
A
Abort function 63, 263
summary of uses 240
abort, crash-related 371
ABT function. See Abort function
access rights
security considerations 30
Anticipated Number of Concurrent Sessions field 73
Assembler. See IBM Assembler
authorization
security considerations 30
B
be 47
Buffer, request. See Request buffer
Buffer, response. See Response buffer
C
C2S Conversion field 87, 167
Call Level Interface version 2. See CLIv2
Call routine, DBCHCL 244
Change Options field 75
Parcel Mode Fetch 131
processing options 76
setting 49
using 49
change_opts 75
Character Set Pointer field 78
Cleanup routine 271
CLI routine
DBCHCL 244
DBCHCLN 271
DBCHINI 242
optional
summary of uses 273
summary of uses 240
CLI0200, return code 507
CMD function. See Command function
COBOL
DBCAREA-0-REQ-ID 127
DBCAREA-CHANGE-OPTS 75
DBCAREA-CUR-REQ-BUF-LEN 84, 87
DBCAREA-CUR-RESP-BUF-LEN 87
DBCAREA-EYECATCHER 93
DBCAREA-FET-DATA-PTR 94
DBCAREA-FET-MAX-DATA-LEN 95
DBCAREA-FET-PARCEL-FLAVOR 96
DBCAREA-FET-RET-DATA-LEN 97
DBCAREA-HSISVC-TIME 168
DBCAREA-I-REQ-ID 101
DBCAREA-IWPF-FUNCTION 135
DBCAREA-KEEP-RESP 103
DBCAREA-LOC-MODE 107, 108
DBCAREA-LOGON-LEN 109
DBCAREA-LOGON-PTR 110
DBCAREA-MAX-NUM-SESS 73
DBCAREA-MSG-LEN 123
DBCAREA-MSG-TEXT 123
DBCAREA-O-DBCPATH 128
DBCAREA-O-DBC-SESS-ID 129
DBCAREA-O-HOST-ID 128
DBCAREA-OPEN-REQS 125
DBCAREA-PARCEL-MODE 130
DBCAREA-REQ-BUF-LEN 137
DBCAREA-REQ-LEN 138
DBCAREA-REQ-PROC-OPT 143
DBCAREA-REQ-PTR 142
DBCAREA-RESP-BUF-LEN 146
DBCAREA-RUN-LEN 156
DBCAREA-RUN-PTR 158
DBCAREA-SESS-STATUS 164
DBCAREA-SET-CHAR-SET 165, 175, 176, 177, 178
DBCAREA-TOTAL-LEN 180
DBCAREA-TWO-PHASE-COMMIT 207
Code
error 53, 367
failure 53, 367
return 53, 54
Command function 260
summary of uses 240
CON function. See Connect function
Connect function
ReturnCode address 247
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
525
Index
summary of uses 240
Connect Type field 81
Coordinator’s Participant Interface 509
Country Id 84
changing 85
CPI. See Coordinator’s Participant Interface
Crash 369
CRQ 240
cur_req_buf_len 84, 87
cur_resp_buf_len 87
Current Request Buffer Length field 86
Current Response Buffer Length field 87
D
Data parcel 477
data structures, supported 32
Data type
indicator mode 441, 453
IndicData parcel 482
internal format 35
record mode 454
DataInfo parcel
ECHO statement 429, 477
Date Form field 89
DB02FBU 183
DBC/SQL, partition 33
DBCACNX 230
DBCAID 93
DBCAIRX 209, 229
logical sections 209
DBCAIRXC 230
DBCAIRXH 229, 230
DBCAIRXP 230
DBCAREA 67
allocating 243
as data structure 47
DBCHINI and 242
extension
C definitions for 229
COBOL definitions for 229, 230
IBM Assembler definitions for 229, 230
PL/I definitions for 229, 230
Field Descriptions 67
logical sections 67
multi-session 48
multi-thread 48
preparing to use 47
using 48
DBCAREA.H
change_opts 75
charset_type 165, 175, 176, 177, 178
cur_req_buf_len 84, 87
cur_resp_buf_len 87
526
dbcLevel 107
eyecatcher 93
fet_data_ptr 94
fet_parcel_flavor 96
fet_ret_data_len 97
hsisvc_time 168
i_req_id 101
iwpf_function 135
keep_resp 103
loc_mode 108
logon_len 109
logon_ptr 110
max_num_sess 73
msg_len 123
msg_text 123
o_dbc_sess_id 129
o_dbcpath 128
o_host_id 128
o_req_id 127
open_reqs 125
parcel_mode 130
req_buf_len 137
req_proc_opt 143
req_ptr 142
req-len 138
resp_buf_len 146
run_len 156
run_ptr 158
sess_status 164
tell_about_crash 170
total_len 180
two_phase_commit 207
two_resp_bufs 183
x_elm_type 215
DBCAREA-CHANGE-OPTS 75
DBCAREA-CUR-REQ-BUF-LEN 84, 87
DBCAREA-CUR-RESP-BUF-LEN 87
DBCAREA-EYECATCHER 93
DBCAREA-FET-DATA-PTR 94
DBCAREA-FET-MAX-DATA-LEN 95
DBCAREA-FET-PARCEL-FLAVOR 96
DBCAREA-FET-RET-DATA-LEN 97
DBCAREAH 229
DBCAREA-HSISVC-TIME 168
DBCAREA-I-REQ-ID 101
DBCAREA-KEEP-RESP 103
DBCAREA-LOC-MODE 107, 108
DBCAREA-LOGON-LEN 109
DBCAREA-LOGON-PTR 110
DBCAREA-MAX-NUM-SESS 73
DBCAREA-MSG-LEN 123
DBCAREA-MSG-TEXT 123
DBCAREA-O-DBC-SESS-ID 129
DBCAREA-O-HOST-ID 128
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
DBCAREA-O-PATH 128
DBCAREA-OPEN-REQS 125
DBCAREA-O-REQ-ID 127
DBCAREAP 229
DBCAREA-PARCEL-MODE 130
DBCAREA-REQ-BUF-LEN 137
DBCAREA-REQ-LEN 138
DBCAREA-REQ-PROC-OPT 143
DBCAREA-REQ-PTR 142
DBCAREA-RESP-BUF-LEN 146
DBCAREA-RUN-LEN 156
DBCAREA-RUN-PTR 158
DBCAREA-SESS-STATUS 164
DBCAREA-TOTAL-LEN 180
DBCAREA-TWO-PHASE-COMMIT 207
DBCHCL 244
multi-session 42
return code 245
summary of uses 240
Wait For Response 245
DBCHCL Functions
CMD 260
CON 247
DSC 270
ERQ 267
FET 265
IRQ 252
IWPF 255
REW 269
RSUP 250
DBCHCLN 271
alternate name for 271
summary of uses 240
DBCHCN. See DBCHCLN
DBCHIN. See DBCHINI
DBCHINI 67
alternate name for 242
initializing DBCAREA 242
return code 244
summary of uses 240
Total Length field 242
DBCHME
summary of parameters 274
summary of uses 273
DBCHMEC
Master event control block routine 276, 278
summary of parameters 274
summary of uses 273
DBCHPE. See DBCHPEC
DBCHPEC
alternate name for 279
post ECB routine 279
summary of parameters 274
summary of uses 273
DBCHQE
context area 289
query environment 289
return code 289
DBCHQEP
C definitions for 230, 231
COBOL definitions for 230, 231
IBM Assembler definitions for 230, 231
PL/I definitions for 230, 231
DBCHQEPC 229, 230, 231
DBCHQEPH 230, 231
DBCHQEPP 230, 231
DBCHSA. See DBCHSAD
DBCHSAD
alternate name for 280
return code 280
summary of parameters 275
summary of uses 273
DBCHUEC
return code 281, 283
summary of parameters 275
summary of uses 274
user provided ECB 281, 283
UserECB address 281, 283
DBCHUEPC 231
DBCHUEPH 231
DBCHUEPP 231
DBCHWAT
alternate name for 284
multi-session 42
return code 284
summary of parameters 275
uses 274
DBCHWL
summary of parameters 275
DBCHWT. See DBCHWAT
DBCIFBRL 146
DBCIRBRL 137
DBCISMAX 73
DBCMSG 124
DBCMSGL 123
DBCMSGRD 156
DBCNILSL 109
DBCNILSP 110
DBCNIRSL 156
DBCNIRSP 158
DBCOFBLA 84, 87
DBCOFLG1 164
DBCOREQN 127
DBCOSID 128
DBCOSILH 128
DBCOSISN 129
DBCOSITM 128
DBCOSITV 128
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
527
Index
DBCSIZE 180
DBCTSTMP 168
DBFIWPF, 2PC and 508
DBFOPFLV 96
DBFXFDP 94
DBOBSYW 203
DBOBTPM 130
DBOCRSW 201, 202
DBOCRTL 170
DBOFLOC 107, 108
DBOFUNT 143
DBOKRSP 103
DBOSCSP 165, 175, 176, 177, 178
DBOSETO 75
DBRIPF 135
DBRIRQL 138
DBRIRQP 142
DBROREQC 125
Describing User-defined Character Sets 407
Disconnect function 64, 270
summary of uses 240
DSC function. See Disconnect function
E
ECHO statement
DataInfo parcel 429, 477
PrepInfo parcel 444, 447
record mode 454
Record parcel 454
Element Length field
DBCAIRX 215
Element Type field and 215
Element Type field
DBCAIRX 215
Element Length field and 215
Pointer Element Address field and 212
Pointer Element Length field and 213
ElicitData parcel
LOBs 38
ElicitName parcel
LOBs 38
End Request function 267
summary of uses 240
EndRequest parcel
indicator mode 347
EndStatement parcel
indicator mode 347
Environment query. See DBCHQE
ERQ function. See End Request function
Error code 367
Error parcel 244, 435
KeepResp parcel and 435
Resp parcel and 435
528
response sequence 364
Event control block (ECB)
master routine. See DBCHME
master routine. See DBCHMEC
post routine. See DBCHPEC
user provided. See DBCHUEC
Extension Pointer field 92
DBCAIRX and 209
Extensions, DBCAREA 209
Eyecatcher field
DBCAIRX 216
DBCAREA 93
F
Failure code 53, 367
Failure parcel 244
logging on and 350
response sequence 364
session control 350
FET function. See Fetch function
fet_data_ptr 94
fet_max_data_len 95
fet_parcel_flavor 96
fet_ret_data_len 97
Fetch Data Pointer field 93
Fetch Returned Date Length 98
locate mode, relation to 109
Fetch function 60, 265
summary of uses 240
Fetch Maximum Data Length field 95
locate mode, relation to 109
Fetch Parcel Flavor field 96
locate mode, relation to 109
Fetch Returned Data Length field 97
locate mode 109
Variable Length Fetch
relation to 197
Fields in DBCAIRX
Data Address 212
Data Length 213
Element Length 215
Element Type 215
Eyecatcher 216
Next Pointer 218
Total Length 219
Total Size 220
Fields in DBCAREA
2PC 207
C2S conversion 87
change options 75
character set pointer 78
connect type 81
current request buffer length 86
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
current response buffer length 87
date form 89
extension pointer 92
eyecatcher 93
fetch data pointer 93
fetch maximum data length 95
fetch parcel flavor 96
fetch returned data length 97
function 98
input CLIv2 request id 100
input CLIv2 session id 100
keep response 102
locate mode 108
logon length 109
logon pointer 110
Max-decimal-returned 113
maximum parcel 114
message length 123
message text 123
open requests 124
output CLIv2 request id 127
output DBC session id 129
output host id 128
output TDP path 128
parcel mode fetch 130
protocol-function 135
request buffer length 137
request length 138
request mode 139
request pointer 142
request processing option 143
Request-token 145
response buffer length 145
response mode 146
return code 149
return time 154
route description codes 156
run length 156
run pointer 158
S2C conversion 167
Save Response Buffer 159
Segment Data 160
Session Status 164
Set Character Set 165
TDP request number 169
TDP-receipt-timestamp 168
TDPWAIT Time 171
tell about crash 170, 371
Time1-status 174
Time2-status 175
Time3 172
Time3-status 176
Time4 171, 173
Time4-status 177
Time5 174
Time5-status 178
total length 180
Transaction Semantics 180
Two Response Buffers 183
Use Presence Bits 186
Using Data Length 189
Using Data Pointer field 190
Variable Length Fetch 196
Variable Length Request 198
wait across crash 201, 371
wait for response 203, 371
fields in DBCAREA 67
Finding Files on the Release Tape
DBCAIRX 229
DBCHMEP 230
DBCHQER 231
DBCHUEP 231
HSHSPB 231
format, data
IBM mainframe, internal 35
Function
abbreviations 67
Abort 240, 263
Command 240, 260
Connect 240, 247
Disconnect 240, 270
End Request 240, 267
Fetch 240, 265
Initiate Request 240, 252
IWPF 240, 255
Rewind 240, 269
RunStartUp 240, 250
Function field 98
H
HSHSPB 33
defaults 49
MVS 233
VM 233
hsisvc_time 168
I
i_req_id 101
IBM Assembler 47
DBCAID 93
DBCIFBRL 146
DBCIRBRL 137
DBCISMAX 73
DBCMSG 124
DBCMSGL 123
DBCMSGRD 156
DBCNILSL 109
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
529
Index
DBCNILSP 110
DBCNIRSL 156
DBCNIRSP 158
DBCOFBLA 84, 87
DBCOREQ 127
DBCOSID 128
DBCOSILH 128
DBCOSITM 128
DBCOSITV 128
DBCOTSS1 175
DBCOTSS2 176
DBCOTSS3 176
DBCOTSS4 177
DBCOTSS5 178
DBCPSOSN 129
DBCSIZE 180
DBCTSTMP 168
DBFIPACT 132
DBFIPSNM 134
DBFIPVAL 134
DBFOPFLV 96
DBFXFDP 94
DBO2FBU 183
DBO2PC 207
DBOBSYW 203
DBOBTPM 130
DBOCRSW 201, 202
DBOCRTL 170
DBOFLOC 107, 108
DBOFUNT 143
DBOKRSP 103
DBOSCSP 165
DBOSETO 75
DBRIPF 135
DBRIRQL 138
DBRIRQP 142
DBROREQC 125
DNCOFLG1 164
MVS 128
VM 128
implied waiting 47
Indicator mode 440, 452
DataInfo parcel 441, 453
null indicator 440, 452
Response parcel 440, 452
response sequence 348
SELECT statement and 441, 453
IndicData parcel, data type 482
In-doubt resolution, 2PC 510
Initialize routine, DBCHINI 242
Initiate Request function 59, 252
summary of uses 240
Initiate With Protocol-Function
summary of uses 240
530
Initiate With Protocol-Function function 255
Input CLIv2 Request Id field 100
Output CLIv2 Request Id 127
Input CLIv2 Session Id field 100
Output Field Id 126
Input TDP Path field 101
INSERT statement 38
internal format
data type 35
mainframe 35
IRQ function. See Initiate Request function
ISO 3166-1
Country Id 84
ISO 639
Language Id standard 105
IWPF function. See Initiate With Protocol-Function
iwpf_function 135
K
Keep Response field 102
keep_resp 103
KeepResp parcel
Error parcel, relation to 435
L
Language
message module names 413
variant
specify with Country Id 84
Language Id
described 105
LANG and Country keywords 415
large objects 38
Level 107
loc_mode 107, 108
Locate Mode field 108
Fetch Maximum Data Length, relation to 96
logical structure 30
Logon
unsuccessful
Error parcel 350
Failure parcel 350
Logon Length field 109
Logon pointer field 110
logon_len 109
logon_ptr 110
LOGON-LEN 109
M
Macro
message definition 415
mainframe
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
format, internal 35
max_num_sess 73
Maximum Parcel field 114
Message Definition
file described 232, 413
macro described 415
message definitions 33
Message Length field 123
Message modules 413
Message Text field 123
Move area 341
msg_len 123
msg_text 123
multi-session management
concurrent requests 42
DBCHCL 42
DBCHWAT 42
N
Next Pointer field
DBCAIRX 218
NullField parcel 441
O
o_dbc_sess_id 129
o_host_id 128
o-dbcpath 128
onzero 53
Open Requests field 124
Keep Response 104
open_reqs 125
operation, parallel 40
o-req-id 127
Output CLIv2 Request Id field 127
Input CLIv2 Request Id, relation to 101
Output CLIv2 Session Id field
Input CLIv2 Session Id, relation to 100
Output DBC Session Id field 129
Output Session Id, relation to 126
Output Host Id 128
Output TDP Path 126
field 128
P
Parcel
body 420
Data 477
Error 364, 435
Failure 364
flavor 419
header 419
NullField 441
overview 419
Record 439, 450, 451
Request 420, 473
Resolver Base Module 503
Response 421
sequence 364
structure 471
type 419, 420, 473
Parcel Mode Fetch field 130
Fetch Maximum Data Length, relation to 96
Fetch Parcel Flavor, relation to 97
locate mode, relation to 108
wait for response, relation to 203
parcel_mode 130
partition
DBC/SQL 33
performance monitor 33
Resolver Base Module 33
password, expiration 57
passwords
security considerations 30
PL/I
CHANGE_OPTS 75
CUR_REQ_BUF_LEN 84, 87
CUR_RESP_BUF_LEN 87
EYECATCHER 93
FET_DATA_PTR 94
FET_MAX_DATA_LEN 95
FET_PARCEL_FLAVOR 96
FET_RET_DATA_LEN 97
HSISVC Time 168
I_REQ_ID 101
IWPF_FUNCTION 135
KEEP_RESP 103
LOC_MODE 107, 108
LOGON_LEN 109
LOGON_PTR 110
MAX_NUM_SESS 73
MSG_LEN 123
MSG_TEXT 123
O_DBC_SESS_ID 129
O_DBCPATH 128
O_HOST_ID 128
O_REQ_ID 127
OPEN_REQS 125
PARCEL_MODE 130
REQ_BUF_LEN 137
REQ_LEN 138
REQ_PROC_OPT 143
REQ_PTR 142
RESP_BUF_LEN 146
RUN_LEN 156
RUN_PTR 158
SESS_STATUS 164
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
531
Index
SET_CHAR_SET 165, 175, 176, 177, 178
TELL_ABOUT_CRASH 170
TOTAL_LEN 180
TWO_PHASE_COMMIT 207
TWO_RESP_BUFS 183
Pointer Element Address field
DBCAIRX 212
Pointer Element Length field, DBCAIRX 213
Positioning-action 132, 133
PrepInfo parcel, ECHO statement 444, 447
preprocessors 30
prerequisites 47
product version numbers 3
Protocol-Function field 135
R
Record mode
data type 454
ECHO statement 454
null 454
requests
issuing 355
Response parcel 440, 452, 454
response sequence 345
Record parcel 439, 450, 451
ECHO statement 454
indicator mode. See Indicator mode
Record Parcel, Record mode. See Record mode
release tape
C files 229
COBOL files 229
IBM assembler files 229
PL/I files 229
z/OS and z/VM 233
Release Tapes
DBCAREA 229
req_buf_len 137
req_len 138
req_proc_opt 143
req_ptr 142
request
concurrent 42
multiple, managing 40
multi-statement 40
Teradata SQL, submitting 59
Request buffer
Current Request Buffer Length field 339
Request Buffer Length field 339
Request Buffer Length 137
Request Length field 138
Request Mode 140
Request mode 139
Request Pointer field 142
532
Request Processing Option 143
Request-token field 145
Resolver Base Module
parcel 503
partition 33
Resp parcel
Error parcel, relation to 435
resp_buf_len 146
Response
sequence 342, 504, 505
indicator mode 348
Record mode 345
Response buffer
Current Response Buffer Length field 341
Keep Response field 340
Response Buffer Length field 341
Two Response Buffers field 340
Wait For Response field 341
Response Mode 146
Response parcel, overview 421
Return code 53
2PC 507
busy 245
CLI0200 507
DBCHCL 54
DBCHWAT 54
Fetch Returned Data Length field 54
timing 54
Return Code field 149
relation to Message Text 123
Return Time field 154
HSISVC Time 169
SRBSCHED Time 174
TDPDBI Time 173
TDPDBO Time 172
TDPWAIT Time 171
TDPXMM Time 173
ReturnCode address
Connect function 247
DBCHCL 245
REW function. See Rewind function
Rewind function 62, 269
summary of uses 240
Route Description Codes field 156
Routine 239
DBCHCL 244
DBCHCLN 271
DBCHMEC 273
DBCHPEC 273
DBCHSAD 273
DBCHUEC 274
DBCHWAT 274
optional
summary of uses 273
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
parameters 241
summary of uses 240
RSUP function. See RunStartUp function
Run Length field 156
run pointer field 158
run_len 156
run_ptr 158
RunStartUp function 57, 250
summary of uses 240
S
Save Response Buffer
field
Variable Length Fetch 159
security considerations 29
Segment Data
option described 160
SELECT statement 38
sess_status 164
Session
establishing 55
terminating 64
Session control
Failure parcel 350
Session pool, 2PC 509
session status 164
Set Character Set 165
software releases
supported 3
SP Options parcel
described 489
SPB. See System Parameter Block
Spool file
Keep Response field 104
maintaining 341
Statement
INSERT 38
SELECT 38
Status session 164
stored procedures
described 497
Success parcel
indicator mode 347
System Parameter Block
HSHSPB 233
system parameter block
HSHSPB 33
T
TDP
relationship to Teradata Database 30
TDP command, issuing 260, 510
TDP Request Number field 169
TDP-receipt-timestamp 168
TDPXMM Time 173
Tell About Crash field
Wait Across Crash, relation to 202
tell about crash field 170
Teradata server
communicating with 33
Teradata SQL
response sequence 364
Teradata SQL statement
INSERT 38
SELECT 38
Time1 171
Time3 field 172
Time4 171
Time5 field 174
Total Length
field
DBCAIRX 219
DBCAREA 180
Total Size field, DBCAIRX 220
total_len 180
Transaction Semantics 180
Two Response Buffers field 183
Response Buffer Length field, relation 146
two_phase_commit 207
U
Use Presence Bits field 186
Using Data Length 191
Using Data Pointer 192, 195
Variable Length Request 200
Using Data Length 189
Use Presence Bits, relation to 187
Using Data Pointer 190
Use Presence Bits 187
V
Variable Length Fetch 196
Fetch Maximum Data Length 96
Variable Length Request 198
field
Request Mode 140
setting 51
Using Data Length 192
Using Data length 190, 194
version numbers 3
W
Wait Across Crash field 201
wait across crash field
tell about crash, relation to 170
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
533
Index
Wait For Response
field 164, 203
DBCHME 276
option 47
534
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems