Teradata Call-Level Interface Version 2...This book provides information about Teradata® Call-Level...

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.

mailto:[email protected]

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

http://www.info.teradata.com

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


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


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.




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.


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.


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.


2 Under Print & CD Publications, click How to Order.

3 Follow the ordering instructions.







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.



http://www.teradata.com/t/resources

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


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


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


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


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


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


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


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


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


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


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


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


Table of Contents

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525


Table of Contents


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


List of Figures


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


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 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


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


List of Tables


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.


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.


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


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


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:



• 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



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.



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)


year 1900–( ) 10000× month 100×( ) day+ +



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)


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.



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



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


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.



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.



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


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


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.



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.”


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


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.



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.



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.”



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.



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


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.


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.


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:


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:


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.


Chapter 2: Session OperationsExecuting a RunStartUp Request

To run a startup string once the session is established, an application must perform the following steps:


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-token



• Using-data-count

• Using-data-length-vector

• Using-data-pointer-vector

• Data-encryption



• 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.


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:


a Set the Function to Initiate Request.


c Set the Request Pointer.

d Set the Request Length.

e Optionally set the following:

• Positioning-action

• Positioning-statement-number

• Positioning-value





• Request-token



• Using-data-count

• Using-data-length-vector

• Using-data-pointer-vector

• Data-encryption



• 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.



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:


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



2 Call DBCHCL to perform the Fetch function.


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.”



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:


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.


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.



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:


a Set the Function to Rewind.






2 Call DBCHCL to perform the Rewind function.


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.



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:


• 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:



2 Call DBCHCL to perform the End Request function.


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:


a Set the Function to Abort.







Return Code Results.

0 The request is successfully ended.

anything else Process the return code and DBCAREA message and resubmit the End Request.


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:


a Set the Function to Disconnect.


c Optionally set the following:



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.


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.


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



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)


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 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



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:


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



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)




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





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





When the Level field is not binary '0', the following fields are also present:

Table 3: Order of the Enlarged DBCAREA When Level > 0


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


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)


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


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'


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.



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



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


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


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



• “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


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


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




• 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


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)


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.


Chapter 3: DBCAREAContinued-characters-state


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


Continued-characters-state is used by... To...

applications write


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.


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.


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


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:


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


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)


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.


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:


2 Change the value for C2S Conversion as follows:


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


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


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


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:


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.


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


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


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.


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


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


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



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)


Chapter 3: DBCAREAFetch Maximum Data Length


• 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)


Chapter 3: DBCAREAFetch Parcel Flavor

Review the following conditions before calling DBCHCL for any of the following functions:

• Connect

• RunStartUp


• Command


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


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


• Command


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)


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


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


Y N Y Nothing. These settings produce an error.

Code Operation

1 Connect

2 Disconnect


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


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


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


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


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


• Command



2 Change the value for Keep Response as follows.


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...


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.


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.


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)


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:


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


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:


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


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:


2 Change the value for Locate Mode as follows.


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


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


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.



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.



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.


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


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


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.


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.


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.


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


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.


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.


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.


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


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.


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


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


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


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


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


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


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...


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


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


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



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


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


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


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


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


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.


Parcel Mode Fetch is used by... To...

applications write


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




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


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.


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


Chapter 3: DBCAREAPositioning-statement-number

One of the following values may be set before calling the Fetch function:


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


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


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


Chapter 3: DBCAREARefresh-cached-data


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


Refresh-cached-data is used by... To...

applications write


Chapter 3: DBCAREARequest Buffer Length


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


Request Buffer Length is used by... To...

applications write


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.


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)


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:


2 Change the value for Request Mode as follows.


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


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‘.


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


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).


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


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:


2 Change Request Processing Option as follows:

The difference between "P" and "S" is that "P" does not support parameterized SQL while "S" does.


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


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


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.


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:


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


Chapter 3: DBCAREAResult-sets-OK


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.


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


Result-sets-OK are used by. . . To...

applications write


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.


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


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)


Chapter 3: DBCAREAReturn-objects-as


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


Return-objects-as is used by... To...

applications write


Chapter 3: DBCAREAReturn-statement-info


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).


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


Return-statement-info is used by... To...

applications write


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.


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


Return-result-to are used by. . . To...

applications write


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'.


Return Time

Return Time is a one byte field that specifies if time stamps are to be generated for the application.


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


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:


2 Change the value for Return Time as follows.


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


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


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.


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.


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


• Command



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


Chapter 3: DBCAREASegment Data


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)


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').


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


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:


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


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.


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


32,725 O

64,493 H



Chapter 3: DBCAREASession Status


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.


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


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.


2 Change the value for Set Character Set to N.


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)


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.


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)


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:


2 Change the value for S2C Conversion as follows:


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)


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



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.


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


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


COBOL DBCAREA-TDPDBO-TIME

PL/I TDPDBO_TIME

C tdpdbo_time





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.


DBCHINI writes

DBCHCL writes (FET)


applications read


COBOL DBCAREA-TDPDBI-TIME

PL/I TDPDBI_TIME

C tdpdbi_time



DBCHINI writes (FET)

DBCHCL writes


applications read




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.


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.


COBOL DBCAREA-TDPXMM-TIME

PL/I TDPXMM_TIME

C tdpxmm_time



DBCHINI writes

DBCHCL writes


applications read



Time5

Time5 is a four byte field that records when the response arrives in the CLIv2 response buffer.


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.


COBOL DBCAREA-SRBSCHED-TIME

PL/I SRBSCHED_TIME

C srbsched_time



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


Chapter 3: DBCAREATime2-status


Time2-status



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.



COBOL DBCOTSS2

PL/I DBCOTSS2

C dbcoTSS2




Time3-status





DBCHCL writes


applications read




Spaceorbinary zero




COBOL DBCOTSS3

PL/I DBCOTSS3

C dbcoTSS3





Time4-status




DBCHCL writes


applications read




Spaceorbinary zero



COBOL DBCOTSS4

PL/I DBCOTSS4

C dbcoTSS4



DBCHCL writes




Time5-status




applications read




Spaceorbinary zero



COBOL DBCOTSS5

PL/I DBCOTSS5

C dbcoTSS5



DBCHCL writes


applications read


Chapter 3: DBCAREATiming-precision


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.




Spaceorbinary zero


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


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


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.


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...


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.


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


Transforms-off is used by... To...

applications write


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.


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


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


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




2 Change the value for Two Response Buffers as follows.


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


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.


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


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.


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.


'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


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




2 Change the value for Use Presence Bits as follows.


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...


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


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


Using Data Length is used by... To...

applications write


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


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


Chapter 3: DBCAREAUsing Data Pointer

number of fields in the Teradata SQL USING row descriptor may be obtained using the DBCHQE SQL-limits query.


In this language... The variable name for Using Data Pointer is...

COBOL DBCAREA-USING-DATA-PTR

PL/I USING_DATA_PTR

C using_data_ptr

IBM Assembler DBRIUDP

This routine... Does this for Using Data Pointer...

DBCHINI writes

DBCHCL reads (IWPF; IRQ)

Using Data Pointer is used by... To...

applications write

When Using Data Pointer has this value... Then the following things are true:

0 No USING row descriptor is to be in the request string

No data string is to accompany the request (thus, neither Using Data Pointer nor Use Presence Bits contain meaningful information)

The length of the nonexistent data string is zero

anything else A USING row descriptor begins the request string

A data string accompanies the request (thus, Using Data Pointer and Use Presence Bits contain meaningful information)

If Variable Length Request is set to this value...

Then the length of the data string (including the bytes containing presence bits, if any) is provided as the...

N value of Using Data Length.

Y two-byte length field preceding the data string


Chapter 3: DBCAREAUsing-data-length-vector


Since DBCHCL does not parse the request string, it is the application‘s responsibility to check whether the request string contains a USING row descriptor and then to set the using-data appropriately.

If 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.


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.


• 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..


Chapter 3: DBCAREAUsing-data-pointer-vector


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


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


Chapter 3: DBCAREAUsing-data-pointer-vector



Since DBCHCL does not parse the request string, it is the application‘s responsibility to check whether the request string contains a USING row descriptor and then to set the using-data appropriately. The maximum number of fields in the Teradata SQL USING row descriptor may be obtained using the DBCHQE SQL-limits query.

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


Using-data-pointer-vector is used by... To...

applications write


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.


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.


• 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


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:


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


Variable Fetch Length is used by... To...

applications write


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


length

Fetch Data Pointer

Fetch Data Pointer


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.


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


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



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.



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


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.


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


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


Chapter 3: DBCAREAWait-exclusion

If a restart occurs during a logoff request, CLIv2 reconnects the session and resubmits the logoff request.


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


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


Chapter 3: DBCAREAWait For Response


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


Wait For Response is used by... To...

applications write


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.


2 Change the value for Wait For Response as follows.


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


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:


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


32,725 O

64,493 H



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


32,725 O


Chapter 3: DBCAREA2PC


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



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


Chapter 3: DBCAREA2PC


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


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.


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


Total Size, 4 bytes

offset

2417A015

0

4

8

Eyecatcher, 4 bytes


Total Length, 2 bytes Unused, 2 bytes



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)



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




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




4

8



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


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



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


Data Length is used by... To...

applications write


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




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


32767 O

65535 H

The variable name for Element Length is...


COBOL D8XILLEN DBXILLEN

PL/I D8XILLEN DBXILLEN

C d8xilLen dbxilLen

IBM Assembler D8XILLEN DBXILLEN

This routine... Does this for Element Length...

DBCHINI n/a


Element Length is used by... To...

applications write



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


Element Type is used by... To...

applications write



Eyecatcher is set to ‘IRX8‘, ‘IRX‘, or ‘DBCX‘ by the application before calling DBCHCL for the Initiate Request function.

Note: Apostrophes are not used in Eyecatcher.

New development should use only the 'IRX8' form. The others are deprecated.

Level

When the Eyecatcher is “‘IRX8‘,” the Level field specifies the format of the extension.

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


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


DBCHINI n/a

DBCHCL reads (CON)



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.


applications write

The variable name for Next Pointer is...



D8XINEXT DBXINEXT

C d8xiNext dbxiNext

This routine... Does this for Next Pointer...

DBCHINI n/a


Next Pointer is used by... To...

applications write



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...


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


Total Length is used by... To...

applications write


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


D8XISIZE DBXISIZE

C d8xiSize dbxiSize

This routine... Does this for Total Size...

DBCHINI n/a


Total Size is used by... To...

applications write



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


Length, 4 bytes

Level, 1 byte Unused, 3 bytes

offset

2417A022

16

20

Unused, 8 bytes



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)



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...


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...


COBOL D8XCEDTY DBXCEDTY

PL/I D8XCEDTY DBXCEDTY

C d8xcedTy dbxcedTy



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...


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...



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...


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...


COBOL D8XCID DBXCID

PL/I D8XCID DBXCID

C d8xcId dbxcId



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...


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...



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...


COBOL D8XCLVL DBXCLVL

PL/I D8XCLVL DBXCLVL

C d8xcLvl dbxcLvl

IBM Assembler D8XCLVL DBXCLVL


DBCHINI n/a

DBCHCL reads (CON)


applications write

The variable name for Next-pointer is...


COBOL D4XCNEXT DBXCNEXT

PL/I D4XCNEXT DBXCNEXT

C d4xcNext dbxcNext

IBM Assembler D4XCNEXT DBXCNEXT



This routine... Does this for Next-pointer...

DBCHINI n/a

DBCHCL reads (CON)

Next-pointer is used by... To...

applications write


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).


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).


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).


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).


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.


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



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.



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)




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


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'.



Table 8: HSHSPB Source Default Settings That Should Never Be Changed


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.


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.


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


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


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


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.


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.


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


DBCHCL(ReturnCode,ContextArea,DBCAREA)



Argument Content



DBCAREA The DBCAREA structure.


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.


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


CRQ Continue Request

CMD Command

ABT Abort

FET Fetch

REW Rewind and Fetch

ERQ End Request

DSC Disconnect


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



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



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


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.


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


Chapter 6: Common RoutinesDBCHCL RSUP Function


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


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


Open Requests TDP Request Number

Table 16: DBCAREA Output Fields Optional for the RunStartup Function (continued)

DBCAREA Output Fields Optional for the RunStartup Function


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.


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


Request Length Request Pointer

Table 20: DBCAREA Input Fields Optional for the Initiate Request Function

DBCAREA Input Fields Optional for the Initiate Request Function


Change Options Character Set

C2S Conversion Column-info

Continued-character-state Data-encryption




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-token Response Buffer Length

Response Mode Result-sets-OK

Return-identity-data Return-result-to

Return-statement-info Return Time


Save Response Buffer Session Id



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


Table 20: DBCAREA Input Fields Optional for the Initiate Request Function (continued)

DBCAREA Input Fields Optional for the Initiate Request Function



Output CLIv2 Request Id Return Code

DBCAREA Output Fields set by Successful Initiate Request Functions

Current Request Buffer Length Open Requests

TDP Request Number

DBCAREA Output Fields always set by the Initiate Request Function


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:


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





Table 22: DBCAREA Input Fields Optional for Initiate With Protocol-function

DBCAREA Input Fields Optional for the Initiate With Protocol-function Function


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-token Response Buffer

Response Mode Result-sets-OK

Return-identity-data Return-result-to

Return-statement-info Return Time


Save Response Buffer Session Id



Transforms-off Trusted-requestf

Two Response Buffers Using Data Length

Using Data Pointer Use Presence Bits



Wait For Response




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


TDP Request Number


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.


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



Chapter 6: Common RoutinesDBCHCL CRQ Function


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


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


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.


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




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


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



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 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




TDP Request Number

Table 32: DBCAREA Output Fields set by Successful Command Functions (continued)

DBCAREA Output Fields set by Successful Command Functions


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).


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.


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


DBCAREA Input Fields Optional for the Abort Function



Chapter 6: Common RoutinesDBCHCL ABT Function

DBCAREA Output Fields always set by the Abort Function

Message Return Code Message Length


Return Code


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


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


Input CLIv2 Request Id

DBCAREA Input Fields Optional for the Fetch Function

Fetch Data Pointer Fetch Maximum Data Length


Positioning-action Positioning-statement-number

Positioning-value


Chapter 6: Common RoutinesDBCHCL FET Function


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


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


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.


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.


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



Table 36: DBCAREA Input Fields Optional for the EndRequest Functions

DBCAREA Input Fields Optional for the EndRequest Functions


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


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


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.


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.


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



DBCAREA Input Fields Optional for the Rewind Function


DBCAREA Output Fields always set by the Rewind Function


Message Length Message Text Length

Return Code


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.


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.


Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the table.

DBCAREA Input Fields Required for the Disconnect Function


DBCAREA Input Fields Optional for the Disconnect Function


DBCAREA Output Fields always set by the Disconnect Function

Message Return Code Message Lenth

Message Text Message Text Lenth


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


DBCHCLN(ReturnCode,ContextArea)



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.


Argument Content




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.


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


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


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


Chapter 7: Other CLIv2 RoutinesDBCHME

DBCHME

Purpose

Called by the application to establish a master event in place of individual session events.

Interface


DBCHME(ReturnCode,ContextArea,MasterECB,FunctionCode)



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.


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



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.


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.


Chapter 7: Other CLIv2 RoutinesDBCHMEC

DBCHMEC

Purpose

A deprecated routine now replaced by DBCHME.

Interface


DBCHMEC(ReturnCode,ContextArea,MasterECB)



Argument Content



MasterECB The area allocated by the application for use as the master ECB.


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


DBCHPEC(ReturnCode,ECB)



Usage Notes

• After control returns from DBCHPEC, the variable contains a code whose value represents success or failure. A return code of zero indicates success, a nonzero return code indicates failure, and the value specifies the reason for the failure.


• For more information on ECBs, see IBM manuals.

Argument Content


ECB The application allocated area for use as the ECB.


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


DBCHSAD(ReturnCode,Target,Source)



Usage Notes

DBCHSAD is intended for use in COBOL and other languages that do not support pointer manipulation.

Argument Content


Target The area where the source address will be stored.

Source Address to be stored.


Chapter 7: Other CLIv2 RoutinesDBCHUE

DBCHUE

Purpose

Called by the application to add a user-provided event to CLIv2‘s internal wait list.

Interface


DBCHUE(ReturnCode,ContextArea,User event,DBCHUEP)



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



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)


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:


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.


Chapter 7: Other CLIv2 RoutinesDBCHUEC

DBCHUEC

Purpose

A deprecated routine now replaced by DBCHUE.

Interface


DBCHUEC(ReturnCode,ContextArea,UserECB)



Usage Notes

The user ECB may be cancelled by specifying a User ECB address of binary zeroes.

Argument Content



UserECB The application allocated area for use as the User ECB.

For CICS applications, the User ECB must be in SHARED storage.


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


DBCHWAT(ReturnCode,ContextArea,ConnectionNumber,Request-token)



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



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.


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.



• Requests for sessions that specify the Wait-exclusion option are ignored by DBCHWAT.


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


DBCHWL(ReturnCode,ContextArea,SessionList,ConnectionNumber, Request-token)



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



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.



• 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.


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


DBCHQE(ReturnCode,ContextArea,DBCHQEP,...)



Argument Content




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


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.



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.




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:


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.




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:


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.




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)


QEPMCSP8

(qepMCSP8)


QEPMSGP8

(qepMsgP8)


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


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



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)




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.





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.



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.



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.


Returns the type of SQL standard supported by the Teradata Database.


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.


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)


‘N‘ with mnemonic QERLCSN(QER_NotSupported for C)

‘Y‘ with mnemonic QERLCSY(QER_Supported for C)



Referential-integrity-support

Referential-integrity-support might be used to ascertain whether the Teradata Database supports Referential Integrity.


Returns whether referential integrity is supported by the Teradata Database.


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.


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)


‘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)


‘N‘ with mnemonic QERRFIN(QER_NotSupported for C)

‘Y‘ with mnemonic QERRFIY(QER_Supported for C)



Extended-parcel-size-support

Extended-parcel-size-support might be used to ascertain whether a response buffer larger than 32767 bytes will be used.


Returns whether parcels greater than 32767 bytes are supported by the Teradata Database.


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)


‘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)


‘N‘ with mnemonic QEREPS(QER_NotSupported for C)

‘Y‘ with mnemonic QEREPSY(QER_Supported for C)



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



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.


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.



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.


Returns whether the UPSERT SQL statement is supported by the Teradata Database.


Item Code Mnemonic

Response DBQERSSO (DbqerSSo for C)

Field Value

13 QEPISSO QERSSO ('status' for C)


‘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.



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.


Returns whether the array operations is supported by the Teradata Database.


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.


Returns whether the MERGE-INTO SQL statement for single-rows is supported by the Teradata Database.


Item Code Mnemonic

Response DBQERUPS (DbqerUps for C)

Field Value

15 QEPIUPS QERUPS ('status' for C)


‘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)


‘N‘ with mnemonic QERAOPN(QER_NotSupported for C)

‘Y‘ with mnemonic QERAOPY(QER_Supported for C)



Large-object-support

Large-object-support might be used to ascertain whether the Teradata Database supports large objects (BLOBs or CLOBs).

Refers to the TDP whose TDP identifier is addressed by the QEPTDP field and has length specified by the QEPTLEN field.

Returns whether Large Objects are supported by the Teradata Database.

This item is also included in the Aggregate-support-list query item

Timing-precision-range

Timing-precision-range is used to obtain the minimum and maximum values acceptable for the DBCAREA Timestamp-precision option.


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)


‘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)


‘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.



Extended-response-support

Extended-response-support might be used to ascertain whether a response buffer larger than 65535 bytes will be used.


Returns whether response buffers greater than 65535 bytes are supported by the Teradata Database.


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.


Returns whether parcels greater than 65535 bytes are supported by the Teradata Database.


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)


‘N‘ with mnemonic QERERSN(QER_NotSupported for C)

‘Y‘ with mnemonic QERERSY(QER_Supported for C)



Timestamp-types-support

Timestamp-types-support might be used to ascertain whether the Teradata Database will implicitly convert Timestamp data to Date data.


Returns whether distinct datatypes for timestamps are supported by the Teradata Database.


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)


‘N‘ with mnemonic QERTMTN(QER_NotSupported for C)

‘Y‘ with mnemonic QERTMTY(QER_Supported for C)



Utility-data

Utility-data is used by proprietary utilities and is not intended for other applications. It is described here simply for completeness.


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.


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)


‘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)


"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)


'0' with mnemonic QERUDEUS (QER_UtilData_ExportSpool for C, SPOOL for COBOL, QER_UTILDATA_EXPORT_SPOOL for PL/I)

'1' with mnemonic QERUDEUN (QER_UtilData_ExportNoSpool for C, NO-SPOOL for COBOL, QER_UTILDATA_EXPORT_NO_SPOOL for PL/I)



aggregate 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


‘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


‘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


‘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


‘N‘ with mnemonic QERRFIN(QER_NotSupported for C) (QERASLRIN for COBOL)

‘Y‘ with mnemonic QERRFIY(QER_Supported for C) (QERASLRIY for COBOL)



QERASLEP (extendedParcelStatus for C)is Extended-parcel- size-support


‘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


‘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


‘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


‘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.


‘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


Field Value



QERASLLO (lobStatus for C)is Large-object-support

‘N‘ with mnemonic QERLOBN(QER_NotSupported for C)(QERASLLON for COBOL)

‘Y‘ with mnemonic QERLOBY(QER_Supported for C)(QERASLLOY for COBOL)

QERASLER (extendedResponseStatus for C)is Extended-response-support

‘N‘ with mnemonic QERERSN(QER_NotSupported for C)(QERASLERN for COBOL)

‘Y‘ with mnemonic QERERSY(QER_Supported for C)(QERASLERY for COBOL)

QERASLTT (timingTypesStatus for C)is Timestamp-types-support


‘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


‘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


‘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


Field Value



QERASLES (statementStatusStatus for C)is Enhanced-statement-status-support

‘N‘ with mnemonic QERESSN(QER_NotSupported for C)(QERASLESN for COBOL)

‘Y‘ with mnemonic QERESSY(QER_Supported for C)(QERASLESY for COBOL)

QERASLUT (userTypesStatus for C)is User-defined-types-support


‘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


'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


'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


Field Value



QERASLID (integerDecimalStatus for C,INTEGE-DECIMAL-STATUS for COBOL,INTEGER-DECIMAL_STATUSfor PL/I)is Statement-info-support


'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


'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


'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


Field Value



QERASLCC (columnCorrStatus for C, COLUMN-CORR-STATUS for COBOL, COLUMN_CORR_STATUS for PL/I) is Column-correlation-status


'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


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


Field Value



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.


Returns whether response positioning is supported by the Teradata Database.


QERASLTO(transformsOffUsage for C, TRANSFORMS-OFF-USAGE for COBOL, TRANSFORMS_OFF_USAGE for PL/I) is Transforms-off-usage


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


Field Value

Item Code Mnemonic

Response DBQERRPO (DbqerRPo for C)

Field Value

25 QEPIRPO QERRPO('status' for C)


‘N‘ with mnemonic QERRPON(QER_NotSupported for C)

‘Y‘ with mnemonic QERRPOY(QER_Supported for C)



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.


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)


‘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.



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.



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.


Returns whether Enhanced-statement-status is supported by the Teradata Database.


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.


Returns whether User-defined-types is supported by the Teradata Database.


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)


‘N‘ with mnemonic QERUDTN(QER_NotSupported for C)

‘Y‘ with mnemonic QERUDTY(QER_Supported for C)



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.


Item Code Mnemonic

Response DBQERAPH (DbqerAPH for C)

Field Value

31 QEPIAPH QERAPH(responseUsage for C)


‘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.



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.


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



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.


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.



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.


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.



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.


QERSQLKT ('tableColumns' for C, TABLE-COLUMNS for COBOL, TABLE_COLUMNS for PL/I) is the maximum number of columns in a table.


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.


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.




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.


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.


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.


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.


QERSQLKL ('columnLen' for C, COLUMN-LEN for COBOL, COLUMN_LEN for PL/I) is the maximum number of bytes for a column.


Item Code Mnemonic


Fields Value



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.


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.


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.


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.


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.


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.


Item Code Mnemonic


Fields Value



QERSQLPD ('decimalPrecision' for C, DECIMAL-PRECISION for COBOL, DECIMAL_PRECISION for PL/I) is the maximum precision (number of digits) in a column of data type DECIMAL or NUMERIC.


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].


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].


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.


QERSQLUN ('usingValues' for C, USING-VALUES for COBOL, USING_VALUES for PL/I) is the maximum number Teradata SQL USING row descriptor fields.


Item Code Mnemonic


Fields Value



Relaxed-call-args

The Relaxed-call-args might be used to simplify construction of SQL CALL statements.


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.


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.


QERSQLPP ('procedureParms' for C, PROCEDURE-PARMS for COBOL, PROCEDURE_PARMS for PL/I) is the maximum number of parameters to a stored procedure.


Item Code Mnemonic


Fields Value

Item Code Mnemonic

Response DBQERRCA (DbqerRCA for C)

Field Value

37 QEPIRCA QERRCA('status' for C and PL/I)


'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)



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.


Returns whether StatementInformation parcels are supported.


Integer/decimal-enlargement

Integer/decimal-enlargement might be used to ascertain wheter the DBCAREA Max-decimal-returned option is supported by Teradata Database.


Returns whether the maximum size of the decimal data type in responses may be specified.


Item Code Mnemonic

DBQERSIS (DbqerSIS for C)

Field Value

38 QEPISIS QERSIS('status' for C and PL/I)


'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)


'N' with mnemonic QERIDEN (QER_NotSupported for C, NOT-SUPPORTED for COBOL,QER_NOT_SUPPORTED) for PL/I)



Return-Identity-Data-support

Return-Identity-Data-support might be used to ascertain whether the DBCAREA Return-identity-data option may be specified to request data be returned in response to an SQL Insert operation when Identity columns are involved.


Returns whether returning data for SQL Inserts when Identity columns are involved.


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.


Returns whether stored procedures may return the results of their SQL statements to the application.


'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)


'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)



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.


Returns whether Teradata Database supports the SQL SET QUERY_BAND statement.


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: '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)


'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)



Merge-into-usage

Merge-into-usage might be used to ascertain the degree to which the Database supports the SQL MERGE INTO statement.


Returns the degree of support for the SQL MERGE INTO statement.


Logging-errors-usage

Logging-errors-usage might be used to ascertain the degree to which the Database supports the Teradata SQL LOGGING ERRORS clause.


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)


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.




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)


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)


'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.



Session-character-set

Session-character-set obtains the name of a character set that is not explicitly specified.


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.


'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)


'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)



Utility-session

Utility-session is used internally only by Teradata utilities, and is not intended for other applications.


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.


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.



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)



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).


Returns the degree of support for referencing the constituent attributes of SQL Structured User Defined Types (UDTs).


Transforms-request-support

There is no known use for the Trusted-request-support query.


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)


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.



Item Code Mnemonic

Response DBQERTRS (DbqerTRS for C)

Field Value

53 QEPITRS QERTRS ('usage' for C and PL/I)


'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)


CHAPTER 9

Response Sequences


• 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.


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


• 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.


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.


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)


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)



FormatEnd parcel (flavor 23)

SizeStart parcel (flavor 24)


Size parcel (flavor 26)

SizeEnd parcel (flavor 25)

The following parcels are repeated activity-count number of times:

RecStart parcel (flavor 27)



RecEnd parcel (flavor 28)



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.








Table 42: Response Parcel Sequence in Field Mode (continued)










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)













EndWith parcel (flavor 35)

The following parcels are repeated activity-count number of times










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.









an ECHO request OK parcel (flavor 17) or ResultSummary (flavor 171)









Table 43: Response parcel sequence in Record Mode



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.





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:


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)




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 parcels are repeated for each summary row:






an ECHO request Success parcel (flavor 8) or ResultSummary (flavor 171)




Table 43: Response parcel sequence in Record Mode (continued)



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.







DataInfoX parcel (flavor 146) or StatementInformation (flavor 169) and StatementInformationEnd (flavor 170)


One or more MultipartRecord parcels (flavor 144)

EndMultipartRecord parcel (flavor 145)




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 parcels are repeated activity-count number of times:









Table 44: Response Sequence in MultipartIndicator Mode (continued)




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:


an ECHO request Success parcel (flavor 8) or ResultSummary (flavor 171).





Table 44: Response Sequence in MultipartIndicator Mode (continued)


Table 45: Response Parcel Sequence Indicator Mode



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.





DataInfo parcel (flavor 71) or StatementInformation (flavor 169) and StatementInformationEnd (flavor 170)






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.





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.














an ECHO request Success parcel (flavor 8) or ResultSummary (flavor 171)




Table 45: Response Parcel Sequence Indicator Mode (continued)



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.



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)


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



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



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)


Parcel Flavor Body



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



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


Parcel Flavor Body



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


Parcel Flavor Body

Name Flavor

Failure 9

Error 49

Success 8

ResultSummary 171

Record 10

With 33




EndWith 35

EndStatement 11

EndRequest 12


Parcel Flavor Body

Success 8 (1, 23, 0, 0, 3, 0)

EndStatement 11 (1)

EndRequest 12


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



Record (1)

.

.

.

Record (23)

10

.

.

.

10

(data)

.

.

.

(data)

With 33 (1)

Record 10 (data)

EndWith 35 (1)

EndStatement 11 (1)

EndRequest 12


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


Parcel Flavor Body



Issuing Requests—MultipartIndicator Mode

MultipartIndicator Mode requests may return the following parcels:



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



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)


EndMultipartRecord 145 (ind, data)

EndStatement 11 (1)

EndRequest 12


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)





MultipartRecord (s)for row 23 144 (ind, data)


With 33 (1)

MultipartRecord(s) 144 (ind,data)


EndWith 35 (1)

EndStatement 11 (1)

EndRequest 12


Parcel Flavor Body

Success 8 (1, 23, 0, 1, 1, 0)

DataInfoX 146 (1, 496, 4)





EndStatement 11 (1)

Success 8 (2, 10, 0, 1, 1, 0)

DataInfoX 71 (2, 496, 4)





EndStatement 11 (2)

EndRequest 12


Parcel Flavor Body



Issuing Requests—Indicator Mode

Indicator Mode requests may return the following parcels:



Parcel Flavor Body

Success 8 (1, 0, 0, 1, 33, 0)

MultipartRecord(s) 144 (ind, data)


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



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.


Parcel Flavor Body

Success 8 (1, 23, 0, 0, 3, 0)

EndStatement 11 (1)

EndRequest 12


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


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)



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


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)


Parcel Flavor Body


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


Parcel Flavor Body

Success 8 (1, 0, 0, 1, 33, 0)

Record 10 (echoed string)

EndStatement 11 (1)

EndRequest 12


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.


Chapter 9: Response SequencesParcels That Indicate Problems


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


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.


Failure Code 3598 concurrent change conflict on data base - try again.


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


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.


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.


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



• 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 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)


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.)


Wait During Delay Y

Tell If Delay N



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 delay occurs before or after receiving information from DBCHCL

• CLIv2 returns control to the application, with a return code of 286


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.


Wait During Delay N

Tell If Delay Y


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


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


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


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


Reserved codepoints



characters Single Shift Two and Single Shift Three imply nothing about subsequent codepoints.

EBCDIC273_0E



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







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


Reserved codepoints



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.


EBCDIC277_0E








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


Reserved codepoints


Chapter 12: Character Set CodepointsHANGULEBCDIC933_1II


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.


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


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



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


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



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





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'


codepoint





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'


codepoint




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'.


BB OE400000 Hangul 'EUI'

U+FFDB Halfwidth Hangul Letter 'YI'

BC OI000000 Hangul 'I'

U+FFDC Halfwidth Hangul Letter 'I'


codepoint






Table 53: Single-byte Teradata KANJIEBCDIC5026_0I Codepage


0x NUL SOH STX ETX HT VT FF CR SO SI

1x BS CAN EM IS4 IS3 IS2 IS1


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



Ex $ S T U V W X Y Z

Fx 0 1 2 3 4 5 6 7 8 9


Reserved codepoints.

Katakana codepoints. Refer to Table 54 on page 386 for details.

Table 54: Kanji Codepoint Assignments for KANJIEBCDIC5026_0I

codepoint



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'

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





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'


codepoint





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'


codepoint





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'


codepoint





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.


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


codepoint





between the Shift-out and Shift-in control characters is always between X'41' and X'FE'. Currently, the second byte is also between X'41' and X'FE'. The X'4040' codepoint is defined as the Double-byte Space character. No double-byte control characters exist. The double-byte characters are not described.


Table 55: Single-byte Teradata KANJIEBCDIC5035_0I Codepage


0x NUL SOH STX ETX HT VT FF CR SO SI

1x BS CAN EM IS4 IS3 IS2 IS1


3x SYN EOT NAK

4x SP ¢ . < ( + |

5x & ! $ * ) ; ¬

6x - / , % _ > ?

7x ` : # @ ' = "

8x a b c d e f g h i


Ax ¯ ~ s t u v w x y z [

Bx ^ £ ¥ ]




Fx 0 1 2 3 4 5 6 7 8 9


Reserved codepoints




Table 56: Kanji Codepoint Assignments for KANJIEBCDIC5035_0I

codepoint




































U+FF70 Halfwidth Katakana-Hiragana prolonged sound mark



















70 JK500000 'Katakana 'KO'


71 JS100000 Katakana 'SA'


72 JS200000 Katakana 'SI'/'SHI'



codepoint





73 JS300000 Katakana 'SU'


74 JS400000 Katakana 'SE'






77 JT200000 Katakana 'TI'/'CHI'


78 JT300000 Katakana 'TU'/'TSU'


8A JT400000 Katakana 'TE'


8B JT500000 Katakana 'TO'


8C JN100000 Katakana 'NA'


8D JN200000 Katakana 'NI'


8E JN300000 Katakana 'NU'


8F JN400000 Katakana 'NE'




9B JH100000 Katakana 'MH'

U+FF8A Halfwidth Katakana Letter 'MH'


codepoint





9C JH200000 Katakana 'HI'


9D JH300000 Katakana 'HU'/'FU'


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'


codepoint




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.


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'


BA JR500000 Katakana 'RO'


BB JW100000 Katakana 'WA'


BC JN000000 Katakana 'N'







codepoint





character until the Shift-in control character is encountered. The first byte of codepoints between the Shift-out and Shift-in control characters is always between X'41' and X'FE'. Currently, the second byte is also between X'41' and X'FE'. The X'4040' codepoint is defined as the Double-byte Space character. No double-byte control characters exist. The double-byte characters are not described.


Table 57: Single-byte Teradata KATAKANAEBCDIC Codepage


0x NUL SOH STX ETX HT y VT FF CR SO SI

1x ¢ ¬ / a BS b CAN EM IS4 IS3 IS2 IS1


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



Fx 0 1 2 3 4 5 6 7 8 9


Reserved codepoints




Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC

codepoint




































U+FF70 Halfwidth Katakana-Hiragana prolonged sound mark



















8A JK500000 Katakana 'KO'


8C JS100000 Katakana 'SA'


8D JS200000 Katakana 'SI'/'SHI'


Table 58: Katakana Codepoint Assignments for KATAKANAEBCDIC (continued)

codepoint





8E JS300000 Katakana 'SU'


8F JS400000 Katakana 'SE'






92 JT200000 Katakana 'TI'/'CHI'


93 JT300000 Katakana 'TU'/'TSU'


94 JT400000 Katakana 'TE'


95 JT500000 Katakana 'TO'


96 JN100000 Katakana 'NA'


97 JN200000 Katakana 'NI'


98 JN300000 Katakana 'NU'


99 JN400000 Katakana 'NE'




9D JH100000 Katakana 'HA'

U+FF8A Halfwidth Katakana Letter 'HA'


codepoint





9E JH200000 Katakana 'HI'


9F JH300000 Katakana 'HU'/'FU'


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'


codepoint




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.


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'


BB JR500000 Katakana 'RO'


BC JW100000 Katakana 'WA'


BD JN000000 Katakana 'N'







codepoint




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'



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



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


4x SP £ . < ( + |

5x & ! ¥ * ) ; ¬

6x - / ¦ , % _ > ?

7x ` : # @ ' = "



Ax ~ ¯ s t u v w x y z

Bx ^ \ [ ]




Fx 0 1 2 3 4 5 6 7 8 9 APC


Reserved codepoints


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'



Chapter 12: Character Set CodepointsTCHEBCDIC937_3IB


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



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


4x SP ¢ . < ( + |

5x & ! $ * ) ; ¬

6x - / ¦ , % _ > ?

7x ¡ ` : # @ ' = "



Ax ~ s t u v w x y z

Bx ^ [ ]




Fx 0 1 2 3 4 5 6 7 8 9 APC


Reserved codepoints


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.


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



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'


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'


Single-shift1 (X'8E')

• Triple-byte (ASCII) codepoints:

Single-shift2 (X'8F)'



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'


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'


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'


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



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



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


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:


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


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.


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)



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


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


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)




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.



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)




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.




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



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




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



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)




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




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



• 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



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



• 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



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



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.


150 4 Token: 4 byte


152 0 None



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.



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



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.


145 0 None


12 0 none



EndStatement

Purpose

Delimits the end of the results of a Teradata SQL statement.

Usage Notes


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


Parcel Data

The following table lists field information for EndWith.

Field Notes

WithId is the summary number (1-n) for this End With clause.


11 2 StatementNo: 2 byte unsigned integer


35 2 WithId: 2 byte unsigned integer



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.


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.


49 8 to 263 StatementNo:

Info:

Code:

Length:

Msg:

2 byte unsigned integer




1 to 255 bytes



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.


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.



Info:

Code:

Length:

Msg:





1 to 255 bytes



Parcel Data


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.


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...


RecStart a data value of a column or it contains a string echoed from the Teradata server

TitleStart the title of one column.

FormatStart the format of one column.



Field Notes

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


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.



Location:

Reason:

MsgLength:

Message:

2 bytes

2 bytes

2 bytes

to maximum body size


23 0 none



Usage Notes


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).


Parcel Data

The following information applies to the MultipartRecord parcel (in Indicator Mode).


22 0 none



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.



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.



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


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.


19 0 none



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.



FieldCount:

ActivityCount:

ActivityType:

WarningCode:

WarningLength:

WarningMsg:







0 to 255 bytes



Usage Notes


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.


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



47 0 none


34 2 ColumnNo: 2 byte unsigned integer



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.


46 0 none



CostEstimate:

SummaryCount:

8 byte floating


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:



two byte unsigned integer plus the number of bytes specified by that integer





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.



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



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.



CostEstimate:

SummaryCount:

8 byte floating


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:


8 bytes

2 bytes




For non-decimal columns, the following occur:

DataType:

DataLen:

CharacterType:

ColumnInformation

ColumnName:

ColumnFormat:

ColumnTitle:


8 bytes


8 bits

2 to 92 bytes of characters





• 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



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



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


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


28 0 none

In this mode... Nulls are...

Record not explicitly identified in the Record parcel.



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).


Parcel Data

The following information applies to the Record parcel (in Indicator Mode).

Indicator explicitly identified.

In this mode... Nulls are...



Field Notes


• 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.



• The Data Field contains items with characteristics as follows:

• The order of the items.



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


ON null.

OFF not null.


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.



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).


Parcel Data

The following information applies to the Record parcel (in Record Mode).



Data: organized as:

item 1, item2, . . . , item i, . . . , item n



If in Record Mode, the Record parcel for an ECHO statement does NOT contain zeros.

Field Notes


• The 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




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).


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.



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


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


171 24 to maximum parcel size

Activity Count:

Statement No:

Field Count:

Activity Type:




2 byte unsigned integer See “Activity Type” on page 425 for the possible activity types



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).


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)




Size

Purpose

Specifies the size of a returned field.

Usage Notes


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.


26 2 MaxFldSize: 2 byte unsigned integer


25 0 none



Usage Notes


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


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:


24 0 none



Self-defining extensions: Six or more bytes



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


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.



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


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.



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)




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.





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.


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.





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




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.



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


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


PBTISEE 8 byte unsigned integer

The estimated execution time for the statement, in milliseconds.



Usage Notes


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.


Parcel Data

The following information applies to the Success parcel.

Field Notes

The following notes apply to Success fields.


170 0 none



ActivityCount:

WarningCode:

FieldCount:

ActivityType:

WarningLength:

WarningMsg:

byte unsigned integer






0 to 255 bytes



• 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


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


Parcel Data

The following information applies to the TitleStart parcel.


21 0 none



With

Purpose

Delimits the start of a sequence of parcels that provides descriptors for the results of a summary generated by a WITH clause.

Usage Notes

The WithId specifies the parcels that apply to the WITH clause.


Parcel Data

The following information applies to the With parcel.

Field Notes

WithId is the summary number (1-n) for this WITH clause.


20 0 none


33 2 WithID: 2 byte unsigned integer


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


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)


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)


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


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


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


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


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


121 CursorDBC Returns cursor information


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



• CursorDBC • CursorHost

• Data • DataInfo

• DataInfoX • EndMultipartData

• EndMultipartIndicData • FMReq

• IndicData • IndicReq

• MultipartData • MultipartIndicData

• MultipartRequest • Options

• Req • SP Options

• StatementInformation Requests • StatementInformationEnd Returns



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



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


Data: 1 to maximum body size bytes



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.



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



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.



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



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.


141 0 none


143 0 none



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


Parcel Data

The following information applies to the IndicData parcel.



ReqText

Flavor Parcel Body Length Parcel Body Fields


NullIndicators: (n+7)/8 bytes where n = the number of items in the Data Field,

organized as: bit 1, bit 2, . . . , bit i,. . . , bit n, unused bits

Data: 1 to maximum body size - ((n+7) / 8) bytes

organized as: item 1, item2, . . . , item i,..., item n



Field Notes

The following notes apply to IndicData fields.

The NullIndicators Field contains one bit for each item in the Data Field, stored in the minimum number of 8-bit bytes required to hold them, with the unused bits in the rightmost byte set to zero.

Each bit is matched on a positional basis to an item in the Data Field (that is, the ith bit in the NullIndicators Field corresponds to the ith item in the Data Field).


For example,


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.



ON null.

OFF not null.


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).



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.



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.


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.



ReqText



Data: 1 to maximum body size



• 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.


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


Data: 1 to maximum body size bytes



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.



ReqText



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



• 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.



• 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.



• '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.



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.



ReqText



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:


129 2 Print: 1 byte (unused)SaveSPL: 1 byte



Self-defining extensions: Six or more bytes




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).



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


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.


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.



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


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


PBTILND 2 byte unsigned integer


PBTILNID 2 byte unsigned integer


PBTILNFD 2 byte unsigned integer





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


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


PBTIUND 2 byte unsigned integer


PBTIUNID 2 byte unsigned integer


PBTIUNFD 2 byte unsigned integer


Table 81: Untransformed imited-layout Fields for Requests


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.



StatementInformationEnd Returns

Purpose

Indicates that no more StatementInformation parcels (flavor 169) exist.

Parcel Data

The following information applies to the StatementInformationEnd parcel.


170 0 none


CHAPTER 17

Stored Procedures


• 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:


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.


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...


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


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.


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.


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.


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


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


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:



1 to 30 bytes

Flavor Field

Length Field Parcel Body Fields

10 7 to 36 StringLength:

CoordinatorID:

2 bytes

1 to 30 bytes


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


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


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.


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.


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).


Chapter 19: 2PC ProtocolCLIv2 Application Requirements for 2PC


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.


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



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



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



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



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 ;


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.


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.


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


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


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.


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.


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


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


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


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


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


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


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


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


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


Index

Wait For Responsefield 164, 203

DBCHME 276option 47


Teradata Call-Level Interface Version 2...This book provides information about Teradata® Call-Level...

Documents

Transcript of Teradata Call-Level Interface Version 2...This book provides information about Teradata® Call-Level...