teradata call-level interface version 2...this book provides information about teradata® call-level...
TRANSCRIPT
Teradata Call-Level InterfaceVersion 2
Reference for Channel-Attached Systems
Release 13.10B035-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: [email protected]
Any comments or materials (collectively referred to as “Feedback”) sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback.
Copyright © 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
PrefacePrerequisites
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 201013.10
Updated Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems to reflect Teradata products added and updated for Teradata Tools and Utilities Release 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
PrefaceChanges to This Book
August 200813.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.
Date and Release Description
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 5
PrefaceAdditional 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
Late information
Use the Release Definition for the following information:
• 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
1 Go to http://www.info.teradata.com.
2 Under Online Publications, click General Search.
3 In the Publication Product ID box, type 2029.
4 Click Search.
5 Select the appropriate Release Definition from the search results.
6 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
PrefaceAdditional 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 ReferenceB035-2416-mmyx
• IBM IMS/DC Interface for Teradata ReferenceB035-2447-mmyx
• IBM CICS Interface for Teradata ReferenceB035-2448-mmyx
• Teradata Tools and Utilities Installation Guide for IBM z/OSB035-2458-mmyx
• MessagesB035-1096-mmyx
• Teradata Tools and Utilities Command SummaryB035-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.
Type of Information Description Access to Information
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 7
PrefaceAdditional Information
General information about Teradata
The Teradata home page provides links to numerous sources of information about Teradata. Links include:
• Executive reports, case studies of customer experiences with Teradata, and thought leadership
• Technical information, solutions, and expert advice
• Press releases, mentions, and media resources
1 Go to Teradata.com.
2 Select a link.
Type of Information Description Access to Information
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Executing Programs in Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Parallel Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Multi-Statement Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Multi-Request Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Multi-Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
DBCHCL FET Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
DBCHCL ERQ Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
DBCHCL REW Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
DBCHCL DSC Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
DBCHCLN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Chapter 7: Other CLIv2 Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Uses of CLIv2 Routines: Tabular Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Parameters of CLIv2 Routines: Tabular Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
DBCHME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
DBCHMEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
DBCHPEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
DBCHSAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
DBCHUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
DBCHUEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
DBCHWAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
DBCHWL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Chapter 8: CLIv2 Query Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
DBCHQE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Available-logon-mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
CLIv2-limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
SQL-limits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Integer/decimal-enlargement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Result-sets-support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
QueryBand-support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Merge-into-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Logging-errors-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Procedure-data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Utility-session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Transforms-off-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Transforms-request-support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
CHARSET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
END. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
UNICODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
SizeEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
SizeStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
StatementInformation Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
StatementInformationEnd Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Success. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
TitleEnd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
TitleStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
With. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
CursorDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
CursorHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
DataInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
DataInfoX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
EndMultipartData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
EndMultipartIndicData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
FMReq. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
IndicData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
IndicReq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
MultipartData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
MultipartIndicData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
MultipartRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Req. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
SP Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
StatementInformation Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
StatementInformationEnd Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 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: IntroductionLogical 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: IntroductionLogical Structure
Figure 1: CLIv2: Logical Structure
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.
ApplicationProgram
CLIv2Stub
CLIv2Runtime
TDP
TeradataDatabase
Requests Responses
2414A025
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 31
Chapter 1: IntroductionData 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
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.
DBCAREA
2417A008
CLIv2Runtime
Application
CLIv2Stub
HSHSPBDBCAREAExtensions
User-DefinedCharacter
Sets
MessageDefinitions
32 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: IntroductionCommunicating 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: IntroductionCommunicating 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) in-doubt 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 two-statement 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: IntroductionCommunicating 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
REAL
DOUBLE PRECISION
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)
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: IntroductionCommunicating with the Teradata Database
VARCHAR (n)
(actual length k,
where 0 <= k <= n )
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)
(actual length k,
where 0 <= k <= n )
16-bit SMALLINT (2 bytes), actual count k, followed by k bytes (total of k+2 bytes)
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:
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.
Table 1: Teradata SQL Data Type and Mainframe Internal Format (continued)
Teradata SQL Data Type Mainframe Internal Format
year 1900–( ) 10000× month 100×( ) day+ +
36 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: IntroductionCommunicating with the Teradata Database
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.
PERIOD (TIME WITH TIMEZONE)
Two 8-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.
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 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.
Table 1: Teradata SQL Data Type and Mainframe Internal Format (continued)
Teradata SQL Data Type Mainframe Internal Format
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: IntroductionCommunicating with the Teradata Database
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.
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=Yand 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.
Specified Option Result
38 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: IntroductionCommunicating with the Teradata Database
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
Action Result
If the first statement is completed The money would vanish
If the second statement is completed The money would be counted twice
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 39
Chapter 1: IntroductionParallel 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: IntroductionParallel 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: IntroductionParallel 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.
Language Location of Sample on the Release Tape
IBM Assembler EX2
COBOL CLI2MCB
PL/I CLI2MPB
42 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 1: IntroductionMulti-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: IntroductionCommon 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 • 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.
DBCHCLN Cleans up after an application is finished using Teradata Database.
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: IntroductionCommon 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: IntroductionCommon 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 OperationsSetting 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).
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.
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.
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.
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.
48 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session OperationsSetting 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 OperationsSetting 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 OperationsSetting 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
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.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 51
Chapter 2: Session OperationsSetting 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 areaLM R0,R1,areaSR R15,R15IC R15,DBCITSPSRDL R0,12(R15)ST R1,DBCTIMEn
52 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session OperationsReturn 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 OperationsReturn 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 OperationsExplicitly 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 OperationsExplicitly 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.
• 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:
56 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session OperationsExecuting a RunStartUp Request
4 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.
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.
C 0 Process parcels from Teradata Database.
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 An abnormal situation occurred. Use the Fetch function (“Fetching the Response for a Request” on page 60) to process.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 57
Chapter 2: Session OperationsExecuting a RunStartUp Request
To run a startup string once the session is established, an application must perform the following steps:
1 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)
2 Call DBCHCL to perform the RunStartUp function, then checks the return code from DBCHCL:
3 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.
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.
58 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session OperationsSubmitting 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 OperationsFetching 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 Process the return code and DBCAREA message.
60 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session OperationsContinuing 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:
• Fetch Buffer Length field
• Message Area Pointer field
• Message Area Length field
g 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 OperationsRewinding 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.
To rewind to the start of the response once the session has been established, an application must performs the following steps:
1 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:
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.
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.
62 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 2: Session OperationsEnding 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:
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 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
2 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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 63
Chapter 2: Session OperationsTerminating a Session
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.
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
2 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.
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.
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 OperationsExamples
Multiple Sessions
Each horizontal item that follows represents a call to DBCHCL with the function code set as in the left column.
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
Function Description
Function Description
Connect/Fetch Same as for a single session
Initiate Request
(Session 1)
Send Teradata SQL request to the Teradata Database.
Application must set address and length of Teradata SQL request and optional using data. Application must save the Output CLIv2 Request Id.
Initiate Request
(Session 2)
Same as for session 1, probably with different data
Fetch
(Session 1 and 2)
Same as for a single session
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 OperationsImplicitly Establishing a 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.
Disconnect
(for each session)
Log off from the Teradata Database and free the session-related control blocks
Function Description
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: DBCAREAField Descriptions
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.
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
Table 2: Order of the DBCAREA
Byte Offset (in decimal) 000 001 002 003
000 Eyecatcher, 8 bytes
004
008 Total Length, 4 bytes
012 Function, 4 bytes
016 Input CLIv2 Connection Id, 4 bytes
020 Input CLIv2 Request Id, 4 bytes
68 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAField Descriptions
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 Output TDP Session Id, 4 bytes
064 Output Host Id, 2 bytes Session Status, 1 byte
Unused, 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
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
Table 2: Order of the DBCAREA (continued)
Byte Offset (in decimal) 000 001 002 003
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 69
Chapter 3: DBCAREAField Descriptions
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
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 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 LengthRequest, 1 byte
Variable LengthFetch, 1 byte
Save ResponseBuffer, 1 byte
Two Response,Buffers, 1 byte
228 Return Time,1 byte
Parcel Mode Fetch,1 byte
Wait for Response,1 byte
Request ProcessingOption, 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
Table 2: Order of the DBCAREA (continued)
Byte Offset (in decimal) 000 001 002 003
70 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAField Descriptions
240 Unused, 2 byte 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 C2S Conversion,1byte
S2C Conversion, 1 byte
Date Form,1 byte
MaximumParcel, 1 byte
344 Language Id, 2 bytes Country Id, 2 bytes
348 Segment Data, 1byte Return-objects-as, 1 byte
Continued-data,1 bytes
Data-encryption, 1 byte
352 Request-parcel-format, 1 byte
Statement-status, 1 byte
Continued-characters-state,
1 byte
APH-response-OK, 1 byte
356 Return-statement-info
Return-identity-data
Positioning-statement-number, 2 bytes
360 Positioning-value, 8 bytes
364
368 Positioning-action, 2 bytes Timing-precision, 2 bytes
372 Level, 1 byte Message Charset Used, 1 byte
Message Return Code, 2 bytes
376 Message Length, 2 bytes Message Area Length, 2 bytes
380 Message Area Pointer, 4 bytes
Table 2: Order of the DBCAREA (continued)
Byte Offset (in decimal) 000 001 002 003
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 71
Chapter 3: DBCAREAField 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 Mechanism-data-encoding, 1byte
Result-sets-OK,1 byte
Return-result-sets-to, 1 byte
Delegate-user-identity, 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
Period-as-Struct1 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 Trusted-request1 byte
Column-info1 byte
Utility-workload1 byte
Unused 1 byte
616 Unused, 20 bytes
72 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAAnticipated Number of Concurrent Sessions
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.
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
636 Unused, 3 bytes Refresh-cached-data, 4 bytes
Table 3: Order of the Enlarged DBCAREA When Level > 0 (continued)
Byte Offset (in decimal) 000 001 002 003
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 73
Chapter 3: DBCAREAAPH-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.
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'
74 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAChange 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.
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:
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 75
Chapter 3: DBCAREAChange Options
1 Set Change Options to ‘Y‘.
2 Change the value for <option> as follows.
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‘.
If the application requires... Then set <option> to...
<desired condition> <option that specifies the desired condition>
Table 4: Change Options Scanning
Function
Options Scanned Conn
ect
RunS
tartU
p
Initi
ate R
eque
st
Initi
ate W
ithin
Pr
otoc
ol-F
unct
ion
Com
man
d
Cont
inue
-requ
est
Rewi
nd
End
Requ
est
Abor
t
Disc
onne
ct
Fetc
h
Anticipated Num Sessions no yes* yes* yes* yes no 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 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAChange Options
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
Table 4: Change Options Scanning (continued)
Function
Options Scanned Conn
ect
RunS
tartU
p
Initi
ate R
eque
st
Initi
ate W
ithin
Pr
otoc
ol-F
unct
ion
Com
man
d
Cont
inue
-requ
est
Rewi
nd
End
Requ
est
Abor
t
Disc
onne
ct
Fetc
h
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 77
Chapter 3: DBCAREACharacter Set Pointer
* 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:
• “EBCDIC” on page 375
• “EBCDIC037_0E” on page 377
• “EBCDIC273_0E” on page 378
• “EBCDIC277_0E” on page 379
• “HANGULEBCDIC933_1II” on page 380
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
Table 4: Change Options Scanning (continued)
Function
Options Scanned Conn
ect
RunS
tartU
p
Initi
ate R
eque
st
Initi
ate W
ithin
Pr
otoc
ol-F
unct
ion
Com
man
d
Cont
inue
-requ
est
Rewi
nd
End
Requ
est
Abor
t
Disc
onne
ct
Fetc
h
78 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREACharacter 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: DBCAREAColumn-info
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.
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
Language Variable Name for Character Set Pointer
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)
80 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAConnect Type
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.
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:
Column-info is used by... To...
applications write.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 81
Chapter 3: DBCAREAContinued-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‘.
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 locking-shifts (such as the Shift-out and Shift-in control characters).
One of the following values can be set before initiating a request:
If... Then set Connect Type to...
a separate logon and run should be sent to the Teradata Database
R
a combined logon and connect should be sent to the Teradata Database
C
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
82 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAContinued-data
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.
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'
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: DBCAREACountry Id
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.
DBCHCL reads.
CRQ
Continued-data is used by... To...
applications write
This routine... Takes this action for Continued-data...
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
84 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREACountry 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: DBCAREACurrent Request Buffer Length
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.
Romansh/Grishun (Switzerland) CH
Russian (Russian Federation) RU
Swedish (Sweden) SE
Thai (Thailand) TH
Turkish (Turkey) TR
Chinese (China) CN
Chinese (Taiwan) TW
If the language is... Then set Country Id to...
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)
86 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREACurrent Response Buffer Length
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.
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.
Current Request Buffer Length is used by... To...
applications read.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 87
Chapter 3: DBCAREAC2S Conversion
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:
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the DBCAREA.
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
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
88 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAData-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.
One of the following values may be set before calling the Fetch function:
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.
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
If... Then set Data-encryption to...
do not encrypt the data (default) N
encrypt the data Y
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 89
Chapter 3: DBCAREADate Form
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:
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.
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
If...
Then change the value for Date Form to...
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
90 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREADelegate-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.
One of the following values can be set before initiating a request:
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 91
Chapter 3: DBCAREAExtension Pointer
Extension Pointer
Extension Pointer is a four-byte field that specifies the address of the first or only DBCAREA extension.
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.
If... Then set Connect Type to...
indicates that a new connection is established. 'N'
• DBCNIDIN for Assembler
• DBC_DelegateIdNo for C
• DBC-NO for COBOL
• DBC_DELEGATE_ID_NO for PL/I
indicates that the new connection's user identity is delegated to the Teradata Database for use by application there.
'Y'
• DBCNIDIY for Assembler
• DBC_DelegateIdYes for C
• DBC-YES for COBOL
• DBC_DELEGATE_ID_YES for PL/I
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
92 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAEyecatcher
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.
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.
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.
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
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 93
Chapter 3: DBCAREAFetch Data Pointer
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
In Move Mode, only the number of bytes that constitute the length are affected in the move area. The bytes beyond are unaffected.
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.
The following table explains how Fetch Data Pointer works in Locate Mode (Locate Mode = ‘Y‘) when DBCHCL is called for the following functions:
• Connect
• RunStartUp
This routine... Does this for Fetch Data Pointer in Move Mode...
DBCHINI writes
DBCHCL reads (FET)
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, Fetch Data Pointer is used by... To...
applications write (FET)
This routine... Does this for Fetch Data Pointer in Locate Mode...
DBCHINI writes
DBCHCL writes (FET)
94 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAFetch Maximum Data Length
• Initiate with Protocol-Function
• Command
• Initiate Request.
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.
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)
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: DBCAREAFetch Parcel Flavor
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.
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.
Fetch Maximum Data Length is used by... To...
applications write
If Maximum Data Length is set to... Then the largest parcel body is...
O 32763
H 2,147,483,639
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
96 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAFetch Returned Data Length
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.
DBCHCL writes (FET)
Fetch Parcel Flavor is used by... To...
applications read
This routine... Does this for Fetch Parcel Flavor...
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: DBCAREAFunction
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.
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:
Fetch Returned Data Length is used by... To...
applications read
Table 5: Length of Returned Data
Locate Mode
Parcel Mode Fetch
Variable Length 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.
Code Operation
1 Connect
2 Disconnect
98 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAFunction
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.
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
Code Operation
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 99
Chapter 3: DBCAREAInput 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.
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.
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
100 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAInput TDP Path
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 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
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: DBCAREAKeep Response
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.
This routine... Does this for Input TDP Path...
DBCHINI writes
DBCHCL reads (CON)
CON
Input TDP Path is used by... To...
applications write
In this language... The variable name for Keep Response is...
COBOL DBCAREA-KEEP-RESP
PL/I KEEP_RESP
C keep_resp
102 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAKeep Response
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.
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
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.
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
In this language... The variable name for Keep Response is...
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 103
Chapter 3: DBCAREALanguage 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.
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.
1 Set Change Options to ‘Y‘.
2 Change the value for Language Conformance as follows.
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.
104 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREALanguage Id
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.
If conformance checking is to be done at this level...
Then change the value for Language Conformance to...
None
This is always acceptable.
N
Entry-level ANSI (FIPS 127-2).
If the Teradata Database does not support language conformance, it rejects this selection.
2
Intermediate-level ANSI (FIPS 127-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.
3
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: DBCAREALanguage Id
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:
1 Set Change Options to ‘Y‘.
2 Change the value for Language Id as follows:
Language Id is used by... To...
applications write
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
106 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREALevel
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: DBCAREALocate Mode
Locate Mode
Locate Mode is a one-byte field that specifies where the data returned is to be made available.
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.
Use mnemonics for the codes. Mnemonics are provided in the language definition file for the DBCAREA.
Within this manual, the following conventions apply:
• Locate Mode of Y is known as Locate Mode.
• Locate Mode of N with Parcel Mode Fetch of Y is known as Move Mode.
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.
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
108 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREALogon 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.
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 109
Chapter 3: DBCAREALogon 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:
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.
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.
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.
110 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREALogon 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: DBCAREALogon Pointer
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.
‘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.
Syntax element... Is the ...
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').
Any TDP identifier and all delimiters (slash, commas, blanks, quotation marks, apostrophes) must be specified as single-byte characters.
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.
HANGUL949_7R0, HANGULKSC5601_2R4, KANJI932_1S0, KANJISJIS_0S, SCHGB2312_1T0, SCHINESE936_6R0, TCHBIG5_1R0, or TCHINESE950_8R0
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.
112 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAMax-decimal-returned
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.
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-decimal-returned is ignored.
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.
Session Character Set Specification
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.
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: DBCAREAMaximum Parcel
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.
Routine. Action for Max-decimal-returned
DBCHINI writes
DBCHCL reads (RSUP; IRQ; IWPF)
Max-decimal-returned is used by... To...
applications write.
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.
114 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAMechanism-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:
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.
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
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: DBCAREAMechanism-data-len
One of the following numeric values can be set before establishing a connection:
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 Total-length 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.
This routine... Does this for Mechanism-data-encoding...
DBCHINI writes
DBCHCL reads (CON)
Mechanism-data-encoding is used by... To...
applications write
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 Mechanism-data-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 Mechanism-data-ptr requires two bytes.
116 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAMechanism-data-ptr
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 Total-length 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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 117
Chapter 3: DBCAREAMechanism-name
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 Total-length 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.
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
In this language... The variable name for Mechanism-name is...
COBOL MECHANISM-NAME
PL/I MECHANISM_NAME
C mechanismName
IBM Assembler DBCNIMNM
118 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAMessage Area Length
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.
If the Message Area Pointer is not specified, this value is ignored.
This routine... Does this for Mechanism-name...
DBCHINI writes
DBCHCL reads (CON)
Mechanism-name is used by... To...
applications write
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 119
Chapter 3: DBCAREAMessage 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.
An error message is returned when a CLIv2 routine that uses the DBCAREA ends with a non-zero 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.
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
120 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAMessage 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.
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 121
Chapter 3: DBCAREAMessage Return Code
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.
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
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
122 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAMessage Text Length
Message Text Length
Message Text Length is a two-byte field that is the length in bytes of a message in Message Text.
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
Message Return Code is used by... To...
applications read
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
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: DBCAREAOpen Requests
An error message is returned when a CLIv2 routine that uses the DBCAREA ends with a non-zero 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.
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
In this language... The variable name for Message Text is...
124 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAOpen Requests
Open Requests Calculations
DBCHCL calculates the value of Open Requests as follows:
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.
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 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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 125
Chapter 3: DBCAREAOutput 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.
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.
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
126 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAOutput 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.
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 127
Chapter 3: DBCAREAOutput 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.
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.
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.
In this language... The variable name for Output TDP Path is...
COBOL DBCAREA-O-DBCPATH
PL/I O_DBCPATH
128 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAOutput TDP Session Id
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.
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
In this language... The variable name for Output TDP Path is...
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: DBCAREAParcel Mode Fetch
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.
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).
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
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
130 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAPeriod-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:
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.
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
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: DBCAREAPositioning-action
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.
This routine... Does this for Period-as-Struct...
DBCHINI writes.
DBCHCL reads (RSUP; IRQ; IWPF)
Period-as-Struct is used by... To...
applications write.
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: DBCAREAPositioning-statement-number
One of the following values may be set before calling the Fetch function:
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.
Positioning-action is used by... To...
applications write.
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 Positioning-statement-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
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: DBCAREAPositioning-value
Use of this setting does not require use of Change-option. That is, honoring Positioning-statement-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 Positioning-action 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.
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
In this language... The variable name for Positioning-statement-number is...
In this language... The variable name for Positioning-value is...
COBOL DBFIPVAL
PL/I DBFIPVAL
C dbfiPVal
IBM Assembler DBFIPVAL
134 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAProtocol-Function
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)
You can set the following in IWPF:
This routine... Does this for Positioning-value...
DBCHINI writes
DBCHCL reads (FET)
Positioning-value is used by... To...
applications write
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 135
Chapter 3: DBCAREARefresh-cached-data
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 re-used or must be reread from the Teradata Database.
Refresh-cached-data 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, Refresh-cached-data is ignored.
One of the following values may be set before initiating a request:
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'
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
136 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREARequest Buffer Length
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.
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.
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'
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 137
Chapter 3: DBCAREARequest 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.
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
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.
138 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREARequest 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.
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.
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.
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: DBCAREARequest-parcel-format
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.
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.
Request Mode is used by To...
applications write
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
140 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREARequest-parcel-format
The following table describes the Request-parcel-format variable.
Set one of the following values before calling the Fetch function:
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.
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
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 141
Chapter 3: DBCAREARequest Pointer
Request Pointer
Request Pointer is a four byte field that specifies the address of the request string.
Before calling DBCHCL for the Initiate Request function, the application must build a request string, such as a Teradata SQL request.
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.
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
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).
142 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREARequest 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.
Request Processing Option is initialized by DBCHINI to the default value provided for Request Processing Option in the HSHSPB.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 143
Chapter 3: DBCAREARequest 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:
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.
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.
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.
P
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
144 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREARequest-token
Request-token
Request-token is a four byte field that is used to specify a user-defined identifier for the request.
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 145
Chapter 3: DBCAREAResponse Mode
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 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.
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 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.
146 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAResponse Mode
When MultipartIndicator Response-mode is selected, the Continued-characters-state option is also be relevant.
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.
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
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: DBCAREAResult-sets-OK
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 Total-length 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.
One of the following values may be set before initiating a request:
MultipartIndicator M
Indicator I
If the response is to be packaged in this mode...Then change the value for Response Mode to...
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
148 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAReturn Code
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.
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
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: DBCAREAReturn-identity-data
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.
DBCHCL writes
Return Code is used by... To...
applications read
This routine... Does this for Return Code...
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)
150 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAReturn-objects-as
One of the following values may be set before initiating a request:
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.
Return-objects-as is initialized to the default value provided in the site's HSHSPB.
Return-identity-data is used by... To...
applications write
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 151
Chapter 3: DBCAREAReturn-statement-info
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).
One of the following values may be set before initiating a request:
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'
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
152 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAReturn-result-to
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 Total-length 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.
One of the following values may be set before initiating a request:
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 153
Chapter 3: DBCAREAReturn Time
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.
If... Then set Connect Type to...
indicates that the results are returned only the procedure making the request.
'1'
• DBRIRRR for Assembler
• DBC_RetnRsltRqstr for C
• RQSTR for COBOL
• DBC_RETN_RSLT_RQSTR for PL/I
indicates that the results are returned only to the application invoking a procedure.
'2'
• DBRIRRA for Assembler
• DBC_RetnRsltAppl for C
• APPL for COBOL
• DBC_RETN_RSLT_APPL for PL/I
indicates that the results are return only to the procedure caller.
'3'
• DBRIRRC for Assembler
• DBC_RetnRsltCaller for C
• CALLER for COBOL
• DBC_RETN_RSLT_CALLER for PL/I
indicates that the results are returned to both the requester and the application.
'4'
• DBRIRRRA for Assembler
• DBC_RetnRsltRqstrAppl for C
• RQSTR-APPL for COBOL
• DBC_RETN_RSLT_RQSTR_APPL for PL/I
indicates that the results are returned to both the requester and the caller.
'5'
• DBRIRRRC for Assembler
• DBC_RetnRsltRqstrCaller for C
• RQSTR-CALLER for COBOL
• DBC_RETN_RSLT_RQSTR_CALLER for PL/I
154 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAReturn Time
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.
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.
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
If time stamps are... Then change the value for Return Time to...
to be provided Y
not to be provided N
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 155
Chapter 3: DBCAREARoute 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.
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).
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
In this language... The variable name for Run Length is...
COBOL DBCAREA-RUN-LEN
PL/I RUN_LEN
C run_len
IBM Assembler DBCNIRSL
156 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREARun Length
The value of Run Length must be positive.
If the Connect Type is set to ‘C‘, a connect parcel will be built based on the value set in Run Length.
This routine... Does this for Run Length...
DBCHINI writes
DBCHCL reads (CON)
Run Length is used by... To...
applications write
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 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: DBCAREARun Pointer
Run Pointer
Run Pointer is a four byte field that specifies a particular set of services to be used by the session.
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.
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 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.
158 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREASave 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.
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 159
Chapter 3: DBCAREASegment Data
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.
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
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)
160 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREASession-desc-length
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:
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 Variable-length-request option is “Y”, Session-desc-length is ignored.
Use of Session-desc requires a Connect-type setting of “C”.
Segment Data is used by... To...
applications write
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 161
Chapter 3: DBCAREASession-desc-pointer
Session-desc-length 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, Session-desc-length is ignored.
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 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
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 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.
162 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREASession-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 Total-length 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.
The character string has no meaning beyond that determined by the application. Any non-graphic 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:
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 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: DBCAREASession 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.
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:
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.
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.
164 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREASet Character Set
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 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.
Cleanup needed
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.
In-Doubt
Set bit X‘10‘ to this... If a 2PC session is...
1 in doubt.
0 not in doubt.
Flag Name Description
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: DBCAREAStatement-status
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.
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
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)
166 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAS2C Conversion
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.
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'
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: DBCAREATDP-receipt-timestamp
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:
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.
S2C Conversion is used by... To...
applications write
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
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)
168 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREATDP Request Number
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.
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
HSISVC Time is used by . .. To...
applications read
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 169
Chapter 3: DBCAREATell 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
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.
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
170 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREATime1
Time1
Time1 is a four byte field that records when the request arrives at the TDP from CLIv2.
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 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
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: DBCAREATime3
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.
This routine... Does this for Time2...
DBCHINI writes
DBCHCL writes (FET)
Time2 is used by... To...
applications read
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
172 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREATime4
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.
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 173
Chapter 3: DBCAREATime5
Time5
Time5 is a four byte field that records when the response arrives in the CLIv2 response buffer.
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.
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.
In this language... The variable name for Time1-status is...
COBOL DBCOTSS1
174 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREATime2-status
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.
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 four-bytes.
Spaceorbinary zero
the timestamp is not valid.
In this language... The variable name for Time1-status is...
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: DBCAREATime3-status
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.
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 four-bytes.
Spaceorbinary zero
the timestamp is not valid.
In this language... The variable name for Time2-status is...
In this language... The variable name for Time3-status is...
COBOL DBCOTSS3
PL/I DBCOTSS3
C dbcoTSS3
IBM Assembler DBCOTSS3
176 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREATime4-status
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.
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.
Spaceorbinary zero
the timestamp is not valid.
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: DBCAREATime5-status
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.
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 four-bytes.
Spaceorbinary zero
the timestamp is not valid.
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
178 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREATiming-precision
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.
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.
If Time5-status is a... Then...
V the timestamp is valid.
O the timestamp overflowed. Could not be contained in four-bytes.
Spaceorbinary zero
the timestamp is not valid.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 179
Chapter 3: DBCAREATotal Length
Total Length
Total Length is a four byte field that specifies the length of the DBCAREA in bytes.
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.
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
In this language... The variable name for Transaction Semantics is...
COBOL DBCAREA-SEMANTICS
180 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREATransaction Semantics
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.
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
If the transaction semantics to be used for the application is ...Then change the value for Transaction Semantics to...
the Teradata Database default.
This value is always acceptable.
D
ANSI
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).
A
Teradata
This value is always acceptable.
T
In this language... The variable name for Transaction Semantics is...
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 181
Chapter 3: DBCAREATransforms-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.
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.
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
182 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREATwo Response Buffers
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 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
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: DBCAREATwo Response Buffers
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.
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.
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
If the response is to be... Then change the value for Two Response Buffers to...
double-buffered Y
single-buffered N
184 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAUse-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 Total-length 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.
One of the following values may be set before initiating a request:
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 185
Chapter 3: DBCAREAUse Presence Bits
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: Connect-type, Delegate-user-identity, input-TDP-pat, Logon-length, Logon-pointer, Mechanism-data-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.
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
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
186 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAUse Presence Bits
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.
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.
DBCHCL reads (CON; RSUP; IWPF; IRQ)
Use Presence Bits is used by... To...
applications write
If the data string has been prepared in this mode... Then change the value for Use Presence Bits to...
indicator (IndicData) Y
record N
This routine... Does this for Use Presence Bits...
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 187
Chapter 3: DBCAREAUsing-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 Total-length 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.
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:
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
188 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAUsing Data Length
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
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.
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: DBCAREAUsing Data Pointer
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:
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-data-count.
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
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
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
190 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAUsing Data Pointer
number of fields in the Teradata SQL USING row descriptor may be obtained using the DBCHQE SQL-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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 191
Chapter 3: DBCAREAUsing-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:
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 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.
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.
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..
192 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAUsing-data-pointer-vector
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.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 193
Chapter 3: DBCAREAUsing-data-pointer-vector
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:
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.
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
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.
194 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAUtility-workload
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 Utility-workload 'Y' is specified, Connect-type 'C' must also be specified.
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-pointer-vector.
• 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.
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: DBCAREAVariable 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.
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:
1 Set Change Options to ‘Y‘.
2 Change the value for Variable Length Fetch as follows.
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
196 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAVariable Length Fetch
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 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.
If the length information is to...Then change the value for Variable Length Fetch to...
precede immediately the string to which it applies
Y
be supplied separately from the string to which it applies
N
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‘.
parcel body
length
2417A006
parcel body
length
Fetch Returned Data Length
length
Fetch Data Pointer
Fetch Data Pointer
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 197
Chapter 3: DBCAREAVariable 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).
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.
The following figures show what the DBCAREA must contain in either of the above cases.
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
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
198 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAVariable Length Request
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.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 199
Chapter 3: DBCAREAVariable Length Request
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.
data
data
2417A007length
In DBCAREA:- Variable Length Request field (N)- Length field (value of length)- Pointer field
length
In DBCAREA:- Variable Length Request field (Y)- Pointer field
value oflength
200 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAWait 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.
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.
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
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: DBCAREAWait-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 Total-length 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
One of the following values may be set before initiating a request:
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
202 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAWait For Response
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.
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
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: DBCAREAWait 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.
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.
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
204 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREAWorkload-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 Variable-length-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 Total-length set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a smaller DBCAREA, Workload-length is ignored.
The value must be positive. The sum of this length and the length used for Session-desc-pointer must be less than or equal to one of the following values:
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.
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 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 205
Chapter 3: DBCAREAWorkload-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 Total-length set to at least 640 (that is, the returned DBCAREA Level value is at least 1). For a smaller DBCAREA, Workload-pointer is ignored.
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:
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 maximum value is approximately. . . If Maximum Parcel is set to...
32,725 O
206 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 3: DBCAREA2PC
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).
2PC can be set to either ‘Y‘ or ‘N‘.
64,493 H
2,147,483,602 H, and the Teradata Database supports ExtendedRespond, as indicated by the DBCHQE Extended-response-support query.
The maximum value is approximately. . . If Maximum Parcel is set to...
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 207
Chapter 3: DBCAREA2PC
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.
If the application... Then set 2PC to...
uses the 2PC protocol Y
does not use the 2PC protocol N
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 ExtensionsDBCAIRX
Figure 3: DBCAIRX Header Fields (Eyecatcher is ‘IRX8‘)
Deprecated Headers
Figure 4: Deprecated DBCAIRX Header Fields (Eyecatcher = ‘IRX‘)
Figure 5: Deprecated DBCAIRX Header Fields (Eyecatcher = ‘DBCX‘)
DBCAIRX Elements
Immediately following the header are one or more elements. Each element will either:
• Contain the actual data
• Address the actual data
bytes
2417A014
0
4
8
12
Eyecatcher, 4 bytes
Next Pointer, 4 bytes
Total Size, 4 bytes
16
20
Level, 1 bytes Unused, 3 bytes
Unused, 8 bytes
offset
2417A016
0
4
8
Eyecatcher, 4 bytes
Next Pointer, 4 bytes
Total Size, 4 bytes
offset
2417A015
0
4
8
Eyecatcher, 4 bytes
Next Pointer, 4 bytes
Total Length, 2 bytes Unused, 2 bytes
210 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCAIRX
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
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
Parcel Flavor, 2 bytes
Element Length, 2 bytes
Unused, 2 bytes
Element Type, 2 bytes
Data Size, 4 bytes
2417A023
0
4
8
12
16
20
24
28
offset
Unused, 4 bytes
Data Address, 4 bytes
Unused, 8 bytes
Unused, 8 bytes
Parcel Data (no mandatory length)
offset
2417A017
0 Element Type, 2 bytes Element Length, 2 bytes
4 Parcel Data (No Mandatory Length)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 211
Chapter 4: DBCAREA ExtensionsDBCAIRX
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
Figure 9: Deprecated DBCAIRX Element When Eyecatcher is 'IRX' or 'DBCX'
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.
Unused, 2 bytes
Element Type, 2 bytes
Data Address, 4 bytes
Element Length, 2 bytes
Unused, 4 bytes
2417A019
0
4
8
12
16
20
24
28
offset
Data Address (continued)
Unused (continued) Data Size, 4 bytes
Data Size (continued) Unused, 4 bytes
Unused, 8 bytes
Unused (continued)
offset
2417A018
0
Data Address(continued)
Data Length, 2 bytes
Element Type, 2 bytes
Data Address, 4 bytes
Element Length, 2 bytes
4
8
212 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCAIRX
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 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
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 ExtensionsDBCAIRX
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 symbolic name depends upon both the Eyecatcher and Level fields:
This routine... Does this for Data Length...
DBCHINI n/a
DBCHCL reads (IRQ; IWPF)
Data Length is used by... To...
applications write
The maximum value is... If Maximum Parcel is set to...
32763 O
65531 H
The variable name for Data Size is...
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)
214 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCAIRX
Element Length
Element Length contains the length of the individual element.
The symbolic name depends upon the Eyecatcher field.
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
Data Size is used by... To...
applications write
The maximum value is... If Maximum Parcel is set to...
32767 O
65535 H
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 215
Chapter 4: DBCAREA ExtensionsDBCAIRX
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:
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.
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
216 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCAIRX
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.
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
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 ExtensionsDBCAIRX
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 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.
Level is used by... To...
applications write
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
218 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCAIRX
Total Length
If ‘DBCX‘ was specified in Eyecatcher, Total Length specifies the length of one DBCAIRX in bytes.
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.
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)
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 219
Chapter 4: DBCAREA ExtensionsDBCACNX
Total Size
If ‘IRX8 or IRX‘ was specified in Eyecatcher, Total Size specifies the length of one DBCAIRX in bytes.
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.
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
220 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCACNX
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
When the Level field contains a value of '2', there is an additional header field as shown below:
New development should use only the level 2 form. The level 1 form is deprecated.
offset
2417A020
0
4
8
12
Eyecatcher, 4 bytes
Next Pointer, 4 bytes
Length, 4 bytes
Level, 1 byte Unused, 3 bytes
offset
2417A022
16
20
Unused, 8 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 221
Chapter 4: DBCAREA ExtensionsDBCACNX
Figure 11: DBCACNX Element Fields When Level = 2
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...
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)
Data Type, 2 bytes
Element Type, 2 bytesElement Length, 2 bytes
2417A021
0
4
8
12
16
20
24
16 or 28
offset
Data Length, 4 bytes
Data Pointer, 4 bytes
Data (no fixed length)
Unused, 2 bytes
Unused, 4 bytes(Level 2 only)
Unused, 8 bytes(Level 2 only)
222 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCACNX
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.
Data-type
Data-type is a two-byte unsigned integer field into which the type of data is placed.
Data-length is used by... To...
applications write
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
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 ExtensionsDBCACNX
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.
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 variable name for Element-length is...
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)
The variable name for Data-type is...
224 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCACNX
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 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.
Element-length is used by... To...
applications write
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 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 ExtensionsDBCACNX
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.
IBM Assembler D8XCID DBXCID
This routine... Does this for Eyecatcher. . .
DBCHINI n/a
DBCHCL reads (CON)
Eyecatcher is used by... To...
applications write
The variable name for Length is...
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
The variable name for Eyecatcher is...
226 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 4: DBCAREA ExtensionsDBCACNX
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 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 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 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 ExtensionsDBCACNX
This routine... Does this for Next-pointer...
DBCHINI n/a
DBCHCL reads (CON)
Next-pointer is used by... To...
applications write
228 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:
DBCAIRX
Definitions for DBCAREA extensions (DBCAIRX), provided for each program language, are located 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)
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 TapesFinding Files on the Release Tape
DBCACNX
Definitions for DBCACNX (DBCAREA Connect-extension), provided for each programming language, are located as shown below:
DBCHMEP
Definitions for DBCHMEP (DBCHME parameters), provided for each programming language, are located as shown below:
DBCHQEP
Definitions for DBCHQEP, provided for each program language, are located as shown below:
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).
For this language... Definitions for DBCAIRX are located in the. . .
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).
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).
For this language... Definitions for DBCHQEP are located in the. . .
IBM Assembler DBCHQEP in library SAMPLIB (z/OS).
230 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 5: Release TapesFinding Files on the Release Tape
DBCHQER
Definitions for DBCHQER (Query Results), provided for each programming language, are located as shown below:
DBCHUEP
Definitions for DBCHUEP (DBCHUE parameters), provided for each programming language, are located as shown below:
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.
C DBCHQEPH in library SAMPLIB (z/OS).
COBOL DBCHQEPC in library SAMPLIB (z/OS).
PL/I DBCHQEPP in library SAMPLIB (z/OS).
For this language... Definitions for DBCHQEP are located in the. . .
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).
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).
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 231
Chapter 5: Release TapesSystem Parameter Block
TRDSPB
Definitions for TRDSPB, provided in each programming language, are located as shown below:
TC2XPH
Definitions for TC2XPH, provided in each programming language, are located as shown below:
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.
For this language... Definitions for TRDSPB are located in the. . .
IBM Assembler TRDSPB in library SAMPLIB (z/OS).
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).
232 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 5: Release TapesHSHSPB
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.
In this programming environment...
The name for the data structure containing default values to pass to DBCHINI is... Description
z/OS batch
z/OS TSO
IMS/DC
CICS/VS
HSHSPB The accessible default for applications running in the named environments.
CICS HSHSPBC A block containing information to manage globally CLIv2 memory usage.
Used only under CICS.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 233
Chapter 5: Release TapesHSHSPB Assembler Source
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:
Under this operating system...
The application can include HSHSPB at... If HSHSPB is...
z/OS link time in STEPLIB/JOBLIB/LINKLIST
Table 6: HSHSPB Source Default Settings That Are Safe to Change
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.
234 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 5: Release TapesHSHSPB Assembler Source
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.
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'.
RCD
'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'.
Table 6: HSHSPB Source Default Settings That Are Safe to Change (continued)
Keyword Default Description
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 235
Chapter 5: Release TapesHSHSPB Assembler Source
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:
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
IBOS2CC
'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'.
236 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 5: Release TapesHSHSPB 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 TapesHSHSPB 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 RoutinesUses 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.
DBCHCL 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.
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
DBCHCLN 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
240 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesSummary 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 RoutinesDBCHINI
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:
Usage Notes
• 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.
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.
242 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHINI
• 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 RoutinesDBCHCL
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:
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.
244 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL
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 RoutinesDBCHCL Functions
DBCHCL Functions
This section describes the DBCHCL functions listed below.
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.
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
246 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL 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 RoutinesDBCHCL CON Function
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.
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
248 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL 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 RoutinesDBCHCL 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
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
250 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL RSUP Function
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.
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
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
Table 16: DBCAREA Output Fields Optional for the RunStartup Function (continued)
DBCAREA Output Fields Optional for the RunStartup Function
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 251
Chapter 6: Common RoutinesDBCHCL 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
Anticipated Number of Concurrent Sessions APH-response-OK
Change Options Character Set
C2S Conversion Column-info
Continued-character-state Data-encryption
252 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL IRQ Function
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.
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 always set by the Initiate Request Function
Current Response Buffer Length Message Return Code
Message Text Message Text Length
Table 20: DBCAREA Input Fields Optional for the Initiate Request Function (continued)
DBCAREA Input Fields Optional for the Initiate Request Function
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 253
Chapter 6: Common RoutinesDBCHCL IRQ 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
DBCAREA Output Fields always set by the Initiate Request Function
254 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL 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:
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.
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.
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 RoutinesDBCHCL 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 RoutinesDBCHCL 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 RoutinesDBCHCL 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.
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.
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
258 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL CRQ Function
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 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
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 Current Response Buffer Length
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 259
Chapter 6: Common RoutinesDBCHCL 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 RoutinesDBCHCL CMD Function
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 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
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 Open Requests
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 261
Chapter 6: Common RoutinesDBCHCL CMD Function
TDP Request Number
Table 32: DBCAREA Output Fields set by Successful Command Functions (continued)
DBCAREA Output Fields set by Successful Command Functions
262 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL 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 Output Fields
Upon completion of the Abort function, CLIv2 will always set DBCAREA fields in the table.
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 263
Chapter 6: Common RoutinesDBCHCL 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 RoutinesDBCHCL 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 RoutinesDBCHCL 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 RoutinesDBCHCL 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.
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 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
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 RoutinesDBCHCL ERQ Function
Table 38: DBCAREA Output Fields Set by Successful EndRequest Functions
DBCAREA Output Fields Set by Successful EndRequest Functions
Open Requests Message Return Code
268 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCL 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 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 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 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 RoutinesDBCHCL 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 Output Fields
Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the table.
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 always set by the Disconnect Function
Message Return Code Message Lenth
Message Text Message Text Lenth
270 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 6: Common RoutinesDBCHCLN
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:
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.
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 271
Chapter 6: Common RoutinesDBCHCLN
• The call to DBCHCLN does not deallocate the DBCAREA.
The application may itself deallocate the DBCAREA if the programming language provides that ability.
• Termination of the application has the same effect as DBCHCLN, but it is good programming practice to call DBCHCLN for cleanup.
272 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
DBCHMEC What A deprecated routine now replaced by DBCHME.
Why For the convenience of the application
DBCHPEC 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
DBCHSAD What Stores specified value at specified address
Why To provide pointer support in languages that do not support pointer manipulation
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 273
Chapter 7: Other CLIv2 RoutinesParameters of CLIv2 Routines: Tabular Summary
Parameters of CLIv2 Routines: Tabular Summary
Table 40 lists the parameters for the routines described in this chapter.
DBCHUE
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)
DBCHUEC 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)
DBCHWAT What Waits for event to occur (an event refers to the arrival of some response from the Teradata Database)
If DBCHUE has been invoked, an event also refers to the occurrence of some application-defined event
Why To provide a mechanism for explicit waits for events; also simplifies handling of concurrent sessions
DBCHWL What Waits for one of a list of events to occur.
Why To provide a mechanism to explicitly wait for only some events.
Table 39: Uses of CLIv2 Routines (continued)
Routine Description
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 RoutinesParameters of CLIv2 Routines: Tabular Summary
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
Table 40: Parameters of CLIv2 Routines (continued)
Routines Parameters
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 275
Chapter 7: Other CLIv2 RoutinesDBCHME
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:
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.
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.
276 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 RoutinesDBCHME
The MEPFUNC Field
In the MEPFUNC field, the following are valid function codes:
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.
Function Code NameMnemonic 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 RoutinesDBCHMEC
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:
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.
278 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 RoutinesDBCHPEC
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:
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.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 279
Chapter 7: Other CLIv2 RoutinesDBCHSAD
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:
Usage Notes
DBCHSAD is intended for use in COBOL and other languages that do not support pointer manipulation.
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.
280 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 RoutinesDBCHUE
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:
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.
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)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 281
Chapter 7: Other CLIv2 RoutinesDBCHUE
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.
The UEPFUNC Field
In the UEPFUNC field, the following are valid function codes:
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.
Function Code Name
Mnemonic for All Languages, Including C Description
1 Define UEPFDEF Define a user event.
2 Delete UEPFDEL Delete a user event.
282 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 RoutinesDBCHUEC
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:
Usage Notes
The user ECB may be cancelled by specifying a User ECB address of binary zeroes.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 283
Chapter 7: Other CLIv2 RoutinesDBCHWAT
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:
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.
• If DBCHUE has been used to provide a User-event, its completion is reflected before the arrival of any response.
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.
284 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 RoutinesDBCHWAT
• 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 RoutinesDBCHWL
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:
Usage Notes
• 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.
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.
286 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 7: Other CLIv2 RoutinesDBCHWL
• 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 longer-running 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 RoutinesDBCHWL
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 RoutineDBCHQE
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.
DBCHQEP The DBCHQEP structure.
... Zero or more additional DBCHQEP structures.
Argument Content
Field Name Offset Length Description
QEPLEVEL
(qepLevel)
00 1 Unsigned numeric format of the parameter list.
Must be set to 4.
QEPITEM
(qepItem)
01 1 Unsigned numeric item to be queried.
Valid item codes and their descriptions are listed in the table following this table.
QEPTLEN
(qepTLen)
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 RoutineDBCHQE
QEPTIDP
(qepTIDP)
04 4 Pointer to an area containing the TDP identifier, if one is provided.
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
(qepConn)
04 4 Unsigned numeric CLIv2 connection number, if required.
QEPFILL1 08 3 Not used.
Must be set to 0.
QEPVRF
(varyingResultFmt for C; VARYING-RESULT-FMT for COBOL; VARYING_RESULT_FMT for PL/I))
11 1 Varying-result-format must be one of the following:
• 0, the default, or just characters as an unsigned 1-byte integer that specifies the format of variable-length 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).
QEPRALEN
(qepRALen)
12 2 Unsigned numeric length of the area in which the result of the query is returned.
QEPRDLEN
(qepRDLen)
14 2 Unsigned numeric length of the data returned.
Set to the length of the data returned (up to the size of the area as specified by the QEPRALEN field).
QEPRAP
(qepRAP)
16 4 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.
Field Name Offset Length Description
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 291
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
Field Name Offset Length Description
292 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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
(qepMsgCS)
24 4 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
(qepMsgP)
28 4 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
(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.
QEPRMLEN
(qepRMLen)
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.
QEPRMRC
(qepRMRC)
36 2 Unsigned numeric CLIv2 return code for any error that occurred while constructing the message. If no error occurred, binary zeroes are returned.
Field Name Offset Length Description
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 293
Chapter 8: CLIv2 Query RoutineDBCHQE
QEPITEM Field
In the QEPITEM field, the following are valid item codes:
QEPRC
(qepRC)
38 2 Unsigned numeric CLIv2 return code that occurred while processing this DBCHQEP. If no error occurred, binary zeroes are returned.
QEPTIDP8
(qepTIdP8)
40 8 Reserved, must be binary zeroes.
QEPRAP8
(qepRAP8)
48 8 Reserved, must be binary zeroes.
QEPMCSP8
(qepMCSP8)
56 8 Reserved, must be binary zeroes.
QEPMSGP8
(qepMsgP8)
64 8 Reserved, must be binary zeroes.
QEPRQST
(qepRqst)
72 4 Unsigned numeric CLIv2 request number, if required.
QEPTOKEN
(qepToken)
76 4 Binary token, initially zero, thereafter as returned by the previous incomplete query Available-character-sets request
Field Name Offset Length Description
Table 41: QEPITEM Field Valid Item Codes
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
294 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
Table 41: QEPITEM Field Valid Item Codes (continued)
Item Code Name Description
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 295
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
Table 41: QEPITEM Field Valid Item Codes (continued)
Item Code Name Description
296 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
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.
Table 41: QEPITEM Field Valid Item Codes (continued)
Item Code Name Description
Item Code Mnemonic
Response DBQERIID (DbqerIid for C)
Field Value
1 QEPIIID QERIID ('id' for C)
Forty EBCDIC characters, left-justified and padded on the right with blanks.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 297
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
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.
Item Code Mnemonic
Response DBQERTSM (DbqerTSm for C)
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)
Item Code Mnemonic
Response DBQERLCS (DbqerLCS for C)
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)
298 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERUCR (DbqerUCr for C)
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)
Item Code Mnemonic
Response DBQERRFI (DbqerRfI for C)
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)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 299
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERDTS (DbqerDTS for C)
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)
Item Code Mnemonic
Response DBQEREPS (DbqerEPS for C)
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)
300 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERC2R (DbqerC2R for C)
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.
Item Code Mnemonic
Response DBQERSPF (DbqerSPF for C)
Field Value
10 QEPISPF QERSPF ('factor' for C)
A four-byte unsigned integer.
Item Code Mnemonic
Response DBQERMSS (DbqerMSS for C)
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 RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERTDR (DbqerTDR for C)
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 one-character 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.
302 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERSSO (DbqerSSo for C)
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)
Item Code Mnemonic
Response DBQERSUI (DbqerSUi for C)
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 303
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERUPS (DbqerUps for C)
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)
Item Code Mnemonic
Response DBQERAOP (DbqerAOp fo C)
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)
304 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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
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.
Item Code Mnemonic
Response DBQERMRI (DbqerMrI for C)
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)
Item Code Mnemonic
Response DBQERLOB (DbqerLOb for C)
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)
Item Code Mnemonic
Response DBQERTPR (DbqerTPR for C)
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 RoutineDBCHQE
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
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
QERTPRMX ('maximum' for C)
A two-byte signed integer containing the maximum value.
Item Code Mnemonic
Response DBQERTPR (DbqerTPR for C)
Fields Value
Item Code Mnemonic
Response DBQERERS (DbqerERs for C)
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)
306 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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
Item Code Mnemonic
Response DBQEREPH (DbqerEPH for C)
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, 71-72, 85, 102, 115-118, 120, 128-129, 140-143, 146-148, 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
Item Code Mnemonic
Response DBQERTMT (DbqerTmT for C)
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 RoutineDBCHQE
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.
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
Item Code Mnemonic
Response DBQERUD (DbqerUD for C)
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, WORKLOAD-STATUS for COBOL, WORKLOAD_STATUS for PL/I)
One of the following EBCDIC characters:
"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)
QERUDEU(exportUsage for C, EXPORT-USAGE for COBOL, EXPORT_USAGE for PL/I)
A two-byte unsigned integer containing either:
'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)
308 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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).
Item Code Mnemonic
Response DBQERASL(DbqerASL for C)
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 RoutineDBCHQE
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)
Item Code Mnemonic
Response DBQERASL(DbqerASL for C)
Field Value
310 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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)
Item Code Mnemonic
Response DBQERASL(DbqerASL for C)
Field Value
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 311
Chapter 8: CLIv2 Query RoutineDBCHQE
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_SUPPORTEDfor PL/I)
'Y' is QERSISY (QER_Supported for C, SUPPORTED for COBOL, QER_SUPPORTED for PL/I
Item Code Mnemonic
Response DBQERASL(DbqerASL for C)
Field Value
312 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
QERASLID (integerDecimalStatus for C,INTEGE-DECIMAL-STATUS for COBOL,INTEGER-DECIMAL_STATUSfor 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_STATUSfor 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)
QERASLRSresultSetsStatus 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)
Item Code Mnemonic
Response DBQERASL(DbqerASL for C)
Field Value
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 313
Chapter 8: CLIv2 Query RoutineDBCHQE
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_MERGE for PL/I)
Item Code Mnemonic
Response DBQERASL(DbqerASL for C)
Field Value
314 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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)
Item Code Mnemonic
Response DBQERASL(DbqerASL for C)
Field Value
Item Code Mnemonic
Response DBQERRPO (DbqerRPo for C)
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 RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERDEN (DbqerDEN for C)
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)
Item Code Mnemonic
Response QEPIRMR (DbqerRMR for C)
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 RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response QEPIRMR (DbqerRMR for C)
Field Value
Item Code Mnemonic
Response DBQERACS (DbqerACS for C)
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 RoutineDBCHQE
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.
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.
APH-response
There is no known use for the APH-response query.
Item Code Mnemonic
Response DBQERES (DbqerES for C)
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.
Item Code Mnemonic
Response DBQERUT (DbqerUT for C)
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)
318 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERAPH (DbqerAPH for C)
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
Item Code Mnemonic
Response DBQERALM (DbqerALM for C)
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 RoutineDBCHQE
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
QERALMNR(entriesRemaining for C, ENTRIES-REMAININGfor 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.
Item Code Mnemonic
Response DBQERALM (DbqerALM for C)
Field Value
320 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
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.
Item Code Mnemonic
DBQERDCS (DbqerDCS for C)
Field Value
33 QEPIDCS QERDCS ('name' for C, COBOL, and PL/I)
Thirty EBCDIC characters, left-justified, padded on the right with spaces.
Item Code Mnemonic
Response DBQERDBR (DbqerDBR for C)
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, left-justified and padded with spaces as necessary.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 321
Chapter 8: CLIv2 Query RoutineDBCHQE
Returns limits for the Teradata Database affecting an application's values for CLIv2 settings. The response consists of four fields totalling thirty-two bytes.
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.
Item Code Mnemonic
DBQERC2L (DbqerC2L for C)
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.
322 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
Item Code Mnemonic
DBQERSQL (DbqerSQL for C)
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 four-byte 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 RoutineDBCHQE
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.
Item Code Mnemonic
DBQERSQL (DbqerSQL for C)
Fields Value
324 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
QERSQLC ('charCharlen' for C, CHAR-CHARLEN for COBOL, CHAR_CHARLEN for PL/I) is the maximum number of single-byte 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.
Item Code Mnemonic
DBQERSQL (DbqerSQL for C)
Fields Value
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 325
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
Item Code Mnemonic
DBQERSQL (DbqerSQL for C)
Fields Value
326 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
DBQERSQL (DbqerSQL for C)
Fields Value
Item Code Mnemonic
Response DBQERRCA (DbqerRCA for C)
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_SUPPORTEDfor 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 RoutineDBCHQE
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.
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.
Item Code Mnemonic
DBQERSIS (DbqerSIS for C)
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)
Item Code Mnemonic
DBQERIDE (DbqerIDE for C
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 RoutineDBCHQE
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.
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.
'Y' with mnemonic QERSISY (QER_Supported for C,SUPPORTED for COBOL, QER_SUPPORTED) for PL/I)
Item Code Mnemonic
DBQERIDE (DbqerIDE for C
Field Value
Item Code Mnemonic
DBQERRID (DbqerRID for C)
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)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 329
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
Item Code Mnemonic
Response DBQERRSS (DbqerRSS for C)
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)
Item Code Mnemonic
Response DBQERQBS (DbqerQBS for C)
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 RoutineDBCHQE
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.
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.
Item Code Mnemonic
DBQERMIU (DbqerMIU for C)
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_ROW for PL/I) if multi-row MERGE INTO is supported.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 331
Chapter 8: CLIv2 Query RoutineDBCHQE
This item is also included in the Aggregate-support-list query item.
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.
Item Code Mnemonic
DBQERLEU (DbqerLEU for C)
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_MERGE for PL/I) if the clause is supported for MERGE INTO, INSERT, and SELECT statements.
Item Code Mnemonic
DBQERPD (DbqerPD for C)
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.
332 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
'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.
Item Code Mnemonic
DBQERPD (DbqerPD for C)
Field Value
Item Code Mnemonic
Response DBQERSCS (DbqerSCS for C)
Field Value
46 QEPISCS QERSCS('name' for C)
Between 1 and 30 EBCDIC characters.
Item Code Mnemonic
Response DBQERCCS (DbqerCCS for C)
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 RoutineDBCHQE
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.
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.
The returned value contains no leading or trailing blanks.
Item Code Mnemonic
Response DBQERIUS (DbqerUS for C)
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.
Item Code Mnemonic
Response DBQERDAP (DbqerDAP for C)
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.
334 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERTSS (DbqerTSS for C)
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)
Item Code Mnemonic
Response DBQERLNS (DbqerLNS for C)
Field Value
51 QEPILNS QERLNS ('status' for C and PL/I)
One of the following EBCDIC:
• '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)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 335
Chapter 8: CLIv2 Query RoutineDBCHQE
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.
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.
Item Code Mnemonic
Response DBQERTOU (DbqerTOU for C)
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, NOT-SUPPORTED 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.
336 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 8: CLIv2 Query RoutineDBCHQE
Item Code Mnemonic
Response DBQERTRS (DbqerTRS for C)
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 RoutineDBCHQE
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 Bitsis 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 SequencesBuffers
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
Parcels received from the Teradata Database are stored in the response buffers in the following ways.
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
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.
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.
340 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesBuffers
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 SequencesTypical 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 SequencesTypical Teradata Response Sequences
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)
Table 42: Response Parcel Sequence in Field Mode (continued)
If the Teradata SQL statement is...
Then the response parcels are as follows...
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 343
Chapter 9: Response SequencesTypical Teradata Response Sequences
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)
Table 42: Response Parcel Sequence in Field Mode (continued)
If the Teradata SQL statement is...
Then the response parcels are as follows...
344 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical Teradata Response Sequences
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.
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)
Table 42: Response Parcel Sequence in Field Mode (continued)
If the Teradata SQL statement is...
Then the response parcels are as follows...
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 SequencesTypical Teradata Response Sequences
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:
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)
Table 43: Response parcel sequence in Record Mode (continued)
If the Teradata SQL statement is...
Then the response parcels are as follows...
Table 44: Response Sequence in MultipartIndicator 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 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.
346 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical Teradata Response Sequences
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)
Table 44: Response Sequence in MultipartIndicator Mode (continued)
If the Teradata SQL statement is... Then the response parcels are as follows...
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 347
Chapter 9: Response SequencesTypical Teradata Response Sequences
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:
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)
Table 44: Response Sequence in MultipartIndicator Mode (continued)
If the Teradata SQL statement is... Then the response parcels are 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 Select statement with no WITH clause
Success parcel (flavor 8) or ResultSummary (flavor 171), the activity count will reflect the number of rows returned.
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 SequencesTypical Teradata Response Sequences
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.
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)
Table 45: Response Parcel Sequence Indicator Mode (continued)
If the Teradata SQL statement is...
Then the response parcels are as follows...
Connect Type.
Return Code field is... And... Then...
R 33 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 SequencesTypical Teradata Response Sequences
Issuing Requests—Field Mode
Field Mode requests may return the following parcels:
R 0 the parcel returned is one of the following:
Failure parcel (flavor 9)
Error parcel (flavor 49)
C non-zero the response parcels do not have to be scanned.
C 0 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)
Connect Type.
Return Code field is... And... Then...
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
350 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical Teradata Response Sequences
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.
RecEnd 28
SizeStart 24
Size 26
SizeEnd 25
TitleStart 20
TitleEnd 21
EndStatement 11
EndRequest 12
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 (title)
TitleEnd 21
FormatStart 22
Field 18 (format)
FormatEnd 23
SizeStart 24
Size 26 (size)
Name Flavor
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 351
Chapter 9: Response SequencesTypical Teradata Response Sequences
SizeEnd 25
RecStart (1) 27
Field 18 (data)
RecEnd (1) 28
.
.
.
.
.
.
RecStart (23) 27
Field 18 (data)
RecEnd (23) 28
EndStatement 11 (1)
EndRequest 12
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1)
Parcel Flavor Body
OK 17 (1, 1, 24, 1, 0, 0)
TitleStart 20
Field 18 (title)
TitleEnd 21
FormatStart 22
Field 18 (format)
FormatEnd 23
SizeStart 24
Size 26 (size)
SizeEnd 25
With 33 (1)
PosStart 46
Position 34 (1)
SELECT FIELD1 FROM TABLE1;
Parcel Flavor Body
352 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical Teradata Response Sequences
PosEnd 47
TitleStart 20
Field 18 (title)
TitleEnd 21
FormatStart 22
Field 18 (format)
FormatEnd 23
SizeStart 24
Size 26 (size)
SizeEnd 25
EndWith 35 (1)
RecStart (1) 27
Field 18 (data)
RecEnd (1) 28
.
.
.
.
.
.
RecStart (23) 27
Field 18 (data)
RecEnd (23) 28
With 33 (1)
Field 18 (data)
EndWith 35 (1)
EndStatement 11 (1)
EndRequest 12
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
Parcel Flavor Body
OK 17 (1, 1, 23, 1, 0, 0)
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1)
Parcel Flavor Body
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 353
Chapter 9: Response SequencesTypical Teradata Response Sequences
TitleStart 20
Field 18 (title)
TitleEnd 21
FormatStart 22
Field 18 (format)
FormatEnd 23
SizeStart 24
Size 26 (size)
SizeEnd 25
RecStart (1) 27
Field 18 (data)
RecEnd (1) 28
.
.
.
.
RecStart (23) 27
Field 18 (data)
RecEnd 28
EndStatement 11 (1)
OK 17 (2, 1, 10, 1, 0, 0)
TitleStart 20
Field 18 (title)
TitleEnd 21
FormatStart 22
Field 18 (format)
FormatEnd 23
SizeStart 24
Size 26 (size)
SizeEnd 25
RecStart (1) 27
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
Parcel Flavor Body
354 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical Teradata Response Sequences
Issuing Requests—Record Mode
Record Mode requests may return the following parcels:
Field 18 (data)
RecEnd (1) 28
.
.
.
.
.
.
RecStart (10) 27
Field 18 (data)
RecEnd (10) 28
EndStatement 11 (2)
EndRequest 12
ECHO ‘SELECT FIELD1 FROM TABLE1‘;
Parcel Flavor Body
OK 17 (1, 1, 0, 33, 0, 0)
RecStart 27
Field 18 (data)
RecEnd 28
EndStatement 11 (1)
EndRequest 12
SELECT FIELD1 FROM TABLE1; SELECT FIELD2 FROM TABLE2;
Parcel Flavor Body
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 SequencesTypical Teradata Response Sequences
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.
EndWith 35
EndStatement 11
EndRequest 12
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)
.
.
.
Record (23)
10
.
.
.
10
(data)
.
.
.
(data)
EndStatement 11 (1)
EndRequest 12
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
Parcel Flavor Body
Success 8 (1, 24, 0, 1, 1, 0)
Name Flavor
356 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical Teradata Response Sequences
Record (1)
.
.
.
Record (23)
10
.
.
.
10
(data)
.
.
.
(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)
.
.
.
Record (23)
10
.
.
.
10
(data)
.
.
.
(data)
EndStatement 11 (1)
Success 8 (2, 10, 0, 1, 1, 0)
Record (1)
.
.
.
Record (10)
10
.
.
.
10
(data)
.
.
.
(data)
EndStatement 11 (2)
EndRequest 12
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
Parcel Flavor Body
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 357
Chapter 9: Response SequencesTypical Teradata Response Sequences
Issuing Requests—MultipartIndicator Mode
MultipartIndicator Mode requests may return the following parcels:
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.
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
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
358 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical 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 (1)
PosEnd 47
DataInfoX 146 (1, 496, 4)
EndWith 35 (1)
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 359
Chapter 9: Response SequencesTypical Teradata Response Sequences
MultipartRecord(s) for row 1 144 (ind, data)
EndMultipartRecord 145
MultipartRecord (s)for row 23 144 (ind, data)
EndMultipartRecord 145
With 33 (1)
MultipartRecord(s) 144 (ind,data)
EndMultipartRecord 145
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)
DataInfoX 146 (1, 496, 4)
MultipartRecord(s) for row 1 144 (ind, data)
EndMultipartRecord 145
MultipartRecord(s) for row 23 144 (ind, data)
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 (ind, data)
EndMultipartRecord 145
EndStatement 11 (2)
EndRequest 12
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
Parcel Flavor Body
360 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical Teradata Response Sequences
Issuing Requests—Indicator Mode
Indicator Mode requests may return the following parcels:
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.
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 (1)
EndRequest 12
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
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 361
Chapter 9: Response SequencesTypical 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
(continued)
71 (1, 496, 4)
Record (1)
.
.
.
Record (23)
10
.
.
.
10
(ind, data)
.
.
.
(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)
DataInfo 71 (1, 496, 4)
With 33 (1)
PosStart 46
Position 34 (1)
PosEnd 47
DataInfo 71 (1, 496, 4)
362 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesTypical Teradata Response Sequences
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)
.
.
.
Record (23)
10
.
.
.
10
(ind.data)
.
.
.
(ind,data)
EndStatement 11 (1)
Success 8 (2, 10, 0, 1, 1, 0)
DataInfo 71 (2, 496, 4)
Record (1)
.
.
.
Record (10)
10
.
.
.
10
(ind,data)
.
.
.
(data)
EndStatement 11 (2)
SELECT FIELD1 FROM TABLE1 WITH SUM (FIELD1);
Parcel Flavor Body
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 363
Chapter 9: Response SequencesParcels in Normal Sequences
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.
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
364 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 9: Response SequencesParcels 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 SequencesParcels 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 CodesError and Failure Codes
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.
Failure Code 3111 the transaction has been timed out. Resubmit the transaction
Error Code 3115 a response parcel greater than 32767 bytes but the CLIv2 Maximum Parcel option to allow larger parcels was not specified.
Specify the Maximum Parcel option to allow larger parcels
an invalid value was returned by the server for the Error parcel information field, being either 0 or not greater than the existing buffer size.
Report the server problem to the Global Support Center
Error Code 3116 an invalid value was returned by the server for the Error parcel information field (being either zero or greater than 32767) when Maximum-parcel was specified as O.
Report the server problem to the Global Support Center
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
Table 46: Error and Failure Codes (continued)
Code Message Action
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 RecoveryAP 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:
• The Teradata session ids are preserved and can continue to be used.
370 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 11: Crash and RecoveryWhat 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:
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
Delay Option Setting
Wait During Delay Y
Tell if Delay Y
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 371
Chapter 11: Crash and RecoveryWhat 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.
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.)
Delay Option Setting
Wait During Delay Y
Tell If Delay N
372 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 11: Crash and RecoveryWhat 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 re-established.
Tell and Logoff
After calling DBCHINI, set the delay options as follows.
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.
Delay Option Setting
Wait During Delay N
Tell If Delay Y
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 373
Chapter 11: Crash and RecoveryWhat 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 CodepointsEBCDIC
• X'40' is the 'Space' character
• X'41' through X'FE' are available to represent graphic characters
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.
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
376 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsEBCDIC037_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'.
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
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
2x LF ETB ESC HTS HTJ VTS PLD PLU ENQ ACK BEL
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 377
Chapter 12: Character Set CodepointsEBCDIC273_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'.
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
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
2x LF ETB ESC HTS HTJ VTS PLD PLU ENQ ACK BEL
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
378 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsEBCDIC277_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
2x LF ETB ESC HTS HTJ VTS PLD PLU ENQ ACK BEL
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 CodepointsHANGULEBCDIC933_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 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 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 CodepointsHANGULEBCDIC933_1II
The server will reject character data containing any single or double byte reserved codepoint and will not identify which invalid codepoint was present.
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
Hangul codepoints. Refer to Table 52 on page 381 for details.
Table 51: Single-byte Teradata HANGULEBCDIC933_1II Codepage (continued)
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II
codepoint
IBM GCGID IBM description
Unicode code Unicode name
42 SP490000 Korean fill (NULL)
U+FFA0 Halfwidth Hangul Filler
43 OG000000 Hangul 'G'
U+FFA1 Halfwidth Hangul Letter kiyeok
44 OG100000 Hangul 'GG'
U+FFA2 Halfwidth Hangul Letter ssangkiyeok
45 OG20000 Hangul 'GS'
U+FFA3 Halfwidth Hangul Letter kiyeok-sios
46 ON00000 Hangul 'N'
U+FFA4 Halfwidth Hangul Letter nieun
47 ON150000 Hangul 'NJ'
U+FFA5 Halfwidth Hangul Letter nieun-cieuc
48 ON100000 Hangul 'NH'
U+FFA6 Halfwidth Hangul Letter nieun-hieuh
49 OD000000 Hangul 'D'
U+FFA7 Halfwidth Hangul Letter tikeut
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 381
Chapter 12: Character Set CodepointsHANGULEBCDIC933_1II
52 OD100000 Hangul 'DD'
U+FFA8 Halfwidth Hangul Letter ssangtikeut
53 OL000000 Hangul 'L'
U+FFA9 Halfwidth Hangul Letter rieul
54 OL200000 Hangul 'LG'
U+FFAA Halfwidth Hangul Letter rieul-kiyeok
55 OL400000 Hangul 'LM'
U+FFAB Halfwidth Hangul Letter rieul-mieum
56 OL100000 Hangul 'LB'
U+FFAC Halfwidth Hangul Letter rieul-pieup
57 OL600000 Hangul 'LS'
U+FFAD Halfwidth Hangul Letter rieul-sios
58 OL700000 Hangul 'LT'
U+FFAE Halfwidth Hangul Letter rieul-thieuth
59 OL500000 Hangul 'LP'
U+FFAF Halfwidth Hangul Letter rieul-phieuph
62 OL300000 Hangul 'LH'
U+FFB0 Halfwidth Hangul Letter rieul-hieuh
63 OM000000 Hangul 'M'
U+FFB1 Halfwidth Hangul Letter mieum
64 OB000000 Hangul 'B'
U+FFB2 Halfwidth Hangul Letter pieup
65 OB100000 Hangul 'BB'
U+FFB3 Halfwidth Hangul Letter ssangpieup
66 OB2000000 Hangul 'BS'
U+FFB4 Halfwidth Hangul Letter pieup-sios
67 OS0000000 Hangul 'S'
U+FFB5 Halfwidth Hangul Letter sios
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
382 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsHANGULEBCDIC933_1II
68 OS100000 Hangul 'SS'
U+FFB6 Halfwidth Hangul Letter ssangsios
69 ON2000000 Hangul 'NG'/'W'
U+FFB7 Halfwidth Hangul Letter ieung
72 OJ000000 Hangul 'J'
U+FFB8 Halfwidth Hangul Letter cieuc
73 OJ100000 Hangul 'JJ'
U+FFB9 Halfwidth Hangul Letter ssangcieuc
74 OC200000 Hangul 'CH'
U+FFBA Halfwidth Hangul Letter chieuch
75 OK000000 Hangul 'K'
U+FFBB Halfwidth Hangul Letter khieukh
76 OT000000 Hangul 'T'
U+FFBC Halfwidth Hangul Letter thieuth
77 OP000000 Hangul 'P'
U+FFBD Halfwidth Hangul Letter phieuph
78 OH000000 Hangul 'H'
U+FFBE Halfwidth Hangul Letter hieuh
8A OA000000 Hangul 'A'
U+FFC2 Halfwidth Hangul Letter 'A'
8B OA200000 Hangul 'AE'
U+FFC3 Halfwidth Hangul Letter 'AE'
8C OY200000 Hangul 'YA'
U+FFC4 Halfwidth Hangul Letter 'YA'
8D OY250000 Hangul 'YAE'
U+FFC5 Halfwidth Hangul Letter 'YAE'
8E OE200000 Hangul 'EO'
U+FFC6 Halfwidth Hangul Letter 'EO'
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 383
Chapter 12: Character Set CodepointsHANGULEBCDIC933_1II
8F OE000000 Hangul 'E'
U+FFC7 Halfwidth Hangul Letter 'E'
9A OY400000 Hangul 'YEO'
U+FFCA Halfwidth Hangul Letter 'YEO'
9B OY300000 Hangul 'YE'
U+FFCB Halfwidth Hangul Letter 'YE'
9C OO000000 Hangul 'O'
U+FFCC Halfwidth Hangul Letter 'O'
9D OO100000 Hangul 'OA'
U+FFCD Halfwidth Hangul Letter 'WA'
9E OO200000 Hangul 'OAE'
U+FFCE Halfwidth Hangul Letter 'WAE'
9F OO300000 Hangul 'OI'
U+FFCF Halfwidth Hangul Letter 'OE'
AA OY500000 Hangul 'YO'
U+FFD2 Halfwidth Hangul Letter 'YO'
AB OU000000 Hangul 'U'
U+FFD3 Halfwidth Hangul Letter 'U'
AC OU300000 Hangul 'UEO'
U+FFD4 Halfwidth Hangul Letter 'WEO'
AD OU200000 Hangul 'UE'
U+FFD5 Halfwidth Hangul Letter 'WE'
AE OU400000 Hangul 'UI'
U+FFD6 Halfwidth Hangul Letter 'WI'
AF OY600000 Hangul 'YU'
U+FFD7 Halfwidth Hangul Letter 'YU'
BA OE300000 Hangul 'EU'
U+FFDA Halfwidth Hangul Letter 'EU'
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
384 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKANJIEBCDIC5026_0I
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.
BB OE400000 Hangul 'EUI'
U+FFDB Halfwidth Hangul Letter 'YI'
BC OI000000 Hangul 'I'
U+FFDC Halfwidth Hangul Letter 'I'
Table 52: Hangul Codepoint Assignments for HANGULEBCDIC933_1II (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 385
Chapter 12: Character Set CodepointsKANJIEBCDIC5026_0I
The server will reject character data containing any single or double byte reserved codepoint and will not identify which invalid codepoint was present.
Table 53: Single-byte Teradata KANJIEBCDIC5026_0I Codepage
x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x NUL SOH STX ETX HT VT FF CR SO SI
1x BS CAN EM IS4 IS3 IS2 IS1
2x LF ETB ESC ENQ ACK BEL
3x SYN EOT NAK
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 1 2 3 4 5 6 7 8 9
Control character codepoints
Reserved codepoints.
Katakana codepoints. Refer to Table 54 on page 386 for details.
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I
codepoint
IBM GCGID IBM description
Unicode code Unicode name
41 JQ700000 Katakana full stop
U+FF61 Halfwidth Ideographic Full Stop
42 JQ710000 Katakana left Bracket
U+FF62 Halfwidth Left Corner Bracket
386 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKANJIEBCDIC5026_0I
43 JQ720000 Katakana right Bracket
U+FF63 Halfwidth Right Corner Bracket
44 JQ730000 Katakana comma
U+FF64 Halfwidth Ideographic Comma
45 JQ74000 Katakana conjunctive symbol
U+FF65 Halfwidth Katakana Middle Dot
46 JW500000 Katakana 'WO'
U+FF66 Halfwidth Katakana Letter 'WO'
47 JA010000 Katakana 'a'
U+FF67 Halfwidth Katakana Letter Small 'a'
48 JI010000 Katakana 'i'
U+FF68 Halfwidth Katakana Letter Small 'i'
49 JU010000 Katakana 'u'
U+FF69 Halfwidth Katakana Letter Small 'u'
51 JE010000 Katakana 'e'
U+FF6A Halfwidth Katakana Letter Small 'e'
52 JO010000 Katakana 'o'
U+FF6B Halfwidth Katakana Letter Small 'o'
53 JY110000 Katakana 'ya'
U+FF6C Halfwidth Katakana Letter Small 'ya'
54 JY310000 Katakana 'yu'
U+FF6D Halfwidth Katakana Letter Small 'yu'
55 JY510000 Katakana 'yo'
U+FF6E Halfwidth Katakana Letter Small 'yo'
56 JT310000 Katakana 'tu'/'tsu'
U+FF6F Halfwidth Katakana Letter Small 'tu'
58 JX700000 Katakana prolonged sound symbol
U+FF70 Halfwidth Katakana-Hiragana prolonged sound symbol
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 387
Chapter 12: Character Set CodepointsKANJIEBCDIC5026_0I
81 JA000000 Katakana 'A'
U+FF71 Halfwidth Katakana Letter 'A'
82 JI000000 Katakana 'I'
U+FF72 Halfwidth Katakana Letter 'I'
83 JU000000 Katakana 'U'
U+FF73 Halfwidth Katakana Letter 'U'
84 JE000000 Katakana 'E'
U+FF74 Halfwidth Katakana Letter 'E'
85 JO000000 Katakana 'O'
U+FF75 Halfwidth Katakana Letter 'O'
86 JK100000 Katakana 'KA'
U+FF76 Halfwidth Katakana Letter 'KA'
87 JK200000 Katakana 'KI'
U+FF77 Halfwidth Katakana Letter 'KI'
88 JK300000 Katakana 'KU'
U+FF78 Halfwidth Katakana Letter 'KU'
89 JK400000 Katakana 'KE'
U+FF79 Halfwidth Katakana Letter 'KE'
8A JK500000 Katakana 'KO'
U+FF7A Halfwidth Katakana Letter 'KO'
8B LQ010000 'q' Small
U+0071 Latin Small Letter 'q'
8C JS100000 Katakana 'SA'
U+FF7B Halfwidth Katakana Letter 'SA'
8D JS200000 Katakana 'SI'
U+FF7C Halfwidth Katakana Letter 'SI'
8E JS300000 Katakana 'SU'
U+FF7D Halfwidth Katakana Letter 'SU'
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
388 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKANJIEBCDIC5026_0I
8F JS400000 Katakana 'SE'
U+FF7E Halfwidth Katakana Letter 'SE'
90 JS500000 Katakana 'SO'
U+FF7F Halfwidth Katakana Letter 'SO'
91 JT100000 Katakana 'TA'
U+FF80 Halfwidth Katakana Letter 'TA'
92 JT200000 Katakana 'TI'
U+FF81 Halfwidth Katakana Letter 'TI'
93 JT300000 Katakana 'TU'
U+FF82 Halfwidth Katakana Letter 'TU'
94 JT400000 Katakana 'TE'
U+FF83 Halfwidth Katakana Letter 'TE'
95 JT500000 Katakana 'TO'
U+FF84 Halfwidth Katakana Letter 'TO'
96 JN100000 Katakana 'NA'
U+FF85 Halfwidth Katakana Letter 'NA'
97 JN200000 Katakana 'NI'
U+FF86 Halfwidth Katakana Letter 'NI'
98 JN300000 Katakana 'NU'
U+FF87 Halfwidth Katakana Letter 'NU'
99 JN140000 Katakana 'NE'
U+FF88 Halfwidth Katakana Letter 'NE'
9A JN500000 Katakana 'NO'
U+FF89 Halfwidth Katakana Letter 'NO'
9D JH100000 Katakana 'HA'
U+FF8AD Halfwidth Katakana Letter 'HA'
9E JH200000 Katakana 'HI'
U+FF8B Halfwidth Katakana Letter 'HI'
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 389
Chapter 12: Character Set CodepointsKANJIEBCDIC5026_0I
9F JH300000 Katakana 'HU'/'FU'
U+FF8C Halfwidth Katakana Letter 'HU'
A2 LS010000 Katakana 'HE'
U+0073 Halfwidth Katakana Letter 'HE'
A3 LT010000 Katakana 'HO'
U+0074 Halfwidth Katakana Letter 'HO'
A4 LU010000 Katakana 'MA'
U+0075 Halfwidth Katakana Letter 'MA'
A5 LV010000 Katakana 'MI'
U+0076 Halfwidth Katakana Letter 'MI'
A6 LW010000 Katakana 'MU'
U+0077 Halfwidth Katakana Letter 'MU'
A7 LX010000 Katakana 'ME'
U+0078 Halfwidth Katakana Letter 'ME'
A8 LY010000 Katakana 'MO'
U+0079 Halfwidth Katakana Letter 'MO'
A9 LZ010000 Katakana 'YA'
U+007A Halfwidth Katakana Letter 'YA'
AA SM210000 Katakana 'YU'
U+00AA Halfwidth Katakana Letter 'YU'
AC SM660000 Katakana 'YO'
U+00AC Halfwidth Katakana Letter 'YO'
AD SM060000 Katakana 'RA'
U+005B Halfwidth Katakana Letter 'RA'
AE SM530000 Katakana 'RI'
U+00AE Halfwidth Katakana Letter 'RI'
AF SM150000 Katakana 'RU'
U+00AF Halfwidth Katakana Letter 'RU'
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
390 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKANJIEBCDIC5035_0I
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
BA JR400000 Katakana 'RE'
U+FF9A Halfwidth Katakana Letter 'RE'
BB JR500000 Katakana 'RO'
U+FF9B Halfwidth Katakana Letter 'RO'
BC JW100000 Katakana 'WA'
U+FF9C Halfwidth Katakana Letter 'WA'
BD JN000000 Katakana 'N'
U+FF9D Halfwidth Katakana Letter 'N'
BE JX710000 Voiced sound symbol
U+FF9E Halfwidth Katakana Voiced sound Mark
BF JX720000 Semi-voiced sound symbol
U+FF9F Halfwidth Katakana Semi-voiced sound Mark
Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 391
Chapter 12: Character Set CodepointsKANJIEBCDIC5035_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.
The server will reject character data containing any single or double byte reserved codepoint and will not identify which invalid codepoint was present.
Table 55: Single-byte Teradata KANJIEBCDIC5035_0I Codepage
x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x NUL SOH STX ETX HT VT FF CR SO SI
1x BS CAN EM IS4 IS3 IS2 IS1
2x LF ETB ESC ENQ ACK BEL
3x SYN EOT NAK
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 1 2 3 4 5 6 7 8 9
Control character codepoints
Reserved codepoints
Katakana codepoints. Refer to Table 56 on page 393 for details.
392 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKANJIEBCDIC5035_0I
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I
codepoint
IBM GCGID IBM description
Unicode code Unicode name
42 JQ700000 Katakana full stop
U+FF61 Halfwidth Ideographic Full Stop
43 JQ710000 Katakana left Bracket
U+FF62 Halfwidth Left Corner Bracket
44 JQ720000 Katakana right Bracket
U+FF63 Halfwidth Right Corner Bracket
45 JQ730000 Katakana comma
U+FF64 Halfwidth Ideographic Comma
46 JQ74000 Katakana conjunctive symbol
U+FF65 Halfwidth Katakana Middle Dot
47 JW500000 Katakana 'WO'
U+FF66 Halfwidth Katakana Letter 'WO'
48 JA010000 Katakana 'a'
U+FF67 Halfwidth Katakana Letter Small 'a'
49 JI010000 Katakana 'i'
U+FF68 Halfwidth Katakana Letter Small 'i'
51 JU010000 Katakana 'u'
U+FF69 Halfwidth Katakana Letter Small 'u'
52 JE010000 Katakana 'e'
U+FF6A Halfwidth Katakana Letter Small 'e'
53 JO010000 Katakana 'o'
U+FF6B Halfwidth Katakana Letter Small 'o'
54 JY110000 Katakana 'ya'
U+FF6C Halfwidth Katakana Letter Small 'ya'
55 JY310000 Katakana 'yu'
U+FF6D Halfwidth Katakana Letter Small 'yu'
56 JY510000 Katakana 'yo'
U+FF6E Halfwidth Katakana Letter Small 'yo'
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 393
Chapter 12: Character Set CodepointsKANJIEBCDIC5035_0I
57 JT310000 Katakana 'tu'/'tsu'
U+FF6F Halfwidth Katakana Letter Small 'tu'
58 JX700000 Katakana prolonged sound symbol
U+FF70 Halfwidth Katakana-Hiragana prolonged sound mark
59 JA000000 Katakana 'A'
U+FF71 Halfwidth Katakana Letter 'A'
62 JI000000 Katakana 'I'
U+FF72 Halfwidth Katakana Letter 'I'
63 JU000000 Katakana 'U'
U+FF73 Halfwidth Katakana Letter 'U'
64 JE000000 Katakana 'E'
U+FF74 Halfwidth Katakana Letter 'E'
65 JO000000 Katakana 'O'
U+FF75 Halfwidth Katakana Letter 'O'
66 JK100000 Katakana 'KA'
U+FF76 Halfwidth Katakana Letter 'KA'
67 JK200000 Katakana 'KI'
U+FF77 Halfwidth Katakana Letter 'KI'
68 JK300000 Katakana 'KU'
U+FF78 Halfwidth Katakana Letter 'KU'
69 JK400000 Katakana 'KE'
U+FF79 Halfwidth Katakana Letter 'KE'
70 JK500000 'Katakana 'KO'
U+FF7A Halfwidth Katakana Letter 'KO'
71 JS100000 Katakana 'SA'
U+FF7B Halfwidth Katakana Letter 'SA'
72 JS200000 Katakana 'SI'/'SHI'
U+FF7C Halfwidth Katakana Letter 'SI'
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
394 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKANJIEBCDIC5035_0I
73 JS300000 Katakana 'SU'
U+FF7D Halfwidth Katakana Letter 'SU'
74 JS400000 Katakana 'SE'
U+FF7E Halfwidth Katakana Letter 'SE'
75 JS500000 Katakana 'SO'
U+FF7F Halfwidth Katakana Letter 'SO'
76 JT100000 Katakana 'TA'
U+FF80 Halfwidth Katakana Letter 'TA'
77 JT200000 Katakana 'TI'/'CHI'
U+FF81 Halfwidth Katakana Letter 'TI'
78 JT300000 Katakana 'TU'/'TSU'
U+FF82 Halfwidth Katakana Letter 'TU'
8A JT400000 Katakana 'TE'
U+FF83 Halfwidth Katakana Letter 'TE'
8B JT500000 Katakana 'TO'
U+FF84 Halfwidth Katakana Letter 'TO'
8C JN100000 Katakana 'NA'
U+FF85 Halfwidth Katakana Letter 'NA'
8D JN200000 Katakana 'NI'
U+FF86 Halfwidth Katakana Letter 'NI'
8E JN300000 Katakana 'NU'
U+FF87 Halfwidth Katakana Letter 'NU'
8F JN400000 Katakana 'NE'
U+FF88 Halfwidth Katakana Letter 'NE'
9A JN500000 Katakana 'NO'
U+FF89 Halfwidth Katakana Letter 'NO'
9B JH100000 Katakana 'MH'
U+FF8A Halfwidth Katakana Letter 'MH'
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 395
Chapter 12: Character Set CodepointsKANJIEBCDIC5035_0I
9C JH200000 Katakana 'HI'
U+FF8B Halfwidth Katakana Letter 'HI'
9D JH300000 Katakana 'HU'/'FU'
U+FF8C Halfwidth Katakana Letter 'HU'
9E JH400000 Katakana 'HE'
U+FF8D Halfwidth Katakana Letter 'HE'
9F JH500000 Katakana 'HO'
U+FF8E Halfwidth Katakana Letter 'HO'
AA JM100000 Katakana 'MA'
U+FF8F Halfwidth Katakana Letter 'MA'
AB JM200000 Katakana 'MI'
U+FF90 Halfwidth Katakana Letter 'MI'
AC JM300000 Katakana 'MU'
U+FF91 Halfwidth Katakana Letter 'MU'
AE JM400000 Katakana 'ME'
U+FF92 Halfwidth Katakana Letter 'ME'
AF JM500000 Katakana 'MO'
U+FF93 Halfwidth Katakana Letter 'MO'
B3 JY100000 Katakana 'YA'
U+FF94 Halfwidth Katakana Letter 'YA'
B4 JY300000 Katakana 'YU'
U+FF95 Halfwidth Katakana Letter 'YU'
B5 JY500000 Katakana 'YO'
U+FF96 Halfwidth Katakana Letter 'YO'
B6 JR100000 Katakana 'RA'
U+FF97 Halfwidth Katakana Letter 'RA'
B7 JR200000 Katakana Letter 'RI'
U+FF98 Halfwidth Katakana Letter 'RI'
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
396 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKATAKANAEBCDIC
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
B8 JR300000 Katakana 'RU'
U+FF99 Halfwidth Katakana Letter 'RU'
B9 JR400000 Katakana 'RE'
U+FF9A Halfwidth Katakana Letter 'RE'
BA JR500000 Katakana 'RO'
U+FF9B Halfwidth Katakana Letter 'RO'
BB JW100000 Katakana 'WA'
U+FF9C Halfwidth Katakana Letter 'WA'
BC JN000000 Katakana 'N'
U+FF9D Halfwidth Katakana Letter 'N'
BE JX710000 Voiced sound symbol
U+FF9E Halfwidth Katakana Voiced sound Mark
BF JX720000 Semi-voiced sound symbol
U+FF9F Halfwidth Katakana Semi-voiced sound Mark
Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 397
Chapter 12: Character Set CodepointsKATAKANAEBCDIC
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.
The server will reject character data containing any single or double byte reserved codepoint and will not identify which invalid codepoint was present.
Table 57: Single-byte Teradata KATAKANAEBCDIC Codepage
x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF
0x NUL SOH STX ETX HT y VT FF CR SO SI
1x ¢ ¬ / a BS b CAN EM IS4 IS3 IS2 IS1
2x LF ETB ESC ENQ ACK BEL
3x SYN c EOT ~ NAK
4x SP £ . < ( + |
5x & ! ¥ * ) ; ^
6x - / d e f g h i j , % _ > ?
7x p q r s t u v w x ´ : # @ ' = "
8x
9x
Ax [ ¯
Bx ]
Cx { A B C D E F G H I z k l m n o
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
Katakana codepoints. Refer to Table 58 on page 399 for details.
398 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKATAKANAEBCDIC
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC
codepoint
IBM GCGID IBM description
Unicode code Unicode name
41 JQ700000 Katakana full stop
U+FF61 Halfwidth Ideographic Full Stop
42 JQ710000 Katakana left Bracket
U+FF62 Halfwidth Left Corner Bracket
43 JQ720000 Katakana right Bracket
U+FF63 Halfwidth Right Corner Bracket
44 JQ730000 Katakana comma
U+FF64 Halfwidth Ideographic Comma
45 JQ74000 Katakana conjunctive symbol
U+FF65 Halfwidth Katakana Middle Dot
46 JW500000 Katakana 'WO'
U+FF66 Halfwidth Katakana Letter 'WO'
47 JA010000 Katakana 'a'
U+FF67 Halfwidth Katakana Letter Small 'a'
48 JI010000 Katakana 'i'
U+FF68 Halfwidth Katakana Letter Small 'i'
49 JU010000 Katakana 'u'
U+FF69 Halfwidth Katakana Letter Small 'u'
51 JE010000 Katakana 'e'
U+FF6A Halfwidth Katakana Letter Small 'e'
52 JO010000 Katakana 'o'
U+FF6B Halfwidth Katakana Letter Small 'o'
53 JY110000 Katakana 'ya'
U+FF6C Halfwidth Katakana Letter Small 'ya'
54 JY310000 Katakana 'yu'
U+FF6D Halfwidth Katakana Letter Small 'yu'
55 JY510000 Katakana 'yo'
U+FF6E Halfwidth Katakana Letter Small 'yo'
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 399
Chapter 12: Character Set CodepointsKATAKANAEBCDIC
56 JT310000 Katakana 'tu'/'tsu'
U+FF6F Halfwidth Katakana Letter Small 'tu'
58 JX700000 Katakana prolonged sound symbol
U+FF70 Halfwidth Katakana-Hiragana prolonged sound mark
81 JA000000 Katakana 'A'
U+FF71 Halfwidth Katakana Letter 'A'
82 JI000000 Katakana 'I'
U+FF72 Halfwidth Katakana Letter 'I'
83 JU000000 Katakana 'U'
U+FF73 Halfwidth Katakana Letter 'U'
84 JE000000 Katakana 'E'
U+FF74 Halfwidth Katakana Letter 'E'
85 JO000000 Katakana 'O'
U+FF75 Halfwidth Katakana Letter 'O'
86 JK100000 Katakana 'KA'
U+FF76 Halfwidth Katakana Letter 'KA'
87 JK200000 Katakana 'KI'
U+FF77 Halfwidth Katakana Letter 'KI'
88 JK300000 Katakana 'KU'
U+FF78 Halfwidth Katakana Letter 'KU'
89 JK400000 Katakana 'KE'
U+FF79 Halfwidth Katakana Letter 'KE'
8A JK500000 Katakana 'KO'
U+FF7A Halfwidth Katakana Letter 'KO'
8C JS100000 Katakana 'SA'
U+FF7B Halfwidth Katakana Letter 'SA'
8D JS200000 Katakana 'SI'/'SHI'
U+FF7C Halfwidth Katakana Letter 'SI'
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
400 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsKATAKANAEBCDIC
8E JS300000 Katakana 'SU'
U+FF7D Halfwidth Katakana Letter 'SU'
8F JS400000 Katakana 'SE'
U+FF7E Halfwidth Katakana Letter 'SE'
90 JS500000 Katakana 'SO'
U+FF7F Halfwidth Katakana Letter 'SO'
91 JT100000 Katakana 'TA'
U+FF80 Halfwidth Katakana Letter 'TA'
92 JT200000 Katakana 'TI'/'CHI'
U+FF81 Halfwidth Katakana Letter 'TI'
93 JT300000 Katakana 'TU'/'TSU'
U+FF82 Halfwidth Katakana Letter 'TU'
94 JT400000 Katakana 'TE'
U+FF83 Halfwidth Katakana Letter 'TE'
95 JT500000 Katakana 'TO'
U+FF84 Halfwidth Katakana Letter 'TO'
96 JN100000 Katakana 'NA'
U+FF85 Halfwidth Katakana Letter 'NA'
97 JN200000 Katakana 'NI'
U+FF86 Halfwidth Katakana Letter 'NI'
98 JN300000 Katakana 'NU'
U+FF87 Halfwidth Katakana Letter 'NU'
99 JN400000 Katakana 'NE'
U+FF88 Halfwidth Katakana Letter 'NE'
9A JN500000 Katakana 'NO'
U+FF89 Halfwidth Katakana Letter 'NO'
9D JH100000 Katakana 'HA'
U+FF8A Halfwidth Katakana Letter 'HA'
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 401
Chapter 12: Character Set CodepointsKATAKANAEBCDIC
9E JH200000 Katakana 'HI'
U+FF8B Halfwidth Katakana Letter 'HI'
9F JH300000 Katakana 'HU'/'FU'
U+FF8C Halfwidth Katakana Letter 'HU'
A2 JH400000 Katakana 'HE'
U+FF8D Halfwidth Katakana Letter 'HE'
A3 JH500000 Katakana 'HO'
U+FF8E Halfwidth Katakana Letter 'HO'
A4 JM100000 Katakana 'MA'
U+FF8F Halfwidth Katakana Letter 'MA'
A5 JM200000 Katakana 'MI'
U+FF90 Halfwidth Katakana Letter 'MI'
A6 JM300000 Katakana 'MU'
U+FF91 Halfwidth Katakana Letter 'MU'
A7 JM400000 Katakana 'ME'
U+FF92 Halfwidth Katakana Letter 'ME'
A8 JM500000 Katakana 'MO'
U+FF93 Halfwidth Katakana Letter 'MO'
A9 JY100000 Katakana 'YA'
U+FF94 Halfwidth Katakana Letter 'YA'
AA JY300000 Katakana 'YU'
U+FF95 Halfwidth Katakana Letter 'YU'
AC JY500000 Katakana 'YO'
U+FF96 Halfwidth Katakana Letter 'YO'
AD JR100000 Katakana 'RA'
U+FF97 Halfwidth Katakana Letter 'RA'
AE JR200000 Katakana 'RI'
U+FF98 Halfwidth Katakana Letter 'RI'
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
402 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsSCHEBCDIC935_2IJ
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.
AF JR300000 Katakana 'RU'
U+FF99 Halfwidth Katakana Letter 'RU'
BA JR400000 Katakana 'RE'
U+FF9A Halfwidth Katakana Letter 'RE'
BB JR500000 Katakana 'RO'
U+FF9B Halfwidth Katakana Letter 'RO'
BC JW100000 Katakana 'WA'
U+FF9C Halfwidth Katakana Letter 'WA'
BD JN000000 Katakana 'N'
U+FF9D Halfwidth Katakana Letter 'N'
BE JX710000 Voiced sound symbol
U+FF9E Halfwidth Katakana Voiced sound Mark
BF JX720000 Semi-voiced sound symbol
U+FF9F Halfwidth Katakana Semi-voiced sound Mark
Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)
codepoint
IBM GCGID IBM description
Unicode code Unicode name
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 403
Chapter 12: Character Set CodepointsSCHEBCDIC935_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.
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.
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
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 APC
Control character codepoints
Reserved codepoints
404 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 12: Character Set CodepointsTCHEBCDIC937_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 CodepointsTCHEBCDIC937_3IB
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.
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 1 2 3 4 5 6 7 8 9 APC
Control character codepoints
Reserved 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 SetsDirectives
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
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
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.
Directive Description
2417C005
CHARSET NAME character_set_name
CHARS NAM ENCODINGENC
ASCIIA
EBCDICE
IBMSOSII
BIGFIVER
SJISS
UHCEUC-CNEUC-KR
TEUC-JP
U
UTF8
UTF-16
408 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 13: User-Defined Character SetsDirectives
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-Coded-Decimal 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 SetsDirectives
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
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.
ENCODING Meaning Characteristics
410 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 13: User-Defined Character SetsDirectives
END
The END directive ends processing of records in the file.
Syntax
Usage
Any remaining records in the file are not read.
ExampleEND
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
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.
2417A012
END
2417A013
UNICODEUNI
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 411
Chapter 13: User-Defined Character SetsDirectives
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 001A 115F 1100 1101 1115 1102 11AC48-4F: 11AD 1103 00A2 002E 003C 0028 002B 007C50-57: 0026 001A 1104 1105 11B0 11B1 11B2 11B358-5F: 11B4 11B5 0021 0024 002A 0029 003B 00AC60-67: 002D 002F 11B6 1106 1107 1108 1121 110968-6F: 110A 110B 00A6 002C 0025 005F 003E 003F70-77: 005B 001A 110C 110D 110E 110F 1110 111178-7F: 1112 0060 003A 0023 0040 0027 003D 002280-87: 005D 0061 0062 0063 0064 0065 0066 006788-8F: 0068 0069 1161 1162 1163 1164 1165 116690-97: 001A 006A 006B 006C 006D 006E 006F 007098-9F: 0071 0072 1167 1168 1169 116A 116B 116CA0-A7: 00AF 007E 0073 0074 0075 0076 0077 0078A8-AF: 0079 007A 116D 116E 116F 1170 1171 1172B0-B7: 005E 001A 005C 001A 001A 001A 001A 001AB8-BF: 001A 001A 1173 1174 1175 001A 001A 001AC0-C7: 007B 0041 0042 0043 0044 0045 0046 0047C8-CF: 0048 0049 001A 001A 001A 001A 001A 001AD0-D7: 007D 004A 004B 004C 004D 004E 004F 0050D8-DF: 0051 0052 001A 001A 001A 001A 001A 001AE0-E7: 20A9 001A 0053 0054 0055 0056 0057 0058E8-EF: 0059 005A 001A 001A 001A 001A 001A 001AF0-F7: 0030 0031 0032 0033 0034 0035 0036 0037F8-FF: 0038 0039 001A 001A 001A 001A 001A 001A
412 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 DefinitionsSuffixes
Table 61: Language Module Suffixes
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
414 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 14: Message DefinitionsComment Formatting
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:
Keywords
To ensure portability of applications using Language Ids, the following are the recommended LANG and COUNTRY keywords:
Chinese (China) CHS
Chinese (Taiwan) CHT
Table 61: Language Module Suffixes (continued)
Language Suffix
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 415
Chapter 14: Message DefinitionsKeywords
Table 62: Language and Country Keywords
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)
416 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 14: Message DefinitionsKeywords
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.
Chinese (China) LANG=ZH,COUNTRY=(CN,OPTIONAL)
Chinese (Taiwan) LANG=ZH,COUNTRY=TW
Table 62: Language and Country Keywords (continued)
Language Keywords
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 417
Chapter 14: Message DefinitionsKeywords
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 ApplicationsParcel Types
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:
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
Table 63: Parcel flavors (continued)
Flavor Parcel Name Flavor Parcel Name
420 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Types
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.
Parcel type... Is generated for...
Request requests sent to the Teradata Database
Response responses sent from the Teradata Database to a client
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
(Record Mode)
Returns one row of selected results.
10 Record
(Indicator Mode)
Returns one row of selected results.
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 ApplicationsParcel Types
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.
Table 64: Response Parcel Flavors, Names, And Uses (continued)
Flavor Parcel Name Use
422 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Types
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.
Table 64: Response Parcel Flavors, Names, And Uses (continued)
Flavor Parcel Name Use
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 423
Chapter 15: Parcels for Basic ApplicationsCommon 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
NameType ifnon-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
424 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsCommon Parcel Fields
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.
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
Table 65: Data Type Values (continued)
NameType ifnon-nullable
Type if Nullable
Type if IN parameter
Type if INOUT parameter
Type if OUT parameter
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 ApplicationsCommon Parcel Fields
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
Table 66: Activity Codes (continued)
Value Statement Value Statement Value Statement
426 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsCommon Parcel Fields
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
Table 66: Activity Codes (continued)
Value Statement Value Statement Value Statement
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 427
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Parcel Descriptions
The following alphabetized sections describe parcels generated by basic applications and the Teradata Database, when Return-statement-info 'Y' was not specified.
145 Replace Ordering 146 Drop Ordering 147 SQL CREATE TRANSFORM
148 Replace Transform 149 SQL DROP TRANSFORM
196 SQL Select for FastExport without Spooling
Table 66: Activity Codes (continued)
Value Statement Value Statement Value Statement
• 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
428 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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
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.
FlavorParcel Body Length Parcel Body Fields
71 6 to maximum body size
FieldCount:
Pair 1:
.
.
.
Pair i:
.
.
.
Pair n:
Data Type:
Length:
Data Type:
Length:
Data Type:
Length:
2 bytes
2 bytes
2 bytes
2 bytes
2 bytes
2 bytes
2 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 429
Chapter 15: Parcels for Basic ApplicationsParcel 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.
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
FlavorParcel Body Length Parcel Body Fields
146 6 to maximum body size
FieldCount:
Pair 1:
.
.
.
Data Type:
Length:
2 bytes
2 bytes
8 bytes
Pair i:
.
.
.
Pair n:
Data Type:
Length:
Data Type:
Length:
2 bytes
8 bytes
2 bytes
8 bytes
430 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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
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
ElicitFile
Purpose
For MultipartIndicator mode responses, elicits a User Defined Function.
FlavorParcel Body Length Parcel Body Fields
150 4 Token: 4 byte
FlavorParcel Body Length Parcel Body Fields
152 0 None
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 431
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Parcel Data
The following table lists field information for ElicitFile.
Usage Notes
SourceLanguage identifies the language in which the User Defined Function is programmed, as one of the following:
FileType identifies the type of file, chosen as one of the following:
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.
FlavorParcel Body Length Parcel Body Fields
151 6 to maximum body size
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
0 = Not supplied 1 = C
2 = C++ 3 = Java
0 = Not supplied 1 = A source file
2 = An included file 3 = An object file
432 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
EndMultipartRecord
Purpose
For MultipartIndicator mode responses, delimits one row or selected results.
Usage Notes
The following table lists field information for EndMultipartRecord.
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 MnemonicTRDSPBEN
Field Length Value
178 TRDSPFEN 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.
FlavorParcel Body Length Parcel Body Fields
145 0 None
FlavorParcel 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 ApplicationsParcel 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.
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.
Field Notes
WithId is the summary number (1-n) for this End With clause.
FlavorParcel Body Length Parcel Body Fields
11 2 StatementNo: 2 byte unsigned integer
FlavorParcel Body Length Parcel Body Fields
35 2 WithId: 2 byte unsigned integer
434 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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.
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.
FlavorParcel Body Length Parcel Body Fields
49 8 to 263 StatementNo:
Info:
Code:
Length:
Msg:
2 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
1 to 255 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 435
Chapter 15: Parcels for Basic ApplicationsParcel 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.
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.
FlavorParcel Body Length Parcel Body Fields
9 8 to 263 StatementNo:
Info:
Code:
Length:
Msg:
2 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
1 to 255 bytes
436 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Parcel Data
This parcel is generated by the Teradata server.
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.
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.
FlavorParcel Body Length
Parcel Body Fields
If Field is preceded by this parcel... Then it contains...
18 0 to maximum body size
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 437
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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.
FormatStart
Purpose
Delimits the start of a sequence of Field parcels that contain format descriptors for fields in Field Mode.
FlavorParcel Body Length Parcel Body Fields
122 6 to maximum body size
Location:
Reason:
MsgLength:
Message:
2 bytes
2 bytes
2 bytes
to maximum body size
FlavorParcel Body Length Parcel Body Fields
23 0 none
438 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the FormatStart parcel.
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).
FlavorParcel Body Length Parcel Body Fields
22 0 none
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 439
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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.
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:
• The Data Field contains items with characteristics as follows:
• The order of the items.
FlavorParcel Body Length Parcel Body Fields
144 1 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: 1 to 32000 - ((n+7) / 8) bytes
organized as: item 1, item2, . . . , item i,
. . . , item n
If a bit is... Then the value of the corresponding data item is...
ON null.
OFF not null.
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.
440 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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.
OK
Purpose
First parcel returned in response to a successfully executed Field Mode Teradata SQL statement when using Original Statement-status.
FlavorParcel Body Length Parcel Body Fields
19 0 none
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 441
Chapter 15: Parcels for Basic ApplicationsParcel 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.
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.
FlavorParcel Body Length Parcel Body Fields
17 14 to 269 StatementNo:
FieldCount:
ActivityCount:
ActivityType:
WarningCode:
WarningLength:
WarningMsg:
2 byte unsigned integer
2 byte unsigned integer
4 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
0 to 255 bytes
442 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the PosEnd parcel.
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.
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.
FlavorParcel Body Length Parcel Body Fields
47 0 none
FlavorParcel Body Length Parcel Body Fields
34 2 ColumnNo: 2 byte unsigned integer
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 443
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Parcel Data
The following information applies to the PosStart parcel.
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.
FlavorParcel Body Length Parcel Body Fields
46 0 none
FlavorParcel Body Length Parcel Body Fields
86 12 to maximum body size
CostEstimate:
SummaryCount:
8 byte floating
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:
DataLen:
ColumnName:
ColumnFormat:
ColumnTitle:
2 byte unsigned integer
2 byte unsigned integer
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
two byte unsigned integer plus the number of bytes specified by that integer
444 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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 ApplicationsParcel 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 SalaryWITH COUNT (DeptNo) BY DeptNo;
This statement produces a PrepInfo parcel with the following byte sequence:
Parcel flavor is 86 with length 12440 4D BE B8 51 EB 85 1E 00 02 00 01 01 C0 00 0C00 04 D5 81 94 85 00 05 E7 4D F1 F2 5D 00 04 4E61 6D 65 00 02 01 F1 00 04 00 00 00 06 60 4D F1F0 5D F9 00 0B E2 E4 D4 4D C4 85 97 A3 D5 96 5D01 E5 0F 02 00 00 00 0A E9 E9 E9 6B E9 E9 F9 4BF9 F9 00 0B 53 75 6D 28 53 61 6C 61 72 79 29 0001 01 F1 00 04 00 00 00 06 E2 E4 D4 4D E2 81 9381 99 A8 5D 00 0B E2 E4 D4 4D C4 85 97 A3 D5 965D
The parcel fields, above, translate as follows (an explanation of each acronym follows):
CE CE CE CE CE CE CE CE SC SC CC CC DT DT DL DLNL NL CN CN CN CN FL FL CF CF CF CF CF TL TL CTCT CT CT CC CC DT DT DL DL NL NL FL FL CF CF CFCF CF CF TL TL CT CT CT CT CT CT CT CT CT CT CTDT DT DL DL NL NL FL FL CF CF CF CF CF CF CF CFCF CF TL TL CT CT CT CT CT CT CT CT CT CT CT CCCC DT DT DL DL NL NL FL FL CF CF CF CF CF CF TLTL CT CT CT CT CT CT CT CT CT CT CT
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.
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
446 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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.
Field Notes
The following notes apply to PrepInfoX fields.
FlavorParcel Body Length Parcel Body Fields
125 12 to maximum body size
CostEstimate:
SummaryCount:
8 byte floating
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:
DataLen:
Unused:
ColumnName:
ColumnFormat:
ColumnTitle:
2 byte unsigned integer
8 bytes
2 bytes
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
two byte unsigned integer plus the number of bytes specified by that integer
For non-decimal columns, the following occur:
DataType:
DataLen:
CharacterType:
ColumnInformation
ColumnName:
ColumnFormat:
ColumnTitle:
2 byte unsigned integer
8 bytes
1 byte unsigned integer
8 bits
2 to 92 bytes of characters
2 to 92 bytes of characters
2 to 182 bytes of characters
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 447
Chapter 15: Parcels for Basic ApplicationsParcel 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:
• 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.
Table 67: PrepInfoX Data Types
If the data type is... Then the code is...
Not character data 0
Latin1 1
Unicode 2
KanjiSJIS 3
Graphic 4
Kanji1 5
448 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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 SalaryWITH COUNT (DeptNo) BY DeptNo;
This statement produces a PrepInfoX parcel with the following byte sequence:
Parcel flavor is 86 with length 12440 4D BE B8 51 EB 85 1E 00 02 00 01 01 C0 00 0000 00 00 00 00 0C 01 80 00 04 D5 81 94 85 00 05E7 4D F1 F2 5D 00 04 D5 81 94 85 00 02 01 F1 0000 00 00 00 00 00 04 00 00 00 00 00 06 60 4D F1F0 5D F9 00 0B E2 E4 D4 4D C4 85 97 A3 D5 96 5D01 E5 00 00 00 0F 00 00 00 02 00 00 00 00 00 0AE9 E9 E9 6B E9 E9 F9 4B F9 F9 00 0B 53 75 6D 2853 61 6C 61 72 79 29 00 01 01 F1 00 00 00 00 0000 00 04 00 00 00 00 00 06 E2 E4 D4 4D E2 81 9381 99 A8 5D 00 0B 53 75 6D 28 44 65 70 74 4E 6F29
The parcel fields, above, translate as follows (an explanation of each acronym follows):
CE CE CE CE CE CE CE CE SC SC CC CC DT DT DL DLDL DL DL DL DL DL CS CI NL NL CN CN CN CN FL FLCF CF CF CF CF TL TL CT CT CT CT CC CC DT DT DLDL DL DL DL DL DL DL CS CI NL NL FL FL CF CF CFCF CF CF TL TL CT CT CT CT CT CT CT CT CT CT CTDT DT DL DL UU UU NL NL FL FL CF CF CF CF CF CFCF CF CF CF TL TL CT CT CT CT CT CT CT CT CT CTCT CC CC DT DT DL DL CS CI NL NL FL FL CF CF CFCF CF CF TL TL CT CT CT CT CT CT CT CT CT CT 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 ApplicationsParcel Descriptions
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.
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.
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
FlavorParcel Body Length Parcel Body Fields
28 0 none
In this mode... Nulls are...
Record not explicitly identified in the Record parcel.
450 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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).
Indicator explicitly identified.
In this mode... Nulls are...
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 451
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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.
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:
• The Data Field contains items with characteristics as follows:
• The order of the items.
FlavorParcel Body Length Parcel Body Fields
10 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
If a bit is... Then the value of the corresponding data item is...
ON null.
OFF not null.
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.
452 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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).
FlavorParcel Body Length Parcel Body Fields
10 1 to maximum body size
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 ApplicationsParcel 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 ApplicationsParcel Descriptions
Parcel Data
The following information applies to the RecStart parcel.
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).
FlavorParcel Body Length Parcel Body Fields
27 0 none
Flavor Mnemonic
TRDSPBRT
Field Length Value
172 TRDSPFRT PBRTRNUM 8byte unsigned integer. row number contained in the first response parcel returned for this statement.
A value of zero corresponds to parcels before those for the actual first row's data (Success, for example) while a value one greater then the number of rows corresponds to parcels after those for the actual last row's data (EndRequest).
PBRTDB 2byte unsigned integer, plus the number of bytes specified by that integer
Stored procedure database, consisting of the length in bytes of the name, followed by that name in characters from the current session character set. The maximum length of a name may be obtained using the DBCHQE SQL-limits query.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 455
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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.
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
Flavor Mnemonic
TRDSPBRT
Field Length Value
Table 68: ResultSummary Parcel Information
FlavorParcel Body Length Parcel Body Fields
171 24 to maximum parcel size
Activity Count:
Statement No:
Field Count:
Activity Type:
8 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer See “Activity Type” on page 425 for the possible activity types
456 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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:
The Warning Message extension consists of the following 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
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).
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.
Table 68: ResultSummary Parcel Information (continued)
FlavorParcel Body Length Parcel Body Fields
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 457
Chapter 15: Parcels for Basic ApplicationsParcel 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.
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.
SizeStart
Purpose
Delimits the start of a sequence of Size parcels that specifies the maximum size of each field returned in Field Mode.
FlavorParcel Body Length Parcel Body Fields
26 2 MaxFldSize: 2 byte unsigned integer
FlavorParcel Body Length Parcel Body Fields
25 0 none
458 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Usage Notes
This parcel is generated by the Teradata server.
Parcel Data
The following information applies to the SizeStart parcel.
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.
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:
FlavorParcel Body Length Parcel Body Fields
24 0 none
FlavorParcel Body Length Parcel Body Fields
169 6 to maximum parcel size
Self-defining extensions: Six or more bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 459
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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
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.
460 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel 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 ApplicationsParcel Descriptions
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.
Table 69: Full-layout Fields for Responses (continued)
Field Length Description
462 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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.
Table 69: Full-layout Fields for Responses (continued)
Field Length Description
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 463
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
When at least one more byte is present, the first such byte is defined as follows:
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.
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:
• '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.
Table 69: Full-layout Fields for Responses (continued)
Field Length Description
464 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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.
Table 70: PBTIFDT Additional Data Types
NameType 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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 465
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Statistic-layout
The Statistic-layout is used for Estimated-processing information. Table 8 shows the Statistic-layout fields.
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.
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.
Table 72: Statistic-layout fields
Field Length Description
PBTISEE 8 byte unsigned integer
The estimated execution time for the statement, in milliseconds.
466 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
Usage Notes
This parcel is generated by the Teradata Database.
Parcel Data
The following information applies to the StatementInformationEnd parcel.
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.
Field Notes
The following notes apply to Success fields.
FlavorParcel Body Length Parcel Body Fields
170 0 none
FlavorParcel Body Length Parcel Body Fields
8 14 to 269 StatementNo:
ActivityCount:
WarningCode:
FieldCount:
ActivityType:
WarningLength:
WarningMsg:
byte unsigned integer
4 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
2 byte unsigned integer
0 to 255 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 467
Chapter 15: Parcels for Basic ApplicationsParcel 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.
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.
FlavorParcel Body Length Parcel Body Fields
21 0 none
468 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 15: Parcels for Basic ApplicationsParcel Descriptions
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.
Field Notes
WithId is the summary number (1-n) for this WITH clause.
FlavorParcel Body Length Parcel Body Fields
20 0 none
FlavorParcel Body Length Parcel Body Fields
33 2 WithID: 2 byte unsigned integer
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 469
Chapter 15: Parcels for Basic ApplicationsParcel 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.
Parcel Header
There are two formats of parcel headers. The parcel headers are symbolically defined in the TC2XPH file. The format of the first is:
2417A009
Header Body
2417A010
Flavor
Fla
g
0 2 4
Length
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 471
Chapter 16: Parcels for Advanced ApplicationsParcel Header
The format of the second is:
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.
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.
Table 74: Alternate Parcel Header (TPH1)
Field Name Offset Length Description
PH1FLAVR (FLAVOR-FLAGfor 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.
2417A011
Unused
Fla
g
0 2 4 8
Flavor Length
472 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel 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.
Parcel Types
There are two parcel types:
The following two sections describe request and response parcels.
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 type... Is generated for...
Request requests sent to the Teradata Database
Response responses sent from the Teradata Database to a client
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 473
Chapter 16: Parcels for Advanced ApplicationsParcel 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.
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 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.
Table 77: Response Parcel Flavors, Names, And Uses
Flavor Parcel Name Use
121 CursorDBC Returns cursor information
474 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
Parcel Descriptions
The following alphabetized sections describe parcels generated by advanced applications and the Teradata Database.
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.
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
Table 77: Response Parcel Flavors, Names, And Uses (continued)
Flavor Parcel Name Use
• 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
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
Parcel Data
The following table lists field information for the CursorDBC parcel.
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.
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.
Flavor Field
Parcel Body Length Parcel Body Fields
121 10 Processor:
Row:
2 bytes
8 bytes
Flavor Field
Parcel Body Length Parcel Body Fields
120 14 Processor:
Row:
Request
2 bytes
8 bytes
4 bytes
476 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel 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.
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.
Flavor Field Parcel Body Length Parcel Body Fields
3 1 to maximum body size
Data: 1 to maximum body size bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 477
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
Parcel Data
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.
FlavorParcel Body Length Parcel Body Fields
71 6 to maximum body size
FieldCount:
Pair 1:
.
.
.
Pair i:
.
.
.
Pair n:
Data Type:
Length:
Data Type:
Length:
Data Type:
Length:
2 bytes
2 bytes
2 bytes
2 bytes
2 bytes
2 bytes
2 bytes
478 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
Usage Notes
DataInfoX is not returned if the statement was ECHO.
Parcel Data
The following table lists field information for DataInfoX.
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.
FlavorParcel Body Length Parcel Body Fields
146 6 to maximum body size
FieldCount:
Pair 1:
.
.
.
Data Type:
Length:
2 bytes
2 bytes
2 bytes
Pair i:
.
.
.
Pair n:
Data Type:
Length:
Data Type:
Length:
2 bytes
2 bytes
2 bytes
2 bytes
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 479
Chapter 16: Parcels for Advanced ApplicationsParcel 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.
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.
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.
FlavorParcel Body Length Parcel Body Fields
141 0 none
FlavorParcel Body Length Parcel Body Fields
143 0 none
480 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
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.
FlavorParcel Body Length Parcel Body Fields
13 1 to maximum body size
ReqText
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 ApplicationsParcel 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).
Whether the null indicator bit is ON or OFF, the length of the corresponding data item is meaningful.
For example,
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.
If a bit is... Then the value of the corresponding data item is...
ON null.
OFF not null.
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).
482 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
Parcel Data
The following information applies to the IndicReq parcel.
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.
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.
FlavorParcel Body Length Parcel Body Fields
69 1 to maximum body size
ReqText
FlavorParcel Body Length Parcel Body Fields
140 1 to maximum body size
Data: 1 to maximum body size
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 483
Chapter 16: Parcels for Advanced ApplicationsParcel 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.
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.
FlavorParcel Body Length MultipartIndicData Parcel Fields
142 1 to maximum body size
Data: 1 to maximum body size bytes
484 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel 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.
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.
FlavorParcel Body Length Parcel Body Fields
148 1 to maximum body size
ReqText
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 485
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
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:
• E- specifies that the request should be executed.
• A binary zero in this field is interpreted as an E.
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
486 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel 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 ApplicationsParcel 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:
• 'N', the default, indicates the request may not change the session userid.
488 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel 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.
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.
FlavorParcel Body Length Parcel Body Fields
1 1 to maximum body size
ReqText
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 489
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
Parcel Data
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.
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:
FlavorParcel Body Length Parcel Body Fields
129 2 Print: 1 byte (unused)SaveSPL: 1 byte
FlavorParcel Body Length Parcel Body Fields
169 6 to maximum parcel size
Self-defining extensions: Six or more bytes
490 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel 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 ApplicationsParcel 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.
When at least one more byte is present, the first such byte is defined as follows:
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.
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
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.
492 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
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.
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.
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).
Field Length Description
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 493
Chapter 16: Parcels for Advanced ApplicationsParcel 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.
When at least one more byte is present, the first such additional is defined as follows:
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.
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).
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.
494 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 16: Parcels for Advanced ApplicationsParcel Descriptions
StatementInformationEnd Returns
Purpose
Indicates that no more StatementInformation parcels (flavor 169) exist.
Parcel Data
The following information applies to the StatementInformationEnd parcel.
FlavorParcel 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 ApplicationsParcel 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 ProceduresSQL Stored Procedures
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... 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.
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 ProceduresSQL Stored Procedures
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.
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
If this response parcel is returned... Then...
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 499
Chapter 17: Stored ProceduresExternal 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 D8XIID(4),=A(D8XIIIRX) Set EyecatcherXC D8XINEXT(4),D8XINEXT No more extensionsMVC D8XISIZE(4),=A(D8XIHDSZ+D8XILMSZ+2) Ext. lengthMVI D8XILVL,D8XIL64MVC D8XILTYP(2),=H'129' Parcel flavorMVC D8XILLEN(2),=Y(D8XILMSZ+2) Parcel lengthMVI D8XILDAT,C'P' "PRINT" compile optionMVI 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 ProceduresDynamic 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 ProceduresDynamic 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 ModuleRequest 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 ElementLength (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 ModuleResponses
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.
Logoff flag 1 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.
String ElementLength (bytes) Description
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 505
Chapter 18: Resolver Base ModuleResponses
The record parcel includes the following:
• 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:
• 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.
Flavor Field
Length Field Parcel Body Fields
10 11 to 40 SessionNo:
StringLength:
RunUnitID:
4 byte unsigned integer
2 byte unsigned integer
1 to 30 bytes
Flavor Field
Length Field Parcel Body Fields
10 7 to 36 StringLength:
CoordinatorID:
2 bytes
1 to 30 bytes
506 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 ProtocolEnabling 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.
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,
To use this option as the default mode...Specify this setting in IBO2PC in the system parameter block (HSHSPB)...
2PC Y
non-2PC N
508 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 19: 2PC ProtocolUsing 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 ProtocolIn-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.
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:
• 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.
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.
510 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Chapter 19: 2PC ProtocolCLIv2 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 ProtocolCLIv2 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
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.
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.
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 513
Appendix A: How to Read Syntax DiagramsSyntax 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:
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:
If you can choose from more than one entry, the choices appear vertically, in a stack. The first entry appears on the main path:
Optional Entries
You may choose to include or disregard optional entries. Optional entries appear below the main path:
If you can optionally choose from more than one entry, all the choices appear below the main path:
FE0CA002
A
A
FE0CA003
SHOW
FE0CA005
SHOW
VERSIONS
CONTROLS
FE0CA004
SHOW
CONTROLS
514 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Appendix A: How to Read Syntax DiagramsSyntax Diagram Conventions
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:
If the string text includes a single quote or a blank space, the string appears in double quotes:
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.
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:
JC01A010SHARE
READ
ACCESS
JC01A004
'msgtext'
JC01A005
''abc'd"
''abc d"
FE0CA042
SHOW
CONTROL
CONTROLS
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 515
Appendix A: How to Read Syntax DiagramsSyntax Diagram Conventions
Read loops from right to left.
The following conventions apply to loops:
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.
Loop Convention Description
A maximum number of entries is allowed.
The number appears in a circle on the return path.
In the example, you may type cname a maximum of 4 times.
A minimum number of entries is required.
The number appears in a square on the return path.
In the example, you must type at least three groups of column names.
A separator character is required between entries.
The character appears on the return path.
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.
JC01B012
(
, 4
cname )
, 3
516 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Appendix A: How to Read Syntax DiagramsSyntax 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:
Multiple Legitimate Phrases
In a syntax diagram, it is possible for any number of phrases to be legitimate:
In this example, any of the following phrases are legitimate:
• dbname
• DATABASE dbname
• tname
• TABLE tname
• vname
• VIEW vname
LOCKING excerpt
where_cond
A
cname
excerpt
JC01A014
A
HAVING con
,
col_pos
,
JC01A016
DATABASE
dbname
TABLE
tname
VIEW
vname
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 517
Appendix A: How to Read Syntax DiagramsSyntax Diagram Conventions
Sample Syntax Diagram
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.
JC01A018
viewnameCREATE VIEW AS
cname
A
C
CV
,
LOCKING
LOCK
ACCESSA
DATABASE
dbname
TABLE
tname
VIEW
vname
FOR
IN
B
SHARE
READ
WRITE
EXCLUSIVE
EXCL
MODE
FROMB SEL C
.aname
expr
,
tname
,
qual_cond
qual_cond
WHERE cond
cname
,
col_pos
,GROUP BY
HAVING cond ;
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 A special user responsible for allocating resources to a community of users.
AP 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 Symmetric multi-processing
522 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) One of the primary operating systems for large IBM computers.
524 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
Numerics2PC 207
Coordinator’s Participant Interfacedefined 509
field 207in-doubt resolution 510session, starting Connect function 508using in CLIv2 application 507
AAbort function 63, 263
summary of uses 240abort, crash-related 371ABT function. See Abort functionaccess rights
security considerations 30Anticipated Number of Concurrent Sessions field 73Assembler. See IBM Assemblerauthorization
security considerations 30
Bbe 47Buffer, request. See Request bufferBuffer, response. See Response buffer
CC2S Conversion field 87, 167Call Level Interface version 2. See CLIv2Call routine, DBCHCL 244Change Options field 75
Parcel Mode Fetch 131processing options 76setting 49using 49
change_opts 75Character Set Pointer field 78Cleanup routine 271CLI routine
DBCHCL 244DBCHCLN 271DBCHINI 242optional
summary of uses 273summary of uses 240
CLI0200, return code 507CMD function. See Command functionCOBOL
DBCAREA-0-REQ-ID 127DBCAREA-CHANGE-OPTS 75DBCAREA-CUR-REQ-BUF-LEN 84, 87DBCAREA-CUR-RESP-BUF-LEN 87DBCAREA-EYECATCHER 93DBCAREA-FET-DATA-PTR 94DBCAREA-FET-MAX-DATA-LEN 95DBCAREA-FET-PARCEL-FLAVOR 96DBCAREA-FET-RET-DATA-LEN 97DBCAREA-HSISVC-TIME 168DBCAREA-I-REQ-ID 101DBCAREA-IWPF-FUNCTION 135DBCAREA-KEEP-RESP 103DBCAREA-LOC-MODE 107, 108DBCAREA-LOGON-LEN 109DBCAREA-LOGON-PTR 110DBCAREA-MAX-NUM-SESS 73DBCAREA-MSG-LEN 123DBCAREA-MSG-TEXT 123DBCAREA-O-DBCPATH 128DBCAREA-O-DBC-SESS-ID 129DBCAREA-O-HOST-ID 128DBCAREA-OPEN-REQS 125DBCAREA-PARCEL-MODE 130DBCAREA-REQ-BUF-LEN 137DBCAREA-REQ-LEN 138DBCAREA-REQ-PROC-OPT 143DBCAREA-REQ-PTR 142DBCAREA-RESP-BUF-LEN 146DBCAREA-RUN-LEN 156DBCAREA-RUN-PTR 158DBCAREA-SESS-STATUS 164DBCAREA-SET-CHAR-SET 165, 175, 176, 177, 178DBCAREA-TOTAL-LEN 180DBCAREA-TWO-PHASE-COMMIT 207
Codeerror 53, 367failure 53, 367return 53, 54
Command function 260summary of uses 240
CON function. See Connect functionConnect function
ReturnCode address 247
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 525
Index
summary of uses 240Connect Type field 81Coordinator’s Participant Interface 509Country Id 84
changing 85CPI. See Coordinator’s Participant InterfaceCrash 369CRQ 240cur_req_buf_len 84, 87cur_resp_buf_len 87Current Request Buffer Length field 86Current Response Buffer Length field 87
DData parcel 477data structures, supported 32Data type
indicator mode 441, 453IndicData parcel 482internal format 35record mode 454
DataInfo parcelECHO statement 429, 477
Date Form field 89DB02FBU 183DBC/SQL, partition 33DBCACNX 230DBCAID 93DBCAIRX 209, 229
logical sections 209DBCAIRXC 230DBCAIRXH 229, 230DBCAIRXP 230DBCAREA 67
allocating 243as data structure 47DBCHINI and 242extension
C definitions for 229COBOL definitions for 229, 230IBM Assembler definitions for 229, 230PL/I definitions for 229, 230
Field Descriptions 67logical sections 67multi-session 48multi-thread 48preparing to use 47using 48
DBCAREA.Hchange_opts 75charset_type 165, 175, 176, 177, 178cur_req_buf_len 84, 87cur_resp_buf_len 87
dbcLevel 107eyecatcher 93fet_data_ptr 94fet_parcel_flavor 96fet_ret_data_len 97hsisvc_time 168i_req_id 101iwpf_function 135keep_resp 103loc_mode 108logon_len 109logon_ptr 110max_num_sess 73msg_len 123msg_text 123o_dbc_sess_id 129o_dbcpath 128o_host_id 128o_req_id 127open_reqs 125parcel_mode 130req_buf_len 137req_proc_opt 143req_ptr 142req-len 138resp_buf_len 146run_len 156run_ptr 158sess_status 164tell_about_crash 170total_len 180two_phase_commit 207two_resp_bufs 183x_elm_type 215
DBCAREA-CHANGE-OPTS 75DBCAREA-CUR-REQ-BUF-LEN 84, 87DBCAREA-CUR-RESP-BUF-LEN 87DBCAREA-EYECATCHER 93DBCAREA-FET-DATA-PTR 94DBCAREA-FET-MAX-DATA-LEN 95DBCAREA-FET-PARCEL-FLAVOR 96DBCAREA-FET-RET-DATA-LEN 97DBCAREAH 229DBCAREA-HSISVC-TIME 168DBCAREA-I-REQ-ID 101DBCAREA-KEEP-RESP 103DBCAREA-LOC-MODE 107, 108DBCAREA-LOGON-LEN 109DBCAREA-LOGON-PTR 110DBCAREA-MAX-NUM-SESS 73DBCAREA-MSG-LEN 123DBCAREA-MSG-TEXT 123DBCAREA-O-DBC-SESS-ID 129DBCAREA-O-HOST-ID 128
526 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
DBCAREA-O-PATH 128DBCAREA-OPEN-REQS 125DBCAREA-O-REQ-ID 127DBCAREAP 229DBCAREA-PARCEL-MODE 130DBCAREA-REQ-BUF-LEN 137DBCAREA-REQ-LEN 138DBCAREA-REQ-PROC-OPT 143DBCAREA-REQ-PTR 142DBCAREA-RESP-BUF-LEN 146DBCAREA-RUN-LEN 156DBCAREA-RUN-PTR 158DBCAREA-SESS-STATUS 164DBCAREA-TOTAL-LEN 180DBCAREA-TWO-PHASE-COMMIT 207DBCHCL 244
multi-session 42return code 245summary of uses 240Wait For Response 245
DBCHCL FunctionsCMD 260CON 247DSC 270ERQ 267FET 265IRQ 252IWPF 255REW 269RSUP 250
DBCHCLN 271alternate name for 271summary of uses 240
DBCHCN. See DBCHCLNDBCHIN. See DBCHINIDBCHINI 67
alternate name for 242initializing DBCAREA 242return code 244summary of uses 240Total Length field 242
DBCHMEsummary of parameters 274summary of uses 273
DBCHMECMaster event control block routine 276, 278summary of parameters 274summary of uses 273
DBCHPE. See DBCHPECDBCHPEC
alternate name for 279post ECB routine 279summary of parameters 274summary of uses 273
DBCHQEcontext area 289query environment 289return code 289
DBCHQEPC definitions for 230, 231COBOL definitions for 230, 231IBM Assembler definitions for 230, 231PL/I definitions for 230, 231
DBCHQEPC 229, 230, 231DBCHQEPH 230, 231DBCHQEPP 230, 231DBCHSA. See DBCHSADDBCHSAD
alternate name for 280return code 280summary of parameters 275summary of uses 273
DBCHUECreturn code 281, 283summary of parameters 275summary of uses 274user provided ECB 281, 283UserECB address 281, 283
DBCHUEPC 231DBCHUEPH 231DBCHUEPP 231DBCHWAT
alternate name for 284multi-session 42return code 284summary of parameters 275uses 274
DBCHWLsummary of parameters 275
DBCHWT. See DBCHWATDBCIFBRL 146DBCIRBRL 137DBCISMAX 73DBCMSG 124DBCMSGL 123DBCMSGRD 156DBCNILSL 109DBCNILSP 110DBCNIRSL 156DBCNIRSP 158DBCOFBLA 84, 87DBCOFLG1 164DBCOREQN 127DBCOSID 128DBCOSILH 128DBCOSISN 129DBCOSITM 128DBCOSITV 128
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 527
Index
DBCSIZE 180DBCTSTMP 168DBFIWPF, 2PC and 508DBFOPFLV 96DBFXFDP 94DBOBSYW 203DBOBTPM 130DBOCRSW 201, 202DBOCRTL 170DBOFLOC 107, 108DBOFUNT 143DBOKRSP 103DBOSCSP 165, 175, 176, 177, 178DBOSETO 75DBRIPF 135DBRIRQL 138DBRIRQP 142DBROREQC 125Describing User-defined Character Sets 407Disconnect function 64, 270
summary of uses 240DSC function. See Disconnect function
EECHO statement
DataInfo parcel 429, 477PrepInfo parcel 444, 447record mode 454Record parcel 454
Element Length fieldDBCAIRX 215
Element Type field and 215Element Type field
DBCAIRX 215Element Length field and 215Pointer Element Address field and 212Pointer Element Length field and 213
ElicitData parcelLOBs 38
ElicitName parcelLOBs 38
End Request function 267summary of uses 240
EndRequest parcelindicator mode 347
EndStatement parcelindicator mode 347
Environment query. See DBCHQEERQ function. See End Request functionError code 367Error parcel 244, 435
KeepResp parcel and 435Resp parcel and 435
response sequence 364Event control block (ECB)
master routine. See DBCHMEmaster routine. See DBCHMECpost routine. See DBCHPECuser provided. See DBCHUEC
Extension Pointer field 92DBCAIRX and 209
Extensions, DBCAREA 209Eyecatcher field
DBCAIRX 216DBCAREA 93
FFailure code 53, 367Failure parcel 244
logging on and 350response sequence 364session control 350
FET function. See Fetch functionfet_data_ptr 94fet_max_data_len 95fet_parcel_flavor 96fet_ret_data_len 97Fetch Data Pointer field 93
Fetch Returned Date Length 98locate mode, relation to 109
Fetch function 60, 265summary of uses 240
Fetch Maximum Data Length field 95locate mode, relation to 109
Fetch Parcel Flavor field 96locate mode, relation to 109
Fetch Returned Data Length field 97locate mode 109Variable Length Fetch
relation to 197Fields in DBCAIRX
Data Address 212Data Length 213Element Length 215Element Type 215Eyecatcher 216Next Pointer 218Total Length 219Total Size 220
Fields in DBCAREA2PC 207C2S conversion 87change options 75character set pointer 78connect type 81current request buffer length 86
528 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
current response buffer length 87date form 89extension pointer 92eyecatcher 93fetch data pointer 93fetch maximum data length 95fetch parcel flavor 96fetch returned data length 97function 98input CLIv2 request id 100input CLIv2 session id 100keep response 102locate mode 108logon length 109logon pointer 110Max-decimal-returned 113maximum parcel 114message length 123message text 123open requests 124output CLIv2 request id 127output DBC session id 129output host id 128output TDP path 128parcel mode fetch 130protocol-function 135request buffer length 137request length 138request mode 139request pointer 142request processing option 143Request-token 145response buffer length 145response mode 146return code 149return time 154route description codes 156run length 156run pointer 158S2C conversion 167Save Response Buffer 159Segment Data 160Session Status 164Set Character Set 165TDP request number 169TDP-receipt-timestamp 168TDPWAIT Time 171tell about crash 170, 371Time1-status 174Time2-status 175Time3 172Time3-status 176Time4 171, 173Time4-status 177
Time5 174Time5-status 178total length 180Transaction Semantics 180Two Response Buffers 183Use Presence Bits 186Using Data Length 189Using Data Pointer field 190Variable Length Fetch 196Variable Length Request 198wait across crash 201, 371wait for response 203, 371
fields in DBCAREA 67Finding Files on the Release Tape
DBCAIRX 229DBCHMEP 230DBCHQER 231DBCHUEP 231HSHSPB 231
format, dataIBM mainframe, internal 35
Functionabbreviations 67Abort 240, 263Command 240, 260Connect 240, 247Disconnect 240, 270End Request 240, 267Fetch 240, 265Initiate Request 240, 252IWPF 240, 255Rewind 240, 269RunStartUp 240, 250
Function field 98
HHSHSPB 33
defaults 49MVS 233VM 233
hsisvc_time 168
Ii_req_id 101IBM Assembler 47
DBCAID 93DBCIFBRL 146DBCIRBRL 137DBCISMAX 73DBCMSG 124DBCMSGL 123DBCMSGRD 156DBCNILSL 109
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 529
Index
DBCNILSP 110DBCNIRSL 156DBCNIRSP 158DBCOFBLA 84, 87DBCOREQ 127DBCOSID 128DBCOSILH 128DBCOSITM 128DBCOSITV 128DBCOTSS1 175DBCOTSS2 176DBCOTSS3 176DBCOTSS4 177DBCOTSS5 178DBCPSOSN 129DBCSIZE 180DBCTSTMP 168DBFIPACT 132DBFIPSNM 134DBFIPVAL 134DBFOPFLV 96DBFXFDP 94DBO2FBU 183DBO2PC 207DBOBSYW 203DBOBTPM 130DBOCRSW 201, 202DBOCRTL 170DBOFLOC 107, 108DBOFUNT 143DBOKRSP 103DBOSCSP 165DBOSETO 75DBRIPF 135DBRIRQL 138DBRIRQP 142DBROREQC 125DNCOFLG1 164MVS 128VM 128
implied waiting 47Indicator mode 440, 452
DataInfo parcel 441, 453null indicator 440, 452Response parcel 440, 452response sequence 348SELECT statement and 441, 453
IndicData parcel, data type 482In-doubt resolution, 2PC 510Initialize routine, DBCHINI 242Initiate Request function 59, 252
summary of uses 240Initiate With Protocol-Function
summary of uses 240
Initiate With Protocol-Function function 255Input CLIv2 Request Id field 100
Output CLIv2 Request Id 127Input CLIv2 Session Id field 100
Output Field Id 126Input TDP Path field 101INSERT statement 38internal format
data type 35mainframe 35
IRQ function. See Initiate Request functionISO 3166-1
Country Id 84ISO 639
Language Id standard 105IWPF function. See Initiate With Protocol-Functioniwpf_function 135
KKeep Response field 102keep_resp 103KeepResp parcel
Error parcel, relation to 435
LLanguage
message module names 413variant
specify with Country Id 84Language Id
described 105LANG and Country keywords 415
large objects 38Level 107loc_mode 107, 108Locate Mode field 108
Fetch Maximum Data Length, relation to 96logical structure 30Logon
unsuccessfulError parcel 350Failure parcel 350
Logon Length field 109Logon pointer field 110logon_len 109logon_ptr 110LOGON-LEN 109
MMacro
message definition 415mainframe
530 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
format, internal 35max_num_sess 73Maximum Parcel field 114Message Definition
file described 232, 413macro described 415
message definitions 33Message Length field 123Message modules 413Message Text field 123Move area 341msg_len 123msg_text 123multi-session management
concurrent requests 42DBCHCL 42DBCHWAT 42
NNext Pointer field
DBCAIRX 218NullField parcel 441
Oo_dbc_sess_id 129o_host_id 128o-dbcpath 128onzero 53Open Requests field 124
Keep Response 104open_reqs 125operation, parallel 40o-req-id 127Output CLIv2 Request Id field 127
Input CLIv2 Request Id, relation to 101Output CLIv2 Session Id field
Input CLIv2 Session Id, relation to 100Output DBC Session Id field 129
Output Session Id, relation to 126Output Host Id 128Output TDP Path 126
field 128
PParcel
body 420Data 477Error 364, 435Failure 364flavor 419header 419NullField 441
overview 419Record 439, 450, 451Request 420, 473Resolver Base Module 503Response 421sequence 364structure 471type 419, 420, 473
Parcel Mode Fetch field 130Fetch Maximum Data Length, relation to 96Fetch Parcel Flavor, relation to 97locate mode, relation to 108wait for response, relation to 203
parcel_mode 130partition
DBC/SQL 33performance monitor 33Resolver Base Module 33
password, expiration 57passwords
security considerations 30PL/I
CHANGE_OPTS 75CUR_REQ_BUF_LEN 84, 87CUR_RESP_BUF_LEN 87EYECATCHER 93FET_DATA_PTR 94FET_MAX_DATA_LEN 95FET_PARCEL_FLAVOR 96FET_RET_DATA_LEN 97HSISVC Time 168I_REQ_ID 101IWPF_FUNCTION 135KEEP_RESP 103LOC_MODE 107, 108LOGON_LEN 109LOGON_PTR 110MAX_NUM_SESS 73MSG_LEN 123MSG_TEXT 123O_DBC_SESS_ID 129O_DBCPATH 128O_HOST_ID 128O_REQ_ID 127OPEN_REQS 125PARCEL_MODE 130REQ_BUF_LEN 137REQ_LEN 138REQ_PROC_OPT 143REQ_PTR 142RESP_BUF_LEN 146RUN_LEN 156RUN_PTR 158SESS_STATUS 164
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 531
Index
SET_CHAR_SET 165, 175, 176, 177, 178TELL_ABOUT_CRASH 170TOTAL_LEN 180TWO_PHASE_COMMIT 207TWO_RESP_BUFS 183
Pointer Element Address fieldDBCAIRX 212
Pointer Element Length field, DBCAIRX 213Positioning-action 132, 133PrepInfo parcel, ECHO statement 444, 447preprocessors 30prerequisites 47product version numbers 3Protocol-Function field 135
RRecord mode
data type 454ECHO statement 454null 454requests
issuing 355Response parcel 440, 452, 454response sequence 345
Record parcel 439, 450, 451ECHO statement 454indicator mode. See Indicator mode
Record Parcel, Record mode. See Record moderelease tape
C files 229COBOL files 229IBM assembler files 229PL/I files 229z/OS and z/VM 233
Release TapesDBCAREA 229
req_buf_len 137req_len 138req_proc_opt 143req_ptr 142request
concurrent 42multiple, managing 40multi-statement 40Teradata SQL, submitting 59
Request bufferCurrent Request Buffer Length field 339Request Buffer Length field 339
Request Buffer Length 137Request Length field 138Request Mode 140Request mode 139Request Pointer field 142
Request Processing Option 143Request-token field 145Resolver Base Module
parcel 503partition 33
Resp parcelError parcel, relation to 435
resp_buf_len 146Response
sequence 342, 504, 505indicator mode 348Record mode 345
Response bufferCurrent Response Buffer Length field 341Keep Response field 340Response Buffer Length field 341Two Response Buffers field 340Wait For Response field 341
Response Mode 146Response parcel, overview 421Return code 53
2PC 507busy 245CLI0200 507DBCHCL 54DBCHWAT 54Fetch Returned Data Length field 54timing 54
Return Code field 149relation to Message Text 123
Return Time field 154HSISVC Time 169SRBSCHED Time 174TDPDBI Time 173TDPDBO Time 172TDPWAIT Time 171TDPXMM Time 173
ReturnCode addressConnect function 247DBCHCL 245
REW function. See Rewind functionRewind function 62, 269
summary of uses 240Route Description Codes field 156Routine 239
DBCHCL 244DBCHCLN 271DBCHMEC 273DBCHPEC 273DBCHSAD 273DBCHUEC 274DBCHWAT 274optional
summary of uses 273
532 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems
Index
parameters 241summary of uses 240
RSUP function. See RunStartUp functionRun Length field 156run pointer field 158run_len 156run_ptr 158RunStartUp function 57, 250
summary of uses 240
SSave Response Buffer
fieldVariable Length Fetch 159
security considerations 29Segment Data
option described 160SELECT statement 38sess_status 164Session
establishing 55terminating 64
Session controlFailure parcel 350
Session pool, 2PC 509session status 164Set Character Set 165software releases
supported 3SP Options parcel
described 489SPB. See System Parameter BlockSpool file
Keep Response field 104maintaining 341
StatementINSERT 38SELECT 38
Status session 164stored procedures
described 497Success parcel
indicator mode 347System Parameter Block
HSHSPB 233system parameter block
HSHSPB 33
TTDP
relationship to Teradata Database 30TDP command, issuing 260, 510TDP Request Number field 169
TDP-receipt-timestamp 168TDPXMM Time 173Tell About Crash field
Wait Across Crash, relation to 202tell about crash field 170Teradata server
communicating with 33Teradata SQL
response sequence 364Teradata SQL statement
INSERT 38SELECT 38
Time1 171Time3 field 172Time4 171Time5 field 174Total Length
fieldDBCAIRX 219DBCAREA 180
Total Size field, DBCAIRX 220total_len 180Transaction Semantics 180Two Response Buffers field 183
Response Buffer Length field, relation 146two_phase_commit 207
UUse Presence Bits field 186
Using Data Length 191Using Data Pointer 192, 195Variable Length Request 200
Using Data Length 189Use Presence Bits, relation to 187
Using Data Pointer 190Use Presence Bits 187
VVariable Length Fetch 196
Fetch Maximum Data Length 96Variable Length Request 198
fieldRequest Mode 140setting 51Using Data Length 192Using Data length 190, 194
version numbers 3
WWait Across Crash field 201wait across crash field
tell about crash, relation to 170
Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems 533
Index
Wait For Responsefield 164, 203
DBCHME 276option 47
534 Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems